railwaysystem/docs/development/rbac-r2/04_api_design.md

# RailwaySystem 自助服务接口体系设计 (Self-Service API Design)

- **设计版本**: R.2A Design Freeze
- **设计日期**: 2026-09-15
- **核心目标**: 建立专属的 Teacher 和 Student 自服务 API 契约（`/train/me/**`），彻底切断客户端参数越权可能性，确保后端 100% 服务端自主推导身份。

---

## 1. API 设计原则与边界

1. **禁止复用 Admin 全量管理接口**:
   - 严禁让教师或学员调用 `/train/student/list` 或 `/train/plans/{id}/timetable` 并寄希望于前端过滤。
   - 前端代码可被逆向、调试或通过 Postman 直接调用，任何客户端过滤均等于零安全防护。
2. **专属 `/train/me/**` 统一前缀**:
   - 所有自服务请求均指向当前登录人上下文。
   - 接口入参完全不接收 `studentId`、`teacherId` 等身份主键，参数只允许包含时间范围（如 `startDate`, `endDate`）或分页标记。
3. **严格对应真实业务能力 (No Fictional APIs)**:
   - 仅设计当前数据库与领域服务已真实支撑的业务模块（课表、入班名单、报到、考勤、学时、画像）。
   - 当前一期暂未实现正式闭环的成绩填报或复杂选课，一律不虚构开放。

---

## 2. 教师自服务接口规格 (Teacher Self-Service APIs)

### 2.1 获取教师本人档案信息
- **端点**: `GET /train/me/teacher`
- **鉴权要求**: `@PreAuthorize("@ss.hasRole('train_teacher')")`
- **响应示例**:
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "tId": "1540e76a34c54596b0e365ae8804ef68",
      "tName": "DEMO_E2E_20260915_122800_王老师",
      "tGender": "1",
      "tPhone": "13900000000",
      "tEmail": "wang@railway.cn",
      "orgName": "机务段技能实训中心",
      "jobTitle": "高级讲师",
      "status": 1
    }
  }
  ```

### 2.2 获取我参与任课的培训班列表
- **端点**: `GET /train/me/plans`
- **逻辑**: 通过 `train_timetable_lesson` 与 `train_plan_course` 逆向查出教师受聘的全部有效培训班。
- **参数**: `pageNum`, `pageSize`, `planStatus` (可选)
- **响应示例**:
  ```json
  {
    "code": 200,
    "rows": [
      {
        "planId": "613b316621e5466c9039650ced299aa1",
        "planName": "DEMO_E2E_20260915_122800_铁路综合培训第一期",
        "startDate": "2026-09-15",
        "endDate": "2026-09-20",
        "planStatus": 0,
        "myCourseCount": 2,
        "myLessonCount": 2
      }
    ],
    "total": 1
  }
  ```

### 2.3 获取我的授课课表日程
- **端点**: `GET /train/me/timetable`
- **参数**: `startDate` (如 `2026-09-15`), `endDate` (如 `2026-09-21`)
- **逻辑**: 仅查询 `teacher_id = #{currentTeacherId}` 的已排课次。
- **响应示例**:
  ```json
  {
    "code": 200,
    "data": [
      {
        "lessonId": 97,
        "planId": "613b316621e5466c9039650ced299aa1",
        "planName": "铁路综合培训第一期",
        "cId": "f4a28c4079fe47a1a542d3a34768f9fd",
        "courseName": "铁路安全理论",
        "venueType": 2,
        "venueName": "实训区A",
        "startTime": "2026-09-15 08:30:00",
        "endTime": "2026-09-15 10:00:00",
        "status": 1
      }
    ]
  }
  ```

### 2.4 获取我所带班级学员花名册 (敏感信息脱敏)
- **端点**: `GET /train/me/students`
- **参数**: `planId` (必填，后端校验教师是否有该班任教关系)
- **安全保障**: 身份证号脱敏为后四位，手机号中间四位脱敏。
- **响应示例**:
  ```json
  {
    "code": 200,
    "rows": [
      {
        "studentId": "f1b524da49da4a54a6d832ab22c2d092",
        "studentName": "张三",
        "maskedPhone": "138****0001",
        "maskedIdCard": "************1234",
        "orgName": "车辆段检修一车间",
        "reportStatus": 1,
        "enrollmentStatus": 0
      }
    ],
    "total": 2
  }
  ```

### 2.5 获取我授课课次的学员出勤情况
- **端点**: `GET /train/me/lessons/{lessonId}/attendance`
- **逻辑**: 后端严格核验 `lessonId` 的授课教师是否为当前登录人，然后输出该课次应到学员的打卡流水。

---

## 3. 学员自服务接口规格 (Student Self-Service APIs)

### 3.1 获取学员个人档案
- **端点**: `GET /train/me/student`
- **鉴权要求**: `@PreAuthorize("@ss.hasRole('train_student')")`
- **响应字段**: 学员工号、姓名、性别、联系电话、所属单位、照片凭证引用。身份证号仅向本人展示后四位。

### 3.2 获取我的参训班级与生命周期状态
- **端点**: `GET /train/me/enrollments`
- **逻辑**: 从 `train_training_enrollment` 查询 `student_id = #{currentStudentId}`。
- **状态字段**:
  - `enrollmentStatus`: `0 (待报到)`, `1 (已报到)`, `2 (请假)`, `3 (退训)`, `4 (已完成)`。
  - `planId`, `planName`, `startTime`, `endTime`, `reportDeadline`。

### 3.3 获取我的参训课表
- **端点**: `GET /train/me/timetable`
- **参数**: `startDate`, `endDate`, `viewType` (`day`/`week`)
- **逻辑**: 关联当前学员所在有效班级（`enrollmentStatus IN (0, 1, 4)`），汇总返回所有授课课次、场地位置与任课教师姓名。

### 3.4 获取我的报到凭据与状态
- **端点**: `GET /train/me/report`
- **逻辑**: 查询当前学员在最新培训计划中的报到记录（`train_class_report`），返回报到时间、分配教室、分配场地与当前报到状态。

### 3.5 获取我的考勤打卡流水
- **端点**: `GET /train/me/attendance`
- **参数**: `planId` (可选), `month` (可选)
- **逻辑**: 查询 `train_student_checkin WHERE student_id = #{currentStudentId}`。
- **响应示例**:
  ```json
  {
    "code": 200,
    "rows": [
      {
        "checkinId": 10,
        "lessonId": 97,
        "courseName": "铁路安全理论",
        "checkinTime": "2026-09-15 08:28:10",
        "checkoutTime": "2026-09-15 12:48:42",
        "attendanceStatus": 2,
        "statusLabel": "迟到",
        "manualFlag": 1,
        "adjustReason": "因列车调度交接延误10分钟"
      }
    ]
  }
  ```

### 3.6 获取我的累计学习时长
- **端点**: `GET /train/me/duration`
- **逻辑**: 归集 `train_study_duration`，按理论课时与实训课时分别统计有效累计秒数与达标折算学时。

### 3.7 获取我的多维成长画像雷达
- **端点**: `GET /train/me/portrait`
- **逻辑**: 查询 `train_student_portrait WHERE student_id = #{currentStudentId}`，返回出勤率、测评平均分、技能掌握度等 5 维雷达数据。

---

## 4. 身份异常与边界错误码规范

| HTTP 状态码 | 业务错误代码 (Code) | 错误提示说明 (Message) | 触发边界与处理方式 |
| :---: | :---: | :--- | :--- |
| `401` | `401` | "认证凭据无效或会话已过期" | Token 缺失、伪造或 Redis 缓存失效，引导至登录页 |
| `403` | `403` | "非教师身份，禁止访问教师专属工作台" | 学员账号或非授课管理员访问 `/train/me/teacher/**` |
| `403` | `403` | "非学员身份，禁止访问学员个人培训中心" | 教师或管理员账号访问 `/train/me/student/**` |
| `400` | `40041` | "当前登录账号未绑定任何业务档案，请联系管理员" | 存在 `sys_user` 账号，但 `train_teacher/student` 表中未关联对应主体 |
| `403` | `40042` | "您并非该班级或课次的任课教师，无权查看学员信息" | 教师尝试横向探测试图读取无关班级名册 |