## 目标
- 为所有接口补充清晰的中文 `summary/description`、请求/响应示例与错误码说明，使文档在 `/docs` 可直接理解与使用。
- 统一端口到 `http://127.0.0.1:8000/docs`（启动后端到 8000）以符合你的访问习惯。

## 全局文档配置
- `app/main.py`
  - 在创建 `FastAPI()` 时设置 `description`（项目概览与角色说明）与 `openapi_tags`（认证、仪表盘、学生、绑定、人员、教师、班级、课表、管理员、对话）。
  - 示例：为每个 Tag 增加中英文说明，便于分组导航。

## 路由级文档增强
- 统一在路由装饰器中加入：
  - `summary`：一句话概述
  - `description`：详细说明（包含角色要求、鉴权依赖、数据口径、注意事项）
  - `responses`：标准错误（401/403/404）与成功示例（`example`）
- 覆盖文件：
  - 认证：`app/api/v1/auth.py`
  - 仪表盘：`app/api/v1/dashboard.py`（学生/班主任/中层/校级）
  - 学生：`app/api/v1/students.py`
  - 绑定：`app/api/v1/bindings.py`
  - 人员：`app/api/v1/persons.py`
  - 教师：`app/api/v1/teachers.py`
  - 班级：`app/api/v1/classes.py`
  - 课表：`app/api/v1/schedules.py`
  - 管理员：`app/api/v1/admin.py`
  - 对话：`app/api/v1/conversation.py`

## 响应模型与字段说明
- 为关键接口新增/完善 `Pydantic` 响应模型：
  - 使用 `Field(description=...)` 为每个字段提供中文说明
  - 在模型 `model_config` 中设置 `title` 与示例（如 `json_schema_extra={'examples': [...]}`）
- 典型模型：
  - 登录响应 `Token` 增补 `person_id/person_type/bound_primary` 字段说明
  - 仪表盘返回对象：学生端今日汇总、班主任端当前时段、中层/校级总览
  - 绑定查询对象：`account_id/person_id/type/primary`

## 示例与错误码
- 在 `responses` 中定义：
  - `401` 未认证，`403` 权限不足或绑定不匹配，`404` 资源不存在
  - `200` 示例：给出典型返回的完整示例（课表/出勤/操行/指示）
- 请求示例：
  - 登录：`application/x-www-form-urlencoded` 的 `username/password`
  - `POST /bindings` 与 `POST /persons/teachers/bulk` 的 JSON 示例体

## 端口统一与验证
- 将后端启动端口统一到 8000，验证 `http://127.0.0.1:8000/docs` 展示完整中文说明与示例。
- 通过实际请求核对各接口的示例与返回一致性。

## 不改业务逻辑
- 本次仅增强文档与描述，不改变接口的输入输出契约与鉴权逻辑。

确认后我将逐个路由补充 `summary/description/responses/example`，完善响应模型字段说明，并统一启动端口到 8000 进行文档验证。