W05 两表联动数据技术标准
C:/Users/xub/.workbuddy/spec/3.行政法规/范式/W05_两表联动数据技术标准_V1.1.0_2026-09-03_0956.docx前言
目次
前言
1 版本变更说明（V1.0 → V1.1）
2 方案总览（核心架构，双向版）
3 两表定义与关联字段（新增）
3.1 主表（P：文档登记表.json，汇总/状态层）
3.2 子表（C：映射台账.xlsx，明细/消费层）
3.3 关联字段映射（双向联动锚点）
4 表结构定义（沿用 V1.0，落实 C5/C1）
4.1 主表 schema V2（扩展）
4.2 子表 schema（映射台账.xlsx）
4.3 场景映射表（C4 落实：独立配置文件）
5 双向联动机制（新增核心）
5.1 联动触发方式（三种）
5.2 数据同步范围
5.3 双向一致性保障（三层校验 + 事务）
5.4 幂等与防循环
6 数据同步机制（沿用 V1.0，落实 C2 职责分层）
6.1 同步方向与策略（C2 修正：登记表永远全量重建）
7 事务性与异常回滚（新增核心）
7.1 事务模型（ACID）
7.2 异常处理
7.3 回滚机制
8 联动逻辑（沿用 V1.0，落实 C3 归档粒度）
8.1 冲突处理（优先级）
8.2 归档粒度（C3 修正）
9 运行流程与运维（沿用）
10 关键实现细节（沿用，落实 C5）
11 潜在风险点（沿用 + 新增双向联动风险）
12 可落地实施步骤（沿用 + 双向联动阶段）
13 与现有规范的关系
本标准规定利衡辨全域「文档登记表（主表）与映射台账（子表）双向联动」数据方案的技术要求，是全域主登记表 `specs/文档登记表.json`（SSOT）与子表 `映射台账.xlsx` 的实现标准。
版本：V1.1 ｜ 编制日期：2026-09-03 ｜ 状态：正式基准 · 全域强制
适用范围：全域文档登记表与映射台账的双向联动、事务性、异常回滚及运维实现
权威关系：本文与 `specs/范式/W3_两表联动数据方案范式.md` 内容一致、互为备份；冲突时以本发布态为准
上位规范：受 N1（命名规则）/ W1（工作流）/ W2（生命周期工具链）约束；命名、时间戳、四件套、归档严格遵循 N1 §三 与 W1 R16–R19
排版说明（2026-09-03）：本版为按蓝本《WorkBuddy应用技术标准》V1.3.0 的排版对齐修订——补封面 / 静态目次 / 两类认知图 / 页脚「第X页共Y页」/ 表格规范；正文条款与内容保持不变
1 版本变更说明（V1.0 → V1.1）
| 项 | V1.0 问题 | V1.1 处理 |
|---|---|---|
| C1 | 50/51 项口径矛盾 | 统一为「当前基线 50（范式 19）→ 补 W2 后目标 51（范式 20）」，全文单一口径 |
| C2 | 全量重建 vs 指纹增量互斥 | 职责分层：登记表永远全量重建，fingerprint 只控五件套重生成（见 §五.1） |
| C3 | R19 归档 vs 只保留当前版冲突 | 五件套实体=移动归档、台账 xlsx=追加历史行（见 §七） |
| C5 | 扫描路径相对/绝对混用 | 统一「相对工作区根 F:/400.WorkBuddy_origin」为登记表 path 基准（见 §三） |
| **新增** | 无双向联动 | 新增 §二/§四/§六 双向联动、事务性、异常回滚 |
2 方案总览（核心架构，双向版）
图2-1 两表联动数据治理逻辑思维简图
注：本图回答「为什么这样组织」——自顶向下的分层认知框架与层间依赖关系
┌─────────────────────────────────────────────┐ │ 主表：文档登记表.json（SSOT） │ │ 汇总字段 stats + 状态字段 status + 明细条目 │ └───────────────┬─────────────────────────────┘ │ ① 主→子（明细同步） ③ 子→主（汇总/状态刷新） ▼ ▲ ┌───────────────────────────────┐ │ 子表：映射台账.xlsx（明细消费层） │ │ 五件套引用明细 + 场景映射明细 │ └───────────────────────────────┘ │ 只读消费 ▼ 五件套（emmx / 说明.md / html / svg）
· 主表（P）＝ 文档登记表.json：唯一事实源，存汇总（`stats`）、状态（`status`）、明细条目。
· 子表（C）＝ 映射台账 xlsx：消费层明细，每条引用通过 `ref_id` 关联主表，承载五件套「引用 SOP/引用规范」与场景映射。
· 双向联动：主表增/改/删 → 子表引用明细自动同步；子表引用变动 → 主表汇总/状态字段刷新。
· 原「静态一览表.md/.docx」降级为历史快照，由登记表可读版替代。
3 两表定义与关联字段（新增）
3.1 主表（P：文档登记表.json，汇总/状态层）
| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | 主键 | 全局唯一编码（B11/S01/SK08/EX01/W2…），主表唯一标识 |
| `owner` + `version` | 复合业务键 | 关联 范式 ↔ SKILL.md ↔ 专家 md |
| `spec_id` | 外键 | 专家插件目录 ID（kebab-case） |
| `path` | 引用键 | 相对工作区根 `F:/400.WorkBuddy_origin` 的路径（C5 统一） |
| `hash` | 指纹 | sha256 内容指纹 |
| `status` | 状态字段 | `active` / `deprecated`（**子→主刷新对象**） |
| `updated` | 变更日期 | `YYYY-MM-DD`（最后变更，子→主刷新对象） |
| `stats` | 汇总字段 | 各维度计数（**子→主刷新对象**） |
| `meta.fingerprint` | 全表指纹 | hash(全部条目 hash 拼接) |
3.2 子表（C：映射台账.xlsx，明细/消费层）
| 字段 | 类型 | 说明 |
|---|---|---|
| `ref_id` | 外键 | 指向主表 `id`（**主→子同步锚点**） |
| `ref_type` | 类型 | 引用类型：范式/SOP/skill/expert/docx |
| `scenario` | 场景 | 所属场景（A1–F6） |
| `ref_version` | 版本投影 | 主表 `version` 的副本（主→子同步字段） |
| `ref_status` | 状态投影 | 主表 `status` 的副本（主→子同步字段） |
3.3 关联字段映射（双向联动锚点）
| 主表字段 | 子表字段 | 基数 | 联动方向 |
|---|---|---|---|
| `id` | `ref_id` | 1:N | 主→子（明细增删改）；子→主（stats 重算） |
| `owner`+`version` | 1:1 | 跨维度对齐（范式↔SKILL.md↔专家md） | |
| `spec_id` | 1:1 | 专家外键一致性 | |
| `status`/`updated` | `ref_status` | 1:N | 主→子状态投影；子→主状态复核 |
4 表结构定义（沿用 V1.0，落实 C5/C1）
4.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": "specs/范式/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）。
4.2 子表 schema（映射台账.xlsx）
| 列 | 说明 |
|---|---|
| `ref_id` | 外键→主表 id（唯一键 `ref_id + scenario`） |
| `ref_type` / `scenario` / `ref_version` / `ref_status` | 引用明细 + 主表投影 |
| `reuse` | 跨场景复用标注（Ⓡ） |
4.3 场景映射表（C4 落实：独立配置文件）
场景映射迁入独立配置 `_tools/scenarios.json`（人工维护），`refresh_register.py` 读取后写入主表 `meta.scenarios`；子表据此生成场景引用明细。
5 双向联动机制（新增核心）
图5-1 两表联动数据治理生命周期逻辑结构图
注：本图回答「每一步做什么」——各阶段触发条件、责任人、校验方式与例外回路
5.1 联动触发方式（三种）
| 触发 | 主表动作 | 子表自动同步 | 子表动作 | 主表自动同步 |
|---|---|---|---|---|
| **新增（选择）** | 新增记录（补登 W2 / 新增 skill） | ① 插入引用该 id 的明细行；② stats 计数 +1 | 新增引用行（新场景引用某 id） | ① stats 重算；② 被引用条目 status 复核（孤儿→候选 deprecated） |
| **修改** | 改 version/status/path/hash | ① 刷新对应明细行 `ref_version`/`ref_status` 投影 | 改 `ref_id`/`ref_type`/`scenario` | ① stats 重算；② 新旧引用条目 status 复核 |
| **删除** | 删除/废弃记录 | ① 删除或标记失效对应明细行；② stats 计数 -1 | 删除引用行 | ① stats 计数 -1；② 相关汇总/状态刷新 |
5.2 数据同步范围
· 主→子（明细同步）：主表记录的增/改/删，同步到子表所有引用该 `id` 的明细行，字段级同步 `ref_version`、`ref_status`、`path` 投影。
· 子→主（仅汇总/状态刷新）：子表明细变动，仅刷新主表 `stats`（计数）与 `status`/`updated`（状态复核），不回写主表明细本体——此为防循环关键。
5.3 双向一致性保障（三层校验 + 事务）
· Schema 校验（写前）：主表 JSON 结构、必填字段、id 唯一、`stats` 与数组长度一致。
· 引用完整性（消费前）：子表每个 `ref_id` 必须命中主表 id；范式 `owner` 必须命中 SKILL.md/expert 的 `owner`；脱节即 `sys.exit` 阻断。
· 文件指纹校验：主表 `path` 文件存在且 `hash` 匹配；不匹配 → 自动重扫自愈，仍失败置 `status=deprecated` + 告警（按 C3 规则连续 2 次才置位）。
5.4 幂等与防循环
· 幂等：子表唯一键 `ref_id + scenario` 去重；`meta.fingerprint` 不变则跳过派生重生成；重复触发不重复写入。
· 防循环：明确「子→主只刷汇总/状态，不写明细」，切断双向写死循环；主表写与子表写同事务串行化。
6 数据同步机制（沿用 V1.0，落实 C2 职责分层）
6.1 同步方向与策略（C2 修正：登记表永远全量重建）
refresh_register.py（主表层，永远全量重建）： 扫描 specs/skills/my-experts → 全量条目 → 校验(id唯一/path存在) → 全量重建主表（tmp → os.replace 原子写） ◀── 不因 fingerprint 不变而跳过 → 计算 meta.fingerprint → 与旧 fingerprint 比对： 不同 → 重写 README 可读版 + 置「子表/五件套需重生成」标记 + 触发子表同步 相同 → 仅刷新时间戳，不重写派生产物 gen_logic_map_v8.py（消费层，fingerprint 增量）： 读主表 → 过滤 active → 读 fingerprint： fingerprint 不变 且 上版子表/五件套存在 → 跳过重生成（仅刷新时间戳） 否则 → 全量重生成子表 + 五件套
| 维度 | 决策 | 理由 |
|---|---|---|
| 主表刷新 | **全量重建**（永远） | 体量小、免增量状态、天然幂等 |
| 子表/五件套消费 | **fingerprint 增量** | fingerprint 不变则跳过重生成 |
| 双向同步 | 主→子明细、子→主汇总/状态 | 事务内原子提交 |
| 双端同步 | specs/ 权威 + 3.Skill_技术规范/ 展示副本 md5 校验，不一致仅告警不自动覆盖 | 零破坏基线 |
7 事务性与异常回滚（新增核心）
7.1 事务模型（ACID）
| 性质 | 实现 |
|---|---|
| **原子性** | 主表写 + 子表写在同一事务：写前双表备份 `.bak`，全部成功后提交，任一步失败整体回滚 |
| **一致性** | 提交后校验 `ref_id` 全命中、`stats` 与实际计数一致，不一致触发回滚 |
| **隔离性** | 日更 automation（`automation-1787712201757`）与手动触发用文件锁（`.lock`）串行化，防并发写冲突 |
| **幂等性** | 唯一键去重 + fingerprint 比对，重复触发不重复写 |
7.2 异常处理
| 异常 | 处理 |
|---|---|
| 引用脱节（ref_id 无主表 id） | 阻断 + 差异清单，不产生残缺子表 |
| id 冲突 / schema 校验失败 | `sys.exit(1)` + 差异清单 |
| 文件指纹不匹配 | 自动重扫自愈；仍失败置 deprecated + 告警（连续 2 次才置位） |
| 双端 md5 不一致 | 仅告警，不自动覆盖（specs/ 为权威） |
| 主表 JSON 解析失败 | 回退 `.bak` + 告警，不阻塞日更 |
7.3 回滚机制
· 写前备份：主表 `文档登记表.json.bak` + 子表 `_映射台账_<ts>.xlsx.bak`。
· 原子写：`json.dump` 到 `.tmp` → `os.replace()` 原子替换。
· 失败回滚：事务内任一步失败 → `os.replace(.bak, 正式)` 还原双表，输出回滚日志。
· 回滚后：告警 + 保留差异清单；日更下周期自愈；连续失败超阈值升级人工。
8 联动逻辑（沿用 V1.0，落实 C3 归档粒度）
8.1 冲突处理（优先级）
| 冲突场景 | 处理 | 优先级 |
|---|---|---|
| 主表 vs 文件系统不一致 | 以文件系统为准（refresh 全量重建覆盖） | 文件系统 > 主表 |
| 主表 vs 子表引用脱节 | 以主表为准，子表重生成 | 主表 > 子表 |
| 双端副本不一致 | specs/ 权威，F 盘只读，md5 不符仅告警 | specs > F 盘副本 |
| 同一 id 多维度重复 | refresh 启动校验报错，阻断 | 阻断 > 容忍 |
8.2 归档粒度（C3 修正）
· 五件套实体（emmx/html/svg/说明.md）：旧目录按 R19 移动归档（非删除） → 「活动区只保留当前版 + 归档区保留历史版」。
· 子表台账 xlsx：单文件追加历史行（不覆盖），保留历周快照。
· 统一表述：「五件套实体按 R19 归档旧版（移动非删除、可回溯）；台账 xlsx 内部追加历史行（不破坏历史）」。
9 运行流程与运维（沿用）
| 项 | 配置 |
|---|---|
| 触发 | `automation-1787712201757` 日更：每日 06:30（`FREQ=DAILY;BYHOUR=6;BYMINUTE=30`，cwd=`F:\400.WorkBuddy_origin`）｜原周更 `automation-1787567722214`（每周一 09:00）已退役，由日更接管主表对账 |
| 手动触发 | 资产变更时 agent 手动执行 refresh + gen + check_deliverables（含复验） |
| 日志 | `~/.workbuddy/logs/YYYY-MM-DD/register-sync.log`（主表）+ `logic-map-sync.log`（子表）+ 事务回滚日志 |
10 关键实现细节（沿用，落实 C5）
· 扫描源：`specs/范式/*.md|*.docx`、`specs/SOP/*.md`、`~/.workbuddy/skills/*/SKILL.md`、`plugins/marketplaces/my-experts/plugins/*/agents/*.md`；写回登记表 path 统一为「相对工作区根 F:/400.WorkBuddy_origin」（C5）。
· hash：sha256 文件指纹；`meta.fingerprint` = 全部条目 hash 拼接后再哈希。
· version 三方对齐：范式.version ↔ SKILL.md frontmatter ↔ 专家 md version，不一致告警进差异清单。
· 渲染器：README 可读版与子表由同一渲染函数从主表生成，杜绝手改漂移。
· 原子写：`json.dump` 到 `.tmp` → `os.replace()`；事务写前双表 `.bak` 备份。
11 潜在风险点（沿用 + 新增双向联动风险）
| # | 风险 | 影响 | 缓解 |
|---|---|---|---|
| R1 | 主表滞后（W2 未登记） | 首轮基线不准 | 阶段 0 先基线重建（补 W2）后冻结 |
| R2 | 双端副本漂移 | 展示误导 | 只读副本 + md5 告警，不自动覆盖 |
| R3 | 场景映射演化不同步 | 子表漏场景 | scenarios 独立配置 + refresh 一并重建 |
| R4 | 自动化无人值守失败 | 日更缺失 | 幂等重跑 + 日志 + 次日自愈 |
| R5 | 误扫/误标 deprecated | 主表误判 | 连续 2 次扫描缺失才置位 |
| R6 | 旧一览表与主表冲突 | 用户困惑 | 旧一览表加「历史快照」标注 |
| **R7** | **双向写循环** | 死循环/重复写 | 子→主仅刷汇总/状态、不写明细 + 文件锁串行化 |
| **R8** | **事务中断（半提交）** | 双表不一致 | 写前双表 .bak + 原子写 + 失败回滚 |
| **R9** | **并发触发冲突** | 覆盖丢失 | `.lock` 文件锁 + 唯一键去重 |
12 可落地实施步骤（沿用 + 双向联动阶段）
| 阶段 | 内容 | 验收标准 |
|---|---|---|
| **0. 基线** | 补登 W2；手工重建 baseline（补齐 hash/status/updated） | 主表 51 项与 specs 实际文件 100% 对账一致 |
| **1. SSOT 化** | 新增 `refresh_register.py`（扫描+校验+原子写+渲染）；schema V2 | 双端 refresh 输出一致；id 唯一校验通过 |
| **2. 双向联动** | 主表↔子表双向同步引擎（明细投影 + 汇总/状态刷新 + 事务） | 增/改/删三触发全链路一致；幂等无重复写 |
| **3. 事务回滚** | 双表 .bak 备份 + 原子写 + 失败回滚 + 文件锁 | 模拟半提交失败可完整回滚；并发无覆盖丢失 |
| **4. 消费方切换** | `v7 → v8`：读主表 + meta.scenarios；check_s06_sync 升级 | v8 空跑输出与 v7 结构一致 |
| **5. 联动闭环** | 更新 automation prompt；日志落盘；旧一览表标注 | 手动触发全链路退出码 0 |
| **6. 验收运维** | 连跑 2 周期验证幂等/一致性/回滚/日志 | 2 周期产物 hash 幂等；双端 md5 一致；0 阻断 |
13 与现有规范的关系
· 遵守 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 已显式豁免）。
宪法 ＞ 基本法 ＞ 行政法规 ＞ 地方法规 ＞ 地方规章