补充LSFX Mock大额交易实施计划

docs/plans/backend/2026-03-18-lsfx-mock-large-transaction-backend-implementation.md

@@ -0,0 +1,421 @@
+# LSFX Mock Large Transaction Backend Implementation Plan
+
+> **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` 的分页流水稳定包含可命中后端大额交易 8 条规则的样本，同时保留随机噪声流水。
+
+**Architecture:** 在 `lsfx-mock-server` 内新增独立的大额交易样本生成模块，维护默认身份池、阈值常量与 5 组规则样本簇；`statement_service.py` 负责调用样本生成器、补足噪声流水、统一分配流水 ID 并缓存分页结果；测试分成样本生成测试和 API 返回测试两层，最后补一份实施记录文档。
+
+**Tech Stack:** Python 3, FastAPI, pytest, httpx TestClient
+
+---
+
+### Task 1: 固化样本生成边界与文件结构
+
+**Files:**
+- Create: `lsfx-mock-server/services/statement_rule_samples.py`
+- Modify: `lsfx-mock-server/services/statement_service.py`
+- Test: `lsfx-mock-server/tests/test_statement_service.py`
+
+- [ ] **Step 1: Write the failing test**
+
+先新增一个最小单测，约束后续服务层会调用“命中样本 + 噪声流水”两段式生成，而不是继续只走单条完全随机逻辑：
+
+```python
+from services.statement_service import StatementService
+
+
+def test_generate_statements_should_include_seeded_samples_before_noise():
+    service = StatementService()
+
+    statements = service._generate_statements(group_id=1000, log_id=20001, count=30)
+
+    assert len(statements) >= 30
+    assert any(item["userMemo"] == "购买房产首付款" for item in statements)
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_statement_service.py -k seeded_samples -v
+```
+
+Expected:
+
+- `FAIL`
+- 原因是 `tests/test_statement_service.py` 尚不存在，且 `StatementService` 还没有命中样本生成能力
+
+- [ ] **Step 3: Write minimal implementation**
+
+先搭文件骨架和最小接口，不一次性塞完整逻辑，但要保证首个样本断言可以通过：
+
+```python
+# lsfx-mock-server/services/statement_rule_samples.py
+DEFAULT_LARGE_TRANSACTION_THRESHOLDS = {
+    "SINGLE_TRANSACTION_AMOUNT": 1111,
+    "CUMULATIVE_TRANSACTION_AMOUNT": 50000001,
+    "ANNUAL_TURNOVER": 50000001,
+    "LARGE_CASH_DEPOSIT": 2000001,
+    "FREQUENT_CASH_DEPOSIT": 5,
+    "FREQUENT_TRANSFER": 100001,
+}
+
+
+def build_large_transaction_seed_statements(group_id: int, log_id: int) -> list[dict]:
+    return [
+        {
+            "groupId": group_id,
+            "batchId": log_id,
+            "userMemo": "购买房产首付款",
+            "customerName": "杭州贝壳房地产经纪有限公司",
+            "drAmount": 680000.0,
+            "crAmount": 0.0,
+            "cashType": "对公转账",
+            "cretNo": "330101198801010011",
+        }
+    ]
+```
+
+```python
+# lsfx-mock-server/services/statement_service.py
+from services.statement_rule_samples import build_large_transaction_seed_statements
+
+
+def _generate_statements(self, group_id: int, log_id: int, count: int) -> List[Dict]:
+    statements = build_large_transaction_seed_statements(group_id, log_id)
+    while len(statements) < count:
+        statements.append(self._generate_random_statement(len(statements), group_id, log_id))
+    return statements
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_statement_service.py -k seeded_samples -v
+```
+
+Expected:
+
+- `PASS`
+- 说明样本生成器与服务层的最小整合入口已经建立
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lsfx-mock-server/services/statement_rule_samples.py lsfx-mock-server/services/statement_service.py lsfx-mock-server/tests/test_statement_service.py
+git commit -m "拆分Mock大额交易样本生成骨架"
+```
+
+### Task 2: 用单元测试锁定 8 条规则样本口径
+
+**Files:**
+- Modify: `lsfx-mock-server/services/statement_rule_samples.py`
+- Test: `lsfx-mock-server/tests/test_statement_service.py`
+
+- [ ] **Step 1: Write the failing test**
+
+在 `tests/test_statement_service.py` 中补一组口径测试，至少覆盖 8 条规则的关键命中特征：
+
+```python
+from services.statement_rule_samples import build_large_transaction_seed_statements
+
+
+def test_large_transaction_seed_should_cover_all_eight_rules():
+    statements = build_large_transaction_seed_statements(group_id=1000, log_id=20001)
+
+    assert any(item["userMemo"] == "购买房产首付款" and item["drAmount"] > 0 for item in statements)
+    assert any("税" in item["userMemo"] and item["drAmount"] > 0 for item in statements)
+    assert any(item["crAmount"] > 1111 for item in statements)
+    assert len([item for item in statements if item["cashType"] == "现金存款"]) >= 1
+    assert len([item for item in statements if item["customerName"] == "浙江远望贸易有限公司"]) >= 3
+```
+
+再补几个针对性断言：
+
+- 同一身份证、同一日期，至少 6 笔 `crAmount > 2000001` 的存现样本
+- 至少 1 笔 `userMemo` 含 `手机银行转账` 且 `drAmount > 100001`
+- 所有“收入样本”都避开工资排除词
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_statement_service.py -k "eight_rules or cash_deposit or transfer" -v
+```
+
+Expected:
+
+- `FAIL`
+- 原因是样本构造函数还没有真实返回 8 条规则所需数据
+
+- [ ] **Step 3: Write minimal implementation**
+
+在 `statement_rule_samples.py` 中先把 5 组样本簇写实：
+
+```python
+IDENTITY_POOL = {
+    "staff_primary": {"name": "模型测试员工", "id_card": "330101198801010011", "account": "6222024000000001"},
+    "family_primary": {"name": "模型测试家属", "id_card": "330101199001010022", "account": "6222024000000002"},
+    "staff_secondary": {"name": "模型二测试员工", "id_card": "330101198802020033", "account": "6222024000000003"},
+    "family_secondary": {"name": "模型二测试家属", "id_card": "330101199202020044", "account": "6222024000000004"},
+}
+```
+
+```python
+def build_large_transaction_seed_statements(group_id: int, log_id: int) -> list[dict]:
+    statements = []
+    statements.extend(build_house_or_car_samples(group_id, log_id))
+    statements.extend(build_tax_samples(group_id, log_id))
+    statements.extend(build_income_samples(group_id, log_id))
+    statements.extend(build_cash_deposit_samples(group_id, log_id))
+    statements.extend(build_large_transfer_samples(group_id, log_id))
+    return statements
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_statement_service.py -v
+```
+
+Expected:
+
+- `PASS`
+- 测试输出能证明 8 条规则所需的关键样本全部存在
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lsfx-mock-server/services/statement_rule_samples.py lsfx-mock-server/tests/test_statement_service.py
+git commit -m "补充Mock大额交易八条规则样本"
+```
+
+### Task 3: 重构 StatementService 合并样本与噪声流水
+
+**Files:**
+- Modify: `lsfx-mock-server/services/statement_service.py`
+- Test: `lsfx-mock-server/tests/test_statement_service.py`
+
+- [ ] **Step 1: Write the failing test**
+
+补两个服务层测试：
+
+```python
+def test_generate_statements_should_fill_noise_up_to_requested_count():
+    service = StatementService()
+
+    statements = service._generate_statements(group_id=1000, log_id=20001, count=80)
+
+    assert len(statements) == 80
+
+
+def test_get_bank_statement_should_keep_same_cached_result_for_same_log_id():
+    service = StatementService()
+
+    page1 = service.get_bank_statement({"groupId": 1000, "logId": 30001, "pageNow": 1, "pageSize": 20})
+    page2 = service.get_bank_statement({"groupId": 1000, "logId": 30001, "pageNow": 1, "pageSize": 20})
+
+    assert page1["data"]["bankStatementList"] == page2["data"]["bankStatementList"]
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_statement_service.py -k "fill_noise or cached_result" -v
+```
+
+Expected:
+
+- `FAIL`
+- 原因是当前 `_generate_statements()` 会直接按 `count` 循环生成单条随机流水，既不保底命中样本，也没有样本与噪声的装配逻辑
+
+- [ ] **Step 3: Write minimal implementation**
+
+把 `statement_service.py` 改成以下结构：
+
+```python
+def _generate_statements(self, group_id: int, log_id: int, count: int) -> List[Dict]:
+    seed_statements = build_large_transaction_seed_statements(group_id, log_id)
+    total_count = max(count, len(seed_statements))
+    noise_count = total_count - len(seed_statements)
+
+    statements = list(seed_statements)
+    for index in range(noise_count):
+        statements.append(self._generate_random_statement(index, group_id, log_id))
+
+    statements = self._assign_statement_ids(statements, log_id)
+    random.shuffle(statements)
+    return statements
+```
+
+同时新增一个专用方法，为样本和噪声统一补齐：
+
+- `bankStatementId`
+- `bankTrxNumber`
+- `uploadSequnceNumber`
+- `batchId`
+- `groupId`
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_statement_service.py -v
+```
+
+Expected:
+
+- `PASS`
+- 同一 `logId` 首次生成后被缓存，后续分页请求不会漂移
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lsfx-mock-server/services/statement_service.py lsfx-mock-server/tests/test_statement_service.py
+git commit -m "重构Mock流水生成并保留分页缓存一致性"
+```
+
+### Task 4: 扩展 API 测试覆盖分页与命中特征
+
+**Files:**
+- Modify: `lsfx-mock-server/tests/test_api.py`
+- Modify: `lsfx-mock-server/tests/integration/test_full_workflow.py`
+
+- [ ] **Step 1: Write the failing test**
+
+在 API 层增加最小回归：
+
+```python
+def test_get_bank_statement_should_return_seed_samples(client):
+    response = client.post(
+        "/watson/api/project/getBSByLogId",
+        data={"groupId": 1000, "logId": 40001, "pageNow": 1, "pageSize": 200}
+    )
+
+    assert response.status_code == 200
+    items = response.json()["data"]["bankStatementList"]
+    assert any(item["userMemo"] == "购买房产首付款" for item in items)
+```
+
+再补一个分页拼接测试，确认把前几页拼起来后可以找到：
+
+- 税务样本
+- 至少 6 笔同日存现
+- 大额转账样本
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_api.py -k "seed_samples or bank_statement" -v
+```
+
+Expected:
+
+- `FAIL`
+- 原因是接口返回的仍是完全随机流水，无法稳定断言命中特征
+
+- [ ] **Step 3: Write minimal implementation**
+
+这里主要是补充测试，不引入新的 API 逻辑分支。若前一任务已完成，接口应天然满足这些断言；如仍失败，只允许回到 `statement_rule_samples.py` 或 `statement_service.py` 修正数据构造，不要在路由层堆业务判断。
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_api.py -v
+pytest tests/integration/test_full_workflow.py -v
+```
+
+Expected:
+
+- `PASS`
+- 现有上传、拉取、查询等主流程回归不受影响
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lsfx-mock-server/tests/test_api.py lsfx-mock-server/tests/integration/test_full_workflow.py
+git commit -m "补充Mock流水分页与命中特征回归测试"
+```
+
+### Task 5: 补实施记录并完成最终验证
+
+**Files:**
+- Create: `docs/reports/implementation/2026-03-18-lsfx-mock-large-transaction-implementation.md`
+- Modify: `docs/plans/backend/2026-03-18-lsfx-mock-large-transaction-backend-implementation.md`
+
+- [ ] **Step 1: Write the implementation report skeleton**
+
+记录以下内容：
+
+- 改动文件清单
+- 8 条规则对应的样本策略
+- 实际跑过的 pytest 命令
+- 已知约束：身份池必须存在于目标后端环境
+
+建议骨架：
+
+```markdown
+# LSFX Mock 大额交易样本实施记录
+
+## 变更概述
+- ...
+
+## 验证记录
+- `cd lsfx-mock-server && pytest tests/test_statement_service.py -v`
+- `cd lsfx-mock-server && pytest tests/test_api.py -v`
+```
+
+- [ ] **Step 2: Run final verification**
+
+Run:
+
+```bash
+cd lsfx-mock-server
+pytest tests/test_statement_service.py -v
+pytest tests/test_api.py -v
+pytest tests/integration/test_full_workflow.py -v
+python verify_implementation.py
+```
+
+Expected:
+
+- 所有测试通过
+- `verify_implementation.py` 不报接口字段缺失
+
+- [ ] **Step 3: Stop any started services**
+
+如果验证过程中启动了：
+
+- `python main.py`
+- `uvicorn main:app --reload --host 0.0.0.0 --port 8000`
+
+必须在结束时关闭对应进程，避免残留端口占用。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/reports/implementation/2026-03-18-lsfx-mock-large-transaction-implementation.md docs/plans/backend/2026-03-18-lsfx-mock-large-transaction-backend-implementation.md
+git commit -m "补充Mock大额交易样本实施记录"
+```

docs/plans/frontend/2026-03-18-lsfx-mock-large-transaction-frontend-implementation.md

@@ -0,0 +1,202 @@
+# LSFX Mock Large Transaction Frontend Implementation Plan
+
+> **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:** 在不改动现有 Vue 页面业务逻辑的前提下，完成与 LSFX Mock 大额交易样本的前端联调验证，确保项目详情中的上传、拉取本行信息和流水明细查询页面能正常展示命中样本数据。
+
+**Architecture:** 本期前端以联调验证为主，不预设页面代码改造；先锁定实际受影响的入口页面与 API，再通过构建、手工回归和验证记录确认现有组件能承接新的 Mock 流水样本；若联调中发现展示问题，再将问题回流到后端 Mock 数据字段层或单独前端修复需求。
+
+**Tech Stack:** Vue 2, Element UI, Axios request wrapper, npm, Node
+
+---
+
+### Task 1: 固化联调入口与验证记录模板
+
+**Files:**
+- Verify: `ruoyi-ui/src/views/ccdiProject/detail.vue`
+- Verify: `ruoyi-ui/src/views/ccdiProject/components/detail/UploadData.vue`
+- Verify: `ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue`
+- Verify: `ruoyi-ui/src/api/ccdiProjectUpload.js`
+- Create: `docs/tests/records/2026-03-18-lsfx-mock-large-transaction-frontend-verification.md`
+
+- [ ] **Step 1: Write the verification record skeleton**
+
+先创建前端联调记录，提前写好待验证项目：
+
+```markdown
+# LSFX Mock 大额交易前端联调记录
+
+## 验证范围
+- UploadData 拉取本行信息
+- DetailQuery 流水明细查询
+- 关键样本展示：房产首付、税款、现金存款、手机银行转账
+
+## 验证结果
+- [ ] 页面可打开
+- [ ] 列表可分页
+- [ ] 摘要和对手方可见
+```
+
+- [ ] **Step 2: Run path existence smoke check**
+
+Run:
+
+```bash
+test -f ruoyi-ui/src/views/ccdiProject/detail.vue
+test -f ruoyi-ui/src/views/ccdiProject/components/detail/UploadData.vue
+test -f ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue
+test -f ruoyi-ui/src/api/ccdiProjectUpload.js
+```
+
+Expected:
+
+- 四条命令都返回成功
+
+- [ ] **Step 3: Keep implementation minimal**
+
+本任务不改动 Vue 代码，只建立联调记录文件并确认入口路径真实存在。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/tests/records/2026-03-18-lsfx-mock-large-transaction-frontend-verification.md
+git commit -m "新增Mock大额交易前端联调记录模板"
+```
+
+### Task 2: 完成前端静态构建与入口冒烟
+
+**Files:**
+- Modify: `docs/tests/records/2026-03-18-lsfx-mock-large-transaction-frontend-verification.md`
+
+- [ ] **Step 1: Run frontend build smoke check**
+
+Run:
+
+```bash
+cd ruoyi-ui
+npm run build:prod
+```
+
+Expected:
+
+- 构建成功
+- 说明本次 Mock 数据增强不会强制触发前端源码改动
+
+- [ ] **Step 2: Run route-level smoke check**
+
+手工验证以下入口：
+
+- 项目详情页可打开
+- “上传数据”页签可打开
+- “流水明细查询”页签可打开
+- “拉取本行信息”弹窗可打开
+
+若要辅助定位，可在浏览器中重点观察：
+
+- `ruoyi-ui/src/views/ccdiProject/detail.vue`
+- `ruoyi-ui/src/views/ccdiProject/components/detail/UploadData.vue`
+- `ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue`
+
+- [ ] **Step 3: Update verification notes**
+
+把构建结果和入口检查结果记入联调记录文件。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/tests/records/2026-03-18-lsfx-mock-large-transaction-frontend-verification.md
+git commit -m "记录Mock大额交易前端构建与入口冒烟结果"
+```
+
+### Task 3: 使用新 Mock 样本验证流水明细展示
+
+**Files:**
+- Modify: `docs/tests/records/2026-03-18-lsfx-mock-large-transaction-frontend-verification.md`
+- Verify: `ruoyi-ui/src/views/ccdiProject/components/detail/DetailQuery.vue`
+- Verify: `ruoyi-ui/src/api/ccdiProjectUpload.js`
+
+- [ ] **Step 1: Prepare the manual verification checklist**
+
+围绕新样本，准备以下查询口径：
+
+- 搜索摘要 `首付款`
+- 搜索摘要 `税款`
+- 搜索摘要 `现金存款`
+- 搜索摘要 `手机银行转账`
+- 按金额倒序检查大额收入 / 大额支出是否展示正确
+
+- [ ] **Step 2: Run manual verification against the updated Mock**
+
+建议联调步骤：
+
+1. 启动后端、前端、`lsfx-mock-server`
+2. 在项目详情页执行上传或拉取本行信息
+3. 打开“流水明细查询”页签
+4. 通过关键词和排序验证新样本是否可见
+
+重点观察字段：
+
+- 交易日期
+- 收入/支出金额
+- 对手方名称
+- 用户摘要
+
+- [ ] **Step 3: Record the actual UI results**
+
+把每一类样本是否能在页面上被找到写入联调记录，例如：
+
+```markdown
+- `购买房产首付款`：可见 / 不可见
+- `个人所得税税款`：可见 / 不可见
+- `柜面现金存款`：可见 / 不可见
+- `手机银行转账`：可见 / 不可见
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/tests/records/2026-03-18-lsfx-mock-large-transaction-frontend-verification.md
+git commit -m "记录Mock大额交易流水前端明细联调结果"
+```
+
+### Task 4: 收敛前端结论并关闭验证进程
+
+**Files:**
+- Modify: `docs/tests/records/2026-03-18-lsfx-mock-large-transaction-frontend-verification.md`
+- Modify: `docs/plans/frontend/2026-03-18-lsfx-mock-large-transaction-frontend-implementation.md`
+
+- [ ] **Step 1: Summarize whether frontend code changes are required**
+
+在联调记录末尾补最终结论：
+
+- 若现有页面能正确展示新样本，则结论为“本期前端零代码改动”
+- 若页面出现字段缺失或文案异常，明确问题是 Mock 字段问题还是页面展示问题
+
+- [ ] **Step 2: Stop any started services**
+
+若本任务启动过：
+
+- `npm run dev`
+- 后端 `mvn -pl ruoyi-admin spring-boot:run`
+- Mock `python main.py` 或 `uvicorn main:app --reload --host 0.0.0.0 --port 8000`
+
+必须在验证完成后主动关闭进程，避免残留端口占用。
+
+- [ ] **Step 3: Keep implementation minimal**
+
+除非联调明确暴露真实展示缺陷，否则不提前改动 `ruoyi-ui/src` 下业务代码。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/tests/records/2026-03-18-lsfx-mock-large-transaction-frontend-verification.md docs/plans/frontend/2026-03-18-lsfx-mock-large-transaction-frontend-implementation.md
+git commit -m "补充Mock大额交易前端联调结论"
+```
+
+## Frontend Integration Conclusion
+
+本计划默认结论是“先联调验证，再决定是否改前端代码”：
+
+- 这次主变更在 `lsfx-mock-server`
+- 前端优先验证现有页面是否已经能承接增强后的流水样本
+- 只有在联调明确暴露展示问题时，才补独立前端修复任务，避免为了 Mock 数据升级而提前制造无效改动

docs/reports/implementation/2026-03-18-lsfx-mock-large-transaction-plan-record.md

@@ -0,0 +1,17 @@
+# LSFX Mock 大额交易实施计划产出记录
+
+## 变更概述
+
+- 基于已确认的设计文档，新增后端实施计划与前端实施计划各一份。
+- 后端计划聚焦 `lsfx-mock-server` 的样本生成、分页缓存、pytest 回归和实施记录。
+- 前端计划聚焦现有项目详情页对增强后 Mock 流水的联调验证，默认不做 Vue 代码改动。
+
+## 新增文件
+
+- `docs/plans/backend/2026-03-18-lsfx-mock-large-transaction-backend-implementation.md`
+- `docs/plans/frontend/2026-03-18-lsfx-mock-large-transaction-frontend-implementation.md`
+
+## 说明
+
+- 计划已按仓库约定拆为前后端两份。
+- 后续若按计划执行并产生代码改动，需要继续补实施记录与测试记录。