feat: 静态通知同步 + 积分审计 JSONB 序列化修复

docs/plans/static-notification-sync-plan.md

@@ -38,9 +38,7 @@
 
 - 系统级离线推送
 - 自动监听文件变化并实时同步
-- 通过文件删除自动删库
 - 复杂运营后台
-- 严格对齐目标用户集合并自动删除既有投递记录
 
 ---
 
@@ -161,6 +159,7 @@ notification:
   body: 你已获得注册奖励，可前往积分中心查看。
 
   payload:
+    deleted: false
     action: open_route
     route: /points
     entity_id: null
@@ -222,6 +221,8 @@ targets:
   - 通知类型，当前默认 `system`
 - `status`
   - `draft/published/revoked`
+- `deleted`
+  - 显式软删除主通知
 - `published_at`
   - 发布时间
 - `title/body/payload`
@@ -239,6 +240,7 @@ targets:
 - `source_key` 必填且全局唯一
 - `version >= 1`
 - `status` 只允许 `draft/published/revoked`
+- `deleted` 为可选布尔值
 - `payload` 必须符合现有通知 payload schema
 - `targets.mode='all_users'` 时不允许传 `user_ids`
 - `targets.mode='user_ids'` 时 `user_ids` 必填且不能为空
@@ -280,22 +282,39 @@ targets:
 
 ### 8.4 统一删除
 
-本阶段不使用“文件消失自动删库”语义。
+本阶段支持两种明确的下线方式：
+
+1. 在 YAML 中显式写 `deleted: true`
+2. 执行同步时使用 `--prune`，将文件中已不存在的静态通知软删除
+
+- `deleted: true` 语义：
+
+- 设置 `notifications.deleted_at`
+- 不删除既有 `user_notifications`
+
+- `--prune` 语义：
+
+- 扫描范围内缺失的静态通知会被软删除
+- 不会删除非 `source='static'` 的通知
+
+默认情况下，不因为文件消失自动删库。
 
 原因：
 
 - 文件误删风险高
 - 容易把版本控制操作误解释为业务删除
 
-如果需要下线，显式通过配置状态控制：
+如果只是想临时停止用户可见，优先用：
 
 - `status: revoked`
 
-如果未来确实需要静态配置触发软删除，再单独增加明确字段，不在本阶段默认启用。
+如果想做统一下线并保留审计主记录，可用：
+
+- `deleted: true`
 
 ### 8.5 目标用户变更
 
-第一阶段采用保守策略：
+默认采用保守策略：
 
 - 新增目标用户时，补插入 `user_notifications`
 - 被移出目标集合的用户，不自动删除既有 `user_notifications`
@@ -305,7 +324,9 @@ targets:
 - 防止误操作删除已投递历史
 - 与“通知一旦发出就保留用户侧记录”的语义更一致
 
-如果未来需要严格对齐文件目标集合，再单独增加显式 `--reconcile-targets` 行为。
+如果执行同步时显式加上 `--reconcile-targets`，则：
+
+- 当前目标集合之外的既有 `user_notifications` 会被删除
 
 ---
 
@@ -377,8 +398,10 @@ PYTHONPATH=backend/src uv run python -m core.runtime.cli sync-notifications
 - `--path`
 - `--source-key`
 - `--dry-run`
+- `--prune`
+- `--reconcile-targets`
 
-第一阶段不默认提供危险的全量清理参数。
+危险行为必须显式开启，不默认启用。
 
 ### 10.2 infra 脚本
 
@@ -399,6 +422,7 @@ infra/scripts/register-notifications.sh
 ./infra/scripts/register-notifications.sh
 ./infra/scripts/register-notifications.sh --dry-run
 ./infra/scripts/register-notifications.sh --source-key welcome_bonus
+./infra/scripts/register-notifications.sh --prune --reconcile-targets
 ```
 
 ---
@@ -435,8 +459,9 @@ infra/scripts/register-notifications.sh
 6. 为通知模块补充按 `source/source_key` 查询与更新能力
 7. 在 `core.runtime.cli` 中新增 `sync-notifications` 命令
 8. 新增 `infra/scripts/register-notifications.sh`
-9. 视需要补充 `notification_updated` Realtime 事件
-10. 编写最小测试和 dry-run 校验
+9. 支持 `--prune` 和 `--reconcile-targets`
+10. 视需要补充 `notification_updated` Realtime 事件
+11. 编写最小测试和 dry-run 校验
 
 ---
 
@@ -447,7 +472,10 @@ infra/scripts/register-notifications.sh
 - [ ] 修改 `title/body/payload` 后，再同步可反映到数据库
 - [ ] 用户侧已读状态在主通知内容更新后保持不变
 - [ ] 将 `status` 改为 `revoked` 后，再同步可使通知在用户列表中失效
+- [ ] 将 `deleted` 改为 `true` 后，再同步可使通知从用户列表和未读数中消失
 - [ ] `--dry-run` 可输出计划变更而不写库
+- [ ] `--prune` 可将文件中已不存在的静态通知软删除
+- [ ] `--reconcile-targets` 可严格对齐目标用户集合
 - [ ] YAML 结构不合法时同步失败，并给出明确错误
 - [ ] 脚本可按全量或按 `source_key` 手动触发同步
 
@@ -461,10 +489,13 @@ infra/scripts/register-notifications.sh
 - 新建通知同步
 - 已有通知更新同步
 - 撤销同步
+- 显式软删除同步
 - 相同 `source_key` 幂等 upsert
 - 更新主通知时不重置 `user_notifications.is_read/read_at`
 - 新增目标用户时补插入接收关系
 - 被移出目标集合时不删除既有接收关系
+- `--reconcile-targets` 下删除多余接收关系
+- `--prune` 下软删除缺失静态通知
 
 脚本至少验证：
 
@@ -479,6 +510,5 @@ infra/scripts/register-notifications.sh
 只有在真实需求出现时，再考虑：
 
 - 用删除文件触发软删除
-- 严格对齐目标用户集合并清理历史接收关系
 - 通过后台页面管理静态通知
 - 将静态通知同步纳入更完整的发布工作流