数据产品体系总体建设方案（修订版）
版本：v1.0 · 日期：2026-10-24 · 性质：实施计划草案，未获批实施 基础版本：v0.1（docs/20）。本版按所有者 2026-10-24 修订任务书完成修订，修改记录见 docs/28。 标注：【事实】有代码/运行/文档证据；【推论】基于事实的判断；【建议】推荐方案；【待决策】所有者定夺；【待验证】证据不足。 约束声明：本方案未修改任何代码、配置、正式协议、生产环境与项目数据；方案中的推荐一律不视为已批准。
第一章 系统总体定义
（保留 v0.1 表述，实施视角收敛自元协议设计稿 B）
1.1 系统是什么【建议·待元协议定稿确认】
数据产品体系是一个生产系统：把外部信息源与业务需求，加工为"每条事实可回答来源、验证状态、责任归属"的结构化数据产品，并通过人读网站与 AI 入口（API/MCP）对外服务。由四种职能构成：规则（协议）、管理（控制）、操作（执行）、产品（模块）。
1.2 管理对象（五类）【建议】
数据产品（5 个，可增）、数据资产、任务、规则（全局协议→专项协议→项目协议→模块契约）、公共能力。
1.3 从外部数据到可信产品的通路【事实+建议】
外部来源/业务需求 → [执行]采集结构化 → [执行]校验闸 → [控制]差异识别与登记
→ [人]审核批准 → [执行+控制]guarded 发布 → 网站/API/MCP 服务
→ [控制]健康探测/变更监测/结果回传 → 问题工单 → 回到采集或规则修订
1.4 自身状态判断
三级健康矩阵（任务级/项目级/体系级）；单点绿色不构成健康判定；"未验证"是合法且必须如实显示的状态。
1.5 问题发现、恢复与演进【事实】
site-status 六维探测 → 异常自动登记 items；失败 classifyFailure 11 类；/api/runs/:id/retry；items 六态（关闭需证据）；P-06 版本流程 + ADR。
第二章 总体架构与职责模型
2.1 四层职责（权威 = P-02 v1.0.0）
| 层 | 职责 | 当前物理承载【事实】 | 不负责 |
|---|---|---|---|
| 协议层 | 说什么算什么 | Protocol System（独立仓 + protocol.constraintlab.io v1.1.0） | 执行、状态管理 |
| 控制层 | 决定谁何时做什么 | data-workbench（items/site-status/releases/notify/scheduler 决策面） | 亲自执行、业务规则 |
| 执行层 | 把它做了并留证据 | workbench 内核（runs/exec/tasks/node-runs）+ 各项目 scripts/ + 各站 CI/CF | 发明规则、业务判断 |
| 模块层 | 领域数据与业务语义 | 五个数据产品仓库 | 全局规则、他人数据 |
2.2 组件关系【事实+推论】
- 协议系统 ↔ 工作台：ADR-001 分离；【推论】当前无引用机制，注册与 P-07 时建立。
- 工作台 ↔ 执行内核：同进程（现状，不是错误）；逻辑边界 = "控制不执行、执行不决策"。
- 工作台 ↔ 五产品：project.config.json + adapter.ts + spawn；【事实】仅 CN 有运行记录。
- 产品 ↔ 对外服务：三种部署状态相互独立【事实：仅 CN 三端全部上线；BagComply/PoreWise 代码未部署；BB/WGL 无】：
- 网站部署：人读站点可达且内容最新；
- API 部署：结构化接口可达且数据一致；
- MCP 部署：机器访问入口注册可用。 三者不得互相推断：网站部署 ≠ API 可用 ≠ MCP 可用。各产品按 P-04 §2.5 逐项声明。
2.3 逻辑架构 ≠ 物理部署【原则重申】
四层不对应四个服务。控制/执行分离保留为条件触发的独立决策（E-7 / Phase 6），不属于预先承诺的实施任务；实施计划中不含拆分工作。
第三章 核心对象与状态模型
3.1 对象关系（继承元协议第五章）
系统 ──1:N── 数据产品(项目)
项目 ──拥有── 数据资产/来源清单/业务规则
项目 ──声明── 项目配置(project.config.json) ←──登记── 项目协议(P-03)
任务(定义) ──1:N── 运行实例(run) ──产出── 执行结果(信封)
执行结果 ──支撑── 数据质量状态 / 审核状态 / 发布状态
异常 → items 工单(证据关闭) → 修复任务(运行实例) → 决策记录(ADR)/版本(P-06)
3.2 状态枚举（统一词汇表）
| 对象 | 状态集 | 现状载体 |
|---|---|---|
| 运行实例 | pending/running/succeeded/failed（+failureClass 11 类）【事实】 | state/runs.json |
| 数据质量 | 每实体：校验通过/未通过/未验证（缺失/未找到规则/信息不足/验证失败分别表达）【信封落地后固化】 | 各站校验闸（风格不一） |
| 审核 | 待审/needsReview/approved/已转正【事实·命名不一】 | verify-draft/review-server |
| 发布 | guarded-unverified → 可发布 → 已发布【生产从未走过全程】 | releases/（空） |
| 服务健康 | site-status 六维探测结果【事实】 | state/site-status/ |
3.3 项目接入七级阶梯【v1.0 新增，修订要求 5】
四个不同概念此前被 enabled:true 混为一谈【事实：四站 enabled 但零运行】。v1.0 起统一为七级，逐级可验收，禁止跳级声明：
| 级 | 名称 | 达标判据（需证据） |
|---|---|---|
| L0 | 未注册 | 默认态 |
| L1 | 已注册 | 注册索引中有该项目的登记行，项目协议文件存在且经 P-03 校验 |
| L2 | 配置完成 | project.config.json 路径/环境/任务清单有效，configured:true 有核验记录 |
| L3 | 执行连通 | ≥1 个任务手动触发产生完整 run 记录（含日志、退出码） |
| L4 | 结果合规 | 该任务产出 Schema 合规信封（或明确登记 legacy 降级） |
| L5 | 审核通过 | 该项目至少一次数据变更经人工审核闭环 |
| L6 | 生产可用 | 网站部署 + 已声明范围内的 API/MCP 部署 + 健康探测连续通过 + 一次发布/异常演练完成 |
3.4 术语重叠、缺失与冲突检查【结论不变】
| 类型 | 术语 | 问题 | 处理 |
|---|---|---|---|
| 重叠 | enabled vs 已接入 vs 已注册 | 混为一谈【事实】 | 七级阶梯（3.3）+ P-07 独立字段 |
| 重叠 | 任务成功 vs 数据合格 | 退出码 0 ≠ 校验通过【事实：CN hash 0/11】 | 元协议硬性条款 + 信封区分 |
| 重叠 | failed(run) vs 异常(item) | 10-23 failed 实为对账标记【事实】 | failureClass + items 登记规则入 P-07 |
| 缺失 | 发布状态 | 无实战词汇验证【事实】 | Phase 5 发布演练补齐 |
| 缺失 | 代码版本 | runs.json 无 gitSha/clean【事实】 | P-07 信封强制字段 |
| 冲突 | ADR-001 vs 目标态执行可独立 | 措辞冲突 | ADR-003 限定【建议】 |
| 冲突 | 门户证据五档 vs P-04 | 双源风险 | 声明 P-04 权威【建议】 |
3.5 统一结果契约的兼容策略【v1.0 新增，修订要求 7】
| 对象 | 处理方式 |
|---|---|
| 历史运行记录（本地 13 条等） | 永不删除、永不回填。信封落地后按 envelope: legacy / gitSha: null 解释，保持可查询 |
| 旧任务（无信封输出） | 自动降级为 legacy 信封（workbench 包装退出码+截断日志），逐个升级，不强制一次性重写 |
| 缺失字段 | 显式 null 并记 missingFields，禁止用默认值伪装（"0 条"≠"未采集"） |
| 信封版本 | envelopeVersion: 1；后续演进按 P-06，Schema 向后兼容破坏需 MAJOR |
| legacy 的退出标准 | 任务产出原生合规信封后，其 legacy 降级路径才可移除；移除本身留痕 |
第四章 端到端运行机制
十环节闭环（每环节责任主体/输入/输出/成功/失败/证据要求）：
| # | 环节 | 责任主体 | 成功条件 | 失败条件 | 证据要求 | 状态 |
|---|---|---|---|---|---|---|
| 1 | 需求或触发 | 调度器/人/健康探测 | 到点或异常登记 | 漏触发（现版不补跑） | 调度日志 | 【已存在】 |
| 2 | 决策与授权 | 控制层 | 白名单内+无互斥 | 白名单外/运行中/无协议依据 | 运行记录含 trigger | 【已存在】（白名单协议化待建设） |
| 3 | 任务执行 | 执行层(spawn) | 正常退出且产物落盘 | 超时/崩溃/路径无效 | 全量日志+gitSha（待建设） | 【已存在】 |
| 4 | 结果记录 | RunStore | 记录完整可查 | 记录丢失（对账兜底，CN 10-23 即实例） | runs.json+日志 | 【已存在】 |
| 5 | 数据验证 | 执行层+项目规则 | 全部闸通过 | 任一闸失败（四类语义分别表达） | 校验输出明细 | 【已存在·表达待统一】 |
| 6 | 审核与发布判断 | 人+控制层 | 人工批准+护栏通过 | 积压逾期/guarded 拦截 | items+审核记录 | 【已存在】（发布实战待建设） |
| 7 | 发布或拒绝 | 执行层+CF | 线上指纹与本地一致 | 推送失败/不一致 | releases+deploy-check | 【已存在·生产未实战】 |
| 8 | 监控 | 控制层 | 探测周期内完成 | 探测失败（本身登记） | site-status/monitor-baseline | 【已存在】 |
| 9 | 异常处理与恢复 | 控制层+人 | 工单证据关闭 | 无人工响应（44 条积压实证） | items 链路 | 【已存在·闭环靠人】 |
| 10 | 反馈 | 全层 | 提议进入 P-06 流程 | 无反馈渠道 | CHANGELOG/ADR | 【已存在·制度化低】 |
闭环结论【推论】：最薄弱两环是"发布实战"与"异常闭环"，而非缺失组件——Phase 5 专门针对这两环。
第五章 协议体系与治理设计
5.1 权威载体
【建议】总规则唯一权威 = P-01 v2.0.0（吸收元协议）；P-02~P-06 原样保留；ADR 记录不可逆决策；项目协议/模块契约在各项目仓库。冲突处理：全局 > 项目 > 模块；引用带版本；内部文档标注"非全局权威"。
5.2 P-01 升级方案：逐条内容映射【v1.0 新增，修订要求 6】
证明 P-01 v1.0.0 每条规则在 v2.0.0 中得到保留。逐节核对依据 P-01 v1.0.0 原文：
| P-01 v1.0.0 条目 | v2.0.0 处置 | 说明 |
|---|---|---|
| §1 名称与定位（Protocol System 定义、职责边界、与 Workbench 分立） | 保留 + 一处修正 | 修正点：§1 写"Workbench 负责任务管理、调度与执行"——与"执行承载可演进"（E-7 目标态）冲突。v2.0.0 改为"任务管理与调度，并承载当前执行内核（现状描述）；执行承载可依 ADR 演进"。其余原文保留 |
| §2 服务对象与适用范围 | 保留原样 | 逐字保留 |
| §3 核心原则 5 条（复杂不混乱/职责清晰/资产有归属/规则可追溯/模块可替换） | 保留原样 + 新增 3 条 | 新增（来自元协议，均不与原 5 条冲突）：⑥ 事实与建议区分（结论须标注依据等级）；⑦ 渐进机器可验证（不为形式自动化强行编码）；⑧ 不为架构完整过度设计 |
| §4 四层框架 | 保留 + 扩充 | 原文四层定义保留；新增：逻辑分层 ≠ 物理部署、四层可嵌套的正式表述、"控制不执行/执行不决策"边界条款（元协议 3.2） |
| §5 协议层级关系 | 保留 + 扩充 | 原三级层级保留；新增：ADR 与内部文档的权威关系、单一事实来源规则（同一规则只允许一份权威来源） |
| §6 全局约束与项目自主边界 | 保留 + 扩充 | 原"不得放宽/允许自定"两清单逐条保留；新增：灰色区裁决规则（未明确事项默认归项目自治，涉及跨项目才上升为全局）、健康矩阵与状态区分列入全局约束 |
| §7 V1.0 目标/范围/暂不实现 | 改写（唯一重写节） | 原因：V1.0 专属的范围声明对 v2.0.0 不再成立。改写为通用"版本目标与暂不实现"条款：机器验证渐进立场（暂不建协议校验机器人/自动门禁/管理后台）逐条保留；版本范围改为 v2.0.0 十章内容 |
结论【推论】：7 节中 6 节保留或保留+扩充，仅 §7 因时效重写且其"暂不实现"清单逐条保留；1 处措辞冲突修正（§1 执行承载）。无信息丢失。发布形态仍待 E-2 批准，本映射供决策。
5.3 机器验证 vs 人工审查【建议】
- 优先机器验证：信封 Schema、注册信息完整性、调度白名单、repoRoot 有效性、协议引用完整性。
- 维持人工：证据等级判定、审核批准、ADR 审查、健康矩阵综合判读。
5.4 内部文档权威关系
workbench"六层"表述、总规范/审计档案、execution 设计稿均为内部文档：冲突时全局协议为准。
第六章 差距分析（现状 → 目标）
分级：A=有证据 / B=未充分验证 / C=部分实现 / D=未实现 / ?=待确认。
纠偏声明：enabled:true、文档设计、历史记录一律不计为当前可用能力。
| # | 领域 | 级别 | 差距要点 |
|---|---|---|---|
| 1 | 工作台控制能力 | A(CN)/C(跨项目) | 四站零接入；发布段无实战 |
| 2 | 执行内核与任务运行 | B | 跨平台直测；接口未协议化 |
| 3 | 五产品配置/注册/接入 | C | 路径失效（E-1）→注册→接入；且本地运行时前提未核实（v1.0 修正，见 Phase 0） |
| 4 | 统一执行结果格式 | D | 信封+Schema（兼容策略见 3.5） |
| 5 | 数据验证与发布控制 | C | 发布实战归 Phase 5 |
| 6 | 系统健康监控 | A | 矩阵判读未制度化 |
| 7 | API/MCP | C | 三种部署状态独立管理（v1.0 修正，见 2.2）；节奏由项目定 |
| 8 | 生产环境验证 | ? | 服务器核实（E-5） |
| 9 | 协议机器验证 | D | 随 P-07；维持渐进 |
| 10 | 控制/执行部署关系 | 现状即目标允许形态 | 独立化=条件触发决策（Phase 6），非实施任务 |
第七章 分阶段实施计划
修订后的七阶段路线（详细任务、依赖、验收、回滚见 docs/22-分阶段实施计划 与 docs/23-任务清单）：
| 阶段 | 名称 | 核心内容 | 关键修正 vs v0.1 |
|---|---|---|---|
| Phase 0 | 环境核实与风险处置准备 | 运行时前提核实、路径修复、服务器对账、BagComply 只读验证、凭据处置准备 | 不再是"5 行配置"：补足本地运行时前提（启动冒烟、依赖、端口、调度器干跑），不假定改路径即恢复执行 |
| Phase 1 | 总体设计修订与所有者批准 | 本方案获批 + E-1~E-7 决策落定 | 新增阶段：把"批准"从隐含前置显式化为独立阶段 |
| Phase 2 | 协议治理与统一任务契约 | P-01 v2.0.0、ADR-003、P-07+Schema、五项目注册 | 与凭据处置（L3 安全敏感）拆分，凭据移入独立支线 |
| Phase 3 | CN 单项目试点与完整链路验证 | 信封落地（首个改码阶段）+ CN 全链路受控验证 | 明确"试点验证信封机制"与 Phase 4"验证配置机制"分工 |
| Phase 4 | 其他产品逐个接入与独立验收 | 四站逐个接入，每站独立验收、独立回滚 | 与发布实战、异常闭环拆开（v0.1 混在 Phase 4） |
| Phase 5 | 生产发布、异常恢复与系统级验证 | 首次真实发布全程 + 故障注入走完异常闭环 + 系统级九域验收 | 新增独立阶段 |
| Phase 6 | 架构演进评估 | 依据 Phase 3–5 真实运行数据评估 E-7（独立部署）、P-08 收编、调度自动化 | 条件触发，非预先承诺 |
第八章 最终验收体系
九域验收判据（全部需证据链，详见 docs/24 与 docs/25）：
| # | 验收域 | 达标判据 |
|---|---|---|
| 1 | 系统规则 | 元协议正式生效（批准记录+tag）；现行协议无冲突 |
| 2 | 职责边界 | 各组件可回答负责/不负责；控制不执行、执行不决策可指认 |
| 3 | 任务运行 | 每站 ≥1 任务有 run 记录；失败有 failureClass 与处理痕迹 |
| 4 | 结果追溯 | run 可查 gitSha+clean+全量日志；信封 Schema 校验通过；legacy 显式标注 |
| 5 | 数据质量 | 质量状态独立于任务状态；"未验证"如实显示 |
| 6 | 审核发布 | 一次真实发布证据链：批准→护栏→线上指纹一致→健康探测通过 |
| 7 | 异常恢复 | 一次注入故障走完：发现→工单→重试/人工→证据关闭 |
| 8 | 服务健康 | 五站健康矩阵证据齐备；网站/API/MCP 三种部署状态分别判定 |
| 9 | 版本治理 | 三层版本独立且留痕；内部文档标注权威关系 |
附录 A 操作授权分级【v1.0 新增，修订要求 8】
| 级 | 类别 | 定义 | 授权要求 | 证据要求 |
|---|---|---|---|---|
| L0 | 只读检查 | 读文件/git status/只读脚本/GET 探测 | 无需逐次批准，但须记录操作清单 | 操作日志 |
| L1 | 可控测试操作 | 本地、可逆、不触生产：本地配置修改、本地手动跑任务、受控试点 | 需所有者对具体任务及范围明确授权（可一次列明一批，但须逐任务写明；计划批准本身只解锁 L0） | diff+运行记录 |
| L2 | 真实生产操作 | 发布、服务器变更、线上数据、对外服务影响 | 每次操作单独批准 | 批准记录+发布/变更证据 |
| L3 | 安全敏感/不可逆 | 凭据轮换、文件删除、不可逆数据修改、架构拆分 | 单独批准；凭据类由所有者亲自操作或现场见证 | 批准记录+结果证据+回滚方式 |
禁止：未获授权把推荐方案当批准；L2/L3 打包进阶段批量授权。
本方案到此为止：不执行任何实施操作。等待所有者审查批准后，方可按 docs/22 启动 Phase 0。