GaoYiYuan_0626
497cee289f
背景：交接文档的定位是「给 AI 接手用的入口」，此前三份分散（项目根 交接文档.md
+ docs/交接文档-基金转换.md + docs/交接文档-架构改进.md），且 docs/ 两份停留在旧版
（v1.0 / v1.1，不含 T-0~T-2b、609 passed、D20 实施等进度），新会话极易被误导。
改动：
- 三份合并为项目根 交接文档.md v3.0（545 行 = §0 公共层 + §A 风控主线 + §B 基金转换线
+ §C 架构改进线）；该文件在 .gitignore:47 内，按用户要求不入库（交接文档只留本地）
- 全仓指向统一到 交接文档.md §A/§B/§C：AGENTS.md（含顶部新增「接手先读交接文档.md」）、
docs/memory/{MEMORY,TODO,FRAMEWORK,ITERATION}、PRD-架构改进与稳定性加固、
开发计划-架构改进、TODO-架构改进、开发计划-基金转换交易
- 两份 docs/交接文档-*.md 加「已废弃（2026-09-10）· 勿读」横幅并指向新入口，
保留作历史留档（不删除）
- 记录事故：对 docs/ 下中文名文件使用 git rm 会静默抹除整个 docs/ 目录（复现 2 次、
退出码 0），已零损失恢复；纪律写入 交接文档.md §0.4 与工作区记忆
无代码改动；pytest 609 passed / 3 skipped。
25 lines
13 KiB
Markdown
25 lines
13 KiB
Markdown
# 需求迭代
|
||
|
||
| 日期 | 变更 | 原因 | 影响 |
|
||
| --- | --- | --- | --- |
|
||
| 2026-09-05 | init 项目记忆 + app 脚手架 | 用户要求 memory kit + 目录结构 | MEMORY / ENVIRONMENT / REQUIREMENTS / FRAMEWORK / FLOW / TODO |
|
||
| 2026-09-05 | 需求拆解四 Agent P0 场景定稿 | 用户故事归纳 | REQUIREMENTS（对照 docs/需求拆解/） |
|
||
| 2026-09-05 | 技术栈 Windows 原生 + Milvus Lite | 本机内存限制 | FRAMEWORK |
|
||
| 2026-09-05 | Core 模拟库 jinrong_core + 扩大种子 + Neo4j 同步 | 无真实 Core | FRAMEWORK / FLOW / ENVIRONMENT |
|
||
| 2026-09-05 | Agent 编排依赖改为 LangGraph 为主 | 状态图 + Tool 节点 | FRAMEWORK |
|
||
| 2026-09-05 | memory 全量刷新：§0 新 Agent 交接清单 + 实现状态表 + bootstrap | 脚手架已落地，便于无上下文交接 | MEMORY / FRAMEWORK / FLOW / TODO / REQUIREMENTS / ENVIRONMENT |
|
||
| 2026-09-07 | 追加需求 FR-8/FR-9/FR-10 经独立 AI 评审→修订→复审并入 PRD v1.1 + 规则表 v1.1 + 开发计划 v1.2（C4~C6 任务 + 挂账 #1~#9） | 弥补单笔合规盲区/处置时效红线/代理人操作风险 | PRD / 附-风控规则表 / 开发计划 |
|
||
| 2026-09-07 | 《实现方案-风控追加需求v1.1-C4C6.md》定稿：独立 AI 评审 FAIL（P0×1/P1×4/P2×6）→ 修订闭环；C4~C6 编码依据可照抄 | 开发流程第 2 步（另一 AI 验证挑毛病） | 实现方案文档 |
|
||
| 2026-09-07 | 全库文档同步：分支口径修正（`feature/risk` → 实况 `risk-control-agent`，与 main 分叉 67/4）+ T-21 评审闭环 / 425 绿 / T-03 / C1~C3 状态落账 + 新建项目根交接文档.md | 文档与实况不一致（用户排查要求） | MEMORY / TODO / REQUIREMENTS / FRAMEWORK / FLOW / ENVIRONMENT / ITERATION / PRD / 架构设计 / 开发计划 / README / 交接文档 |
|
||
| 2026-09-07 | **阶段一「对齐 main 基准」AL-01~AL-08 完成**（逐项独立 commit bb244f4~b5fd52e）：SUIT-001~008 换核为 core_ro.check_suitability（C×R 矩阵 + match_result 五值 + JR-AST/FM 契约）· risk_suitability_log 重建 21 列 · Core 表 is_hnw/风评 expires_at 七新列 · 种子 33 客户/14 产品 · 全量 **406 passed 0 failed 0 skipped**（425→406，SUIT 测试重写）· uvicorn 冒烟三端点通过 · risk-m1 补打（3c07de6）· 六项拍板全落定 | 阶段一执行（用户拍板 main = 需求唯一基准）；基线变更与 SUIT 体系退役需落账 | MEMORY / TODO / REQUIREMENTS / FRAMEWORK / FLOW / ENVIRONMENT / ITERATION / README / 交接文档 |
|
||
| 2026-09-08 | 前端接入面交付：**方案 B** 会话管理三端点（`8328c24`）+ **方案 C** SSE 流式对话（`01ec5fc`），测试 482→**503 绿** | 前端 React 多 Agent 入口需后端接入面先就绪（用户拍板方案 B+C） | chat.py / session_repository / agent_service / 测试 / README / 交接文档 |
|
||
| 2026-09-09 | **架构改进与稳定性加固 T-101~T-202**：Redis 双层分布式锁（T-201）+ 无 key 启动告警（T-107）+ 审计 trace 顺序守卫（T-202）+ 文档口径勘误（词表 45 / Tool 5 / Agent 表 6）；pytest 503→**510 绿**（+7）；接口契约与表结构零变更 | 架构梳理发现 24 项待处理，两轮独立审核通过；用户拍板「补告警 + 换 Redis 锁」；合并 main 前只做低风险项 | 交接文档-架构改进 / 架构设计-风控模块 / MEMORY / 开发计划-架构改进 / TODO / 测试 +7 |
|
||
| 2026-09-10 | **架构改进线收尾闭环**：§7.2 七项手工冒烟补跑 **7/7 PASS**（无 key 告警 / 交易阻断放行 / 预警聚合 / Redis 降级退回进程内锁 / Redis 恢复零降级 / 调换装饰器使 T-202 守卫变红后字节级还原）；**核实并纠正「`037ce7e` 未 push」的过期表述**（远程 `risk-control-agent` = `fffb78a` = 本地 HEAD，早已推送）；冒烟残留按 SOP §2 重灌双库清除，全量 **510 passed** 复绿 | 架构改进线唯一缺口是手工冒烟未执行；交接文档/项目记忆的 push 状态与实际 git 状态不符（以 `git ls-remote` 为准） | TODO-架构改进 / 交接文档-架构改进 / 交接文档-基金转换 / MEMORY / TODO / ITERATION / 当日日志 |
|
||
| 2026-09-10 | **基金转换（convert）线设计闭环**：PRD **v0.9**（33 条外审闭环）+ 架构 **v1.0**（独立评审通过，13 条建议 **0 悬空**）+ 执行期风险 5 条 + **D18/D19/D20**；**DB 账号分离定案**（用户拍板「按真实项目走」，接主架构 C1）；**新建 `docs/交接文档-基金转换.md`** | `PRD-风控监测Agent` FR-1 一期显式拒收 convert，需放开；合规口径须外部事实核验（证监会公告〔2025〕22 号）；账号方案为跨线交叉点 | PRD-基金转换 / 架构设计-基金转换 / 评审待办 / 处置表 / **交接文档-基金转换（新）** / MEMORY / TODO / 交接文档.md / 交接文档-架构改进 / 开发计划-架构改进 |
|
||
| 2026-09-10 | **基金转换（convert）线第 4 步开发计划闭环**：产出 `docs/项目框架设计/开发计划-基金转换交易.md`（**v1.0，1,047 行**，T-0~T-13 逐任务改法 + DoD + §0 速览 + §1.4 **十五条代码事实核对表** + §1.5 **七条实现级裁定 R-a~R-g** + §12 **十六条回归面** + §13 PRD 19 条验收映射 + §14 实现级风险表）；**经四轮独立子代理审核收敛：12 条 → 接受 11 / 驳回 1（附实测证据）/ 0 悬空**（一轮补 R15 真 MySQL 集成用例 `test_integration_risk.py:426-437` + R16 redeem 用例 + **R-c 拆「降级规则 + 覆盖率补偿」双条** + F-11 计数 11→13；二轮抓出 **R-a 并发论证不成立**——执行权锁是**请求粒度** → 增第 ③ 步 `IntegrityError` 回退 + T-6 并发用例；三轮修 §14「四道→五道」口径不一致 + **实测驳回**「SQLAlchemy 会抛 `PendingRollbackError`」的推测；四轮终验通过、无「声明已改实际未改」残留）；**三项实测加固**（sqlite 3.50.4 不支持 `ON DUPLICATE KEY UPDATE`，且 `WHERE NOT EXISTS`/`FROM DUAL` 两个候选写法**方言互斥**；SQLAlchemy 2.0.51 异常后同事务可用；pydantic 2.13.4 `Optional+gt` 保 422） | AIcoding 第 4 步；用户要求「写完拉起子进程审核，改完后再审，审到没问题才能进行下一步」；架构/PRD 存在 2 处口径不一致需裁定（W-1/W-2），且实现级空白 7 处需收口 | 开发计划-基金转换交易（新） / 交接文档-基金转换（v1.2） / MEMORY / TODO / ITERATION / skill `ai-coding-step4-dev-plan`（新） |
|
||
| 2026-09-10 | **基金转换线：T-0 / T-0b / T-1 落地 + PRD 费率分类修正（v0.9 → v0.9.1）**：**T-0** sqlite/MySQL 结构对齐（`core_holding` 列名+PK、补 `core_product_nav`）+ 建库自校验 · **T-0b** DB 账号分离 D20（`xh_core_ro` / `xh_core_rw` / `xh_agent_rw`）· **T-1** 数据层（`core_fee_rule`、`core_share_lot`、`core_convert_lot_detail`、`risk_convert_detail` 四表 + `07-seed-fee-rule` / `08-seed-share-lot` / `09-seed-org` 三个种子 + reset 链），全量 **516 passed / 3 skipped**（批 0 后基线，零回归），T-1 数据层断言 **8/8 PASS**；**外审漏网的费率分类错误修正**——`PROD-005827` 由「主动偏股 0.0080」归位「其他混合型 0.0050」（22 号文 §8 分档），主示例转入方改真主动偏股 `PROD-003095`，`09-seed-org` 按真实「管理人全产品线」重排为 v1.1 | 用户驳回「那是两种类型，怎么能混呢？」并强调「按真实业务走，强调很多遍了，这个项目要贴近真实，是要上线的」；根因是**五轮评审只做内部自洽核对，从未做「产品类型 ↔ 费率档」匹配核对** | PRD-基金转换（v0.9.1） / 开发计划-基金转换交易 / 交接文档-基金转换（v1.3） / 架构设计-基金转换交易 / AGENTS.md / `09-seed-org.sql`（v1.1） / `verify_convert_seed.py` / MEMORY（自检第 11、12 问） / TODO / FRAMEWORK |
|
||
| 2026-09-10 | **基金转换线 T-2（纯函数包）+ T-2b（实算回填）完成**：新增 `app/service/convert/` **7 文件**（`__init__` / `types`（frozen dataclass + 3 归一工具）/ `calc` / `fee` / `nav` / `lot_bootstrap` / `errors`（`ConvertError` + **11** 子类））+ 新增 `tests/test_convert_calc.py` **93 用例**（12 类，含 **HALF_UP 反向自证**与**纯函数零 IO 依赖断言**，把 DoD 的「人工 grep」升级为硬断言）；**重写 `scripts/dev/calc_convert_demo.py`** —— 去掉脚本内公式副本、改调生产 `calc.py`、末尾 15 项自校验（不一致即退出码 1），使其兼作「PRD §5.3 ↔ 生产口径」一致性门禁；新增实现级裁定 **R-h**（`plan_lots` 零剩余不触发强制处置）；两处文档计数差异已留痕（异常实为 11 个而非 8 个 / 架构 §7 补 `hold_days`·`rounding_diff`·`ensure_batch_limit` 三签名）；全量 **609 passed / 3 skipped**（516 → +93，零回归） | 用户「继续推进到结束」；T-2 是并行组 A（T-3/T-4/T-5）与 T-2b 的唯一前置；原实算脚本自带公式副本 = 与 D18 同类的漂移风险 | 开发计划-基金转换交易（§1.5 R-h + §4.2/§4.3 执行记录 + DoD 勾选） / 架构设计-基金转换交易（§7 签名回填 · §8.3 `FEE_RULE_MISSING` 注 · §15 T-2 完成） / PRD-基金转换（§5.3 数值来源） / 交接文档-基金转换（v1.4） / AGENTS.md / `app/service/convert/*`（新） / `tests/test_convert_calc.py`（新） / `scripts/dev/calc_convert_demo.py` / MEMORY / TODO / FRAMEWORK / ITERATION |
|
||
| 2026-09-10 | **基金转换线第 5 步开工 · 第 0 批门禁 T-0 + T-0b 完成**：基线 510 → **516 passed / 3 skipped**。**T-0**：`tests/_ddl.py` 重写 `core_holding`（`qty`/`cost_amount`/`as_of`/`pnl_pct` + PK + `uk_cust_product`）+ 新增 `core_product_nav` + `_assert_ddl_aligned()` 建库自校验；2 处测试 INSERT 改 `qty` **并补 3 个 NOT NULL 列**（**原计划漏项**）；`test_db.py` +3 用例（含**门禁反向验证的自动化用例**）。**T-0b（D20 账号分离）**：新增 `scripts/core/00-grant.sql`（3 账号逐表授权，不进 reset.ps1）；`settings.py` +6 项；`db.py` `get_engine(db, role)` + `_resolve_credentials`（缓存键 `(db, role)`，未配置回退 `mysql_user`）；`core_ro`→`ro` / `gateway_repository`→`rw` / `risk_repository`·`session_repository`→`rw` 显式；`conftest.py` 4 处→`admin`（R-e）。**两处口径修正**：① `audit_log` 实授 **`SELECT, INSERT`**（字面「只授 INSERT」会连读一起剥夺，致 `has_engine_error_audit`/`list_audit_events` 失权）② conftest 必须 admin。**遗留环境操作**：`00-grant.sql` 需管理员执行 + 写 `.env`（3 条权限断言未配置时自动 skip） | AIcoding 第 5 步（T-0/T-0b 为阻断前置）；用户「你进行下一步」 | tests/_ddl.py · tests/test_db.py · tests/conftest.py · tests/test_chat_tools.py · tests/test_concentration_c4.py · app/utils/db.py · app/config/settings.py · 4 个 Repository · **scripts/core/00-grant.sql（新）** · 开发计划-基金转换（§3.3） · 架构设计-基金转换（§11.1 实施记录） · 交接文档-基金转换（v1.2） · MEMORY / TODO / 当日日志 |
|
||
| 2026-09-10 | **交接文档合并为单一入口 + 全仓指向统一**：三份交接文档合并为项目根 `交接文档.md`（**v3.0**，545 行）—— **§0 公共层** + **§A 风控模块主线** + **§B 基金转换线**（含工作区最新版 v1.4：T-0~T-2b 完成 / 609 passed）+ **§C 架构改进线**（含工作区最新版 v1.2：结项态 / 7/7 冒烟）。**全仓 10 处指向统一改到 `交接文档.md` §A/§B/§C**（`AGENTS.md` · `docs/memory/{MEMORY,TODO,FRAMEWORK}` · `PRD-架构改进与稳定性加固` · `开发计划-架构改进` · `TODO-架构改进` · `开发计划-基金转换交易`）；两份 `docs/交接文档-*.md` **保留为历史留档并加醒目「已废弃·勿读」横幅**（未删除）。⚠️ `交接文档.md` 在 `.gitignore:47` 内、**不入库**（用户 2026-09-10 明确「不进提交」，交接文档只留本地） | 用户「统一一下，不是早都说过交接文档是给你 AI 接手用的吗」—— 交接文档的定位是 **AI 接手入口**，因此全仓指向必须唯一且不可指向过期文件，否则新会话会被误导到旧版（`docs/` 两份留档停在 v1.0/v1.1，不含 T-2/T-2b 等进度） | `交接文档.md`（**v3.0**，未入库） · `AGENTS.md` · `docs/memory/{MEMORY,TODO,FRAMEWORK,ITERATION}` · `PRD-架构改进与稳定性加固` · `开发计划-架构改进` · `TODO-架构改进` · `开发计划-基金转换交易` · `docs/交接文档-基金转换.md` / `docs/交接文档-架构改进.md`（加废弃横幅，保留留档） |
|
||
| 2026-09-10 | **【事故·已恢复】`git rm` 会静默抹除整个 `docs/` 目录**：对 `docs/` 下两个中文名文件执行 `git rm`（带不带 `-f` 均如此）→ **`docs/` 全部 54 个文件从工作区消失**，且**返回退出码 0 不报错**（**复现 2 次**）。已排除中文路径（同路径 `ls` 正常）与自定义 hooks（`core.hooksPath` 空）→ **触发条件即 `git rm` 本身**，根因未查明。**零内容丢失**：`git checkout HEAD -- docs/` 完整还原 54 文件。改判：删文件用**纯 `rm -f <精确路径>`** + `git add -A` | 工具链缺陷（Git Bash on Windows + 中文名路径）；教训：批量删除后必须立即复核文件数，异常立即从 HEAD 还原 | `docs/`（还原） · 规避纪律写入 `交接文档.md` §0.4 第 10 条 + `.workbuddy/memory/MEMORY.md` |
|