docs: brief for #285 synastry per-layer birth precision (BUG-1894)

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

docs/tasks/TASK-synastry-layer-precision-20261115.md

@@ -0,0 +1,119 @@
+# TASK：合盘出生时间误差改为按候选时间逐层核对（2026-11-15）
+
+- Gitea：#285
+- 分支：`codex/synastry-layer-precision-20261115`，从 staging 的本任务书提交切出（基于 `f914571e`，已含 #280）。
+- Bug 编号：BUG-1894。开工时核对 `docs/BUG_HISTORY.md` 末尾；已被占用就顺延，并在 PROGRESS 写明。
+- 负责验收：Claude（jyotisha-8a）。
+- 同时在做：
+  - #281（合盘第 3 批，BUG-1892）：改 `synastry-full-sections.ts` 的结构和提示词、`synastry-full-technical.ts` 的「技法执行情况」分组。
+  - #283（Raman 勾选，BUG-1893）：改「传统配对参考」和发起链路。
+  - #279（生时纠正，BUG-1890）。
+  - 本单只改误差扫描、标记和误差相关的展示。各改各的函数，后合入的负责 rebase。
+
+任务书没写到的取舍，不得写成"产品决定"或"裁定"，一律标「需拍板」。不得修改或删除既有断言来让测试通过。确需修改的，在 PROGRESS 逐条写明原值、新值和原因。
+
+## 背景
+
+- 占星师 2026-11-15 合盘裁定 Q6：
+  - 只把变化一侧依赖它的层，以及用到这一侧的两盘结论标出，另一人不受影响。
+  - DK、UL、宫位、大运等逐项计算敏感性，不因为时间不稳就机械认定每项都变。
+  - 候选分支已经算出、能展示差异的，用 `parameter_sensitive`；缺输入、分支没算或关键依赖没有结果的，用 `blocked` 并写具体原因。
+  - 不能只改标签却仍用单点结果写唯一结论。
+- 产品负责人 2026-11-15：按候选时间逐层算出、并列给用户看，不替用户选，不算「在报告里分支」。
+- 默认前后 30 分钟的写法已由 #280 统一（契约 M 节），本单沿用 `report-window-copy.ts` 和 `birth_window_disclosure`，不另写一套。
+- 现状（#276）：
+  - `scripts/marriage_match_service/birth_precision.py` 只扫 D1 上升、D9 上升、月亮星宿和 pada 三项。
+  - 某项会变时，按固定表 `LAYERS` / `MODULES` 把一整批层机械地标成参数敏感（例如 D1 上升会变，就把 UL、A7、AL、宫主、Narayana 全标上）。这些层在候选时间下是否真的变了，并没有算。
+  - Ashtakoota 只标 Tara、Yoni、Gana、Nadi。月亮跨星座时 Varna、Vashya、Graha Maitri、Bhakoot 也会变，现在没标。
+
+## 要做的
+
+### 1. 候选分支
+
+- 沿用现在的三项扫描，找出每人会变的轴和候选值。每个候选值记录一个代表时刻：取窗口内第一次出现该值的时刻，再往里推 1 分钟，不越出窗口。
+- 对每个代表时刻，用和档案时刻同一条原生路径（`build_synastry_full_dossier` 用的 `read`）算一份这个人的读盘。另一人不重算。
+- 上限：每人最多 4 个额外分支。超出时：
+  - 按离档案时刻由近到远取前 4 个；
+  - 其余候选在附录照实写「候选太多，未逐个计算」，它们影响的层标 `blocked` 并写这个原因。
+- 分支并行计算，结果进合盘缓存（缓存键已含两人的窗口），`CACHE_SCHEMA` 加一，照现有格式写原值、新值、原因。在 PROGRESS 记录公开名人盘的耗时：改前、改后。
+- 分支的读盘只用来对比，不替换档案时刻的读盘，不进她的 builder。她的 builder 输出不改。
+
+### 2. 逐层对比
+
+每个分支用现有函数取出同样的值，与档案时刻逐项比较：
+- D1 侧（`relationship_structure`、`relationship_promise` 已有的字段）：
+  - 上升星座；
+  - 第 1、5、7、8、12 宫的宫主及其落宫；
+  - 金星、木星、火星、月亮的落宫；
+  - UL 及 UL 第二宫、A7、AL 的星座；
+  - DK；
+  - Narayana 起始星座和当前大运。
+- D9 侧：D9 上升、D9 第 7 宫主及其落宫、DK 在 D9 的位置。
+- 月亮侧：
+  - 月亮星宿和 pada、月亮星座；
+  - Vimshottari 出生时大运余额，以及今天所在的大运和小运；
+  - Ashtakoota 全部 8 项（重算两人配对，用现有 `build_marriage_match_dossier`，不新写）。
+- 两盘互落：`pair_interaction_evidence` 里受影响一侧作为落点的宫位。
+
+每一项的结果是下面三种之一：
+- `unchanged`：各分支都和档案时刻相同。不标敏感。用户可见文字用 `unchangedWithinBirthWindow(source)` 的写法。
+- `varies`：至少一个分支不同。标 `parameter_sensitive`，记录每个分支的值。
+- `blocked`：分支没算出来，或这项在分支里取不到。写具体原因。
+
+把 `LAYERS`、`MODULES` 这类按轴整批标记的做法换成按上面的结果逐项标记。回执里某一行的标记，只看它依赖的那些项里有没有 `varies` 或 `blocked`；两项都有时取 `blocked`。依赖关系写成一张表放在代码里，并抄进 PROGRESS。
+
+### 3. 两盘结论
+
+- 两盘对照任务（`pair_execution_tasks`）、`pair_promise_links`、互落：只有用到的那一侧的项确实 `varies` 时才标；`blocked` 同理。
+- 另一人的项不标。
+- 已有的 `parameter_sensitive` 行保留，不能因为逐层没变就改成 executed。
+
+### 4. 展示
+
+- 附录「计算参数」每人一段：
+  - 误差来源一行，用 `birth_window_disclosure`；
+  - 一张表「项目 / 档案时刻 / 候选（偏早或偏晚多少分钟）」，只列 `varies` 和 `blocked` 的项；
+  - `unchanged` 的项合成一句，例如「上升、UL、A7 等 9 项按前后 30 分钟试算，没有变化」。
+- 表格复用 `annual-table` 样式。用户可见文字没有字段名、下划线或「·」。
+- 技法表「计算」一栏照逐项结果标；理由写「出生时间误差内会变」或 `blocked` 的具体原因。
+- 写作输入：每节那一句改成列出这一节用到、并且 `varies` 的项及其候选值。提示词写明：
+  - 这些项要写成条件，把候选都说出来，不替用户选；
+  - 不能写成没有算出；
+  - `unchanged` 的项不能写成「稳定」，按 M 节的写法。
+- Ashtakoota 附录：月亮会变时，列出确实会变的那几项和各分支的结果，替换现在固定的四项。
+
+### 5. 不改的
+
+- 冻结文件、她的 `skills/**`、`references/**`、`consult-preset-prompts.ts` 不碰。
+- 窗口怎么取不改（#224、#279）；`personal-report-longform-birth.ts` 不碰。
+- 不改四类事件、事件扫描、写作章节结构（#281）、Raman（#283）。
+- 不调用 DeepSeek。
+
+## 测试
+
+- `tests/test_synastry_layer_precision_20261115.py`、`frontend/tests/synastry-layer-precision-20261115.test.tsx`。合成数据和桩读盘覆盖：
+  - 上升会变但 UL 在两个分支相同：UL 不标；
+  - 上升会变且 A7 不同：A7 标 `parameter_sensitive`，附录有两个值；
+  - 分支读盘失败：相关项标 `blocked` 并写原因；
+  - 候选超过 4 个：多出的写「候选太多，未逐个计算」；
+  - 月亮跨星座：Bhakoot 或 Graha Maitri 的变化被标出；
+  - 只有甲方会变：乙方各项和只用乙方的两盘对照不标；
+  - 两人都没变：附录只有「没有变化」一句，写法符合 M 节；
+  - 写作输入列出候选值，没有「没有算出」「稳定」；
+  - 旧快照（#276 格式）照常显示；
+  - 用户可见文字没有「·」、字段名或下划线。
+- 公开名人盘一对实算：在 PROGRESS 贴每人 `varies`、`unchanged`、`blocked` 的项目清单和耗时。
+
+## 要改的文件
+
+- `scripts/marriage_match_service/birth_precision.py`、`full_dossier.py`（只限调用处）、`api.py`（缓存版本）、`scripts/consult_full_data_cache.py`（版本号）。
+- `frontend/src/lib/synastry-full-technical.ts`（只限误差相关函数和 Ashtakoota 误差说明）、`synastry-full-sections.ts`（只限 `precisionEvidence` 和误差那一条提示词）、`synastry-report-view.tsx`（只限误差表）。
+- `docs/BUG_HISTORY.md`，只在末尾追加。
+- `docs/tasks/PROGRESS-synastry-layer-precision-20261115.md`。
+
+## 验收标准
+
+1. 公开名人盘一对：附录每人只列确实变化或算不出的项，且有候选值；没有变化的项按 M 节写一句；技法表和两盘对照只标确实受影响的行。
+2. 合成测试覆盖上面每种情况。
+3. 耗时增加写进 PROGRESS。增加超过 30 秒时标「需拍板」，并给出降低的办法。
+4. tsc、eslint（0 错）、`npm test`（基线失败除外）、quick gate 全部通过。