实现七月迭代公共技术基础

docs/tech-public-foundation/统一异步任务与前端轮询契约.md

@@ -0,0 +1,13 @@
+# 统一异步任务与前端轮询契约
+
+业务任务固定使用五态：`1=待处理、2=处理中、3=已完成、4=已失败、5=已取消`，所有公开投影同时返回中文状态名。各业务继续拥有自己的任务表、任务项和失败明细；公共基础不建设万能任务表。
+
+公开投影至少包含 `task_id`、状态与状态名、总数、成功数、失败数、进度、安全错误码与中文摘要、开始时间、完成时间和更新时间。业务项到达处理终点时使用“已完成”：部分成功和全部业务项失败均通过计数表达，且必须满足 `total_count = success_count + failed_count`；只有整体无法建立或执行到业务终点时才使用“已失败”。
+
+领取必须使用 PostgreSQL 预期状态条件更新。待处理任务可以进入处理中；处理中任务保存租约所有者与到期时间，仅过期租约可被其他 Worker 恢复。续租和进入终态都校验当前状态、租约所有者与有效期。队列重复投递遇到终态时直接返回，不制造第二次业务副作用。取消仅适用于业务明确支持的任务，并从待处理或处理中条件更新到已取消。
+
+调用统一 `EnqueueTask` 时载荷只包含 `task_id`、必要分片标识和关联标识，并以 struct 或 map 传入；禁止预序列化为 `[]byte`。
+
+前端首次加载显示占位；成功且确实无数据时才显示空态，筛选无结果提供清除筛选入口。403 显示无权限且不提供重试。瞬时失败保留已有数据和输入并提供显式重试。创建成功后持久保存 `task_id`，刷新或重新进入页面后恢复查询。
+
+待处理或处理中按 2 秒、3 秒、5 秒逐步退避，最长不超过 10 秒；终态停止轮询。页面隐藏时暂停，恢复可见后立即刷新一次，再按最新状态继续。网络恢复和页面刷新不得重新创建任务。