study-api-v2/docs/学生管理系统使用指南.md

# 学生管理系统使用指南

## 概述

学生管理系统是一个完整的学生信息管理解决方案，支持学生基本信息管理、家长关系管理、班级分配、状态管理等功能。

## 主要功能

### 1. 学生基本信息管理
- 学生CRUD操作
- 家长CRUD操作
- 用户名、邮箱、手机号唯一性验证
- 密码加密存储

### 2. 家长子女关系管理
- 家长和子女关系绑定
- 家长查看子女信息
- 关系解除功能

### 3. 班级管理
- 学生班级分配
- 班级转移功能
- 班级历史记录
- 批量操作

### 4. 状态管理
- 用户状态控制（正常/禁用/欠费/未激活）
- 密码重置功能
- 统计信息查看

## 数据库设计

### 学生表 (student)
```sql
-- 主要字段
id              -- 主键
username        -- 用户名（唯一）
real_name       -- 真实姓名
password        -- 加密密码
salt            -- 密码盐值
role            -- 角色（2：学生，3：家长）
grade_id        -- 年级ID
parent_id       -- 家长ID
email           -- 邮箱（唯一）
phone_number    -- 手机号（唯一）
status          -- 状态（0：禁用，1：正常，2：欠费，3：未激活）
sex             -- 性别（0：不填，1：男，2：女）
reg_time        -- 注册时间
reg_ip          -- 注册IP
-- 其他字段...
```

### 学生班级关联表 (student_class)
```sql
-- 主要字段
id              -- 主键
student_id      -- 学生ID
school_id       -- 学校ID
class_id        -- 班级ID
join_time       -- 入班时间
leave_time      -- 离班时间
status          -- 状态（1：正常在读，2：已转班，3：已毕业，4：退学）
remark          -- 备注
created_at      -- 创建时间
updated_at      -- 更新时间
```

## API接口

### 学生管理接口

#### 1. 获取学生列表
```
GET/POST /admin/student/list
```

**参数:**
- `page`: 页码
- `page_size`: 每页数量
- `username`: 用户名（模糊搜索）
- `real_name`: 真实姓名（模糊搜索）
- `email`: 邮箱（模糊搜索）
- `phone_number`: 手机号（模糊搜索）
- `role`: 角色（2：学生，3：家长）
- `status`: 状态
- `sex`: 性别
- `grade_id`: 年级ID
- `parent_id`: 家长ID
- `class_id`: 班级ID

**返回示例:**
```json
{
    "success": true,
    "data": {
        "data": [
            {
                "id": 1,
                "username": "student001",
                "real_name": "张三",
                "role": 2,
                "role_name": "学生",
                "status": 1,
                "status_name": "正常",
                "sex": 1,
                "sex_name": "男",
                "email": "student001@example.com",
                "phone_number": "13800138001",
                "current_class": {
                    "id": 1,
                    "name": "一年级1班"
                },
                "parent": {
                    "id": 2,
                    "username": "parent001",
                    "real_name": "张父"
                }
            }
        ],
        "total": 100,
        "per_page": 15,
        "current_page": 1
    },
    "msg": "获取学生列表成功"
}
```

#### 2. 创建学生
```
POST /admin/student/create
```

**参数:**
- `username`: 用户名（必填）
- `real_name`: 真实姓名
- `password`: 密码（必填）
- `role`: 角色（必填，2：学生，3：家长）
- `grade_id`: 年级ID
- `parent_id`: 家长ID
- `email`: 邮箱
- `phone_number`: 手机号
- `status`: 状态
- `sex`: 性别

#### 3. 更新学生
```
PUT/POST /admin/student/update
```

**参数:**
- `id`: 学生ID（必填）
- 其他参数同创建接口

#### 4. 删除学生
```
DELETE/POST /admin/student/delete
```

**参数:**
- `id`: 学生ID（必填）

#### 5. 获取学生详情
```
GET/POST /admin/student/detail
```

**参数:**
- `id`: 学生ID（必填）

#### 6. 重置密码
```
POST /admin/student/reset-password
```

**参数:**
- `id`: 学生ID（必填）
- `password`: 新密码（必填）

#### 7. 更新状态
```
POST /admin/student/status
```

**参数:**
- `id`: 学生ID（必填）
- `status`: 状态（必填，0-3）

#### 8. 获取班级历史
```
GET/POST /admin/student/class-history
```

**参数:**
- `id`: 学生ID（必填）

#### 9. 分配到班级
```
POST /admin/student/assign-class
```

**参数:**
- `id`: 学生ID（必填）
- `class_id`: 班级ID（必填）
- `join_time`: 入班时间
- `remark`: 备注

#### 10. 从班级移除
```
POST /admin/student/remove-class
```

**参数:**
- `id`: 学生ID（必填）
- `class_id`: 班级ID（必填）
- `status`: 离班状态
- `leave_time`: 离班时间
- `remark`: 备注

### 家长管理接口

#### 1. 获取家长的子女列表
```
GET/POST /admin/student/children
```

**参数:**
- `id`: 家长ID（必填）

#### 2. 绑定家长和子女
```
POST /admin/student/bind-child
```

**参数:**
- `id`: 家长ID（必填）
- `child_id`: 子女ID（必填）

#### 3. 解除家长和子女绑定
```
POST /admin/student/unbind-child
```

**参数:**
- `id`: 子女ID（必填）

### 统计接口

#### 1. 获取学生统计信息
```
GET/POST /admin/student/statistics
```

**返回示例:**
```json
{
    "success": true,
    "data": {
        "total_students": 150,
        "total_parents": 80,
        "normal_students": 140,
        "male_students": 75,
        "female_students": 75,
        "status_distribution": {
            "normal": 140,
            "disabled": 5,
            "arrears": 3,
            "inactive": 2
        }
    },
    "msg": "获取统计信息成功"
}
```

## 使用示例

### 1. 创建学生
```bash
curl -X POST http://localhost:8000/admin/student/create \
  -H "Content-Type: application/json" \
  -d '{
    "username": "student123",
    "real_name": "测试学生",
    "password": "123456",
    "role": 2,
    "email": "test@example.com",
    "phone_number": "13800138000",
    "sex": 1,
    "status": 1
  }'
```

### 2. 查询学生列表
```bash
curl -X GET "http://localhost:8000/admin/student/list?page=1&page_size=10&role=2&status=1"
```

### 3. 分配学生到班级
```bash
curl -X POST http://localhost:8000/admin/student/assign-class \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "class_id": 5,
    "join_time": "2024-01-01 08:00:00",
    "remark": "新学期分班"
  }'
```

### 4. 绑定家长和子女
```bash
curl -X POST http://localhost:8000/admin/student/bind-child \
  -H "Content-Type: application/json" \
  -d '{
    "id": 2,
    "child_id": 1
  }'
```

## 数据初始化

### 1. 运行迁移
```bash
php artisan migrate
```

### 2. 运行测试数据填充
```bash
php artisan db:seed --class=StudentSeeder
```

这会创建以下测试数据：
- 3个学生用户：student001, student002, student003
- 2个家长用户：parent001, parent002
- 密码都是：123456
- 已设置好家长和子女关系

## 注意事项

1. **密码安全**: 系统使用MD5+盐值加密，建议在生产环境中升级到更安全的加密方式
2. **数据验证**: 所有输入都经过严格验证，确保数据完整性
3. **权限控制**: 需要配合认证中间件使用
4. **日志记录**: 所有重要操作都会记录日志
5. **事务处理**: 重要操作使用数据库事务确保数据一致性

## 扩展功能

系统预留了以下扩展接口：
- 批量导入学生数据
- 导出学生数据
- 更多统计报表
- 图片上传功能
- 消息通知功能

## 技术架构

- **框架**: Laravel 11
- **数据库**: MySQL
- **认证**: Laravel Sanctum
- **验证**: Laravel Validation
- **日志**: Laravel Log
- **中间件**: 自定义认证中间件

## 联系支持

如有问题或需要技术支持，请联系开发团队。