urbanLifeline/.kiro/specs/urbanlifeline-to-pigx-migration/permission-conversion-guide.md

# 权限注解转换指南

## 目标

将 urbanLifeline 的权限体系完全迁移到 pigx 平台的权限模型。

## 核心概念对比

| 特性 | urbanLifeline | pigx |
|------|---------------|------|
| 权限注解 | `@PreAuthorize("hasAuthority()")` | `@PreAuthorize("@pms.hasPermission()")` |
| 权限格式 | `module:resource:action` | `module_resource_action` |
| 用户获取 | `JwtUtils.getUserId()` | `SecurityUtils.getUser()` |
| 用户服务 | `UserService` (本地) | `RemoteUserService` (Feign) |
| 响应格式 | `ResultDomain<T>` | `R<T>` |
| 租户支持 | 无 | 有 (tenant_id) |

## 转换步骤详解

### 步骤 1：权限注解转换

#### 1.1 基本转换规则

```java
// ❌ 旧代码 (urbanLifeline)
@PreAuthorize("hasAuthority('workcase:ticket:create')")
public ResultDomain<TbWorkcaseDTO> createWorkcase(@RequestBody TbWorkcaseDTO dto) {
    // ...
}

// ✅ 新代码 (pigx)
@PreAuthorize("@pms.hasPermission('workcase_ticket_add')")
public R<TbWorkcaseDTO> createWorkcase(@RequestBody TbWorkcaseDTO dto) {
    // ...
}
```

#### 1.2 多权限组合

```java
// ❌ 旧代码 - OR 条件
@PreAuthorize("hasAuthority('workcase:ticket:update') or hasAuthority('workcase:ticket:admin')")

// ✅ 新代码 - OR 条件
@PreAuthorize("@pms.hasPermission('workcase_ticket_edit') or @pms.hasPermission('workcase_ticket_admin')")

// ❌ 旧代码 - AND 条件
@PreAuthorize("hasAuthority('workcase:ticket:view') and hasAuthority('workcase:export:data')")

// ✅ 新代码 - AND 条件
@PreAuthorize("@pms.hasPermission('workcase_ticket_view') and @pms.hasPermission('workcase_export_data')")
```

#### 1.3 动态权限检查

```java
// ❌ 旧代码
@Service
public class WorkcaseService {
    public boolean canEdit(Long workcaseId) {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        return auth.getAuthorities().stream()
            .anyMatch(a -> a.getAuthority().equals("workcase:ticket:update"));
    }
}

// ✅ 新代码
@Service
public class WorkcaseService {
    @Autowired
    private PermissionService permissionService;

    public boolean canEdit(Long workcaseId) {
        return permissionService.hasPermission("workcase_ticket_edit");
    }
}
```

### 步骤 2：用户信息获取转换

#### 2.1 获取当前用户

```java
// ❌ 旧代码
Long userId = JwtUtils.getUserId();
String username = JwtUtils.getUsername();
String role = JwtUtils.getRole();

// ✅ 新代码
PigxUser user = SecurityUtils.getUser();
Long userId = user.getId();
String username = user.getUsername();
Long tenantId = user.getTenantId();  // 新增：租户ID
Long deptId = user.getDeptId();      // 新增：部门ID
List<String> roles = user.getRoles(); // 角色列表
```

#### 2.2 Service 层用户信息处理

```java
// ❌ 旧代码
@Service
public class WorkcaseServiceImpl implements WorkcaseService {
    @Autowired
    private UserService userService;

    public void assignWorkcase(Long workcaseId, Long assigneeId) {
        User assignee = userService.getById(assigneeId);
        // 处理逻辑...
    }
}

// ✅ 新代码
@Service
public class WorkcaseServiceImpl implements WorkcaseService {
    @Autowired
    private RemoteUserService remoteUserService;

    public void assignWorkcase(Long workcaseId, Long assigneeId) {
        // 使用 Feign 远程调用
        R<SysUser> result = remoteUserService.selectById(assigneeId);
        if (result.isSuccess() && result.getData() != null) {
            SysUser assignee = result.getData();
            // 处理逻辑...
        } else {
            throw new BusinessException("用户不存在");
        }
    }
}
```

### 步骤 3：响应格式转换

#### 3.1 成功响应

```java
// ❌ 旧代码
return ResultDomain.success(data);
return ResultDomain.success(list, total);
return ResultDomain.success("操作成功", data);

// ✅ 新代码
return R.ok(data);
return R.ok(list, total);  // 分页响应
return R.ok(data, "操作成功");
```

#### 3.2 错误响应

```java
// ❌ 旧代码
return ResultDomain.failure("参数错误");
return ResultDomain.failure(ErrorCode.INVALID_PARAM);
throw new BusinessException("业务异常");

// ✅ 新代码
return R.failed("参数错误");
return R.failed(CommonConstants.FAIL, "参数错误");
throw new ServiceException("业务异常");
```

#### 3.3 分页响应

```java
// ❌ 旧代码
public ResultDomain<List<TbWorkcaseDTO>> list(PageParam param) {
    Page<TbWorkcase> page = workcaseMapper.selectPage(param);
    return ResultDomain.success(page.getRecords(), page.getTotal());
}

// ✅ 新代码
public R<IPage<TbWorkcaseDTO>> list(Page page, TbWorkcaseDTO query) {
    IPage<TbWorkcaseDTO> result = workcaseMapper.selectPageVo(page, query);
    return R.ok(result);
}
```

### 步骤 4：租户隔离实现

#### 4.1 实体类添加租户字段

```java
@Data
@TableName("tb_workcase")
public class TbWorkcase {
    @TableId
    private Long id;

    private String title;

    // ✅ 新增租户字段
    @TableField("tenant_id")
    private Long tenantId;

    // 其他字段...
}
```

#### 4.2 Service 层自动注入租户

```java
@Service
public class WorkcaseServiceImpl implements WorkcaseService {

    @Override
    public R<TbWorkcaseDTO> save(TbWorkcaseDTO dto) {
        // ✅ 自动注入当前租户
        PigxUser user = SecurityUtils.getUser();
        dto.setTenantId(user.getTenantId());
        dto.setCreateBy(user.getUsername());
        dto.setCreateTime(LocalDateTime.now());

        workcaseMapper.insert(dto);
        return R.ok(dto);
    }

    @Override
    public R<IPage<TbWorkcaseDTO>> page(Page page, TbWorkcaseDTO query) {
        // ✅ 查询条件自动添加租户过滤
        PigxUser user = SecurityUtils.getUser();
        query.setTenantId(user.getTenantId());

        return R.ok(workcaseMapper.selectPageVo(page, query));
    }
}
```

#### 4.3 Mapper 层租户隔离

```xml
<!-- WorkcaseMapper.xml -->
<select id="selectPageVo" resultType="com.pig4cloud.pigx.app.api.dto.TbWorkcaseDTO">
    SELECT * FROM tb_workcase
    <where>
        <!-- ✅ 租户隔离条件 -->
        <if test="query.tenantId != null">
            AND tenant_id = #{query.tenantId}
        </if>
        <if test="query.title != null and query.title != ''">
            AND title LIKE CONCAT('%', #{query.title}, '%')
        </if>
    </where>
    ORDER BY create_time DESC
</select>
```

### 步骤 5：配置 RemoteUserService

#### 5.1 添加 Feign 客户端接口

```java
package com.pig4cloud.pigx.app.api.feign;

import com.pig4cloud.pigx.common.core.constant.ServiceNameConstants;
import com.pig4cloud.pigx.common.core.util.R;
import com.pig4cloud.pigx.upms.api.entity.SysUser;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.*;

@FeignClient(contextId = "remoteUserService",
            value = ServiceNameConstants.UPMS_SERVICE)
public interface RemoteUserService {

    /**
     * 根据用户ID查询用户信息
     */
    @GetMapping("/user/info/{id}")
    R<SysUser> selectById(@PathVariable("id") Long id);

    /**
     * 根据用户名查询用户信息
     */
    @GetMapping("/user/info")
    R<SysUser> selectByUsername(@RequestParam("username") String username);

    /**
     * 批量查询用户信息
     */
    @PostMapping("/user/list")
    R<List<SysUser>> selectBatchIds(@RequestBody List<Long> ids);
}
```

#### 5.2 使用 RemoteUserService

```java
@Service
@RequiredArgsConstructor
public class WorkcaseServiceImpl implements WorkcaseService {

    private final RemoteUserService remoteUserService;

    public TbWorkcaseDTO getWorkcaseDetail(Long id) {
        TbWorkcase workcase = workcaseMapper.selectById(id);
        TbWorkcaseDTO dto = BeanUtil.copyProperties(workcase, TbWorkcaseDTO.class);

        // 获取创建人信息
        if (dto.getCreatorId() != null) {
            R<SysUser> creatorResult = remoteUserService.selectById(dto.getCreatorId());
            if (creatorResult.isSuccess() && creatorResult.getData() != null) {
                dto.setCreatorName(creatorResult.getData().getUsername());
                dto.setCreatorDeptName(creatorResult.getData().getDeptName());
            }
        }

        // 获取处理人信息
        if (dto.getAssigneeId() != null) {
            R<SysUser> assigneeResult = remoteUserService.selectById(dto.getAssigneeId());
            if (assigneeResult.isSuccess() && assigneeResult.getData() != null) {
                dto.setAssigneeName(assigneeResult.getData().getUsername());
            }
        }

        return dto;
    }
}
```

## 批量转换工具

### 使用 IDE 批量替换（推荐）

#### IntelliJ IDEA

1. **权限注解替换**
   - 查找：`@PreAuthorize\("hasAuthority\('([^:]+):([^:]+):([^']+)'\)"\)`
   - 替换：`@PreAuthorize("@pms.hasPermission('$1_$2_$3')")`
   - 选项：勾选 "Regex"

2. **响应格式替换**
   - 查找：`ResultDomain\.success\((.*?)\)`
   - 替换：`R.ok($1)`

3. **用户信息获取**
   - 查找：`JwtUtils\.getUserId\(\)`
   - 替换：`SecurityUtils.getUser().getId()`

#### VS Code

使用 Find and Replace (Ctrl+Shift+H)，启用正则表达式模式。

### 使用脚本批量转换

创建 `convert-permissions.sh`：

```bash
#!/bin/bash

# 转换权限注解
find ./src -name "*.java" -type f -exec sed -i \
  's/@PreAuthorize("hasAuthority('\''\\([^:]*\\):\\([^:]*\\):\\([^'\'']*\\)'\''")"/@PreAuthorize("@pms.hasPermission('\''\\1_\\2_\\3'\'')"/g' {} \;

# 转换响应格式
find ./src -name "*.java" -type f -exec sed -i \
  's/ResultDomain\.success(\(.*\))/R.ok(\1)/g' {} \;

# 转换用户信息获取
find ./src -name "*.java" -type f -exec sed -i \
  's/JwtUtils\.getUserId()/SecurityUtils.getUser().getId()/g' {} \;

echo "转换完成！"
```

## 测试验证

### 1. 单元测试示例

```java
@SpringBootTest
@AutoConfigureMockMvc
public class WorkcaseControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @WithMockUser(username = "admin", authorities = {"workcase_ticket_add"})
    public void testCreateWorkcase() throws Exception {
        TbWorkcaseDTO dto = new TbWorkcaseDTO();
        dto.setTitle("测试工单");

        mockMvc.perform(post("/workcase")
                .contentType(MediaType.APPLICATION_JSON)
                .content(JSON.toJSONString(dto)))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(0))
                .andExpect(jsonPath("$.data.title").value("测试工单"));
    }

    @Test
    @WithMockUser(username = "user", authorities = {})
    public void testCreateWorkcaseNoPermission() throws Exception {
        mockMvc.perform(post("/workcase")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{}"))
                .andExpect(status().isForbidden());
    }
}
```

### 2. 集成测试检查清单

- [ ] 权限注解正确转换
- [ ] 用户信息正确获取
- [ ] 租户数据正确隔离
- [ ] 响应格式符合规范
- [ ] RemoteUserService 调用成功
- [ ] 菜单权限正确配置
- [ ] 角色权限正确分配

## 常见问题解决

### Q1: @pms.hasPermission() 不生效

**原因**：没有正确配置 PermissionService Bean

**解决**：
```java
@Configuration
public class SecurityConfig {
    @Bean("pms")
    public PermissionService permissionService() {
        return new PermissionService();
    }
}
```

### Q2: RemoteUserService 调用失败

**原因**：Feign 客户端未正确配置

**解决**：
1. 检查 `@EnableFeignClients` 注解
2. 确认服务名称正确
3. 添加熔断处理

```java
@FeignClient(contextId = "remoteUserService",
            value = ServiceNameConstants.UPMS_SERVICE,
            fallback = RemoteUserServiceFallback.class)
```

### Q3: 租户数据泄露

**原因**：查询时未添加租户过滤

**解决**：
1. 使用 MyBatis-Plus 租户插件
2. 手动添加租户条件

```java
@Configuration
public class MybatisPlusConfig {
    @Bean
    public TenantLineInnerInterceptor tenantLineInnerInterceptor() {
        return new TenantLineInnerInterceptor(new TenantLineHandler() {
            @Override
            public Expression getTenantId() {
                PigxUser user = SecurityUtils.getUser();
                return new LongValue(user.getTenantId());
            }

            @Override
            public String getTenantIdColumn() {
                return "tenant_id";
            }
        });
    }
}
```

## 迁移验证

完成转换后，执行以下验证：

1. **编译检查**：确保所有代码编译通过
2. **启动检查**：应用能正常启动
3. **权限测试**：各接口权限控制正确
4. **数据隔离**：租户数据正确隔离
5. **功能测试**：业务功能正常运行

## 总结

权限迁移是整个系统迁移的核心部分，需要：
1. 仔细转换每个权限注解
2. 正确处理用户信息获取
3. 实现租户数据隔离
4. 充分测试验证

建议分模块逐步迁移，每完成一个模块就进行测试验证。