Core / channel 内部协议 #
本接口只挂载于 CHANNEL_LISTEN，默认 127.0.0.1:8081。Compose 中为 :8081，仅容器网络可达。公共 :8080 不注册内部路由。内部接口不要求 Authorization；携带浏览器 Origin 的请求被拒绝。租约字段仅用于防止过期任务确认，不是服务认证。
所有路径以 /internal/v1/channels/{channel_id} 开头。渠道必须与 core 数据库配置的 Telegram channel 一致；租户由已登记渠道和输入 actor 解析，请求不接受 tenant ID。完整类型见 internal/channelapi/types.go。
| 方法与后缀 | 用途 |
|---|---|
GET /config |
Bot 配置、Web URL、持久化轮询 offset |
POST /events |
持久化规范化输入；按渠道与 update_id 去重；返回是否删除凭据原消息 |
POST /work/claim |
最长等待 20 秒；返回 work 和 90 秒租约，无任务返回 204 |
POST /work/{id}/ack |
续租、批次进度、message_id、完成或延后重试；重复完成确认幂等 |
POST /actions |
在 event 的 actor 上下文执行业务动作并保存结果；重试返回已存结果 |
GET /work/{id}/delivery |
收藏、任务暂停状态和集合进度（含中止状态）；由 channel 生成 Telegram 文本与按钮 |
GET /work/{id}/assets/{asset} |
校验领取任务的租户与资源权限后代理私有对象数据，支持 Range |
GET/PUT/DELETE /media-cache |
当前 Bot 的媒体远端引用缓存；缓存不作为内容授权依据 |
POST /work/{id}/normalize |
仅升级时使用，将旧 inbox 输入转成规范化 event |
领取返回的 lease 用于动作和确认请求；读取任务资源时置于 X-Work-Lease。每 25 秒续租。崩溃后租约到期可重新领取，progress 和 message_id 保留。TG channel 不连接 PostgreSQL、S3 或 gRPC Adapter。
输入确认和 offset 更新处于同一个数据库事务。账号凭据在持久化之前由 core 加密，完成或永久失败后清除暂存密文。账号对话存在数据库中，因此两个进程重启都不会丢失对话。已确认的媒体批次不会再次发送；发送成功但 HTTP/TG 确认丢失仍可能重复，协议不承诺恰好一次。
Web 继续使用公共 /v1 API，Telegram initData 的签名在 core 本地校验，不需要 channel 在线。已有收藏的查询与下载也不需要 Adapter 在线；采集和凭据校验才调用 Adapter。
internal/app 不处理 Telegram Update、SDK 调用或消息排版。历史 inbox 的解析在 channel 完成，core 的 /normalize 仅处理升级数据与凭据密文；历史 reply 的已存内容由 channel 发送。新任务统一进入 channel_work，不再生成 River 投递任务。