ccdi/docs/superpowers/specs/2026-03-18-lsfx-logid-primary-binding-design.md

# LSFX Mock LogId 主体账号绑定设计

## 背景

当前 `lsfx-mock-server` 的上传文件接口已经会为文件记录生成 `enterpriseNameList` 和 `accountNoList`，但银行流水查询接口 `getBSByLogId` 仍然在 `StatementService` 内独立随机或写死 `leName`、`accountMaskNo`。这导致同一个 `logId` 在不同接口里看到的“本方主体/本方账号”并不统一。

新增需求要求：

- 每次上传流水文件时，随机生成银行流水的本方主体和本方账号。
- 一个本方主体对应一个本方账号。
- 一个 `logId` 对应一组固定的本方主体和本方账号。
- 同样的逻辑也覆盖“拉取本行信息”链路产生的 `logId`。

## 目标

- 为每个新生成的 `logId` 绑定一组随机本方主体和本方账号。
- 上传文件、上传状态、银行流水查询三类接口对同一 `logId` 返回一致的主体账号信息。
- 保持现有接口出参结构兼容，不引入前端契约变更。

## 范围

### In Scope

- `lsfx-mock-server/services/file_service.py`
- `lsfx-mock-server/services/statement_service.py`
- 上传文件链路的 `logId` 绑定生成
- 拉取本行信息链路的 `logId` 绑定生成
- 对应测试和实施记录

### Out of Scope

- 前端页面或后端 Java 工程改造
- 一个 `logId` 下支持多个本方主体/账号
- 跨 `logId` 复用同一主体账号映射

## 设计原则

- 一个 `logId` = 一个本方主体 + 一个本方账号
- 同一个 `logId` 的所有流水记录都使用同一组 `leName/accountMaskNo`
- 外部响应兼容当前数组格式，但内部语义收敛为单值绑定
- 主体账号由 `FileService` 统一生成，`StatementService` 只消费，不再自行决定

## 现状问题

### 上传文件链路

`FileService.upload_file()` 在创建 `FileRecord` 时会随机生成：

- `account_no_list`
- `enterprise_name_list`

但它们只服务于上传接口和解析状态接口。

### 拉取本行信息链路

`FileService.fetch_inner_flow()` 目前仅返回随机 `logId`，不会创建 `FileRecord`，因此后续没有主体账号上下文可以复用。

### 流水查询链路

`StatementService._generate_random_statement()` 当前独立写死或随机：

- `accountMaskNo`
- `leName`

它不知道上传或拉取本行信息时已经生成了什么主体账号。

## 方案概览

将“本方主体/本方账号”的主数据收敛到 `FileService` 维护的 `FileRecord` 中，并让所有基于 `logId` 的接口围绕同一份绑定工作：

1. `FileService` 在生成新 `logId` 时，创建并保存一组主体账号绑定。
2. `upload_file()` 和 `fetch_inner_flow()` 都走这套绑定生成逻辑。
3. `StatementService` 根据 `logId` 读取绑定值，填入流水的 `leName/accountMaskNo`。
4. 对外仍然返回：
   - `enterpriseNameList: [name]`
   - `accountNoList: [account]`
5. 删除记录时，若 `logId` 绑定被删除，后续兼容逻辑生成的新记录也必须保持接口间自洽。

## 数据模型设计

## FileRecord 扩展

建议在现有 `FileRecord` 上明确单值语义字段：

- `primary_enterprise_name: str`
- `primary_account_no: str`

同时保留兼容字段：

- `enterprise_name_list`
- `account_no_list`

约束为：

- `enterprise_name_list == [primary_enterprise_name]`
- `account_no_list == [primary_account_no]`

这样既不破坏当前响应格式，也让内部逻辑不再把主体和账号当成可变长集合。

## 主体账号生成策略

新增统一生成方法，例如：

- `_generate_primary_account_binding()`

职责：

- 随机选取一个本方主体名称
- 随机生成一个本方账号
- 返回单一绑定对象

建议主体名称从固定 Mock 名称池中随机选择，例如：

- `测试主体A`
- `测试主体B`
- `测试主体C`
- `兰溪测试主体一部`
- `兰溪测试主体二部`

账号生成规则保持简单：

- 生成合法长度的纯数字字符串
- 作为单个 `logId` 的专属账号使用

本次不要求“同一主体跨所有 `logId` 始终映射同一账号”，只要求：

- 对单个 `logId` 而言，主体与账号是一对一且稳定的

## 接口联动设计

### 1. 上传文件接口

`upload_file()` 在创建 `FileRecord` 时：

- 生成 `logId`
- 生成主体账号绑定
- 回填：
  - `primary_enterprise_name`
  - `primary_account_no`
  - `enterprise_name_list`
  - `account_no_list`

上传响应里的：

- `accountsOfLog[*].accountName`
- `accountsOfLog[*].accountNo`
- `uploadLogList[*].enterpriseNameList`
- `uploadLogList[*].accountNoList`

都来自这组绑定。

### 2. 拉取本行信息接口

`fetch_inner_flow()` 不能再只返回裸 `logId`，需要同时：

- 生成新 `logId`
- 创建 `FileRecord`
- 生成主体账号绑定并落入 `self.file_records`

这样同一个 `logId` 后续再查上传状态或银行流水时，能拿到一致的本方主体和账号。

### 3. 上传状态接口

`check_parse_status()` 和 `get_upload_status()` 对已存在的 `FileRecord`，统一返回其中的绑定数据。

若 `get_upload_status()` 走兼容分支按 `logId` 现场生成记录，生成出的主体账号也必须写成单一绑定，并在该次响应内部保持自洽。

### 4. 银行流水查询接口

`StatementService` 不再自己决定：

- `leName`
- `accountMaskNo`

而是通过 `logId` 获取对应绑定：

- `leName = primary_enterprise_name`
- `accountMaskNo = primary_account_no`

同一 `logId` 下生成的所有流水记录都使用这一组值。

## 组件边界

### FileService

负责：

- 生成 `logId`
- 生成并保存主体账号绑定
- 对上传/拉取本行信息/上传状态返回统一绑定值

### StatementService

负责：

- 读取 `logId` 对应主体账号绑定
- 将绑定值注入每条流水记录
- 不再自行随机本方主体或本方账号

为避免重复造一份状态，`StatementService` 需要拿到查询绑定的方法或共享 `file_records` 访问能力，但不负责写绑定。

## 错误处理

- 若 `logId` 没有对应绑定记录，允许走兼容生成逻辑，但必须在当前响应范围内自洽。
- 不允许同一次 `getBSByLogId` 返回中出现多个本方主体或多个本方账号。
- 不允许上传响应和流水响应对同一 `logId` 返回不同主体账号。

## 测试设计

至少补 3 类测试：

### 1. 上传文件链路测试

验证上传接口返回中：

- `accountsOfLog` 的 `accountName/accountNo`
- `uploadLogList` 的 `enterpriseNameList/accountNoList`

三者一致，且数组长度为 `1`。

### 2. 拉取本行信息链路测试

验证 `fetch_inner_flow()` 返回 `logId` 后：

- `FileService` 内已存在对应 `FileRecord`
- 该记录带有主体账号绑定
- 后续查询上传状态或银行流水时能看到相同绑定

### 3. 银行流水链路测试

验证同一 `logId` 下：

- 第一页和第二页流水里的 `leName/accountMaskNo` 一致
- 重复查询结果中的本方主体账号不漂移
- 流水里的 `leName/accountMaskNo` 与 `FileRecord` 中的绑定完全一致

## 成功标准

- 上传文件和拉取本行信息产生的新 `logId` 都会绑定一组随机本方主体与账号。
- 同一 `logId` 的上传响应、上传状态、银行流水查询三处返回一致的主体账号。
- 同一 `logId` 的所有流水记录只出现一个 `leName` 和一个 `accountMaskNo`。
- 对外接口结构不变，前端无需因这次改动调整解析逻辑。

## 风险与约束

- 现有 `get_upload_status()` 存在按 `logId` 即时生成确定性记录的兼容路径，这部分要特别注意与 `file_records` 中真实记录的优先级。
- 若后续一个 `logId` 需要支持多个本方账号，本次设计需要重做，因为当前明确锁定为“一对一”。
- `StatementService` 新增对 `FileService` 绑定数据的依赖后，需要避免双向循环依赖，优先通过轻量查询函数或共享只读访问注入。

## 实施输出

实施阶段应至少产出：

- Mock 服务代码改动
- 对应 pytest 测试
- 一份后端实施计划
- 一份前端实施计划
- 一份实施记录文档