修复Mock流水按数据库员工及亲属绑定身份证

docs/plans/misc/2026-03-19-lsfx-mock-db-backed-identity-selection-implementation.md

@@ -0,0 +1,54 @@
+# LSFX Mock 数据库身份绑定实施计划
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让 `lsfx-mock-server` 在创建 `logId` 时从员工信息库随机选择一个员工，并读取该员工亲属，后续同一 `logId` 的流水仅使用这组数据库身份。
+
+**Architecture:** 在 Mock 服务中新增一个只读身份仓储，负责从 `ccdi_base_staff` 与 `ccdi_staff_fmy_relation` 读取员工及亲属。`FileService` 在创建 `FileRecord` 时写入选中的员工/亲属身份，`StatementService` 只复用该记录中的证件号，不再依赖内置固定身份证池。
+
+**Tech Stack:** FastAPI, Python 3.9, PyMySQL, pytest
+
+---
+
+### Task 1: 补数据库身份绑定失败测试
+
+**Files:**
+- Modify: `lsfx-mock-server/tests/test_file_service.py`
+- Modify: `lsfx-mock-server/tests/test_statement_service.py`
+
+- [ ] Step 1: 写出 `FileService` 需要保存员工与亲属身份的失败测试
+- [ ] Step 2: 运行对应测试，确认当前实现失败
+- [ ] Step 3: 写出 `StatementService` 只能使用该员工及其亲属证件号的失败测试
+- [ ] Step 4: 运行对应测试，确认当前实现失败
+
+### Task 2: 新增只读身份仓储
+
+**Files:**
+- Create: `lsfx-mock-server/services/staff_identity_repository.py`
+- Modify: `lsfx-mock-server/config/settings.py`
+- Modify: `lsfx-mock-server/requirements.txt`
+
+- [ ] Step 1: 定义员工/亲属身份查询结果结构与仓储接口
+- [ ] Step 2: 接入 MySQL 只读查询配置
+- [ ] Step 3: 实现“随机取一个有身份证号员工 + 读取该员工有效亲属”的最小查询逻辑
+- [ ] Step 4: 保持仓储可被测试替身替换
+
+### Task 3: 将 logId 与数据库身份绑定
+
+**Files:**
+- Modify: `lsfx-mock-server/services/file_service.py`
+- Modify: `lsfx-mock-server/services/statement_service.py`
+- Modify: `lsfx-mock-server/routers/api.py`
+
+- [ ] Step 1: 在 `FileRecord` 中增加员工/亲属身份字段
+- [ ] Step 2: 在上传文件与拉取行内流水时写入随机员工及其亲属
+- [ ] Step 3: 在流水生成阶段只使用 `FileRecord` 中的员工/亲属证件号
+- [ ] Step 4: 保留 deterministic fallback，但不影响真实记录链路
+
+### Task 4: 回归验证与文档沉淀
+
+**Files:**
+- Create: `docs/reports/implementation/2026-03-19-lsfx-mock-db-backed-identity-selection-fix.md`
+
+- [ ] Step 1: 运行 `lsfx-mock-server` 相关测试
+- [ ] Step 2: 记录根因、改动点和验证结果

docs/reports/implementation/2026-03-19-lsfx-mock-db-backed-identity-selection-fix.md

@@ -0,0 +1,58 @@
+# 2026-03-19 LSFX Mock 数据库身份绑定修复记录
+
+## 背景
+
+- 调整目标：一个 `logId` 需要从员工信息库随机选取一个员工身份证号，并且该员工的亲属证件号也必须从数据库读取。
+- 业务口径：同一个 `logId` 的流水证件号范围仅允许使用“该员工本人 + 该员工亲属”。
+
+## 根因
+
+- `lsfx-mock-server` 之前使用内置固定身份证池生成 `cretNo`，没有接入 `ccdi_base_staff` 和 `ccdi_staff_fmy_relation`。
+- 即使前一版已经收敛到单员工域，身份来源仍然是 mock 常量，不满足“从数据库读取员工及亲属”的要求。
+
+## 修改内容
+
+### 1. 新增只读员工身份仓储
+
+- 新增 `lsfx-mock-server/services/staff_identity_repository.py`
+- 仓储使用 `PyMySQL` 只读查询：
+  - 从 `ccdi_base_staff` 随机选取一个有身份证号的在职员工
+  - 优先选择存在有效亲属记录的员工
+  - 从 `ccdi_staff_fmy_relation` 读取该员工的有效亲属证件号
+
+### 2. FileRecord 绑定数据库身份
+
+- `lsfx-mock-server/services/file_service.py`
+  - `FileService` 支持注入身份仓储
+  - `FileRecord` 新增：
+    - `staff_name`
+    - `staff_id_card`
+    - `family_id_cards`
+  - 上传文件与拉取行内流水时，创建 `logId` 的同时写入该员工及亲属身份
+
+### 3. 流水生成只复用绑定身份
+
+- `lsfx-mock-server/services/statement_service.py`
+  - 若 `logId` 已存在真实 `FileRecord`，则流水生成阶段只使用该记录中的 `staff_id_card` 与 `family_id_cards`
+- `lsfx-mock-server/services/statement_rule_samples.py`
+  - 固定命中样本支持接收外部传入的员工/亲属证件号，避免继续依赖内置固定身份证
+
+### 4. 配置与测试
+
+- `lsfx-mock-server/config/settings.py`
+  - 从主项目 `ruoyi-admin/src/main/resources/application-dev.yml` 提取数据库连接默认值
+- `lsfx-mock-server/requirements.txt`
+  - 新增 `PyMySQL`
+- 测试层新增假仓储，避免单元/集成测试访问真实数据库
+
+## 验证结果
+
+- 执行：
+  - `cd lsfx-mock-server && python3 -m pytest tests/test_file_service.py tests/test_statement_service.py tests/integration/test_full_workflow.py -q`
+- 结果：
+  - `17 passed`
+
+## 影响说明
+
+- 本次变更仅作用于 `lsfx-mock-server`。
+- 真实运行时会按数据库随机绑定员工与亲属；测试环境仍通过假仓储保持可控与稳定。

docs/reports/implementation/2026-03-19-lsfx-mock-single-employee-scope-fix.md

@@ -0,0 +1,42 @@
+# 2026-03-19 LSFX Mock 单员工域修复记录
+
+## 背景
+
+- 现象：新建项目后导入单个流水文件，解析完成后结果总览出现两个员工信息。
+- 预期：单个上传文件只应归属到一个员工域，结果总览最多出现该员工本人对应的一条员工信息。
+
+## 根因
+
+- `lsfx-mock-server/services/statement_rule_samples.py` 中的大额交易固定样本同时混入了两名员工及两名家属的证件号。
+- `lsfx-mock-server/services/statement_service.py` 中的随机噪声流水继续从四个证件号的全量池随机取值。
+- 因此同一个 `logId` 返回的流水天然会覆盖两个员工域，主系统按 `cret_no` 聚合后就会出现两个员工。
+
+## 修改内容
+
+### Mock 造数收敛为单员工域
+
+- 在 `lsfx-mock-server/services/statement_rule_samples.py` 新增 `IDENTITY_SCOPES`。
+- 新增 `resolve_identity_scope(log_id)` 和 `resolve_identity_cards(log_id)`，按 `logId` 稳定选择单个员工域。
+- 将固定命中样本从“跨两个员工域混用”改为“只使用当前员工域的员工本人及家属”。
+
+### 随机噪声不再污染其他员工
+
+- 在 `lsfx-mock-server/services/statement_service.py` 中改为按 `logId` 读取允许的证件号范围。
+- 随机噪声流水的 `cretNo` 仅能从当前员工域的两张证件号中选择。
+
+### 测试补充
+
+- 在 `lsfx-mock-server/tests/test_statement_service.py` 增加“同一 `logId` 只能落在单一员工域”测试。
+- 调整大额交易样本测试，改为基于 `resolve_identity_scope(log_id)` 校验，避免继续依赖固定第二名员工。
+
+## 验证结果
+
+- 执行：
+  - `cd lsfx-mock-server && python3 -m pytest tests/test_statement_service.py tests/test_file_service.py tests/integration/test_full_workflow.py -q`
+- 结果：
+  - `17 passed`
+
+## 影响说明
+
+- 本次只修改 `lsfx-mock-server` 的 mock 造数逻辑，不影响主系统 Java/Vue 代码。
+- 已存在库中的历史测试项目数据不会自动回写；如需验证页面结果，需要重启 mock 服务后重新上传文件生成新流水。