摘要
NFR-3.9-01（溯源 AI-3.9-01）要求按 APPI 建立数据处理基础：①三语隐私政策；②敏感数据脱敏、密钥加密存储；③数据最小化；④AI 处理专项条款；⑤「要配慮個人情報」以不取得为原则。PRD 验收要点原文：「AI 处理专项条款发布并经法务复核；数据最小化清单评审通过；扩量启动前条款已生效」。现状判定部分实现：三语隐私政策、日志脱敏、密钥加密均在代码层成立（底座已建成）；但隐私政策无 AI/LLM 处理专项条款（错放 ToS §8）、ja 正文泄漏 seed 脚本、占位符未填、文档版本化形同虚设。
本 TDD 以两段式组织（与 AI-3.5-02 的管道增强段/服务接入段同构）：技术管道段（T-① legal-document-revision 版本化发布模块、T-② ja 泄漏修复、T-③ 占位符修复与发布门禁、T-④ 发布通道先决）无门控、零外部依赖、立即可开工；条款内容段（AI 处理专项条款正文、要配慮机制、最小化清单评审）由 blocker DEC-2 门控——法务核实服务商数据处理条款、确定委托/越境分支归属后方可开工，技术侧仅交付挂载位与生效机制。本条不引入任何 AI 调用路径。
技术管道任务
4 项
T-①~④ 无门控可并行开工（T-① 依赖 T-④ 决策记录）；估时合计约 4.5d（技术侧）
受污染文档
4 份
storefront/b2b 两端 × privacy_policy-ja 与 terms_of_service-ja（h2b 端 0 污染）
新增 API 路由
5 条
admin 域 4 条（列表/创建/编辑/发布）+ store 域 1 条（现行版读取）
条款内容段门控
DEC-2
不决策的后果：翻译扩量须持续搁置（AI-3.5-02 扩量的顺序不可颠倒前置）；技术管道段不受阻
关键概念
APPI
日本《個人情報の保護に関する法律》（个人信息保护法）。本条对应其三语隐私政策、委托处理/越境转移告知、要配慮個人情報不取得原则等要求。
两段式组织
技术管道段（无门控、零外部依赖）+ 条款内容段（DEC-2 门控）——技术侧可开工部分与法务前置部分显式拆分，互不阻塞。
DEC-2 门控
C2 合规条款（AI 处理告知、委托与越境分支核实）的启动时点决策。分支归属取决于服务商数据处理条款（含数据是否用于模型训练），由法务核实后回填；核实与条款补齐前翻译扩量不得启动。
C2 双分支
①委托处理：受托方仅限受托目的使用 + 平台履行委托方监督管理义务 + 明示委托事实；②越境转移：本人同意 + 规定信息提供，或认定同等保护安排——二选一回填。
legal-document-revision
本卡新建的后端本地模块：法务文档版本化发布（draft/published/archived 三态 + published_at 审计时间戳），命名沿用历史 drop 迁移中的表名（重建非首创）。
static→api 双模开关
env
LEGAL_DOCS_SOURCE=static|api（缺省 static = 现状逐字节不变）；api 模式读取失败回退 static JSON 兜底（可用性优先），static 同时是回滚态。发布双门禁
validate-revision-content-step 内两道校验：占位符未填检测（
LEGAL_DOC_PLACEHOLDER_UNFILLED）+ 脚本痕迹检测（LEGAL_DOC_SCRIPT_ARTIFACT），任一命中即阻断发布。要配慮個人情報
APPI 下的「需要关照的个人信息」（健康/犯罪履历等）——以不取得为原则：收集字段清单设该当性列（默认不取得）+ 字段变更评审门。
references_only
责任边界声明：条款正文、占位真实值由法务提供（技术侧不起草）；脱敏/加密机制只引用不重设计（其强制化归 AI-3.5-02 P-③）。
方案设计
两段式总览
| 分段 | 门控 | 内容 | 开工条件 |
|---|---|---|---|
| 技术管道段 | 无门控、零外部依赖 | T-① legal revision 版本化发布模块 / T-② ja 泄漏修复 + 发布前内容校验 / T-③ 三语占位符修复 + 占位符发布门禁 / T-④ 发布通道先决 A/B 对比与切换机制 | T-④ 决策记录后 T-①③ 开工；T-② 文本修复随时可做（内容确认后入库） |
| 条款内容段 | DEC-2 门控 | AI 处理专项条款正文（委托/越境双分支）、「要配慮個人情報」机制、数据最小化清单内容评审 | 前置决策点 DEC-2 关闭（法务核实服务商条款 → 分支归属回填）后方可开工；技术侧仅交付挂载位与生效机制 |
设计红线（AGENTS.md §0.1，强制验收）
- Workflow 承载业务逻辑：revision 状态变更全部走 Workflow，守卫在 step 内实现；
- 不修改上游源码：
@medusajs/*/@mercurjs/*不触碰，本卡全部为本地新建模块； - 后端是单一数据源：条款状态/版本/生效时间以后端为准，三前台仅消费；
- 参数化 SQL：查询经模块 service 与 query builder，动态条件参数化绑定。
flowchart TB
subgraph TECH["技术管道段（无门控，立即可开工）"]
T4["T-④ 发布通道先决（首节决策，推荐候选 B）"]
T2["T-② ja 泄漏修复（4 份受污染文档）"]
T3["T-③ 占位符修复 + 发布门禁（依赖 T-① step 骨架）"]
T1["T-① legal-document-revision 版本化发布模块（依赖 T-④ 决策）"]
T4 --> T1
T1 --> T3
end
GATE{"DEC-2 关闭：法务核实服务商数据处理条款 → 确定委托/越境分支归属 → 回填条款正文"}
L1["L-1 AI 处理专项条款挂载发布（§AI-1~§AI-4）"]
L2["L-2 数据最小化清单评审（并行，不依赖 L-1）"]
EXP["AI-3.5-02 翻译扩量解锁（顺序不可颠倒）"]
T1 --> GATE
GATE -->|"已关闭"| L1
L1 --> EXP
现状底座与数据质量缺陷
| 模块 | 锚点（file:line） | 结论 |
|---|---|---|
| ① 法务文档静态 JSON（三前台打包产物） | {storefront,b2b-storefront,h2b-storefront}/src/legal-documents/current/documents.json | 三端各 24 条 = 8 文档类型 × 3 语（cookie_policy / personal_information_protection / pricing_and_fees / privacy_policy / return_policy / seller_agreement / terms_of_service / tokushoho）；结构字段 id/type/title/content（markdown）/version/locale/published_at/created_at/updated_at（storefront/src/types/legal-document.ts:13-23）；版本化 = version 字段 + 人工 back/ 目录归档——back/ 三端均为空脚手架（仅 README），无任何已归档历史版本，版本化机制形同虚设 |
| ② 前台消费链（静态读取） | storefront/src/lib/data/legal-documents.ts | :3 打包期静态导入（更新内容必须重新构建发版——R-legal-publish-channel/RK-10 根因）；:14-38 findDocument（type 过滤 → locale 精确 → en 回退 → 首条兜底）；:8-12 OFFLINE_SELLER_AGREEMENT 硬编码覆盖 seller_agreement 正文（文档与代码耦合） |
| ③ 后端法务文档表 | backend/src/modules/platform_config/migrations/Migration20260710030000_drop_legal_document_tables.ts:5-10 | 负证据：当前后端无任何 legal document 模块/Workflow/API（rg 0 业务命中）——revision 化管道从零新建；历史意图证据：曾存在 legal_document / legal_document_revision / legal_consent 三表，2026-07-10 被 drop（down() 为空）——本卡 T-① 为「按现状约束重建」，drop 迁移表名作命名与结构历史参考，不恢复 legal_consent（范围外） |
| ④ 泄漏现场（R-privacy-ja-leak / RK-03） | storefront|b2b-storefront/src/legal-documents/current/documents.json:62 | privacy_policy-ja content len=6170 vs zh-Hans 1932（en 5121）——ja 正文在「*最終更新日: 2026-07-10*」后拼接 seed 脚本源码片段（含 updateLegalDocumentRevisionWorkflow、publishLegalDocumentRevisionWorkflow 调用块等）；本 run 扩证：terms_of_service-ja 同模式泄漏（len 6103 vs zh 1103 / en 3357）——实际 storefront/b2b 两端各 2 份文档受污染；对照组 h2b 端 privacy ja len=2111 干净 |
| ⑤ 占位符现场（R-legal-placeholder） | documents.json:62（三端同构行） | 「代表者: [氏名]」「住所: [住所]」「連絡先: [メール/電話]」「個人情報保護管理者: [氏名/部署]」；en/zh 对应占位；另有 [privacy@example.com]、[X年]、[13/16/18] 等多处未填——APPI 信息管理者联系方式在线上不可用（RK-03：法务效力存疑） |
| ⑥ 日志脱敏（已存在，references_only） | backend/src/modules/error-log/recorder.ts:15-23,271-341 | SENSITIVE_KEY = /password|token|secret|card|authorization|cookie|api[_-]?key/i（:15）+ 敏感请求头集合（:16-20）+ maskSensitive/walkMask 递归脱敏（:271-290）+ summarizeValue 分支（:335-341）——沿用不重设计 |
| ⑦ 服务密钥加密（已存在，references_only） | backend/src/utils/crypto/secret-crypto.ts:8-15,77,95 | AES-256-GCM（M-12/CWE-312），主密钥 TRANSLATION_ENCRYPTION_KEY，密文格式 enc:v1: + base64(iv(12)‖tag(16)‖ciphertext)；encryptSecret 幂等（:70）、decryptSecret 失败抛错防静默泄漏（:92-95）——其加密强制化与密钥轮换属 AI-3.5-02 P-③ 范围（交叉引用） |
| ⑧ 三语现状画像（抽样） | documents.json 内容级抽样 | 隐私政策三语均明示依 APPI 制定（结构齐备）；第三者提供节列六类服务商——无任何 AI/LLM 供应商条目（脚本扫描 False×3）；跨境转移节「[指定国家]」占位未填；其余 6 类文档未做 AI 条款全文扫描（列入实施期 A8 收口） |
| 类别 | 项 |
|---|---|
| 已存在可复用 | 三端 documents.json 结构与 8×3 文档矩阵；前台 getLegalDocument 读取链与 en 回退语义；recorder.ts maskSensitive 脱敏；secret-crypto AES-256-GCM；back/ 归档目录骨架（空置待启用） |
| 需扩展 | 前台读取链双模化（static→api 切换，T-④）；StoreLegalDocument 类型对齐 revision API 响应；privacy_policy 结构（AI 处理章节挂载位，条款内容段） |
| 从零新建 | 后端 legal-document-revision 模块（实体/Workflow/API 全套——drop 迁移证实现状为零）；发布前内容校验（占位符门禁 + 脚本痕迹检测）；数据最小化清单技术载体 |
T-① legal-document-revision 版本化发布模块（字段级）
新本地模块 backend/src/modules/legal-document-revision/（index/service/models/migrations 标准四件套，注册进 backend/medusa-config.ts 本地模块区，不触碰上游包）。实体字段级定义见数据模型与 API 契约；表名沿用 drop 迁移中的历史命名 legal_document_revision（重建非首创）。
发布动作走 Workflow——publishLegalDocumentRevisionWorkflow（命名即历史泄漏文本中出现的字样，历史意图对齐）：
sequenceDiagram
autonumber
participant Ad as admin-panel 法务文档管理页
participant Api as POST /admin/legal-document-revisions/:id/publish
participant Wf as publishLegalDocumentRevisionWorkflow
participant Db as legal_document_revision
participant Eb as event bus
participant St as 三前台（store 路由 + 缓存）
Ad->>Api: 发布动作（published_by = req.auth_context.actor_id）
Api->>Wf: 触发工作流
Wf->>Db: 1 validate-revision-content-step（占位符门禁 + 脚本痕迹门禁）
alt 双门禁任一命中
Wf-->>Ad: 抛 MedusaError INVALID_DATA（错误体列出违规清单，不产生任何写操作）
else 校验通过
Wf->>Db: 2 archive-current-published-step（该 type+locale 现行版置 archived，保留 published_at 历史值）
Wf->>Db: 3 publish-revision-step（新行置 published + 写 published_at / published_by）
Wf->>Eb: 4 emit legal-document.published（含 type / locale / version，事务上下文外直接 emit）
Eb-->>St: 缓存失效订阅（进程内 TTL 缓存主动失效）
St->>Api: GET /store/legal-documents/:type?locale=xx
Api-->>St: 返回现行 published 版本
end
| step | 职责 | 守卫 / 补偿 |
|---|---|---|
validate-revision-content-step | 占位符未填校验（T-③ 门禁）+ 脚本痕迹检测（T-② 门禁），双校验任一命中即抛 MedusaError(INVALID_DATA) 阻断发布，错误体列出违规清单 | 校验失败不产生任何写操作 |
archive-current-published-step | 将该 (document_type, locale) 现行 published 行置 archived（保留 published_at 历史值） | 补偿：恢复原行 published、新行回 draft |
publish-revision-step | 新行置 published + 写 published_at/published_by | 补偿：新行回 draft + 恢复原行 |
emit-legal-doc-published | event bus 直接 emit legal-document.published（含 document_type/locale/version）——供前台缓存失效与审计订阅；step 事务上下文外直接 emit（沿用 run-translate-product:251-256 同理由） | — |
revision 状态机：
stateDiagram-v2
state "draft（可编辑）" as D
state "published（现行版，同 type+locale 至多一条）" as P
state "archived（历史版，可回切）" as A
[*] --> D: POST 创建 draft 行
D --> D: PUT 修改（仅 draft 可改）
D --> P: publish workflow（archive 先行守卫）
P --> A: 新版发布归档 / 应急下线 unpublish
A --> D: 以历史 archived 内容新建高版本 draft（回切路径）
note right of P: published 行不可变（改即新建版本），published_at 为「扩量启动前条款已生效」的审计时间戳
前台读取与缓存策略（候选对比，随 T-④ 决策落地）：
| 候选 | 机制 | 评估 |
|---|---|---|
| C-1 进程内 TTL 缓存 | store 路由 server 端拉取 + 模块级 Map 缓存，TTL 数值基线立项定（DEC-5）；订阅 legal-document.published 事件主动失效 | ✅ 推荐：法务文档低频更新，实现最简、无新增基建 |
| C-2 CDN/ISR 层缓存 | Cache-Control s-maxage / Next ISR 标签再验证 | 效果更优但引入每端配置差异，列为演进项 |
| C-3 无缓存直查 | 每请求查库 | 法务页 QPS 低亦可接受，作为正确性基准 |
static→api 双模开关（T-④ 承接）：env LEGAL_DOCS_SOURCE=static|api（缺省 static = 现状行为逐字节不变）。storefront/src/lib/data/legal-documents.ts 改造：api 模式下 getLegalDocument 改走 /store/legal-documents/:type，失败回退 static JSON 兜底（可用性优先）；三端同构改造。
T-② ja 泄漏修复（R-privacy-ja-leak / RK-03 缓解）
- 修复范围（复核后清单）：storefront 与 b2b-storefront 的
privacy_policy-ja-current（len 6170）与terms_of_service-ja-current（len 6103）共 4 份文档对象；h2b 端不受影响（privacy ja 2111 干净）； - 清除动作：删除泄漏段（泄漏起点 = 「*最終更新日: 2026-07-10*」之后的代码片段，含
publishLegalDocumentRevisionWorkflow调用块）；正确 ja 正文由商务/法务确认后入库（技术侧提供清洗稿：仅剥离脚本段、不改动正文语义）； - 防再发门禁（随 T-① validate-revision-content-step 落地）：
- 代码标识符检测：content 命中 seed/workflow 代码模式即拒绝——检测正则集（可配置）：
publishLegalDocumentRevisionWorkflow|updateLegalDocumentRevisionWorkflow|createStep\(|StepResponse|container\)\.run\(|LegalDocumentType\.|legalDocumentService； - 长度比突变检测：同一 document_type 三语 content 长度比超出历史基线带即告警/阻断（阈值基线立项定（DEC-5）；实测锚点：privacy 三语 5121/1932/2111、TOS 3357/1103/2111 为参考带）；
- 代码标识符检测：content 命中 seed/workflow 代码模式即拒绝——检测正则集（可配置）：
- 回归断言（A4）：修复后 4 份文档 content 中上述标识符 0 命中；ja/zh 长度比回到参考带内。
T-③ 三语占位符修复与发布门禁（R-legal-placeholder）
- 占位值来源：
[氏名]/[住所]/[メール/電話]/[氏名/部署]及 en/zh 对应占位、[privacy@example.com]等真实值由法务提供（技术侧不起草——references_only）； - 技术侧交付：占位符未填校验发布门禁（并入 T-① validate step），正则清单（可配置）：
| 语言 | 检测正则 |
|---|---|
| ja | [氏名]|[住所]|[メール/電話]|[氏名/部署] |
| en | [Name]|[Address]|[Email/Phone]|[Name/Department] |
| zh | [姓名]|[地址]|[邮箱/电话] |
| 通用 | \[[^\]\[]{2,}\] 模式（放行合法 markdown 链接语法后扫描） |
命中即阻断发布并列出占位符清单（文档/行/片段），错误码 LEGAL_DOC_PLACEHOLDER_UNFILLED；存量修复：T-① 落地前，4 份受污染文档的占位符修复走 T-② 同批人工修 JSON（内容法务提供后一次性替换 + 回归扫描）。
T-④ 发布通道先决（R-legal-publish-channel / RK-10）——首节决策项
| 维度 | 候选 A：维持前端打包静态 JSON | 候选 B：DB/后台化动态发布（T-① revision 模块 + API + 缓存） |
|---|---|---|
| 更新时效 | 需三端各自改 JSON → 构建 → 发版（分钟~小时级 + 发版窗口）；泄漏/占位符类缺陷修复同样要走发版 | 后台发布即生效（秒级），无需发版 |
| 版本治理 | version 字段 + 空置 back/ 目录，无系统化归档（实证） | revision 表全量留痕，published/archived 可回切，published_at 可审计 |
| 多端一致性 | 三端三份 JSON 手工同步（现已出现单端泄漏差异：h2b 干净、storefront/b2b 泄漏） | 单一数据源，三端一致（后端单一数据源红线） |
| 建设成本 | 零开发，但每次更新均有运维成本且合规审计能力缺失 | 新模块一套（实体 + Workflow + API + 双模开关），一次性成本 |
| 合规硬需求匹配 | C2 AI 专项条款「发布生效」时效无法承诺，扩量顺序审计（条款生效时间戳）无后端权威数据源 | published_at 权威时间戳直接支撑 PRD 验收要点「扩量启动前条款已生效」 |
推荐：候选 B
C2 AI 专项条款「发布并生效」是 AI-3.5-02 扩量的硬前置（§7.5 顺序不可颠倒），发布时效与生效时间戳审计为合规硬需求；A 路径下该验收要点不可验证。A 不废弃：双模开关保证 static 为回滚态与兜底态。本决策为本卡首节先决，决策记录落 PR/文档后 T-① 即可开工。
条款内容段（DEC-2 门控，关闭后方可开工）
门控声明
本段设计照写备妥，但任何条款正文起草与发布动作必须等 DEC-2 关闭：法务核实服务商数据处理条款（含数据是否用于模型训练）→ 确定委托/越境分支归属 → 回填条款正文 → 经本卡技术管道发布。技术侧在本段的交付物仅为挂载位结构与生效机制，不起草正文（references_only）。
AI 处理专项条款挂载位结构（privacy_policy 内新增独立章节，三语同步，结构占位）：
| 章节占位 | 内容要求（由法务回填） | 技术侧约束 |
|---|---|---|
| §AI-1 处理事实 | 商品数据（以含可识别个人之信息为前提）发送至外部大模型服务进行 AI 翻译的事实明示 | 章节锚点 id 固定（ai-processing），前台锚点跳转可用 |
| §AI-2 分支说明 | 委托分支：受托方仅限受托目的使用 + 平台履行委托方监督管理义务 + 明示委托事实；越境分支：本人同意 + 规定信息提供，或认定同等保护安排——二选一回填 | 分支字段 metadata.branch = delegation | cross_border（revision 行可挂），发布校验分支字段非空 |
| §AI-3 供应商条目 | LLM 服务商标识、处理目的、数据用途（含是否用于模型训练——C2 分支归属的决定项） | 供应商条目结构化列表位 |
| §AI-4 用户权利影响 | 对利用目的/開示・訂正・利用停止等用户权利的具体影响说明 | — |
「要配慮個人情報」以不取得为原则的机制位：①收集字段清单（见下）中设「要配慮該当性」列（默认「不取得」）；②字段变更评审门：新增收集字段走清单评审（与数据最小化清单同一载体）；③后续医疗类目场景确需接触时，先完成取得同意与目的通知机制设计（C6 同批前瞻，references_only——本卡不设计）。
数据最小化清单技术实现：
- 清单载体：「字段 / 收集目的 / 存储位置 / 保留期限 / 要配慮該当性」五列清单，覆盖 customer 注册字段与 seller 入驻字段（对照
seller-profile.ts:18-25现有字段面：business_type/capabilities/approval_data 等）；清单内容评审 = PRD 验收要点「数据最小化清单评审通过」的业务动作； - 超范围不存储校验点：①注册/入驻表单 validator 白名单（
validateAndTransformBodyzod schema 键闭合——多余字段拒绝）；②落库面审计：清单字段集 vs 实体字段集差异脚本（实施期一次性核对 + CI 可选）；③发送外部 LLM 的内容最小化由 AI-3.5-02 P-① 白名单参数化承载（交叉引用不重复设计）。
迁移与回滚
| migration | 内容 | 兼容性 |
|---|---|---|
| legal-document-revision 模块 migration | CREATE TABLE legal_document_revision（全列 + 唯一约束 + 索引，见数据模型） | 新表，无存量；空库可重放；走 medusa db:generate 规范 |
seed 兼容（pnpm db:reset / db:reset:demo 不破坏）：seed 注入首版 8 类型 × 3 语（以现 storefront documents.json 内容为源导入为 status=published, version=1 行）——reset 后 API 模式有数据可读；demo 数据不新增法务文档（与现状一致）。
| 变更 | 回滚路径 |
|---|---|
| 前台读取双模化 | LEGAL_DOCS_SOURCE=static（缺省态即回滚态）——三端回到现状静态读取，逐字节不变 |
| revision 发布 | 法务文档回滚 = archived 版本可回切：以历史 archived content 新建高版本 draft → 再发布（版本只增不改，审计链完整）；应急下线走 unpublish workflow（store 端 static 兜底） |
| 泄漏/占位符修复 | 文本修复为内容更正，回滚 = git 版本库 revert JSON（static 模式天然可回）；api 模式下按上一行回切 |
| 门禁误拦截 | 正则清单可配置——临时放行走配置白名单（不走代码热修），误拦事件回 feed 门禁规则评审 |
| 新能力总开关 | 本条非 AI 能力，无 AI 开关；模块级开关 = medusa-config 移除注册 + 双模开关回 static（两级均可独立回退） |
上线顺序建议：T-②（泄漏修复最急，线上缺陷）→ T-④ 决策记录 → T-①③ 并行 → 双模灰度（static 维持 → api 验证 → 切 api）→ 条款内容段等 DEC-2。
数据模型与 API 契约
实体 legal_document_revision（字段级，12 字段）
erDiagram
LEGAL_DOCUMENT_REVISION {
text id PK "prefix legrev"
text document_type "8 类型枚举，以 documents.json 现档为准"
text locale "ja-JP，zh-Hans，en-US（静态 JSON 短码在适配层映射）"
int version "默认 1，递增整数"
text title "文档标题"
text content "markdown 载体（与现 JSON content 同构）"
text status "draft，published，archived（默认 draft）"
timestamptz published_at "生效审计时间戳（可空）"
timestamptz effective_at "法务生效日（可空）"
text published_by "发布人 actor_id（可空）"
timestamptz created_at "标准三件套"
timestamptz updated_at "标准三件套"
timestamptz deleted_at "标准三件套"
}
| 字段 | 类型 | 约束 / 默认 | 说明 |
|---|---|---|---|
id | text | PK，prefix legrev | — |
document_type | text | not null，枚举 8 值：cookie_policy / personal_information_protection / pricing_and_fees / privacy_policy / return_policy / seller_agreement / terms_of_service / tokushoho（类型联合中的 shipping_policy 为预留位、无现档不建行） | 以 documents.json 现有 8 类型为准 |
locale | text | not null，枚举 ja-JP / zh-Hans / en-US（对齐后端三语白名单）；静态 JSON 短码 ja/en 在切换适配层映射 | 与三前台 locale 语义对齐 |
version | integer | not null，默认 1 | 递增整数（法务文档惯例：版本+日期，不做语义化强校验） |
title | text | not null | 文档标题 |
content | text | not null | markdown 载体（与现 JSON content 同构，零转换成本） |
status | text | not null，enum draft / published / archived，default draft | 同一 (document_type, locale) 下至多一条 published（唯一性由 Workflow step 内守卫保证：发布前先 archived 现行版） |
published_at | timestamptz | nullable | 「扩量启动前条款已生效」的审计时间戳来源 |
effective_at | timestamptz | nullable | 法务生效日（可与 published_at 不同） |
published_by | text | nullable | 发布人 actor_id |
created_at / updated_at / deleted_at | timestamptz | 标准三件套 | medusa 约定 |
约束与索引：UNIQUE(document_type, locale, version)；INDEX(document_type, locale, status)；INDEX(published_at)。
| 对象 | 变更 | 内容 |
|---|---|---|
legal_document_revision（新表/新模块） | 新建 | 12 字段全列见上；2 索引 + 1 唯一约束 |
三前台 documents.json（现有） | 保留 | static 模式数据源与回滚兜底；修复批次（T-②③）直接修 JSON 并入版本库 |
前台类型 StoreLegalDocument | 需扩展 | api 模式响应映射：locale 短码映射（ja-JP→ja）、status=published 过滤在前端不可见（API 已过滤） |
| module link / 上游表 | 无新增 | 不触碰 @medusajs/*/@mercurjs/*；不恢复 legal_consent（范围外，drop 迁移维持） |
API 契约（逐字段）
| 路由 | 方法 | 权限域 | 请求 / 响应要点 |
|---|---|---|---|
/admin/legal-document-revisions | GET | admin | query: document_type/locale/status/limit/offset；响应：revision 数组（全字段）+ count |
/admin/legal-document-revisions | POST | admin | body: document_type/locale/version/title/content/effective_at?；创建 draft 行 |
/admin/legal-document-revisions/:id | PUT | admin | body: title/content/effective_at?（仅 draft 可改；published 行不可变——改即新建版本） |
/admin/legal-document-revisions/:id/publish | POST | admin | 触发 publishLegalDocumentRevisionWorkflow；published_by: req.auth_context.actor_id（沿用 review-channel-qualification.ts:43-46 落库范式） |
/store/legal-documents/:type | GET | public | query: locale；返回该 (type, locale) 现行 published 版本（前台消费，见缓存策略） |
Workflow 设计汇总
| Workflow | 状态 | steps 链 | 补偿逻辑 | 事件 |
|---|---|---|---|---|
publish-legal-document-revision | 新增 | validate-revision-content（占位符 + 脚本痕迹双门禁）→ archive-current-published → publish-revision → emit | 逐 step 补偿见 T-①（发布回切 = 原行恢复 published） | legal-document.published |
unpublish-legal-document-revision（应急下线） | 新增（可选切片） | archive-published（目标行置 archived，该 (type,locale) 暂无现行版 → store 端回退 static 兜底） | 恢复原行 published | legal-document.unpublished |
错误码约定
| 错误码 | 语义 |
|---|---|
LEGAL_DOC_PLACEHOLDER_UNFILLED | 占位符门禁：content 含未填占位符，阻断发布并列出清单（文档/行/片段） |
LEGAL_DOC_SCRIPT_ARTIFACT | 脚本痕迹门禁：content 命中 seed/workflow 代码模式，阻断发布 |
LEGAL_DOC_REVISION_NOT_DRAFT | published 行不可改（改即新建版本） |
LEGAL_DOC_NOT_FOUND | revision / 现行版不存在 |
全部 admin 路由走 /admin 全局认证；store 路由 public + publishable key 约定。
前端改动面与 i18n
前端触点（逐端）
| 端 | 改动 | 依据 |
|---|---|---|
| admin-panel | 新增法务文档管理页（revision 列表 + draft 编辑 + 发布动作，复用现有 Table+Drawer 工作台范式）；发布按钮走 /admin/legal-document-revisions/:id/publish | T-①；管理界面骨架复用 seller-qualification-review-actions 同款 Drawer 交互范式（范式引用） |
| storefront / b2b-storefront / h2b-storefront | lib/data/legal-documents.ts 双模化（static|api + 回退兜底）；泄漏修复与占位符修复批次（T-②③）；展示层 legal/[type]/page.tsx 与 LegalDocumentDrawer 无逻辑改动（数据源透明替换） | T-④；现状底座②④⑤ |
| vendor-panel / influencer-panel / referrer-panel | 无改动 | 无法务文档触点（rg 0 命中） |
i18n 三语言 key 规划（en / zhCN / ja，仅 admin-panel）
改动面仅 admin-panel（法务文档管理页）：admin-panel/src/i18n/translations/{en.json, zhCN.json, ja.json} 三文件同步新增，命名空间 legalDocuments.*：
| 新增 key | 用途 |
|---|---|
legalDocuments.list.title / .status / .version / .publishedAt / .actions | 列表页列头 |
legalDocuments.status.draft / .published / .archived | 状态徽标（三态） |
legalDocuments.publish.action / .confirmTitle / .successToast | 发布动作 |
legalDocuments.publish.blockedPlaceholder | 占位符门禁拦截提示（LEGAL_DOC_PLACEHOLDER_UNFILLED 映射） |
legalDocuments.publish.blockedScriptArtifact | 脚本痕迹门禁拦截提示 |
legalDocuments.validation.branchRequired | 条款内容段分支字段未回填提示（DEC-2 门控的 UI 面） |
三前台 i18n 无新增 key（法务文档正文即内容，不走词条机制）。
验收与测试
验收标准（条款段标注 DEC-2）
| # | 验收标准 | 映射 |
|---|---|---|
| A1 | AI 处理专项条款发布并经法务复核（PRD 原文）——条款以 privacy_policy §AI-1~§AI-4 挂载位发布，分支字段非空；DEC-2 门控：正文与分支归属待法务回填后验收 | 条款内容段 |
| A2 | 数据最小化清单评审通过（PRD 原文）——五列清单覆盖 customer/seller 字段面并经评审记录；超范围不存储校验点生效（validator 键闭合测试） | 条款内容段 |
| A3 | 扩量启动前条款已生效（PRD 原文）——revision 表 published_at 权威时间戳可审计；与 AI-3.5-02 首次生产 AI 调用时间戳的先后可验证 | T-① / 前置依赖 |
| A4 | 泄漏修复回归：storefront/b2b 4 份受污染文档 content 中 publishLegalDocumentRevisionWorkflow 等 seed 标识符 0 命中；ja/zh 长度比回到参考带（阈值基线立项定（DEC-5），参考锚点 privacy 5121/1932/2111） | T-② / N-① |
| A5 | 占位符门禁测试：注入含 [氏名]/[Name]/[姓名] fixture 的 draft → 发布被拒（LEGAL_DOC_PLACEHOLDER_UNFILLED）且错误清单逐条列出；占位值回填后发布成功 | T-③ |
| A6 | revision 发布链路单测：draft→published→archived 状态迁移正确；同 (type,locale) 双 published 不可能出现（archive 先行守卫）；补偿路径可回切；LEGAL_DOC_SCRIPT_ARTIFACT 门禁命中拒绝 | T-① |
| A7 | 发布通道决策记录（R-legal-publish-channel）：A/B 对比与选定结论落 PR/文档；双模开关 static|api 行为验证（static = 现状逐字节不变；api 失败回退 static 兜底） | T-④ / 迁移回滚 |
| A8 | 内容级核对收口：其余 6 类文档（cookie_policy 等）AI 条款全文扫描完成并出结论 | 现状底座⑧ |
测试策略（分层）与 L0 门禁
L0 门禁：本文档十要素章节齐备、关键 code anchor 字符串可 rg 命中、既有法务文档域单测可回归（实现期复跑）。
| 层 | 范围 | 明细 |
|---|---|---|
| 既有回归 | 现网行为守卫 | storefront/src/lib/data/__tests__/legal-documents.test.ts（static 读取 + 回退语义）、components/organisms/LegalDocumentDrawer/__tests__/LegalDocumentDrawer.test.tsx |
| 新增单测（后端） | T-①③ | revision 模块 service CRUD；publish Workflow step 链（含双门禁拒绝分支、archive→publish 补偿回切）；store API published 过滤与 locale 映射；admin API 权限域 |
| 新增单测（前端） | T-④ | 双模开关：static 缺省行为不变；api 成功/失败回退两分支；三端同构 |
| 内容回归（脚本） | T-② | 泄漏标识符 0 命中断言 + 长度比带内断言（随 CI 或发布前脚本） |
| 集成点 | 跨模块 | 发布 → 事件 →（缓存失效）→ store 读取新版本；AI-3.5-02 接入段步骤链第 1 步联调（条款生效时间戳 < 首次生产 AI 调用时间戳） |
降级路径说明
本条无 AI 降级路径（不引入 AI 调用）；可用性兜底 = api 读失败回退 static（A7 测试点）。发布门禁失败 = 阻断发布属业务内容门控（非法务文档不可发布），与 AI 可选增强范式（NFR-3.8-01「未配置/故障即跳过」）分属两类语义，显式区分不混同。
风险与开放问题
已识别风险
高
线上法务文档 ja 正文泄漏（R-privacy-ja-leak / RK-03，critical）
storefront/b2b 两端 privacy_policy-ja 与 terms_of_service-ja 共 4 份文档泄漏 seed 脚本（len 6170/6103，含
publishLegalDocumentRevisionWorkflow 等代码标识符）——线上法务文档存在非正文残留，质量缺陷可见。缓解：T-② 修复（P1 范围内顺手修复，文本清洗随时可做）+ 发布前脚本痕迹门禁防再发。
高
DEC-2 未决 → 条款不能发布 → 翻译扩量持续搁置
不决策的后果（PRD §2.5 DEC-2 原文）：翻译扩量须持续搁置；存在合规暴露。缓解：两段式拆分——技术管道段不受阻先行；数据流清单（发送字段范围/目标服务/是否含可识别个人信息）先行交付法务作为 C2 核实输入。
高
APPI 信息管理者联系方式线上不可用（R-legal-placeholder）
三语正文
[氏名]/[住所]/[メール/電話] 等占位未填——法务效力存疑（RK-03 同体）。缓解：门禁逻辑（T-③）立即开工；占位真实值由法务提供后一次性回填；回填前门禁在存量文档上的命中即缺陷清单（可直接交付法务催办）。
中
发布通道未定（R-legal-publish-channel / RK-10，high）
static 打包发版耦合：更新需三端各自改 JSON → 构建 → 发版，条款「发布生效」时效无法承诺、生效时间戳无权威数据源。缓解：本卡已给 A/B 对比与推荐 B——按推荐先行动即决策记录成立；static 模式修复（T-②③）与候选选择无关，先行。
低
其余 6 类文档未做 AI 条款全文扫描
内容级核对仅抽样（隐私政策/服务条款正文）。缓解：列入实施期清单（A8 收口项），扫描脚本随 T-② 门禁正则集复用。
前提与假设
假设
- PRD V1.4 双层口径锁死：①底座已建成（三语隐私政策/脱敏/加密均在代码层成立）；②生产未配置任何 AI 服务（部署权威口径，风险 C1 已更正）——两态不得混同；
- 条款正文、占位真实值、最小化清单评审均为法务/合规责任（技术侧 references_only，不起草）；
- drop 迁移的历史表名仅作命名与结构参考，不恢复 legal_consent（范围外）。
前置决策点
Blocker 二分表（禁止因阻塞点否定整条 TDD）
| Blocker | 类型 | 阻塞什么 | 可并行做什么 |
|---|---|---|---|
| blocker D-dec2（C2 条款时点与分支归属，PRD §2.5/§8.1 C2） | 管理层决策 + 法务 | 仅阻塞条款内容段（条款正文起草、分支回填、条款发布生效）及其下游传导（AI-3.5-02 翻译扩量，顺序不可颠倒）；不阻塞技术管道段全部四项 | 技术管道段 T-①~④ 全量并行开工；数据流清单先行交付给法务作为 C2 核实输入；挂载位结构与占位章节可先行落（不含正文） |
| blocker R-privacy-ja-leak（ja 泄漏，RK-03 critical） | 代码缺陷（非外部阻塞） | 不阻塞任何外部工作 | P1 范围内顺手修复（T-②）：文本清洗随时可做；防再发门禁随 T-① 落地；建议与 R-legal-placeholder 同一批次修复 |
| blocker R-legal-placeholder（占位符，RK-03 同体） | 代码缺陷 + 内容缺口 | 技术侧门禁不阻塞；占位真实值缺法务输入（[氏名]/[住所] 等联系方式） | 门禁逻辑（T-③）立即开工；真实值由法务提供后一次性回填；回填前门禁在存量文档上的命中即缺陷清单（可直接交付法务催办） |
| blocker R-legal-publish-channel（发布通道未定，RK-10 high） | 架构决策（首节先决） | 阻塞「条款发布管道设计定案」（T-① 实施排期与 T-④ 切换动作）；不阻塞条款内容起草（法务侧） | 本卡 T-④ 已给 A/B 对比与推荐 B——按推荐先行动即决策记录成立；static 模式修复（T-②③）与候选选择无关，先行 |
依赖与下游消费
- 内部依赖：模板十要素骨架（已消费）；
- AI-3.5-02（强）：其服务接入段步骤链第 1 步「C2 条款关闭」的所有方 = 本卡；扩量解锁以本卡 A1/A3 验收为闸；
- AI-3.9-04（轻）：发布复核钩子/巡检机制引用其框架，交叉引用不重复设计；
- AI-3.5-03：场景翻译的合规评估引用本条挂载位范式；
- 外部资源：法务/合规（条款正文、分支归属、占位真实值、最小化清单评审）——DEC-2 关联，不阻塞管道段。
待决问题清单
- DEC-2：C2 条款启动时点与委托/越境分支归属——法务何时完成服务商数据处理条款核实（含数据是否用于模型训练）并回填分支？
- R-legal-publish-channel：发布通道 A/B 选定——是否采纳推荐候选 B（DB/后台化动态发布）？决策记录落 PR/文档后 T-① 即开工。
- 占位符真实值（代表者/住所/連絡先/個人情報保護管理者等）——法务提供的时点与责任方确认。
- 其余 6 类文档（cookie_policy 等）AI 条款全文扫描的收口时点（实施期 A8）。
- C6 前瞻：医疗类目「要配慮」场景、对话数据场景的条款扩展——随对应能力立项评估（references_only）。
附录：溯源对照
本文档由 docs/reports/ai-module-prd/tdd/AI-3.9-01-appi-compliance-foundation.md（文档版本 v1.0，2026-10-26）转换生成。输出章节与源章节映射如下（Preserved = 保留原文内容；Summarized = 摘要化重组；Inferred = 转换侧推断标注）：
| 本文档章节 | 源章节 | 处理方式 |
|---|---|---|
| 摘要 | 元数据表 + §1 溯源与现状 + §4.0 两段式总览 | Summarized |
| 关键概念 | 头部口径声明 + §1.2 关联映射 + §4.0/§6.1 术语 | Summarized |
| 方案设计 · 两段式总览 + 设计红线 | §4.0（含 AGENTS.md 红线） | Preserved |
| 方案设计 · 现状底座与数据质量缺陷 | §1.3 三态判定 + §2.1 涉及模块清单 ①~⑧ + §2.2 三类标注 + §3.3 新发现 N-①~④（并入④/③行内） | Preserved（泄漏 len 数值、正则、锚点逐字保留） |
| 方案设计 · T-① 版本化发布模块 | §4.1 T-①（Workflow steps 表 / 缓存候选 / 双模开关） | Preserved |
| 方案设计 · T-② ja 泄漏修复 | §4.1 T-②（修复范围 / 清除动作 / 防再发门禁 / 回归断言） | Preserved |
| 方案设计 · T-③ 占位符修复与发布门禁 | §4.1 T-③（正则清单 / 错误码 / 存量修复） | Preserved |
| 方案设计 · T-④ 发布通道先决 | §4.1 T-④（A/B 对比表 + 推荐 B） | Preserved |
| 方案设计 · 条款内容段 | §4.2（挂载位 §AI-1~§AI-4 / 要配慮机制位 / 数据最小化清单） | Preserved |
| 方案设计 · 迁移与回滚 | §10（migration / seed 兼容 / 回滚表 / 上线顺序） | Preserved |
| 数据模型与 API 契约 | §4.1 T-① 实体字段表 + §4.3 数据模型汇总 + §4.5 API 契约与错误码 + §4.4 Workflow 汇总 | Preserved |
| 前端改动面与 i18n | §4.6 前端触点 + §4.7 i18n key 规划 | Preserved |
| 验收与测试 | §8.1 验收标准 A1-A8 + §8.2 测试策略与 L0 门禁 + §5.3 降级路径说明 | Preserved |
| 风险与开放问题 | §3.2/§3.3 缺口 + §7 blocker 表（风险分级为转换侧判定，与 findings 记录的 critical/high 标注对齐） | Inferred |
| 前置决策点 | §7 四 blocker 二分表 + §6.1 C2 双分支 + §1.2 决策映射 | Preserved |
| 图1 / 图2 / 图3 / 图4 | §4.0 / §4.1 T-① / §4.4 / §4.1 T-① 实体表 | Inferred（依源表格与文字绘制的可视化视图） |
溯源说明
源文档所有锚点在执行 run 以 rg/sed/脚本逐条复核，上游卡内锚点与复核实际行号漂移处已按「来源锚点（复核：实际行号）」双写标注保留。内部流程标识（任务批次号、执行 run 标识、findings 条目引用）属过程元数据，不影响任何契约性内容（实体字段表、API 契约、Workflow step 链、错误码、门禁正则、验收标准均完整保留）。