Jyotisha/task_plan.md

# 印度占星 Web/App 产品化任务计划

目标：把当前印度占星网页/app推进到同品类成熟产品水平，持续对标开源项目与本地碎片，优先复用 MIT/Apache 代码或现有本地模块，避免重复造轮子。

## 当前阶段

- 状态：in_progress
- 阶段：用户端信任层与运行可用性
- 本轮最高优先级：在已完成首次使用引导、真实浏览器首跑冒烟、AI/API key 安全提示、导出失败恢复后，推进星历后端抽象可行性，把 SwissEph/WASM/xalen/VedAstro/PyJHora 的替换边界变成可检测资产。

## 执行原则

1. 每次实现前先扫描本地碎片、`references/open_source_sources/*`、现有测试与产品差距矩阵。
2. 网络可用时先查 GitHub/开源项目；许可证允许且架构贴合时优先复用。
3. 不直接复制 AGPL/GPL 代码；只作为行为基准或独立重写参考。
4. 每完成一个任务，立刻分析下一个最高优先级问题并继续执行。

## 已完成

- [x] 可见参数/日历/工作区面板。
- [x] HTML 报告导出基础版。
- [x] Panchanga range API、月历、CSV/ICS、Rahu Kala/Yamaganda/Gulika。
- [x] Choghadiya、Hora、Tithi/Nakshatra/Yoga end times。
- [x] 保存星盘工作区：保存、打开、删除、导出、ID 修复。
- [x] Synastry 保存伴侣、保存配对、重新打开/删除、JSON 导出、HTML 报告导出。

## 进行中

- [x] Panchanga richer vrata/festival candidate rules。
- [x] Panchanga search-by-condition 条件检索。
- [x] CSV/ICS/前端表格/月历同步暴露条件标签。
- [x] 构建与碎片审计。
- [x] 多人/家庭分组与更强案例过滤。
- [x] 关系报告模板与比较视图。

## 下一批优先级

- [x] 多人/家庭分组。
- [x] 关系报告模板。
- [x] bi-wheel/composite-style 比较视图。
- [x] `spouse_status_yoga.py` 关系深度折叠。
- [x] 关系报告打印/PDF polish。
- [x] 可编辑关系元数据。
- [x] 后端 PDF 管线。
- [x] 更深关系时机/UL/DK 折叠。
- [x] Panchanga 搜索增强：组合条件、节日说明、location-aware 日历默认值。
- [x] 专业报告后端 PDF 管线：复用 `report_builder.py` 生成后端 HTML/PDF artifact。
- [x] 计算设置选择器：ayanamsa/node/house/sunrise/geocoder policy。
- [x] 规则/技法检索目录与 API explorer。
- [x] 规则变体/流派结果口径：Yoga/Ashtakavarga/Shadbala API 返回 `rule_variants`，Skill workbench 渲染规则口径。
- [x] 候选碎片接入：`curse_yoga_detector.py` 已进入 `/api/yogas`，`shadbala_advanced.py` 已进入 `/api/shadbala` 增强证据层。
- [x] 候选碎片接入：`dasha_analyzer.py` 已进入 `/api/dasha.vimshottari_analysis` 与主 Dasha 详情卡。
- [x] 候选碎片归档：`reading_orchestrator.py`、`report_orchestrator.py`、`orchestrator_bridge.py` 已由 `/api/thematic_report`、registry 与前端 Skill workbench/API Explorer 引用，不再是漂浮碎片。
- [x] 候选碎片接入：`mevg_automation.py` 已进入 `/api/case_validation.mevg_gate`，只读门控状态，不运行子进程。
- [x] 候选碎片归档：`hermes_bridge.py` 判定为外部个人 agent/WorkBuddy 学习桥，写入 `~/.workbuddy`，不属于印度占星网页/app 默认产品面，已加入碎片审计忽略。
- [x] 主题报告真实证据链：`/api/thematic_report` 在传入出生数据或星盘数据时自动派生 chart/dasha/yogas/shadbala/ashtakavarga/relationship/career/Jaimini 证据，前端显示 evidence source 与模块状态，不再把样例报告伪装成实算报告。
- [x] 方法文档与 API 示例：Technique Directory/API Explorer 已返回并展示可复制 cURL、最小 OpenAPI 片段、方法摘要、边界说明和 API doc key。
- [x] PWA/信任中心 MVP：manifest、service worker、installability 状态、Trust Center 本地数据说明、导出本地资料、二次确认清空本地资料。
- [x] 术语模式与星历底座记录：Calculation Settings/Trust Center 支持 balanced/beginner/professional，tooltip、provenance、JSON/HTML 导出记录术语模式和 ephemerisBackend，xalen-ephemeris 作为 Apache-2.0 可行性记录。
- [x] 桌面/普通用户运行健康检查入口：Trust Center 接入 `/api/health`、`/api/capability_audit`、PWA 状态和桌面路线提示，普通用户可直接检查本地 API 与能力目录是否可用。
- [x] 剩余同品类产品 polish：首次使用引导与普通用户空状态路径已提供运行健康检查、示例盘填入、导入聚焦和本地星盘库空状态指引，降低首次运行/无星盘/无 API 时的卡点。
- [x] 浏览器首跑守门：已用真实 Chrome 检查首屏首次使用路径、移动端布局、示例盘生成、运行健康检查入口，并修复 API 字段缺失导致的 Banner `undefined`。
- [x] AI/API key 安全提示：AI 聊天不再提示浏览器 localStorage endpoint 配置；改为提示通过服务端 `/api/chat` 或后端代理读取服务端 `OPENAI_API_KEY`。
- [x] 导出失败恢复：PDF fallback 和导出异常会提示 HTML 降级、Trust Center 健康检查和本地 API 启动命令。
- [x] Ephemeris abstraction feasibility：新增 `scripts/ephemeris_backend_probe.py` 和研究记录，明确 `swisseph_python` 主路径、`swisseph_wasm` fallback、`xalen_ephemeris` spike、`vedastro` product/API benchmark、`pyjhora_benchmark` AGPL benchmark-only。
- [x] Ephemeris adapter contract：新增 `scripts/ephemeris_adapter_contract.py` 与 parity matrix 文档，固定 Sun/Moon/Asc/Rahu/Ketu 的 `longitude_delta_arcsec` 验收口径。
- [x] Runtime smoke 补强：`tests/run_frontend_runtime_smoke.py` 现在真实检查 `/api/report_artifact` HTML fallback 和 `AI_BROWSER_KEY_DISABLED` 前端密钥禁用策略。
- [x] Ephemeris candidate adapter spike：新增 `scripts/ephemeris_candidate_adapter_spike.py` 与研究文档，记录 `swisseph_wasm_candidate`、`xalen_ephemeris_candidate` 的 license gate、parity gate 和 runtime setting 暂不开放。
- [x] 登录/订阅/API 失败恢复提示：`auth.js` 安全解析非 JSON 响应，登录/注册/Apple/token 校验失败会提示 Trust Center、`npm run web`、`python3 scripts/jyotish_api_server.py`；`subscription.js` 用可关闭通知替代关键 IAP alert，并转义错误消息。
- [x] 主排盘/关系/问事/Transit/API bridge/AI chat 失败恢复提示：安全解析非 JSON 响应，普通用户可见 Trust Center、`npm run web`、`python3 scripts/jyotish_api_server.py` 恢复路径，不再只弹 alert 或显示裸错误。
- [x] 真实浏览器点击级 smoke：新增 `tests/run_frontend_click_smoke.py`，覆盖示例盘生成、AI chat、HTML 导出、Transit、合盘、问事；修复 HTML 导出链路中的 `sub_lord` ReferenceError。
- [x] 移动端/离线/PWA 点击守门：`tests/run_frontend_click_smoke.py --mode all` 覆盖在线桌面、移动首屏、manifest/serviceWorker、无 API 健康检查和排盘 fallback，并纳入 `scripts/run_quality_gate.py` 默认质量门。
- [x] 桌面应用/安装后首次打开路线：`scripts/desktop_packaging_preflight.py` 输出 PWA installed shell、Pake first launch、Tauri sidecar readiness 三类 first-launch checks；README 与 desktop packaging spike 同步可执行命令。
- [x] Pake/Tauri 本机可用性探测：`scripts/desktop_packaging_preflight.py` 新增 `toolchain_probe`，只读检查 node/npm/rustc/cargo/xcodebuild/pake/tauri，明确 Pake GPL-3.0、Tauri sidecar/signing_notarization 边界，不生成真实包。
- [x] PDF fallback / PWA 离线 shell / 移动长标签点击守门：`tests/run_frontend_click_smoke.py --mode all` 真实点击 PDF fallback、service worker 离线二次加载、移动端 Complete/Vargas/Synastry/Prashna/Transit Compare 标签切换，并修复 service worker 把 HTML fallback 返回给 JS module 请求的 MIME 噪声。
- [x] 报告/导出后端 artifact 用户可见完整性：`/api/report_artifact` 返回 `artifact_status`、`primary_artifact`、`download_filename`、`download_mime`、`fallback_reason`、`user_message`、`next_action` 与 `delivery` 镜像；前端 PDF 下载优先使用后端下载契约，runtime smoke 验证 HTML artifact 状态和文件名。
- [x] 真实浏览器导入/案例库工作流守门：`tests/run_frontend_click_smoke.py --mode workspace` 覆盖文本星盘识别、填表生成星盘、保存本地星盘、重新打开、参数/日历工作区保存、导出已选案例和导出整库，并已纳入 `--mode all`。
- [x] 移动端导出菜单与 Trust Center 长内容：390px 视口下导出菜单不遮挡、长面板无横向溢出，健康检查/本地数据/安装说明在移动端可读可操作。
- [x] 真实浏览器点击级 smoke 命令级超时/残留进程诊断：`--timeout`、process snapshot、日志尾部与强制清理已进入脚本，长链路异常时不再静默挂起或遗留 API/Vite 子进程。
- [x] 普通用户长链路质量门失败摘要：`scripts/run_quality_gate.py` 输出可行动失败摘要、cwd、stdout/stderr 尾部、click smoke reason/process_snapshot，并修复前端构建 cwd 指向 `jyotish-app`。
- [x] PDF/文本星盘导入文件上传真实浏览器守门：`tests/run_frontend_click_smoke.py --mode import-files` 覆盖文本文件上传解析、PDF 文本抽取失败恢复、导入后字段质量提示与移动端文件选择入口，并纳入 `--mode all`。
- [x] 普通用户安装/启动文档与质量门输出统一：README 增加“普通用户启动路径”，质量门失败摘要输出同一套网页/API/Trust Center 步骤，明确 PWA 只包装网页壳、本地 API 仍需单独启动。
- [x] README/应用内 Trust Center/失败恢复文案术语一致性：应用界面统一使用“普通用户启动路径 / 网页服务 / 本地 API 服务 / PWA 安装壳”，命令只保留在 README 与质量门失败摘要里。
- [x] 质量门分层与运行成本：`scripts/run_quality_gate.py --profile quick|browser|release` 已拆分快速开发守门、完整浏览器守门、发布前守门，并保留 `--frontend-click-mode` 作为局部浏览器路径复验入口。
- [ ] 整机与 Git 云端地毯式遗漏审计：只读枚举整机印度占星相关资料、历史工作区、技能包、引擎碎片、git 仓库与当前远端所有 refs；把遗漏能力/代码/资料反向映射到当前网页/app。
- [x] 整机与 Git 云端地毯式遗漏审计第一轮：已完成高相关目录、历史报告、云端 HTTPS mirror、远端 refs、关键词覆盖矩阵与遗漏优先级文档。
- [x] Ashtakavarga Prashtara / Yoga Pinda 第一类产品化闭环：复用现有 `calc_prastara_av`，新增 `calc_yoga_pinda` 一等契约，并补 API、前端 Skill workbench、registry 与测试守门。
- [x] Sripathi/Placidus 房宫算法用户可控切换与 parity 守门：Bhava Chalit 读取 Calculation Settings 的 `houseSystem`，API 返回 requested/selected/available house systems、Placidus 所需 birth JD/location 与 fallback 元数据，前端工作台显示宫位制、可选系统、宫位边界与迁移摘要。
- [x] KP Horary 产品化闭环：Prashna API 返回 `kp_horary`，包含可选 1-249 `horary_number`、ruling planets、cuspal sub-lord、house significators 与 judgement matrix；前端 Prashna 结果和案例保存/导出保留该证据。
- [x] Tajika Harsha/Panchavargiya Bala 产品化闭环：`scripts/tajika.py` 新增 Harsha/Panchavargiya/综合强度层，`solar_return.py` 与 `varshaphala.py` 年报均返回 `tajika_strength`，Skill Workbench 显示年度强度与风险摘要。
- [x] Muhurta date-range solver：`scripts/muhurta.py` 新增 `muhurta_range_search`，`/api/muhurta` 支持 `start_date/end_date/activity/limit/location` 范围搜索，Skill Workbench 展示候选日期、推荐窗口和过滤原因。
- [x] Sayanadi/Shayanadi Avastha 与 D24/D30/D60 深度模板产品化：新增 `/api/deep_varga_avastha` 聚合层，复用 `avastha_calculator.py`、`divisional_charts_extended.py`、`trimshamsa_d30.py`，Skill Workbench 展示 Avastha 主导状态、深分盘模板与风险标记。
- [x] 二轮整机/Git/开源对标审计与全球排名更新：注册表 68 技法、37 API、碎片审计 0 问题；补齐 `deep_varga_avastha` 注册表/目录/审计映射，确认第一类产品化缺口已闭环。
- [x] 发布/仓库卫生第一步：release profile 新增关键产品文件未跟踪守门，28 个产品关键 untracked 文件已纳入 Git 暂存，`audit_fragments.py --strict` 当前报告 untracked_count=0。
- [ ] 下一步：完整 browser/release profile 与云端分支同步检查，确认普通用户从 GitHub 拉取后网页/API/PWA/报告/高级 Skill Workbench 路径完整。