docs(tasks): brief for #240 reading-timeout

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DbBXozsiu43ob7B8UZCmDM
2026-11-13 09:59:38 +08:00
1 changed files with 40 additions and 0 deletions
@@ -0,0 +1,40 @@
+# TASK：报告解读超时由 120 秒放宽，重试按剩余租期决定（2026-11-13）
+
+- Gitea：#240
+- 分支：`codex/reading-timeout-20261113`，基于 staging `3e6077f752b606fee69a9eb15853fe328801901b`
+- Bug 编号：BUG-1874
+- 验收：Claude（jyotisha-e6）
+
+不得自行写「产品决定/裁定」；任务书没写的取舍一律选需拍板。不得修改或删除既有断言来让测试通过；确需修改的，在 PROGRESS 里写明原值、新值、原因。
+
+## 现象（验收主机实测，2026-11-13）
+
+- 生产模型 `deepseek-flash` 用现行提示（#219 之后）写一份个人报告解读，实测两次分别用了 **126 秒和 141 秒**。
+- `REPORT_READING_TIMEOUT_MS = 120_000`（`frontend/src/lib/personal-report-reading.ts`），所以按生产配置跑，两张公开盘各两次尝试**全部超时**（#220 验收工具 `model_timeout`）。
+- 报告解读是可选项。超时之后报告照常生成，但用户看不到解读。
+- worker 租期是 `leaseSeconds: 600`（`personal-report-worker.ts`）。
+
+## 要做的
+
+1. 单次解读超时改为 240 秒。
+2. 解读最多写两次（`writeReportReading` 已有这个上限）。第二次之前先看剩余时间：从 worker 开始算起，剩下的不到「240 秒 + 60 秒安全余量」，就不再重试，直接按现在的「无解读」流程收尾，并记下原因 `reading_retry_skipped_deadline`。
+   - 剩余时间要从现有的租期或开始时间推算，在 PROGRESS 写明用的是哪个量。
+   - 不得延长租期。
+3. 超时和跳过重试都要在现有日志里留一行，只记耗时和原因，不记正文。
+4. #220 的验收工具 `tools/report-reading-acceptance/run.mts` 使用同一个常量，不另设超时。
+
+## 验收
+
+1. 单元测试：
+   - 用假写作器，第一次耗时 200 秒（用假时钟模拟，不真等）→ 不超时；
+   - 第一次耗时 250 秒 → 超时；
+   - 剩余时间不足时 → 不重试，原因写对。
+2. 原有测试全部通过；tsc 无错误，eslint 0 个错误，Python 快速门通过。
+3. 验收时我会在验收主机用 `deepseek-flash` 对两张公开盘各跑一次。
+
+## 不要碰
+
+- 提示内容
+- 复查规则
+- 租期
+- 冻结文件