@drama/observability · ctx 贯穿约定（权威原文）

本文件是「RequestContext 作为显式首参 ctx 贯穿所有服务签名」约定的单一事实来源。 下游所有 service / application-service / repo / 路由的签名设计都引用本文。任何对 RequestContext 形状、Logger 形状或本约定的改动，必须先改本文件与任务文档 §3，再改代码，因为它影响全仓所有签名。

约定原文（硬性，被全仓引用）

一切跨进程边界进来的逻辑入口（HTTP 路由、定时任务、消息消费）在最外层创建或续传 RequestContext， 并把它作为显式首参 ctx 一路传递到 service、application-service、必要时到 repo。形如：

dramaService.buildBundle(ctx, dramaId)

全仓所有 service 方法的第一形参必须是 ctx: RequestContext。

红线

• 禁止用 AsyncLocalStorage 等隐式穿透携带 ctx（架构基线点名旧参照版靠 ALS 隐式穿 billing 是反模式）。 ctx 必须显式、可见、可测。
• 禁止用全局可变单例「偷偷」携带 ctx。
• 包内不读 process.env、不建顶层连接、不在顶层装 OTel SDK；import 本包无副作用。

为什么

如果一期不定 ctx 贯穿约定，二期接 OpenTelemetry 就要回头给每一个 service 函数加 trace 参数、 给每一处日志补 trace_id——改造面是全仓。一期花几行定下约定与日志工厂，把这个改造面压成接近零。

二期升级点（签名不变，调用方零改动）

• createRequestContext 升级为携带真实 OTel span context。
• createLogger 接 OTel log bridge。
• RequestContext 形态与 child / 工厂入口不变——这是「一期约定先行」的开闭兑现点。