docs(chat): add batch-three and engine-hygiene briefs plus manual walkthrough

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LVapmh2oGNyr6ECHKjPJY8

TASK-engine-runtime-hygiene-20260901.md

@@ -0,0 +1,50 @@
+# 任务书 · Python 引擎运行时治理（2026-09-01）
+
+基线：`origin/staging` 最新。本轮**不碰 `frontend/src/app/page.tsx`**，可与拆页第三批并行。改动面：`deploy/`、`scripts/`、`tests/`、`AGENTS.md`、`docs/`。
+
+## 为什么要做（事故实证）
+
+1. **api 容器没有任何持久卷。** `deploy/docker-compose.server.yml` 里只有 caddy 挂了卷（`caddy_data` / `caddy_config`），api 服务一个卷都没有。而 `scripts/jyotish_api_server.py` 的异步任务态默认落 `scratch/local/async_jobs`（file 后端，`JYOTISH_ASYNC_JOB_BACKEND` 可选 sqlite，同样在 `scratch/local/async_jobs.sqlite3`），chart 缓存落 `scratch/local/api_chart_cache`。**每次部署/重启，进行中的异步任务状态直接蒸发**；chart 缓存全冷（可接受，但同因同治）。
+2. **`scripts/jyotish_api_server.py` 已 11,035 行**，单文件承载全部端点。三轮前端治理的经验：巨石只会继续膨胀，除非有测试锁住。
+3. **重计算端点没有并发上限。** ThreadingHTTPServer 每请求一线程，2 vCPU 生产机上多个校正扫描/高严谨排盘并发时互相挤压，最坏拖垮健康检查。
+
+## 决策记录（产品授权，2026-09-01）
+
+1. api 服务加命名卷持久化 `scratch/local`（任务 1）。这是 `deploy/` 拓扑变更，`deploy/README.md` 是运维真相源，必须同步更新。
+2. `jyotish_api_server.py` **冻结增长**：新端点/新功能必须落独立模块由主文件薄注册，锁文件行数的合同测试入 quick gate（任务 2）。
+3. 重计算端点加有界并发（任务 3）。饱和时快速失败（429 + Retry-After）优于排长队——前端各调用方已有错误/重试路径。
+4. **迁移 squash 本轮明确不做**：需要 staging/production 双环境维护窗口与备份演练配合，收益（新环境重放耗时）目前不痛。延后条件：出现新环境搭建需求或迁移重放实际出错时再立项。
+
+## 硬红线
+
+1. 不改 `.gitea/workflows/**`。deploy 脚本（`run-staging-deploy.sh` 等）如需感知新卷，改动最小化并在 PROGRESS 说明。
+2. 生产 compose（`docker-compose.server.yml` 为 staging/production 共用基座）改动必须向后兼容：卷不存在时首次创建、已有容器内数据无需迁移（本来就是易失的）。
+3. 并发上限必须可配置（环境变量，含默认值），默认值保守（建议 2，与 vCPU 对齐）；健康检查端点绝不能被并发闸门挡住。
+4. Python 测试：`tests/test_api_server_security.py` 等既有套件不得回归；新增锁测试入 `CORE_PYTEST_TARGETS`。行数锁的基线取现值上浮小余量（建议 +300 行，容 bugfix），注释写明"新功能请开模块"。
+5. 前端不动；`npm test` 基线照常逐条比对。tsc 不适用本轮 Python 侧，但若碰 `frontend/` 则照旧全套。
+6. 不在脏工作树切分支；不自行提升 main。
+
+让步顺序：生产不中断 > 数据不损坏 > 功能与测试不回归 > 代码整洁。
+
+## 任务分解
+
+### 任务 1（P0）· api 持久卷
+
+- `docker-compose.server.yml` 的 api 服务加命名卷挂到容器内 `scratch/local` 的实际路径（先读 `deploy/railway-api.Dockerfile` 确认工作目录，不要猜）。
+- `deploy/README.md` 架构段与备份说明同步；staging 备份脚本是否需要覆盖该卷，评估后写结论（chart 缓存不值得备份；异步任务态短生命周期，说明白即可）。
+- 验收：staging 部署后 `docker volume ls` 见新卷；重启 api 容器后 `scratch/local` 内容存活；`/api/health` 正常。
+
+### 任务 2（P1）· 冻结巨石
+
+- `AGENTS.md`（根目录）加规矩：`scripts/jyotish_api_server.py` 只减不增，新端点开模块注册。
+- 新合同测试锁行数上限（红线 4），入 quick gate。
+
+### 任务 3（P1）· 重计算并发闸
+
+- 盘点主文件里最重的计算端点（校正扫描、高严谨排盘类；按实际 handler 认定，PROGRESS 列清单），加共享有界信号量：获取失败立即 429 + `Retry-After`。
+- 健康检查与轻量端点不经过闸门。
+- 测试：并发占满时第 N+1 个请求得到 429；释放后恢复。
+
+## 总验收
+
+quick gate 全绿（含新锁测试）；staging 部署实测任务 1 的三条；PROGRESS 附并发闸端点清单与压测/并发测试输出；`deploy/README.md` 更新可读。

TASK-home-split-batch3-20260901.md

@@ -0,0 +1,25 @@
+# 任务书 · 拆分首页巨石组件·第三批：onboarding/profile 与校正胶水（2026-09-01）
+
+基线：`origin/staging` 最新（不早于 `551d6317`）。第一、二批（`54269fcf`、`551d6317`）的全部红线与样板原样适用，本任务书只写增量。与其它改 `page.tsx` 的轮次不得并行——**注意 staging 上有另一条工作流在推报告/语气类改动，开工前 `git log origin/staging` 确认没有未验收的 page.tsx 改动，有就停下登记 `BLOCKED.md`。**
+
+## 范围（行号基于 `551d6317`，按符号定位）
+
+沿用第二批验收确认的模式：**hook 内部 0 个 useState/useRef/useEffect，一切经显式参数传入/返回**。这个模式已两轮公证（hook 顺序风险为零），不要回退到"独占 state 下移"。
+
+### 任务 1 · profile/onboarding/账户簇 → `hooks/use-profile-onboarding.ts`
+
+`refreshAccount`（1307）到 `signOut`（1569–1582）共约 275 行：`openAccountDialog` / `closeAccountDialog` / `persistAvatar` / `persistProfile` / `assessSavedBirthTime` / `saveProfile` / `saveOnboardingName` / `saveOnboardingBirth` / `editDeclaredBirthTimeDetails` / `saveOnboardingPlace` / `completeGuidedBirthTime` / `retryBirthTimeAssessment` / `signOut`。
+
+### 任务 2 · 校正胶水簇 → `hooks/use-rectification-surface.ts`
+
+`refreshRectificationEntrySummary`（1634）到 `handleRectificationMessagesChange`（1813–1821）共约 190 行。与 `use-consultation-run` / `use-session-management` 的依赖方向必须单一（经 Home 传递，不互相 import）。
+
+### 任务 3 · 读取面与度量
+
+`tests/home-surface.ts` 与 Python `_home_surface()` 扩容；受影响测试"断言不变、只换读取面"，逐条登记。度量表同前两批口径。**目标：`page.tsx` ≤ 2,000 行**（2,445 − 约 465），不达标写明原因。
+
+starter 入口三函数（1583–1633）、合盘起草（1822 起）、composer 小函数（1899 起）**本批不动**——剩的都是小而散的胶水，拆到这里收益已尽，第三批是收官批。
+
+## 验收
+
+同前两批：tsc、测试基线（开工时实测 `origin/staging`，fail=0/skipped=0 于 Docker 环境，无 Docker 逐条比对既有缺口）、`/` 保持 `○ Static`、首屏 gzip ±2%、纯搬家 md5 抽样自证写进 PROGRESS（至少 4 个函数）、quick gate 4 个前端契约 Python 文件保持全绿。

docs/testing/staging-manual-walkthrough-20260901.md

@@ -0,0 +1,58 @@
+# Staging 人肉实测清单（2026-09-01 四轮改造验收）
+
+给产品负责人：以下每条 2–5 分钟，全部在浏览器完成，不需要任何工具。测之前先做第 0 条。任何一条不符合预期，把**条目编号 + 你看到的现象**发给 Claude 即可。
+
+## 0. 确认测的是新版本
+
+浏览器打开 `https://staging.jyotisha.chat/api/health`，页面是一段 JSON。找到 `deployment` 里的 `gitCommit`，前 8 位应当等于当前 staging 最新提交（发版后 Claude 会告诉你期望值）。不一致 = 部署没落地，先别测。
+
+## 1. 双标签页不丢消息（P0 · 消息服务端权威化）
+
+1. 登录后打开同一个对话，复制地址栏 URL，在**第二个标签页**打开同一地址。
+2. 标签页 A 问一个问题，等回答完；标签页 B 再问一个，等回答完。
+3. 两个标签页**分别刷新**。
+- ✅ 预期：两边都看到全部 4 条消息（两问两答），顺序正确，无缺失。
+- ❌ 改造前：后发的会把先发的覆盖掉。
+
+## 2. 刷新回到原对话（P1 · 会话 URL）
+
+1. 打开任一历史对话，注意地址栏出现 `?c=...`。
+2. 按 F5 刷新。
+- ✅ 预期：还在这个对话，消息完整。
+
+## 3. 深链与后退键（P1）
+
+1. 复制某对话的完整地址（含 `?c=`），开新标签页粘贴打开——应直达该对话。
+2. 依次点开对话 A → B → C，然后按浏览器**后退**两次、**前进**一次。
+- ✅ 预期：后退回 B、再回 A，前进回 B；全程页面不整页刷新。
+3. 按后退直到 `?c=` 消失（回默认对话）。
+- ✅ 预期：输入框里的草稿被清空（和你主动点侧栏一个行为）。
+
+## 4. 退出登录后回跳（P1 · 401 回跳）
+
+1. 开着某个对话（地址栏有 `?c=`），在**另一个标签页**打开同站并退出登录。
+2. 回到第一个标签页，发一个问题——会被踢到登录页。
+3. 重新登录。
+- ✅ 预期：落回刚才那个对话，而不是默认首页。
+
+## 5. 断网保存星盘不再假成功（P2a · 云端唯一真相）
+
+1. 打开账户里的星盘库面板，点添加其他人的星盘，填好资料。
+2. **关掉 Wi-Fi/断网**，点保存。
+- ✅ 预期：明确提示「保存失败，请重试」，**表单内容还在**；绝不出现"已保存到本地"字样。
+3. 恢复网络，再点保存——成功。刷新页面，列表里就这一条，没有重复或消失。
+
+## 6. 置顶/归档跨设备（P2a）
+
+1. 在电脑上把某对话置顶、把另一条归档。
+2. 用手机（或另一个浏览器）登录同一账号。
+- ✅ 预期：置顶和归档状态一致。改造前这些状态只存在本机。
+
+## 7. 长会话与整体手感（回归抽查）
+
+- 找一条消息很多的老对话点开：侧栏应立即出现，消息稍后加载（有加载态），不卡整页。
+- 星盘库增删改、发起合盘、点每日星语、进出生时校正：应与改造前一致——这四块代码整体搬过家，重点看有没有点了没反应或样式塌掉。
+
+---
+
+四轮改造：BUG-464（消息权威化）、BUG-465（会话 URL）、BUG-466（云端唯一真相）、拆页两批。自动化侧每轮均已验收（tsc / 2400+ 条测试 / 构建 / SQL 幂等），此清单覆盖的是自动化够不着的真浏览器行为。