Jyotisha/docs/tasks/TASK-chart-surface-polish-20260929.md

TASK · 星盘去引擎展示、能力列按支持显示、宫位对齐、图标解释与盘面收紧（2026-09-29）

初稿为任务书模式。产品于 2026-09-29 明确要求“请你执行任务书”，已进入独立工作树实施；执行后独立验收，本轮不推送、不发布。

执行补充：尺寸只在既有 ≥1024px 桌面两栏断点收紧，印度 440px 指绘图区而非含 padding 的外框。T3 同时修复本命、月亮、Bhava、行运的同类宫位对齐；本命/月亮保留原八列 markup，按八列表头精确限定 CSS 第四列，不全局改 mid。

1. 基线与串行依赖

• 调查基线：origin/staging = 78b9c5b65cda44650e8c7ca019931ce33a85a95d。执行开工重新 fetch，记录实际 SHA。
• 实现分支：codex/chart-surface-polish-20260929；工作树：.worktrees/chart-surface-polish-20260929。
• 进度：docs/tasks/PROGRESS-chart-surface-polish-20260929.md；真人清单：docs/testing/chart-surface-polish-20260929.md。
• 必须接在 codex/mobile-chart-confirmed-edit-20260929（BUG-1083）合入之后；本基线已包含其修复。不得重新引入手机宽表撑开外层网格的问题。
• 同日报告两单既有顺序不变：codex/report-reader-polish-20260929 → codex/report-english-edition-20260929。本单优先限定 /chart；若要同时编辑共享 vedic-chart-svg.tsx、报告图盘导出或同一 CSS/文档段落，必须串行交接，不能各自在旧基线上覆盖。默认本单共享 SVG 改动先合入，英文版再接续；若对方已开工，先协调，不重置别人分支。

2. 事故实证与根因

本轮输入为产品截图和展示要求，不记录截图中的真实星盘数据。本轮没有登录态浏览器复现或全量业务验收。代码定位按符号为准，以下行号对应上述基线：

现象	证据与根因
所有印度盘显示引擎来源	frontend/src/lib/chart-view-mapper.ts:822 投影 engineName，chart-view-contract.ts:261 要求该字段；components/chart-page/chart-param-table.tsx:28 把它作为参数行无条件渲染。chart-vedic-tab.tsx:312 的共享 VedicLayout 让该行出现在全部 23 种印度盘型。西洋盘不走此表，不能声称其已有同一行。
分盘宫位标题左、内容居中（BUG-1098）	chart-vedic-tab.tsx:148,163 的 VargaRow / VargaAscendantRow 给宫位套了 chart-page-planet-mid。globals.css:5210–5215 本来统一左对齐，却被 :5249 的该类覆盖成居中。是单元格类使用不当，不是引擎数据错误。
盘内符号无悬停解释	components/personal-report/vedic-chart-svg.tsx:168–220 的 OccupantGlyph 渲染行星、逆行短线、As，没有逐符号 <title>；整盘读屏描述不能替代鼠标提示。西洋盘 components/chart-page/western-wheel-svg.tsx 的行星交互组已有键盘/选择语义，须在其上补解释而非换一套事件。
印度盘可能铺得过大	globals.css:5136–5142 的 .chart-page-vedic-stage 未设最大宽度；桌面 :5508–5519 第一列为 minmax(0,1.1fr)，盘随列宽铺开。西洋盘 .chart-page-western-wheel（:5417–5421）已有 520px 上限。尺寸取舍不是计算缺陷。

历史约束核对

已确认的产品契约冲突：

• frontend/DESIGN.md §15「排盘参数表」原来明确规定八行，最后一行为「引擎」。因此移除是新的产品决定，不是丢字段。
• 09-28 TASK-chart-types-and-report-buttons-20260928.md T3 规定分盘庙旺只取入旺 / 自宫 / 落陷，且同位是分盘与本命同星座；不能以空白多直接认定计算不支持，也不能把它包装成全面尊贵状态或外部精度认证。
• 09-18 符号化改造让宫内只画行星符号；读屏信息、图例和鼠标悬停提示不是一回事，不能以已有 aria-label 代替可见解释。

数据能力核查（代码证据，不是外部占星准确率验证）

范围	实际来源	本单处理
D1 状态	/api/chart 的原生 _get_dignity_level；旧八列表	保留，不改其计算
D2–D60 行星庙旺	chart-view-mapper.ts:216–253 服务端 vargaRows 调用 chart-view-varga.ts:19–23；规则表由 tests/test_chart_page_vedic_tables_contract.py 与 Python 原生常量及九体×十二星座逐格对照	保留三档能力：入旺 / 自宫 / 落陷。不是 /api/varga_full 原生返回字段，但为有合同保护的同源派生，不能说引擎不支持。没有三档命中为 null；不代表未知或不支持
D9 行星同位	mapper 比较 D1/D9 星座；scripts/jyotish_engine.py:300–313 _calc_vargottama 原生判定也是 D1↔D9	保留；必须加星盘投影与原生结果的直接对照测试
D9 上升同位	mapper 比较 D1/D9 上升；原生 consultation_native_layers.build_d9_summary 与 satabdika_dasha.satabdika_applicability 有同座判定路径	保留已有事实比较，补同源合同；不要声称 _calc_vargottama 本身处理上升
其他 Dn 同位	mapper 对任意分盘都用 sign === natalSign，并统一命名 vargottama；原生 _calc_vargottama 并无各 Dn 的这套泛化	按产品“不支持不显示”的原则，本单收口：只在 D9 显示「同位」，其他 Dn 隐藏。不是断言通用同座比较算错，而是限制产品术语的能力范围
上升庙旺	无此字段，组件固定「—」	不对上升假造尊严计算；行星能力列仍在，上升此格标「不适用」并对照 VOICE
月亮 / Bhava / 行运 / 西洋	独立表，无上述两列	不新增

/api/varga_full 本身没有这两字段；既有契约的 dignity 为三枚举或 null、vargottama 为必填 boolean，没有独立的 unsupported 状态。缺分盘/本命星座时 mapper 会跳过该行。支持性应由服务端的盘型能力和有效数据来源表示，不能由真值多少推断，也不能让未知被 false 吞掉。本轮只读查到上述测试存在，尚未运行其回归，不以旧记录代替本轮结果。

3. 决策记录

项	产品授权 / 本单执行口径
D1 去引擎	产品要求所有盘型不再显示「引擎」「Swiss Ephemeris（本站）」这类实现品牌。删除展示节点，不改为「自研引擎」「本站引擎」，不只用 CSS 藏起来。印度各盘型与西洋盘都查。
D2 能力列	有实际计算依据才显示「庙旺 / 同位」；没有该能力时隐藏整列，不留一列横杠。支持但未命中不能当成不支持。此次不扩建算法、不虚构结果。
D3 宫位对齐	宫位标题与每行内容统一左对齐，同列左右 padding 一致。不是把表头改成居中来迁就错误的单元格样式。
D4 图标说明	鼠标停在图标上显示中文名称和已有事实；键盘能获得等价信息。手机没有 hover，提供可用的轻点说明且不与现有点选动作冲突。不加运势解释，不调用模型。
D5 盘面收紧	适度缩小星盘页的盘面，优先收紧桌面最大宽度；手机不机械按比例缩小文字与点击区域。不改数据坐标，不重做绘图。

对旧约定的有限修订：D1 推翻 DESIGN §15 参数表必须含引擎的旧约定；D2 将 09-28 T3 与 BUG-1076 中「所有分盘同位 = 与本命同星座」的泛化展示收口为 D9 才显示同位（基于此次“不支持则不显示”的授权，架构建议；不新造另名列），庙旺的同源三档派生保留；D3 只修宫位列，宿主 / pada 的居中不顺带改；D5 允许修改星盘页尺寸上限，保留 BUG-1083 的无溢出和西洋盘点击 / 避让规则。版权、许可证、第三方声明与内部诊断元数据不删除；隐藏展示不是让技术栈保密的安全措施。

4. 硬红线

1. 不改本命 / 分盘 / Bhava / 行运 / 西洋盘的计算结果、岁差、交点、宫制或时间精度提示；不拿 D1 数据补分盘（BUG-1076）。
2. 不在浏览器补算庙旺或同位。数据不支持就不显示，未知不伪装为 false / 正常。
3. 服务端计算元数据和审计来源保留；不得全仓字符串替换或删除许可证署名。此次只收口面向用户的盘面展示，不清洗既有存储报告或原始引擎 JSON。
4. 星盘页的盘型条、按需取数、缓存身份、等待 / 失败 / 重试规则不变；不新增请求、模型调用或 loading 动画。
5. 盘面文字与触控可用性优先于尺寸；西洋盘现有行星点选过滤相位、再次点选取消必须保留。多星同宫和拥挤盘不许通过缩字掩盖重叠。
6. 共用 SVG 同时供校正右栏、报告与静态导出使用。不得直接把静态绘图组件整体改为依赖浏览器的客户端组件；交互只在需要的页面接入，导出仍是安全的静态 SVG。图表缩小样式只作用于 /chart。
7. 不动数据库、依赖版本、workflow、DNS、main，不碰首页装配。遵守 AGENTS 增长合同，不另加净增零行约束。
8. 改代码之前在 frontend/tests/ 与 tests/ 检索相关路径、符号、类名和文案；既有断言改动逐条写「原值 / 新值 / 原因」，不删测试消红。fixture 使用现有真实引擎 golden 或虚构输入生成的真实引擎响应。

5. 任务分解与验收

T1 · 去除盘面引擎展示

• 删除参数表引擎行；engineName 在 chart-page view schema / mapper 中只为该行服务，删除这项无用展示投影并同步 fixture / 缓存兼容，不影响原始后端计算元数据。检查所有印度盘型和西洋盘的可见说明是否仍出现实现来源。
• 不误删岁差 / 交点 / 宫制等影响结果的参数，不误删准确性边界。
• 验收：遍历全部盘型，渲染结果无引擎标签和供应商名称；西洋说明同样通过。后台/内部数据来源仍可追踪。若报告中共享盘块原有相同标签，同步去掉盘块标签，但不扩成报告正文清洗任务。

T2 · 能力列按支持显示

• 开工先复核本文数据能力结论，分别记录庙旺与同位的有效来源、覆盖范围和缺值含义。使用最小的服务端列能力契约（如每盘 supportsDignity / supportsVargottama，或等价的可用性字段），无需新建全站能力注册系统。D9 保留两列，其他 Dn 保留庙旺、隐藏同位；上升庙旺标不适用。
• 兼容旧浏览器模块缓存：契约新增字段不得导致旧缓存无声显示错误，按现有 schema/缓存换键方式处理；缺能力声明时保守隐藏对应列，不能假定支持。由 service mapper 输出列能力，组件只消费，不用分散的 JSX 魔法判断。
• 支持性独立于结果值：false 是有效同位结果；未命中入旺 / 自宫 / 落陷也可能是正常有效结果。不能以 rows.some(row => row.vargottama) 或某列有非空字符串作为能力判断。
• 不支持的列整列不渲染（含表头和上升行）；单颗星不适用时可留「—」。两列分别控制，不能同开同关。
• 验收：真实 golden 的支持盘保留结果；缺失能力、只支持其中一列、两列都不支持、支持但全不命中分别覆盖。缺字段/无效字段的防御测试须从真实 golden 复制后做定向删除或破坏，不手造引擎响应形状。

T3 · 宫位同列左对齐

• 精确收窄表格样式到宫位单元格和表头，审计本命、分盘、月亮、Bhava 和行运的同类宫位列。
• 验收：桌面与手机截图中宫位标题和内容同一左边线；自动化断言 computed style 和边距，而不只看 JSX；宿主/pada 等刻意居中列不变，横向滚动仍在表格内部。

T4 · 图标解释

• 覆盖盘内行星、上升标记、逆行标记及存在的星座/角点缩写，明确每种图标含义。文案只报名称、已知位置与顺逆等事实，禁止编个人运势。
• 复用已有 tooltip / 提示样式和现有数据，图例与读屏信息保留。可在 SVG 中补安全的 <title> 作为基础描述，但原生 title 不等于已完成 focus/触屏可见提示；页面级增强不要污染静态绘图层。没有度数等精细数据时只显示有依据的名称，不从粗略显示串造精度。
• frontend/src/lib/report-chart-export.tsx:10–25 的 SVG serializer 当前不允许 title。本单导出的静态 SVG 不要求悬停交互，允许该描述节点按现有规则剥离；不得为图标提示顺带放开脚本、事件属性或任意 SVG 标签白名单。已有图例与事实文本保留，测试明确静态导出不带交互。
• hover 与 focus 可见；离开/失焦/Esc 可关闭；不挡相邻图标。触屏不得依赖原生 title 长按；西洋盘轻点仍完成原有选择，解释随选中显示或采用不冲突的等价方式。
• 验收：鼠标、键盘、触屏各一条交互测试；至少覆盖多星同宫、逆行、上升、切盘后无旧提示；报告/校正共用渲染和静态 SVG 安全合同仍过。

T5 · 缩小盘面

• 推荐初值：/chart 印度盘绘图区宽度上限 440px，西洋盘 480px（不把 stage padding 算成盘宽），同时 width:100% 自适应并居中。印度盘相对 BUG-1083 在桌面记录的 480px 约收紧一成，西洋盘从 520px 小幅收紧；实际基线宽度小于该值时不能反而放大。此数值是设计目标，不是本轮已实测结论，按下方可读性验收可减小缩幅。
• 参数区和下方表格不随盘面一起变窄。骨架盘与结果盘使用相同宽度容器，揭幕后不跳尺寸。
• 手机保留自适应宽度和原可读性。缩小只改容器布局，不用 transform: scale() 留下大空白或压小命中区。
• 验收：至少 375、390、1024、1280 视口对照；无整页横滚，表格仍可横滚；在实际盘宽下验证文字和触控尺寸、西洋拥挤标签/命中归属。报告与校正盘尺寸不变。

T6 · 文档、回归与交付

• UI 同提交更新 frontend/DESIGN.md，新文案核对并更新 frontend/docs/VOICE.md，用户变化入 CHANGELOG.md（Skill 不 bump）。
• 更新 BUG 历史与 PROGRESS；不能自动化的项目进入 docs/testing/chart-surface-polish-20260929.md，实际环境缺口入 BLOCKED.md。
• tsc --noEmit 零错、lint 零 error、相关套件 fail/cancelled 均为零；全量 npm test 与同环境基线比测试名称、失败名单和退出码。npm run build 后 / 仍 Static，首屏 gzip 同口径变化 ±2%。
• 若修改 Python 或 Python 合同测试，定向与 run_quality_gate.py --profile quick 全量必跑；即使仅前端，本单也运行 quick 以防漏掉前端源码的 Python 合同。
• 文档推送前运行 tests/test_repo_privacy_markers.py。代码完成先交 Claude 独立验收，不自行 push；用户授权推 staging 后才核对门禁、部署 SHA，不把文档已推送当作实现已上线。

已定位的回归文件与旧断言

文件	本轮重点
frontend/tests/chart-page-view.test.tsx	参数行无引擎、全盘型遍历；原西洋 max-width:520px 断言改为本单目标，写三栏理由
frontend/tests/chart-varga-table.test.tsx	真实分盘行/D1冻结仍保留；旧六列断言改为 D9 六列、其他 Dn 五列及能力缺失分支；宫位类回归
frontend/tests/chart-view-varga-dignity.test.ts	入旺/自宫/落陷规则子集与未命中含义不变
tests/test_chart_page_vedic_tables_contract.py	同源规则表合同保留；如增加 D9 同位对照，使用真实 golden 和原生函数，输入岁差明确
frontend/tests/chart-planet-glyphs.test.tsx	原 markup.match(/逆/g) 只允许一处“逆”，新增 title 后不可继续全 markup 数字数；改为验证可见文字与说明节点各自语义，三栏列明，不能直接删除测试
frontend/tests/chart-page-mobile-width-20260929.test.ts	保留 BUG-1083 的 minmax/overflow 合同；新增页面限定的盘宽约束
frontend/src/lib/report-chart-export.tsx 的相关测试	共享 drawing 仍 hook-free、静态导出安全、数字 height，不能出现 SVG height="auto"（BUG-906）

西洋 hover 必须实测可见文字层而不只是透明命中层；现有 western-wheel-svg.tsx 先画 hit group、后画 caption group，上层文字可能截走指针。不得为了 tooltip 破坏字符命中归属和原键盘按钮语义。

6. 让步顺序

1. 可先不扩展到本单没有展示缺陷的报告正文；不得扩大为全站技术词清理。
2. 若触屏复杂浮层增加冲突，改用现有选中详情承载等价说明，不新造复杂手势。
3. 若缩小后破坏可读性，减小缩幅，不能牺牲图标文字或命中区域。
4. 去引擎、真实能力边界、宫位左对齐、鼠标图标解释与手机不溢出不可让步。

7. 开工前置命令

每次 Git 操作前都先 git status -sb，确认在自己的工作树；禁止 stash。以下路径按实际环境调整，不在主检出写代码。

git status -sb
git fetch origin --prune
git status -sb
git worktree add -b codex/chart-surface-polish-20260929 .worktrees/chart-surface-polish-20260929 origin/staging
cd .worktrees/chart-surface-polish-20260929
git status -sb
python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45
# 必读 AGENTS、frontend/AGENTS、DESIGN、VOICE；检索 BUG_HISTORY 和全部相关源码合同。
# 核对实际 Node/Python 环境，在同基线独立树保存全量测试名称/失败清单、构建与 gzip。

8. BUG 编号起点

写作时 docs/BUG_HISTORY.md 最大号 BUG-1097。本单从 BUG-1098 起登记已确认的展示缺陷；实现前再次核对，若被占用按当前最大号连续顺延并同步任务书/进度引用。新增功能/产品取舍不为了凑编号全部记 Bug。