消费请求目录（#1645）

目录用于换设备后发现消费、查询原账证和统计完整时间窗。这里只描述当前代码合同；迁移、生产部署与供应商实测须以发布记录为准。

身份与权限

端点	范围与权限
GET /api/billing/v1/requests	当前来源请求目录；OAuth 为同 user+app，API Key/agent 为原凭据；独立 billing:requests / Usage Requests
GET /api/billing/v1/requests/summary	同来源、同请求时间窗全集统计
GET /api/billing/v1/me/requests	JWT，或独立 billing:history 官方 Host，用户本人 actor 的全部来源
GET /api/billing/v1/me/summary	同上，本人同窗全部来源统计
GET /api/billing/v1/me/receipts	同上，本人按 requestId 恢复任一原来源账证

旧 billing:receipts、Usage Receipts 与 /receipts、/summary 不扩大权限。付款团队的 owner 不因付款而取得其他成员私密请求；API Key、agent、child OAuth 不得仅凭可达路由访问 /me。Host还须命中独立 OAUTH_BILLING_HISTORY_HOST_CLIENT_IDS，当前official/standard/admin_managed、非委托token、真实RPC验证及显式用户同意；空名单或未开通一律拒绝。history禁止OTP/微信直接签发和委托签发，旧token刷新不新增scope。注册scope不等于生产Host已开通。普通开发者可申请billing:requests，仍须App版本审核和用户授权；不会自动添加到旧App/revision/token。API Key/agent必须显式绑定新Usage Requests组，并通过原有deny优先的权限校验，通配allow不能代替新组。服务端只把已鉴权身份传给私有SQL，SQL再复验当前token或Key/agent事实与新权限；SQL 的 JWT 身份参数不是 JWT 验签接口，anon/authenticated 均无调用权限。

目录与汇总

参数：since inclusive、before exclusive，默认最近30天，最多366天；limit 默认50、范围1..100；appId、productId、releaseId 仅缩小已获授权的集合；family 目前仅 runtime。不接受 userId、teamId 或 audience 覆写身份。

nextCursor 是不透明字符串，下页可只传 cursor，继承原窗口、过滤和微秒水位。排序键为 (created_at, request_id) 倒序；服务端重新校验 cursor 的身份、过滤与 anchor 归属，不能借别人的 ID 判断存在性。cursor 不适用于汇总接口。

asOf 限定请求创建范围，observedAt 表示本次读取；既有请求的迟到事件、结算和退款仍可能变化。数据库创建时间不是事务提交序号，目录不承诺跨 HTTP 快照。刷新须从窗口首页重扫，或按原 requestId 使用新水位补查明细。nextCursor=null 仅说明这次查询没有下一页，不表示财务结算永久完成。

响应固定 schemaVersion:1、family:runtime、unit:milli-credit、basis:request_created_at、historyComplete:false、requestFinality:not_guaranteed，并提供 coverage includes/exclusions。部署前起始覆盖水位为 not_verified，不能声称历史齐全。

目录项含 requestId/clientRequestId/operation/createdAt/source/usage；source 仅公开安全来源和 authorizationRelease 白名单，不输出 token、付款凭据、请求正文或原始 context。来源绑定 kind 为 explicit_release 或 authorization_revision；后者不能当作 Host 精确 release 绑定凭证。

usage 分别返回 request/event/model-attempt 数量语义；模型 attempt 数不是用户调用次数。金额是十进制整数字符串。known 前缀字段只合计已有数值，完整金额在任一对应事实未知时为 null；没有事件也不能视为免费或成功。实扣、退款、净实扣、已记录应计分别呈现，不能相加。权益金额尚未投影时为 null/not_projected；平台成本账没有实际供应成本金额，返回 null/unknown。

原请求明细

GET /api/billing/v1/me/receipts?requestId=... 只接受全局服务端 requestId；跨来源 clientRequestId 可能碰撞，不支持它。事件下页用 after=<nextCursor>&asOf=<原水位>，最多100条；水位冻结事件创建范围，revision仍可能变化。最新视频预留与 ASR价格投影保持。

非法窗口/参数/cursor为400，缺权限403，跨身份和不存在的明细均404，数据库故障503；不以空目录或零金额掩盖故障。所有响应 Cache-Control:no-store。

验证涵盖隔离 PostgreSQL 15/17 的真实 runtime/video/platform-cost 迁移、角色ACL、跨身份、同微秒分页、原桶退款、token删除保留、迟到事件和全集汇总，以及服务/HTTP权限测试。它们不等同生产验收。

发布方统计

GET /oauth/developer-platform/teams/:teamId/products/:productId/billing/usage 使用独立 developer:billing scope 与现 Developer Platform 官方Host名单。每次按当前Team owner/accepted membership、assigned plugin Product、primary App同Team/Project和Project read权限重验；曾经拥有产品不能继续访问。开发者不获消费者明细或跨产品查询权。

只接受UTC日期 since=YYYY-MM-DD 和exclusive before=YYYY-MM-DD，默认包含今天的30天，最多90天；不接受消费者、子日、cohort或任意多维筛选。返回整窗totals、独立daily/versions分布、observedAt/windowEndExclusive/windowIncludesPartialDay；可见今日桶另有isPartial。统计按请求创建日归属，后续结算/退款会更新，不能当已封账报表。

分布中不足5名已知actor的桶合并到无日期/版本标签的suppressed；来源无法绑定版本时显示unknown，不能猜最新release。整窗保留准确会计金额，小桶处理不保证匿名或防差分推断。响应不含消费者ID、token、请求列表或内容；这些金额是消费者用量/钱包事实，不是开发者收入。

金额和数量保持十进制字符串。客户端10秒等待限制不等于数据库服务器执行上限；生产数据库超时及真实查询计划另在发布检查中确认。隔离PG15/17两万请求、四万事件的查询验证只是测试样本，不能视为线上性能承诺。

开通及回退

本批定义迁移不会给生产App/token扩权或写入Host名单。实际Host开通需具体App/version CAS、名单配置和重新consent；修改现有admin-managed Host scopes会撤销旧token families，必须先明确影响。查询迁移回退禁用新scope、撤回Usage Requests路由并保留历史审计；disabled不删除旧同意，未来重新启用需另核对旧token恢复访问的影响。

用户历史按原始请求发起人（冻结actor.userId）归属。多人继续同一个run时，各执行段仍合并到原请求；执行者身份另行冻结用于审计，当前目录没有独立的“我代别人执行”视图。发布方用量要求当前Team成员及关联Project读权限，只是聚合用量和钱包扣退，不能解释为开发者收入或收益分账。

性能边界：发布方整窗统计和本人汇总仍实时聚合窗口内事实，扫描量随主体用量增长；分页的有界查询不能证明热门主体的汇总耗时。尚无生产p95/p99或超时率验收，不承诺SLA。发布验收需记录这些指标与错误率，达到查询超时则返回503，不能返回部分金额或零额；按日预聚合属于后续工作。