docs(report): add sensitivity float-crash task brief — consultation_workflow 500s
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016P5RoqzmUQEbeC2qjAkeGr
This commit is contained in:
Jesse_Chen
@@ -0,0 +1,77 @@
|
||||
# 任务书 · consultation_workflow 全量 500（出生时间敏感度 float 崩溃）（2026-09-04）
|
||||
|
||||
基线：`origin/staging` @ `285c5722`（开工时 `git fetch` 后以 `origin/staging` HEAD 为准）。
|
||||
|
||||
## 事故实证
|
||||
|
||||
- 2026-09-04 07:38 UTC，staging 真实 personal_full（requestId `85616e32-5a5d-4ed8-b75b-7778dabff4ad`，5 主题含新默认 `health`）**failed，failureCode = `calculation_unavailable`**。
|
||||
- 委托方已在最新 `origin/staging`（`285c5722`，与部署 `45bdb63e` 同源）本地完整复现：本地起引擎后按报告 worker 的真实输入（5 主题 + `birth_time_accuracy: "provisional"` + `representative_time`）调 `/api/consultation_workflow`，**5/5 全部 HTTP 500** → 前端 `ConsultationWorkflowError` → worker 抛 `calculation_unavailable` → job 3 次尝试全败。
|
||||
- 引擎 traceback（每次请求相同）：
|
||||
|
||||
```
|
||||
File "scripts/jyotish_api_server.py", line 2160, in execute_consultation_workflow
|
||||
birth_time_sensitivity = _load_local_module('jyotish_engine')._build_birth_time_sensitivity(sensitivity_args)
|
||||
File "scripts/jyotish_engine.py", line 2170, in _build_birth_time_sensitivity
|
||||
center = _birth_datetime_from_args(args)
|
||||
File "scripts/jyotish_engine.py", line 9752, in _birth_datetime_from_args
|
||||
return datetime(args.year, args.month, args.day, args.hour, args.minute, _arg_second(args))
|
||||
TypeError: 'float' object cannot be interpreted as an integer
|
||||
```
|
||||
|
||||
## 根因（已定位并本地验证修复）
|
||||
|
||||
1. `_high_rigor_birth_payload`（`jyotish_api_server.py:4726`）历来把 `hour` / `minute` 解析为 **float**（`_get_float`，API 路径的历史口径，下游算小数时角没问题）。
|
||||
2. 上游同步 `a7041529`（09-04 02:11 合入）在 `execute_consultation_workflow` 里**无条件**执行 `_build_birth_time_sensitivity(sensitivity_args)`（:2158-2160，不管请求带不带敏感度字段），其中 `_birth_datetime_from_args`（`jyotish_engine.py:9752`）拿 float 的 `hour`/`minute` 直接构造 `datetime()` → `TypeError`。CLI/argparse 路径的 hour/minute 是 int，所以上游在 CLI 侧自测不炸；API 路径必炸。
|
||||
3. 异常只被 `except ValueError` 包住，`TypeError` 直接冒成 500。
|
||||
4. **影响面是全量**：`/api/consultation_workflow` 的**每一个**调用都 500——不只报告，聊天的深度咨询工具链同样走这个端点。部署 `45bdb63e`（含 `a7041529`）起，该端点在 staging 上完全不可用。
|
||||
5. 委托方已本地验证一行修复：`_birth_datetime_from_args` 改为 `datetime(int(args.year), int(args.month), int(args.day), int(args.hour), int(args.minute), _arg_second(args))` 后重跑同一复现，**5/5 主题成功**，bundle 产出 5 张 claim card（`health` 归一为 `health_pressure`）、blockedSections 为空。
|
||||
|
||||
## 与其他在途工作的关系
|
||||
|
||||
- `docs/tasks/TASK-upstream-sync-fix-20260903.md` 的修复在用户侧工作树完成但**未提交**，其十主题 HTTP smoke 是在基线 `779717f4`（早于 `a7041529`）跑的，当时引擎还没有本崩溃——两单不矛盾，本单是独立 P0，可先行合入；执行方若同时持有两个工作树，注意 rebase 顺序即可。
|
||||
- 报告链路前三轮修复（varga 形状 / Transit / karakas / writer 预算与隔离）均已验收，本崩溃与它们无关，是上游同步引入的回归。
|
||||
|
||||
## 硬红线
|
||||
|
||||
1. 修复必须在 `_birth_datetime_from_args` 或 `sensitivity_args` 构造处做**类型规范化**，不得把 `_high_rigor_birth_payload` 的 float 口径改成 int——那是聊天/排盘路径的既有合同，动它影响面不可控。
|
||||
2. `_build_birth_time_sensitivity` 是辅助证据层：除类型修复外，将 :2158-2160 的异常处理加固为**降级不崩全局**——构建失败时把 `birth_time_sensitivity` 置为 blocked/not_available 状态对象并继续 workflow（`BadRequest` 语义保留给真正的输入非法）。敏感度层的失败不允许再打死整个端点。
|
||||
3. 必须加回归测试：float `hour`/`minute` 的 API body 走 `execute_consultation_workflow` 不 500，且 `birth_time_sensitivity` 输出正确；测试用虚构 smoke 出生数据。
|
||||
4. 不改 `.gitea/workflows/**`；不提升 main；前端不需要改动（`calculation_unavailable` 的 worker 语义是对的）。
|
||||
5. Python 测试用 `.venv` 真实跑过；`python3 scripts/run_quality_gate.py` 按仓内现行门跑。
|
||||
|
||||
## 开工前置
|
||||
|
||||
```bash
|
||||
git fetch origin --prune
|
||||
git worktree add -b codex/report-sensitivity-crash-20260904 \
|
||||
../.worktrees/report-sensitivity-crash-20260904 origin/staging
|
||||
```
|
||||
|
||||
读 `docs/BUG_HISTORY.md`（本单与上游同步 `a7041529` / `c2f23131` 直接相关）。
|
||||
|
||||
## 复现与验收（同一方法）
|
||||
|
||||
本地起引擎 `.venv/bin/python scripts/jyotish_api_server.py --port 5200`，用虚构出生数据（1993-06-15 10:30，lat 36.42 / lon 114.21 / tz 8）对 career / marriage / wealth / timing / health 各发一次 `/api/consultation_workflow`（body 含 `birth_time_accuracy: "provisional"`、`representative_time: "10:30"`）：
|
||||
|
||||
- 修复前：5/5 HTTP 500，traceback 同上（确认复现）。
|
||||
- 修复后：5/5 `success=true`；`birth_time_sensitivity` 字段存在且状态合法；喂给 `buildReportEvidenceBundleV2` 得 5 张 claim card、blockedSections 空。
|
||||
- 另发一次**不带**敏感度字段的请求（聊天路径形状），确认同样 200。
|
||||
|
||||
## 任务
|
||||
|
||||
1. **（P0）类型修复 + 降级加固 + 回归测试**（见硬红线 1–3）。
|
||||
2. **（P0）staging 部署后真实验证**：health SHA 对齐后，真实生成一份 standard personal_full（5 主题默认）——这同时是前几轮顺延至今的任务 4：四/五章有正文、telemetry 无 `length`、≥3 处 writer 输出回溯 bundle、每章实测 `inputTokens`/墙钟对照 `docs/tasks/PROGRESS-report-skill-parity-20260901.md` 的 2 倍线裁决。**取证要快**——容器 recreate 会带走日志窗口（09-02 已吃过一次亏）。
|
||||
3. **（P1）聊天路径回归确认**：staging 上发一次深度咨询，确认聊天侧 consultation 恢复正常。
|
||||
|
||||
## 收尾
|
||||
|
||||
- `PROGRESS-report-sensitivity-crash-20260904.md`（按仓内现行位置放 `docs/tasks/`）；`docs/BUG_HISTORY.md` 条目（编号对远端确认）。
|
||||
- 推送后核对 `https://staging.jyotisha.chat/api/health` 的 `.deployment.gitCommit`；流水线约 20 分钟。
|
||||
|
||||
## 交付物清单
|
||||
|
||||
1. 修复 diff（类型规范化 + 敏感度层降级）+ 回归测试
|
||||
2. 复现方法修复前后对照（5/5 500 → 5/5 success）
|
||||
3. 部署后真实报告：章节正文、telemetry、回溯抽查、实测 tokens/墙钟 2 倍线对照
|
||||
4. 聊天路径恢复确认
|
||||
5. BUG_HISTORY、PROGRESS、质量门实际输出
|
||||
Reference in New Issue
Block a user