Core 与 Edge 内部新增接口需求
API 逐项需求、源码归属、字段与验收条件
以下是新增接口设计提案 v0.1，并非 new-api 已有路由或已实现 API。已有接口足以覆盖时继续沿用，不重复建设；这张表明确跨服务和业务缺口需要什么，具体端点可在实现前评审定版。所有请求/结果都需在 Contracts 补精确 Schema 与错误码。
内部接口使用服务身份并验证用途/归属，不直接暴露公网；客户接口使用客户会话，员工接口校验具体权限。错误需求统一覆盖输入非法、认证失败、权限拒绝、资源不存在、余额不足、幂等冲突、版本冲突、限流和依赖不可用；采用与已有接口一致的包络并给出稳定机器码，不伪装为现有上游错误码。
INT-01 · POST /internal/v1/operations/admit
身份与范围：Edge/受控产品服务。
请求字段需求：credential 或 Core 可验证委托身份；request_id、idempotency_key、request_digest、model、protocol、usage_limit。
返回字段需求：operation_id、reservation_id、price_version、授权限制、执行许可与过期时间。
业务与幂等：Core 原子校验客户/Key/模型/预算，保存操作和额度预留；同键同摘要返回原操作，异摘要冲突。无可估上界先报价或拒绝，不凭 client account_id 扣款。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-02 · GET /internal/v1/operations/:id
身份与范围：Edge/Worker。
请求字段需求：Path id；服务身份与操作权限。
返回字段需求：执行状态、账务状态、价格依据、reservation、上游关联、结算结果与更新时间。
业务与幂等：读取 Core 持久事实；受理响应丢失后优先查询，不重新执行。仅所属服务/获授权产品可读。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-03 · POST /internal/v1/operations/:id/usage
身份与范围：Edge/Worker。
请求字段需求：attempt_id、event_id、gateway_request_id、计量单位与数值、final 标记、证据摘要、结束原因。
返回字段需求：接收/已存在/冲突、用量版本、是否可结算。
业务与幂等：同事件去重，完整性和可信来源校验；中间量不能冒充最终量，超时无用量标待核对。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-04 · POST /internal/v1/operations/:id/settle
身份与范围：Edge/Worker。
请求字段需求：settlement_key、最终用量版本/摘要、attempt_id；不接受任意客户端金额。
返回字段需求：settlement_id、已扣积分、释放预留、ledger_ref、原结果或冲突。
业务与幂等：按价格快照在 Core 事务中一次结算；重复调用返回同结果，缺失用量或冲突不得默认为免费。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-05 · POST /internal/v1/operations/:id/release
身份与范围：Worker/受控协调服务。
请求字段需求：release_key、原因、未执行/不计费证据与尝试状态。
返回字段需求：已释放/已结算/待核对、ledger_ref。
业务与幂等：仅确认释放条件后执行；断流、超时或租约过期不自动证明未执行。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-06 · POST /internal/v1/operations/:id/attempts
身份与范围：执行服务。
请求字段需求：attempt_id、gateway 标识、上游请求/任务 ID、提交状态、版本。
返回字段需求：已关联/已存在/冲突及最新版本。
业务与幂等：记录确定执行关联；禁止覆盖已完成尝试，结果未知禁止无依据新增重复供应尝试。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-07 · POST /internal/v1/tasks
身份与范围：受控产品服务/Edge。
请求字段需求：受托客户上下文、幂等键、model/plugin、输入引用、产品关联、usage_limit。
返回字段需求：task_id、operation_id、reservation_id、受理状态。
业务与幂等：授权/预留/持久待执行记录原子受理；产品 Workflow 不直接写 Core 库。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-08 · GET /internal/v1/tasks/:id
身份与范围：受控产品服务/Edge。
请求字段需求：Path id；调用身份。
返回字段需求：task/operation 状态、结果引用、费用状态、错误、cancel 状态。
业务与幂等：返回经过归属过滤的任务；隐藏供应密钥及任意内部 URL。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-09 · POST /internal/v1/tasks/:id/cancel
身份与范围：受控产品服务/Edge。
请求字段需求：cancel_key、原因、预期任务版本。
返回字段需求：cancel_requested/confirmed/unsupported/finished，账务状态。
业务与幂等：取消意图与供应确认分开；已产生费用不伪装全额退款，重复取消不重复调用。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。
INT-10 · GET /internal/v1/access/keys/:id
身份与范围：Edge 服务。
请求字段需求：Path 非秘密标识；服务身份。
返回字段需求：最小有效状态、客户关联、模型范围、有效期、撤销版本。
业务与幂等：只作为需要时的鉴权缓存能力；不得把可取回完整 Key 的客户接口直接开放为服务批量导出。认证方案若直接由 INT-01 校验，可不启用本接口。
验收：成功；字段缺失/越界；无效身份；跨账户/跨服务访问；重复请求与异内容同键；并发版本冲突；持久化后响应丢失与重查；依赖故障后可恢复。