library-picturebook-activity/docs/project/04-feature-design.md

功能模块设计

1. 模块总览

一期功能（三周内完成）

模块	优先级	说明
公众端注册/登录	P0	用户名+密码方式自主注册和登录
公众端活动大厅	P0	浏览公开活动列表，查看活动详情
子女管理	P0	添加/编辑/删除子女信息
活动报名	P0	选择参与者（自己/子女）并报名
作品提交	P0	上传绘本作品（图片/PDF）
个人中心	P0	个人信息、报名记录、作品列表
租户类型字段	P0	租户新增类型分类
活动可见范围	P0	新增"公开"选项
管理端适配	P0	报名记录展示参与者类型和子女信息

二期功能

模块	说明
手机号验证码登录	短信服务集成
微信扫码登录	微信开放平台 OAuth
一号多身份切换	同一账号在公众端和管理端切换
多机构联合举办	主办+协办模式

---

2. 公众端注册与登录

实现说明：登录与注册合并为同一页面 /p/login，通过 isRegister 标志切换表单。公众用户归属公众租户（code='public', tenantId=8），而非 tenant_id 为 NULL。

2.1 登录/注册页面（合一）

路由：/p/login

注册表单字段：

字段	类型	必填	说明
用户名	文本输入	是	4-20位字母数字下划线
密码	密码输入	是	6-20位，至少包含字母和数字
确认密码	密码输入	是	与密码一致
昵称	文本输入	是	2-20位，显示在界面上的名字
手机号	文本输入	否	预留字段，二期用于验证码登录
所在城市	文本输入	否	便于活动统计

登录表单字段：

• 用户名 / 手机号
• 密码

交互逻辑：

1. 页面底部有"切换到注册/切换到登录"链接，通过 isRegister 标志切换
2. 注册：前端校验 → 提交注册 → 后端创建用户（user_source = 'self_registered', 归属 public 租户）→ 自动登录 → 跳转活动大厅
3. 登录：公众用户登录不需要填写租户编码 → 后端在公众租户中查找匹配用户 → 登录成功 → 跳转活动大厅

2.3 与现有登录的关系

登录入口：
├── /p/login              → 公众端登录（无需租户编码）
└── /:tenantCode/login    → 管理端登录（现有，需要租户编码）

两套登录页面独立，共用同一个 Auth API（后端区分来源）

---

3. 公众端活动大厅

3.1 活动列表页

路由：/p/activities

页面元素：

• 顶部：搜索框（按活动名称搜索）
• 筛选：活动状态（报名中/进行中/已结束）
• 列表：活动卡片网格展示

活动卡片信息：

┌─────────────────────────┐
│  [活动封面图]             │
│  ┌─报名中─┐  ┌个人参与┐  │
├─────────────────────────┤
│  活动名称                │
│  主办：广东省立中山图书馆  │
│  报名时间：xx - xx       │
│  [查看详情]              │
└─────────────────────────┘

数据来源：

• 调用 /api/public/activities 接口
• 仅返回 visibility = 'public' 且 contest_state = 'published' 的活动
• 未登录用户也能浏览列表，但报名需要登录

3.2 活动详情页

路由：/p/activities/:id

页面结构：

┌─────────────────────────────────┐
│         活动封面/海报            │
├─────────────────────────────────┤
│  活动名称                       │
│  主办单位  |  活动类型  |  状态   │
├─────────────────────────────────┤
│  Tab: [活动详情] [活动公告] [成果] │
├─────────────────────────────────┤
│  活动详情内容（富文本）           │
│  附件下载                       │
├─────────────────────────────────┤
│  [立即报名] / [提交作品] 按钮    │
│  （根据活动阶段动态显示）         │
└─────────────────────────────────┘

按钮状态逻辑：

活动阶段	未登录	已登录未报名	已登录已报名
报名阶段	登录后报名	立即报名	已报名
提交阶段	登录查看	-	提交作品
评审阶段	-	-	评审中
已结束	查看成果	查看成果	查看成果

---

4. 子女管理

4.1 子女列表页

路由：/p/mine/children

页面元素：

• 子女卡片列表
• "添加子女"按钮

子女卡片：

┌─────────────────────────┐
│  [头像]  小明             │
│  8岁 | 三年级 | 广州      │
│  XX小学                  │
│  [编辑]  [删除]          │
└─────────────────────────┘

4.2 添加/编辑子女

弹窗表单字段：

字段	类型	必填	说明
姓名	文本	是	子女真实姓名
性别	选择	否	男/女
出生日期	日期选择	否	用于自动计算年龄
年级	文本/选择	否	如：大班、一年级
所在城市	文本	否
学校/幼儿园	文本	否	手动填写

4.3 删除保护

• 如果子女有关联的报名记录，提示"该子女有 N 个活动报名记录，删除后历史数据中将显示为'已删除子女'"
• 使用软删除（is_deleted = 1），不物理删除

---

5. 活动报名

5.1 报名流程

步骤1：选择参与者
├── 系统检测用户是否有子女
├── 无子女 → 跳过此步，以自己身份报名
└── 有子女 → 显示参与者选择页面
             ○ 我自己
             ○ 子女A（姓名，年龄）
             ○ 子女B（姓名，年龄）
             ＋ 添加新的子女

步骤2：填写报名信息
├── 参与者基本信息（自动带入，可编辑）
│   ├── 自己报名：显示用户昵称、城市
│   └── 子女报名：显示子女姓名、年龄、学校
├── 活动要求的附加信息（由活动定义，如：创作主题选择）
└── 指导老师信息（可选）

步骤3：确认提交
├── 确认报名信息
└── 提交 → 等待审核（如果活动开启了审核）/ 直接通过

5.2 报名数据存储

registrations 表记录：
├── user_id = 操作人（家长或独立参与者）
├── contest_id = 活动 ID
├── participant_type = 'self' 或 'child'
├── child_id = 子女 ID（仅 child 类型）
├── status = 审核状态
└── 其他现有字段不变

5.3 重复报名检测

• 同一用户不能以"自己"身份重复报名同一活动
• 同一子女不能被重复报名同一活动（通过 child_id 去重）
• 不同子女可以分别报名同一活动

---

6. 作品提交

6.1 提交页面

路由：/p/activities/:id/submit

前置条件：

• 用户已登录
• 用户/子女已报名该活动且报名状态为"通过"
• 活动处于"提交阶段"

表单字段：

字段	类型	必填	说明
作品名称	文本	是	绘本作品标题
作品描述	多行文本	否	创作说明
作品文件	文件上传	是	支持图片（JPG/PNG）和 PDF
封面图	图片上传	否	作品封面，用于列表展示

6.2 与现有作品模块的关系

复用现有 works 表和上传逻辑，新增关联：

• 如果是子女报名，作品记录关联 child_id（通过 registration 关联）
• 管理端查看作品时，能看到实际创作者（子女）的信息

---

7. 个人中心

7.1 个人中心首页

路由：/p/mine

页面结构：

┌─────────────────────────┐
│  [头像]  昵称             │
│  手机号  |  城市           │
│  [编辑个人信息]           │
├─────────────────────────┤
│  📋 我的报名（N）         │
│  🎨 我的作品（N）         │
│  👶 子女管理（N）         │
└─────────────────────────┘

7.2 我的报名

路由：/p/mine/registrations

列表项信息：

┌─────────────────────────────────┐
│  [活动封面]                      │
│  活动名称                        │
│  参与者：我自己 / 子女：小明       │
│  报名时间：2026-04-01            │
│  状态：待审核 / 已通过 / 已拒绝   │
│  [查看详情] [提交作品]            │
└─────────────────────────────────┘

7.3 我的作品

路由：/p/mine/works

展示该用户提交的所有作品（包括代子女提交的）。

---

8. 管理端适配

8.1 活动创建改造

活动创建表单新增字段：

活动可见范围：
○ 公开（所有注册用户可见）
○ 指定机构（选择机构列表）
○ 仅内部

当选择"公开"时，contest_tenants 字段不需要填写。

8.2 报名管理改造

报名记录表格新增列：

列名	说明
报名人	user.nickname（操作人）
参与者	自己报名显示用户名；子女报名显示"子女：小明"
参与方式	自己 / 代子女报名

筛选条件新增：

• 参与方式：全部 / 自己报名 / 代子女报名

8.3 租户管理改造

租户列表新增列：

• 租户类型：图书馆 / 幼儿园 / 学校 / 社会机构 / 其他

租户创建表单新增字段：

• 租户类型（下拉选择）