外部技术规范引用清单

平台不自造协议语义：HTTP 失败契约、查询谓词、OAuth 令牌族、TOTP 算法、CSV 转义这些表面都锚定在公开标准上。本页把散落在源码注释、架构文档与开发手册中的外部规范引用收拢为一张可查的清单——每条给出门仓名称、权威链接、源码落点与采纳方式。规范的编号与标题以 IETF / NIST / W3C 官方发布页为准；本页修订时必须逐条打开链接核对，禁止凭记忆转述编号或条款。

引用纪律

三条硬约定，适用于代码注释、架构文档与本手册：

1. 引用一律”链接 + 条款号 + 一句话准确转述”。例如”RFC 7009 §2.1：撤销端点对不存在的令牌也返回 200，防止枚举”是合格引用；“按照 RFC 的要求处理”不是。
2. 严格区分”标准的要求”与”本平台的工程选择”。标准没有规定的内容（如再认证窗口 300 秒）必须表述为出厂建议值或平台约定，不得包装成标准条款。一个长期存在的反例是”NIST SP 800-63B 要求敏感操作再认证不超过 15 分钟”——SP 800-63B（Authentication and Lifecycle Management）只在 §4.3 给出 AAL1–AAL3 保证分级，再认证时机属于部署方风险决策，平台出厂值与该标准无关。
3. 区分四种采纳方式：直接实现（按标准语义实现）、扩展实现（实现标准语义并叠加平台扩展字段）、有意偏离（明确说明偏离点与理由）、语境引用（借标准的术语或分级表达设计意图，不声称实现）。下表逐条标注。

HTTP 语义与 API 契约

RFC 9457 是全部失败响应的统一形态：type/title/status/detail 之外，平台叠加 errorCode、errorType、traceId、correlationId、requestId 五个扩展成员——扩展部分是平台增量，不是标准要求（长期决策见 BitzOrcasVNext 仓库 ADR 0108）。实际形态：

// RFC 9457 ProblemDetails + 平台扩展成员（errorCode/errorType/traceId 等平铺到根）。
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.bitzsoft.com/problems/business-rule-violation",
  "title": "Business rule",
  "status": 422,
  "detail": "再认证策略行已被他人修改，请刷新后重试。",
  "errorCode": "Identity.StepUp.PolicyVersionConflict",
  "errorType": "Failure"
}

# RFC 10008 QUERY：查询条件在 JSON 正文，URL 不承载筛选；
# 不支持自定义方法的代理按平台降级约定转发为 POST /api/announcements/_query。
curl -s -X QUERY https://localhost:5001/api/announcements \
  -H "Content-Type: application/json" \
  -d '{"pageIndex":1,"pageSize":20,"searchText":"条件"}'

RFC 10008 把分页、列表、搜索类只读请求统一为 QUERY 谓词 + JSON 正文；POST {path}/_query 降级是平台工程选择，用于不支持自定义方法的代理与运行时，标准本身不含该降级。RFC 10008 还要求 QUERY 缓存键包含请求内容——平台据此以 BZEP005 阻止 QUERY 端点配置普通 Output Cache。

认证、授权与令牌

RFC 9470 §3 定义资源服务器以 401 + WWW-Authenticate: Bearer error="insufficient_user_authentication"（可带 acr_values/max_age）发起再认证挑战。本平台面向第一方 SPA、无重定向回路，有意偏离为 403 + RFC 9457 ProblemDetails 扩展字段（purpose/factors/windowSeconds）——偏离点、理由与互操作边界在敏感操作再认证中逐条说明。对接方应实现平台的 403 契约，而非 RFC 9470 客户端逻辑。NIST SP 800-63B 仅以 §4.3 的 AAL 分级作设计语境；其文本不含”敏感操作再认证 ≤ 15 分钟”之类的条款，平台的 300/900 秒窗口是出厂建议值。

多因素认证因子

TOTP 的算法参数与漂移处理沿用 MFA 连接器实现，平台不重复定义；HOTP 底层（RFC 4226）仅在手册语境中随 RFC 6238 一并提及。

数据格式与互操作

草案跟踪与隐式遵循

以下各项未进入上方主表，原因与观察口径如下：

• Idempotency-Key 头：平台幂等管线按 Idempotency-Key 请求头承载幂等键。对应草案 draft-ietf-httpapi-idempotency-key-header-07 已于 2025-10 过期、未成 RFC，但该头名 是业界事实标准（Stripe 等）。策略：维持现状，草案复活时对齐参数细节。
• RateLimit 响应头字段：draft-ietf-httpapi-ratelimit-headers-11 仍为活跃草案 （2026-05），未成 RFC。平台 429 现以标准 Retry-After 头（RFC 9110 语义）+ ProblemDetails retryAfterSeconds 扩展表达退避。策略：草案转 RFC 后再评估采用。
• JWT（RFC 7519）/ HMAC（RFC 2104）：令牌签发与 API 客户端签名经标准库实现，源码 未显式锚定规范编号，属隐式遵循。

有意不采用

以下标准经评估后显式不用，理由登记于此，防止后续会话当作缺口重复提出：

• JSON Patch（RFC 6902）：编码红线禁止核心聚合使用通用 Patch——业务状态变更必须 走显式 Command，保证授权、校验与审计的完整管线覆盖。部分更新用显式部分命令表达。
• 超媒体控制（HAL / JSON:API / Link 头分页，RFC 8288 / RFC 9652）：平台以自描述 分页信封（PagedResult + 页级 Meta 伴生注入）承载导航信息，前端按契约消费；不为 API 响应引入超媒体语义。

手册对照索引

新增引用的约定

向代码或手册引入新的外部规范引用时：先打开官方发布页核对编号、标题与条款原文；在源码注释中写”标准名 + 条款号 + 语义”，不裸写编号；属于平台工程选择的决策在相邻 ADR 或手册中说明偏离点；最后回到本页登记一行——本页是唯一清单，散落的引用以这里为对账基准。