From d28ccdd88c5d3276f2ce2ed089e540cad5a2ecc1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=BF=E4=BA=91=E7=A7=8B=E6=9C=88?= <15273589815@163.com>
Date: Fri, 11 Sep 2026 19:40:17 +0800
Subject: [PATCH] =?UTF-8?q?=E7=AD=94=E5=A4=8D=20NL=5Fdevelop=20=E7=AC=AC?=
 =?UTF-8?q?=E4=BA=8C=E8=BD=AE=EF=BC=9A=E6=89=B9=E5=87=86=E6=95=B4=E6=94=B9?=
 =?UTF-8?q?=EF=BC=8C=E7=BA=A0=E6=AD=A3=20mypy=20=E5=BD=92=E5=9B=A0?=
 =?UTF-8?q?=EF=BC=8C=E8=A3=81=E5=AE=9A=20docs/00=20=E4=B8=8D=E5=8A=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

产出 docs/NL_develop评审回复-架构师答复.md（可直接转给对方）。三条核实结论：

1. docs/21 在我这边本来就重号（21-JWT密钥管理与轮换.md + 21-风控业务第二版迁移
   清单.md），tools/check_authoritative_docs.py 当前就是失败的 —— 我此前只跑
   ruff/mypy/pytest，没跑到文档守卫。对方的让号顺手修好了这个既有故障，
   故批准 docs/26 与 docs/27 两处让号。

2. 对方的 mypy 归因需要纠正。他说主因是缺 SQLAlchemy 2.0 类型信息；我这边
   mypy 1.20.2 + SQLAlchemy 2.0.52 + 未装 sqlalchemy2-stubs → 0 错，而
   pyproject.toml 约束是 sqlalchemy>=2.0,<3 / mypy>=1.14,<2。SQLAlchemy 2.0 自带
   py.typed，sqlalchemy2-stubs 是给 1.4 用的，装了反而按 1.4 的 API 报错（他自己也
   观察到"还会换一批新错"）。真实根因是他的 .venv 没满足 pyproject 约束。

3. 他的迁移警告对我不适用。我这边 alembic current = heads = 20260911_risk_rule_index
   （单一 head，只有我自己的迁移），schema audit 报 51 business tables —— 即"表没建、
   版本号也没跑"，与他那边"版本号跑了、表没建"是两种不同的坏状态。合并后我必须补跑
   alembic upgrade heads。

裁定：
- 补发配置（customer_service:faq 加 query_customer_profile）归我做；
- memory_sync_outbox / GraphProjectionWorker 消费端归我（生产者在他那边）；
- 两处让号批准；
- docs/00 不动，另立文档登记场外/推广域 17 张表，并更新 docs/08 审计基线口径
  （依据 AGENTS.md 规则 8：场外基金运营流程独立，不得写入场内交易表）。
---
 docs/NL_develop评审回复-架构师答复.md | 212 ++++++++++++++++++++++++++
 1 file changed, 212 insertions(+)
 create mode 100644 docs/NL_develop评审回复-架构师答复.md

diff --git a/docs/NL_develop评审回复-架构师答复.md b/docs/NL_develop评审回复-架构师答复.md
new file mode 100644
index 0000000..427f008
--- /dev/null
+++ b/docs/NL_develop评审回复-架构师答复.md
@@ -0,0 +1,212 @@
+# 架构师答复 · 第二轮（对《评审意见回复》的回应）
+
+> **致**：`NL_develop` 维护者
+> **被回复**：`评审意见回复-NL_develop.md`、`接手文档-NL_develop-给架构师.md`
+> **基线核对时间**：2026-09-11 晚　**本机**：`qyqy_develop_1`
+> **结论**：**你的整改我全部认可，两处让号都批准，`docs/00` 我不动。另有一条技术纠正（mypy 根因）和一条
+> "你的合并会顺带修好我这边一个既有故障"。**
+
+---
+
+## 0. 先说一条我欠你的：`docs/21` 重号是我这边的既有故障
+
+你说"`docs/21` 这个号已被你的《风控业务第二版迁移清单》占用，所以我让到 26"。
+
+**我核实了，你说得对，而且比你说的更严重**——我这台 `docs/` 顶层**就是重号的**：
+
+```
+$ python tools/check_authoritative_docs.py
+docs 顶层重号 {'21': ['21-JWT密钥管理与轮换.md', '21-风控业务第二版迁移清单.md']}
+```
+
+**这个守卫脚本在我这里当前是失败的**，而我此前一直没跑到它（我只跑 ruff / mypy / pytest）。
+也就是说：`docs/21` 早在你让号之前就已经是两份了，**你的让号顺手修好了我一个既有故障**。
+
+⇒ **`docs/26` 让号：批准。** 理由不只是"你的文件引用少"，而是**这是唯一能让我这边守卫变绿的方案**。
+
+同理 **`docs/27`（NL2SQL，原 15）批准** —— 手册被 `docs/16`/`docs/17`/`AGENTS.md` 三处引用，
+依据充分。
+
+---
+
+## 1. 技术纠正：mypy 184 错的根因不是"缺 SQLAlchemy 2.0 类型信息"
+
+你查到"装 `sqlalchemy2-stubs` 后 181→43、卸载回 184"，并据此判断主因是缺类型信息。
+**方向对了一半，但结论反了。** 我这边实测：
+
+```
+mypy 1.20.2 (compiled: yes)
+sqlalchemy 2.0.52
+$ pip show sqlalchemy2-stubs → WARNING: Package(s) not found
+
+$ python -m mypy app
+Success: no issues found in 138 source files        ← 0 错
+```
+
+**`sqlalchemy2-stubs` 没有装，SQLAlchemy 也是 2.0.52，而我这边 0 错。**
+
+关键在于 `pyproject.toml` 的约束：
+
+```toml
+"sqlalchemy>=2.0,<3",
+"mypy>=1.14,<2",
+[tool.mypy]
+python_version = "3.13"
+strict = true
+```
+
+**SQLAlchemy 2.0 自带 `py.typed`**，`Mapped[T]` / `mapped_column` / `DeclarativeBase` 的类型信息
+是随包发布的，**根本不需要 `sqlalchemy2-stubs`** —— 那个包是给 **SQLAlchemy 1.4** 用的。
+你自己也观察到了装上之后"还会换一批新错（`mapped_column`/`DeclarativeBase` 不存在）"，
+那正是它在按 1.4 的 API 描述去核对 2.0 代码。
+
+**所以那 184 错的真实来源是：你的 `.venv` 没满足 `pyproject.toml` 的约束**，最可能是
+SQLAlchemy 版本低于 2.0（也可能是 mypy 低于 1.14）。请这样确认：
+
+```powershell
+.\.venv\Scripts\python.exe -c "import sqlalchemy; print(sqlalchemy.__version__)"
+.\.venv\Scripts\python.exe -m mypy --version
+```
+
+若 SQLAlchemy < 2.0，按 `pyproject.toml` / `requirements.txt` 重建环境（`pip install -e .`），
+**mypy 应该会落到和我一样的量级**。
+
+**两个具体请求**：
+
+1. **不要把 `sqlalchemy2-stubs` 写进依赖**——它会让 2.0 代码按 1.4 的类型定义报错；
+2. 你 §1.4 说"不再拿这个数字当结论"是对的，但**别把它归因成"代码质量无从判断"**：
+   环境对齐后这个数字是可信的，我这边就是 0 错。你文件里那 8 个真实错误的修法我看了，改得对
+   （`Mapping`→`dict` 那条尤其对，回表要就地补写 `score`/`intent`，`Mapping` 是只读协议）。
+
+> 顺带：`model_gateway.py` 那 2 个和 `runtime.py` 那 1 个你选择"不用 `cast` 掩盖"——
+> 我同意先放着。环境修好后大概率自己就消失了。
+
+---
+
+## 2. 三件待裁决的事
+
+### 2.1 画像工具白名单补发 —— ✅ 归我，我出脚本
+
+接受你的理由（`config_release` 是环境数据、不随代码合并，谁的环境谁发布）。合并进来后我发一版：
+
+```
+customer_service:faq = [search_knowledge, query_customer_profile]   ← 唯一变化
+其余 8 条原样继承
+```
+
+你提醒的"**同 key 的继承项必须被本次新定义覆盖**"这个坑我记下了——这正是
+`config_release` 整版本替换语义最容易踩的地方，谢谢。脚本我会按"同 key 覆盖 + 打印被替换的旧值"写。
+
+### 2.2 `memory_sync_outbox` / `GraphProjectionWorker` 归属 —— ✅ 归我
+
+**判定依据**（不是分工方便，是证据）：
+
+| | 我这台 | 你这台 |
+|---|---|---|
+| `MemorySyncOutbox` 生产者 | **无** | 有（`profile_repository.py:142`） |
+| 表内数据 | 空 | 2 行待处理 |
+| 消费端 | 无 | 有定义、**无实例化点** |
+| `GraphProjectionWorker` | 无实例化点 | 无实例化点 |
+
+**生产者在你那边，我这边什么都没有** ⇒ 缺的是**消费端**，而消费端属 `app/worker/` 装配层，
+正是我这条线在维护（我改过 `runtime.py` 的 `knowledge_writer` 那类注入点）。
+
+**所以**：生产者保留你的，**消费端（`GraphProjectionWorker` 实例化 + 与 `runtime.py` 装配 +
+`ProjectionReconciliationService` 接上）归我**。你 §6.2 说"我先不动手"是对的，**继续保持不动**。
+
+**时机**：合并之后我再接。现在两边都别动，避免各接一根线。
+
+### 2.3 两处让号 —— ✅ 都批准
+
+见 §0（`docs/26`）与 §0 末（`docs/27`）。
+
+---
+
+## 3. `docs/00` 基线要不要补那 17 张表 —— ❌ 不改 `docs/00`，另立文档
+
+我的裁决是**不改进 `docs/00`**，依据是基线规则本身：
+
+> `AGENTS.md` 规则 8：**当前系统业务功能只针对场内基金模拟交易；场外基金运营流程独立，
+> 不得写入场内交易表。**
+
+同事带来的 17 张表是：
+
+```
+offsite_*   (10)  场外基金运营
+promotion_* ( 7)  推广域
+```
+
+**这两个域都不是场内交易域**，而 `docs/00-新数据库基线设计.md` 冻结的正是场内交易域的基线。
+把独立域塞进去，等于让"基线"这个概念失效——下次有人拿 `docs/00` 当"当前全部表"的依据时就错了。
+
+**但必须有人管**，否则 68 张表与文档的 51 张永远对不上、审计每次都报差异。所以：
+
+1. **`docs/00` 不动**（不可变基线，规则 1）；
+2. **新增一份独立登记**：建议 `docs/28-场外与推广域数据表登记.md`，逐表登记表名、归属域、
+   哪个迁移建的、是否被场内代码引用；
+3. **同步 `docs/08-数据库结构审计基线.md`** 的表数口径：不是简单改成 68，而是写成
+   「场内 51 + 场外/推广 17 = 68」，并说明分类依据；
+4. **`tools/audit_schema.py` 的期望值**：你这台已经报 `68 business tables, no missing or
+   unexpected tables`，说明期望值已经跟着改了——**请在 PR 描述里点明这一点**，否则我合并后
+   看到表数从 51 跳到 68，会以为是有人偷偷建了表。
+
+**这一条我采纳你的做法，但补一个归属文档**——你的"只提示、不动手"是对的，因为它是不可变基线。
+
+---
+
+## 4. 你那 3 个 failed：判断都对，但请注意它们不在我这条分支上
+
+| 用例 | 你的判断 | 我的意见 |
+|---|---|---|
+| `test_fund_readonly_contract` | 既有空集缺陷，双方都不修 | ✅ 同意 |
+| `test_offsite_document_recognition_adapter` ×2 | 环境相关（httpx 序列化成 `\uXXXX`） | ✅ 判断对，你建议的"断言 `json.loads(body)` 后的字段值"也对——字节级断言本来就不该用来测 JSON |
+
+**但要提醒一句**：这 2 个用例**在我这条分支上根本不存在**（同事那条线没进来，我这边
+`pytest tests/unit tests/contract` 是 703 passed）。所以它们不是"双方共有的既有失败"，
+而是**你这条线合并进来之后才会出现**的。合并后我会把它们当**新引入的失败**对待并跟踪，
+不会当成"历史遗留"放过。
+
+---
+
+## 5. 同步给你：我这边的实测状态（供你判断合并冲突面）
+
+```
+分支：qyqy_develop_1，已含 origin/qyqy_develop 的 d2cdbba，并多 1 个提交（未推送）
+
+alembic：current = heads = 20260911_risk_rule_index   ← 单一 head，只有我自己的迁移
+         （不是你说的 20260911_merge_risk_heads —— 同事那 11 个迁移不在我这条线上）
+表数：   schema audit passed: 51 business tables        ← 与你那边的 68 张对不上，见 §3
+门禁：   ruff 干净 / mypy app 138 文件 0 错 / 703 unit+contract / 33 integration
+文档守卫：❌ 失败（docs/21 重号，见 §0）
+```
+
+**⇒ 合并后我必须补做 4 件事**（记在这里，免得忘）：
+
+1. `alembic upgrade heads` —— 补跑你那 11 个迁移、建 17 张表。我这边是"表没建、版本号也没跑"，
+   和你那边"版本号跑了、表没建"是**两种不同的坏状态**，但都靠这一条收敛；
+2. 补发配置（§2.1）；
+3. 接 `memory_sync_outbox` 消费端（§2.2）；
+4. 补场外/推广域的表登记 + 更新审计基线口径（§3）。
+
+---
+
+## 6. 对你 §7 两条建议的答复
+
+1. **文档体系两套口径** —— 认可你的做法（保留 `docs/04`/`06`/`10`/`13`/`99`，但列入 D 类"不要用来
+   判断当前进度"）。理由：你保留了文件（成本为零），又明确标注了它们的可信度（避免误用），
+   这比"删掉"和"无差别都读"都好。**不需要改写索引。**
+2. **`docs/00` 补表** —— 见 §3，不动 `docs/00`。
+
+---
+
+## 7. 一句话总结
+
+你这轮的整改**没有一条我不同意**（除了 mypy 那条归因，而且那是环境问题不是代码问题）。
+剩下的事按这个顺序就能收敛：
+
+**你**：环境重建（§1）→ 推送 `NL_develop`；
+**我**：跑迁移 → 补发配置 → 接 outbox 消费端 → 补表登记 → 跑全量门禁 → 推送。
+
+> 最后回应你 §1.3 那句"既然两台 schema 确实不同，必须以运行时探测为准、禁止任何形式的字段名
+> 硬编码"——**完全同意**，而且你用"双 schema 参数化测试"把它锁住这招很漂亮：任何回退到硬编码
+> 都会让其中一侧立刻变红。比我原来担心的"靠人记住"可靠得多。