feat: add retention policy and stability verification

docs/api/retention.md

@@ -1,4 +1,38 @@
-# 保留清单（只读）
+# 数据保留与归档策略
+
+Orbit 将保留策略作为命名空间级数据库配置保存。控制台保持单管理员模型，登录后打开“保留策略”即可查看和修改窗口；每次修改都要求上一版本号、幂等键和变更原因，前后值写入 `orbit_audit_events`。多个 Orbit 节点读取同一个 MySQL 版本，因此不会因为节点环境变量不同而产生不同清理边界。
+
+首次安装和数据库策略尚未保存时使用部署默认值：幂等记录 90 天、任务历史 365 天、流程历史 365 天、事件日志 365 天、已确认交付 90 天、已处理 Inbox 90 天、管理审计 2555 天。默认 `enabled=false`，保存策略也不会立即删除数据。
+
+环境变量只负责首次展示/未保存策略的默认值：
+
+```text
+ORBIT_RETENTION_IDEMPOTENCY_DAYS=90
+ORBIT_RETENTION_TASK_DAYS=365
+ORBIT_RETENTION_WORKFLOW_DAYS=365
+ORBIT_RETENTION_EVENT_DAYS=365
+ORBIT_RETENTION_DELIVERY_DAYS=90
+ORBIT_RETENTION_INBOX_DAYS=90
+ORBIT_RETENTION_AUDIT_DAYS=2555
+```
+
+窗口范围为 1–3650 天，幂等记录不得短于 90 天；所有节点应使用同一组默认值。数据库中已有策略后，环境变量不覆盖它。管理端的“启用归档”只是允许归档执行器读取固定版本，不能绕过版本核对。
+
+归档分两步：先用“预览”或 `GET /console/retention/preview` 查看各类候选，再按固定类别调用 `POST /console/retention/export` 分批生成只读 JSON 快照。快照包含冻结的策略版本、数据库时间、截止时间、根记录及关联历史，并返回 SHA-256；源表仍然保留，导出成功只记录摘要和数量审计，不代表可以删除。后续删除执行器必须在独立发布和备份恢复验收后接入，不能把导出接口当成删除接口。
+
+候选筛选由服务端固定目录实现，浏览器不能提交表名或 SQL。终态任务必须没有未知效果、租约和流程所有权；流程必须终态且没有未结任务或未处理 Inbox；事件必须没有未确认交付或未处理 Inbox；交付只允许已确认记录；Inbox 只允许已处理且流程已终态记录；幂等记录需同时超过过期时间和窗口。审计单独使用审计窗口，普通清理不处理审计记录。未确认交付、未处理 Inbox、未知效果、进行中的任务/流程和有效幂等身份始终受保护。
+
+控制台接口示例：
+
+```sh
+# 已登录控制台会话；浏览器通常直接使用页面，不需要手工传令牌
+curl -b orbit-console.cookie http://127.0.0.1:8080/console/retention
+curl -b orbit-console.cookie -X PUT http://127.0.0.1:8080/console/retention \
+  -H 'Content-Type: application/json' -H 'Idempotency-Key: retention-2026-q3' \
+  --data '{"expected_revision":"0","enabled":false,"idempotency_days":90,"task_history_days":365,"workflow_history_days":365,"event_log_days":365,"delivery_history_days":90,"inbox_history_days":90,"audit_log_days":2555,"reason":"初始生产保留评审"}'
+```
+
+## 只读盘点
 
 `orbit-admin retention inventory` 用于在制定保留窗口、归档和备份恢复方案前盘点历史数据。它只执行带截止时间的统计查询，不删除、搬迁、改写数据，也不会自动判断某条记录可以安全归档。