group_fqcd_jr/docs/28-场外与推广域数据表登记.md

场外与推广域数据表登记（docs/00 基线的域外补充）

用途：docs/00-新数据库基线设计.md 冻结的是场内基金模拟交易域的基线（不可变，规则 1）。 同事那条线（袁聪）合并进来的 17 张表属场外基金运营域与推广域，不进 docs/00， 由本文单独登记，避免"基线"这个概念因为塞入独立域而失效。

维护约定：新增/删除这两个域的表时必须同步本文；本文是「68 张表从哪来」的唯一答案。 表数口径：场内 51 + 场外/推广 17 = 68（共 69 张含 alembic_version）。

---

1. 为什么另立文档（架构师裁决，2026-09-11）

依据 AGENTS.md 规则 8：

当前系统业务功能只针对场内基金模拟交易；场外基金运营流程独立，不得写入场内交易表。

⇒ 场外与推广是独立域。把它们塞进 docs/00 会让"基线"从"场内交易域的冻结定义" 变成"当前全部表"，下次有人拿 docs/00 当依据时会错。因此：

文档	职责
docs/00-新数据库基线设计.md	场内交易域基线（不可变，51 张）
本文	场外/推广域（17 张）的登记与来源
docs/08-数据库结构审计基线.md	审计口径：场内 51 + 场外/推广 17 = 68
tools/audit_schema.py	期望值同为 68（已生效，见 §4）

---

2. 17 张表逐表登记

2.1 场外基金运营域（offsite_*，10 张）

表名	来源迁移	建立它的提交意图
offsite_fund_mail	20260910_offsite_fund	场外申购邮件记录（运营入口）
offsite_fund_attachment	20260910_offsite_fund	邮件附件（该域唯一有数据的表，见 §3）
offsite_fund_document	20260910_offsite_fund	识别后的业务单据
offsite_execution_plan_task	20260910_offsite_fund	执行计划任务
offsite_rule_result	20260910_offsite_fund	规则校验结果
offsite_query_record	20260910_offsite_fund	NL2SQL 查询记录
offsite_notification	20260910_offsite_fund	对外通知
offsite_mail_cursor	20260910_offsite_worker	邮件 Worker 的游标状态
offsite_recognition_attempt	20260910_offsite_recognition_attempt	识别尝试追踪（OCR/LLM 各一次尝试）
offsite_field_correction	20260911_offsite_field_correction	人工字段纠正记录

2.2 推广域（promotion_*，7 张）

表名	来源迁移	用途
promotion_material_task	20260910_promotion_material	推广素材任务（主表）
promotion_material_version	20260910_promotion_material	素材版本
promotion_input_snapshot	20260910_promotion_material	生成输入快照（可复现）
promotion_attachment	20260910_promotion_material	素材附件（海报/PPT）
promotion_compliance_check	20260910_promotion_material	合规校验结果
promotion_review_record	20260910_promotion_material	审核记录
promotion_delivery_record	20260910_promotion_material	投递记录

2.3 迁移文件清单（11 个，含 6 个 merge/辅助）

建表相关：20260910_offsite_fund / _offsite_worker / _offsite_recognition_attempt /
          _promotion_material / _promotion_poster / 20260911_offsite_field_correction
合并链：  20260910_merge_heads / 20260911_merge_review_separation /
          20260911_merge_risk_heads（当前 head）
其他：    20260910_offsite_worker_identity / 20260911_drop_review_separation

⚠️ 两个环境都踩过的坑：本库曾处于"alembic_version 已指向同事的 revision， 但 offsite_*/promotion_* 表一张都没有"的状态（版本号跑了、表没建）； 架构师那边则是"表没建、版本号也没跑"。两种坏状态都靠 alembic upgrade heads 收敛。

---

3. 当前数据量（2026-09-11 实测）

表	行数
offsite_fund_attachment	60
其余 16 张	0

说明：只有附件表有数据（同事调试/演示时落盘的附件）。这不是"该域已在生产运行"的证据， 也不代表其它表可以删——禁止删表（规则 3）。

---

4. 跨域边界核对（规则 8 的两向检查）

4.1 场内代码是否引用这 17 张表 → 否 ✅

app/ 下搜 offsite_|promotion_ 只有 12 处命中，全部是 app/core/config.py 里的环境变量名 （offsite_mailbox、offsite_allowed_senders 等），没有任何 SQL/ORM 级引用。 场内模型（app/model/fund.py 等）与只读契约（FUND_TABLES）都只覆盖 fin_*。

4.2 场外代码是否写场内交易表 → 否 ✅

在 app/service/offsite*.py 与 app/model/offsite*.py 里搜 fin_sim_order|fin_capital_flow|fin_cash_ledger|fin_transaction|fin_holding —— 零命中。 场外域只读写自己的 offsite_* 表。

⇒ 两个方向都不越界，符合规则 8。这一点在合并评审时是要点，故在此留档。

---

5. 对审计工具的影响（不是"有人偷偷建表"）

$ .\.venv\Scripts\python.exe tools\audit_schema.py
schema audit passed: 68 business tables, no missing or unexpected tables

表数从 51 跳到 68 是同事那 11 个迁移的预期结果**，不是有人绕过基线偷偷建表。**

机制要说清楚（否则会被误读成"期望值被手工改过"）：tools/audit_schema.py 的期望表集合 是动态推导的，不是一份手写清单：

def expected_tables() -> set[str]:
    tables = <从 alembic/baseline_generated.sql 正则提取 CREATE TABLE>
    for path in (alembic/versions/*.py):
        tables |= <从每份迁移里正则提取 CREATE TABLE>      # ← 17 张新表由此自动进入
    return tables

⇒ 期望值随迁移自动增长，没有人手工改过它。优点是不会漏；代价是它只增不减 —— 若将来有迁移 DROP 掉某张表，期望集合仍会包含它，审计会报 missing 的假失败。 真要删表时（记得规则 3：禁止删除已有表）需同步调整该工具。

⚠️ 若你那边 audit_schema.py 报 unexpected，先确认是"库里多表"还是"迁移没进来"—— 前者是绕过基线的违规，后者只是迁移没合。两者处置完全不同。

---

6. 与 docs/00 的关系（一句话）

docs/00 一个字段、一张表都没动（规则 1）。本文是它的域外补充登记， 两者合起来才是"当前库里的全部表"：

docs/00（场内 51）  +  本文（场外/推广 17）  =  68 张业务表

---

登记时点：2026-09-11　登记依据：现库 information_schema 实测 + alembic/versions 逐文件核对 + tools/audit_schema.py 的期望值推导机制核对。