# 学员端开发需求整合确认文档

## 📋 **基于需求文档和数据库分析的整合确认**

我已经分析了《学员端开发需求文档.md》，并通过Docker命令直接查询了数据库表结构，获取了完整的字段定义和枚举值。现在整理出完整的技术规范和需要您确认的业务逻辑问题。

### 核心质量原则
1. **数据一致性第一**：页面显示数据与数据库数据必须100%一致
2. **功能完整性第一**：每个功能都要完整实现，不允许半成品
3. **用户体验第一**：每个交互都要符合预期，不允许异常
4. **代码质量第一**：不合格代码绝不允许合并

#### 数据库信息
- [✅] **数据库访问权限**：开发者是否有数据库读写权限？

- [ ✅] **数据库连接信息**：开发环境的数据库配置
  数据库配置信息如下：
  TYPE = mysql
  HOSTNAME = mysql
  DATABASE = niucloud
  USERNAME = niucloud
  PASSWORD = niucloud123

HOSTPORT = 3306
PREFIX = school_
CHARSET = utf8mb4
DEBUG = false

### 🔧 **数据库操作方法**
```bash
# 数据库连接信息
数据库：niucloud
用户名：niucloud
密码：niucloud123

# Docker命令查询示例
docker exec niucloud_mysql mysql -u niucloud -pniucloud123 -D niucloud -e "SHOW CREATE TABLE 表名;"
docker exec niucloud_mysql mysql -u niucloud -pniucloud123 -D niucloud -e "SELECT * FROM 表名 LIMIT 10;"
```

---

## 🔍 **已明确的需求信息**

### 1. **用户认证和登录** ✅ 已明确
- **登录方式**：手机号+密码，支持微信一键登录
- **数据关联**：`school_customer_resources` 主表，通过 `member_id` 关联 `member` 表
- **微信绑定**：需要获取小程序和公众号openid，绑定到对应字段
- **首次登录**：可提示设置密码但不强制

### 2. **个人信息管理** ✅ 已明确
- **用户信息**：只展示姓名和欢迎语，不可修改
- **学员信息**：可修改学员的基本信息
- **头像上传**：支持，存储在 `headimg` 字段，腾讯云COS，2M以下

### 3. **体测数据功能** ✅ 已明确
- **数据来源**：`school_physical_test` 表
- **展示内容**：身高、体重、体测报告PDF
- **趋势图**：折线图展示身高体重趋势

### 4. **课程预约功能** ✅ 已明确
- **预约规则**：只能预约等待位课程，取消需提前6小时
- **数据表**：`school_person_course_schedule` 插入等待位记录
- **冲突处理**：同一时间段只能预约一节课

### 5. **支付功能** ✅ 已明确
- **支付方式**：微信支付、微信扫码支付
- **订单表**：`school_order_table`

### 6. **知识库功能** ✅ 已明确
- **数据表**：`school_lesson_course_teaching`
- **内容渲染**：富文本方式
- **权限控制**：根据 `student_id` 字段（逗号分割）

### 7. **消息管理功能** ✅ 已明确
- **数据表**：`school_chat_messages`
- **消息推送**：公众号模板消息推送

---

## ✅ **数据库表字段枚举值已确认**

### 1. **订单类型枚举** (`school_order_table.order_type`)
**已确认的枚举值**：
```
order_type 字段注释：'订单类型1新订单2续费订单3内部员工订单4 转校 5 客户内转课订单'
- 1：新订单
- 2：续费订单
- 3：内部员工订单
- 4：转校
- 5：客户内转课订单
```

### 2. **知识库分类枚举** (`school_lesson_course_teaching.table_type`)
**已确认的枚举值**：
```
table_type 字段注释：'类型 1课程教学大纲 2跳绳教案库 3增高教案库 4篮球教案库 5强化教案库 6空中忍者教案库 7少儿安防教案库 8体能教案库 9热身动作库 10体能动作库 11趣味游戏库 12放松动作库 13训练内容 14训练视频 15课后作业 16优秀一堂课 17空中忍者 18篮球动作 19跳绳动作 20跑酷动作 21安防动作 22标准化动作 233-6岁体测 247+体测 253-6岁体测讲解—解读 267+岁体测讲解—解读 27互动游戏 28套圈游戏 29鼓励方式'

主要分类：
- 1：课程教学大纲
- 2：跳绳教案库
- 3：增高教案库
- 4：篮球教案库
- 5：强化教案库
- 6：空中忍者教案库
- 7：少儿安防教案库
- 8：体能教案库
- 9：热身动作库
- 10：体能动作库
- 11：趣味游戏库
- 12：放松动作库
- 13：训练内容
- 14：训练视频
- 15：课后作业
- 16：优秀一堂课
- 17-22：各种动作库
- 23-26：体测相关
- 27-29：游戏和鼓励方式
```

### 3. **消息类型枚举** (`school_chat_messages`)
**已确认的枚举值**：

**`from_type` 字段**：
```sql
enum('personnel','customer','system')
注释：'发送者类型|personnel=员工,customer=学生(客户)system（系统消息）'
- personnel：员工
- customer：学生(客户)
- system：系统消息
```

**`message_type` 字段**：
```sql
enum('text','img','order','student_courses','person_course_schedule')
注释：'消息类型|text=文本,img=图片消息，订单'消息order'学员课程变动消息student_courses'课程安排消息person_course_schedule'
- text：文本消息
- img：图片消息
- order：订单消息
- student_courses：学员课程变动消息
- person_course_schedule：课程安排消息
```

### 4. **课程状态枚举** (`school_course_schedule.status`)
**已确认的枚举值**：
```sql
enum('pending','upcoming','ongoing','completed')
注释：'课程状态: pending-待开始, upcoming-即将开始, ongoing-进行中, completed-已结束'
- pending：待开始
- upcoming：即将开始
- ongoing：进行中
- completed：已结束
```

### 5. **订单状态枚举** (`school_order_table.order_status`)
**已确认的枚举值**：
```sql
enum('pending','paid','signed','completed','transfer')
注释：'订单状态: pending-待支付, paid-已支付,signed待签约，completed已完成，transfer转学'
- pending：待支付
- paid：已支付
- signed：待签约
- completed：已完成
- transfer：转学
```

### 6. **支付类型枚举** (`school_order_table.payment_type`)
**已确认的枚举值**：
```sql
enum('cash','scan_code','subscription')
注释：'付款类型: cash-现金支付, scan_code-扫码支付, subscription-订阅支付wxpay_online微信在线代付'
- cash：现金支付
- scan_code：扫码支付
- subscription：订阅支付
- wxpay_online：微信在线代付（注释中提到但enum中未包含）
```

## ✅ **数据表结构已确认**

### 1. **体测数据表字段** (`school_physical_test`)
**完整字段结构**：
```sql
CREATE TABLE `school_physical_test` (
  `id` int NOT NULL AUTO_INCREMENT COMMENT '体测编号',
  `resource_id` int NOT NULL COMMENT '资源ID',
  `student_id` int DEFAULT NULL COMMENT '学员ID',
  `age` int NOT NULL DEFAULT '0' COMMENT '学员年龄',
  `height` decimal(5,2) NOT NULL COMMENT '身高',
  `weight` decimal(5,2) NOT NULL COMMENT '体重',
  `coach_id` int DEFAULT NULL COMMENT '教练ID',
  `seated_forward_bend` decimal(5,2) DEFAULT NULL COMMENT '坐位体前屈',
  `sit_ups` decimal(5,2) DEFAULT NULL COMMENT '仰卧卷腹',
  `push_ups` decimal(5,2) DEFAULT NULL COMMENT '九十度仰卧撑',
  `flamingo_balance` decimal(5,2) DEFAULT NULL COMMENT '火烈鸟平衡测试',
  `thirty_sec_jump` decimal(5,2) DEFAULT NULL COMMENT '三十秒双脚连续跳',
  `standing_long_jump` decimal(5,2) DEFAULT NULL COMMENT '立定跳远',
  `agility_run` decimal(5,2) DEFAULT NULL COMMENT '4乘10m灵敏折返跑',
  `balance_beam` decimal(5,2) DEFAULT NULL COMMENT '走平衡木',
  `tennis_throw` decimal(5,2) DEFAULT NULL COMMENT '网球掷远',
  `ten_meter_shuttle_run` decimal(5,2) DEFAULT NULL COMMENT '十米往返跑',
  `physical_test_report` text COMMENT '体测报告附件（多文件）',
  `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`)
);
```

**体测指标分类**：
- **基础指标**：身高、体重、年龄
- **柔韧性测试**：坐位体前屈
- **力量测试**：仰卧卷腹、九十度仰卧撑
- **平衡性测试**：火烈鸟平衡测试、走平衡木
- **爆发力测试**：三十秒双脚连续跳、立定跳远、网球掷远
- **敏捷性测试**：4乘10m灵敏折返跑、十米往返跑
- **体测报告**：PDF附件（多文件，逗号分割）

### 2. **订单表字段** (`school_order_table`)
**完整字段结构**：
```sql
CREATE TABLE `school_order_table` (
  `id` int NOT NULL AUTO_INCREMENT COMMENT '订单编号',
  `payment_id` varchar(255) DEFAULT NULL COMMENT '支付编号',
  `order_type` varchar(255) DEFAULT NULL COMMENT '订单类型1新订单2续费订单3内部员工订单4 转校 5 客户内转课订单',
  `order_status` enum('pending','paid','signed','completed','transfer') DEFAULT 'pending' COMMENT '订单状态',
  `payment_type` enum('cash','scan_code','subscription') NOT NULL COMMENT '付款类型',
  `order_amount` decimal(10,2) NOT NULL COMMENT '订单金额',
  `discount_amount` decimal(10,2) DEFAULT NULL COMMENT '优惠金额',
  `course_id` int NOT NULL COMMENT '课程ID',
  `class_id` int DEFAULT NULL COMMENT '班级ID',
  `staff_id` int NOT NULL COMMENT '人员ID|员工表school_personnel.id',
  `resource_id` int NOT NULL COMMENT '资源ID|客户资源表school_customer_resources.id',
  `student_id` int NOT NULL COMMENT '学员 id',
  `campus_id` int NOT NULL COMMENT '校区ID',
  `course_plan_id` int DEFAULT NULL COMMENT '课程计划 id',
  `gift_id` int DEFAULT NULL COMMENT '赠品 id',
  `after_sales_status` varchar(50) DEFAULT NULL COMMENT '售后状态',
  `after_sales_reason` text COMMENT '售后原因',
  `after_sales_time` timestamp NULL DEFAULT NULL COMMENT '售后时间',
  `payment_time` timestamp NULL DEFAULT NULL COMMENT '支付时间',
  `subscription_payment_time` timestamp NULL DEFAULT NULL COMMENT '订阅支付生成时间',
  `accounting_time` timestamp NULL DEFAULT NULL COMMENT '核算时间',
  `remark` varchar(512) DEFAULT NULL COMMENT '订单备注',
  `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
  PRIMARY KEY (`id`)
);
```

### 3. **业务逻辑确认**

#### 3.1 学员选择逻辑
**问题**：一个家长可能有多个孩子，学员端如何处理？
**需要确认**：
- 登录后是否需要选择孩子？
- 如何在不同孩子之间切换？
- 数据展示是否需要按孩子分别显示？

#### 3.2 收藏功能
**问题**：是否需要收藏功能？
**如果需要，请确认**：
- 可以收藏哪些内容？（知识库文章、课程等）
- 是否需要创建 `school_student_favorites` 表？

#### 3.3 合同状态管理
**问题**：合同状态的具体定义
**需要确认**：
```
school_contract_sign.status 字段的枚举值：
- 待签署：pending?
- 已签署：signed?
- 已生效：active?
- 已到期：expired?
```

### 4. **页面功能细节确认**

#### 4.1 个人信息页面
**基于您的说明，确认页面结构**：
```
[用户信息区域]
- 显示：{name} 你好，今天是星期{x}
- 入会时间：{create_year_month}
- 年龄：{age} (根据最新学员生日计算)

[学员信息区域] - 可编辑
- 学员选择下拉框 (如果有多个孩子)
- 学员基本信息编辑
- 头像上传功能

[体测数据区域] - 只读
- 身高、体重显示
- 体测报告PDF预览/下载
```

#### 4.2 消息页面渲染
**基于 `message_type` 字段，确认渲染方式**：
- 不同 `message_type` 对应的页面渲染方式？
- 消息列表和详情页的展示差异？

---

## 📝 **需要创建的数据字典**

基于数据库表结构分析，需要在 `school_sys_dict` 表中存储以下枚举数据：

### 1. 订单类型字典
```sql
INSERT INTO `school_sys_dict` (`name`, `key`, `dictionary`) VALUES
('订单类型', 'order_type', '[
  {"name":"新订单","value":"1"},
  {"name":"续费订单","value":"2"},
  {"name":"内部员工订单","value":"3"},
  {"name":"转校","value":"4"},
  {"name":"客户内转课订单","value":"5"}
]');
```

### 2. 订单状态字典
```sql
INSERT INTO `school_sys_dict` (`name`, `key`, `dictionary`) VALUES
('订单状态', 'order_status', '[
  {"name":"待支付","value":"pending"},
  {"name":"已支付","value":"paid"},
  {"name":"待签约","value":"signed"},
  {"name":"已完成","value":"completed"},
  {"name":"转学","value":"transfer"}
]');
```

### 3. 支付类型字典
```sql
INSERT INTO `school_sys_dict` (`name`, `key`, `dictionary`) VALUES
('支付类型', 'payment_type', '[
  {"name":"现金支付","value":"cash"},
  {"name":"扫码支付","value":"scan_code"},
  {"name":"订阅支付","value":"subscription"},
  {"name":"微信在线代付","value":"wxpay_online"}
]');
```

### 4. 知识库分类字典
```sql
INSERT INTO `school_sys_dict` (`name`, `key`, `dictionary`) VALUES
('知识库分类', 'knowledge_table_type', '[
  {"name":"课程教学大纲","value":"1"},
  {"name":"跳绳教案库","value":"2"},
  {"name":"增高教案库","value":"3"},
  {"name":"篮球教案库","value":"4"},
  {"name":"强化教案库","value":"5"},
  {"name":"空中忍者教案库","value":"6"},
  {"name":"少儿安防教案库","value":"7"},
  {"name":"体能教案库","value":"8"},
  {"name":"热身动作库","value":"9"},
  {"name":"体能动作库","value":"10"},
  {"name":"趣味游戏库","value":"11"},
  {"name":"放松动作库","value":"12"},
  {"name":"训练内容","value":"13"},
  {"name":"训练视频","value":"14"},
  {"name":"课后作业","value":"15"},
  {"name":"优秀一堂课","value":"16"}
]');
```

### 5. 消息发送类型字典
```sql
INSERT INTO `school_sys_dict` (`name`, `key`, `dictionary`) VALUES
('消息发送类型', 'message_from_type', '[
  {"name":"员工","value":"personnel"},
  {"name":"学生(客户)","value":"customer"},
  {"name":"系统消息","value":"system"}
]');
```

### 6. 消息内容类型字典
```sql
INSERT INTO `school_sys_dict` (`name`, `key`, `dictionary`) VALUES
('消息内容类型', 'message_type', '[
  {"name":"文本消息","value":"text"},
  {"name":"图片消息","value":"img"},
  {"name":"订单消息","value":"order"},
  {"name":"学员课程变动消息","value":"student_courses"},
  {"name":"课程安排消息","value":"person_course_schedule"}
]');
```

### 7. 课程状态字典
```sql
INSERT INTO `school_sys_dict` (`name`, `key`, `dictionary`) VALUES
('课程状态', 'course_schedule_status', '[
  {"name":"待开始","value":"pending"},
  {"name":"即将开始","value":"upcoming"},
  {"name":"进行中","value":"ongoing"},
  {"name":"已结束","value":"completed"}
]');
```

---

## ✅ **业务逻辑已确认**

### 1. **多孩子处理逻辑**
- **登录流程**：登录后获取孩子列表，默认选择最新添加的孩子
- **切换方式**：在孩子信息卡片处设置切换按钮
- **数据展示**：所有数据根据选中的孩子ID查询
- **页面结构**：孩子选择卡片下方显示各功能模块入口

### 2. **收藏功能**
- **不需要收藏功能**：知识内容由工作人员分享给学员，学员只能查看

### 3. **体测数据展示**
- **展示指标**：只显示身高和体重
- **趋势图**：展示身高和体重的变化趋势
- **体测报告**：
  - 显示"体测附件"或"体测记录"图标
  - 点击可在应用内预览PDF
  - 支持将PDF转换为图片分享

### 4. **消息页面渲染规则**
- **text消息**：纯文本显示
- **img消息**：缩略图+点击放大
- **order消息**：显示订单号、金额、状态、购买课程信息，支付成功后显示"查看合同"或"签署合同"按钮
- **student_courses消息**：课程变动通知（停课、签到核销等），样式与文本消息有差别，无交互
- **person_course_schedule消息**：预约课程生效通知，显示时间地点，点击查看课程详情
- **已读/未读状态**：需要添加数据库字段支持

### 5. **支付功能**
- **支付流程**：简化为一键支付，直接唤起支付
- **支付成功**：更新订单列表状态
- **支付失败**：提示失败，不修改数据库
- **订单管理**：只显示订单记录，支持按课程、时间筛选

### 6. **课程预约**
- **预约确认**：无需人工确认，可发消息通知教练和教务
- **冲突处理**：相同时间段已有预约时提示不能重复预约
- **取消原因**：可填写但非必填，需检查数据库字段

### 7. **合同管理**
- **显示信息**：合同名称、签署状态、签署时间
- **签署流程**：查看合同 → 填写信息 → 上传签名 → 提交
- **文档下载**：已签署合同可下载，需将Word转换为PDF或图片

### 8. **知识库权限**
- **内容显示**：只显示当前选中孩子可访问的内容
- **学习记录**：不需要，仅支持浏览

## 🔧 **需要的技术实现和数据库修改**

### 1. **需要重新设计的数据表**

#### 1.1 **课程预约功能** - 修改现有表
**方案**：使用现有的 `school_person_course_schedule` 表，通过 `course_type=3` 标识等待位预约
**需要添加的字段**：
```sql
-- 检查并添加取消原因字段
ALTER TABLE `school_person_course_schedule` ADD COLUMN `cancel_reason` varchar(255) DEFAULT NULL COMMENT '取消预约原因';

-- 确保有软删除字段（如果没有的话）
-- ALTER TABLE `school_person_course_schedule` ADD COLUMN `deleted_at` int DEFAULT 0 COMMENT '删除时间，0为未删除';
```

**预约数据管理逻辑**：
- **新预约**：插入记录，设置 `course_type=3`（等待位）
- **预约生效**：员工将 `course_type` 改为正式课程类型
- **取消预约**：设置 `deleted_at` 为当前时间戳，可选填写 `cancel_reason`
- **预约查询**：查询 `course_type=3` 且 `deleted_at=0` 的记录

#### 1.2 **消息已读状态** - 需要修改现有表
**问题**：`school_chat_messages` 表缺少已读状态字段
**解决方案**：添加字段
```sql
ALTER TABLE `school_chat_messages` ADD COLUMN `is_read` tinyint(1) DEFAULT 0 COMMENT '是否已读 0-未读 1-已读';
ALTER TABLE `school_chat_messages` ADD COLUMN `read_time` timestamp NULL DEFAULT NULL COMMENT '已读时间';
```

#### 1.3 **合同签署数据** - 需要修改现有表
**问题**：合同签署可能需要存储填写的表单数据
**解决方案**：检查并补充字段
```sql
-- 检查 school_contract_sign 表是否有以下字段，如果没有需要添加：
ALTER TABLE `school_contract_sign` ADD COLUMN `form_data` text COMMENT '签署时填写的表单数据JSON';
ALTER TABLE `school_contract_sign` ADD COLUMN `signature_image` varchar(500) COMMENT '签名图片路径';
ALTER TABLE `school_contract_sign` ADD COLUMN `signed_document` varchar(500) COMMENT '已签署文档路径';
```

#### 1.4 **支付类型枚举** - 需要修改现有表
**问题**：`school_order_table.payment_type` 枚举中缺少 `wxpay_online`
**解决方案**：修改枚举值
```sql
ALTER TABLE `school_order_table` MODIFY COLUMN `payment_type`
enum('cash','scan_code','subscription','wxpay_online') NOT NULL
COMMENT '付款类型: cash-现金支付, scan_code-扫码支付, subscription-订阅支付, wxpay_online-微信在线代付';
```

### 2. **不需要新建表的功能**

#### 2.1 **收藏功能** - 不需要
**原因**：您明确表示不需要收藏功能

#### 2.2 **体测数据** - 现有表足够
**原因**：`school_physical_test` 表已包含所需的身高、体重和PDF报告字段

#### 2.3 **知识库** - 现有表足够
**原因**：`school_lesson_course_teaching` 表已有 `student_ids` 字段控制权限

#### 2.4 **订单管理** - 现有表足够
**原因**：`school_order_table` 表字段完整，只需要修改支付类型枚举

#### 2.5 **个人信息** - 现有表足够
**原因**：`school_student` 和 `school_customer_resources` 表已满足需求

### 2. **Word文档转换库需求**
**合同下载需要Word转PDF/图片功能，需要检查后端是否有以下库：**
- **PHP Word转PDF**：`phpoffice/phpword` + `dompdf/dompdf` 或 `tecnickcom/tcpdf`
- **Word转图片**：需要 `imagick` 扩展 或 `LibreOffice` 命令行工具
- **推荐方案**：使用 `phpoffice/phpword` + `dompdf/dompdf` 实现Word转PDF

### 3. **PDF转图片分享功能**
**体测报告分享需要PDF转图片：**
- 使用 `imagick` 扩展：`$imagick = new Imagick('file.pdf[0]');`
- 或使用 `spatie/pdf-to-image` 包

### 4. **小程序PDF预览**
**UniApp内PDF预览实现：**
- 使用 `uni.downloadFile()` 下载PDF
- 使用 `uni.openDocument()` 打开PDF预览
- 或集成第三方PDF预览组件

---

## 📊 **最终数据表修改总结**

### ✅ **需要修改的表（共3个）**

#### 1. **school_person_course_schedule** - 课程预约
```sql
-- 添加取消原因字段
ALTER TABLE `school_person_course_schedule` ADD COLUMN `cancel_reason` varchar(255) DEFAULT NULL COMMENT '取消预约原因';
```
**预约逻辑**：
- 新预约：`course_type=3`（等待位）
- 取消预约：设置 `deleted_at` 值 + 可选 `cancel_reason`

#### 2. **school_chat_messages** - 消息已读状态
```sql
ALTER TABLE `school_chat_messages` ADD COLUMN `is_read` tinyint(1) DEFAULT 0 COMMENT '是否已读 0-未读 1-已读';
ALTER TABLE `school_chat_messages` ADD COLUMN `read_time` timestamp NULL DEFAULT NULL COMMENT '已读时间';
```

#### 3. **school_order_table** - 支付类型补充
```sql
ALTER TABLE `school_order_table` MODIFY COLUMN `payment_type`
enum('cash','scan_code','subscription','wxpay_online') NOT NULL
COMMENT '付款类型: cash-现金支付, scan_code-扫码支付, subscription-订阅支付, wxpay_online-微信在线代付';
```

### ✅ **需要检查的表（1个）**
- **school_contract_sign** - 检查是否有 `form_data`、`signature_image`、`signed_document` 字段

### ✅ **不需要新建的表**
- 所有功能都可以使用现有表结构实现
- 无需创建新的数据表

---

## 🎯 **开发任务规划**

**所有需求已明确，数据表设计已确定，现在可以开始制定详细的开发计划：**

1. **数据库设计完善**：执行上述3个表的字段修改 + 7个数据字典插入
2. **后端API开发**：9个功能模块的接口实现
3. **前端页面开发**：UniApp小程序页面实现
4. **第三方集成**：支付、PDF处理、图片转换
5. **测试验收**：功能测试和用户体验验证

**准备开始执行开发计划！**