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. 验收标准

一期上线验收清单

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

---

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	超管运营仪表盘	统计图表