# PHP后端开发规划

## 已完成接口

### 1. 学员课程信息接口

**描述**: 获取学员课程信息，用于前端CourseInfoCard组件使用

**接口**: `GET /api/getStudentCourseInfo`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| resource_id | int | 是 | 资源ID |
| member_id | string | 否 | 会员ID |
| student_id | int | 否 | 学员ID(优先级高于member_id) |

**响应示例**:
```json
{
  "code": 1,
  "message": "success",
  "data": [
    {
      "id": 1,
      "course_name": "篮球课",
      "total_count": 24,
      "used_count": 8,
      "formal_hours": 20,
      "gift_hours": 4,
      "used_formal_hours": 6,
      "used_gift_hours": 2,
      "leave_count": 1,
      "start_date": "2024-01-01",
      "end_date": "2024-12-31",
      "expiry_date": "2024-06-30",
      "status": "active",
      "course_type": "常规课",
      "teacher_name": "张老师",
      "course_price": 2880.00,
      "class_duration": 90,
      "create_time": "2024-01-01 10:00:00",
      "remark": "备注信息"
    }
  ]
}
```

**涉及数据表**:
- `school_customer_resources` - 资源表
- `school_student` - 学员表
- `school_course` - 课程表
- `school_student_course` - 学员课程关联表
- `school_course_schedule` - 课程排期表
- `school_attendance` - 考勤表

**SQL查询逻辑参考**:
```sql
SELECT 
    sc.id,
    sc.course_name,
    ssc.total_count,
    ssc.used_count,
    ssc.formal_hours,
    ssc.gift_hours,
    ssc.used_formal_hours,
    ssc.used_gift_hours,
    ssc.leave_count,
    ssc.start_date,
    ssc.end_date,
    ssc.expiry_date,
    ssc.status,
    sc.course_type,
    sp.name as teacher_name,
    ssc.course_price,
    sc.class_duration,
    ssc.create_time,
    ssc.remark
FROM school_student_course ssc
LEFT JOIN school_course sc ON ssc.course_id = sc.id
LEFT JOIN school_personnel sp ON sc.teacher_id = sp.id
WHERE ssc.student_id = ? 
    AND ssc.resource_id = ?
    [AND ssc.member_id = ?]
ORDER BY ssc.create_time DESC
```

**状态说明**:
- `active`: 正常使用
- `completed`: 课程完结
- `expired`: 已过期
- `pending`: 待激活

**业务逻辑**:
1. 优先使用student_id查询，其次使用member_id
2. 计算剩余课时：remaining_count = total_count - used_count
3. 检查课程是否过期，基于expiry_date
4. 返回完整的课程信息及使用情况
5. 支持多个课程返回

**优化建议**:
- 使用Redis缓存常用查询结果
- 对学员课程查询添加索引优化
- 考虑分页处理大量数据

## 已新增接口

### 2. 服务列表接口

**描述**: 获取学员服务记录列表

**接口**: `GET /api/xy/service/list`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| student_id | int | 是 | 学员ID |

**响应示例**:
```json
{
  "code": 1,
  "message": "操作成功", 
  "data": [
    {
      "id": 1,
      "service_name": "测试服务",
      "preview_image_url": "图片URL",
      "description": "服务描述",
      "service_type": "服务类型",
      "status": "active",
      "logs": [
        {
          "id": 1,
          "status": 1,
          "service_content": "服务内容",
          "service_staff": "教练姓名",
          "service_time": "服务时间",
          "duration": "持续时间",
          "customer_feedback": "客户反馈",
          "service_rating": 5,
          "remark": "备注",
          "course_name": "课程名称",
          "updated_at": "更新时间"
        }
      ],
      "total_count": 3,
      "completed_count": 3
    }
  ]
}
```

### 3. 体测记录接口（增删改查）

**描述**: 体测记录的完整CRUD操作

**接口列表**:
- `GET /api/xy/physicalTest` - 获取体测记录列表
- `GET /api/xy/physicalTest/info` - 获取体测记录详情
- `POST /api/xy/physicalTest/add` - 添加体测记录
- `POST /api/xy/physicalTest/edit` - 编辑体测记录  
- `POST /api/xy/physicalTest/delete` - 删除体测记录

**数据表结构**:
```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 '30秒跳绳',
`standing_long_jump` decimal(5,2) DEFAULT NULL COMMENT '立定跳远',
`agility_run` decimal(5,2) DEFAULT NULL COMMENT '敏捷跑',
`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 '10米折返跑',
`created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`updated_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`physical_test_report` text CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci COMMENT '体测报告附件（多文件）',
PRIMARY KEY (`id`) USING BTREE
)
```

### 4. 学习计划接口（基于自定义表单）

**描述**: 基于diy_form自定义表单的学习计划管理系统

**接口列表**:
- `GET /api/xy/studyPlan` - 获取学习计划列表
- `GET /api/xy/studyPlan/info` - 获取学习计划详情
- `POST /api/xy/studyPlan/add` - 添加学习计划
- `POST /api/xy/studyPlan/edit` - 编辑学习计划
- `POST /api/xy/studyPlan/delete` - 删除学习计划
- `POST /api/xy/studyPlan/updateProgress` - 更新学习计划进度

**数据表**: 使用diy_form自定义表单系统
- `school_diy_form` - 表单定义 (type='study_plan')
- `school_diy_form_fields` - 字段定义
- `school_diy_form_records` - 记录数据

**响应数据结构**:
```json
{
  "code": 1,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "student_id": 1,
      "plan_name": "基础体能训练计划",
      "plan_content": "针对学员的基础体能进行系统性训练",
      "plan_type": "体能训练",
      "status": "active",
      "progress": 65,
      "start_date": "2024-01-15",
      "end_date": "2024-03-15",
      "target_goals": "提升学员整体体能水平",
      "learning_materials": "体能训练器材、训练计划表",
      "evaluation_criteria": "体能测试成绩、训练完成度",
      "remark": "备注信息",
      "create_time": "2024-01-10 14:30:00",
      "update_time": "2024-01-10 14:30:00"
    }
  ]
}
```

## 前端集成状态

### ✅ 已完成联调的接口：
1. **课程信息** - `getStudentCourseInfo` (完整联调，Mock与API一致)
2. **服务列表** - `getStudentServiceList` (API正常工作)
3. **体测记录** - `xy_physicalTest` (列表API + 增删改查API完整)
4. **学习计划** - `getStudyPlanList` (基于自定义表单的完整CRUD)

### 🔧 技术实现特点：
- **统一响应格式**: 所有接口使用统一的 `{code: 1, data: [], msg: "操作成功"}` 格式
- **JWT认证**: 所有接口通过token头进行身份验证
- **参数验证**: 完整的参数校验和错误处理
- **数据库事务**: 确保数据一致性
- **错误处理**: 完善的异常处理和日志记录

### 5. 个人资料接口（员工信息管理）

**描述**: 员工个人资料的查看和编辑功能，涉及基础信息和详细信息两个数据表

**接口列表**:
- `GET /api/getPersonnelInfo` - 获取员工基础信息
- `POST /api/updatePersonnelInfo` - 更新员工基础信息  
- `GET /api/getPersonnelDetailInfo` - 获取员工详细信息
- `POST /api/updatePersonnelDetailInfo` - 更新员工详细信息

#### 基础信息接口

**接口**: `GET /api/getPersonnelInfo`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 否 | 员工ID，不传则获取当前登录用户信息 |

**响应示例**:
```json
{
  "code": 1,
  "message": "操作成功",
  "data": {
    "id": 1,
    "name": "张三",
    "head_img": "/uploads/avatar/20240101/avatar.jpg",
    "gender": 1,
    "birthday": "1990-05-15", 
    "phone": "13800138000",
    "email": "zhangsan@example.com",
    "wx": "zhangsan_wx",
    "address": "北京市朝阳区XXX小区",
    "native_place": "山东济南",
    "education": "本科",
    "profile": "个人简介内容",
    "emergency_contact_phone": "13900139000",
    "id_card_front": "/uploads/idcard/front.jpg",
    "id_card_back": "/uploads/idcard/back.jpg",
    "employee_number": "EMP001",
    "status": 2,
    "account_type": "teacher",
    "join_time": "2024-01-01 09:00:00",
    "create_time": "2024-01-01 09:00:00",
    "update_time": "2024-01-01 09:00:00"
  }
}
```

**接口**: `POST /api/updatePersonnelInfo`

**请求参数**:
```json
{
  "id": 1,
  "name": "张三",
  "head_img": "/uploads/avatar/20240101/avatar.jpg",
  "gender": 1,
  "birthday": "1990-05-15",
  "phone": "13800138000", 
  "email": "zhangsan@example.com",
  "wx": "zhangsan_wx",
  "address": "北京市朝阳区XXX小区",
  "native_place": "山东济南",
  "education": "本科",
  "profile": "个人简介内容",
  "emergency_contact_phone": "13900139000",
  "id_card_front": "/uploads/idcard/front.jpg",
  "id_card_back": "/uploads/idcard/back.jpg"
}
```

#### 详细信息接口

**接口**: `GET /api/getPersonnelDetailInfo`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| person_id | int | 是 | 员工ID |

**响应示例**:
```json
{
  "code": 1,
  "message": "操作成功",
  "data": {
    "id": 1,
    "person_id": 1,
    "name": "张三花名",
    "store": "朝阳校区",
    "ethnicity": "汉族",
    "age": 30,
    "tenure": "3年2个月",
    "regular_date": "2024-07-01",
    "is_regular": "是",
    "politics": "群众",
    "university": "北京大学",
    "major": "体育教育",
    "graduation_date": "2015-06-30",
    "household_place": "山东省济南市",
    "household_type": "城镇户口",
    "household_address": "山东省济南市历下区XXX街道",
    "current_address": "北京市朝阳区XXX小区",
    "emergency_contact": "张父",
    "emergency_phone": "13900139000",
    "marital_status": "已婚",
    "bank_card": "6222021234567890123",
    "bank_name": "中国银行北京分行",
    "contract_expire": "2025-12-31",
    "is_rehired": "否",
    "remark": "备注信息",
    "created_at": "2024-01-01 09:00:00",
    "updated_at": "2024-01-01 09:00:00"
  }
}
```

**接口**: `POST /api/updatePersonnelDetailInfo`

**请求参数**: 与详细信息响应数据格式相同

#### 涉及数据表:
- `school_personnel` - 员工基础信息表
- `school_personnel_info` - 员工详细信息表

#### 字段重复处理：
基于数据库分析，需要删除以下重复字段：
```sql
-- 删除重复字段
ALTER TABLE school_personnel_info 
DROP COLUMN birthday, 
DROP COLUMN education, 
DROP COLUMN native_place;
```

#### 业务逻辑:
1. **只读字段**: `employee_number`（员工编号）、`tenure`（司龄）只能查看不能修改
2. **司龄计算**: 根据`join_time`自动计算并更新
3. **图片上传**: 支持头像、身份证正反面图片上传
4. **数据验证**: 
   - 手机号格式验证
   - 邮箱格式验证
   - 身份证号码验证
5. **权限控制**: 员工只能编辑自己的信息

#### 前端页面:
- 路径: `/pages/common/profile/personal_info.vue`
- 功能: 查看、编辑员工个人资料
- 特性: 响应式设计、表单验证、图片上传、分段展示

---

*最后更新：2024-12-29*
*备注：后续接口开发请及时更新此文档*