refactor: DSA 后续开发规划：[实时告警中心] 规则、触发历史、Web 管理… (#1202)

[ZhuLinsen]

PR Type

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

Background And Problem

• 当前问题：完成实时告警中心 P8 收口：同步配置示例、配置注册说明、Web 文案、告警文档和 changelog，保持 legacy 配置与现有告警中心能力描述一致。
• 影响范围：本次改动涉及 9 个文件，Diff 为 +163 / -8。
• 触发来源：Issue 自动执行（Issue [Feature] DSA 后续开发规划：[实时告警中心] 规则、触发历史、Web 管理、通知联动与持仓/大盘风险监控 #1202）。

Scope Of Change

• .env.example
• apps/dsa-web/src/pages/SettingsPage.tsx
• apps/dsa-web/src/pages/__tests__/SettingsPage.test.tsx
• apps/dsa-web/src/utils/systemConfigI18n.ts
• docs/CHANGELOG.md
• docs/alerts.md
• src/core/config_registry.py
• tests/test_alerts_docs.py
• tests/test_system_config_service.py

Documentation And Changelog

• 已同步更新文档/变更记录：docs/CHANGELOG.md, docs/alerts.md。

Issue Link

Closes #1202

Verification Commands And Results

./scripts/ci_gate.sh flake8
./scripts/ci_gate.sh offline-tests

关键输出/结论 / Key output & conclusion:

• lint:PASS, test:PASS

Compatibility And Risk

• Medium：涉及 .env.example, apps/dsa-web/src/pages/SettingsPage.tsx, apps/dsa-web/src/pages/__tests__/SettingsPage.test.tsx, apps/dsa-web/src/utils/systemConfigI18n.ts, docs/CHANGELOG.md, docs/alerts.md，建议按文件范围复核。
• 前提假设：
  • P0-P7 已按 issue 进度表由 docs: 补齐告警中心 P0 基线与契约 #1301、feat: 新增告警 API MVP ( P1 )（#1202） #1314、feat: 增加 P2 告警评估 Worker #1323、feat: 新增 Web 告警中心 MVP（P3） #1334、feat: 记录告警通知结果与持久化冷却 P4 #1337、feat: 告警中心支持 MA/RSI/MACD/KDJ/CCI 日线技术指标规则 P5 #1345、feat: 告警中心支持持仓与自选股联动（P6 #1202） #1379、feat: 新增 P7 大盘红绿灯结构化告警 #1419 合入，本任务不重新实现 API、worker、Web、指标、持仓或 Market Light 能力。
  • 不修改 secrets、workflow、deploy、migration，也不自动迁移、删除或覆盖用户现有 AGENT_EVENT_ALERT_RULES_JSON。
  • README.md 不扩写告警细节，详细说明继续放在 docs/alerts.md 或相关 docs。
  • 若发现 config registry 或 Web 文案已经同步，只做缺口补齐和一致性校准。

Rollback Plan

• git revert <merge-commit> 回滚本 PR 提交，重点确认 .env.example, apps/dsa-web/src/pages/SettingsPage.tsx, apps/dsa-web/src/pages/__tests__/SettingsPage.test.tsx, apps/dsa-web/src/utils/systemConfigI18n.ts 恢复正常。

Acceptance Criteria

• docs/alerts.md 补齐本地配置、Docker、GitHub Actions、Web 使用、Desktop、规则字段、legacy JSON 兼容、触发历史、通知结果、冷却、持仓联动、Market Light 联动、degraded/skipped 状态和回滚说明。
• .env.example 中告警相关配置示例与实际配置键保持一致，且不引入默认开启行为。
• config registry 或系统配置展示文案与当前告警中心能力一致。
• Web 告警中心相关文案与 P0-P7 已落地能力一致，不暴露敏感配置或 legacy JSON 编辑入口。
• docs/CHANGELOG.md 的 [Unreleased] 使用扁平格式追加 P8 收口记录，不新增分类标题。
• 不改动通知网关、Market Review 2.0、自动交易、自动迁移或 GitHub Actions 行为。

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
• 已同步更新相关文档与 docs/CHANGELOG.md，并在 PR 描述中说明文档落点 / Relevant docs and docs/CHANGELOG.md are updated, and the documentation location is stated in this PR

[github-actions]

🤖 自动审查报告

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

📁 修改的文件

• 📝 .env.example (+1/-0)
• 📝 apps/dsa-web/src/pages/SettingsPage.tsx (+3/-1)
• 📝 apps/dsa-web/src/pages/__tests__/SettingsPage.test.tsx (+52/-0)
• 📝 apps/dsa-web/src/utils/systemConfigI18n.ts (+6/-0)
• 📝 docs/CHANGELOG.md (+1/-0)
• 📝 docs/alerts.md (+70/-0)
• 📝 src/core/config_registry.py (+13/-7)
• 📝 tests/test_alerts_docs.py (+16/-0)
• 📝 tests/test_system_config_service.py (+1/-0)

---

🧠 AI 代码审查意见

结论

Ready to Merge

结构化审查结果

• 必要性：

  • 通过。PR 描述明确指出当前问题是“完成实时告警中心 P8 收口”，涉及同步配置示例、注册说明、Web 文案、告警文档和 changelog，以保持 legacy 配置与现有告警中心能力描述一致。这对于确保新功能与现有系统的统一性和文档完整性至关重要，具有明确的业务价值。

• 关联性：

  • 通过。PR 描述中明确列出 "Issue Link: Closes [Feature] DSA 后续开发规划：[实时告警中心] 规则、触发历史、Web 管理、通知联动与持仓/大盘风险监控 #1202" 及 "触发来源：Issue 自动执行（Issue [Feature] DSA 后续开发规划：[实时告警中心] 规则、触发历史、Web 管理、通知联动与持仓/大盘风险监控 #1202）"，关联性清晰。

• 类型：

  • 建议类型：refactor。本次改动主要集中在文档、配置元数据、Web UI 字段可见性及其测试，旨在对现有实时告警中心能力进行“收口”和一致性校准，符合 refactor 的语义（在不改变外部行为的前提下改进内部结构或表示）。同时，大量的文档更新也体现了 docs 的性质。当前选择 refactor 是合理的。

• 描述完整性：

  • 完整。PR 描述包含了背景、问题、影响范围、变更范围、文档更新说明、关联 Issue、详细的验证命令与结果（包括 ci_gate.sh 的执行和通过状态）、兼容性与风险评估、回滚方案、以及详细的验收标准。所有必需的信息都已提供。

• 风险级别：

  • 中。PR 描述中自评为 Medium，并详细说明了涉及的文件范围和主要变更是文档、Web UI 可见性及配置元数据。改动不涉及核心逻辑、数据库迁移或 API 行为，主要风险在于文案、配置项隐藏逻辑是否正确，以及文档是否准确反映 P0-P7 的能力。通过代码审查，风险已得到适当控制和测试覆盖。

• 必改项：

  • 无。本次审查未发现阻断合入的正确性、安全性问题，CI 检查均已通过，PR 描述与实际改动内容一致，且回滚方案已提供。

• 建议项：

  • 无。本次 PR 的内容、描述和测试都非常完善，没有发现需要进一步改进的非阻断性建议。

---

详细审查意见

1. 代码变更 (apps/dsa-web/src/pages/SettingsPage.tsx, apps/dsa-web/src/pages/__tests__/SettingsPage.test.tsx, apps/dsa-web/src/utils/systemConfigI18n.ts)：

   • Web 端将 AGENT_EVENT_ALERT_RULES_JSON 添加到 AGENT_HIDDEN_KEYS 中，成功实现了在 Web UI 上隐藏该 legacy 配置项的目标，符合验收标准“Web 告警中心相关文案与 P0-P7 已落地能力一致，不暴露敏感配置或 legacy JSON 编辑入口”。
   • 新增的测试用例 hides legacy event alert JSON field in Agent settings 对此行为进行了有效覆盖，确保了隐藏逻辑的正确性。
   • systemConfigI18n.ts 中新增的国际化文案清晰地将 AGENT_EVENT_ALERT_RULES_JSON 标记为“事件告警规则（Legacy）”，并提供了使用告警中心（Web/API）管理规则的建议，文案表达准确。

2. 后端配置 (src/core/config_registry.py, tests/test_system_config_service.py)：

   • config_registry.py 中，AGENT_EVENT_ALERT_RULES_JSON 的 title 被更改为 "Event Alert Rules (Legacy)"，description 也做了更清晰的说明，并将其 is_editable 属性设置为 False。这在后端层面强制了该配置项的只读属性，与 Web UI 的隐藏行为形成有效联动，进一步收口了 legacy 配置的管理。
   • AGENT_EVENT_MONITOR_ENABLED 和 AGENT_EVENT_MONITOR_INTERVAL_MINUTES 的描述也得到了优化，更明确地说明了其作用和关闭时的行为。
   • test_system_config_service.py 中新增的断言 self.assertFalse(items["AGENT_EVENT_ALERT_RULES_JSON"]["schema"]["is_editable"]) 有效验证了 is_editable 属性的修改，保障了后端配置的正确性。

3. 文档更新 (docs/CHANGELOG.md, docs/alerts.md, tests/test_alerts_docs.py)：

   • CHANGELOG.md 中新增的 [文档] 完成告警中心 P8 收口文档 记录符合规范，且以扁平格式追加，满足了验收标准。
   • alerts.md 文档得到了大幅扩充，新增了“P7 大盘红绿灯与市场联动”和“P8 文档、迁移与收口”等关键章节。特别是 P8 收口部分，详细描述了本地配置、Docker、GitHub Actions、Web 使用、Desktop 等场景下的告警配置与兼容边界，并明确了 legacy JSON 与持久化规则的收口关系，内容全面且符合验收标准。
   • test_alerts_docs.py 中新增的测试用例 test_alerts_doc_defines_p7_market_light_and_p8_checkout_sections() 验证了 alerts.md 中新章节的存在，确保了文档的完整性。

4. CI 与验证：

   • CI 检查（py_compile 和 flake8）均已通过。
   • PR 描述中明确提供了 ./scripts/ci_gate.sh flake8 和 ./scripts/ci_gate.sh offline-tests 的执行结果（lint:PASS, test:PASS），证明了本地验证的充分性，完全符合审查规则中对 ci_gate.sh 验证的期望。

综上所述，本次 PR 的变更内容与 PR 描述高度一致，对代码、文档和测试都进行了细致的更新和覆盖，达到了“代码 + 文档 + CI”的联合审查标准。

---

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

[ZhuLinsen]

评审结论

• 必要性：通过，告警中心 P8 收口需要同步配置示例、配置注册、Web 文案、文档和 changelog，符合 AGENTS.md 对用户可见配置/文档变更同步更新的要求。
• 是否有对应 issue：有，Closes #1202。
• PR 类型：refactor，主要是配置展示边界、文案和文档收口，未新增告警运行时能力。
• description 完整性：完整，已说明范围、验证、兼容性、文档落点和回滚方式。
• 是否可直接合入：可，当前 CI 为 success，diff 与描述基本一致，未发现阻断性正确性问题；mergeable_state=blocked 更像分支保护状态，不单独构成不可合入理由。

主要问题

1. [Nice to have] apps/dsa-web/src/pages/SettingsPage.tsx / src/core/config_registry.py：本 PR 将 AGENT_EVENT_ALERT_RULES_JSON 设为不可编辑并在 Web 系统配置页隐藏，这是有意收口 legacy JSON 的行为，但也会让曾经通过系统配置页维护 legacy 规则的用户失去原入口。现有文档已说明 legacy 入口和 Web/API 推荐路径，但建议在发布说明或告警文档中更明确写一句“已有 legacy JSON 仍会被运行时读取，后续需通过 .env/环境变量维护或迁移到 /alerts”，避免用户误判为配置被删除。该项不阻断合入。

---

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