App 状态监控系统

本文档介绍系统三大核心机制：定时任务、状态管理、通知。帮助你理解数据从哪来、状态怎么算、通知何时发。文档仅管理员可见。

① 定时任务

系统的定时能力分两类：后台系统任务（内置、自动运行，无需配置）和用户自定义定时任务（你在「⏰ 定时任务」里手动创建）。所有定时逻辑由一个每分钟触发一次的 Cron 统一驱动。

A. 后台系统任务（自动运行）

每分钟触发时，系统按顺序执行以下后台任务。它们都采用「分片 / 分级」策略——每次只处理少量到期对象，把负载摊平到时间线上，避免定时点雪崩，也避免触发 Apple 接口限流。

任务	作用	频率 / 触发条件
用户自定义任务	到点检查关联 App 的版本 / 状态，有变更则更新入库并推送到任务频道	按每个任务的 Cron 表达式
自动分级刷新	按账号「活跃度档位」自动刷新账号下 App 的状态（见下方档位表）	活跃 1 小时 / 一般 6 小时 / 较冷 每周 / 冷冻 每月
销售报表分片预同步	提前拉取销售报表，报表页即读即得、无需现拉	约每 12 小时 / 账号（需配置 Vendor Number）
下载来源同步	同步 Analytics 下载来源数据	约每 20 小时 / App（需开启「获取下载来源」）
可下载性监控同步	计算「中国大陆销售 / 是否可下载」两列	处理中 10 分钟 / 常规 30 分钟 / 终态 7 天兜底（需开启自动同步）
日志清理	删除过期日志（保留 30 天，并有总行数上限）	每天凌晨 3:00（北京时间）

💡 活跃度分级刷新：系统按账号「距上次实质变化的天数」判定档位，越活跃刷得越勤，越冷越省——既保证及时性又节约 Apple 接口调用。

档位	判定条件（距上次变化）	自动刷新间隔
活跃（hot）	7 天内有变化	每 1 小时
一般（warm）	7 ~ 90 天	每 6 小时
较冷（cold）	90 ~ 180 天	每周
冷冻（frozen）	180 天以上	每月

B. 用户自定义定时任务（手动创建）

1. 进入「⏰ 定时任务」，新建任务：填写名称、Cron 表达式（决定执行时间）、通知频道 / 群组。
2. 到「📦 App 管理」把要监控的 App 关联到该任务（可单个设置，或勾选多个后用批量「定时任务」）。
3. Cron 到点时，任务会实时查询这些 App 的最新版本 / 审核状态，只有发生变化才更新数据库、写入日志，并把变更汇总推送到任务频道。

📌 Cron 表达式为标准 5 段格式：分 时 日 月 周。例：0 9 * * * = 每天 09:00；*/30 * * * * = 每 30 分钟；0 * * * * = 每小时整点。

② 状态管理

系统围绕两个维度描述一个 App：App 状态（审核 / 发布进度） 和 地区可下载性（当前只判中国大陆）。两者相互独立，展示在不同列。

A. App 状态（App statuses）

反映 App / 版本的整体审核与发布进度，取值来自 App Store Connect。常见状态与中文对照：

状态	含义	是否可下载（仅按 App 状态维度）
PREPARE_FOR_SUBMISSION	准备提交	否（从未上架）
WAITING_FOR_REVIEW / IN_REVIEW	等待审核 / 审核中	看是否有历史已发布版本
PENDING_DEVELOPER_RELEASE	待开发者发布	看是否有历史已发布版本
READY_FOR_DISTRIBUTION / READY_FOR_SALE	已上架 / 可供销售	是（已发布）
REJECTED / METADATA_REJECTED / DEVELOPER_REJECTED	被拒 / 元数据被拒 / 开发者撤回	看是否有历史已发布版本
REMOVED_FROM_SALE	已下架（App 级）	否
DEVELOPER_REMOVED_FROM_SALE	开发者主动下架	否

💡 关键点：一个 App 是否可下载，主要看它是否存在一个「已发布」的版本。新版本正在审核 / 被拒时，只要旧版本仍是已上架，用户依然能下载旧版本。

B. 中国大陆「销售状态」与「是否可下载」（两列）

在「App 管理」和「账号 → 查看 App」列表里，中国大陆用两列表达，二者含义不同：

列	是什么	取值
中国大陆销售	Apple 归一化后的地区销售态（你手动设的可售开关 + 苹果自动施加的限制 综合而来）	可售 / 不可销售 / 未上架 / 预售 / 处理中 / 发布后可售
是否可下载	系统综合判定的最终结论；旁边「?」可查看判定原因、置信度与四维明细	🟢 可下载(版本号) / 🔴 不可下载

• 销售状态是「输入」，可下载是「最终结论」。例：你把「中国大陆可售」开关打开了（已设为可售=是），但苹果侧返回 CANNOT_SELL（如 ICP 备案 / 资质问题），最终仍判「不可下载」，原因显示 CANNOT_SELL。
• 不可销售 = 苹果侧禁止销售；未上架 = 你没在该地区开启销售。二者不同。
• 可下载时括号内显示实际可下载的版本号；若它与最新版本不同（如最新 1.1 审核中、1.0 仍可下载），版本号会橙色高亮提示。
• 检测地区可在「⚙️ 全局配置 → 可下载性检测地区」切换（单选，默认中国大陆）。

C. 状态数据从哪来 / 何时更新

来源	说明
手动「查看账号 / 刷新」	立即向 Apple 拉取，并顺带实时检测中国大陆可售性（并发加速）
后台自动分级刷新	按活跃度档位定期刷新（见上表）
Webhook 实时推送	Apple 主动推送版本状态变更，秒级同步入库
用户定时任务	按 Cron 检查关联 App 是否有变化

③ 通知

系统有四条相互独立的通知链路，均通过 Telegram 推送。请先在「✈️ Telegram 管理」配置好机器人与频道 / 群组。

通知链路	触发来源	在哪配置
Webhook 实时通知	Apple 主动推送的事件（最及时）	🔔 Webhook 通知（每个 Webhook 独立配置）
后台轮询变更通知	分级刷新 / 按状态刷新 / 手动刷新时检测到版本或状态变化	⚙️ 全局配置 → 状态轮询变更通知频道
用户定时任务通知	任务 Cron 到点且关联 App 有变化	⏰ 定时任务（每个任务选频道）
可下载性事件通知	中国大陆上架 / 下架事件	⚙️ 全局配置 → 可下载性通知频道

Webhook 精细化通知（A/B 过滤）

一个 Webhook 可绑定多个频道 / 群组，每个频道可单独选择接收哪些「版本状态变更」。状态变更按迁移方向分两类：

• 进入 (A 类：任意 → 目标)：当状态变为你勾选的目标状态时通知（判断新状态 newValue）。例：勾选「已上架」= App 一旦上架就通知。
• 离开 (B 类：目标 → 任意)：当状态离开你勾选的目标状态时通知（判断旧状态 oldValue）。例：勾选「已上架」= App 一旦从上架变成别的（下架 / 重新审核）就通知。

📐 判定规则：进入(A) 命中 或 离开(B) 命中，即发送（两者取并集）。每个频道至少合计勾选 1 个状态；默认全选 = 收到所有变更。一次事件即便同时命中 A 和 B，对同一频道也只发一条，不会重复。

• 提供预设按钮快速勾选：全选 / 清空 / 上线 / 被拒·异常 / 下架 / 审核进度。
• 非「版本状态变更」类事件（如构建上传、Beta 测试）不做 A/B 过滤，会发给该 Webhook 的所有订阅频道。
• 若 Apple 推来一个系统未收录的新状态，会照常通知（宁可多发、不漏报）。
• 批量订阅（App 管理页批量「Webhook」）和全局自动 Webhook（新账号自动创建）也都支持同样的 A/B 选择。

创建 Webhook 的步骤

1. 确保已配置服务公网地址（PUBLIC_BASE_URL），否则 Apple 无法回调。
2. 「🔔 Webhook 通知」→ 新增，选择账号与要监听的 App、订阅的事件类型。
3. 添加一个或多个通知频道，为每个频道设置「进入(A) / 离开(B)」接收范围（默认全选）。
4. 保存后系统会自动在 Apple 端注册回调；之后状态变更会实时推送。

④ 常见问题

• 为什么「已设为可售=是」却显示不可下载？ 因为苹果侧返回了阻断状态（如 CANNOT_SELL / ICP 备案缺失），其优先级高于你的可售开关，实际用户无法下载。点「?」可看具体原因。
• Webhook 和轮询 / 定时任务的区别？ Webhook 是 Apple 主动推、最及时；轮询与定时任务是系统定期主动查、作为兜底与补充。三者通知频道相互独立，便于区分来源。
• 不想收到太多通知怎么办？ 在 Webhook 的每个频道里，用 A/B 只勾选你关心的状态（如只勾「进入：已上架 / 被拒」），或用预设按钮快速设置。
• 冷账号会不会永远不刷新？ 不会。冷冻档位仍每月刷新一次兜底；你也可以随时手动「查看 / 刷新」强制更新。