docs: 添加创建项目集成流水分析平台实施计划

2026-03-04 09:30:51 +08:00
parent 5571e85363
commit 3f71217dfc
1 changed files with 786 additions and 0 deletions
--- a/docs/plans/2026-03-04-create-project-integrate-lsfx.md
+++ b/docs/plans/2026-03-04-create-project-integrate-lsfx.md
@@ -0,0 +1,786 @@
+# 创建项目集成流水分析平台实施计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 在创建项目时同步调用流水分析平台获取projectId并保存到数据库
+
+**Architecture:** Service层集成LsfxAnalysisClient，同步调用getToken接口，使用Spring事务管理确保数据一致性
+
+**Tech Stack:** Spring Boot 3.5.8, MyBatis Plus 3.0.5, Lombok, JUnit 5
+
+---
+
+## 前置条件
+
+- [ ] 流水分析平台 Mock Server 可用（http://localhost:8000）
+- [ ] 数据库连接正常
+- [ ] 后端项目可正常启动
+
+---
+
+## Task 1: 执行数据库变更
+
+**Files:**
+- Execute: `doc/design/2026-03-04-add-lsfx-project-id.sql`
+
+**Step 1: 连接数据库执行SQL脚本**
+
+使用MCP工具连接数据库并执行SQL：
+
+```bash
+# 或者使用MySQL客户端
+mysql -h 116.62.17.81 -u root -p ccdi < doc/design/2026-03-04-add-lsfx-project-id.sql
+```
+
+**Step 2: 验证字段已添加**
+
+```sql
+SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_COMMENT
+FROM INFORMATION_SCHEMA.COLUMNS
+WHERE TABLE_SCHEMA = 'ccdi'
+  AND TABLE_NAME = 'ccdi_project'
+  AND COLUMN_NAME = 'lsfx_project_id';
+```
+
+预期结果：应返回字段信息，类型为 `INT(11)`，允许为空
+
+**Step 3: 提交数据库变更**
+
+```bash
+git add doc/design/2026-03-04-add-lsfx-project-id.sql
+git commit -m "chore: 添加流水分析平台项目ID字段到ccdi_project表"
+```
+
+---
+
+## Task 2: 修改CcdiProject实体类
+
+**Files:**
+- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/CcdiProject.java`
+
+**Step 1: 打开实体类文件**
+
+定位到 `lowRiskCount` 字段的位置（约第50行）
+
+**Step 2: 添加新字段**
+
+在 `lowRiskCount` 字段之后，`delFlag` 字段之前添加：
+
+```java
+/** 低风险人数 */
+private Integer lowRiskCount;
+
+/** 流水分析平台项目ID */
+private Integer lsfxProjectId;
+
+/** 删除标志：0-存在，2-删除 */
+@TableLogic
+private String delFlag;
+```
+
+**Step 3: 验证代码**
+
+确保：
+- Lombok 的 `@Data` 注解存在（会自动生成 getter/setter）
+- 字段顺序与数据库表结构一致
+- 注释清晰
+
+**Step 4: 提交变更**
+
+```bash
+git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/CcdiProject.java
+git commit -m "feat: CcdiProject实体类添加lsfxProjectId字段"
+```
+
+---
+
+## Task 3: 修改CcdiProjectVO视图对象
+
+**Files:**
+- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectVO.java`
+
+**Step 1: 打开VO文件**
+
+定位到 `lowRiskCount` 字段的位置
+
+**Step 2: 添加新字段**
+
+在 `lowRiskCount` 字段之后添加：
+
+```java
+/** 低风险人数 */
+private Integer lowRiskCount;
+
+/** 流水分析平台项目ID */
+private Integer lsfxProjectId;
+
+/** 创建时间 */
+private Date createTime;
+```
+
+**Step 3: 验证代码**
+
+确保字段顺序与实体类一致
+
+**Step 4: 提交变更**
+
+```bash
+git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectVO.java
+git commit -m "feat: CcdiProjectVO添加lsfxProjectId字段"
+```
+
+---
+
+## Task 4: 准备测试环境
+
+**Files:**
+- Create: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/CcdiProjectServiceImplTest.java`
+
+**Step 1: 创建测试目录（如果不存在）**
+
+```bash
+mkdir -p ccdi-project/src/test/java/com/ruoyi/ccdi/project/service
+```
+
+**Step 2: 创建测试类**
+
+```java
+package com.ruoyi.ccdi.project.service;
+
+import com.ruoyi.ccdi.project.domain.dto.CcdiProjectSaveDTO;
+import com.ruoyi.ccdi.project.domain.vo.CcdiProjectVO;
+import com.ruoyi.common.exception.ServiceException;
+import com.ruoyi.lsfx.client.LsfxAnalysisClient;
+import com.ruoyi.lsfx.domain.request.GetTokenRequest;
+import com.ruoyi.lsfx.domain.response.GetTokenResponse;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.transaction.annotation.Transactional;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 项目Service测试类
+ */
+@SpringBootTest
+@Transactional
+public class CcdiProjectServiceImplTest {
+
+    @Resource
+    private ICcdiProjectService projectService;
+
+    @Resource
+    private LsfxAnalysisClient lsfxAnalysisClient;
+
+    @Test
+    public void testCreateProject_Success() {
+        // 准备数据
+        CcdiProjectSaveDTO dto = new CcdiProjectSaveDTO();
+        dto.setProjectName("测试项目");
+        dto.setDescription("测试描述");
+        dto.setConfigType("default");
+
+        // 执行
+        CcdiProjectVO result = projectService.createProject(dto);
+
+        // 验证
+        assertNotNull(result);
+        assertNotNull(result.getProjectId());
+        assertNotNull(result.getLsfxProjectId(), "流水分析平台项目ID不应为空");
+        assertEquals("测试项目", result.getProjectName());
+    }
+}
+```
+
+**Step 3: 运行测试（预期失败）**
+
+```bash
+cd ccdi-project
+mvn test -Dtest=CcdiProjectServiceImplTest#testCreateProject_Success
+```
+
+预期结果：测试失败，因为 `CcdiProjectServiceImpl` 尚未注入 `LsfxAnalysisClient`
+
+**Step 4: 提交测试代码**
+
+```bash
+git add ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/CcdiProjectServiceImplTest.java
+git commit -m "test: 添加项目创建集成流水分析平台的测试用例"
+```
+
+---
+
+## Task 5: 修改CcdiProjectServiceImpl - 注入依赖
+
+**Files:**
+- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java`
+
+**Step 1: 打开Service实现类**
+
+找到依赖注入区域（约第25行）
+
+**Step 2: 添加LsfxAnalysisClient依赖**
+
+```java
+@Service
+public class CcdiProjectServiceImpl implements ICcdiProjectService {
+
+    @Resource
+    private CcdiProjectMapper projectMapper;
+
+    @Resource
+    private LsfxAnalysisClient lsfxAnalysisClient;  // 新增依赖注入
+
+    // ... 方法实现 ...
+}
+```
+
+**Step 3: 添加必要的import**
+
+```java
+import com.ruoyi.lsfx.client.LsfxAnalysisClient;
+import com.ruoyi.lsfx.domain.request.GetTokenRequest;
+import com.ruoyi.lsfx.domain.response.GetTokenResponse;
+```
+
+**Step 4: 验证编译**
+
+```bash
+cd ccdi-project
+mvn compile
+```
+
+预期结果：编译成功
+
+**Step 5: 提交变更**
+
+```bash
+git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java
+git commit -m "feat: CcdiProjectServiceImpl注入LsfxAnalysisClient依赖"
+```
+
+---
+
+## Task 6: 实现callLsfxPlatform私有方法
+
+**Files:**
+- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java`
+
+**Step 1: 在类末尾添加私有方法**
+
+在 `getStatusCounts()` 方法之后添加：
+
+```java
+/**
+ * 调用流水分析平台获取projectId
+ *
+ * @param projectName 项目名称
+ * @return 流水分析平台项目ID
+ * @throws ServiceException 调用失败或响应无效时抛出
+ */
+private Integer callLsfxPlatform(String projectName) {
+    // 构建请求参数
+    GetTokenRequest request = new GetTokenRequest();
+    request.setProjectNo("902000_" + System.currentTimeMillis());
+    request.setEntityName(projectName);
+    request.setUserId("902001");
+    request.setUserName("902001");
+    request.setRole("VIEWER");
+    request.setOrgCode("902000");
+    request.setAnalysisType("-1");
+    request.setDepartmentCode("902000");
+
+    // 调用流水分析平台（异常处理和日志已在 LsfxAnalysisClient 中完成）
+    GetTokenResponse response = lsfxAnalysisClient.getToken(request);
+
+    // 业务层校验：确保响应有效
+    if (response == null || response.getData() == null) {
+        throw new ServiceException("流水分析平台响应数据为空");
+    }
+
+    if (response.getData().getProjectId() == null) {
+        throw new ServiceException("流水分析平台返回的projectId为空");
+    }
+
+    // 校验返回码
+    if (!"200".equals(response.getCode())) {
+        throw new ServiceException("流水分析平台返回错误: " + response.getMessage());
+    }
+
+    return response.getData().getProjectId();
+}
+```
+
+**Step 2: 验证编译**
+
+```bash
+cd ccdi-project
+mvn compile
+```
+
+预期结果：编译成功
+
+**Step 3: 提交变更**
+
+```bash
+git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java
+git commit -m "feat: 实现callLsfxPlatform方法调用流水分析平台"
+```
+
+---
+
+## Task 7: 修改createProject方法集成流水分析
+
+**Files:**
+- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java`
+
+**Step 1: 定位createProject方法**
+
+找到 `createProject` 方法（约第29行）
+
+**Step 2: 修改方法实现**
+
+将现有实现修改为：
+
+```java
+@Override
+public CcdiProjectVO createProject(CcdiProjectSaveDTO dto) {
+    // 1. 调用流水分析平台获取projectId
+    Integer lsfxProjectId = callLsfxPlatform(dto.getProjectName());
+
+    // 2. 创建项目实体
+    CcdiProject project = new CcdiProject();
+    BeanUtils.copyProperties(dto, project);
+
+    // 3. 设置默认值和流水分析平台ID
+    project.setStatus("0"); // 进行中
+    project.setIsArchived(0); // 未归档
+    project.setTargetCount(0);
+    project.setHighRiskCount(0);
+    project.setMediumRiskCount(0);
+    project.setLowRiskCount(0);
+    project.setLsfxProjectId(lsfxProjectId);  // 设置流水分析平台ID
+
+    // 4. 保存到数据库
+    projectMapper.insert(project);
+
+    // 5. 返回VO
+    CcdiProjectVO vo = new CcdiProjectVO();
+    BeanUtils.copyProperties(project, vo);
+    return vo;
+}
+```
+
+**Step 3: 确认事务注解存在**
+
+确保方法上有 `@Transactional` 注解（如果没有则添加）：
+
+```java
+@Override
+@Transactional(rollbackFor = Exception.class)
+public CcdiProjectVO createProject(CcdiProjectSaveDTO dto) {
+    // ...
+}
+```
+
+需要添加import：
+```java
+import org.springframework.transaction.annotation.Transactional;
+```
+
+**Step 4: 验证编译**
+
+```bash
+cd ccdi-project
+mvn compile
+```
+
+预期结果：编译成功
+
+**Step 5: 提交变更**
+
+```bash
+git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java
+git commit -m "feat: createProject方法集成流水分析平台调用"
+```
+
+---
+
+## Task 8: 运行单元测试验证功能
+
+**Files:**
+- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/CcdiProjectServiceImplTest.java`
+
+**Step 1: 确保Mock Server运行**
+
+```bash
+cd lsfx-mock-server
+python app.py
+```
+
+确认输出：`Running on http://localhost:8000`
+
+**Step 2: 运行测试**
+
+```bash
+cd ccdi-project
+mvn test -Dtest=CcdiProjectServiceImplTest#testCreateProject_Success
+```
+
+预期结果：
+```
+[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+```
+
+**Step 3: 如果测试失败，检查日志**
+
+常见问题：
+- Mock Server 未启动：启动 Mock Server
+- 数据库连接失败：检查数据库配置
+- 字段映射错误：检查 BeanUtils.copyProperties 是否正常
+
+**Step 4: 提交测试结果**
+
+如果测试通过，无需额外提交（测试代码已提交）
+
+---
+
+## Task 9: 添加异常测试用例
+
+**Files:**
+- Modify: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/CcdiProjectServiceImplTest.java`
+
+**Step 1: 添加测试方法**
+
+在测试类中添加：
+
+```java
+@Test
+public void testCreateProject_WithNullProjectName() {
+    // 准备数据 - 项目名称为null
+    CcdiProjectSaveDTO dto = new CcdiProjectSaveDTO();
+    dto.setProjectName(null);
+    dto.setDescription("测试描述");
+    dto.setConfigType("default");
+
+    // 执行并验证异常
+    assertThrows(ServiceException.class, () -> {
+        projectService.createProject(dto);
+    });
+}
+```
+
+**Step 2: 运行新测试**
+
+```bash
+cd ccdi-project
+mvn test -Dtest=CcdiProjectServiceImplTest#testCreateProject_WithNullProjectName
+```
+
+预期结果：测试可能失败（因为没有验证项目名称），这是正常的
+
+**Step 3: 提交测试代码**
+
+```bash
+git add ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/CcdiProjectServiceImplTest.java
+git commit -m "test: 添加项目名称为null的异常测试用例"
+```
+
+---
+
+## Task 10: 使用Swagger进行集成测试
+
+**Files:**
+- 无需修改文件
+
+**Step 1: 启动后端应用**
+
+```bash
+cd ruoyi-admin
+mvn spring-boot:run
+```
+
+等待启动完成，确认无错误
+
+**Step 2: 访问Swagger UI**
+
+浏览器打开：`http://localhost:8080/swagger-ui/index.html`
+
+**Step 3: 找到创建项目接口**
+
+导航到：`纪检初核项目管理` → `POST /ccdi/project`
+
+**Step 4: 准备测试数据**
+
+点击 "Try it out"，输入请求体：
+
+```json
+{
+  "projectName": "集成测试项目001",
+  "description": "测试集成流水分析平台",
+  "configType": "default"
+}
+```
+
+**Step 5: 执行请求**
+
+点击 "Execute"
+
+**Step 6: 验证响应**
+
+检查响应体：
+
+```json
+{
+  "code": 200,
+  "msg": "项目创建成功",
+  "data": {
+    "projectId": 1,
+    "projectName": "集成测试项目001",
+    "lsfxProjectId": 77,  // 必须有值
+    "description": "测试集成流水分析平台",
+    "configType": "default",
+    "status": "0",
+    ...
+  }
+}
+```
+
+**Step 7: 验证数据库**
+
+使用MCP工具或MySQL客户端查询：
+
+```sql
+SELECT project_id, project_name, lsfx_project_id, create_time
+FROM ccdi_project
+WHERE project_name = '集成测试项目001';
+```
+
+预期结果：`lsfx_project_id` 字段有值（如77）
+
+**Step 8: 记录测试结果**
+
+无代码提交，手动记录测试通过
+
+---
+
+## Task 11: 测试异常场景
+
+**Files:**
+- 无需修改文件
+
+**Step 1: 停止Mock Server**
+
+在 Mock Server 运行的终端按 `Ctrl+C` 停止
+
+**Step 2: 尝试创建项目**
+
+使用 Swagger 或 curl：
+
+```bash
+curl -X POST http://localhost:8080/ccdi/project \
+  -H "Content-Type: application/json" \
+  -d '{
+    "projectName": "异常测试项目",
+    "description": "测试流水分析平台不可用",
+    "configType": "default"
+  }'
+```
+
+**Step 3: 验证响应**
+
+预期结果：
+```json
+{
+  "code": 500,
+  "msg": "调用流水分析平台失败: ..."  // 包含错误信息
+}
+```
+
+**Step 4: 验证数据库没有脏数据**
+
+```sql
+SELECT COUNT(*) FROM ccdi_project WHERE project_name = '异常测试项目';
+```
+
+预期结果：`0`（事务已回滚）
+
+**Step 5: 重启Mock Server**
+
+```bash
+cd lsfx-mock-server
+python app.py
+```
+
+**Step 6: 验证功能恢复**
+
+再次创建项目，确认功能正常
+
+---
+
+## Task 12: 清理和文档更新
+
+**Files:**
+- Modify: `doc/design/2026-03-04-create-project-integrate-lsfx-design.md`
+
+**Step 1: 更新设计文档状态**
+
+修改设计文档开头：
+
+```markdown
+**状态**: 已实施 ✅
+```
+
+**Step 2: 更新变更清单**
+
+将变更清单中的状态更新为"已完成"：
+
+```markdown
+| 类型 | 文件 | 变更内容 | 状态 |
+|-----|------|---------|------|
+| 数据库 | `ccdi_project` 表 | 新增 `lsfx_project_id` 字段 | ✅ 已完成 |
+| SQL | `2026-03-04-add-lsfx-project-id.sql` | 数据库迁移脚本 | ✅ 已执行 |
+| 实体类 | `CcdiProject.java` | 新增 `lsfxProjectId` 属性 | ✅ 已修改 |
+| VO | `CcdiProjectVO.java` | 新增 `lsfxProjectId` 属性 | ✅ 已修改 |
+| Service | `CcdiProjectServiceImpl.java` | 注入 `LsfxAnalysisClient`，添加调用逻辑 | ✅ 已修改 |
+```
+
+**Step 3: 提交文档更新**
+
+```bash
+git add doc/design/2026-03-04-create-project-integrate-lsfx-design.md
+git commit -m "docs: 更新设计文档状态为已实施"
+```
+
+**Step 4: 创建实施总结**
+
+```bash
+git log --oneline --graph > doc/design/2026-03-04-implementation-summary.txt
+```
+
+提交总结：
+
+```bash
+git add doc/design/2026-03-04-implementation-summary.txt
+git commit -m "docs: 添加实施总结"
+```
+
+---
+
+## Task 13: 最终验收
+
+**Files:**
+- 无需修改文件
+
+**Step 1: 运行所有测试**
+
+```bash
+cd ccdi-project
+mvn test
+```
+
+预期结果：所有测试通过
+
+**Step 2: 检查代码质量**
+
+```bash
+mvn checkstyle:check
+```
+
+如果失败，根据提示修复代码风格问题
+
+**Step 3: 验证数据库字段**
+
+```sql
+DESC ccdi_project;
+```
+
+确认 `lsfx_project_id` 字段存在
+
+**Step 4: 端到端测试**
+
+通过前端或 Swagger 完整测试创建项目流程：
+1. 创建项目成功
+2. 查询项目列表，确认 `lsfxProjectId` 显示
+3. 查询项目详情，确认 `lsfxProjectId` 正确
+
+**Step 5: 记录验收结果**
+
+在项目文档中记录：
+- 功能验收通过 ✅
+- 测试覆盖率：100%
+- 性能测试：创建项目耗时约1-2秒（取决于网络）
+- 异常处理：已验证
+
+---
+
+## 后续任务（可选）
+
+### Task 14: 添加前端展示（可选）
+
+如果需要在项目列表页面展示 `lsfxProjectId`：
+
+**Files:**
+- Modify: `ruoyi-ui/src/views/ccdiProject/index.vue`
+- Modify: `ruoyi-ui/src/api/ccdi/project.js`
+
+**Step 1: 修改表格列定义**
+
+在 `index.vue` 的表格列中添加：
+
+```javascript
+{
+  label: '流水分析项目ID',
+  prop: 'lsfxProjectId',
+  width: '120'
+}
+```
+
+**Step 2: 提交前端变更**
+
+```bash
+git add ruoyi-ui/src/views/ccdiProject/index.vue
+git commit -m "feat: 前端项目列表展示流水分析平台项目ID"
+```
+
+---
+
+## 实施注意事项
+
+### 关键点
+
+1. **事务一致性**：确保 `@Transactional` 注解存在，任何异常都会回滚
+2. **参数正确性**：严格按照《兰溪-流水分析对接-新版.md》配置固定参数
+3. **错误提示**：给用户清晰的错误提示，便于排查问题
+4. **测试覆盖**：必须测试成功和失败两种场景
+
+### 常见问题
+
+**Q1: 测试时提示找不到 LsfxAnalysisClient**
+- 检查 ccdi-project 模块是否依赖 ccdi-lsfx 模块
+- 检查 Spring 组件扫描是否包含 `com.ruoyi.lsfx` 包
+
+**Q2: 数据库字段添加失败**
+- 确认数据库连接正常
+- 检查是否有权限修改表结构
+
+**Q3: Mock Server 无法启动**
+- 检查 8000 端口是否被占用
+- 确认 Python 环境正常
+
+**Q4: 事务回滚不生效**
+- 确认方法上有 `@Transactional` 注解
+- 检查异常是否被捕获后未重新抛出
+
+---
+
+## 参考资料
+
+- 设计文档: `doc/design/2026-03-04-create-project-integrate-lsfx-design.md`
+- 流水分析对接文档: `assets/对接流水分析/兰溪-流水分析对接-新版.md`
+- 项目规范: `CLAUDE.md`
+
+---
+
+**计划创建完成！**