阅读

docs/后端重构计划-活动信息发布.md

@@ -63,7 +63,7 @@ com.yunhai.familyactivity
 ├── entity/
 │   ├── BaseEntity / SysDict / UpFile / ContactsGroup / ContactsGroupUser   # 保留
 │   ├── Activity               # 新建：活动主表
-│   ├── ActivityRead           # 新建：已读记录（班级粒度）
+│   ├── ActivityRead           # 新建：已读记录（学生粒度）
 │   ├── ActivitySignup         # 新建：回执/报名记录
 │   └── OperationLogRecord     # 新建：操作日志表（参考 UserclassService）
 ├── enums/                     # 新建：ActivityStatusEnum、ReceiptModeEnum、SignupStatusEnum
@@ -175,11 +175,14 @@ com.yunhai.familyactivity
 | --- | --- | --- |
 | id | int 自增 | |
 | activityId | int | 活动 id |
-| classId | varchar(50) | **班级粒度已读**（前端关键约定 4：`classRead`） |
-| account | varchar(50) | 操作账号（家长=学生账号） |
+| classId | varchar(50) | 班级 id |
+| studentId | int | 阅读学生ID（家长端以学生身份打开；学生档案不可得时为 null） |
 | readTime | datetime | 阅读时间 |
 
-唯一约束 `(activity_id, class_id)`；应收/已读人数按班级 `studentCount` 累加（班级与学生数取自 `ClassService`/基础平台接口）。
+唯一约束 `(activity_id, class_id, student_id)`（`uk_activity_class_student`；2026-09-23 由班级粒度 `(activity_id, class_id)`
+迁移而来，SQL 见 `docs/sql/20260923_activity_read_per_student.sql`，`ddl-auto=update` 不会自动改唯一键，各环境需手动执行）。
+**已读人数 = 接收班级内的已读记录条数**（即实际打开过活动的家长数，每个家长一条，重复打开幂等）；
+班级「读/未读」= 该班是否存在任一已读记录；应读人数（allowCount）仍为接收班级学生数之和（取自 `ClassService`/基础平台接口）。
 
 #### `ActivitySignup`（回执/报名记录，表 `fa_activity_signup`）
 
@@ -210,8 +213,8 @@ com.yunhai.familyactivity
 
 1. **发布**（Create）：draft=true 存草稿；否则置已发；`targetClassIds()` 统一解析 `receiveList`（`"ALL"`=全校班级）；发布时按班级×学生**预生成回执记录**（receiptMode≠none 时，status=none），保证「应收人数」「未回执名单」可查。
 2. **状态机**：`actStatus` 推导规则 —— status=草稿→`draft`；now < signupDeadline→`signup`；signupDeadline ≤ now < endTime→`closed`；now ≥ endTime→`finished`（receiptMode=none 时无报名态语义，仅展示）。
-3. **进度统计**（`ActivityProgress`）：`should`=应回执人数；`signed/confirmed/canceled` 按 signup 表 status 计数；`unsigned=should-signed-confirmed-canceled`；`usedQuota`=ΣjoinCount（canceled 不计）；`full = quota>0 && usedQuota≥quota`；`signupRate`；`readCount`=已读人数、`readRate`=阅读率%（readCount/should 取整，仅 `/Signups` 汇总填充，口径同详情 `readnumcount`）。`receiptMode=none` 或 `draft` 时 `progress=null`。
-4. **已读**：`Detail(type=1)` / `MySignup` 标读（家长端打开即确认模式：`receiptMode=confirm` 且状态为 none 时同步置 `confirmed`）；`InitializeRed` 一键全部已读；`ReadDetail` 按年级→班级分组返回读/未读。
+3. **进度统计**（`ActivityProgress`）：`should`=应回执人数；`signed/confirmed/canceled` 按 signup 表 status 计数；`unsigned=should-signed-confirmed-canceled`；`usedQuota`=ΣjoinCount（canceled 不计）；`full = quota>0 && usedQuota≥quota`；`signupRate`；`readCount`=已读人数（学生粒度：接收班级内已读记录条数=实际阅读家长数，仅 `/Signups` 汇总填充，口径同列表 `readCount` 与详情 `readnumcount`）、`readRate`=阅读率%（readCount/should 取整）。`receiptMode=none` 或 `draft` 时 `progress=null`。
+4. **已读**：学生粒度——`Detail(type=1)` / `MySignup` 标读（每个家长账号各记一条，重复打开幂等；打开即确认模式 `receiptMode=confirm` 且状态为 none 时同步置 `confirmed`）；`InitializeRed` 一键全部已读（为当前学生逐活动补记录）；家长端列表/收件箱的已读标志按「本人学号已读」判定；`ReadDetail` 按年级→班级分组返回读/未读（该班任一学生已读即记为读）。
 5. **报名**（Signup/CancelSignup）：校验活动状态（signup 中）、截止时间、名额（quota>0 时 usedQuota+joinCount≤quota）、随行（allowAccompany）；成功/失败回执业务码。
 6. **管理动作**：Edit（含 sourceId 复用）、Delete（批量 + 级联删 read/signup）、UserPull 撤回、SetTopmost、ReceiveClasses 补发（新班级追加并补回执记录）、Expedite/Remind 催办（本期日志占位）、ExportSignups 导出 CSV（easyexcel 已在 pom，CSV 直接拼文本返回）。
 7. **家长端**：`MyActivities` 分桶（todo 待回执/signed 已报名/finished 已结束/all）+ 计数；`MySignup` 活动详情+我的回执（同时标读/自动确认）。