chore: 清理过时文档文件

删除不再使用的文档文件，包括统一鉴权、字段清理、接口文档、用户绑定等过时方案说明

.trae/documents/M4 清理冗余字段与统一鉴权方案.md

-## 目标
-- 彻底移除旧字段与索引，保证仅以实体化模型（bindings→persons→students/teachers）运转。
-- 补充接口文档与示例，并统一鉴权口径（系统角色等级＋实体身份）。
-
-## 待执行工作
-1) 统一鉴权依赖
-- 在 `app/api/deps.py` 增加 `require_binding(type)`，校验存在主绑定且实体类型匹配（student/teacher）。
-- 学生端与班主任端路由分别挂载 `require_binding('student')` 与 `require_binding('teacher')`，中层/校级端保持角色等级校验。
-
-2) 路由与服务清理
-- `app/services/dashboard.py`：
-  - 班主任端查询仅使用 `head_teacher_person_id`；移除对 `head_teacher_id` 的回退。
-  - 学生/中层/校级端均以“绑定→实体”解析路径，移除旧字段回退。
-- `app/api/v1/students.py`：仅以绑定解析学生，不再读取旧 `user_id`。
-
-3) 数据与索引维护
-- 运行维护脚本（或在 `init_db.py` 的维护段）删除旧索引：
-  - `classes.head_teacher_id_1`、`schedules.teacher_id_1`、`students.user_id_1`
-- 确保集合不再写入或依赖旧字段：
-  - `classes.head_teacher_id`、`schedules.teacher_id`、`students.user_id`
-
-4) 文档与示例
-- 在文档中补充以下内容：
-  - 绑定接口用法与主绑定约束
-  - 人员/教师批量导入字段说明与示例
-  - 班级/课表实体化字段设置示例
-  - 仪表盘各角色返回示例（关键字段）
-  - 迁移流程与注意事项（导入顺序、索引清理）
-
-5) 验证
-- MCP 校验集合：确认不再存在旧字段与旧索引；`students.person_id`、`classes.head_teacher_person_id`、`schedules.teacher_person_id` 正常。
-- 接口联调：
-  - 学生端：需主绑定且类型为 student；返回课表/出勤/操行
-  - 班主任端：以 `head_teacher_person_id` 定位所辖班；返回当前节次课程与地点、节次出勤、请假与指示
-  - 中层/校级端：统计与序列化正常，无 `ObjectId` 泄露
-
-## 回滚策略
-- 保留兼容分支的开关，在异常时临时恢复旧字段回退；完成 M4 验证后默认关闭。
-
-如果你确认，我将按以上步骤执行：先实现依赖与代码清理，再完成索引维护与文档补充，最后进行 MCP 与接口联调验证。
\ No newline at end of file

.trae/documents/M4-统一鉴权与字段清理.md

-# M4 统一鉴权与字段清理
-
-## 鉴权口径
-- 系统角色等级：1 学生、2 班主任、3 中层、4 校级、5 管理员
-- 实体身份依赖：require_binding(student|teacher)
-- 版别运行模式：require_edition_for_mode()
-
-## 字段与索引
-- classes：使用 head_teacher_person_id（索引）；移除 head_teacher_id（索引）
-- schedules：使用 teacher_person_id（索引）；移除 teacher_id（索引）
-- students：使用 person_id（稀疏唯一）；移除 user_id（索引）
-
-## 管理接口
-- POST /api/v1/persons/bulk
-- POST /api/v1/teachers/bulk
-- PUT /api/v1/classes/{class_id}/head-teacher
-- PUT /api/v1/schedules/assign-teacher
-- POST /api/v1/bindings；GET /api/v1/bindings/me
-
-## 仪表盘接口
-- GET /api/v1/dashboard/student/today（role≥1 + binding=student）
-- GET /api/v1/dashboard/homeroom/current（role≥2 + binding=teacher）
-- GET /api/v1/dashboard/department/overview（role≥3）
-- GET /api/v1/dashboard/campus/overview（role≥5）
-
-## 迁移顺序
-1. persons 导入→ 2. teachers 导入 → 3. classes 设置 head_teacher_person_id → 4. schedules 设置 teacher_person_id → 5. bindings 建主绑定 → 6. 清理旧索引与字段
-
-## 验证
-- MCP 检查集合字段与索引；联调各仪表盘接口返回示例。

.trae/documents/完善与交付班主任端当前时段看板.md

-## 现状与差距
-- 已有接口：`GET /api/v1/dashboard/homeroom/current`（角色≥2，受版别限制）。功能包含：
-  - 当前时段课程与地点（按登录时间映射节次）
-  - 所辖班级今日整体出勤率（present/total）
-  - 今日请假列表（time-window 过滤）
-  - 部门级近期指示（倒序取前 N 条）
-- 待完善：
-  - 按“当前节次”统计出勤（而不是全天）
-  - 请假与指示的过滤更精确（按系部/班级目标）
-  - 响应统一可序列化（去除 `ObjectId` 等）
-
-## 接口与权限
-- 路由：`GET /api/v1/dashboard/homeroom/current`
-- 依赖：`Depends(require_edition_for_mode())` + `Depends(require_role(2))`
-- 当前用户定位班级：`classes.head_teacher_id == current_user._id`
-
-## 数据口径（最终返回）
-- `current_lessons`
-  - 每个所辖班在当前节次的课程名、地点（从共享节次 `schedules.classes` 中匹配 `class_id`）
-- `attendance_rates`
-  - 每班“当前节次”的出勤数据：`present/total/rate`（从 `attendance` 以 `lesson_id=W{weekday}-P{period}` 精确统计）
-- `leaves`
-  - 今日处于有效区间的请假记录（`from_date<=today<=to_date`），返回 `student_id/class_id/reason/status`
-- `directives`
-  - 部门级指示（可选：按目标包含所辖班级或专业筛选），倒序最近 N 条
-
-## 技术实现
-- 服务层（`app/services/dashboard.py`）
-  - 统一序列化字典，不返回不可序列化类型
-  - 当前节次计算：使用登录时间（小时→节次）
-  - 出勤统计粒度：`attendance.count_documents({class_id, date=today, lesson_id=current_lesson_id, status='出勤'})`
-- 索引与性能
-  - 已有索引：`students.user_id`、`classes.head_teacher_id`、`schedules(classes.class_id, weekday, period)`、`attendance(lesson_id, student_id)`、`leaves(class_id, from_date)`
-  - 查询按索引字段过滤，保持 O(logN) 级命中
-
-## 验证方案
-- MCP 校验：
-  - 按 `head_teacher_id` 列出所辖班；按 `weekday+period` 查当前节次课表；按 `lesson_id+class_id` 统计出勤
-- 接口联调：
-  - 使用 `manager_edu` 登录，访问 `/dashboard/homeroom/current` 检查四块数据完整性
-
-## 交付步骤
-1. 优化 `homeroom_current_summary` 的出勤统计粒度到“当前节次”
-2. 指示列表按部门或目标过滤，统一序列化输出
-3. 加入最小限度的错误兜底（无所辖班时返回空集合）
-4. 通过 MCP 与本地接口联调验证
-
-## 安全与回滚
-- 仅读取查询，无数据破坏；若需回滚，保留原全天出勤实现分支
-
-确认后我将立即完善服务实现并复核接口返回，随后重启后端（端口可改回 8000 或继续 8001）进行联调验证。
\ No newline at end of file

.trae/documents/完善接口文档与示例（统一到 8000_docs）.md

-## 目标
-- 为所有接口补充清晰的中文 `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 进行文档验证。
\ No newline at end of file

.trae/documents/实现用户-学生绑定与接口整合.md

-## 问题与目标
-- 现状：仅示例用户 `user` 绑定了一个学生，其余学生未与用户账户关联，导致学生端接口需要 fallback，功能割裂。
-- 目标：建立稳定的“用户↔学生”绑定关系与接口，使学生端数据根据登录用户精确返回；同时保证班主任、中层、校级端不受影响。
-
-## 数据库与索引
-1. `students` 集合新增索引：
-- `user_id` 唯一（稀疏），确保一个用户仅绑定一个学生；便于按用户查学生
-- 维持现有：`student_id` 唯一、`class_id` 索引
-
-2. 可选（若需要反查更快）：
-- `users` 集合新增字段：`student_id`（非必需）；无需索引，主要用于展示与快捷反查
-
-## 服务与接口
-1. 新增服务 `app/services/student_binding.py`：
-- `bind_user_to_student(user_id, student_id)`：校验重复绑定，写入 `students.user_id`，可同步回写 `users.student_id`
-- `unbind_user_from_student(student_id)`：移除绑定；可同步清理 `users.student_id`
-- `get_student_by_user(user_id)`：按 `students.user_id` 查询返回学生
-
-2. 新增路由 `app/api/v1/students.py`：
-- `POST /students/{student_id}/bind`（管理员或班主任，≥2级）：请求体携带 `user_id`
-- `DELETE /students/{student_id}/bind`（管理员或班主任，≥2级）
-- `GET /students/me`（学生本人，≥1级）：返回当前登录用户绑定的学生信息
-- 路由统一挂载 `Depends(require_edition_for_mode())`，角色控制用 `require_role(min_level)`
-
-## 学生端接口对齐
-- 更新 `app/services/dashboard.py`：
-  - 去掉“未绑定时随机学生”的 fallback，若当前用户未绑定学生则返回 404（或明确错误）
-  - 查询逻辑改为严格基于 `students.user_id` 取 `student_id/class_id`，再取当天课表/出勤/操行
-
-## 初始化数据与迁移
-- 在 `init_db.py` 中：
-  - 保留已绑定示例 `user ↔ SW22-1-001`
-  - 新增批量绑定工具函数（可选）：用于演示环境将若干学生与新创建的用户批量绑定（仅本地开发）
-- 正式环境：由管理员通过新接口进行绑定
-
-## 验证
-- 使用 MCP：
-  - 检查 `students` 索引与绑定结果（`count`、`query`）
-  - 按用户查询学生 `get_student_by_user` 的返回
-- 通过接口：
-  - 学生登录访问 `/dashboard/student/today` 能准确返回本人数据；未绑定返回明确错误
-  - 班主任、中层、校级端接口不受影响
-
-## 变更范围
-- 新增文件：`app/services/student_binding.py`、`app/api/v1/students.py`
-- 修改文件：`app/services/dashboard.py`（去除 fallback）、`app/api/v1/router.py`（注册 students 路由）、`init_db.py`（索引与演示绑定可选）
-
-## 回滚与安全
-- 仅在 `students.user_id` 写入引用，不影响学生主键；解绑接口可恢复
-- 索引为稀疏唯一，避免未绑定数据被约束；写入时做并发校验，防止竞态
-
-请确认以上方案，我将按此落地实现并完成 MCP 与接口验证。
\ No newline at end of file

.trae/documents/更新项目 README（实体化模型与接口文档说明）.md

-## 目标
-- 用中文完善 README，对当前架构、鉴权口径、数据模型与主要接口进行系统化说明，便于快速上手与联调。
-
-## README 结构
-1) 项目简介
-- 简述：LLM 过滤系统后端；统一角色等级与实体化数据模型；支持教育/企业版运行模式。
-
-2) 技术栈
-- FastAPI、Motor/PyMongo、Pydantic v2、Uvicorn、HTTPX；MongoDB
-
-3) 运行与端口
-- 开发启动：`uvicorn app.main:app --reload --port 8000`
-- 文档：`http://127.0.0.1:8000/docs`
-
-4) 环境变量
-- 核心：`MONGODB_URL/DB_NAME/APP_MODE/SECRET_KEY/ALGORITHM/ACCESS_TOKEN_EXPIRE_MINUTES`
-- 外部：`OLLAMA_BASE_URL/OLLAMA_MODEL`
-- 初始密码：`ADMIN_EDU_PASSWORD/USER_EDU_PASSWORD/MANAGER_EDU_PASSWORD/LEADER_EDU_PASSWORD/MASTER_EDU_PASSWORD` 与企业版对应变量
-
-5) 初始化数据库
-- 命令：`python init_db.py`
-- 内容：创建用户、敏感词、对话；创建并填充 students/classes/schedules/attendance/conduct/leaves/directives；生成 persons/teachers/bindings 并清理旧字段与索引
-
-6) 鉴权口径
-- 角色等级：1 学生、2 班主任、3 中层、4 校级、5 管理员
-- 版别依赖：`require_edition_for_mode()`
-- 实体绑定依赖：`require_binding(student|teacher)`；登录载荷含 `person_id/person_type/bound_primary`
-
-7) 数据模型（Mongo 集合）
-- `users`（账号）；`persons`（人物）；`students`/`teachers`（实体）；`bindings`（绑定）
-- 班级：`classes`（`head_teacher_person_id`）；课表：`schedules`（共享节次，`teacher_person_id`）
-- 出勤与行为：`attendance/leaves/conduct`；指示：`directives`
-- 敏感词与审计：`sensitive_words/sensitive_records`；对话：`conversations`
-
-8) 主要接口
-- 认证：`POST /auth/register`、`POST /auth/login`
-- 仪表盘：学生/班主任/中层/校级（`/dashboard/...`）
-- 学生：`/students/me`、绑定：`POST/DELETE /bindings`、`GET /bindings/me`
-- 人员：`POST /persons/bulk`、`GET /persons`
-- 教师：`POST /teachers/bulk`、`GET /teachers`
-- 班级：`PUT /classes/{class_id}/head-teacher`、`GET /classes`
-- 课表：`PUT /schedules/assign-teacher`、`GET /schedules`
-
-9) 快速演示
-- 示例账号与密码（教育版）：`admin/admin123`、`user/user123`、`manager_edu/manager123`、`leader_edu/leader123`、`master_edu/master123`
-- 绑定流程：登录→查询/创建绑定→访问仪表盘
-
-10) 注意事项
-- ObjectId 序列化：接口返回不包含原始 `ObjectId`；如需返回 `_id`，统一转换为字符串
-- 索引：`person_id` 稀疏唯一；`head_teacher_person_id`/`teacher_person_id` 索引、课表组合索引、出勤组合索引
-
-## 交付方式
-- 更新根目录 `README.md` 文件内容为以上结构
-- 保持内容简洁、示例充分，与 `/docs` 文档一致
-
-确认后我将直接更新 README.md 并进行一次端到端核对（初始化与接口文档一致性）。
\ No newline at end of file

.trae/documents/重构用户与实体模型：账户_学生_教师分离与统一绑定.md

-## 问题概述
-- 现状：`users` 同时承载学生/老师/班主任/干部等身份，且“学生↔用户”绑定分散，导致查询与权限判定割裂。
-- 痛点：
-  - 身份与账号未解耦，复用困难、扩展性差
-  - 教师/班主任/学生的组织归属（班级、系部）未统一建模
-  - 仪表盘与考勤口径需跨实体检索，复杂度与耦合高
-
-## 目标
-- 账户与人物实体解耦：统一用“账号（Account）↔人物（Person）”绑定
-- 学生/老师/干部使用专属子实体，清晰表达业务属性
-- 路由鉴权同时基于账号的角色等级与实体身份
-
-## 数据模型（MongoDB 集合）
-1. accounts（账号）
-- 字段：`_id, username, email, hashed_password, edition, status`
-- 说明：仅承载登录与权限基础信息，不直接承载业务属性
-
-2. persons（人物基础档案）
-- 字段：`person_id, name, gender, phone, id_no, type: ['student','teacher','staff']`
-- 索引：`person_id` 唯一
-
-3. students（学生实体）
-- 字段：`person_id, student_id, grade, major, class_id, guardians, status, department`
-- 关系：`account_id?`（可空）；索引：`student_id` 唯一、`class_id`、`account_id` 稀疏唯一
-
-4. teachers（教师实体）
-- 字段：`person_id, teacher_id, department, title, roles: ['teacher','homeroom','cadre']`
-- 关系：`account_id?`；索引：`teacher_id` 唯一、`department`、`account_id` 稀疏唯一
-
-5. bindings（统一绑定表）
-- 字段：`account_id, person_id, primary: boolean, type`
-- 说明：一账号可绑定一个主人物（primary）与若干备用绑定；索引：`account_id+type` 唯一（primary）
-
-6. classes（班级）
-- 扩展：`head_teacher_person_id` 替代原 `head_teacher_id`（指向教师实体）
-
-7. schedules（课表）
-- 扩展：`teacher_person_id` 替代原 `teacher_id`；`classes: [{class_id, location}]` 保持共享节次
-
-8. leaves/attendance/conduct/directives
-- 维持现有集合，但在查询上通过 `person_id`/`student_id`/`class_id` 衔接
-
-## 鉴权与角色
-- 保留 `role_level`（user=1, manager=2, leader=3, master=4, administrator=5）
-- 登录载荷扩展：`person_id, person_type, bound_primary`（用于后端快速定位实体）
-- 路由依赖：在 `require_role(min_level)` 基础上增加实体类型校验（例如学生端必须有绑定且为 `student`）
-
-## API 设计（新增/改造）
-- 绑定管理（新）：`POST /api/v1/bindings`、`DELETE /api/v1/bindings/{account_id}/{person_id}`、`GET /api/v1/bindings/me`
-- 人物档案：`POST/GET/PUT /api/v1/persons`
-- 学生：`POST/GET/PUT /api/v1/students`（含批量导入/绑定工具）
-- 教师：`POST/GET/PUT /api/v1/teachers`（标记班主任/干部）
-- 班级与课表：适配 `person_id` 字段，查询统一从实体出发
-- 仪表盘路由：学生/班主任/中层/校级端以实体维度查询，兼容旧数据
-
-## 迁移方案
-1. 引入新集合与索引（不破坏现有）
-2. 从现有 `users` 生成 `persons` 与对应 `students/teachers`（示例用户：`leader_edu→teacher(cadre)`、`manager_edu→teacher(homeroom)`）
-3. 写入 `bindings`（把当前登录账号与对应人物建立主绑定）
-4. 更新 `classes.head_teacher_person_id` 与 `schedules.teacher_person_id`
-5. 仪表盘查询优先走新模型，保留旧模型回退
-
-## 分阶段实施
-- M1（模型与绑定）：创建集合与索引，提供绑定接口，完成示例数据迁移与验证
-- M2（查询改造）：学生/班主任/中层/校级端查询切换到实体模型，完成序列化与性能验证
-- M3（管理接口）：完善人员与班级、系部管理接口，支持批量导入/绑定
-- M4（清理与文档）：去除冗余字段、补充接口文档与示例
-
-## 验证与性能
-- MCP 校验集合与索引；事务性绑定校验唯一约束
-- 查询走索引：`account_id/person_id/class_id/teacher_person_id`
-- 压测：按班级/教师的日级查询与节次查询
-
-## 兼容策略
-- 保留现有 `users` 字段与接口短期可用
-- 新接口逐步替换前端对旧字段的依赖
-
-确认后，我将按此方案落地：先交付 M1（集合与绑定接口），在不影响现有功能的前提下逐步迁移与联调。
\ No newline at end of file