library-picturebook-activity/docs/project/05-development-plan.md

# 开发计划

## 1. 总体时间线

- **项目启动**：2026-03-24
- **目标上线**：2026-04-14
- **总工期**：3 周（15 个工作日）
- **开发方式**：Claude 辅助全栈开发

---

## 2. 一期开发计划（三周冲刺）

### 第一周（03-24 ~ 03-28）：地基改造

| 日期 | 任务 | 产出 | 状态 |
|------|------|------|------|
| D1 (03-24) | 需求梳理、设计文档沉淀、UI 主题改造 | 设计文档、UI 新主题 | 已完成 |
| D2 (03-25) | 数据库改造：users/tenants/registrations/contests 表变更，新建 children 表，Prisma Schema 同步 | 数据库迁移脚本 | 已完成 |
| D3 (03-26) | 后端：公众注册/登录 API、子女 CRUD API | 公众端 Auth + Children API | 已完成 |
| D4 (03-27) | 后端：公众端活动列表/详情 API、报名 API、我的报名/作品 API | Public Activities + Registration API | 已完成 |
| D5 (03-28) | 前端：公众端基础框架、路由、布局（H5 响应式）、注册/登录页、活动大厅、个人中心 | 公众端框架 + 核心页面 | 已完成 |

### 第二周（03-31 ~ 04-04）：核心业务流程

| 日期 | 任务 | 产出 | 状态 |
|------|------|------|------|
| D6-10 | 前端：活动详情页（含报名弹窗）、子女管理页、我的报名页、我的作品页 | 公众端全部页面 | 已完成 |

### 第三周（04-07 ~ 04-11）：管理端适配 + 联调

| 日期 | 任务 | 产出 | 状态 |
|------|------|------|------|
| D11-12 | 管理端：活动创建增加可见范围、租户类型字段、报名记录展示参与者类型和子女信息 | 管理端改造 | 已完成 |
| D13 | 广东省图初始化：创建租户(gdlib)、管理员(admin/admin@gdlib)、权限、菜单 | 初始化数据 | 已完成 |
| D14 | 超管端菜单重构 + 公众用户管理 + 评委端修复 | 各端功能完善 | 已完成 |
| D15 (04-11) | Bug 修复、UI 微调、部署上线 | 生产环境上线 | |

**缓冲时间**：04-12 ~ 04-14 留作紧急修复和优化。

---

## 3. 已完成工作详细记录

### 3.1 系统改名与 UI 改造（D1）

**文案替换：**
- "比赛/赛事" → "活动"（前后端 46 个文件 + 数据库）
- "个人赛/团队赛" → "个人参与/团队参与"（25 个文件 + 数据库）
- "赛果" → "成果"（25 个文件 + 数据库菜单/权限）
- 系统名称 → "乐绘世界创想活动乐园"
- Logo 替换为 LeSingle 品牌标志

**UI 主题全面改造（6 个核心文件）：**
- 主色调：`#0958d9` 蓝 → `#6366F1` Creative Indigo
- 强调色：`#EC4899` 玫瑰粉
- 字体：系统默认 → Nunito（Google Fonts）
- 圆角：6-8px → 10-16px
- 阴影：灰色 → 靛蓝色调
- 页面背景：`#f5f7fa` → `#F8F7FC` 暖紫
- 侧边栏：纯白 → 暖白渐变
- 全局组件覆盖：按钮、卡片、表格、标签、输入框、模态框等

### 3.2 数据库改造（D2）

**Prisma Schema 变更：**

| 表 | 变更 | 默认值 |
|---|------|--------|
| `tenants` | +`tenant_type` | `'other'` |
| `users` | +`phone`(unique), `wx_openid`(unique), `wx_unionid`, `user_source`, `city`, `birthday` | `user_source='admin_created'` |
| `t_contest` | +`visibility` | `'designated'` |
| `t_contest_registration` | +`participant_type`, `child_id` | `participant_type='self'` |
| `children` | **新建表** | - |

**初始化数据：**
- 公众租户：code=`public`, tenantId=8, type=`platform`
- 公众用户角色：code=`public_user`, 4 个权限
- 广东省图租户：code=`gdlib`, tenantId=9, type=`library`
- 广东省图管理员：admin/admin@gdlib, 21 个权限, 角色 `tenant_admin`
- 超级租户类型更新：`platform`
- 学校端类型更新：`school`

### 3.3 公众端后端 API（D3-D4）

**新增模块 `backend/src/public/`：**

| 文件 | 说明 |
|------|------|
| `public.module.ts` | 模块定义 |
| `public.controller.ts` | 16 个 API 端点 |
| `public.service.ts` | 完整业务逻辑 |
| `dto/register.dto.ts` | 注册/登录 DTO |
| `dto/child.dto.ts` | 子女 CRUD DTO |
| `dto/registration.dto.ts` | 活动报名 DTO |

**API 端点清单（16 个）：**

| 方法 | 路径 | 认证 | 说明 |
|------|------|------|------|
| POST | `/api/public/auth/register` | 公开 | 公众注册（自动登录） |
| POST | `/api/public/auth/login` | 公开 | 公众登录 |
| GET | `/api/public/mine/profile` | 需登录 | 个人信息+子女 |
| PUT | `/api/public/mine/profile` | 需登录 | 更新个人信息 |
| GET | `/api/public/mine/children` | 需登录 | 子女列表 |
| POST | `/api/public/mine/children` | 需登录 | 添加子女 |
| GET | `/api/public/mine/children/:id` | 需登录 | 子女详情 |
| PUT | `/api/public/mine/children/:id` | 需登录 | 编辑子女 |
| DELETE | `/api/public/mine/children/:id` | 需登录 | 删除子女（软删除） |
| POST | `/api/public/activities/:id/register` | 需登录 | 报名活动（选择参与者） |
| GET | `/api/public/mine/registrations` | 需登录 | 我的报名列表 |
| GET | `/api/public/mine/works` | 需登录 | 我的作品列表 |
| GET | `/api/public/activities` | 公开 | 公开活动列表 |
| GET | `/api/public/activities/:id` | 公开 | 活动详情 |
| GET | `/api/public/users` | 需登录 | 公众用户列表（超管用） |
| GET | `/api/public/users/:id` | 需登录 | 公众用户详情（超管用） |

**架构决策：** 创建 `public` 系统租户（code=public）承载公众用户，避免修改现有认证链路，JWT token 格式完全兼容。

### 3.4 公众端前端 H5（D5-D10）

**新增文件：**

| 文件 | 路由 | 说明 |
|------|------|------|
| `layouts/PublicLayout.vue` | `/p` | 公众端布局（顶部导航+底部TabBar+响应式） |
| `views/public/Login.vue` | `/p/login` | 登录/注册合一页面 |
| `views/public/Activities.vue` | `/p/activities` | 活动大厅（卡片网格+搜索+分页） |
| `views/public/ActivityDetail.vue` | `/p/activities/:id` | 活动详情（报名弹窗+选择参与者） |
| `views/public/mine/Index.vue` | `/p/mine` | 个人中心 |
| `views/public/mine/Registrations.vue` | `/p/mine/registrations` | 我的报名列表 |
| `views/public/mine/Works.vue` | `/p/mine/works` | 我的作品网格 |
| `views/public/mine/Children.vue` | `/p/mine/children` | 子女管理（CRUD） |
| `api/public.ts` | - | 公众端 API 封装 |

**路由守卫：** `/p/` 前缀路由直接放行，不走管理端认证逻辑。

### 3.5 管理端适配（D11-D12）

**活动创建页（Create.vue）：**
- 新增"可见范围"字段：公开 / 指定机构 / 仅内部
- 后端 DTO 同步新增 `Visibility` 枚举

**租户管理页（tenants/Index.vue）：**
- 新增"租户类型"下拉选择和表格列
- 类型标签：图书馆(紫)/幼儿园(绿)/学校(蓝)/社会机构(橙)/其他

**报名记录页（registrations/Records.vue）：**
- 个人参与和团队参与表格新增"参与方式"列
- 显示"本人参与"(蓝色标签) 或 "代子女报名"(绿色标签)+子女姓名
- 后端查询 include child 关联数据

**机构管理端菜单清理（广东省图 gdlib）：**
- 移除不应有的平台级菜单：菜单管理、数据字典、系统配置、权限管理、租户管理
- 保留：用户管理、角色管理、日志记录

### 3.6 超管端菜单重构（D14）

**菜单结构从 2 个一级 → 4 个一级：**

| 重构前 | 重构后 |
|--------|--------|
| 活动管理（8 项） | 活动管理（8 项，不变） |
| 系统管理（8 项混杂） | 拆分为 ↓ |
| └ 租户管理 | **机构管理** → 机构列表（改名） |
| └ 用户管理 + 角色管理 | **用户中心** → 公众用户(🆕) + 平台用户 + 角色管理 |
| └ 菜单/权限/字典/配置/日志 | **系统设置** → 5 个配置类功能 |

**新增公众用户管理页面（`system/public-users/Index.vue`）：**
- 自注册用户列表（搜索、分页）
- 用户信息列：头像+昵称+用户名
- 统计列：子女数、报名次数
- 详情抽屉：基本信息 + 子女列表 + 近期报名记录

### 3.7 评委端修复（D14）

**问题：** 评委端前后端代码完整但数据库菜单缺失，导致评委登录后看不到任何功能。

**修复内容：**

| 项目 | 改动 |
|------|------|
| 数据库菜单 | 创建"我的评审"一级菜单 + "评审任务""预设评语"子菜单，分配给评委租户 |
| 权限 | 添加 `review:score` 权限并分配给评委角色 |
| 路由 | 新增评审详情路由 `activities/review/:id` → `ReviewDetail.vue` |
| Bug 修复 | "活动活动" → "我的评审"（6 个文件，原"赛事活动"批量替换导致的 bug） |
| 登录页 | 开发模式快捷入口增加"评委端"标签 |

**评委端最终菜单：**
```
评委端 (/judge/login, admin/admin@judge)
└── 我的评审
    ├── 评审任务（活动列表+进度 → 进入评审工作台）
    └── 预设评语（评语模板管理+跨活动同步）
```

### 3.8 登录页改造（D14）

- 快捷切换标签：从旧的 5 个学校端 → 新的 3 个（平台超管/广东省图/评委端）
- 副标题：显示当前机构名 + "管理端登录"
- 移除租户编码手动输入框
- 新增"参与活动？前往公众端"链接

---

## 4. 当前各端状态总览

| 端 | 入口 | 账号 | 功能状态 |
|----|------|------|---------|
| 公众端 | `/p/activities` | 自主注册 | ✅ 活动浏览、注册登录、子女管理、报名、个人中心 |
| 广东省图管理端 | `/gdlib/login` | admin/admin@gdlib | ✅ 活动管理 8 个功能 + 系统管理 3 个功能 |
| 超管端 | `/super/login` | admin/admin@super | ✅ 活动管理 + 机构管理 + 用户中心(含公众用户) + 系统设置 |
| 评委端 | `/judge/login` | admin/admin@judge | ✅ 评审任务 + 预设评语 + 评审工作台 |

---

## 5. 二期功能规划

| 功能 | 预估工期 | 负责人 | 依赖 |
|------|---------|--------|------|
| 手机号+验证码登录 | 3天 | 同事 | 腾讯云短信服务开通、签名模板审批 |
| 微信扫码登录（Web） | 3天 | 同事 | 微信开放平台网站应用审批 |
| 微信授权登录（H5） | 2天 | 同事 | 微信公众号认证、授权域名配置 |
| 一号多身份切换 | 5天 | Claude | user_identities 表、身份切换 UI |
| 多机构联合举办 | 3天 | Claude | contest_co_organizers 表、权限配置 |
| 超管运营仪表盘 | 3天 | Claude | 活动/用户/报名统计图表 |

---

## 6. 外部依赖清单

### 一期需要（上线前）

| 依赖项 | 状态 | 说明 |
|--------|------|------|
| 域名和 HTTPS | 待确认 | H5 页面需要 HTTPS |
| 服务器部署环境 | 待确认 | 生产环境服务器配置 |
| 广东省图活动信息 | 待获取 | 活动名称、时间、规则、封面等 |
| 广东省图 Logo | 待获取 | 用于活动页面展示主办方标识 |

### 二期需要

| 依赖项 | 状态 | 说明 |
|--------|------|------|
| 腾讯云短信服务 | 待开通 | 短信签名、验证码模板审批（约3-5天） |
| 微信开放平台账号 | 待注册 | 需要企业资质，网站应用审批（约7天） |
| 微信公众号 | 待确认 | H5 微信授权登录需要认证服务号 |

---

## 7. 技术风险

| 风险 | 等级 | 应对措施 |
|------|------|---------|
| 公众端性能（全国用户） | 中 | 活动列表接口加缓存、分页控制 |
| 少儿信息安全 | 高 | 子女姓名等敏感信息在数据库层面加密存储 |
| 文件上传（作品）并发 | 中 | 使用现有腾讯云 COS 直传方案 |

---

## 8. 验收标准

### 一期上线验收清单

- [x] 公众用户可以通过 H5 页面注册账号
- [x] 公众用户可以浏览公开活动列表和详情
- [x] 家长可以添加/管理子女信息
- [x] 用户可以为自己或子女报名活动
- [ ] 用户可以在提交阶段上传作品
- [x] 个人中心可以查看所有报名和作品记录
- [x] 广东省图管理员可以创建"公开"可见范围的活动
- [x] 广东省图管理员可以查看报名记录并区分参与者类型
- [ ] H5 页面在手机浏览器和微信内置浏览器中正常显示（待真机测试）
- [ ] 全流程走通：注册 → 浏览 → 报名 → 提交 → 审核 → 成果发布（待联调）
- [x] 超管端可以查看公众注册用户和子女信息
- [x] 评委端可以看到评审任务和预设评语功能
- [x] 定向推送活动按城市/年龄过滤
- [x] 超管端活动监管只读（无创建/编辑/删除按钮）
- [x] 年龄校验在报名时生效

---

## 9. Day 1 完整工作记录（2026-03-24）

### 9.1 完成的设计工作

| 项目 | 说明 |
|------|------|
| 需求分析 | 广东省图项目需求、用户角色、参与者模型（家长-子女）、一号多身份方案 |
| 系统架构 | 多端架构（公众端/机构端/评委端/超管端）、公众租户方案、路由设计、API 设计 |
| 数据库设计 | 5 张表变更 + 1 张新表（children），含完整字段定义和 ER 关系 |
| 功能模块设计 | 9 个功能模块的详细交互设计 |
| 各端定位分析 | 超管端监管视角 vs 机构端操作视角、评委端工作流、公众端参与流程 |
| 术语对照 | 比赛→活动、个人赛→个人参与、赛果→成果 |
| 测试方案 | 188 条测试用例覆盖数据库/后端/前端/全链路 |

### 9.2 完成的开发工作

| 类别 | 工作量 | 说明 |
|------|--------|------|
| UI 主题改造 | 6 个核心文件 | Nunito 字体、Creative Indigo 主色、全组件圆角化 |
| 文案替换 | 71 个文件 + 数据库 | 比赛→活动、个人赛→个人参与、赛果→成果 |
| 数据库改造 | 5 张表 + 1 张新表 | Prisma Schema 同步、迁移执行 |
| 后端 API | 20 个端点 | 公众端完整 CRUD + 作品提交 + 公众用户管理 |
| 前端公众端 H5 | 9 个页面/组件 | 登录注册、活动大厅、详情、个人中心、子女管理、报名、作品 |
| 管理端适配 | 6 个页面修改 | 可见范围、租户类型、报名参与方式、主办机构列 |
| 超管端重构 | 菜单+页面+权限 | 4 级菜单重组、公众用户管理页、活动监管只读化 |
| 评委端修复 | 菜单+权限+路由 | 创建菜单、补齐权限、修复路由死循环 |
| 定向推送 | 全链路 | 数据库字段 + DTO + Service + 创建表单 + 公众端过滤 + 报名年龄校验 |
| 登录页改造 | 1 个文件重写 | 管理端登录页+公众端登录页双向跳转 |
| 机构管理页重写 | 1 个文件重写 | 去租户化、精简表格、搜索筛选、隐藏系统租户 |
| 初始化脚本 | 1 个脚本 | 广东省图租户初始化（权限/角色/菜单/管理员） |

### 9.3 测试执行结果

| 层级 | 测试项 | 通过 | Bug 数 |
|------|--------|------|--------|
| 数据库 | 23 | 23 | 0 |
| 后端 API | 37 | 37 | 4（已修复） |
| 前端自动化 | 33 | 33 | 1（已修复） |
| **合计** | **93** | **93** | **5（全部已修复）** |

### 9.4 发现并修复的 Bug

| 编号 | 严重度 | 问题 | 修复文件 |
|------|--------|------|---------|
| BUG-01 | 致命 | 创建活动时 visibility/targetCities/ageMin/ageMax 未写入数据库 | `contests.service.ts` |
| BUG-02 | 致命 | Visibility 枚举缺少 targeted 值 | `create-contest.dto.ts` |
| BUG-03 | 高 | @Public() 接口无法获取登录用户 JWT 信息 | `jwt-auth.guard.ts` |
| BUG-04 | 高 | 报名 targeted 活动查询条件硬编码 public | `public.service.ts` |
| BUG-05 | 中 | 超管端显示创建/编辑/删除按钮 | `contests/Index.vue` |

### 9.5 产出文件清单

**文档（9 个）：**
- `docs/guangdong-library-project/` 目录下 01-09 共 9 个文档

**后端新增文件（7 个）：**
- `backend/src/public/` 模块（module + controller + service + 3 个 DTO）
- `backend/scripts/init-guangdong-library.ts`

**前端新增文件（11 个）：**
- `frontend/src/layouts/PublicLayout.vue`
- `frontend/src/views/public/` 下 7 个页面
- `frontend/src/views/system/public-users/Index.vue`
- `frontend/src/api/public.ts`

**修改文件（约 30 个）：**
- Prisma Schema、全局样式、主题、App.vue、路由、菜单映射
- 6 个管理端页面（活动列表/报名/作品/评审/成果/通知）
- 登录页、机构管理页
- JWT Guard、Contest Service/DTO

### 9.6 待完成工作（Day 2 起）

| 优先级 | 工作 | 说明 |
|--------|------|------|
| P0 | 作品提交文件上传对接 COS | 当前作品提交表单已有，需对接腾讯云 COS 文件上传 |
| P0 | 全链路联调测试 | 4 条端到端流程走通 |
| P0 | 真机 H5 测试 | 微信内置浏览器兼容性 |
| P1 | 个人信息编辑完善 | 补充手机号字段 |
| P1 | 成果查看详情 | 活动成果发布后公众端展示评审结果 |
| P1 | 子女删除保护提示 | 有报名记录时给出警告 |
| P2 | 手机号+验证码登录 | 同事负责 |
| P2 | 微信扫码登录 | 同事负责 |
| P2 | 超管运营仪表盘 | 统计图表 |