eryao/.trellis/tasks/archive/2026-04/04-16-fix-notification-targets-cleanup/prd.md

PRD: 修复通知 targets 约束、合并注册脚本、路径缩短及清理重复索引

Task: 04-16-fix-notification-targets-cleanup Branch: worktree/fix-notification-targets-cleanup Status: planning

---

背景与动机

当前代码库存在四类独立但可并行修复的问题：

1. 数据库重复索引 — llm_factory.name 和 llms.model_code 各有两个功能完全相同的 unique index，浪费存储并拖慢写入。
2. 脚本碎片化 — register-notifications.sh 作为独立脚本存在，但其功能本质上是 dev-migrate.sh 的一个子命令（与 migrate / init-data 并列），且未被 bootstrap 覆盖。
3. 路径冗余 — backend/src/core/config/static/notification/notifications 存在两层嵌套的 notification，可缩短为 backend/src/core/config/static/notifications。
4. targets 语义缺失 — 通知 YAML 中的 targets.mode 仅支持 all_users 和 user_ids，缺少对"新用户"和"已存在用户"的精确语义区分，且当前 link_published_notifications_to_user 在用户注册时无差别地关联所有 published 通知，无法满足"只推给新注册用户"的需求。

---

任务 1：清理数据库重复索引

现状分析

数据库中确认存在以下重复索引（通过 pg_indexes 查询确认）：

表	冲突索引	列	类型
llm_factory	ix_llm_factory_name vs llm_factory_name_key	name	UNIQUE BTREE
llms	ix_llms_model_code vs llms_model_code_key	model_code	UNIQUE BTREE

根因：Alembic migration 20260411_0001 同时定义了 UniqueConstraint("name")（自动生成 *_key）和 op.create_index("ix_*", ..., unique=True)，导致两个相同功能的索引。

实现方案

1. 创建新 Alembic migration，drop 冗余索引：
   • llm_factory: 保留 llm_factory_name_key（UniqueConstraint 自动生成的），drop ix_llm_factory_name
   • llms: 保留 llms_model_code_key，drop ix_llms_model_code
2. 在 migration 的 downgrade() 中恢复被 drop 的索引。
3. 更新 20260411_0001 migration 的 downgrade() 中对应的 drop_index 调用，改为 drop 保留的那个索引名（因为 ix_* 将不再存在）。
4. ORM model 中 unique=True 已在 mapped_column 上声明，不需要改动。

涉及文件

• backend/alembic/versions/ — 新增 migration
• backend/alembic/versions/20260411_0001_initial_llm_schema.py — 修正 downgrade

---

任务 2：将 register-notifications.sh 合并到 dev-migrate.sh

现状分析

• infra/scripts/register-notifications.sh：加载 env 后调用 python -m core.runtime.cli sync-notifications "$@"
• infra/scripts/dev-migrate.sh：支持 migrate、init-data、bootstrap 三个子命令
• backend/src/core/runtime/cli.py：main() 已支持 sync-notifications 命令
• bootstrap() 函数（cli.py:86）仅执行 migrate + init-data，不含 sync-notifications

实现方案

1. 修改 dev-migrate.sh：添加 sync-notifications 子命令，透传所有参数给 CLI
2. 修改 dev-migrate.sh 的 bootstrap 子命令：使其在 migrate + init-data 之后也执行 sync-notifications
3. 修改 cli.py 的 bootstrap() 函数：在 run_init_data() 之后调用 run_sync_notifications()
4. 删除 infra/scripts/register-notifications.sh
5. 更新 usage 文本

涉及文件

• infra/scripts/dev-migrate.sh — 添加子命令，修改 bootstrap
• backend/src/core/runtime/cli.py — 修改 bootstrap() 和 main()
• infra/scripts/register-notifications.sh — 删除

---

任务 3：缩短 notification 配置路径

现状分析

当前路径：backend/src/core/config/static/notification/notifications/welcome_points.yaml

目录结构：

backend/src/core/config/static/notification/
├── __init__.py
├── static_schema.py
├── static_sync.py
└── notifications/
    ├── README.md
    └── welcome_points.yaml

目标路径：backend/src/core/config/static/notifications/welcome_points.yaml

同时 backend/src/core/config/notification/ 包（Python package）需要重新审视命名：

• 该 package 本身只有 __init__.py、static_schema.py、static_sync.py 三个文件
• package 名 notification 和 YAML 目录 notifications 容易混淆

实现方案

1. 重命名目录：将 backend/src/core/config/static/notification/notifications/ 移动到 backend/src/core/config/static/notifications/
2. 更新 utils/paths.py：get_notification_config_dir() 返回 get_static_config_dir() / "notifications"
3. 保留 backend/src/core/config/notification/ package 不变（这是 Python 代码 package，不是配置目录）
4. 删除空出来的 backend/src/core/config/static/notification/ 目录（仅含 notifications/ 子目录）
5. 更新 README.md 的路径引用（如果有）

涉及文件

• backend/src/core/config/static/notification/notifications/ → backend/src/core/config/static/notifications/ (git mv)
• backend/src/utils/paths.py — 修改 get_notification_config_dir()
• backend/src/core/config/static/notification/ — 删除空目录

---

任务 4：通知 targets 语义约束与按用户类型分发

现状分析

当前 StaticNotificationTargets schema（static_schema.py:32）：

mode: Literal["all_users", "user_ids"]
user_ids: list[UUID] | None = None

当前 YAML（welcome_points.yaml）：

targets:
  mode: all_users

当前注册流程（auth/router.py:80-83）：

notification_service = NotificationService(NotificationRepository(session))
linked_count = await notification_service.link_published_notifications_to_user(
    user_id=UUID(result.user.id)
)

link_published_notifications_to_user 无差别地将所有 published 状态的通知关联到新注册用户，不区分 target mode。

register_bonus_claims 表：通过 email_hash 记录首次注册奖励 claim。如果该邮箱已 claim 过，说明用户是"重新注册"的。

需求定义

targets mode 扩展为三种语义：

mode	含义	新用户注册时	已有用户（sync 时）
new_users	仅推送给首次注册用户	注入	不推送
exist_users	仅推送给已存在的用户	不注入	推送
all_users	所有用户	注入	推送

关键判断逻辑：

• "新用户"vs"重新注册用户"通过查询 register_bonus_claims 表判断
  • 如果该用户 email 在 register_bonus_claims 中已有记录且 first_user_id_snapshot != 当前 user_id，则为重新注册用户
• new_users：仅首次注册（register_bonus_claims 中无记录）的用户
• exist_users：已存在于数据库的用户（非注册时注入，而是通过 sync-notifications 或其他方式推送）

实现方案

4.1 扩展 StaticNotificationTargets schema

class StaticNotificationTargets(BaseModel):
    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")

    mode: Literal["new_users", "exist_users", "all_users", "user_ids"]
    user_ids: list[UUID] | None = None

    @model_validator(mode="after")
    def validate_target_mode(self) -> StaticNotificationTargets:
        if self.mode in ("new_users", "exist_users", "all_users") and self.user_ids is not None:
            raise ValueError("targets.user_ids must be absent when mode is not user_ids")
        if self.mode == "user_ids":
            if self.user_ids is None or len(self.user_ids) == 0:
                raise ValueError("targets.user_ids must be a non-empty list when mode=user_ids")
        return self

4.2 修改 welcome_points.yaml

targets:
  mode: new_users

4.3 修改注册时通知分发逻辑

在 auth/router.py 的 create_email_session 中，替换当前的 link_published_notifications_to_user 调用：

• 查询所有 published 状态且未删除的通知
• 对每条通知，根据其 targets.mode 决定是否关联：
  • all_users：始终关联
  • new_users：仅在用户是首次注册时关联（通过 register_bonus_claims 判断）
  • exist_users：注册时不关联（此 mode 仅供 sync-notifications 使用）
  • user_ids：如果 user_id 在列表中则关联

判断是否首次注册：复用 PointsService 的逻辑，通过 register_bonus_claims 表的 email_hash 查询是否已有 claim 记录。但需要注意时序——注册 bonus claim 和通知关联在同一个事务中。需要：

• 在 grant_register_bonus_if_eligible 之后判断该 claim 的结果
• 如果 granted=True，说明是首次注册 → 新用户
• 如果 granted=False 且 claim 已存在 → 重新注册用户

具体方案：让 grant_register_bonus_if_eligible 返回的结果已经包含判断信息（当前返回 RegisterBonusResult），可以用 granted 字段推断。但更精确的做法是在 RegisterBonusResult 中添加 is_first_registration: bool 字段。

或者更简洁：在 NotificationRepository 中新增方法 link_notifications_for_new_user，接收 is_first_registration: bool 参数，按 target mode 过滤通知后关联。

4.4 修改 static_sync.py 的 _resolve_target_user_ids

当前 all_users mode 返回所有 AuthUser.id。需要根据新语义调整：

• all_users：返回所有 auth users
• new_users：返回在 register_bonus_claims 中没有 claim 记录的用户的 first_user_id_snapshot（首次注册的用户）
• exist_users：返回所有 auth users 减去 new_users
• user_ids：保持不变

4.5 通知与 target mode 的关联方式

通知的 target mode 存储在 YAML 中，但 sync 到数据库时 Notification 表本身没有 target_mode 字段。需要：

• 方案 A：在 notifications 表中添加 target_mode 列，sync 时写入
• 方案 B：每次分发时重新读取 YAML 配置

推荐 方案 A，因为：

1. 分发逻辑（注册、sync）需要高效查询，不应每次都读文件
2. target mode 是通知的固有属性，应持久化

实现步骤清单

1. 在 notifications 表新增 target_mode 列（Alembic migration）
2. 更新 Notification ORM model，添加 target_mode 字段
3. 更新 StaticNotificationTargets.mode 的 Literal 类型，加入 new_users 和 exist_users
4. 更新 StaticNotificationDefinition 或 sync 逻辑，将 target_mode 写入 Notification 记录
5. 修改 welcome_points.yaml 的 targets.mode 为 new_users
6. 在 NotificationRepository 中新增 link_notifications_for_registered_user 方法
7. 修改 auth/router.py 注册流程，使用新的分发逻辑
8. 更新 _resolve_target_user_ids 以支持新的 mode 语义

涉及文件

• backend/alembic/versions/ — 新增 migration（notifications.target_mode）
• backend/src/models/notification.py — 添加 target_mode 字段
• backend/src/core/config/notification/static_schema.py — 扩展 StaticNotificationTargets
• backend/src/core/config/notification/static_sync.py — sync 时写入 target_mode，修改 _resolve_target_user_ids
• backend/src/core/config/static/notifications/welcome_points.yaml — mode 改为 new_users
• backend/src/v1/notifications/repository.py — 新增按 target_mode 过滤的关联方法
• backend/src/v1/notifications/service.py — 新增服务方法
• backend/src/v1/auth/router.py — 修改注册流程调用

---

执行顺序

四个任务相互独立，按风险从低到高执行：

1. 任务 1（重复索引清理）— 风险最低，纯 DDL
2. 任务 3（路径缩短）— 低风险，文件移动 + 一行代码修改
3. 任务 2（脚本合并）— 低风险，脚本层修改 + 删除文件
4. 任务 4（targets 语义）— 中风险，涉及 schema 变更、DB migration、业务逻辑修改

---

验证策略

• 任务 1：迁移后查询 pg_indexes 确认冗余索引已删除
• 任务 2：运行 ./infra/scripts/dev-migrate.sh sync-notifications --dry-run 验证子命令可用；运行 ./infra/scripts/dev-migrate.sh bootstrap 验证包含通知同步
• 任务 3：运行 sync-notifications 验证 YAML 加载路径正确
• 任务 4：
  • 单元测试：StaticNotificationTargets 的验证逻辑（new_users/exist_users/all_users/user_ids）
  • 集成测试：新用户注册时只收到 new_users + all_users 通知
  • 集成测试：重新注册用户不收到 new_users 通知
  • sync-notifications 按 target_mode 正确分发

---

不在范围内

• 前端通知展示逻辑变更
• 通知的推送（push notification）机制
• 通知模板引擎或多语言支持