docs(tasks): brief for #228 report-gender

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DbBXozsiu43ob7B8UZCmDM
2026-11-13 02:29:08 +08:00
1 changed files with 65 additions and 0 deletions
@@ -0,0 +1,65 @@
+# TASK：个人报告带上档案里的性别（2026-11-13）
+
+- Gitea：#228
+- 分支：`codex/report-gender-20261113`，基于 staging `65fab6ebdfd6bc5c22324c6857af562097a99d3e`
+- Bug 编号：开工时取 `docs/BUG_HISTORY.md` 末尾的下一个空号，并在 PROGRESS 里写明。
+- 验收：Claude（jyotisha-e6）
+
+不得自行写「产品决定/裁定」。任务书没写到的取舍，一律选「需拍板」。
+
+不得修改或删除既有断言来让测试通过。确需修改的，在 PROGRESS 里逐条写明原值、新值和原因。
+
+占星师的引擎和资料（`scripts/jyotish_engine.py`、`scripts/yoga_engine.py`、`references/` 下她仓库已有的文件、`SKILL.md`）一律不改。产品差异只能放进单独的产品文件，并在 `references/product_runtime_contract.md` 公告（项目规则 2026-11-07）。
+
+
+
+## 背景（产品负责人 2026-11-13）
+
+产品负责人问：用户档案里的出生地、性别，报告有没有用上。核对结果如下。
+
+- **出生地已用上。** `buildLongformBirthPayload` 传了经纬度、时区偏移和地名。
+- **性别没有用上。** 有三处断点：
+  1. `ACCOUNT_BIRTH_SELECT`（`frontend/src/lib/server-owned-birth-profile.ts`）不读 `gender`。
+  2. `buildLongformBirthPayload` 不传性别。
+  3. Python 端 `professional_report_reference._export_args` 也不转交。
+- 聊天的读取（`app/api/consult/route.ts`）是读性别的。
+- 引擎里会用到性别的地方：
+  - `jyotish_engine._yoga_birth_context` 把 `args.gender` 放进瑜伽上下文，`yoga_engine` 判断 Mahabhagya 等规则时要用。没有性别，这条判断只能记为条件未知。
+  - `jaimini.py` 的 `goel_gendered` profile 用 `chara_gender`。
+  - startrack 桥接的默认值是 `female`（`jyotish_engine.py:1978`）。
+
+## 要做的
+
+1. 报告读取档案时带上 `gender`：本人资料和档案两条读取路径都要。档案表里这一列的名字先核对清楚，写进 PROGRESS。
+2. 报告生成请求带上 `gender`，按 `frontend/src/lib/profile-gender.ts` 现有的规范值传。没有或未填，就不传，不得猜测。
+3. Python 端 `_export_args` 把它转交给 `args.gender`。startrack 桥接如果启用，改用这个值；没有值时，保持现有行为并在 PROGRESS 记明。`chara_gender` 只在所选 profile 用得到时才传，不改默认 profile。
+4. 报告事实包（`reading_facts.py`）加 `subject.gender`，取值为 `male`、`female` 或 `unknown`。另外盘点占星师资料里按性别区分的规则，例如婚恋的配偶指标星，列出文件和行号。只列，不新增解读规则；如果需要新增，选需拍板。
+5. 缓存键要包含性别，同一张盘、性别不同时不得命中同一份缓存。
+
+## 不要碰
+
+- `frontend/src/lib/personal-report-reading.ts`（#219 在改）
+- `references/**`
+- `evidence_grade.py`
+- 冻结文件
+- 聊天现有的性别处理
+
+## 验收标准
+
+1. 档案性别为女时，报告请求里有 `gender: "female"`，`args.gender == "female"`，瑜伽上下文含性别，事实包 `subject.gender == "female"`。
+2. 档案没有性别时，请求里不出现 `gender` 字段，事实包为 `unknown`，Mahabhagya 等规则仍记为条件未知，不得默认成某个性别。
+3. 用一张公开盘，分别按男、女生成，Mahabhagya 的判断按规则不同。在 PROGRESS 记录这张盘和两次的结果。
+4. 改动的旧测试写明原值、新值和原因，例如 `ACCOUNT_BIRTH_SELECT` 的字面值。
+
+## 自测命令
+
+```
+python3 -m pytest -q tests/test_reading_facts_v3_20261112.py tests/test_report_reading_facts.py
+python3 scripts/run_quality_gate.py --profile quick --skip-frontend-runtime
+cd frontend && npx tsx --test tests/server-owned-birth-profile.test.ts tests/personal-report-longform*.test.ts && npx tsc --noEmit -p . && npx eslint .
+```
+
+## 何时停下来选「需拍板」
+
+- 档案的性别字段有多种存法，无法统一。
+- 要让性别影响解读结论，必须新增规则。