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

全部活动模块优化 — 设计方案

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

---

1. 背景与问题

超管端"全部活动"模块包含列表页和详情页，均与机构端共用组件，仅通过 isSuperAdmin 隐藏写操作按钮。超管的核心职能是监管，但当前设计缺乏监管视角。

列表页问题

问题	说明
无全局概览	没有活动总量、各状态分布等统计信息，进来就是一张裸表格
缺少活动阶段筛选	只能筛发布状态（已发布/未发布），不能按实际阶段（报名中/征稿中/评审中/已结束）筛选
缺少主办机构筛选	超管跨机构查看但无法按机构过滤
数据列缺少阶段感知	看不到每个活动当前处于哪个阶段（报名中？征稿中？评审中？），只有静态的"已发布/未发布"
统计数字不可交互	报名/作品/评委列的数字是纯展示，不能点击跳转到对应的管理页面
主色不一致	页面内写死 #1890ff，与全局主题色 #6366f1 不一致

详情页问题

问题	说明
页面为参与者视角	海报+报名按钮设计面向教师/学生，不适合超管监管场景
缺少监管数据	看不到报名人数、作品提交情况、评审完成进度等关键指标
缺少配置信息	看不到报名时间、提交时间、评审时间、评审规则等完整配置
缺少快捷导航	无法从详情页跳转到该活动的报名数据、作品数据、评审进度等子模块
文案错误	标题写的"竞赛详情"，应为"活动详情"

---

2. 现状分析

2.1 列表页（contests/Index.vue）

• 与机构管理端共用同一组件
• 超管通过 isSuperAdmin 隐藏写操作（创建/编辑/删除/发布/添加评委）
• 搜索：活动名称、活动状态、活动类型、可见范围
• 表格 12 列：序号/名称/主办方/类型/状态/可见范围/公开机构/报名/作品/评委/时间/操作
• 操作列只有"查看详情"

2.2 详情页（contests/Detail.vue）

• 与机构端、教师端完全共用
• 顶部海报区 + 3 个 Tab（活动信息/通知公告/活动结果）+ 右侧组织信息
• 报名按钮仅 teacher 角色可见，超管看不到也不需要
• 活动信息 Tab 展示富文本内容
• 活动结果 Tab 展示获奖表格（成果已发布时）

2.3 后端现有能力

QueryContestDto 已支持：contestName, contestState(published/unpublished), status(ongoing/finished), contestType, visibility

返回数据已包含：_count { registrations, works, teams, judges }, 时间字段齐全, reviewedCount, totalWorksCount

---

3. 设计方案

3.1 整体思路

列表页：在现有基础上增加统计卡片和阶段筛选，增强数据列的信息密度和可交互性。不拆分为独立组件（超管和机构端列表差异不大），继续共用但通过 isSuperAdmin 适配。

详情页：超管端使用独立的详情页组件，取代当前的参与者视角页面，聚焦监管数据展示和快捷导航。

3.2 列表页优化

3.2.1 新增统计卡片

列表页顶部增加一行统计卡片（仅超管可见）：

┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 全部  12 │ │ 报名中 3 │ │ 征稿中 2 │ │ 评审中 1 │ │ 已结束 4 │ │ 未发布 2 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘

点击卡片 = 快捷筛选。需要后端新增 GET /api/contests/stats 接口。

活动阶段判定逻辑（基于时间字段，非数据库字段）：

未发布：contestState === 'unpublished'
报名中：已发布 && now 在 registerStartTime ~ registerEndTime 之间
征稿中：已发布 && now 在 submitStartTime ~ submitEndTime 之间
评审中：已发布 && now 在 reviewStartTime ~ reviewEndTime 之间
已结束：status === 'finished' 或 所有阶段时间均已过

3.2.2 增强筛选栏

在现有 4 项筛选基础上，超管端增加：

新增筛选项	组件	说明
主办机构	Select（下拉搜索）	按 organizers 字段模糊匹配，或按创建活动的租户筛选
活动阶段	Select	报名中 / 征稿中 / 评审中 / 已结束（前端根据时间字段过滤，或后端增加 stage 参数）

注意：将现有的"活动状态（已发布/未发布）"和"活动阶段"合并为一个筛选项，因为阶段已隐含发布状态。

最终筛选栏（超管端）：

活动名称:[______] 活动阶段:[下拉] 活动类型:[下拉] 可见范围:[下拉] 主办机构:[下拉] [搜索] [重置]

3.2.3 表格列优化

列	宽度	变更
序号	60	不变
活动名称	200	不变
主办机构	120	改为 tenant.name（创建活动的租户名），替代 organizers 字段，更准确
活动类型	90	不变
活动阶段	100	新列，替代原"活动状态"，根据时间字段计算当前阶段，颜色编码：蓝=报名中，绿=征稿中，橙=评审中，灰=已结束，默认=未发布
可见范围	90	不变
报名	70	可点击，点击跳转到该活动的报名数据页
作品	70	可点击，点击跳转到该活动的作品数据页
评审	80	改为进度展示：已评/总数（如 12/30），利用后端已有的 reviewedCount/totalWorksCount
活动时间	160	不变
操作	100	不变（查看详情）

移除列：

• "公开机构"列 — 信息密度低，可在详情页查看
• "评委"列 — 评委数量监管价值低，评审进度更有意义

3.2.4 样式修复

• 将页面内写死的 $primary: #1890ff 改为 $primary: #6366f1，与全局主题一致

3.3 详情页优化（超管专用）

超管点击"查看详情"后，跳转到超管专用的活动详情页，而非现有的参与者视角页面。

3.3.1 页面结构

┌─ 顶部信息栏 ──────────────────────────────────────────────┐
│ ← 返回    活动名称                                        │
│ [个人参与] [已发布] [报名中]   主办：广东省图  创建：2026-03-01 │
└──────────────────────────────────────────────────────────┘

┌─ 数据概览卡片 ─────────────────────────────────────────────┐
│ [报名 128人] [作品 56份] [评审进度 12/56] [评委 5人]        │
│  点击跳转     点击跳转     点击跳转        点击跳转         │
└──────────────────────────────────────────────────────────┘

┌─ 时间轴 ──────────────────────────────────────────────────┐
│ ● 报名阶段 03-01~03-15  ● 征稿阶段 03-15~04-01           │
│ ○ 评审阶段 04-01~04-10  ○ 成果发布 未发布                  │
└──────────────────────────────────────────────────────────┘

┌─ Tab 区域 ────────────────────────────────────────────────┐
│ [活动配置] [活动内容] [通知公告] [活动结果]                  │
├──────────────────────────────────────────────────────────┤
│ 活动配置 Tab：                                             │
│  基本信息：名称/类型/可见范围/定向条件                       │
│  报名配置：时间/是否审核/年级限制/人数限制                   │
│  作品配置：提交时间/提交规则/作品类型/作品要求               │
│  评审配置：评审时间/评审规则名                              │
│  组织信息：主办/协办/赞助/联系方式                          │
│                                                           │
│ 活动内容 Tab：                                             │
│  富文本 v-html（复用现有）                                  │
│                                                           │
│ 通知公告 Tab：                                             │
│  公告列表（复用现有）                                       │
│                                                           │
│ 活动结果 Tab：                                             │
│  获奖表格（复用现有）                                       │
└──────────────────────────────────────────────────────────┘

3.3.2 顶部信息栏

一行展示核心身份信息：

• 返回按钮
• 活动名称（大标题）
• 标签组：活动类型 + 发布状态 + 当前阶段
• 主办机构、创建时间

不使用海报/背景图，保持管理后台的简洁风格。

3.3.3 数据概览卡片

4 张可点击的数据卡片：

卡片	数据来源	点击跳转
报名人数	_count.registrations	/super/contests/registrations?contestId=xx（报名数据页带筛选）
作品数量	_count.works	/super/contests/works/:id/list（作品数据页）
评审进度	reviewedCount / totalWorksCount	/super/contests/reviews/:id/progress（评审进度页）
评委人数	_count.judges	/super/contests/:id/judges（评委管理页）

3.3.4 时间轴

横向时间轴，展示活动的 4 个阶段及其时间范围：

报名阶段 → 征稿阶段 → 评审阶段 → 成果发布

• 已完成的阶段：实心圆 + 主色
• 当前阶段：实心圆 + 高亮 + 脉冲动画
• 未来阶段：空心圆 + 灰色
• 每个节点显示时间范围

3.3.5 Tab 区域

Tab	内容	说明
活动配置	Descriptions 组件展示所有配置字段	新增，超管最需要看到的完整配置信息
活动内容	富文本 v-html	复用现有逻辑
通知公告	公告列表	复用现有逻辑
活动结果	获奖表格	复用现有逻辑

活动配置 Tab 详细设计：

基本信息
├── 活动名称 / 活动类型 / 可见范围
├── 定向条件（城市/年龄，仅 targeted 时显示）
└── 公开机构列表（仅 designated 时显示）

报名配置
├── 报名时间：xx ~ xx
├── 是否需要审核：是/否
├── 允许年级/班级（如有）
└── 团队人数限制（团队参与时显示）

作品配置
├── 提交时间：xx ~ xx
├── 提交规则：单次提交 / 允许重新提交
├── 作品类型：图片/视频/文档/...
└── 作品要求（文本描述）

评审配置
├── 评审时间：xx ~ xx
├── 关联评审规则：规则名称
└── 成果状态：已发布 / 未发布

组织信息
├── 主办单位 / 协办单位 / 赞助单位
└── 联系人 / 联系电话

3.4 路由设计

超管端活动详情使用独立路由，不影响现有的机构端/教师端详情页：

// 新增：超管活动详情路由
{
  path: "contests/:id/overview",
  name: "SuperContestOverview",
  component: () => import("@/views/contests/SuperDetail.vue"),
  meta: { title: "活动详情", requiresAuth: true },
}

列表页"查看详情"按钮：

• 超管端跳转到 /:tenantCode/contests/:id/overview（新页面）
• 机构端保持跳转到 /:tenantCode/contests/:id（原页面）

3.5 后端改动

3.5.1 新增 GET /api/contests/stats（活动统计）

仅超管可用，返回：

{
  "total": 12,
  "unpublished": 2,
  "registering": 3,
  "submitting": 2,
  "reviewing": 1,
  "finished": 4
}

阶段判定在后端基于时间字段计算。

3.5.2 扩展 GET /api/contests 查询参数

新增参数	类型	说明
stage	string?	活动阶段筛选：unpublished/registering/submitting/reviewing/finished
creatorTenantId	number?	按创建活动的租户（主办机构）筛选

stage 筛选逻辑在后端实现（基于时间字段比较），避免前端做应用层过滤影响分页。

3.5.3 GET /api/contests/:id 返回增强

超管调用时额外返回：

• tenant: { id, name, code }（创建活动的租户信息）
• 确保 reviewedCount 和 totalWorksCount 已返回（当前已有）

3.6 前端改动

文件	操作	说明
frontend/src/api/contests.ts	修改	QueryContestParams 增加 stage/creatorTenantId，新增 getStats 接口
frontend/src/views/contests/Index.vue	修改	超管端增加统计卡片、阶段筛选、机构筛选、可点击数字、阶段列、样式修复
frontend/src/views/contests/SuperDetail.vue	新增	超管专用活动详情页
frontend/src/router/index.ts	修改	新增超管活动详情路由
backend/src/contests/contests/contests.service.ts	修改	新增 getStats 方法，findAll 增加 stage/creatorTenantId 参数
backend/src/contests/contests/contests.controller.ts	修改	新增 stats 端点，findAll 增加查询参数
backend/src/contests/contests/dto/query-contest.dto.ts	修改	新增 stage/creatorTenantId 字段

---

4. 改动范围

后端（3 个文件）

文件	改动类型
backend/src/contests/contests/contests.service.ts	修改：新增 getStats()，findAll 增加 stage/creatorTenantId 过滤
backend/src/contests/contests/contests.controller.ts	修改：新增 GET /contests/stats，findAll 增加查询参数
backend/src/contests/contests/dto/query-contest.dto.ts	修改：DTO 新增字段

前端（4 个文件）

文件	改动类型
frontend/src/api/contests.ts	修改：扩展类型和接口
frontend/src/views/contests/Index.vue	修改：超管端增强
frontend/src/views/contests/SuperDetail.vue	新增：超管活动详情页
frontend/src/router/index.ts	修改：新增路由

---

5. 实施记录

2026-03-27 — 首次实现

后端改动（3 个文件）：

• backend/src/contests/contests/dto/query-contest.dto.ts — 新增 stage、creatorTenantId 字段
• backend/src/contests/contests/contests.service.ts — 新增 getContestStage() 阶段判定方法、getStats() 统计方法；findAll 增加 stage 应用层过滤和 creatorTenantId 筛选；返回数据增加 stage、creatorTenant 字段
• backend/src/contests/contests/contests.controller.ts — 新增 GET /api/contests/stats 端点

前端改动（4 个文件）：

• frontend/src/api/contests.ts — QueryContestParams 增加 stage/creatorTenantId/visibility；新增 ContestStats 类型和 getStats 接口
• frontend/src/views/contests/Index.vue — 重写：超管端增加统计卡片（6 个阶段）、活动阶段筛选+主办机构筛选、超管/机构分列定义、活动阶段列、报名/作品可点击跳转、评审进度列（已评/总数）、主色修复为 #6366f1
• frontend/src/views/contests/SuperDetail.vue — 新增：超管活动详情页，含顶部信息栏+4 张数据概览卡片+横向时间轴+4 Tab（配置/内容/公告/结果）
• frontend/src/router/index.ts — 新增 contests/:id/overview 超管详情路由