docs: 收口 #1390 P7 决策信号文档与 Web i18n

[massif-01]

PR Type

• fix
• feat
• refactor
• docs
• chore
• test

Background And Problem

#1390 P7 要求把 DecisionSignal 1.0 前几期能力做最终收口：文档/API/Web 展示/迁移回滚/脱敏边界需要保持一致。P1-P6 已经引入 Web UI 与后端链路，本 PR 不新增运行时能力，只补齐 P7 文档、Web i18n 展示边界和防回归测试，避免用户界面直接裸露 enum/raw value 或设置页出现未本地化配置标题/说明。

Scope Of Change

• 新增 docs/decision-signals.md，补齐字段语义、API/Web 使用、告警/通知/组合风险/outcome/feedback、脱敏边界、迁移与回滚。
• 同步 docs/full-guide*.md、docs/INDEX*.md、docs/alerts.md、docs/notifications.md、docs/CHANGELOG.md 的入口和交叉引用。
• 新增 apps/dsa-web/src/utils/decisionSignalLabels.ts，统一 DecisionSignal 的 market、market phase、horizon、plan quality、source type 本地化 value label。
• 收口 DecisionSignalsPage、DecisionSignalDisplay、ReportDecisionSignals、PortfolioPage 的展示路径，避免 jp/kr、closing_auction、10d、partial、market_review、sell/reduce/alert 等 raw value 直接出现在 UI。
• Review follow-up：Portfolio 风险预览复用结构化 action label helper，确保 action='sell' 且旧数据带 actionLabel='卖出' 时，英文 UI 仍显示 Sell。
• Review follow-up：同步 DecisionSignal list/latest API 参数描述和 checked-in OpenAPI spec，market filter 说明统一为 cn/hk/us/jp/kr。
• 扩展 Web/后端测试：i18n 展示、Portfolio 风险 fallback、设置页负向 guard、专题文档锚点、敏感信息脱敏边界。

Issue Link

Refs #1390

Verification Commands And Results

cd apps/dsa-web && npm run test -- decisionSignalLabels DecisionSignalsPage DecisionSignalDisplay ReportDecisionSignals PortfolioPage system_config_i18n
npm run test -- PortfolioPage
python -m pytest tests/test_decision_signal_docs.py tests/test_decision_signal_service.py tests/test_decision_signal_api.py tests/test_alert_worker.py tests/test_decision_signal_summary.py -q
python -m pytest tests/test_decision_signal_docs.py -q
python -m pytest tests/test_notification.py -k decision_signal -q
cd apps/dsa-web && npm run lint
cd apps/dsa-web && npm run build
git diff --cached --check
git diff --check

关键输出/结论：

• Web targeted tests：6 files / 68 tests passed。
• Review follow-up Web test：PortfolioPage 26 passed，覆盖旧 actionLabel='卖出' 在英文 UI 下显示 Sell。
• Backend targeted tests：140 passed, 3 warnings。
• Review follow-up docs test：tests/test_decision_signal_docs.py 3 passed，覆盖 OpenAPI market 描述为 cn/hk/us/jp/kr。
• Notification targeted tests：5 passed, 68 deselected, 2 warnings。
• npm run lint：passed。
• npm run build：passed。
• git diff --cached --check：passed。
• git diff --check：passed。
• 过程中也执行过 PATH=.venv/bin:$PATH ./scripts/ci_gate.sh，结果为 3528 passed, 2 deselected, 44 warnings, 322 subtests passed；最终一次 Web-only label helper 调整后补跑了上述 targeted tests/lint/build。

Visual Evidence (if applicable)

• 截图链接 / Screenshot links:
  • 中文 Web i18n 验收截图

• English Web i18n 验收截图：

• 截图生成方式：本地 Vite 页面 + Playwright mock API，注入 JP / closing_auction / 10d / partial 信号；截图断言确认中文页面包含 日股、集合竞价、部分，英文页面包含 Japan、Closing auction、Partial。
• 截图没有入库，避免一次性验收图污染仓库；可复现证据见上方 Web i18n 测试、lint 和 build。
• Portfolio 风险预览 follow-up 为文本 label 选择逻辑修复，无布局变化；本次用 PortfolioPage DOM 回归测试覆盖 stale actionLabel 反例。

Compatibility And Risk

• API wire value 不变：后端继续返回原始 enum 字段，前端按当前 UI 语言转换展示 label。
• DecisionSignal API/OpenAPI 仅同步参数说明为 cn/hk/us/jp/kr；不修改数据库 schema、API route、request/response 字段、CLI 参数、环境变量、config registry 或 .env.example。
• 设置页保持无 DecisionSignal 配置项进入 schema；如果未来新增相关配置，现有 guard 会要求中文标题/说明/option label 不 fallback 到英文。
• 风险主要在 Web 展示文案映射遗漏；本 PR 通过显式 enum map 和多入口测试覆盖主要路径。

Rollback Plan

Revert this PR 即可。回滚不需要额外数据库迁移或配置回滚；历史 DecisionSignal、feedback、outcome 数据不会自动清理，既有报告主流程不受影响。

EXTRACT_PROMPT Change (if applicable)

未修改 src/services/image_stock_extractor.py 或 EXTRACT_PROMPT。

Checklist

• 本 PR 有明确动机和业务价值 / This PR has a clear motivation and value
• 已提供可复现的验证命令与结果 / Reproducible verification commands and results are included
• 已评估兼容性与风险 / Compatibility and risk have been assessed
• 已提供回滚方案 / A rollback plan is provided
• 若修改报告格式或 Web UI 界面，已在 PR 描述/评论附受影响报告 / 页面截图，且未把一次性验收截图作为仓库文件合入 / If report formatting or Web UI changed, affected report/page screenshots are linked in the PR body/comments and one-off acceptance screenshots are not committed as repository files
• 若涉及用户可见变更，已同步更新相关文档与 docs/CHANGELOG.md；README.md 仅在首页级信息变化时更新，细节优先写入 docs/*.md / If user-visible changes are included, relevant docs and docs/CHANGELOG.md are updated; README.md is updated only for homepage-level changes, with details kept in docs/*.md

[github-actions]

🤖 自动审查报告

项目	结果
📊 变更文件	23 个
➕ 新增行数	579 行
➖ 删除行数	28 行
🔍 静态检查	✅ 通过
🧠 AI 审查	✅ 已完成

📁 修改的文件

• 📝 api/v1/endpoints/decision_signals.py (+2/-2)
• 📝 apps/dsa-web/src/components/decision-signals/DecisionSignalDisplay.tsx (+16/-15)
• 📝 apps/dsa-web/src/components/decision-signals/__tests__/DecisionSignalDisplay.test.tsx (+24/-1)
• 📝 apps/dsa-web/src/components/report/__tests__/ReportDecisionSignals.test.tsx (+6/-0)
• 📝 apps/dsa-web/src/i18n/uiText.ts (+50/-0)
• 📝 apps/dsa-web/src/pages/DecisionSignalsPage.tsx (+12/-3)
• 📝 apps/dsa-web/src/pages/PortfolioPage.tsx (+12/-1)
• 📝 apps/dsa-web/src/pages/__tests__/DecisionSignalsPage.test.tsx (+37/-0)
• 📝 apps/dsa-web/src/pages/__tests__/PortfolioPage.test.tsx (+31/-2)
• 🆕 apps/dsa-web/src/utils/__tests__/decisionSignalLabels.test.ts (+34/-0)
• 🆕 apps/dsa-web/src/utils/decisionSignalLabels.ts (+98/-0)
• 📝 apps/dsa-web/tests/system_config_i18n.test.ts (+16/-0)
• 📝 docs/CHANGELOG.md (+1/-0)
• 📝 docs/INDEX.md (+1/-0)
• 📝 docs/INDEX_EN.md (+1/-0)
• 📝 docs/alerts.md (+2/-0)
• 📝 docs/architecture/api_spec.json (+4/-4)
• 🆕 docs/decision-signals.md (+123/-0)
• 📝 docs/full-guide.md (+2/-0)
• 📝 docs/full-guide_EN.md (+2/-0)

... 还有 3 个文件

---

🧠 AI 代码审查意见

结论: Ready to Merge

---

结构化审查结果:

• 必要性：通过
  • 理由：本 PR 明确旨在收口 [Feature] DSA 后续开发规划：[AI 建议池 / 决策信号 1.0] 结构化沉淀操作建议、价格计划与后验验证 #1390 P7 阶段的决策信号能力，通过补齐文档、实现 Web UI 的 i18n 展示和加强防回归测试，解决用户界面直接裸露原始 enum/raw value 的问题。这对于提升用户体验、确保系统一致性以及提高可维护性具有明确的业务价值。
• 关联性：通过
  • 证据：PR 描述中明确 Refs #1390，并详细阐述了与该 Issue P7 阶段需求的关联。
• 类型：建议类型为 docs, test, feat
  • PR 勾选了 docs 和 test，符合其主要变更内容。新增 apps/dsa-web/src/utils/decisionSignalLabels.ts 并将其应用于多个 Web 组件进行本地化展示，这在功能上增加了 i18n 支持，因此也符合 feat (feature) 类型。
• 描述完整性：完整
  • 证据：PR 描述包含背景、变更范围、详细的验证命令与结果、兼容性与风险评估以及回滚方案。验证结果充分，并说明了 ci_gate.sh 的执行情况。视觉证据也已提供，并按规定未入库。
• 风险级别：低
  • 关键风险：PR 描述中已评估，主要风险在于 Web 展示文案映射遗漏，但通过显式枚举映射和多入口测试进行了缓解。后端 API 仅更新了 market 参数的描述字符串，未改变其行为。无数据库 schema、API 路由、请求/响应字段、CLI 参数、环境变量或配置注册表等底层修改，回滚方案简单直接。
• 必改项：无。
• 建议项：
  1. API 文档同步：api/v1/endpoints/decision_signals.py 中 market 参数的 description 已更新，新增了 jp/kr 市场。为了保持 API 文档的准确性，请确保 docs/architecture/api_spec.json 文件也已同步更新，包含了这些新的市场信息。尽管 PR 文件列表提及了 api_spec.json，但提供的 diff 截断，无法直接确认其内容变更。
  2. CI 警告处理：./scripts/ci_gate.sh 执行结果显示有 44 warnings。虽然这些警告不构成当前 PR 的阻断项，但从长期代码质量和 CI 清晰度的角度考虑，建议在后续 PR 中逐步审查并解决这些 warnings。
  3. 前端过滤器动态性：在 apps/dsa-web/src/pages/DecisionSignalsPage.tsx 中，虽然 getDecisionSignalMarketLabel 等辅助函数已用于本地化过滤器选项的显示，但如果过滤器选项本身的列表（例如所有支持的市场：cn, hk, us, jp, kr）是硬编码的，未来若新增市场，仍需要手动修改此处。建议考虑一个更动态的机制（例如，从一个统一的枚举定义或后端接口获取可用选项），以增强系统的可扩展性。

---

💡 提示: 请确保代码已通过本地测试，并遵循项目代码规范。

[ZhuLinsen]

评审结论

• 必要性：通过，#1390 P7 需要把 DecisionSignal 文档、Web i18n 展示边界和回归测试收口。
• 是否有对应 issue：有，Refs #1390。
• PR 类型：fix，实际改动包含 Web enum/raw value 展示修复，并配套 docs/test。
• description 完整性：不完整，验证、兼容性和回滚说明基本齐全，但 Web UI 改动的截图证据使用 /private/tmp/... 本地路径，GitHub PR 中不可访问。
• 是否可直接合入：不可，需先补充可访问的 UI 视觉证据；CI 当前为 success，mergeable_state=blocked 本身不作为阻断点。

主要问题

1. [Process blocker] PR 描述 / Visual Evidence：本 PR 修改了 DecisionSignalsPage、DecisionSignalDisplay、ReportDecisionSignals、PortfolioPage 等 Web UI 展示路径。按 AGENTS.md，Web UI 改动必须在 PR 描述、PR 评论、GitHub 附件、Actions artifact 或外部可访问链接中附受影响页面截图；当前给出的 /private/tmp/dsa-pr1390-p7-web-i18n-*.png 是本地路径，reviewer 无法访问，等同未附可验证截图。请上传为 PR 附件/评论或 artifact，或明确说明无法截图并提供替代可视证据。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

[massif-01]

评审结论

• 必要性：通过，[Feature] DSA 后续开发规划：[AI 建议池 / 决策信号 1.0] 结构化沉淀操作建议、价格计划与后验验证 #1390 P7 需要把 DecisionSignal 文档、Web i18n 展示边界和回归测试收口。
• 是否有对应 issue：有，Refs [Feature] DSA 后续开发规划：[AI 建议池 / 决策信号 1.0] 结构化沉淀操作建议、价格计划与后验验证 #1390。
• PR 类型：fix，实际改动包含 Web enum/raw value 展示修复，并配套 docs/test。
• description 完整性：不完整，验证、兼容性和回滚说明基本齐全，但 Web UI 改动的截图证据使用 /private/tmp/... 本地路径，GitHub PR 中不可访问。
• 是否可直接合入：不可，需先补充可访问的 UI 视觉证据；CI 当前为 success，mergeable_state=blocked 本身不作为阻断点。

主要问题

1. [Process blocker] PR 描述 / Visual Evidence：本 PR 修改了 DecisionSignalsPage、DecisionSignalDisplay、ReportDecisionSignals、PortfolioPage 等 Web UI 展示路径。按 AGENTS.md，Web UI 改动必须在 PR 描述、PR 评论、GitHub 附件、Actions artifact 或外部可访问链接中附受影响页面截图；当前给出的 /private/tmp/dsa-pr1390-p7-web-i18n-*.png 是本地路径，reviewer 无法访问，等同未附可验证截图。请上传为 PR 附件/评论或 artifact，或明确说明无法截图并提供替代可视证据。

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。

是误报，截图是有的

[ZhuLinsen]

评审结论

• 必要性：通过，#1390 P7 需要收口 DecisionSignal 文档、Web i18n 展示边界和防回归测试。
• 是否有对应 issue：有，Refs #1390。
• PR 类型：fix，实际修复 Web raw enum/value 展示问题，并配套 docs/test。
• description 完整性：完整，已覆盖背景、范围、验证命令与结果、可访问截图、兼容性、风险、回滚方案和 EXTRACT_PROMPT 说明，符合 AGENTS.md 对 Web UI 与用户可见变更的交付要求。
• 是否可直接合入：可，阻断型 CI 均为 success，当前描述和截图证据已补齐；结合完整改动文件列表和 diff 摘要，未发现 provider/model/Base URL、默认模型或运行时配置保存/迁移逻辑的实际变更，结构化兼容风险提示不构成本次阻断点。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。