W04 两表联动数据方案范式

编号：W3 ｜ 版本：V1.1 ｜ 日期：2026-08-26 ｜ 状态：方案设计（V1.0 更新版，双向联动）
维度：通用 ｜ 归属：全域 ｜ owner：全域
上游版本：V1.0（两表联动_2026-08-26_0932/产出/两表联动数据方案_2026-08-26_0932.md）
本版变更：①新增「双向联动」设计（关联字段/触发方式/同步范围/事务性/异常回滚）；②落实异源双模校核 P0 整改 C1（50/51 口径）、C2（全量重建 vs 指纹增量）、C3（R19 归档 vs 只保留当前版）、C5（扫描路径统一）。
配套权威源：发布态 Word 原件 spec\3.行政法规\范式\两表联动数据方案_V1.1_2026-08-26_1000.docx（与本范式内容一致）；判定基准 _tools/两表联动数据方案技术标准.md；索引 README/两表联动数据方案/README.md。
上位规范：本方案是全域主登记表 spec\3.行政法规\文档登记表.json（SSOT）+ 子表 映射台账.xlsx 的实现标准，受 N1（命名规则）/ W1（工作流）/ W2（生命周期工具链 R7–R12 审批归档）约束；命名、时间戳、四件套、归档均严格遵循 N1 §三 与 W1 R16–R19。

〇、版本变更说明（V1.0 → V1.1）

一、方案总览（核心架构，双向版）

              ┌─────────────────────────────────────────────┐
              │        主表：文档登记表.json（SSOT）           │
              │  汇总字段 stats + 状态字段 status + 明细条目   │
              └───────────────┬─────────────────────────────┘
                              │ ① 主→子（明细同步）  ③ 子→主（汇总/状态刷新）
                              ▼        ▲
              ┌───────────────────────────────┐
              │   子表：映射台账.xlsx（明细消费层） │
              │   五件套引用明细 + 场景映射明细     │
              └───────────────────────────────┘
                              │ 只读消费
                              ▼
                 五件套（emmx / 说明.md / html / svg）

• 主表（P）＝ 文档登记表.json：唯一事实源，存汇总（stats）、状态（status）、明细条目。
• 子表（C）＝ 映射台账 xlsx：消费层明细，每条引用通过 ref_id 关联主表，承载五件套「引用 SOP/引用规范」与场景映射。
• 双向联动：主表增/改/删 → 子表引用明细自动同步；子表引用变动 → 主表汇总/状态字段刷新。
• 原「静态一览表.md/.docx」降级为历史快照，由登记表可读版替代。

二、两表定义与关联字段（新增）

2.1 主表（P：文档登记表.json，汇总/状态层）

2.2 子表（C：映射台账.xlsx，明细/消费层）

2.3 关联字段映射（双向联动锚点）

三、表结构定义（沿用 V1.0，落实 C5/C1）

3.1 主表 schema V2（扩展）

{
  "meta": { "schema": "REG-V2", "version": "2.0", "generated": "2026-08-26_1000",
            "fingerprint": "sha256:…", "scenarios": { /* 见 §三.3 */ } },
  "stats": { "范式": 20, "SOP": 11, "skill_SKILLmd": 15, "expert_agentmd": 3, "正式基准_docx": 2, "合计": 51 },
  "技术规范_范式": [{ "id": "W2", "name": "W2_全域文件生命周期工具链技术标准.md", "dim": "通用",
    "owner": "全域", "version": "1.0.0", "path": "spec\3.行政法规\范式\W2_全域文件生命周期工具链技术标准.md",
    "hash": "sha256:…", "updated": "2026-08-26", "status": "active" }],
  "SOP": [ … ], "skill_SKILLmd": [ … ], "expert_agentmd": [ … ], "正式基准_docx": [ … ]
}

C1 落实：stats 统一为「范式 20 / 合计 51」（含已补登的 W2）；全文不再出现「50 项」与「51 项」并存。
C5 落实：path 统一「相对工作区根 F:/400.WorkBuddy_origin」，扫描源与写回路径归一化（见 §九.1）。

3.2 子表 schema（映射台账.xlsx）

3.3 场景映射表（C4 落实：独立配置文件）

场景映射迁入独立配置 _tools/scenarios.json（人工维护），refresh_register.py 读取后写入主表 meta.scenarios；子表据此生成场景引用明细。

四、双向联动机制（新增核心）

4.1 联动触发方式（三种）

4.2 数据同步范围

• 主→子（明细同步）：主表记录的增/改/删，同步到子表所有引用该 id 的明细行，字段级同步 ref_version、ref_status、path 投影。
• 子→主（仅汇总/状态刷新）：子表明细变动，仅刷新主表 stats（计数）与 status/updated（状态复核），不回写主表明细本体——此为防循环关键。

4.3 双向一致性保障（三层校验 + 事务）

1. Schema 校验（写前）：主表 JSON 结构、必填字段、id 唯一、stats 与数组长度一致。
2. 引用完整性（消费前）：子表每个 ref_id 必须命中主表 id；范式 owner 必须命中 SKILL.md/expert 的 owner；脱节即 sys.exit 阻断。
3. 文件指纹校验：主表 path 文件存在且 hash 匹配；不匹配 → 自动重扫自愈，仍失败置 status=deprecated + 告警（按 C3 规则连续 2 次才置位）。

4.4 幂等与防循环

• 幂等：子表唯一键 ref_id + scenario 去重；meta.fingerprint 不变则跳过派生重生成；重复触发不重复写入。
• 防循环：明确「子→主只刷汇总/状态，不写明细」，切断双向写死循环；主表写与子表写同事务串行化。

五、数据同步机制（沿用 V1.0，落实 C2 职责分层）

5.1 同步方向与策略（C2 修正：登记表永远全量重建）

refresh_register.py（主表层，永远全量重建）：
  扫描 spec\3.行政法规\skills\my-experts → 全量条目 → 校验(id唯一/path存在)
  → 全量重建主表（tmp → os.replace 原子写）   ◀── 不因 fingerprint 不变而跳过
  → 计算 meta.fingerprint → 与旧 fingerprint 比对：
      不同 → 重写 README 可读版 + 置「子表/五件套需重生成」标记 + 触发子表同步
      相同 → 仅刷新时间戳，不重写派生产物

gen_logic_map_v8.py（消费层，fingerprint 增量）：
  读主表 → 过滤 active → 读 fingerprint：
      fingerprint 不变 且 上版子表/五件套存在 → 跳过重生成（仅刷新时间戳）
      否则 → 全量重生成子表 + 五件套

六、事务性与异常回滚（新增核心）

6.1 事务模型（ACID）

6.2 异常处理

6.3 回滚机制

1. 写前备份：主表 文档登记表.json.bak + 子表 _映射台账_<ts>.xlsx.bak。
2. 原子写：json.dump 到 .tmp → os.replace() 原子替换。
3. 失败回滚：事务内任一步失败 → os.replace(.bak, 正式) 还原双表，输出回滚日志。
4. 回滚后：告警 + 保留差异清单；日更下周期自愈；连续失败超阈值升级人工。

七、联动逻辑（沿用 V1.0，落实 C3 归档粒度）

7.1 冲突处理（优先级）

7.2 归档粒度（C3 修正）

• 五件套实体（emmx/html/svg/说明.md）：旧目录按 R19 移动归档（非删除） → 「活动区只保留当前版 + 归档区保留历史版」。
• 子表台账 xlsx：单文件追加历史行（不覆盖），保留历周快照。
• 统一表述：「五件套实体按 R19 归档旧版（移动非删除、可回溯）；台账 xlsx 内部追加历史行（不破坏历史）」。

八、运行流程与运维（沿用）

九、关键实现细节（沿用，落实 C5）

1. 扫描源：spec\3.行政法规\范式\*.md|*.docx、spec\3.行政法规\SOP\*.md、~/.workbuddy/skills/*/SKILL.md、plugins/marketplaces/my-experts/plugins/*/agents/*.md；写回登记表 path 统一为「相对工作区根 F:/400.WorkBuddy_origin」（C5）。
2. hash：sha256 文件指纹；meta.fingerprint = 全部条目 hash 拼接后再哈希。
3. version 三方对齐：范式.version ↔ SKILL.md frontmatter ↔ 专家 md version，不一致告警进差异清单。
4. 渲染器：README 可读版与子表由同一渲染函数从主表生成，杜绝手改漂移。
5. 原子写：json.dump 到 .tmp → os.replace()；事务写前双表 .bak 备份。

十、潜在风险点（沿用 + 新增双向联动风险）

十一、可落地实施步骤（沿用 + 双向联动阶段）

附：与现有规范的关系

• 遵守 N1 §5.7（SOP/范式/一览表命名）、W1 §3.6 R16–R19（五件套治理）、W2（生命周期工具链 13 项）。
• 新脚本归入 _tools/（命名/四件套工具链），遵守 N1 §九工具链门禁。
• 双向联动事务/回滚设计对齐 W2 的 R7–R9（审批）/R10–R12（归档）工具链规格。
• 双类交付物：refresh/联动脚本属工具链（Class 工具），五件套属 R16 治理产物，不受 Class A/B 四件套约束（W1 R17 已显式豁免）。