接口文档 · 登录鉴权（教师端）

满足根 CLAUDE.md #3/#5/#6。设计见 ../鉴权设计.md；账号库口径见 ../多端账号与登录规范.md。 Base URL：dev http://localhost:8000；生产 https://teacher-api.weizhiqingtu.com。统一返回 { "code":0, "message":"ok", "data":<T> }。日志分类：登录鉴权。 模型：教师端 FastAPI 自建后端，直连共享 Supabase（GoTrue 验密 + service_role/PostgREST 读写），签发本端 JWT。账号/数据全部本端实现，只有在线升级走 118.145.144.101。

接口一览

方法 路径 鉴权 名称
POST /api/teacher/login 公开 登录（GoTrue 验密，仅放行 teacher）
POST /api/teacher/register 公开 自助注册（三件套，注册即登录）
POST /api/teacher/refresh 公开 续期（本端自签）
GET /api/teacher/schools 公开 注册选校列表
GET /api/teacher/me Bearer 当前教师简档
GET /api/teacher/profile Bearer 教师档案（含学科/学校）
GET /api/teacher/students Bearer 本校学生（行级隔离）

1. 登录 POST /api/teacher/login

入参：{ "loginName": "ceshilaoshi01", "password": "******" }。后端拼虚拟邮箱 {loginName}@admin.xiaoyuan.local 调 GoTrue 验密 → 查 profiles(role=teacher,enabled)+teachers → 自签 JWT。

响应 data（LoginResult）：

{
  "accessToken": "<本端 JWT, 120min>",
  "refreshToken": "<本端 JWT, 30d>",
  "teacher": {
    "id": "profiles.id", "name": "测试老师", "role": "teacher",
    "code": "ceshilaoshi01", "phone": null,
    "schoolId": "school uuid", "schoolName": "建邺外国语学校"
  }
}

错误码：401 账号或密码错误；403 非教师账号 / 账号已停用；503 生产下 Supabase 未配置。

2. 自助注册 POST /api/teacher/register

入参：{ "loginName", "password", "displayName", "schoolId", "phone"? }。后端建 auth.users+profiles(role=teacher)+teachers(profile_id 回填) 三件套，注册即登录返回 LoginResult。

错误码：409 登录名已被占用；400 请选择所属学校（teachers.school_id NOT NULL，无占位校时）；502 写共享库失败；503 未配 Supabase。

3. 续期 POST /api/teacher/refresh

入参：{ "refreshToken" }；响应 data：{ "accessToken", "refreshToken" }。401 refresh 无效/过期/类型不对。

4. 当前教师 GET /api/teacher/me（Bearer）

响应 data：TeacherProfile（id/name/role/code/phone/schoolId/schoolName）。401 无/无效/过期 token。

5. 教师档案 GET /api/teacher/profile（Bearer）

响应 data：{id(=teachers.id),name,code,phone,subjects,is_head,status,school:{id,name},login_name,display_name}（本人，service_role 查）。

6. 本校学生 GET /api/teacher/students（Bearer）

Query：class_id?、keyword?（姓名/学号 ilike）、page=1、size=20。按当前教师 teachers.school_id 行级隔离。data：{ items:[{id,name,sno,gender,grade_id,class_id,student_status}], total }；无 school_id 的教师返回空集。

7. 注册选校 GET /api/teacher/schools

data：[{id,name,code}]（只读共享 schools，status=normal）。DEV 下返回占位项。

鉴权与日志

  • 前端统一走 @teacher/api-client 的 authFetch（自动 Bearer + 401 自动 /api/teacher/refresh 续期）。
  • 中间件校验本端 JWT（jwt_secret），白名单外无/无效 token → 401。
  • 日志经中间件落 t_api_logs，password/token 字段脱敏（见 ../鉴权设计.md §3）。
  • 测试库已有联调教师号 ceshilaoshi01（建邺外国语学校）。