From 62cce22312c55fa85f663ea64b7ac6c8d430a92c Mon Sep 17 00:00:00 2001 From: makewheels <33256842+makewheels@users.noreply.github.com> Date: Fri, 30 Oct 2026 14:44:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20[M016]=20=E5=9B=BA=E5=AE=9A=E4=BB=BB?= =?UTF-8?q?=E5=8A=A1=E5=8F=97=E7=90=86=E5=8F=8A=E6=81=A2=E5=A4=8D=E5=8D=8F?= =?UTF-8?q?=E8=AE=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/CHANGELOG.md | 6 + docs/design/serverless-backend.md | 4 +- .../overview/remaining-work.md | 4 +- .../overview/status.md | 10 +- .../2026-10-14-serverless-backend/plan.md | 4 +- .../2026-10-14-serverless-backend/progress.md | 8 ++ .../tasks/README.md | 1 + .../tasks/task-acceptance-recovery.md | 108 ++++++++++++++++++ .../upload/local-output-registration.md | 2 +- .../verification.md | 10 ++ 10 files changed, 147 insertions(+), 10 deletions(-) create mode 100644 docs/requirements/2026-10-14-serverless-backend/tasks/task-acceptance-recovery.md diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 7e53d4d9..2ec54f7f 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,11 @@ # 变更日志 +## docs: [M016] 固定任务受理与恢复协议(2026-10-30) + +- 交付源码可审阅设计:完整意图、既有task/attempt/HTTP、每次deadline护栏、重复/乱序/ACK与崩溃矩阵。SUBMITTED不等于确认受理,MPS另有扫描/租约,未知付费请求不立即重发;不只保护首次提交或删除恢复来实现零空扫。 +- 产品/有限保留/死信/费用及可能技术收件箱字段索引明确待实验/确认;无运行时代码、新资源或业务模型变更。已有Java2项/进程模型7项本次未重跑,实际文档/台账门禁与最终head CI记录于本PR,不把设计当M017–M023通过。 +- 用户已授权17:00前分批验证后普通merge;#232终版CI成功后14:24合并为`a78813b9`。固定90项现5交付、剩余85,不以任务数换算总体进度或宣称真实FC上线。 + ## feat: [M027] 迁移LOCAL内部产物扫描登记([PR #232](https://github.com/makewheels/video-2022/pull/232),2026-10-30) - #231已按用户授权合并;继续迁移真实LOCAL完成方法的侧车/校验/签名清单/全前缀/分片/Transcode登记前缀,显式内部工厂,不安装半条完成HTTP或提前READY。 diff --git a/docs/design/serverless-backend.md b/docs/design/serverless-backend.md index e22b7e27..1f1fa22b 100644 --- a/docs/design/serverless-backend.md +++ b/docs/design/serverless-backend.md @@ -52,7 +52,9 @@ flowchart LR **未解决门槛:Mongo 写入与任务投递不构成原子事务。** 单纯“写库后发队列”会在两步之间崩溃时丢工作;反过来投递后写库同样有间隙。Mongo outbox 只有在有可靠唤醒/消费来源时才完整,不能取消所有扫描后宣称不会丢任务。 -原型需对比:先进入受持久化保障的编排,再执行业务步骤;或可靠 outbox 消费(需核实 replica set/change stream、断连恢复和常驻依赖);或低频兜底扫描。最后一项会产生无用户请求调用,与严格零空扫有取舍。尚未选定产品/机制,必须在保留任务恢复及既有响应语义的前提下确认,不擅自增加新业务字段或减少故障恢复能力。 +原型需对比:先进入受持久化保障的编排,再执行业务步骤;或可靠 outbox 消费(需核实 replica set/change stream、断连恢复和常驻依赖);或低频兜底扫描。最后一项会产生无用户请求调用,与严格零空扫有取舍。[M016源码协议设计](../requirements/2026-10-14-serverless-backend/tasks/task-acceptance-recovery.md)推荐完整意图先获持久受理,每次活跃转换先建立deadline唤醒再CAS,处理完且后继可恢复才ACK;产品及存续/费用须M017真实实验,运行时仍待M018–M023,不增加业务字段、不删除旧恢复。 + +现有SUBMITTED在付费HTTP之前写入,不等于已获受理确认;崩溃后缺requestId不能立即重发。PROCESSING登记租约、429/业务退避和单独MPS查询租约也都要覆盖,不只保护首次提交。原HTTP返回、全部档位先保存、未知付费受理和有限重试语义见M016;死信/保留期限和技术收件箱需求明确列为未证实/待确认,设计不冒充云平台验收。 ## 5. 分组、兼容和回退 diff --git a/docs/requirements/2026-10-14-serverless-backend/overview/remaining-work.md b/docs/requirements/2026-10-14-serverless-backend/overview/remaining-work.md index 0368bc0c..1b779cdf 100644 --- a/docs/requirements/2026-10-14-serverless-backend/overview/remaining-work.md +++ b/docs/requirements/2026-10-14-serverless-backend/overview/remaining-work.md @@ -11,7 +11,7 @@ - 前置栏只列本台账内的实际依赖,`无`表示可利用已合并基线独立推进,不表示可跳过旧行为调查。外部权限、费用、生产变更需要具体授权,任务编号本身不是授权。 - 每项完成后记录实际用时、阻塞等待和复验结果;有了同类任务实测数据再修正工期。**完成项数不是工作量百分比**,本表完成率也不是整个项目的完成率。 -当前:**4已交付 / 0进行中 / 1阻塞 / 85待做**,基线剩余86项。M030–M032已合并[#231](https://github.com/makewheels/video-2022/pull/231);M027隔离实现/本机验收已交付,当前工作分支未合并,完整CI见本批PR当前head。固定分母不变;这不是生产完成率。 +当前:**5已交付 / 0进行中 / 1阻塞 / 84待做**,基线剩余85项。M030–M032已合并[#231](https://github.com/makewheels/video-2022/pull/231),M027已合并[#232](https://github.com/makewheels/video-2022/pull/232);M016本PR交付可审阅设计,不是可靠任务运行时。固定分母不变;这不是生产完成率。 ## 发布、网络及已有能力的剩余验收 @@ -41,7 +41,7 @@ | 编号 | 归属 | 交付物 | 关键验收 | 前置 | 状态 | |---|---|---|---|---|---| -| M016 | S12 | 受理意图及恢复协议的可审阅设计 | 固定现有业务键/attempt/返回语义和崩溃点;新增技术字段/索引等单列确认,不暗改业务模型 | 无 | 待做 | +| M016 | S12 | [受理意图及恢复协议的可审阅设计](../tasks/task-acceptance-recovery.md) | 固定现有业务键/attempt/返回语义和崩溃点;新增技术字段/索引等单列确认,不暗改业务模型 | 无 | 已交付 | | M017 | S12 | 托管唤醒与deadline真实平台实验 | 受理确认、重复投递、可见性、延迟粒度、保留/死信和空闲费用有证据;收费/扩权先授权 | M016 | 待做 | | M018 | S12 | 可恢复的任务受理与持久化 | 覆盖保存/投递先后两种间隙,成功响应有可恢复依据;不靠尽力发通知 | M016、M017 | 待做 | | M019 | S12 | 事件触发消费者及可靠唤醒适配 | 重启后能处理完整意图,找不到任务不能盲目确认;无常驻消费者/保活 | M018 | 待做 | diff --git a/docs/requirements/2026-10-14-serverless-backend/overview/status.md b/docs/requirements/2026-10-14-serverless-backend/overview/status.md index 2897a46c..7648351c 100644 --- a/docs/requirements/2026-10-14-serverless-backend/overview/status.md +++ b/docs/requirements/2026-10-14-serverless-backend/overview/status.md @@ -1,8 +1,8 @@ # 总体进度与剩余清单 -更新:2026-10-30。远端master为`dec7a776`,[PR #231](https://github.com/makewheels/video-2022/pull/231)订阅写入/通知已按用户授权合并;该PR终版CI40990924783成功,Python1531passed、Java783passed,API/浏览器E2E跳过。合并后的部署另验,不能把既有Java部署或原型CI当Python真实FC上线。 +更新:2026-10-30。14:24现场已按用户“分批merge,继续干”授权合并[PR #232](https://github.com/makewheels/video-2022/pull/232),本批基线master为`a78813b9`;#232终版head `4a1ddd30`的CI40999329017实际成功,Python1616passed、Java784passed,12项成功/2项API及浏览器E2E跳过。#231也已合并;合并后部署另验,不能把既有Java部署或原型CI当Python真实FC上线。 -剩余执行改用[固定任务台账](remaining-work.md):基线90项,M001–M090,不再扩展字母子编号。M030–M032已合并,M027内部LOCAL扫描登记隔离交付、工作分支未合并;剩余86项,完整CI以新PR当前head为准。历史S阶段和PR编号保留,不重算已交付成果。 +剩余执行改用[固定任务台账](remaining-work.md):基线90项,M001–M090,不再扩展字母子编号。M030–M032及M027已合并;本PR另交付M016受理/恢复协议设计,基线剩余85项,真实平台及运行时仍未交付。完整CI以各PR最终head为准;历史S阶段和PR编号保留,不重算已交付成果。 ## 两个工程分别看 @@ -15,7 +15,7 @@ ## 一眼看懂当前位置 -- 后端迁移总计 **25个大阶段**,编号S00–S24;**M030–M032已合并,M027隔离交付待合并**。S10上传、S11 LOCAL、S12可靠任务和真实FC/各端验收仍未完成,不表示此前阶段全部完成。 +- 后端迁移总计 **25个大阶段**,编号S00–S24;**M030–M032及M027已合并,M016本PR交付协议设计**。S10上传、S11 LOCAL、S12可靠任务和真实FC/各端验收仍未完成,不表示此前阶段全部完成。 - 应用户2026-10-16要求给出沟通用百分比:**整体开发工作量粗估约25%,剩余约75%**。这是基于已完成/部分阶段的人工估算,误差较大,不是实测或生产验收完成率;生产尚未切换。 - **3已交付 / 2阻塞或未验 / 10部分完成 / 10主体未迁移**。S10/S11/S12/S14/S15均有隔离能力,但仍缺各自剩余业务或真实环境验收;不能按PR数量或已写模块数换算上线百分比。 - S09固定拆为 **14个子任务:13已合并、1待验**;m.1–m.3隔离装配/入口/编码矩阵已合并,n真实环境仍未验。S10.a.1已合并#216、a.2/b.1普通创建#217、c.1凭证/文件完成#218;b.2状态轮询已合并#219;原片可靠受理/MD5等仍缺。 @@ -59,8 +59,8 @@ | 09/25 | S08 播放/清单/文件 | 部分实现 | 观看信息/主子清单已合并;文件重定向#196已合并,完整下载/计费/端到端仍缺 | | 10/25 | S09 心跳/进度/会话/历史 | 隔离能力已合并,真实环境待验 | a–m共13子项与统一装配/HTTP/日志/编码已合并;n真实FC与各端验收仍依赖S03/S04 | | 11/25 | S10 上传/MD5/AUTO去重 | 部分实现 | #216–#219创建、凭证/文件确认和状态轮询已合并;原片完成、MD5/AUTO及可靠受理待做 | -| 12/25 | S11 LOCAL登记 | 部分实现 | #221–#224迁移封面/档位登记、校验和就绪窄写;M027内部扫描已隔离交付待合并,M028完成/可靠副作用和M029真实云端/各端链路仍待做 | -| 13/25 | S12 可靠任务/恢复 | 故障实验已交付,方案/运行时待做 | #220进程终止模型确认写库/投递与未知受理间隙;真实托管唤醒、deadline和恢复协议仍未解决 | +| 12/25 | S11 LOCAL登记 | 部分实现 | #221–#224迁移封面/档位登记、校验和就绪窄写,M027内部扫描#232已合并;M028完成/可靠副作用和M029真实云端/各端链路仍待做 | +| 13/25 | S12 可靠任务/恢复 | 故障基线及M016协议设计已交付,运行时待做 | #220进程模型与M016推荐协议不等于真实托管唤醒/deadline通过;M017实验及M018–M023实现/验收仍待做 | | 14/25 | S13 云任务/回调/MPS | 主体未迁移 | 把既有Java任务/回调/恢复迁入Python,不能重复计费或双所有者 | | 15/25 | S14 评论回复 | 隔离读写能力已交付 | #225读取、#227创建/回复/级联删除/点赞切换;尚未接生产入口,真实FC和各端验收仍待做 | | 16/25 | S15 赞踩/订阅/通知 | 隔离HTTP能力已合并,真实验收未齐 | 赞踩#229、订阅读取#230、M030–M032订阅写入/通知#231已合并;真实FC/各端归M040,不新增原本未调用的通知生成业务 | diff --git a/docs/requirements/2026-10-14-serverless-backend/plan.md b/docs/requirements/2026-10-14-serverless-backend/plan.md index b30aa755..6c34201a 100644 --- a/docs/requirements/2026-10-14-serverless-backend/plan.md +++ b/docs/requirements/2026-10-14-serverless-backend/plan.md @@ -47,7 +47,9 @@ S12 可以提前调查,但依赖可靠任务的写业务不能在它未通过 总计划25个里程碑S00–S24保留,S09历史a–n及原PR证据不重编号。**2026-10-30起,剩余执行统一使用[固定任务台账](overview/remaining-work.md)的M001–M090**;每项列交付物、验收、依赖和状态,不再扩展字母层级。新PR标题用`[M030]`或明确任务范围,正文记录S阶段归属、已验/未验与回退点;总体状态仍见[总表](overview/status.md)。 -M027内部LOCAL扫描没有独立旧HTTP,以真实旧方法/完整BSON、普通能力/适配与显式内部工厂交付,不新增半条完成HTTP。69组旧样本、本机Java8项/Python相关314项已实际通过;新PR/完整CI另记,M028/M019完成及可靠副作用不顺带标完,不为内部步骤加新编号。 +M027内部LOCAL扫描没有独立旧HTTP,以真实旧方法/完整BSON、普通能力/适配与显式内部工厂交付,不新增半条完成HTTP。69组旧样本、本机Java8项/Python相关314项已实际通过;#232最终head CI成功后已按用户批次授权普通合并,M028/M019完成及可靠副作用不顺带标完,不为内部步骤加新编号。 + +M016另交付[完整意图及恢复协议设计](tasks/task-acceptance-recovery.md),其设计成果不代替M017真实平台实验或M018–M023运行时。2026-10-30下午继续至17:00,已授权验证通过后分批普通merge;16:40起只收尾已有批次。云资源/费用/扩权、生产配置/切流及新业务模型仍须具体授权,不因截止时间跳过门禁。 ## 每个 PR 的交付要求 diff --git a/docs/requirements/2026-10-14-serverless-backend/progress.md b/docs/requirements/2026-10-14-serverless-backend/progress.md index f81ed26b..0c5b6f7b 100644 --- a/docs/requirements/2026-10-14-serverless-backend/progress.md +++ b/docs/requirements/2026-10-14-serverless-backend/progress.md @@ -1,5 +1,13 @@ # 接续记录 +## 2026-10-30 下午批次合并与M016设计 + +- 用户要求继续至北京时间17:00,随后明确“分批merge,继续干”。此授权覆盖验证通过后的普通批次合并,不包含新增收费资源、RAM扩权、生产配置/切流或业务模型变更;旧记录中的逐批等待所有者合并不再作为本次执行限制。 +- 14:24:26按#232最终head `4a1ddd309d75ee075b22fc19a29e924df5d6cc26`核验CI40999329017(12成功/2条件E2E跳过,Python1616passed、Java784passed)后正常合并为`a78813b936b6e78180feacd62a9d1632cb8b135d`;本地master干净快进,新分支`feat-m016-task-recovery-20261030`。未据此宣称合并后部署或Python切流已通过。 +- M016交付[完整意图及恢复协议](tasks/task-acceptance-recovery.md):固定真实taskId/attempt/字段、四类确认、原HTTP形状、每个deadline转换和崩溃出口;特别指出SUBMITTED先于付费调用,MPS另有独立30秒扫描,不能靠“没requestId”重发或只删除旧扫描。 +- 推荐完整意图先持久受理、活跃转换前建立托管deadline护栏、条件认领与后继可恢复才ACK。产品/有限保留窗口/费用及可能收件箱字段索引明确待M017证明/另行确认;仅文档,无新运行时/资源/数据修改。已有Java2项/进程模型7项未在本次重跑,文档/台账检查和当前head CI另记本PR。 +- 固定90项为5交付/1阻塞/84待做、剩余85;设计交付不把S12或M017–M023标完成,不据任务数提升粗估百分比。后续优先现有独立M033真实旧提交/回调/完整BSON契约,16:40起不再开新批次,收尾验证/普通合并/清理,不为时间点绕门禁。 + ## 2026-10-30 合并#231并继续M027 - 用户明确要求“merge继续做”。现场复核#231原head `73422dde`未变化、12项CI成功/2项E2E跳过,按仓库普通merge方式合并为`dec7a776b8d2678ed08b6ea02538244a26f68dd6`,本地master已干净快进。此前CI全量Python1531passed/Java783passed;不将旧head结果冒充后续master部署。 diff --git a/docs/requirements/2026-10-14-serverless-backend/tasks/README.md b/docs/requirements/2026-10-14-serverless-backend/tasks/README.md index 55f62be9..35857dd7 100644 --- a/docs/requirements/2026-10-14-serverless-backend/tasks/README.md +++ b/docs/requirements/2026-10-14-serverless-backend/tasks/README.md @@ -4,5 +4,6 @@ | 文档 | 内容 | |---|---| +| [task-acceptance-recovery](task-acceptance-recovery.md) | M016 源码身份、受理/ACK/deadline协议、崩溃矩阵及待确认技术模型;设计不冒充运行时 | | [task-submission-persistence](task-submission-persistence.md) | S12.a 提交持久化故障基线 | | [process-crash-experiment](process-crash-experiment.md) | S12.b.1 真实进程终止下的模型受理间隙和重复认领;非云队列验收 | diff --git a/docs/requirements/2026-10-14-serverless-backend/tasks/task-acceptance-recovery.md b/docs/requirements/2026-10-14-serverless-backend/tasks/task-acceptance-recovery.md new file mode 100644 index 00000000..8d4cc8f6 --- /dev/null +++ b/docs/requirements/2026-10-14-serverless-backend/tasks/task-acceptance-recovery.md @@ -0,0 +1,108 @@ +# M016 任务受理意图与恢复协议 + +[固定台账](../overview/remaining-work.md) · [候选架构](../../../design/serverless-backend.md) · [提交故障基线](task-submission-persistence.md) · [进程终止实验](process-crash-experiment.md) + +状态:**可审阅设计交付,不是可靠任务运行时交付**。2026-10-30现场源码基线为合并#232后的`a78813b9`。推荐“完整意图先获托管持久受理,消费者重建既有任务,每次活跃状态转换先建立可靠唤醒护栏”;具体产品、有限保留的恢复窗口、权限和费用必须由M017实验证实。M018–M023尚未实现,不停用Java恢复、不创建云资源、不变更生产配置或数据库模型。 + +## 现有源码事实 + +| 边界 | 现有行为与迁移约束 | 源码 | +|---|---|---| +| 原片完成 | 存在性/视频状态/文件READY检查后启动`new Thread`,HTTP先返回`Result.ok()`;线程失败只记日志,不是持久受理 | [VideoService](../../../../server/video/src/main/java/com/github/makewheels/video2022/video/service/VideoService.java)、[RawFileService](../../../../server/video/src/main/java/com/github/makewheels/video2022/video/service/RawFileService.java) | +| 业务身份 | `fc--`;PROBE用videoId,TRANSCODE用transcodeId,COVER用coverId。TRANSCODE记录ID另为`tr_fc__` | [Submitter](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/task/FcTaskSubmitter.java)、[Launcher](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/TranscodeLauncher.java) | +| attempt | 构造默认count=0、max=2;现有启动器准备首个attempt时设count=1。业务失败重试才生成后缀并增加count;429和消息重投不等于新业务attempt | [FcTask](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/task/FcTask.java)、[Callback](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/task/FcTaskCallbackService.java) | +| 付费提交 | 先保存完整snapshot并CAS `CREATED→SUBMITTED`,再发HTTP;成功后只条件更新requestId,不能覆盖快速回调。**SUBMITTED实际上不证明平台已受理**,不能照字段注释推断 | [Submitter](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/task/FcTaskSubmitter.java)、[Repository](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/task/FcTaskRepository.java) | +| 输出隔离 | 既有outputBaseDir下`attempts/`;playlistKey/imageKey改为该目录加原basename,result manifest固定为该outputDir下`result.json` | [Submitter](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/task/FcTaskSubmitter.java)、[Callback](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/task/FcTaskCallbackService.java) | +| 多档竞态 | 所有Transcode及准备完的FcTask先保存,之后才逐档发送;不能让首档快速回调误以为全档已完成 | [Launcher](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/TranscodeLauncher.java) | +| MPS兜底 | fallbackCount原子0→1,只允许一次;30分钟deadline。`FALLBACK_PENDING`由单独的30秒`pollFallbacks`扫描,不在FcTimeoutRecovery的超时集合;已有job仅查询 | [MPS fallback](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/mps/MpsFallbackService.java)、[Recovery](../../../../server/video/src/main/java/com/github/makewheels/video2022/transcode/task/FcTimeoutRecoveryService.java) | + +`fcTask`已有operation/videoId/refId、attemptId/count/max、provider/fcRequestId、status/deadline/errorMessage、payloadSnapshot/outputBaseDir/resultManifestKey/executionTimeoutMs/submitFailures、createTime/finishTime。优先复用,消息ID、投递次数和平台执行状态不取代它们。 + +## 完整意图不是“有一个taskId” + +| 受理阶段 | 必须可恢复的既有输入 | 不能偷偷增加的行为 | +|---|---|---| +| 原片处理尚未创建FcTask | 旧调用命令及videoId;消费者按原RawFileService顺序回读Video/File,LOCAL/AUTO等分支保留 | 不把“完整”误解为冻结所有Video字段,不新增rawFileId版本校验、所有者规则或伪FcTask | +| 已准备PROBE/TRANSCODE/COVER | 既有完整任务身份、attempt和参数、原payloadSnapshot、输出基目录及超时;源key、bucket/endpoint、媒体策略等须足够重建缺失任务 | 不在缺任务时只凭ID猜profile、源对象、provider或默认媒体策略;不覆盖新attempt | +| 活跃任务唤醒 | 既有taskId、attemptId、目标status和deadline,以及执行片段类别;恢复仍回读权威业务记录 | 不把队列接收次数写成attemptCount,不新增业务状态、终态或统一重试规则 | + +业务层只接普通值/能力,不接FC event、SDK receipt或BSON对象;消息适配器须无损往返既有Date、Integer/Long、缺失/null和payload内容,类型契约留M033/M018实测。沿用媒体payload的schemaVersion=1,不凭本设计添加业务版本语义。 + +入队前执行旧HTTP既有鉴权/绑定/检查顺序;异步内容只存必要输入或受控对象引用,不含用户token、STS凭证、调用/回调secret、视频字节或整份分片。现有CloudFunctionClient的secret在发送header里取配置,不在snapshot里;YouTube带token的旧URL等不能直接复制成通用任务载荷,另归对应任务调查。 + +## 推荐的受理、消费与确认协议 + +1. **受理端**先完成旧同步前置检查,生成完整意图,经托管服务取得持久受理确认后才返回原成功响应。不能先写Mongo后尽力通知,也不能把线程启动、SDK本地排队或HTTP连接成功当持久确认。受理异常/结果未知须沿既有错误路径显式记录并返回错误,不返回假成功;重试仍用原业务键,不为一次不确定响应创建新付费身份。 +2. **消费端**用完整意图`createIfAbsent`重建缺失任务,再回读权威记录。只通知ID且任务不存在时不能ACK;反序、重复、终态及旧attempt不覆盖当前记录。任务准备仍保持全部档位先保存、后发送。 +3. **每个活跃转换**先可靠登记覆盖目标deadline的唤醒,再用既有业务键/attempt/预期状态及观测deadline做CAS。CAS失败只产生可安全忽略的冗余唤醒,不产生第二次付费提交;平台登记失败则不开始该片段的付费副作用。新增deadline条件是对已有字段的并发约束,不是新业务字段。 +4. **执行端**仅CAS赢家发送一次,保留原固定长度HTTP发送和禁止隐式重放的策略。2xx后只条件补fcRequestId;429沿原计数/等待;HTTP0/5xx或发送中崩溃保持未知受理,等原deadline/核对,不立即重新付费。 +5. **ACK是传输确认,不是业务成功。** 只有任务已终结/确属过期消息,或当前片段已持久落地且其后续活跃deadline有可靠护栏时,才确认本条投递。保存任务、调用返回或打印日志本身不足以ACK。无法证明后继护栏时先补当前状态的可靠唤醒;失败保留消息重投并显式告警,不静默吃掉。 +6. **延迟消息处理**回读状态并比较attempt/目标状态/deadline;旧消息无权触发新attempt的失败或提交。提前投递按实际deadline重新可靠安排,不靠进程sleep;到期消息只触发当前应执行的恢复片段。数据库/对象服务临时失败用传输重投,不额外增加业务attempt。 + +上述“登记护栏→CAS→片段→ACK”是推荐的不变量,不是现有Java已经实现的能力。所有初始创建、重试、回调登记及MPS交接都必须遵循,不能只在首次SUBMITTED补一个计时器。托管调度与Mongo也没有跨系统事务;登记先于CAS,并在重复/陈旧投递时校验权威状态,才避免把该间隙搬到另一个位置。 + +原片入口没有现成FcTask时,持久托管活动必须保留完整命令直到下一可恢复边界,不允许消费者只留一个无法重建的通知。若候选产品无法满足此条件,M017结论应为不满足;需要技术收件箱/outbox时先单列字段/索引方案确认,不能为了赶进度暗建集合。 + +## 所有需要护栏的转换 + +| 转换/片段 | 沿用的业务语义 | 护栏后要恢复的动作 | +|---|---|---| +| 新建/重建CREATED | 同一业务键和已准备attempt、完整snapshot;保留原创建/部分写入顺序 | 同attempt认领发送,不另建收费任务 | +| CREATED→SUBMITTED | executionTimeoutMs显式值沿用;缺失才按旧逻辑至少300000ms。PROBE/COVER准备300秒,转码准备按原公式300–1740秒 | 到期按旧失败/重试策略;不能把requestId缺失当未发送 | +| 429→RETRY_WAIT | submitFailures增加,前29次等待60秒,同attempt;第30次走原不可重试失败 | 到期恢复CREATED后同attempt发送,仍先覆盖新deadline | +| 业务失败→RETRY_WAIT | 现有maxAttempts、attempt后缀、count和10秒加配置jitter;不将所有异常统一算业务失败 | 到期发送已经持久的新attempt;晚到旧回调继续忽略 | +| 成功回调→PROCESSING | 匹配既有result.json路径后CAS,保存manifestKey和5分钟登记租约 | 重放登记,不重转码;RegistrationException仍返回200并保留PROCESSING | +| PROCESSING到期 | 原恢复先改回SUBMITTED,再用保存的manifest重放成功回调 | 新的登记租约同样先登记可靠唤醒,不能只保护第一次 | +| CREATED/RETRY_WAIT到期 | 原恢复不增加attempt,缺snapshot按旧失败出口 | 先覆盖将写入的deadline,再CAS/重提;不编造缺失payload | +| 转入FALLBACK_PENDING | TRANSCODE且满足现有MPS资格/名额才交接;保留fallbackCount、currentProvider、jobId和30分钟deadline | 查询已有job、登记或原超时失败;名额占用/HTTP响应不确定时禁止重发MPS | +| MPS查询租约 | 原fallbackPollAfter认领5分钟,finally释放;不是FcTimeoutRecovery的PROCESSING | 活跃job的下一检查及租约崩溃恢复也要有托管唤醒,具体映射归M037/M021,不取消现有扫描冒充完成 | +| SUCCEEDED/FAILED | 既有终态和finishTime,重复回调不改变结果 | 旧唤醒只确认/清理,无新付费动作 | + +回调继续在原HTTP边界执行既有登记/返回语义,不因有队列就改成“入队即登记完成”。需要异步化某个旧同步接口时必须另做契约/明确授权,不由本设计顺带改变。 + +## HTTP与未知结果的兼容边界 + +- 原片GET及OpenAPI仍保留原路径、参数、成功`Result`形状,不改成202、工单号或新的必填字段。持久受理替代原线程是已确认目标;前置检查和部分写入顺序由M024真实旧HTTP固定。 +- 普通业务异常沿现有`GlobalExceptionHandler`/Result错误形状;它未设置异常HTTP状态,**HTTP200不能单独当业务成功**。不凭框架默认值换成422/503,不新增错误码掩盖未知受理;新适配必须验证实际错误正文/日志。 +- 自建回调secret缺失/不符为403空体;业务handler返回200/400/404映射相应HTTP,其正文仍是`Result.ok()`。旧attempt/终态或FALLBACK_PENDING可忽略;当前attempt的非法status/manifest路径仍按原顺序报错。M033固定真实HTTP与完整BSON,不凭“更合理”改形状。 +- 外部已受理但响应丢失和根本没发出在本地可能完全相同。fd/requestId日志只能辅助;不能据此证明未计费。业务期限后仍沿既有有限重试/兜底,不承诺付费动作的全局exactly-once。必要查询/manifest核对由M022实测,不擅自新增调用。 +- 内部投递ACK、普通API成功、自建回调200、媒体作业成功是四种不同结果,不互相替代。生产切换前还须核实发送端重试/确认语义,不能靠一个HTTP200闭环。 + +## 崩溃矩阵与责任出口 + +| 崩溃/故障点 | 恢复依据与允许动作 | 禁止 | +|---|---|---| +| 托管受理前 | API无成功承诺;原键重试 | 先成功再后台投递 | +| 平台已受理但确认丢失 | 完整意图可能已运行;重复受理按原身份归并 | 当作一定未受理而换taskId | +| 已受理但任务尚不存在 | 消费完整意图重建、回读;重建失败不ACK | 缺任务就丢消息,或凭ID造默认载荷 | +| 任务已存但消费消息未确认 | 重投读取状态,补护栏/安全忽略 | 扩增业务attempt | +| 护栏已登记但CAS前崩溃 | 原状态或重复意图继续;陈旧护栏核对后安全清理 | 把护栏存在等同已付费 | +| CAS后、付费发送前崩溃 | 已有deadline护栏;保守按未知受理处理 | 因没requestId立即重发 | +| 平台接受后/响应持久化前崩溃 | 同上;快速回调/期限核对决定下一步 | 覆盖已PROCESSING/终态,隐式HTTP重放 | +| 登记写了一部分后崩溃 | PROCESSING/manifest/租约恢复登记;沿旧幂等和部分写入 | 再编码,或回滚已登记对象冒充全成功 | +| RETRY_WAIT持久后/新投递前崩溃 | 转换前已登记的对应attempt/deadline唤醒 | 只保护第一次提交 | +| MPS名额占用/提交结果未知 | 保留已耗名额和原期限,已有job仅查;无jobId按原超时失败 | 重复耗费兜底或无期限静默悬挂 | +| 完成已存、ACK前崩溃 | 重投识别终态并确认 | 重做收费动作/覆盖finishTime | +| 超过传输重试/队列保留 | 独立死信/告警及明确再投责任;完整意图仍须可找回 | ACK错误当成功,宣称有限保留等于永久不丢 | + +已有本机实验覆盖若干模型间隙,**不等于上述目标协议或真实平台已经通过**。M023必须在最终选定产品上逐点杀进程/断响应,并验证数据库、托管活动、对象和付费调用次数;没有真实证据就不能停掉旧恢复。 + +## 保留期、成本与单所有者门槛 + +- M017须记录实际受理确认、重复/乱序、延迟粒度/提前投递、可见性/租约、保留/死信、重驱和服务端故障行为及来源,不预设某产品天然满足。请求ACK丢失和回调先于确认须单测。 +- 平台保留期、活动最长时间和最大停机恢复窗口必须有实测值/操作责任;有限保留不是永久保证。现有PROCESSING登记可以反复续租,不能擅自加总时长/次数使旧任务提前FAILED。若候选服务需要续投或额外持久收件箱才能保持该语义,先提出明确方案,否则不通过门槛。 +- 超过重试的死信须保留完整意图/错误并可安全再驱,告警不可依赖失效的同一消费者。未证明保留期内恢复和超期意图存续,不宣称“永不丢任务”。 +- 业务无活跃任务时不启动自有轮询/保活;托管服务的轮询、消息、定时器、日志、保留和最低费用仍逐项计算。MPS的活跃检查有实际调用,不用“无空扫”包装成零费用,也不擅自降低旧检查频率。 +- 真实产品/新增收费、RAM策略/资源、生产配置须另行授权。上线交接前以既有任务键划分唯一所有者;MPS、旧回调、在途Java任务也需M085/M086交接证据,不让旧扫描与新消费者并发收费,不直接关闭旧恢复。 + +## 技术模型与确认清单 + +| 项目 | 本设计建议/尚缺证据 | 是否本批执行 | +|---|---|---| +| 业务集合/字段/状态/索引 | 首选全部复用既有;不新增全局任务状态、attempt含义或金额/重试规则 | 否,无运行时/数据库改动 | +| 传输元数据 | 消息类型、投递ID、receipt/可见期限、目标status/deadline只属适配;平台值不成为业务状态 | 仅设计;具体wire编码在M017/M018证明 | +| CAS条件 | 现有键/attempt/status外核对观测deadline,防止旧唤醒认领后来同状态的租约 | 仅设计;M020并发证据待做 | +| 持久技术收件箱/outbox | 仅在托管完整意图存续能力不足且确有必要时提出独立集合/字段/唯一键/索引/清理方案 | 未选定、未授权、未创建 | +| 产品与保留/死信/费用 | M017在授权隔离环境提供可回读配置、真实事件和报价/账单边界 | 未实测,不用本机模型代替 | + +M016的完成标准是以上源码身份、返回语义、所有deadline转换、故障点和待确认项可审阅;不是M017–M023通过。已有Java提交故障2项、本机进程模型7项仍是历史覆盖,本次文档批次未重新运行它们。文档链接/围栏、固定90项状态/依赖与空白门禁及本PR最终head CI另记交付证据;回退仅需撤回本批文档,不触碰业务数据。 diff --git a/docs/requirements/2026-10-14-serverless-backend/upload/local-output-registration.md b/docs/requirements/2026-10-14-serverless-backend/upload/local-output-registration.md index 87c17891..efa60b00 100644 --- a/docs/requirements/2026-10-14-serverless-backend/upload/local-output-registration.md +++ b/docs/requirements/2026-10-14-serverless-backend/upload/local-output-registration.md @@ -2,7 +2,7 @@ [固定台账](../overview/remaining-work.md) · [档位创建](local-transcodes.md) · [产物校验](output-validation.md) · [全档就绪](video-readiness.md) -状态:隔离实现及本机验收已交付,[PR #232](https://github.com/makewheels/video-2022/pull/232)未合并。2026-10-30用户授权合并#231后继续;基线master `dec7a776`,功能分支`feat-m027-local-output-20261030`。本轮只交M027,不扩大到M028完成回调、Webhook可靠派发或视频READY副作用;终版head完整CI的实际核验记录以PR正文为准。 +状态:隔离实现及本机验收已交付,[PR #232](https://github.com/makewheels/video-2022/pull/232)于2026-10-30 14:24按用户批次授权普通合并为`a78813b9`。实现基线master `dec7a776`,功能分支`feat-m027-local-output-20261030`;终版head `4a1ddd30`的CI40999329017实际Python1616passed、Java784passed,12成功/2 E2E跳过。只交M027,不扩大到M028完成回调、Webhook可靠派发或视频READY副作用,不把合并当生产切流。 ## 真实边界与设计 diff --git a/docs/requirements/2026-10-14-serverless-backend/verification.md b/docs/requirements/2026-10-14-serverless-backend/verification.md index 7f9113fd..8a14e0e0 100644 --- a/docs/requirements/2026-10-14-serverless-backend/verification.md +++ b/docs/requirements/2026-10-14-serverless-backend/verification.md @@ -2,6 +2,16 @@ 日期:2026-10-14。状态:用户已确认开始,P1 隔离原型开发和本地验证;尚未部署 FC 原型、修改生产配置或切换业务流量。 +## M016 可审阅协议设计(2026-10-30下午) + +只交付[源码协议设计](tasks/task-acceptance-recovery.md)及必要状态/索引文档;无运行时代码、业务模型、配置或云资源改动。核对真实Submitter/Repository/Callback/Recovery、三个任务启动器、原片入口/全局错误映射和MPS单独恢复,不把状态注释误当实际受理确认。 + +- 设计覆盖完整意图重建、既有身份/attempt、护栏先于每次活跃转换、登记恢复不重转码、未知付费受理、MPS已有job只查、四类确认及有限保留/死信出口。新增技术收件箱等只是待确认项,没有新增字段/集合/索引或重试规则。 +- **已有覆盖**:Java提交故障2项及本机进程/并发模型7项,见tasks既有记录;**本次未重跑**,文档批次不以这些旧数字充新增测试。14:43实际检查10份变更Markdown/137个本地链接存在、围栏配对、固定90项/5交付/1阻塞/84待做且依赖无环,`git diff --check`通过;最终head CI另持久记录在本PR。 +- M017真实托管受理/延迟/保留/死信/收费、M018–M023运行时/崩溃证据、FC网络、生产切流均未做;旧Java恢复和生产所有者不变。回退只撤本文档,不恢复业务数据库。 + +#232已于14:24:26正常合并,merge `a78813b9`;其最终head `4a1ddd30`的CI40999329017实际Python1616passed、Java784passed,12成功/2 E2E跳过。下节为上午本机证据,不能当作下午重新跑过或M016运行时已通过。 + ## M027 LOCAL内部扫描登记验收(2026-10-30) #231已按用户授权合并为`dec7a776`后继续,Windows CPython3.12.12/JDK21.0.10/Mongo8.3.7。依赖确实缺少pytest后,按uv.lock恢复到系统临时目录;独享Mongo只绑定`127.0.0.1:13904`,显式覆盖Java全部`spring.mongodb.uri/host/port/database`,Python随机测试库,不接生产或已有27017。