55-决策与变更记录 Template v1.0 | 第11章 实现绑定层与函数原型规范

目录 ／ 文档-技术白皮书（V5.05） ／ 55-决策与变更记录 Template v1.0

第11章 实现绑定层与函数原型规范

I. 章节目标与范围（强制）

• 将本卷“决策与变更记录（DR）”在实现绑定层（Implementation Binding）落地为稳定的 API/CLI/Schema 契约与函数原型，确保可复现、可审计、可回放。
• 与第3章记录单结构、第4章状态机、第6章影响评估、第7章回滚闭环、第8章签署、第9章实施与验证、第10章发布策略对齐。

II. 绑定层结构与命名（强制）

• 接口分层：domain（领域服务）/data（数据契约）/ops（运维发布）/audit（审计导出）。
• 命名口径：<namespace>.<resource>.<action>；版本沿用 semver 与 version_range。
• 响应统一字段：code（枚举）、message（简述）、data（载荷）、trace_id（跟踪）。
• 错误分级：E_INPUT/E_STATE/E_GATE/E_DEP/E_SYS；均需可定位到 script@commit 与数据/契约版本。

III. 契约一致性与兼容策略（强制）

• 兼容线：新增字段为 BC；删除/重命名为 Breaking，需提供 fallback 与双栈窗口 ≥ 一个观察期。
• 数据契约：输入/输出均需标注 unit、dim、ci/uncertainty（如适用），并通过 check_dim。
• 锚点显式：在响应 meta.anchors[] 中列出使用到的 S/P/M/I 锚点（“卷名+版本+锚点”）。

IV. 统一符号与路径/公式口径（强制）

1. 到达时示例：
   • 常量外提：T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • 一般口径：T_arr = ( ∫ ( n_eff / c_ref ) d ell )
2. 任何接口如返回或消费 T_arr，同段或邻段需给出路径 gamma(ell) 与测度 d ell 的定义或锚点引用；禁混 T_fil/T_trans、n/n_eff、c/c_ref；公式/符号/定义禁用中文。

V. API 设计规范（REST/HTTP，强制）

• 版本：/api/v{major}；资源复数；幂等保证：GET 幂等，POST 非幂等，PUT/PATCH 条件更新（If-Match）。
• 分页：page/size/next_token；排序：sort=field:asc|desc；过滤：q=、结构化 filter[field]=op:value。
• 观测与审计：所有写操作需返回 audit_ref 与 artifact_hash；落库签署见第8章。
• 速率与限流：429 返回退避建议；长任务采用 202 + Location 轮询。

VI. 典型接口清单（可直接拷贝）

1. DR 生命周期
   • POST /api/v1/decisions（创建）
   • GET /api/v1/decisions/{id}（查询）
   • POST /api/v1/decisions/{id}/review|approve|implement|verify|archive|rollback（状态迁移）
   • GET /api/v1/decisions/{id}/audit（审计导出：yaml/json/pdf）
2. 影响评估与门禁
   • POST /api/v1/impact/assess（提交评估包）
   • GET /api/v1/impact/{id}（评估结果与 S 分）
   • POST /api/v1/gates/check（批量 gate 校验）
3. 实施与回放
   • POST /api/v1/impl/run（触发实施计划）
   • POST /api/v1/replay/run（回放/影子评测）
   • GET /api/v1/replay/{rid}（回放结果与覆盖率）
4. 发布与版本关系
   • POST /api/v1/release；GET /api/v1/release/{id}
   • GET /api/v1/version/graph（主干/草案/Hotfix 图）

VII. 函数原型（语言无关，强制）

create_decision(record: DecisionRecord) -> DecisionID

assess_impact(id: DecisionID, pack: EvidencePack) -> ImpactReport

check_gates(items: List[GateSpec]) -> GateResultSet

approve(id: DecisionID, signers: List[Signer]) -> ApprovalStatus

implement(id: DecisionID, plan: ImplementationPlan) -> ExecutionStatus

verify(id: DecisionID, suite: RegressionSuite) -> VerificationReport

rollback(id: DecisionID, trigger: TriggerSpec) -> RollbackReport

export_audit(id: DecisionID, fmt: ["yaml","json","pdf"]) -> ArtifactRef

release_new(rel: ReleaseSpec) -> ReleaseID

get_version_graph() -> VersionGraph

VIII. 机读 Schema（核心对象，YAML；JSON 等价，强制）

DecisionRecord:

id: "DR-YYYY-NNNN"

title: ""

status: "Draft|Review|Approved|Implemented|Verified|Archived|RolledBack"

requester: { name: "", role: "Requester" }

approvers: [{ name: "", role: "Approver" }]

created_at: "YYYY-MM-DD"

effective_at: "YYYY-MM-DD"

motive: ""

options: [{ name:"", assumptions:[], pros:[], cons:[] }]

decision: ""

rollback: { triggers:[], steps:[] }

impact:

dimensions: {}

scoring: { k_sigma: 1.0 }

verification:

gates: { hard:[], soft:[] }

regression_suite: { cases:[], coverage:{ functional:"", path:"", data:"" } }

references:

see:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

GateSpec:

name: "gate_accuracy"

rule: ">=0.99@7d"

source: { dataset:"", script:"script@commit" }

ImpactReport:

S: 0.0

ci95: [0.0, 0.0]

dimensions: { performance:{ s:0.0, sigma:0.0, s_adj:0.0 }, ... }

ImplementationPlan:

plan_id: "IMP-YYYY-NNNN"

milestones: []

env: { domains:[], images:[], flags:[], config:{} }

data_scripts: { datasets:[], scripts:[], container:"", repro_cmd:"" }

VerificationReport:

gates: { passed: true, details: [{ name:"gate_accuracy", value:"0.993@7d" }] }

regression: { pass_rate:"0.99", failed:[] }

artifacts: ["yaml","json","pdf"]

ReleaseSpec:

semver: "x.y.z"

channel: "alpha|beta|stable|lts"

scope: { modules:[], contracts:[], regions:[] }

gates: { hard:[], soft:[] }

rollback: { baseline:"", triggers:[] }

IX. 安全、限流与审计（强制）

• 安全：采用 OAuth2/OIDC；最小权限（RBAC）；签署与状态迁移需多方确认（MFA/多签）。
• 限流：全局配额与 per-actor 配额；返回 Retry-After；提供幂等键 Idempotency-Key。
• 审计：所有写操作记录 timestamp/actor/action/resource/hash/evidence_ref；导出工件需落库并与签署页对齐。

X. 性能与可用性 SLO（强制）

• SLO 示例：p95_latency<=200ms@1d、availability>=99.9%@30d、error_rate<=1e-3@1d。
• 违约处理：进入第7章触发器策略；必要时自动执行回滚 API 并生成 RollbackReport。

XI. 监控与可观测性（强制）

• 指标：请求量、延迟、错误、限流命中、回放覆盖、gate 通过率。
• 日志：结构化 JSON 日志，包含 trace_id/span_id/decision_id/release_id。
• Tracing：分布式追踪贯通 DR → 实施 → 验证 → 发布 → 回滚。

XII. 示例：到达时查询与验证（可直接拷贝）

1. API：POST /api/v1/arrival-time/estimate
   • 入参：
   • {
   • "path": "gamma(ell)",
   • "measure": "d ell",
   • "c_ref": "ref:L2",
   • "n_eff_profile": "dataset:cmb_set_v3@v3",
   • "mode": "general" // general|factored
   • }
   • 出参：
   • {
   • "code": "OK",
   • "data": {
   • "T_arr": "( ∫ ( n_eff / c_ref ) d ell )",
   • "value": 12.345,
   • "unit": "s",
   • "anchors": [
   • "EFT.WP.Core.Equations v1.1:S20-1",
   • "EFT.WP.Core.Metrology v1.0:check_dim"
   • ]
   • },
   • "trace_id": "..."
   • }
2. 函数原型：estimate_arrival_time(req: ArrivalReq) -> ArrivalResp
3. 验证 gate：gate_accuracy>=0.99@7d、compat_rate>=0.995@replay

XIII. 人读 × 机读对位（强制）

XIV. 引用与交叉引用体例（强制）

1. 文内固定写法：“见《<卷名> vX.Y》Ch.x S/P/M/I…”，优先锚点而非整卷。
2. 在记录单 references.see 中提供机读清单（示例）：
   • "EFT.WP.Core.Terms v1.0:P10-3"
   • "EFT.WP.Core.Equations v1.1:S20-1"
   • "EFT.WP.Core.Metrology v1.0:check_dim"
   • "EFT.WP.Core.DataSpec v1.0:I30-2"