56-报告级方法附录 Template v1.0 | 第11章 实现绑定与函数原型（I）

目录 ／ 文档-技术白皮书 ／ 56-报告级方法附录 Template v1.0

第11章 实现绑定与函数原型（I）

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

• 将本附录的方法条目在实现绑定层（Implementation Binding）落地为API/Schema/函数原型，保证可复现、可审计、可回放与跨版本兼容。
• 与第5章（数据与实验设计）、第6章（数学与伪代码）、第8章（评测协议）、第9章（不确定度与统计检验）、第10章（消融与敏感性）对齐。

II. 接口分层与命名（强制）

• 分层：domain（领域服务）/data（数据契约）/ops（运维与发布）/audit（审计导出）。
• 命名口径：<namespace>.<resource>.<action>；路径采用 REST 版本前缀 /api/v{major}，资源复数。
• 统一响应：code（枚举）、message（简述）、data（载荷）、trace_id（链路跟踪）。

III. 版本与兼容策略（强制）

• 版本：semver 与 version_range 并行；对外发布优先 v1.* 稳定线。
• 兼容：新增字段为 BC；删除/重命名为 Breaking，需提供 fallback 与双栈窗口 ≥ 一个观察期。
• 契约变更需在 compatibility 域标注：{ version_range, fallback, breaking }。

IV. 错误分级与可追溯（强制）

• 错误码：E_INPUT（入参/校验）、E_STATE（状态/依赖）、E_GATE（门禁失败）、E_DEP（外部依赖）、E_SYS（系统异常）。
• 追溯要素：trace_id/span_id、script@commit、dataset@version、artifact_hash。

V. 到达时口径与一致性（强制）

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_arr:s/T、n_eff:1/1、c_ref:m·s^-1/L T^-1；check_dim=true。

VI. 典型端点（REST，强制，可直接拷贝）

1. 方法评测
   • POST /api/v1/methods/{name}/evaluate —— 触发评测（返回 202 + Location 轮询）
   • GET /api/v1/methods/{name}/results/{rid} —— 获取结果与覆盖率
2. 到达时估计
   POST /api/v1/arrival-time/estimate —— 输入路径与口径，输出 T_arr 与锚点
3. 门禁校验
   POST /api/v1/gates/check —— 批量评测门禁判定
4. 审计导出
   GET /api/v1/audit/{id} —— 导出 yaml/json/pdf 审计包
5. 发布与版本关系
   POST /api/v1/release；GET /api/v1/version/graph

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

evaluate_method(req: EvalReq) -> EvalReport

estimate_arrival_time(req: ArrivalReq) -> ArrivalResp

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

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

release_new(spec: ReleaseSpec) -> ReleaseID

get_version_graph() -> VersionGraph

VIII. 请求/响应 Schema（摘要，YAML；JSON 等价，强制）

ArrivalReq:

path: "gamma(ell)"

measure: "d ell"

c_ref: "ref:L2" # 或函数标识

n_eff_profile: "dataset:cmb_set_v3@v3"

mode: "general" # general|factored

params: { Δell: 1e-3, ε_int: 1e-6 }

ArrivalResp:

code: "OK|E_INPUT|E_STATE|E_GATE|E_DEP|E_SYS"

data:

T_arr: 12.345

unit: "s"

anchors:

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

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

context:

delta_form: "general"

path: "gamma(ell)"

measure: "d ell"

params: { Δell: 1e-3, ε_int: 1e-6 }

trace_id: "..."

EvalReq:

method: { name: "", version: "v1.0" }

datasets: ["cmb_set_v3@v3","lens_v1@v1"]

scripts: ["eval.py@a1b2c3"]

config: { seed: 20250927, batch: "B1" }

EvalReport:

summary: { pass: true }

metrics:

gate_accuracy: { value: 0.995, gate: ">=0.99@7d", passed: true, ci: [0.993,0.997] }

gate_latency: { value: "1.8h", gate: "<=2h@7d", passed: true }

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

hashes: ["sha256:…"]

GateSpec:

name: "gate_accuracy"

rule: ">=0.99@7d"

source: { dataset: "cmb_set_v3@v3", script: "eval.py@a1b2c3" }

ReleaseSpec:

semver: "1.4.0"

channel: "beta|stable|lts"

compatibility: { version_range: "[2.0,3.0)", fallback: "adapter_v1", breaking: false }

IX. 安全、限流与幂等（强制）

• 安全：OAuth2/OIDC；RBAC 最小权限；关键状态迁移需多方签署（MFA/多签）。
• 限流：全局与 per-actor 配额；超限返回 429 与 Retry-After。
• 幂等：对潜在重复提交提供 Idempotency-Key；长任务采用 202 + Location 轮询。

X. 可观测性与审计（强制）

• 指标：QPS、p95 延迟、错误率、限流命中、回放覆盖、gate_* 通过率。
• 日志：结构化 JSON，保留 trace_id/span_id/method/version/dataset@version/artifact_hash。
• 审计：所有写操作落库审计条目；导出工件与签署页一并归档。

XI. 人读 × 机读映射（强制）

XII. 最小样稿（可直接拷贝，强制）

• 人读摘要：POST /api/v1/arrival-time/estimate 采用一般口径，Δell=1e-3、ε_int=1e-6；响应返回 T_arr（单位 s）、锚点与 trace_id。
• 机读片段：

request:

path: "gamma(ell)"

measure: "d ell"

c_ref: "ref:L2"

n_eff_profile: "dataset:cmb_set_v3@v3"

mode: "general"

params: { Δell: 1e-3, ε_int: 1e-6 }

response:

code: "OK"

data:

T_arr: 12.345

unit: "s"

anchors: ["EFT.WP.Core.Equations v1.1:S20-1","EFT.WP.Core.Metrology v1.0:check_dim"]

context: { delta_form: "general", path: "gamma(ell)", measure: "d ell" }

trace_id: "..."

XIII. 校验规则（正则/一致性，强制）

• 端点：^/api/v[0-9]+/[a-z0-9\-/\{\}_]+$；资源名复数。
• 引用：^EFT\.WP\.[\w\.]+ v\d+\.\d+(?:\.\d+)?:[PSMI]\d+(?:-\d+)?$。
• 门禁：^gate_[a-z0-9_]+(>=|<=|==)[^@\s]+@[^@\s]+$。
• 到达时：若出现 T_arr，path/measure 必填；check_dim=true。
• 版本：semver 合法；若 breaking=true 必须给出 fallback 与观察窗口。

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