library-picturebook-activity/docs/design/super-admin/registration-data-optimization.md

报名数据模块优化 — 设计方案

所属端：超管端 状态：已实现（待验收） 创建日期：2026-03-27 最后更新：2026-03-27

---

1. 背景与问题

超管端"报名数据"菜单目前是两层结构：第一层按活动维度展示活动列表（每行一个活动，显示报名人数），点击"报名记录"进入第二层查看某活动的具体报名记录。

核心问题

问题	说明
第一层与全部活动列表重复	Index.vue 本质是活动列表精简版，而全部活动列表已有可点击的报名人数列，两个入口功能重叠
超管写操作未隔离	"启动报名/关闭报名"、"通过/拒绝/删除"等写操作对超管应隐藏
缺少全局统计	没有报名总量、各审核状态分布等概览
无跨活动搜索	只能看某个活动的报名记录，不能跨活动搜索（如"某个用户报了哪些活动"）
样式不一致	主色写死 #1890ff

---

2. 现状分析

2.1 第一层：报名管理（registrations/Index.vue）

• 个人参与/团队参与 Tab 切换
• 数据来源：contestsApi.getList() 按活动类型过滤
• 搜索：仅活动名称
• 操作：报名记录（跳转）、启动报名、关闭报名
• 本质是活动列表的子集视图，对超管来说是冗余页面

2.2 第二层：报名记录（registrations/Records.vue）

• 数据来源：registrationsApi.getList({ contestId }) 查某活动的报名记录
• 搜索：机构、姓名/队伍名、报名账号、审核状态、报名时间
• 功能：批量审核、导出、通过/拒绝/删除、详细信息 Drawer、团队成员弹窗

---

3. 设计方案

3.1 整体思路

超管端将两层合并为一层：一个扁平的报名记录列表，展示全平台所有活动的报名数据，通过筛选条件实现分活动查看。

理由：

1. 活动维度的概览已由"全部活动"列表承担（报名数字可点击跳转）
2. 超管需要的是跨活动的全局视角，快速找到某条报名记录
3. 从"全部活动"列表点击报名数字时，带 contestId 参数跳转过来，自动筛选该活动

机构端保持现有两层结构不变。

3.2 页面结构

┌─ 标题卡片 ──────────────────────────────────────────────┐
│  报名数据                                                │
└─────────────────────────────────────────────────────────┘

┌─ 统计卡片 ──────────────────────────────────────────────┐
│ [全部 256] [待审核 38] [已通过 200] [已拒绝 18]           │
└─────────────────────────────────────────────────────────┘

┌─ 筛选栏 ────────────────────────────────────────────────┐
│ 所属活动:[下拉搜索] 参与者:[______] 审核状态:[下拉]       │
│ 参与方式:[下拉] 报名时间:[日期范围]    [搜索] [重置]      │
└─────────────────────────────────────────────────────────┘

┌─ 数据表格 ──────────────────────────────────────────────┐
│ 所属活动 | 参与者 | 参与方式 | 报名账号 | 主办机构 |      │
│          | 审核状态 | 报名时间 | 操作                     │
└─────────────────────────────────────────────────────────┘

3.3 统计卡片

4 张卡片，可点击切换筛选：

卡片	数据	颜色
全部	报名总数	主色
待审核	pending 数量	橙色
已通过	passed 数量	绿色
已拒绝	rejected 数量	红色

数据来源：新增 GET /api/registrations/stats 接口。

3.4 筛选栏

筛选项	组件	说明
所属活动	Select（远程搜索）	按活动名称搜索下拉，选择后按 contestId 过滤
参与者	Input	搜索参与者姓名、手机号、子女姓名
审核状态	Select	待审核 / 已通过 / 已拒绝
参与方式	Select	本人参与 / 代子女报名
报名时间	RangePicker	时间范围筛选

联动逻辑：从"全部活动"列表点击报名数字跳转时，URL 带 ?contestId=xx，页面初始化时自动设置"所属活动"筛选。

3.5 表格列

列	宽度	渲染方式
所属活动	180	活动名称，可点击跳转活动详情
参与者	140	昵称；代子女报名时附带子女姓名
参与方式	100	Tag：本人参与（蓝）/ 代子女报名（绿）
报名账号	120	username
主办机构	120	活动创建者所属租户名
审核状态	90	Tag：待审核（橙）/ 已通过（绿）/ 已拒绝（红）
报名时间	150	YYYY-MM-DD HH:mm
操作	80	查看详情

超管操作列只有"查看详情"，不提供通过/拒绝/删除。

3.6 详情 Drawer

点击"查看详情"打开右侧 Drawer：

基本信息（Descriptions）
├── 所属活动 / 主办机构
├── 参与者昵称 / 报名账号 / 手机号
├── 参与方式 / 子女姓名（如有）
├── 审核状态 / 审核理由（如有）
└── 报名时间

子女信息（参与方式=代子女报名时显示）
├── 姓名 / 性别 / 年龄 / 年级
├── 城市 / 学校

团队信息（团队参与时显示）
├── 队伍名称 / 队长 / 成员数
└── 成员列表表格

3.7 URL 参数支持

• /super/contests/registrations — 全部报名记录
• /super/contests/registrations?contestId=3 — 筛选某个活动的报名记录（从活动列表跳转）
• /super/contests/registrations?status=pending — 筛选待审核记录

页面 onMounted 时读取 URL query 参数，自动设置对应筛选条件。

---

4. 后端改动

4.1 新增 GET /api/registrations/stats

超管调用时返回全平台报名统计：

{
  "total": 256,
  "pending": 38,
  "passed": 200,
  "rejected": 18
}

支持可选的 contestId 参数，传入时只统计该活动。

4.2 扩展 GET /api/registrations（现有接口）

超管调用时：

• contestId 变为可选参数（当前是必填），不传时查全部活动的报名记录
• 新增 participantType 参数：self / child
• 新增 keyword 参数：搜索参与者姓名、手机号、子女姓名
• 返回数据增加活动信息：contest: { id, contestName, creatorTenant: { name } }
• 返回数据增加子女信息：child: { name, gender, birthday, grade, city, schoolName }

普通租户调用时保持现有逻辑不变。

---

5. 前端改动

文件	操作	说明
frontend/src/api/contests.ts	修改	扩展 QueryRegistrationParams，新增 registrations stats 接口
frontend/src/views/contests/registrations/Index.vue	修改	超管端改为扁平报名记录列表（统计卡片+筛选+表格+Drawer），机构端保持不变
backend/src/contests/registrations/registrations.service.ts	修改	扩展 findAll 支持跨活动查询，新增 getStats
backend/src/contests/registrations/registrations.controller.ts	修改	新增 stats 端点，findAll 增加参数

---

6. 实施记录

2026-03-27 — 首次实现

后端改动（3 个文件）：

• backend/src/contests/registrations/dto/query-registration.dto.ts — 新增 participantType、keyword 参数
• backend/src/contests/registrations/registrations.service.ts — 新增 getStats() 方法；findAll 增加 participantType 和 keyword（搜索昵称/手机/子女名）过滤
• backend/src/contests/registrations/registrations.controller.ts — 新增 GET /api/contests/registrations/stats 端点

前端改动（2 个文件）：

• frontend/src/api/contests.ts — 扩展 QueryRegistrationParams（participantType/keyword），新增 RegistrationStats 类型和 getStats 接口
• frontend/src/views/contests/registrations/Index.vue — 完全重写：超管端为扁平报名记录列表（统计卡片+筛选栏+全平台表格+详情Drawer），机构端保持原有两层结构；支持 URL 参数联动（?contestId=xx&status=pending）