library-picturebook-activity/docs/design/org-admin/tenant-portal-optimization.md

# 租户端（机构管理端）全面优化记录

> 所属端：租户端（机构管理员视角）
> 状态：已优化
> 创建日期：2026-03-31
> 最后更新：2026-04-09

---

## 概述

以广东省立中山图书馆（gdlib）为典型租户，从机构管理员/运营人员视角全面审查并优化了租户端的所有模块。

## Day5 (2026-03-31) — 优化内容

### 基础设施

- [x] 数据隔离验证：确认活动/报名/作品查询全部带 tenantId 过滤
- [x] 日志菜单权限修复：补充 log:read 权限
- [x] 公告权限修复：补充 notice:update / notice:delete 权限
- [x] 403 报错修复：fetchTenants 调用加 isSuperAdmin 守卫（contests/Index, system/users/Index）
- [x] 评审规则组件映射修复：contests/ReviewRules 指向正确的 reviews/Index.vue
- [x] 作品详情路由权限修复：work:read 改为 contest:work:read

### 工作台（新增）
- [x] 新增租户端工作台页面（TenantDashboard.vue）
- [x] 欢迎信息 + 机构标识（时段问候、管理员姓名、机构名称/类型）
- [x] 6个统计卡片（可见活动/进行中/总报名/待审核报名/总作品/今日报名），可点击跳转
- [x] 空数据新手引导（三步：创建活动→添加成员→邀请评委）
- [x] 快捷操作按权限动态显示（固定四项：活动列表、报名管理、作品管理、评委管理；不含「用户管理」，用户管理从系统设置进入）
- [x] 待办提醒（待审核报名 + 即将截止的活动）
- [x] 最近活动列表 + 查看全部入口
- [x] 后端 GET /contests/dashboard 接口

### 机构信息（新增）
- [x] 新增机构信息管理页面（tenant-info/Index.vue）
- [x] 查看/编辑机构名称和描述
- [x] 复制登录地址
- [x] 后端 GET/PATCH /tenants/my-tenant 接口

### 活动列表
- [x] 租户端加统计概览（6个阶段卡片，后端 getStats 加 tenantId 过滤）
- [x] 精简表格列（去掉主办方/可见范围/公开机构，加活动阶段列）
- [x] 筛选自动查询（下拉 @change）
- [x] 报名/作品数可点击跳转
- [x] 修复发布弹窗机构选择 bug（租户端用 my-tenant 接口获取自己信息）
- [x] 操作按钮逻辑优化（未发布：发布/编辑/删除；已发布：查看/评委/编辑/取消发布）

### 创建/编辑活动
- [x] 重构页面布局：去掉 card 嵌套，改为独立分区卡片
- [x] 修复 form layout 冲突（vertical + labelCol）
- [x] 去掉固定宽度，改用栅格响应式
- [x] 4 个分区：主办信息、活动信息、图片附件、时间配置

### 评委管理
- [x] 筛选自动查询
- [x] 导入/导出改为 disabled + tooltip
- [x] 主色调统一 #6366f1
- [x] 冻结/解冻二次确认

#### 赛事评委接口（`GET /contests/judges/contest/:id`）

- 响应为结构化对象，包含两部分：**`assigned`**（机构在该赛事下**显式添加**的评委，对应 `t_biz_contest_judge`，每条均有 `id`、`judgeId` 等）与 **`implicitPool`**（平台评委租户下对该赛事**默认可用**、尚未写入关联表的用户，`id` 为 null，`isPlatform` 为 true）。
- **添加评委抽屉**：「已选」回显与提交时的增删差集**仅基于 `assigned`**；可选评委仍来自评委管理分页接口。
- **作品分配**：可选评委池为 **`assigned` ∪ `implicitPool`**（前端合并）；表格行键与选中状态统一使用 **`judgeId`**，与分配接口提交的 `judgeIds` 一致。

### 报名管理（Index）
- [x] 去掉个人/团队 Tab，合并展示加类型列
- [x] 统计概览（总报名/待审核/已通过/已拒绝）
- [x] 表格加审核状态分类计数列（并行查询每个活动的统计）
- [x] 去掉手动启动/关闭报名

### 报名记录（Records）
- [x] 主色调统一
- [x] 统计概览 + 可点击筛选
- [x] 租户端去掉机构列
- [x] 筛选自动查询
- [x] 通过加二次确认
- [x] 批量审核改用后端批量接口 POST /contests/registrations/batch-review
- [x] 返回按钮
- [x] 去掉「参与方式」列（子女已改为独立账号）
- [x] 撤销审核功能 PATCH /contests/registrations/:id/revoke

### 作品管理（Index）
- [x] 去掉 Tab，加统计概览 + 类型筛选
- [x] 递交进度彩色数字（已交/应交）
- [x] 活动名可点击

### 作品详情（WorksDetail）
- [x] 返回按钮
- [x] 统计概览
- [x] 租户端去掉机构筛选
- [x] 筛选自动查询（分配状态、递交时间、机构下拉）
- [x] 后端支持 assignStatus / name / submitStartTime / submitEndTime 筛选
- [x] 分配评委去掉评审时间限制（任何时候都可分配）

### 评审进度
- [x] 去掉 Tab，加统计概览 + 类型筛选
- [x] 评审状态改用实际完成率（无作品/未开始/进行中/已完成）
- [x] 进度数字颜色区分
- [x] 评审进度详情页筛选修复（评审进度前端过滤生效）
- 活动列表接口 `GET /contests` 为每行返回 `reviewedCount`（该活动下**已分配且全部分配均为 completed** 的作品数）与 `totalWorksCount`（最新有效作品总数），与分配表及评委端评审任务口径一致；见 [评委端评审任务](../judge-portal/review-tasks.md#与租户端评审进度的口径对齐)。

### 评审规则
- [x] 组件映射修复
- [x] 主色调统一
- [x] 表格加评委数/计算方式列
- [x] 修复规则描述列数据展示错误
- [x] 已关联活动删除保护提示
- [x] Drawer 标题区分新建/编辑

### 成果发布（Index）
- [x] 去掉 Tab，加统计概览（全部/已发布/未发布）
- [x] 加发布状态筛选 + 类型筛选
- [x] 活动名可点击
- [x] 操作按钮文案优化（查看成果/发布成果）

### 成果发布详情（Detail）— 功能补全
- [x] 统计摘要（总作品/已评分/已排名/已设奖/平均分）
- [x] 三步操作流程（计算得分→计算排名→设置奖项）
- [x] 排名列（金银铜色徽章）
- [x] 奖项列（彩色标签）
- [x] 奖项筛选（动态从数据提取）
- [x] 单个设奖（combobox，选项来自自动设奖配置 + 已有数据）
- [x] 自动设奖改为自定义奖项（动态添加行：奖项名称+人数）
- [x] 后端 AutoSetAwardsDto 改为 awards 数组格式
- [x] 发布按钮二次确认

### 通知公告
- [x] 主色调统一
- [x] 发布/取消发布二次确认
- [x] 操作逻辑优化（未发布：发布/编辑/删除；已发布：查看/取消发布）
- [x] 发布状态筛选
- [x] 日期改为时间范围选择器
- [x] 创建时间列 + 按创建时间倒序
- [x] 后端支持 publishStartDate / publishEndDate 范围查询

### 新增 API
```
GET    /contests/dashboard                          — 租户端仪表盘
GET    /contests/stats (加 tenantId)                 — 活动统计支持租户过滤
GET    /tenants/my-tenant                            — 获取当前租户信息
PATCH  /tenants/my-tenant                            — 更新当前租户信息
POST   /contests/registrations/batch-review          — 批量审核报名
PATCH  /contests/registrations/:id/revoke            — 撤销报名审核
GET    /contests/registrations/stats (加 tenantId)   — 报名统计支持租户过滤
```

### 成果发布详情（Detail）— 功能补全
- [x] 统计摘要（总作品/已评分/已排名/已设奖/平均分）
- [x] 三步操作流程（计算得分→计算排名→设置奖项）
- [x] 排名列（金银铜色徽章）+ 奖项列（彩色标签）+ 奖项筛选
- [x] 自定义奖项支持（动态添加奖项名称+人数，替代硬编码一/二/三等奖）
- [x] 单个设奖（combobox，选项来自自动设奖配置 + 已有数据）
- [x] 后端 AutoSetAwardsDto 改为 awards 数组格式

### 数据统计模块（新增）
- [x] 后端 analytics.module / controller / service
- [x] GET /analytics/overview — 核心指标+漏斗+月度趋势+活动对比
- [x] GET /analytics/review — 评审效率+评委工作量+奖项分布
- [x] 前端安装 echarts + vue-echarts
- [x] analytics/Overview.vue — 6个指标卡片 + 报名转化漏斗 + ECharts月度趋势折线图 + 活动对比表
- [x] analytics/Review.vue — 4个效率卡片 + 评委工作量表 + ECharts奖项分布饼图
- [x] 菜单注册：数据统计（运营概览 + 评审分析）

### Bug 修复
- [x] 超管端重置其他租户用户密码报「用户不存在」— controller 增加超管判断跳过租户过滤
- [x] gdlib 登录快捷标签密码与实际不一致 — 更新为 admin123

### 新增 API（完整）
```
GET    /contests/dashboard                          — 租户端仪表盘
GET    /contests/stats (加 tenantId)                 — 活动统计支持租户过滤
GET    /tenants/my-tenant                            — 获取当前租户信息
PATCH  /tenants/my-tenant                            — 更新当前租户信息
POST   /contests/registrations/batch-review          — 批量审核报名
PATCH  /contests/registrations/:id/revoke            — 撤销报名审核
GET    /contests/registrations/stats (加 tenantId)   — 报名统计支持租户过滤
GET    /analytics/overview                           — 运营概览统计
GET    /analytics/review                             — 评审分析统计
```

### 数据库变更
- menus 表新增：工作台(id=50)、机构信息(id=51)、数据统计(id=52)、运营概览(id=53)、评审分析(id=54)
- permissions 表新增：log:read、notice:update、notice:delete（gdlib 租户）
- work_tags 表新增 color 字段
- 前端依赖新增：echarts、vue-echarts