基金转换 T-11：工具与 SQL 汇总去重（FR-C15 / R-d）

convert 在 core_trade 落两条流水（转出 redeem + 转入 subscribe，共享 convert_group_id），所有金额聚合读取方必须只计一次，否则同笔转换金额翻倍。落地（改码 3 处 + 新增 1 脚本 + 测试 3 文件） - rules.py：_amount_view → 公开 amount_view（提升而非复制别名，全仓唯一金额聚合口径）； docstring 补「跨模块共用」说明 - core_tools.py：query_recent_trades 的 sum_amount 改走 amount_view（FR-C15）； items / total_count 保持全量不变——两条流水是真实的两笔权益变动，读到两条是对的 - core_ro.py：list_holdings 加 h.qty > 0（convert 转出全部份额留下的 qty=0 归零行不是持仓）； sum_trades_on_date 加 convert 去重条件（R-d），组内只计转出端 - 新增 tests/test_core_tools.py（3 条：汇总不翻倍 / 跨口径一致性 / 持仓不返回 qty=0 行） - tests/test_core_ro_sum.py 追加 1 条 convert 去重用例（既有断言零改动） - 新增 scripts/dev/verify_convert_tools.py：真库验证脚本（MySQL 8.0.46）执行期裁定 2 条（已留痕） - _amount_view 提升为公开而非复制：一个函数两个名字会漂移（自检第 13 问） - SQL 条件从 IS NULL 扩为 IS NULL OR = ''：Python 的 if not gid 把空串当无组，而 SQL 里 '' IS NULL 恒假。真库实证：只写 IS NULL → 合计数 400000（正确 450000，漏算 50000）。不加则 RISK-002 漏算，且 sqlite 单测若只造 NULL 数据永远发现不了 - 等价性边界：组内无 redeem 时 SQL 丢整组、amount_view 保留首条；由 R-b 保证不可达验证 - pytest -q → 718 passed / 3 skipped（基线 714 加 4，零回归） - 突变验证 3 组均精准命中：去掉去重条件（2 红）/ 去掉 qty>0（1 红）/ 汇总不走 amount_view（2 红） - 真库 verify_convert_tools.py 14/14，隔离数据零残留 - 复跑受影响真库脚本零回归：T-8 31/31、T-7 35/35、T-10 20/20
2026-09-10 18:40:27 +08:00
parent 5c2dc94b40
commit a6ac39edd6
12 changed files with 562 additions and 31 deletions
@@ -7,7 +7,7 @@

 **阶段一 AL-01~AL-08 与阶段二 C4~C6 均已完成（2026-09-07）**：全量 pytest **482 passed 0 failed 0 skipped**（真库集成）✓ · uvicorn 冒烟三端点 ✓ · 接口实调验收 ✓（2026-09-07：suitability/check 阻断+放行、simulate/trade 阻断、三条鉴权边界 401/403/403，契约零偏差）· risk-m1~m4 tag 齐。**合并 main 已移交合并执行人**（操作手册：《docs/项目框架设计/合并注意事项-风控模块并入main.md》，随分支上传），后续模块侧待办见下方。

-**⚡ 并行新线 · 基金转换（convert）**（2026-09-10）：**设计 + 开发计划均已闭环** —— PRD **v0.9.2** + 架构 **v1.0.1** + 独立评审 13 条 **0 悬空**（接受 10 / 修正性接受 3 / 驳回 0），门控 **M-7 已满足**；**第 4 步开发计划 v1.0 已产出并经独立审核**（4 条意见全接受、**驳回 0**，含新增 2 条回归面 R15/R16 + R-c 双条修订）；**第 5 步进行中**：**T-0 ~ T-10 均已于 2026-09-10 完成**（**714 passed / 3 skipped**；T-1 断言 **8/8 PASS**、T-2 纯函数 **93 用例**、T-2b 实算 **15/15 一致**、T-6 真库 **24/24**、T-7 真库 **35/35**、**T-8 真库 31/31**、**T-9 真 MySQL 集成 8 条 + 4 组突变验证 + 展示位数修复**、**T-10 新增 17 用例 + 真库 20/20 + 2 组突变验证**），**下一步 = T-11（`core_tools` 与 `sum_trades_on_date` 汇总去重 · 依赖 T-8 已解锁）**。两个阻断前置（**T-0** sqlite/MySQL 列名统一 + 建库自校验 · **T-0b** DB 账号分离 D20：`xh_core_ro`/`xh_core_rw`/`xh_agent_rw`）**均已落地**。**入口：项目根 `交接文档.md` §B（三线合并版唯一入口，读这一节即可开工）**；**开工前必读开发计划 §1.4（15 条代码事实）+ §1.5（8 条实现级裁定 R-a~R-h）+ §12（16 条回归面）**。
+**⚡ 并行新线 · 基金转换（convert）**（2026-09-10）：**设计 + 开发计划均已闭环** —— PRD **v0.9.2** + 架构 **v1.0.1** + 独立评审 13 条 **0 悬空**（接受 10 / 修正性接受 3 / 驳回 0），门控 **M-7 已满足**；**第 4 步开发计划 v1.0 已产出并经独立审核**（4 条意见全接受、**驳回 0**，含新增 2 条回归面 R15/R16 + R-c 双条修订）；**第 5 步进行中**：**T-0 ~ T-11 均已于 2026-09-10 完成**（**718 passed / 3 skipped**；T-1 断言 **8/8 PASS**、T-2 纯函数 **93 用例**、T-2b 实算 **15/15 一致**、T-6 真库 **24/24**、T-7 真库 **35/35**、**T-8 真库 31/31**、**T-9 真 MySQL 集成 8 条 + 4 组突变验证 + 展示位数修复**、**T-10 新增 17 用例 + 真库 20/20 + 2 组突变验证**、**T-11 新增 4 用例 + 真库 14/14 + 3 组突变验证 · `amount_view` 提升为公开**），**下一步 = T-12（补偿脚本）**。两个阻断前置（**T-0** sqlite/MySQL 列名统一 + 建库自校验 · **T-0b** DB 账号分离 D20：`xh_core_ro`/`xh_core_rw`/`xh_agent_rw`）**均已落地**。**入口：项目根 `交接文档.md` §B（三线合并版唯一入口，读这一节即可开工）**；**开工前必读开发计划 §1.4（15 条代码事实）+ §1.5（8 条实现级裁定 R-a~R-h）+ §12（16 条回归面）**。

 ### 基金转换线待办（推荐顺序）

@@ -17,11 +17,14 @@
 - [x] **【T-1 · 第 1 批】DDL + 种子 + sqlite 同步** —— **完成（2026-09-10）**：`scripts/core/01-ddl.sql` 新建 `core_fee_rule`/`core_share_lot`/`core_convert_lot_detail` + `core_trade` 加 `convert_group_id`+索引 + `core_product` 加 8 列（`subscribe_fee_rate` 等）+ `fee_rate` 补 COMMENT；**新增 `07-seed-fee-rule.sql`**（14 产品 × 5 档，按 22 号文 §10）/ **`08-seed-share-lot.sql`**（58 行持仓 → 61 行批次，Σ remain_qty 恒等于 qty，CUST-9527 跨批次）/ **`09-seed-org.sql`**（管理人 + TA + 申购费率 + 最低持有余额）；`reset.ps1` 追加 07/08/09；`02-mysql-agent专用.sql` 追加 `risk_convert_detail`（status ENUM 建表即 5 值）；`tests/_ddl.py` 同步 4 表 + `REQUIRED_CONVERT_TABLES` 门禁。**验证**：新增 `scripts/dev/verify_convert_seed.py`（pymysql 等价 reset 流程 + 8 条断言）→ **8/8 PASS**；`pytest -q` → **516 passed / 3 skipped（零回归）**。**3 点需注意**：① mysql 不在 PATH → 用该脚本替代 reset.ps1；② `core_fee_rule` 读取走只读账号（T-6 遵守）；③ ~~`PROD-005827` 费率分类口径差异（`mixed` vs 主动偏股）待裁定~~ → **已裁定并修正（PRD v0.9.1）**：`mixed` 归位 `0.0050`（其他混合型），主示例转入方改真主动偏股 `PROD-003095`，`09-seed-org.sql` 升 **v1.1** 按「管理人全产品线」重排，并新增断言 ⑧ 机器化卡口
 - [x] **【T-2 · 第 2 批】`service/convert/` 纯函数包** —— **完成（2026-09-10）**：新建 `app/service/convert/` **7 文件**（`__init__` / `types`（`Lot`/`FeeRule`/`LotAllocation`/`PlanResult` frozen dataclass + 3 个归一工具）/ `calc`（`plan_lots`/`lot_amount`/`lot_fee`/`convert_amount`/`in_qty`/`rounding_diff`/`diff_fee`/`hold_days`/`ensure_batch_limit`）/ `fee`（`pick_fee_rate` 左闭右开）/ `nav`（`ensure_nav_ready`→503 / `is_stale`）/ `lot_bootstrap`（D18 单点，`crc32` 确定性偏移）/ `errors`（`ConvertError` + 11 子类））。**新增 `tests/test_convert_calc.py` 93 用例**（12 类：精度 HALF_UP 反向自证 / 分档边界 6-7-29-30-179-180-364-365 / FIFO 含同 `confirmed_at` tiebreak / 跨批计费 / 双口径 252.40 vs 253.91 / 强制全转与强制赎回 / 恰好等于阈值不触发 / **零剩余不触发（新裁定 R-h）** / PRD §5.3 全链自证 / T+1 起算 / 净值 503 与 stale 分家 / D18 确定性 / §8.3 错误码 / **纯函数零 IO 依赖断言**）。**验证**：`pytest -q` → **609 passed / 3 skipped（+93，零回归）**；`calc_convert_demo.py` → **15/15 与 PRD §5.3 一致**（退出码 0）
 - [x] **【T-3 ~ T-9 已完成】** 仓储与锁（并行组 A：T-3 / T-4 / T-5 ✅）→ T-6 ✅（阶段一事务 · 真库 24/24）→ T-7 ✅（八步编排 · 真库 35/35）→ **T-8 ✅（规则引擎改造 · 真库 31/31；⭐ 阶段 1.5 从「跳过」变「真跑」）** → **T-9 ✅（API 模型 + 网关分派 · **HTTP 层 convert 已走通**；新增真 MySQL 集成 7 条 + 11 条错误码映射 + 3 组突变验证）**
- [ ] **【T-10 起】剩余任务**：**T-10 高风险单列**（普通申赎批次维护 · 改 `trade_gateway` 主流程 · 先跑基线再动）→ T-11（`core_tools` / `sum_trades_on_date` 汇总去重）→ T-12（补偿脚本）→ **T-13「50 并发压测 + 性能补录」**（最后跑，产出 PRD §9 第 18 条实测值）。**T-13 内部顺序**：先 50 并发压测 → 再性能实测补录 → 最后 PRD §5.3 数字回填（详见架构 §15 + 开发计划 §2~§10）
+- [x] **【T-10 ✅ · T-11 ✅】均已结项（2026-09-10）**：**T-10** 普通申赎批次维护（改 `trade_gateway` 主流程 + D8 兜底补建 + `rebuild_lots.py`；**+17 用例** · 真库 20/20 · 突变 2 组 · R16 零改动通过）→ **T-11** 工具与 SQL 汇总去重（`_amount_view` **提升为公开 `amount_view`** + `query_recent_trades` 汇总去重 FR-C15 + `list_holdings` 过滤 `qty > 0` + `sum_trades_on_date` 加 convert 去重 **R-d**；**+4 用例** · 真库 14/14 · 突变 3 组）
+- [ ] **【T-12 起】剩余任务**：**T-12（补偿脚本）→ T-13「50 并发压测 + 性能补录」**（最后跑，产出 PRD §9 第 18 条实测值）。**T-13 内部顺序**：先 50 并发压测 → 再性能实测补录 → 最后 PRD §5.3 数字回填（详见架构 §15 + 开发计划 §2~§10）
 - [ ] **【待用户裁定】幂等重放响应的数值位数偏差**（T-9 执行期发现，**未顺手改**）：首次响应 2 位（`calc` 量化）vs 重放响应 4 位（`core_trade` `DECIMAL(18,4)` 直读）→ `"53456.95"` vs `"53456.9500"`，**数值相等**，违反 PRD「对外一律 2 位」展示契约，属 T-7 `_rebuild_quote` 范畴。集成测试已「比数值不比字符串」并钉住偏差

 > **第 0~2 批结果（2026-09-10）**：基线 **510 passed** → 批 0 后 **516 passed / 3 skipped**（+3 T-0 用例 +3 T-0b 引擎用例）→ 批 1（T-1）后**仍 516 passed / 3 skipped**（只加表与种子，未加用例 → **零回归**）；**T-1 数据层断言 8/8 PASS**（含新增断言 ⑧：费率档 ↔ `product_type` 匹配，越档即 FAIL）→ 批 2（T-2 + T-2b）后 **609 passed / 3 skipped**（**+93 纯函数用例**，零回归）；T-2b 实算脚本 15/15 与 PRD §5.3 一致（退出码 0）。
-> **下一步 = T-11**（`core_tools.query_recent_trades` 汇总走 `_amount_view` 去重 FR-C15 + 持仓查询过滤 `qty <= 0` + `core_ro.sum_trades_on_date` 加 convert 去重条件 **R-d**；DoD 见开发计划 §7.3）。基线 **714 passed / 3 skipped**。
+> **下一步 = T-12**（补偿脚本，开发计划 §9）。基线 **718 passed / 3 skipped**（T-10 后 714 → **T-11 后 718**，+4）。
+> **T-11 执行期两条裁定**：① `_amount_view` **提升为公开 `amount_view`**（跨层复用，全仓唯一金额聚合口径）；
+> ② SQL 去重条件从计划的 `IS NULL` 扩为 **`IS NULL OR convert_group_id = ''`** —— 真库实证「只写 `IS NULL` 会漏掉空串那笔」（400000 vs 450000，差 50000）。

 > ⚠️ **基金转换的 T-0b 与下方「架构改进第 3/4 批」的 `core_ro` 只读账号是同一件事** —— 已由本线定案为 D20，**不再挂在架构改进线**（该线原「不要做」清单已更新）。