ccdi/docs/design/2026-03-04-create-project-integrate-lsfx-design.md

# 创建项目时集成流水分析平台设计方案

**文档版本**: 1.0
**创建日期**: 2026-03-04
**作者**: Claude Code
**状态**: ✅ 已实施
**实施日期**: 2026-03-04
**测试状态**: ✅ 测试通过

---

## 1. 需求概述

### 1.1 背景

在纪检初核系统中，创建项目时需要同步在流水分析平台创建对应的项目，以便后续进行流水分析操作。

### 1.2 目标

- 创建项目时自动调用流水分析平台的 `getToken` 接口
- 获取返回的 `projectId` 并保存到项目表
- 确保数据一致性，调用失败时项目创建也失败

### 1.3 参考文档

- 《兰溪-流水分析对接-新版.md》
- 项目现有代码：`ccdi-project` 模块、`ccdi-lsfx` 模块

---

## 2. 设计方案

### 2.1 总体架构

#### 业务流程

```
用户创建项目
    ↓
Controller接收请求
    ↓
Service层处理
    ├─→ 生成projectNo (902000_时间戳)
    ├─→ 调用流水分析平台getToken接口
    │   ├─→ 成功：获取projectId
    │   └─→ 失败：抛出异常，事务回滚
    ├─→ 保存项目（包含projectId）
    └─→ 返回项目信息
```

#### 技术方案

- **调用方式**: 同步调用
- **集成位置**: Service层（`CcdiProjectServiceImpl`）
- **事务管理**: Spring声明式事务，失败自动回滚
- **异常处理**: 依赖 `LsfxAnalysisClient` 的异常处理

### 2.2 核心设计决策

| 决策点 | 选择 | 理由 |
|-------|------|------|
| 调用方式 | 同步调用 | 数据一致性强，用户体验清晰 |
| 保存策略 | 仅保存projectId | token 使用一次后失效，无需保存 |
| 集成位置 | Service层 | 业务逻辑集中，事务管理简单 |
| 异常处理 | 依赖客户端 | 避免重复日志，Service层只做业务校验 |

---

## 3. 详细设计

### 3.1 数据库设计

#### ccdi_project 表新增字段

```sql
ALTER TABLE `ccdi_project`
ADD COLUMN `lsfx_project_id` INT(11) DEFAULT NULL COMMENT '流水分析平台项目ID'
AFTER `low_risk_count`;
```

**字段说明:**
- 字段名: `lsfx_project_id`
- 类型: `INT(11)`（与流水分析平台保持一致）
- 允许为空: 是（理论上不会为空，因为失败会回滚）
- 索引: 不设置唯一索引（流水分析平台的 projectId 可能重复）

### 3.2 参数映射规则

根据《兰溪-流水分析对接-新版.md》文档，GetTokenRequest 参数配置如下：

#### 必填参数（固定值）

| 参数名 | 值 | 说明 |
|-------|-----|------|
| `userId` | `"902001"` | 操作人员编号（固定值） |
| `userName` | `"902001"` | 操作人员姓名（固定值） |
| `role` | `"VIEWER"` | 人员角色（固定值） |
| `orgCode` | `"902000"` | 行社机构号（固定值） |
| `analysisType` | `"-1"` | 分析类型（固定值） |
| `departmentCode` | `"902000"` | 客户经理所属营业部机构编码（固定值） |

#### 必填参数（动态生成）

| 参数名 | 生成规则 | 说明 |
|-------|---------|------|
| `projectNo` | `"902000_" + System.currentTimeMillis()` | 项目编号 |
| `entityName` | 使用前端传入的 `projectName` | 项目名称 |

#### 自动生成参数

| 参数名 | 生成位置 | 说明 |
|-------|---------|------|
| `appId` | `LsfxAnalysisClient` 配置 | 固定值：`remote_app` |
| `appSecretCode` | `LsfxAnalysisClient.getToken()` | MD5(projectNo + "_" + entityName + "_" + appSecret) |

#### 可选参数

以下参数不传递（暂不需要）：
- `entityId` (企业统信码或个人身份证号)
- `xdRelatedPersons` (信贷关联人信息)
- `jzDataDateId` (金综链流水日期ID)
- `innerBSStartDateId` (行内流水开始日期)
- `innerBSEndDateId` (行内流水结束日期)

### 3.3 代码实现

#### 3.3.1 实体类修改

**CcdiProject.java**

```java
@Data
@TableName("ccdi_project")
public class CcdiProject implements Serializable {

    // ... 现有字段 ...

    /** 低风险人数 */
    private Integer lowRiskCount;

    /** 流水分析平台项目ID */
    private Integer lsfxProjectId;  // 新增字段

    /** 删除标志 */
    @TableLogic
    private String delFlag;

    // ... 审计字段 ...
}
```

**CcdiProjectVO.java**

```java
@Data
public class CcdiProjectVO implements Serializable {

    // ... 现有字段 ...

    /** 低风险人数 */
    private Integer lowRiskCount;

    /** 流水分析平台项目ID */
    private Integer lsfxProjectId;  // 新增字段

    /** 创建时间 */
    private Date createTime;

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

#### 3.3.2 Service实现

**CcdiProjectServiceImpl.java**

```java
@Service
public class CcdiProjectServiceImpl implements ICcdiProjectService {

    @Resource
    private CcdiProjectMapper projectMapper;

    @Resource
    private LsfxAnalysisClient lsfxAnalysisClient;  // 新增依赖注入

    @Override
    @Transactional(rollbackFor = Exception.class)
    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;
    }

    /**
     * 调用流水分析平台获取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();
    }
}
```

### 3.4 异常处理与事务管理

#### 3.4.1 异常处理策略

**场景1：流水分析平台调用失败**
- `LsfxAnalysisClient` 抛出 `LsfxApiException`
- Service 层捕获后转换为 `ServiceException`
- Spring 事务自动回滚
- 用户收到明确错误提示

**场景2：网络超时**
- `LsfxAnalysisClient` 配置了超时时间（连接30秒，读取60秒）
- 超时后抛出异常，事务回滚

**场景3：响应数据无效**
- Service 层进行业务校验
- 发现无效响应抛出 `ServiceException`
- 事务回滚

#### 3.4.2 事务管理

```java
@Transactional(rollbackFor = Exception.class)
public CcdiProjectVO createProject(CcdiProjectSaveDTO dto) {
    // 任何一步失败，整个事务自动回滚
    Integer lsfxProjectId = callLsfxPlatform(dto.getProjectName());

    // ... 数据库操作 ...

    projectMapper.insert(project);
    return vo;
}
```

**特性:**
- 声明式事务管理
- 任何异常都触发回滚
- 保证数据一致性

#### 3.4.3 日志记录

日志记录已在 `LsfxAnalysisClient.getToken()` 中实现：

```java
// LsfxAnalysisClient 中的日志
log.info("【流水分析】获取Token请求: projectNo={}, entityName={}", ...);
log.info("【流水分析】获取Token成功: projectId={}, 耗时={}ms", ...);
log.error("【流水分析】获取Token失败: projectNo={}, error={}", ...);
```

Service 层无需重复记录日志。

---

## 4. 实施步骤

### 4.1 实施顺序

**步骤1：数据库变更**
```bash
# 执行SQL脚本
mysql -u root -p ccdi < doc/design/2026-03-04-add-lsfx-project-id.sql
```

**步骤2：修改实体类和VO**
- `CcdiProject` 实体类添加 `lsfxProjectId` 字段
- `CcdiProjectVO` 视图对象添加 `lsfxProjectId` 字段

**步骤3：修改 Service 实现**
- `CcdiProjectServiceImpl` 注入 `LsfxAnalysisClient`
- 添加 `callLsfxPlatform()` 私有方法
- 修改 `createProject()` 方法

**步骤4：单元测试**
- 测试正常创建项目流程
- 测试流水分析平台调用失败场景
- 测试网络超时场景

**步骤5：集成测试**
- 使用 Swagger 测试完整流程
- 验证数据库中 `lsfx_project_id` 是否正确保存
- 验证流水分析平台是否成功创建项目

**步骤6：前端适配（可选）**
- 如果前端需要展示 `lsfxProjectId`，修改前端页面

### 4.2 数据库迁移脚本

**文件路径**: `doc/design/2026-03-04-add-lsfx-project-id.sql`

```sql
-- ====================================
-- 功能：ccdi_project 表新增流水分析平台项目ID字段
-- 日期：2026-03-04
-- 作者：Claude Code
-- ====================================

USE ccdi;

-- 新增字段
ALTER TABLE `ccdi_project`
ADD COLUMN `lsfx_project_id` INT(11) DEFAULT NULL COMMENT '流水分析平台项目ID'
AFTER `low_risk_count`;

-- 验证
SELECT * FROM `ccdi_project` LIMIT 1;
```

---

## 5. 测试方案

### 5.1 单元测试

**测试类**: `CcdiProjectServiceImplTest.java`

```java
@SpringBootTest
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());
        assertEquals("测试项目", result.getProjectName());
    }

    @Test(expected = ServiceException.class)
    public void testCreateProject_LsfxFailed() {
        // 模拟流水分析平台失败
        // 需要使用 Mock 或关闭 Mock Server

        CcdiProjectSaveDTO dto = new CcdiProjectSaveDTO();
        dto.setProjectName("测试项目");

        projectService.createProject(dto);
    }
}
```

### 5.2 集成测试

**测试步骤:**

1. **启动 Mock Server**
   ```bash
   cd lsfx-mock-server
   python app.py
   ```

2. **访问 Swagger**
   ```
   http://localhost:8080/swagger-ui/index.html
   ```

3. **测试创建项目接口**
   - 接口: `POST /ccdi/project`
   - 请求体:
     ```json
     {
       "projectName": "测试项目001",
       "description": "测试项目描述",
       "configType": "default"
     }
     ```

4. **验证响应**
   ```json
   {
     "code": 200,
     "msg": "项目创建成功",
     "data": {
       "projectId": 1,
       "projectName": "测试项目001",
       "lsfxProjectId": 77,  // 应该有值
       ...
     }
   }
   ```

5. **验证数据库**
   ```sql
   SELECT project_id, project_name, lsfx_project_id
   FROM ccdi_project
   WHERE project_id = 1;
   ```

### 5.3 异常测试

**测试场景:**

1. **流水分析平台不可用**
   - 关闭 Mock Server
   - 创建项目应该失败
   - 数据库不应该有新记录

2. **网络超时**
   - 修改 Mock Server 延迟超过60秒
   - 创建项目应该超时失败

3. **返回错误码**
   - 修改 Mock Server 返回错误码（如40104）
   - 创建项目应该失败并显示对应错误信息

---

## 6. 风险与注意事项

### 6.1 风险分析

| 风险 | 影响 | 缓解措施 |
|-----|------|---------|
| 流水分析平台不可用 | 无法创建项目 | 提供明确的错误提示，用户可稍后重试 |
| 网络延迟 | 创建项目缓慢 | 已配置合理超时时间（60秒） |
| projectId 重复 | 无影响 | 不设置唯一索引 |
| 事务回滚失败 | 数据不一致 | 依赖 Spring 事务管理，经过充分验证 |

### 6.2 注意事项

1. **依赖外部服务**
   - 流水分析平台必须可用
   - 建议在生产环境做好监控和告警

2. **无重试机制**
   - 失败需要用户手动重试
   - 可以考虑在 UI 层提供重试按钮

3. **项目编号唯一性**
   - 使用时间戳保证唯一性
   - 理论上不会重复（毫秒级时间戳）

4. **前端适配**
   - 当前设计不要求前端传 `lsfxProjectId`
   - 如果需要展示，修改前端页面即可

---

## 7. 变更清单

| 类型 | 文件 | 变更内容 | 状态 |
|-----|------|---------|------|
| 数据库 | `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`，添加调用逻辑 | 待修改 |

---

## 8. 后续优化建议

### 8.1 短期优化

1. **添加重试机制**
   - 在 Service 层添加自动重试（最多3次）
   - 使用 Spring Retry 框架

2. **异步调用（可选）**
   - 如果创建速度成为瓶颈，可改为异步调用
   - 需要增加状态管理和轮询接口

### 8.2 长期优化

1. **批量创建支持**
   - 如果需要批量创建项目，考虑批量调用流水分析平台

2. **缓存机制**
   - 如果 token 需要重复使用，考虑缓存机制
   - 需要处理 token 过期问题

---

## 9. 参考资料

- 《兰溪-流水分析对接-新版.md》
- 项目 CLAUDE.md 文档
- Spring Boot 事务管理文档
- MyBatis Plus 使用指南

---

**文档结束**