library-picturebook-activity/docs/project/07-system-overview.md

# 系统功能结构总览（重构后）

## 1. 系统架构概览

智创未来采用**多端 + 多租户**架构，共分为 3 个端：

```
┌──────────────────────────────────────────────────────────┐
│                 智创未来                       │
├──────────┬───────────────────┬───────────────────────────┤
│  公众端   │    机构管理端      │       平台管理端（超管）    │
│  /p/...  │  /:tenantCode/... │    /super/...             │
├──────────┼───────────────────┼───────────────────────────┤
│ H5 响应式 │    Web 后台        │       Web 后台            │
│ 面向公众  │  面向机构工作人员   │     面向平台运营团队       │
└──────────┴───────────────────┴───────────────────────────┘
```

---

## 2. 公众端（H5）

### 2.1 定位

面向**全国家长和少儿**的活动参与入口。用户自主注册，浏览公开活动、报名、管理子女、提交作品。

### 2.2 访问方式

- **入口地址**：`/p/activities`（活动大厅）
- **登录地址**：`/p/login`（登录/注册合一）
- **适配终端**：手机浏览器、微信内置浏览器、PC 浏览器（响应式设计）
- **登录方式**：一期：用户名+密码；二期：手机号验证码 + 微信扫码

### 2.3 用户角色

| 角色 | 角色编码 | 说明 |
|------|---------|------|
| 公众用户 | `public_user` | 自主注册，归属"公众用户"系统租户（code=public） |

### 2.4 功能清单

```
公众端
├── 🔓 无需登录
│   ├── 活动大厅 (/p/activities)
│   │   ├── 活动卡片网格展示
│   │   ├── 按名称搜索
│   │   └── 分页浏览
│   └── 活动详情 (/p/activities/:id)
│       ├── 活动封面/海报
│       ├── 活动信息（时间、类型、主办方）
│       ├── 活动详情（富文本）
│       ├── 活动公告列表
│       └── 附件下载
│
├── 🔐 需要登录
│   ├── 活动报名
│   │   ├── 选择参与者（我自己 / 子女）
│   │   └── 确认报名
│   │
│   ├── 个人中心 (/p/mine)
│   │   ├── 用户信息展示
│   │   └── 功能入口导航
│   │
│   ├── 我的报名 (/p/mine/registrations)
│   │   ├── 报名记录列表
│   │   ├── 报名状态（待审核/已通过/已拒绝）
│   │   └── 参与者标识（本人/子女）
│   │
│   ├── 我的作品 (/p/mine/works)
│   │   └── 提交的作品网格展示
│   │
│   └── 子女管理 (/p/mine/children)
│       ├── 子女列表
│       ├── 添加子女（姓名、性别、生日、年级、城市、学校）
│       ├── 编辑子女信息
│       └── 删除子女（软删除）
│
└── 📱 H5 适配
    ├── 移动端：底部 Tab 导航（首页 / 我的）
    └── PC 端：顶部导航栏
```

### 2.5 API 端点

| 方法 | 路径 | 认证 | 说明 |
|------|------|------|------|
| POST | `/api/public/auth/register` | 公开 | 注册 |
| POST | `/api/public/auth/login` | 公开 | 登录 |
| GET | `/api/public/activities` | 公开 | 公开活动列表 |
| GET | `/api/public/activities/:id` | 公开 | 活动详情 |
| POST | `/api/public/activities/:id/register` | 需登录 | 报名活动 |
| GET | `/api/public/mine/profile` | 需登录 | 个人信息 |
| PUT | `/api/public/mine/profile` | 需登录 | 更新个人信息 |
| GET/POST/PUT/DELETE | `/api/public/mine/children` | 需登录 | 子女 CRUD |
| GET | `/api/public/mine/registrations` | 需登录 | 我的报名 |
| GET | `/api/public/mine/works` | 需登录 | 我的作品 |

---

## 3. 机构管理端

### 3.1 定位

面向**入驻机构的管理人员**，负责活动的创建、发布、报名审核、评审管理和成果发布。

### 3.2 已入驻机构

| 机构 | 租户编码 | 类型 | 登录地址 | 账号 |
|------|---------|------|---------|------|
| 广东省立中山图书馆 | `gdlib` | 图书馆 | `/gdlib/login` | `admin` / `admin@gdlib` |

### 3.3 支持的机构类型

| 类型编码 | 名称 | 说明 |
|---------|------|------|
| `library` | 图书馆 | 公共图书馆 |
| `kindergarten` | 幼儿园 | 幼儿教育机构 |
| `school` | 学校 | 中小学校 |
| `institution` | 社会机构 | 美术培训等 |
| `other` | 其他 | 未分类 |

### 3.4 用户角色

| 角色 | 角色编码 | 说明 |
|------|---------|------|
| 机构管理员 | `tenant_admin` | 活动管理全部权限 |

### 3.5 功能清单

```
机构管理端（以广东省图为例）
│
├── 📋 活动管理
│   ├── 活动列表
│   │   ├── 创建活动（含可见范围：公开/指定机构/仅内部）
│   │   ├── 编辑活动
│   │   ├── 发布/撤回活动
│   │   ├── 结束/重新开启活动
│   │   └── 删除活动
│   │
│   ├── 评委管理
│   │   ├── 添加评委
│   │   ├── 查看关联活动
│   │   └── 移除评委
│   │
│   ├── 报名管理
│   │   ├── 查看报名记录（个人参与/团队参与分 Tab）
│   │   ├── 参与方式标识（本人参与/代子女报名+子女姓名）
│   │   ├── 审核报名（通过/拒绝）
│   │   └── 批量操作
│   │
│   ├── 作品管理
│   │   ├── 查看提交的作品
│   │   └── 作品详情
│   │
│   ├── 评审进度
│   │   ├── 评审整体进度统计
│   │   └── 评委评审进度详情
│   │
│   ├── 评审规则
│   │   ├── 创建评审规则
│   │   ├── 编辑评审规则
│   │   └── 关联活动
│   │
│   ├── 成果发布
│   │   ├── 查看活动成果列表
│   │   ├── 设置奖项
│   │   └── 发布/撤回成果
│   │
│   └── 通知管理
│       ├── 创建活动公告
│       ├── 编辑公告
│       └── 删除公告
│
└── ⚙️ 系统管理
    ├── 用户管理（管理机构内部工作人员账号）
    ├── 角色管理（配置机构内的角色权限）
    └── 日志记录（查看本机构操作日志）
```

---

## 4. 平台管理端（超管）

### 4.1 定位

面向**乐绘世界运营团队**，管理整个平台的机构、系统配置和全局数据。

### 4.2 访问方式

| 项目 | 值 |
|------|-----|
| 租户编码 | `super` |
| 登录地址 | `/super/login` |
| 角色 | 超级管理员 (`super_admin`) |

### 4.3 功能清单（重构后，动态菜单驱动）

```
平台管理端（超管）— 只读监管模式，不可创建/编辑/删除活动
│
├── 📋 活动监管（全局只读视角）
│   ├── 全部活动（查看所有机构创建的活动，隐藏写操作按钮）
│   ├── 报名数据
│   ├── 作品数据
│   ├── 评审进度
│   ├── 评委管理
│   ├── 评审规则
│   ├── 成果发布
│   └── 通知管理
│
├── 🏛️ 机构管理（去租户化，精简后的机构列表）
│
├── 👥 用户中心
│   ├── 用户管理（全局用户）
│   ├── 公众用户管理
│   └── 角色管理
│
└── ⚙️ 系统设置
    ├── 菜单管理
    ├── 权限管理
    ├── 数据字典
    ├── 系统配置
    └── 系统日志
```

---

## 4.5 评委端

### 定位

面向**受邀参与活动评审的专业评委**，提供评审工作台和评语管理功能。

### 访问方式

| 项目 | 值 |
|------|-----|
| 租户编码 | `judge` |
| 登录地址 | `/judge/login` |
| 账号 | `admin` / `admin@judge` |
| 角色 | 评委 (`judge`) |

### 功能清单

```
评委端
├── 我的评审
│   ├── 评审任务（我参与评审的活动列表，含进度条和完成状态）
│   └── 预设评语（管理常用评语模板，可跨活动同步）
│
└── 评审工作台（从任务列表点击"进入评审"进入）
    ├── 分配给我的作品列表（分页、搜索、筛选已评/未评）
    ├── 评审打分（打开作品详情，按评审规则维度打分）
    └── 撰写评语（使用预设评语或手动输入）
```

### 业务流程

```
机构管理端                                评委端
1. 创建活动 + 配置评审规则
2. 在"评委管理"中添加评委
3. 报名截止后，在"评审进度"中
   分配作品给评委
   （支持手动/批量/自动分配）
                                         4. 登录评委端
                                         5. "评审任务"看到活动列表和进度
                                         6. 进入某活动 → 看到分配的作品
                                         7. 逐个作品打分 + 写评语
                                         8. 全部评审完成
9. 查看评审进度（实时同步）
10. 所有评委评完后发布成果
```

---

### 4.4 超管独有能力

- 跨租户查看所有活动、报名、作品、评审数据（只读监管，不可创建/编辑/删除活动）
- 管理机构（去租户化的机构列表）
- 管理公众用户（自主注册的公众端用户）
- 配置系统级菜单和权限
- 查看全局日志

---

## 5. 三端关系与数据流

### 5.1 活动发布流程

```
机构管理端                              公众端
┌───────────────┐                    ┌────────────────┐
│ 广东省图管理员 │                    │   公众用户      │
│               │                    │                │
│ 1. 创建活动    │                    │                │
│ 2. 设置可见范围│                    │                │
│    = "公开"    │                    │                │
│ 3. 发布活动   ─┼───── 活动可见 ────►│ 4. 浏览活动     │
│               │                    │ 5. 注册/登录    │
│               │                    │ 6. 选择参与者   │
│               │◄── 报名数据 ───────┤ 7. 报名         │
│ 8. 审核报名   │                    │                │
│               │◄── 作品数据 ───────┤ 9. 提交作品     │
│ 10. 分配评委  │                    │                │
│ 11. 评审打分  │                    │                │
│ 12. 发布成果  ─┼─── 成果可见 ─────►│ 13. 查看成果    │
└───────────────┘                    └────────────────┘
```

### 5.2 用户体系

```
用户来源
├── 管理员创建 (user_source = 'admin_created')
│   ├── 超管用户 → 归属超级租户 (super)
│   ├── 机构用户 → 归属对应机构租户 (gdlib, school, ...)
│   └── 评委用户 → 归属评委租户 (judge)
│
└── 自主注册 (user_source = 'self_registered')
    └── 公众用户 → 归属公众租户 (public)
        ├── 可以自己报名活动 (participant_type = 'self')
        └── 可以代子女报名 (participant_type = 'child')
            └── 通过 children 表管理子女信息
```

---

## 6. 数据库新增/变更汇总

### 6.1 新增表

| 表名 | 说明 |
|------|------|
| `children` | 子女信息表（parent_id → users.id） |

### 6.2 变更字段

| 表 | 新增字段 | 说明 |
|---|---------|------|
| `tenants` | `tenant_type` | 租户类型（library/school/kindergarten/institution/other） |
| `users` | `wx_openid`, `wx_unionid` | 微信登录预留 |
| `users` | `user_source` | 用户来源（admin_created/self_registered） |
| `users` | `city`, `birthday` | 公众用户信息 |
| `users` | `phone` (unique) | 手机号唯一约束 |
| `t_contest` | `visibility` | 活动可见范围（public/designated/internal） |
| `t_contest_registration` | `participant_type` | 参与者类型（self/child） |
| `t_contest_registration` | `child_id` | 子女 ID 关联 |

---

## 7. 技术要点

### 7.1 公众端架构决策

- **公众租户方案**：创建 `public` 系统租户承载公众用户，而非将 `tenantId` 改为可空。避免改动整条认证链路，风险最低。
- **JWT 兼容**：公众端和管理端共用同一套 JWT 签发/验证机制，token 格式一致。
- **路由隔离**：公众端路由 `/p/` 前缀，路由守卫中直接放行，不走管理端认证逻辑。

### 7.2 响应式适配

```
一套 Vue 代码，CSS 媒体查询适配：
├── < 768px  → H5 移动端（底部 Tab 导航）
└── >= 768px → Web 端（顶部导航栏）
```

### 7.3 UI 设计体系

| 维度 | 值 |
|------|-----|
| 主色 | `#6366F1` Creative Indigo |
| 强调色 | `#EC4899` 玫瑰粉 |
| 字体 | Nunito（Google Fonts） |
| 圆角 | 10-16px |
| 阴影 | 靛蓝色调 |
| 页面背景 | `#F8F7FC` 暖紫 |