docs: close notification issue 1200 (ZhuLinsen#1276)

Author: massif-01

docs/CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [新功能] 通知网关新增 Gotify 一等渠道，支持通过 `GOTIFY_URL` / `GOTIFY_TOKEN` 推送 Markdown 文本并接入 Web 测试、路由、Actions 与诊断。
 - [修复] 收紧 ntfy 结构化校验，避免 URL 编码空白 topic 被误判为有效通知端点。
 - [文档] 补充 Bark custom webhook 示例和 WebPush / Apprise 通知渠道评估，明确本轮不新增运行时依赖或配置入口。
+- [文档] 收口通知专题场景文档，并为 GitHub Actions 通知 env 对照表加入自动化校验。
 - [修复] 聚合报告通知按静态渠道隔离发送失败，并补充自定义 Webhook 部分成功诊断与脱敏测试。
 - [修复] 未配置 Tushare / Longbridge 凭据时不再实例化对应可选 fetcher，避免缺失凭据的数据源进入候选集。
 - [修复] Longbridge 遇到连接关闭类异常后会进入冷却期，并在美股/港股实时与日线请求中临时跳过该数据源，避免请求级频繁重连。

docs/full-guide.md

@@ -69,7 +69,7 @@ daily_stock_analysis/
 
 #### 通知渠道配置（可同时配置多个，全部推送）
 
-> 通知渠道、minimal/advanced key 分层、Actions 映射、`--check-notify` 诊断和 Web 一键测试说明详见 [通知能力基线](notifications.md)。
+> 通知渠道、minimal/advanced key 分层、Actions 映射、`--check-notify` 诊断、Web 一键测试和本地 / Docker / GitHub Actions / Desktop 场景说明详见 [通知专题文档](notifications.md)。
 
 | Secret 名称 | 说明 | 必填 |
 |------------|------|:----:|
@@ -235,7 +235,7 @@ daily_stock_analysis/
 
 ### 通知渠道配置
 
-更多通知配置基线和诊断说明见 [通知能力基线](notifications.md)。
+更多通知配置基线、诊断和部署场景说明见 [通知专题文档](notifications.md)。
 
 | 变量名 | 说明 | 必填 |
 |--------|------|:----:|
@@ -695,7 +695,7 @@ crontab -e
 
 ## 通知渠道详细配置
 
-通知渠道矩阵、minimal/advanced key 分层和 `--check-notify` 诊断口径见 [通知能力基线](notifications.md)。
+通知渠道矩阵、minimal/advanced key 分层、`--check-notify` 诊断口径和场景化配置说明见 [通知专题文档](notifications.md)。
 
 ### 企业微信
 

docs/full-guide_EN.md

@@ -69,7 +69,7 @@ Go to your forked repo → `Settings` → `Secrets and variables` → `Actions`
 
 #### Notification Channels (Multiple can be configured, all will receive notifications)
 
-> The notification baseline, minimal/advanced key split, Actions mapping, `--check-notify` CLI behavior, and Web one-click notification test are tracked in [Notification Baseline](notifications.md). A complete English notification topic remains a later follow-up.
+> The notification channel matrix, minimal/advanced key split, generated Actions mapping, `--check-notify` CLI behavior, Web one-click notification test, and local / Docker / GitHub Actions / Desktop setup notes are tracked in [Notification Guide](notifications.md).
 
 | Secret Name | Description | Required |
 |------------|------|:----:|
@@ -207,7 +207,7 @@ Default schedule: Every weekday at **18:00 (Beijing Time)** automatic execution.
 
 ### Notification Channel Configuration
 
-For the P0 notification baseline and diagnostics, see [Notification Baseline](notifications.md).
+For the notification baseline, diagnostics, and deployment notes, see [Notification Guide](notifications.md).
 
 | Variable | Description | Required |
 |--------|------|:----:|
@@ -589,7 +589,7 @@ crontab -e
 
 ## Notification Channel Configuration
 
-The P0 notification channel matrix and `--check-notify` CLI details are documented in [Notification Baseline](notifications.md).
+The notification channel matrix and `--check-notify` CLI details are documented in [Notification Guide](notifications.md).
 
 ### WeChat Work
 

docs/notifications.md

@@ -1,6 +1,6 @@
 # 通知能力基线
 
-本文档记录通知能力 P0-P6-D 基线：渠道、配置 key、GitHub Actions 映射、Web 设置元数据、CLI 诊断口径、Web 一键测试、自定义 Webhook Body 模板语义、通知路由策略、降噪机制、聚合报告失败隔离、ntfy / Gotify 一等渠道，以及 WebPush / Apprise 评估。P0 只做基线与只读诊断；P1 增加 Web 单渠道真实测试；P2 产品化现有 Body 模板；P3 增加 report / alert / system_error 路由；P4 增加进程内降噪；P5 强化测试诊断和聚合报告逐渠道失败隔离；P6-A 新增 ntfy；P6-C 新增 Gotify；P6-D 只评估 WebPush / Apprise，不新增运行时依赖、配置入口、per-URL 模板、跨进程持久化、真实每日摘要或重试循环。
+本文档记录通知能力 P0-P7 终态：渠道、配置 key、GitHub Actions 映射、Web 设置元数据、CLI 诊断口径、Web 一键测试、自定义 Webhook Body 模板语义、通知路由策略、降噪机制、聚合报告失败隔离、ntfy / Gotify 一等渠道、WebPush / Apprise 评估，以及本地 / Docker / GitHub Actions / Desktop 场景化配置说明。P0 只做基线与只读诊断；P1 增加 Web 单渠道真实测试；P2 产品化现有 Body 模板；P3 增加 report / alert / system_error 路由；P4 增加进程内降噪；P5 强化测试诊断和聚合报告逐渠道失败隔离；P6-A 新增 ntfy；P6-C 新增 Gotify；P6-D 只评估 WebPush / Apprise；P7 收口文档与 Actions env 对照表自动化，不新增运行时依赖、配置入口、per-URL 模板、跨进程持久化、真实每日摘要或重试循环。
 
 ## 渠道基线
 
@@ -35,35 +35,56 @@
 
 ## GitHub Actions 映射
 
-仓库自带 `.github/workflows/daily_analysis.yml` 只显式导入固定变量名。P0 补齐以下已存在发送链路所需的映射：
+仓库自带 `.github/workflows/daily_analysis.yml` 只显式导入固定变量名。P0/P3/P4/P6 已把 Body 模板、安全项、PushPlus topic、路由、降噪、ntfy 和 Gotify 等通知 key 纳入默认 workflow。下面的表格由 `scripts/generate_notification_actions_env_table.py` 从 workflow `env:` 和通知诊断元数据生成，避免手写对照表和真实 Actions 映射继续漂移。
 
-- `CUSTOM_WEBHOOK_BODY_TEMPLATE`
-- `WEBHOOK_VERIFY_SSL`
-- `FEISHU_WEBHOOK_SECRET`
-- `FEISHU_WEBHOOK_KEYWORD`
-- `PUSHPLUS_TOPIC`
+<!-- notification-actions-env-table:start -->
 
-P3 补齐以下通知路由映射：
-
-- `NOTIFICATION_REPORT_CHANNELS`
-- `NOTIFICATION_ALERT_CHANNELS`
-- `NOTIFICATION_SYSTEM_ERROR_CHANNELS`
-
-P4 补齐以下通知降噪映射：
-
-- `NOTIFICATION_DEDUP_TTL_SECONDS`
-- `NOTIFICATION_COOLDOWN_SECONDS`
-- `NOTIFICATION_QUIET_HOURS`
-- `NOTIFICATION_TIMEZONE`
-- `NOTIFICATION_MIN_SEVERITY`
-- `NOTIFICATION_DAILY_DIGEST_ENABLED`
-
-P6-A / P6-C 补齐以下 ntfy / Gotify 渠道映射：
-
-- `NTFY_URL`
-- `NTFY_TOKEN`
-- `GOTIFY_URL`
-- `GOTIFY_TOKEN`
+| Key | Tier | Channel / feature | Actions source | Default |
+| --- | --- | --- | --- | --- |
+| `WECHAT_WEBHOOK_URL` | minimal | wechat | Secret | - |
+| `WECHAT_MSG_TYPE` | advanced | wechat | Variable or Secret | `markdown` |
+| `FEISHU_WEBHOOK_URL` | minimal | feishu | Secret | - |
+| `FEISHU_WEBHOOK_SECRET` | advanced | feishu | Secret | - |
+| `FEISHU_WEBHOOK_KEYWORD` | advanced | feishu | Variable or Secret | - |
+| `TELEGRAM_BOT_TOKEN` | minimal | telegram | Secret | - |
+| `TELEGRAM_CHAT_ID` | minimal | telegram | Secret | - |
+| `TELEGRAM_MESSAGE_THREAD_ID` | advanced | telegram | Secret | - |
+| `EMAIL_SENDER` | minimal | email | Variable or Secret | - |
+| `EMAIL_PASSWORD` | minimal | email | Secret | - |
+| `EMAIL_RECEIVERS` | advanced | email | Variable or Secret | - |
+| `EMAIL_SENDER_NAME` | advanced | email | Variable or Secret | `daily_stock_analysis股票分析助手` |
+| `PUSHOVER_USER_KEY` | minimal | pushover | Secret | - |
+| `PUSHOVER_API_TOKEN` | minimal | pushover | Secret | - |
+| `NTFY_URL` | minimal | ntfy | Secret | - |
+| `NTFY_TOKEN` | advanced | ntfy | Secret | - |
+| `GOTIFY_URL` | minimal | gotify | Secret | - |
+| `GOTIFY_TOKEN` | minimal | gotify | Secret | - |
+| `PUSHPLUS_TOKEN` | minimal | pushplus | Secret | - |
+| `PUSHPLUS_TOPIC` | advanced | pushplus | Variable or Secret | - |
+| `CUSTOM_WEBHOOK_URLS` | minimal | custom | Secret | - |
+| `CUSTOM_WEBHOOK_BEARER_TOKEN` | advanced | custom | Secret | - |
+| `CUSTOM_WEBHOOK_BODY_TEMPLATE` | advanced | custom | Variable or Secret | - |
+| `WEBHOOK_VERIFY_SSL` | advanced | ntfy, gotify, custom, astrbot | Variable or Secret | `true` |
+| `DISCORD_WEBHOOK_URL` | minimal | discord | Secret | - |
+| `DISCORD_BOT_TOKEN` | minimal | discord | Secret | - |
+| `DISCORD_MAIN_CHANNEL_ID` | minimal | discord | Secret | - |
+| `ASTRBOT_URL` | minimal | astrbot | Secret | - |
+| `ASTRBOT_TOKEN` | advanced | astrbot | Secret | - |
+| `SERVERCHAN3_SENDKEY` | minimal | serverchan3 | Secret | - |
+| `SLACK_WEBHOOK_URL` | minimal | slack | Secret | - |
+| `SLACK_BOT_TOKEN` | minimal | slack | Secret | - |
+| `SLACK_CHANNEL_ID` | minimal | slack | Secret | - |
+| `NOTIFICATION_REPORT_CHANNELS` | advanced | routing | Variable or Secret | - |
+| `NOTIFICATION_ALERT_CHANNELS` | advanced | routing | Variable or Secret | - |
+| `NOTIFICATION_SYSTEM_ERROR_CHANNELS` | advanced | routing | Variable or Secret | - |
+| `NOTIFICATION_DEDUP_TTL_SECONDS` | advanced | noise | Variable or Secret | `0` |
+| `NOTIFICATION_COOLDOWN_SECONDS` | advanced | noise | Variable or Secret | `0` |
+| `NOTIFICATION_QUIET_HOURS` | advanced | noise | Variable or Secret | - |
+| `NOTIFICATION_TIMEZONE` | advanced | noise | Variable or Secret | - |
+| `NOTIFICATION_MIN_SEVERITY` | advanced | noise | Variable or Secret | - |
+| `NOTIFICATION_DAILY_DIGEST_ENABLED` | advanced | noise | Variable or Secret | `false` |
+
+<!-- notification-actions-env-table:end -->
 
 默认 workflow 仍不映射 `MARKDOWN_TO_IMAGE_CHANNELS` 与 `MERGE_EMAIL_NOTIFICATION`。它们是发送形态或聚合行为开关，不是渠道凭证；在 Actions 中自动开始读取同名 Secret/Variable 会引入额外行为变化。
 
@@ -230,9 +251,37 @@ Apprise 后续如要引入，应先作为可选依赖评估，而不是默认依
 - 发送失败应隔离在 Apprise 渠道内，不能影响已有渠道的失败隔离语义。
 - 如果采用 Apprise，建议先新增单独 experimental channel 或 CLI-only spike，再决定是否纳入 Web 设置页和 Actions env。
 
-## 场景占位
+## 本地配置
+
+本地运行优先使用项目根目录 `.env`。复制 `.env.example` 后填写至少一个 minimal key 即可启用对应静态通知渠道；advanced key 只改变认证、安全、格式、路由或降噪行为，不会单独启用渠道。
+
+```bash
+python main.py --check-notify
+```
+
+`--check-notify` 是只读诊断：不发送通知、不写 `.env`、不进入分析流程。配置好 WebUI 后，也可以在系统设置页用单渠道测试发送真实测试消息；该测试只使用页面草稿临时配置，不保存 `.env`。
+
+## Docker
+
+Docker 场景可通过 `--env-file .env` / Compose `env_file` 注入运行时环境变量，也可以挂载 `.env` 让 Web 设置页和后端读写同一份配置文件。只注入环境变量但不挂载 `.env` 时，Web 设置页保存后的值在容器重启后可能被部署环境再次覆盖。
+
+降噪静默时段建议显式配置 `NOTIFICATION_TIMEZONE`，避免容器默认时区与预期不一致。自签名内网 webhook 可临时使用 `WEBHOOK_VERIFY_SSL=false`，但不要在公网链路关闭证书校验。
+
+## GitHub Actions
+
+默认 `daily_analysis.yml` 只读取表格中显式映射的 Secret / Variable。新增 repository Secret 或 Variable 后，只有变量名已经出现在 workflow `env:` 中才会进入运行进程；`STOCK_GROUP_N` / `EMAIL_GROUP_N` 这类任意编号变量不会自动导入。
+
+Secret 适合 token、password、webhook URL 等敏感项；Variable 适合 `WECHAT_MSG_TYPE`、`EMAIL_SENDER_NAME`、路由、降噪窗口和时区这类非敏感行为配置。`MARKDOWN_TO_IMAGE_CHANNELS` 与 `MERGE_EMAIL_NOTIFICATION` 默认不映射，如需在自己的 fork 中使用，应显式修改 workflow 并补充对应测试。
+
+## Desktop
+
+桌面端复用 Web 设置页的通知配置和单渠道测试入口。通知测试会发送真实测试消息，但只使用当前页面草稿值，不会自动保存；需要持久化时仍需点击保存配置。
+
+桌面端可通过配置导出 / 导入恢复 `.env`。回滚某个通知渠道时，清空该渠道 minimal key 并保存即可；advanced key 留存不会单独启用渠道，但建议同步清理以减少后续排障噪音。
+
+## 回滚方式
 
-- Local：优先使用 `.env`，可用 `python main.py --check-notify` 做本地诊断。
-- Docker：配置来源与本地一致，需确保容器环境变量已注入。
-- GitHub Actions：只会读取 workflow `env:` 中显式映射的 Secret/Variable。
-- Desktop：桌面端内嵌 Web 设置页可复用同一通知测试入口；测试仍只使用临时配置，不写入 `.env`。
+- 本地 / Docker：恢复旧 `.env`，或删除对应渠道 minimal key 后重启进程。
+- GitHub Actions：清空或删除对应 Secret / Variable；未映射的 key 不会进入 workflow 运行进程。
+- Desktop：使用配置备份导入旧 `.env`，或在设置页清空对应渠道配置并保存。
+- 版本回退：P6/P7 新增的 `NTFY_*`、`GOTIFY_*`、路由和降噪 key 在旧版本中会被忽略；若要避免误导，应同时从 `.env` 或 Actions 配置中移除。