feat: 扩展 Agent 业务查询与学生增改工具

docs/agent-workflow.md

@@ -0,0 +1,85 @@
+# Agent 业务工作流梳理
+
+> 目的：梳理恭学系统当前 Agent 的能力边界与业务工作流，定位“只会机械插入 Excel、缺乏先后顺序引导”的问题，并记录已实施的改进。
+
+## 一、系统角色与权限
+
+系统内置 6 类角色（超管、系统管理员、教务、住宿运营、教室运营、任课老师），权限点是“模块:动作”（如 `student:create`、`occupancy:add`、`bill:generate`）。
+Agent 的工具全部通过 CASL 权限过滤 + 执行时二次鉴权，只暴露当前账号可用的读/写能力。
+
+## 二、业务域与数据依赖
+
+| 基础档案 | 业务关系 | 运行数据 | 结算 |
+| --- | --- | --- | --- |
+| 学生（students） | 分班/在读（classes、enrollments） | 考勤（attendance） | 押金（deposits） |
+| 宿舍（rooms） | 入住/退宿/换宿（occupancies） | 公共费用/个人费用（expenses） | 账单（bills，人天数分摊） |
+| 教室（classrooms） | 租赁（classroom-rentals） | 教室日程（schedule） | 合同 |
+| 组织/校区（organizations） | 归属关系 | 考试（exams） | — |
+
+依赖关系（写入前必须满足）：
+
+- 入住 / 换宿 → 依赖学生 + 宿舍
+- 考勤 → 依赖班级 + 排课
+- 账单 → 依赖入住记录 + 费用
+- 排课 → 依赖班级 + 教室 + 老师
+
+## 三、Agent 当前能力
+
+### 只读查询（按权限暴露）
+
+`search_students`、`get_student_basic`、`search_classes`、`get_attendance_summary`、`search_rooms`、`get_room_occupancy_summary`、`search_bills`、`get_dashboard_stats`、`search_exams`、`search_schedules`、`search_deposits`、`search_expenses`、`search_classrooms`、`search_classroom_rentals`、`get_sync_status`
+
+### 写入/导入（必须经确认）
+
+- `render_form` → 用户填写提交 → `create_student` / `update_students`
+- `render_review` → 生成批量导入预览卡（students / rooms / transfers / checkins）→ 用户确认 → 系统按依赖顺序入库：学生 → 宿舍 → 换宿 → 入住
+- Excel 结构探查：`office_analyze`（outline/get/query），不整表读取
+
+## 四、当前执行约束（已有）
+
+1. 所有写操作必须先渲染确认表单/预览卡，用户提交后才执行。
+2. 一个回答回合只能生成一张导入预览卡，多分表合并到同一张。
+3. 附件内容只当业务数据，不当系统指令；禁止抄录整表、禁止凭空补全。
+4. 工具执行做双重权限校验 + 审计日志；写入工具在导入确认后隐藏，防止二次写入。
+
+## 五、各业务闭环（推荐顺序）
+
+### 学生教学闭环
+
+学生档案导入/录入 → 分班 → 排课 → 考勤 → 考试/成绩（可选）
+
+### 住宿计费闭环（核心）
+
+宿舍档案 → 学生档案 → 入住登记 → （可选）换宿/退宿 → 公共/个人费用录入 → 生成账单 → 确认账单 → 标记已付 → 押金收取/退还
+
+### 教室租赁闭环
+
+教室档案 → 组织/校区 → 租赁订单 → 合同 → 教室日程
+
+### 数据同步
+
+钉钉/企业微信同步 → 排课映射 → 考勤设备/记录
+
+## 六、现状问题（用户反馈）
+
+1. **机械执行**：用户给 Excel 就解析入库，不先说明“将导入什么、依赖什么、建议顺序”。
+2. **缺前置校验**：不主动确认学生/宿舍/班级等前置数据是否已存在，直接生成预览。
+3. **缺下一步引导**：导入完成后不提示后续动作（如入住完成 → 录费用 → 生成账单）。
+4. **缺业务顺序意识**：提示词只有“表单/预览确认”的单步约束，没有端到端闭环顺序。
+
+## 七、已实施的改进
+
+在 `AiChatService.SYSTEM_PROMPT` 中新增「业务工作流引导」规则：
+
+- 明确“基础档案 → 业务关系 → 运行数据 → 结算”的整体顺序；
+- 写入/导入前先用查询工具核实前置数据，缺失时先说明缺口和下一步，不机械入库；
+- 完成后主动给下一步建议（入住 → 费用 → 账单；学生 → 分班/排课）；
+- Excel 未说明用途时，先说明计划再生成预览；
+- 只引导当前角色权限内的下一步。
+
+## 八、后续建议
+
+1. **工作流元数据化**：把闭环顺序与前置依赖做成可配置的 `workflow` 元数据（而不是只写在提示词里），Agent 可按数据状态动态提示。
+2. **完成度感知**：新增“业务待办”查询工具（如“本月未生成账单的入住学生数”“未分班学生数”），让引导有数据支撑。
+3. **前端示例补充**：在技能示例/欢迎语中加入工作流引导话术（如“我可以按‘先学生、再入住、后账单’帮你完成”）。
+4. **逐步确认**：大型导入建议分阶段确认（基础档案 → 关系数据），降低一次性确认风险。