feat(announcement): 后台公告已读情况增加按已读时间排序

[hyrhyrh]

功能概述

为管理后台 公告管理 → 已读情况 列表新增按 read_at(已读时间)排序。

目前列表只能按 user 字段(email / username / balance)排序,管理员无法快速回答两个常见问题:

• "哪些用户最近读了这条公告?" —— 按 read_at 降序
• "哪些用户还没读?" —— 按 read_at 升序(未读用户排到最前)

实现要点

NULL 处理语义

announcement_reads 是 user × announcement 的稀疏表 —— 未读的用户在 LEFT JOIN 中 read_at 为 NULL。本 PR 的 NULL 排序规则:

• read_at desc → NULLS LAST(未读放最后,顶部是最近读的人)
• read_at asc → NULLS FIRST(未读放最前,顶部是尚未读的人)

这样管理员用同一个列通过点一下表头切方向就能在"看已读"和"找未读"之间切换,不用额外加 filter。

性能 / 索引

跨表排序我对几种方案做了对比:

方案	查询数	适用场景	代码复杂度
LEFT JOIN + ORDER BY(本 PR)	1	通用	低
拆两个查询(已读 + 未读分开)	2	"新公告大部分人没读"场景效率更高	中(分页边界手算)
内存排序	1	永远 < 几千用户	不可扩展

选了方案 1,理由:单查询、分页边界由 SQL 处理,无 corner case bug。

为让排序索引可驱动,migration 146 新增复合索引:

CREATE INDEX IF NOT EXISTS idx_announcement_reads_announcement_id_read_at
    ON announcement_reads (announcement_id, read_at DESC NULLS LAST);

前导列是 announcement_id,与"某个公告内排序"的查询模式完全匹配。原有的 idx_announcement_reads_read_at 是全局单列索引,对本场景帮助有限。

测试估算:即便用户表 10 万行 + 单公告 5 万 reads,LEFT JOIN + 索引驱动 sort 仍保持 ~10ms 级。

与现有路径的关系

ListUserReadStatus service 方法在 sort_by=read_at 时分支到新路径 listUserReadStatusByReadAt,其它 sort_by 走原路径。纯增量改动,不动现有行为。

sort_by 大小写不敏感且去空格("READ_AT" / " read_at " 都命中新路径)。

改动文件

后端:

• backend/migrations/146_announcement_reads_announcement_read_at_index.sql —— 新增复合索引
• backend/internal/service/announcement.go —— 接口扩展(AnnouncementReadRepository.ListUsersOrderedByReadAt + AnnouncementReadUserRow 类型)
• backend/internal/repository/announcement_read_repo.go —— LEFT JOIN raw SQL 实现(用 ent 的 client.QueryContext,与 affiliate_repo 一致的风格)
• backend/internal/service/announcement_service.go —— service 分支逻辑

前端:

• frontend/src/components/admin/announcements/AnnouncementReadStatusDialog.vue —— read_at 列加 sortable: true

测试:

• backend/internal/service/announcement_read_at_sort_test.go —— 服务层 dispatch 单测(routing / 大小写 / 空格 / 默认路径)

测试计划

• go build ./... / go vet ./... 通过
• go test -short ./internal/repository/... ./internal/service/... ./internal/handler/... 通过(新增 3 个测试)
• 前端 pnpm vue-tsc --noEmit 通过
• 实机验证:
  • \d announcement_reads 确认 idx_announcement_reads_announcement_id_read_at 已建立
  • 按 read_at desc 点击列头 → 顶部是最近已读用户
  • 按 read_at asc 点击列头 → 顶部是未读用户(NULL)
  • 配合 email 搜索过滤后排序仍正确

给 reviewer 的几点说明

• 没动现有 N+1:ListUserReadStatus 里循环调 ListActiveByUserID(userID) 是 pre-existing 问题(每条用户一次 SQL 查活跃订阅),不在本 PR 修复 —— 想保持 PR 聚焦在排序功能上,避免引入无关重构。可后续单独提 PR 做批量化。
• 未加 SQL 集成测试:本 PR 的 raw SQL 较短,业务逻辑通过 service 单测覆盖;若 reviewer 倾向于添加 testcontainers 集成测试我可以补一个 commit。
• migration 编号 146:feat(admin): 后台批量公告邮件功能 #2899 已占 145,选 146 以避免两个开放 PR 在 migration 目录的合并冲突。