3.7 KiB
3.7 KiB
未完成项与阻塞原因
本文件取代已删除的根目录
HANDOFF.md。只保留未完成项与阻塞原因；已完成能力见README.md、docs/design.md、docs/deployment.md。门禁命令见docs/deployment.md§8.0。
阻塞（需要真实环境，当前无法验证）
- 真实 Stalwart 邮箱联调：未运行任何真实邮箱端到端集成。JMAP 客户端代码与配置校验已完成并通过本地
cargo test，但Email/changes、PushSubscription等路径没有用真实邮箱账号验证过。→ 阻塞原因：无可用 Stalwart 账号/凭据，禁止使用测试账号或伪造结果。 - 真实 Telegram Bot 联调：
/webhook/tg的签名校验、getUpdates迁移、setWebhook注册、sendMessage出站均未在真实 Bot 上验证。→ 阻塞原因：无 Bot Token，禁止向真实用户发消息。 - 真实 Redis TLS 连接：
REDIS_URL使用rediss://的 TLS 握手、密码特殊字符 URL 编码、CONFIG_ENCRYPTION_KEY热更新均未实测。→ 阻塞原因：无 Upstash/托管 Redis 实例。 Email/changes的newState语义（design.md §10.5.1 应修-1）：客户端已用「同sinceState翻倍maxChanges扩窗」消除按页漏批，但newState是否表示"全部待报变更之后"仍需真实 Stalwart 复验，否则停机积压边界无法判定。→ 阻塞原因：无可用 Stalwart 账号/凭据。- Push callback 公网映射：
push:registration注册锁（360s）与 callback 映射（7d）TTL 依赖真实 Stalwart 的回调时序。→ 阻塞原因：无真实推送回调可观察。
代码缺口（已定位，待实现）
- Redis 错误映射：
read_batch与retry_or_dlq在 Redis 出错时仍可能返回Ok(())，消费循环不会因单次失败退出，这类故障只能靠 Redis 侧告警发现（可选改进）。 - 多实例重复投递窗口（残余）：XAUTOCLAIM 空闲阈值已按批大小缩放（批大小 × 单条上限 300s）；仅当单条事件处理耗时接近 300s 上限时，多实例部署下另一实例仍可能提前认领（仅重复不丢），单实例不受影响。
- Worker safelist 与注册流程不一致：
POST /api/push/register不在cloudflare-worker/src/backends.js的SAFE_ROUTES中，Worker 对其返回 404；docs/deployment.md§10.4 已修正为直连后端实例。→ 待决策：加入 safelist，或保持直连后端。
未排期（阶段 5「搜索 + 搜索片段 + 打磨」）
/search+SearchSnippet/get高亮。- 错误消息打磨、速率/退避实测、
clippy/fmt、README 复核。
监控验收（Q-DEP-B）
- 容器不写日志文件、只走 stdout，已由
docker/docker-compose.yml检查项覆盖。 - 业务事件、计数、时间戳、脱敏摘要的结构化日志已由代码审查确认。
- 未验证项：真实平台的日志采集器是否落盘、是否可检索。→ 阻塞原因：Q-DEP-B 明确允许延后到真实部署验收。
本轮已收口（2026-09-26）
- 错误 envelope 统一：全部公开路由错误响应（含
GET /ready不就绪时的 503）统一为{"error":<code>,"request_id":<id>}，可重试的 503 追加Retry-After: 30；/ready就绪时200仍返回结构化诊断报告。Uptime Kuma 按 HTTP 状态码（/ready期望 200）监控，不受响应体变化影响。 - Web SPA i18n：按浏览器语言判断
zh/en，默认英文，保持纯静态 SPA（data-i18n属性 + 内联消息字典，无新增资源文件）。 - 文档：
README.md改英文默认，新增README.zh-CN.md，两版章节与关键事实 1:1 对齐；docs/design.md、docs/deployment.md、AGENTS.md同步修正滞后描述。