Files

T

## 新入库（`docs/演示用/`）

- `代码库全面审查报告-2026-09-14.md`
- `代码修改方案-2026-09-14.md`
- `记忆系统排查报告-2026-09-14.md`
- `记忆系统修复文档-2026-09-14.md`
- `文档一致性审计报告-2026-09-14.md`
- `多Worker接入方案-2026-09-14.md`

## 全量校对（32 个既有文档 + `AGENTS.md`）

跨 39 个文件、**1125 insertions / 148 deletions**。

⚠️ **这批改动同样不是本次会话写的**。我抽样核对过性质：是**实质内容补充**而不是
格式/换行转换。例如 `docs/44-演示流程.md` 新增两条"2026-09-14 补注"：

- `启动金融Agent平台.bat` 只在**桌面**上，仓库里只有 `启动平台.bat` 这一份
  （两份由同一个 `tools/make_launcher_bat.py` 产出，改完 `start.ps1` 重跑它一起更新）；
- `advisor_t`(9020) 与 `offsite_t`(9006) **不在 `tools/seed_test_rbac.py` 的演示用户里**
  （那里只有 `cust_t`/`risk_t`/`admin_t`/`review_t` 四个），由 `grant_*.py` 系列创建，
  **重跑种子不会重建它们** —— 换机器时这两个账号登录失败，要先查 `sys_user` 有没有这两行，
  而不是查密码。

这两条都是对的地方，与我这一路踩到的现象一致（我确实用到了 `advisor_t`/`offsite_t`）。

**我没有逐字审阅全部 39 个文件**，只抽样确认了改动性质与规模。若其中有需要复核的段落，
请指明文件，我逐处核对。

2026-09-14 20:36:00 +08:00

7.8 KiB

Raw Blame History

数据库结构审计基线

一、审计工具

tools/schema_fingerprint.py 读取 MySQL information_schema 中每张表的字段名、类型、可空性、默认值、额外属性、字符集、排序规则和生成表达式，并输出 SHA-256 指纹。2026-09-09 起指纹 同时覆盖索引与唯一键（STATISTICS）以及外键（KEY_COLUMN_USAGE + REFERENTIAL_CONSTRAINTS），因为只对字段做指纹无法发现约束漂移。它不读取业务行数据，支持 --out 直接落 UTF-8 文件。

tools/audit_constraints.py 做三向比对：docs/00 声明的唯一键 ↔ 库实际唯一索引、 ORM 映射 ↔ 库列名（生成列单独归类为 note）。任一不一致返回非零退出码，可纳入提交前检查。

tools/audit_schema.py 仍负责表名与列存在性比对，与上述两个工具互补。

二、历史指纹记录

2026-09-09 在补建会话表前保存了 49 张既有表指纹；迁移 20260909_session 之后再次比对， 49 张既有表全部一致，新增 svc_conversation_session。随后新增 api_request_receipt，该表是公共 HTTP 幂等回执，不能替代 request_idempotency。

三、2026-09-09 约束纠偏

tools/generate_baseline_sql.py 旧实现只按规则列里的"唯一"字样逐字段生成 UNIQUE KEY，无法表达 docs/00 中的 唯一键 (a, b) 写法，导致四张表的联合唯一键被拆成两个单列唯一键：

表	纠偏前（错误）	基线要求
`fin_market_price`	UNIQUE(product_id)、UNIQUE(trade_date)	UNIQUE(product_id, trade_date)
`fin_nav_history`	UNIQUE(product_id)、UNIQUE(nav_date)	UNIQUE(product_id, nav_date)
`fin_holding`	UNIQUE(customer_id)、UNIQUE(product_id)	UNIQUE(customer_id, product_id)
`sys_customer_assignment`	UNIQUE(customer_id)、UNIQUE(employee_role)	UNIQUE(customer_id, employee_role)

后果：场内日线与净值每产品只能存一行、持仓每客户只能有一个产品，属结构性阻断。四张表在纠偏时均为 0 行，故纠偏无数据风险。迁移 20260909_constraint_fix 删除 8 个错误唯一键、新增 4 个联合唯一键；docs/00 基线文档未做任何修改，纠偏的是库与生成器。

验证证据（docs/evidence/）：

20260909-before-constraint-fix.sql：纠偏前 52 张表 SHOW CREATE TABLE 全量快照；
20260909-fingerprint-before.json 与 20260909-fingerprint-after.json：纠偏前后结构指纹；
两份指纹的差异恰好 4 张表（上表四张），其余 47 张结构未变；
tools/audit_constraints.py：约束差异由 12 条降为 0。

四、既有库对齐（方案 A）

⚠️ 2026-09-14 更新（第二次）：业务表数已从 68 变为 89。

68 → 89 的增量是投顾域的 21 张（advisor_*，迁移见 alembic/versions/20260910_advisor_* 与 20260911_advisor_*）。这 21 张同样不进 docs/00 基线。 登记文档当前待补（AGENTS.md 已声明），补后应与 docs/28 同一口径。
场内 51（docs/00） + 场外/推广 17（docs/28） + 投顾 21（登记文档待补） = 89 张业务表
（另加 alembic_version，库内共 90 张）
历史沿革（保留以备追溯）

2026-09-11：业务表数从 51 变为 68。同事那条线（袁聪）合并进来的 11 个 alembic 迁移新建了 17 张表 —— offsite_*（场外基金运营，10 张）与 promotion_*（推广域，7 张）。该 17 张不进 docs/00 基线（它冻结的是场内交易域），由 docs/28-场外与推广域数据表登记.md 单独登记；当时口径为 场内 51 + 场外/推广 17 = 68 张业务表（另加 alembic_version，库内共 69 张）。

2026-09-14：升到 89（+投顾 21），即本节上方的当前口径。

tools/audit_schema.py 的期望值随迁移自动增长（它读 baseline_generated.sql + 扫描 alembic/versions/*.py 的 CREATE TABLE，不是手写清单），所以 68 与 89 都是自动结果，没有人手工改过期望值。架构师合并后会看到表数从 51 跳到 68 再跳到 89，那是这些迁移的预期结果，不是有人绕过基线偷偷建表（机制与代价详见 docs/28-场外与推广域数据表登记.md §5）。

⚠️ 本文其余各处出现的"68"均为当时实测值，阅读时请代换成 89； 以 python tools/audit_schema.py 的实时输出为准。

基线表补入 Alembic 链首（20260909_baseline_schema）后，按库的来源分三种情况：

库状态	特征	操作
空库	无 `alembic_version` 记录、无业务表	`alembic upgrade head`，全量建出 89 张业务表（原为 51→68，见上方更新）
由 Alembic 建起	`alembic_version` 已位于链上	直接 `alembic upgrade head`；Alembic 不会重跑祖先迁移，无需 stamp
手工或脚本建库	有业务表但 `alembic_version` 为空	直接 upgrade 会重建已有表而失败，必须先 `alembic stamp <当前结构对应版本>`，再 `upgrade head`

⚠️ 本次合并实测到的第四种坏状态（原文档未覆盖，值得记一笔）： alembic_version 已指向较新的 revision，但部分表并不存在 —— 即"版本号跑了、表没建"。本库当时就是这种状态（alembic_version = 20260910_drop_review_separation，而 offsite_*/promotion_* 一张都没有）。它靠 alembic upgrade heads 收敛： Alembic 只跑 alembic_version 之后的迁移，所以恰好补建了缺失的表。架构师那边是另一种坏状态（"表没建、版本号也没跑"），同样靠这一条收敛。

tools/migration_state_check.py 只读诊断这三种状态：读取迁移链 head、alembic_version 记录与业务表数量，并按结构特征（生成列、联合唯一键、代表性表）由新到旧推断库实际所处版本，输出可执行的建议命令。三种状态均已实测：空库判定正确；jr 库判定为"已在 head、无需操作"；手工库场景（建表后清空版本记录）提示 stamp 到 20260909_memory_active_key，按其建议执行后 upgrade head 无任何 Running upgrade 输出，即未误重建表。

五、边界

数据库约束仍以 docs/00-新数据库基线设计.md 为业务权威。指纹与约束审计只证明结构一致，不替代状态机、并发语义和跨存储投影（Milvus/Neo4j）的业务验收。

六、已知文档偏差（`docs/00` 与真实 schema 不一致之处）

docs/00 是不可变业务基线（AGENTS.md 规则 1），不因下列偏差修改；但偏差必须登记，否则每换一个人接手就会重新踩一次。发现新偏差请追加到本节。

#	位置	文档描述	真实 schema	处置
1	`profile_snapshots.current_customer_id`	`docs/00` 第 783 行描述为「生成列」	不是生成列：`information_schema.COLUMNS` 实测 `EXTRA=''`、`GENERATION_EXPRESSION=''`；`alembic/baseline_generated.sql` 的建表语句无 `GENERATED` 子句；`tools/seed_profile_demo.py` 注释写明「不是生成列，必须显式写入」；`profile_repository.py` 用原生 SQL 显式写入	按真实 schema 映射成普通可空列；不改 `docs/00`；不补迁移（DDL 本身正确，错的只是文档描述；为"让文档成真"而加生成列会改变既有列语义，违反规则 4）。四处证据一致，2026-09-11 复核

发现方式：ZSY 那条线在合并前先按 AGENTS.md 与 docs/00/01/05/09/14/20 逐条过规则，撞到"文档说生成列、代码却显式写入"这处矛盾后做了实测。这个自查习惯值得保持—— 本次三家里，只有这条线在合之前把"撞到底座规则"的地方单独清理成了一个提交。

7.8 KiB Raw Blame History Unescape Escape