更新：models/routes/services/templates/docs

docs/API.md

@@ -103,12 +103,14 @@ GET /api/users
   {
     "id": 1,
     "username": "admin",
+    "name": "管理员",
     "role": "admin",
     "created_at": "2026-04-17 10:00"
   },
   {
     "id": 2,
     "username": "teacher1",
+    "name": "张老师",
     "role": "user",
     "created_at": "2026-04-18 10:00"
   }
@@ -141,10 +143,13 @@ PUT /api/users/<id>
 **请求体**:
 ```json
 {
+  "name": "新姓名",
   "role": "user"
 }
 ```
 
+> ⚠️ `username` 不可修改，密码通过单独接口修改
+
 ### 重置用户密码
 
 ```
@@ -182,8 +187,12 @@ GET /api/classes
   {
     "id": 1,
     "name": "钢琴初级班",
+    "level": "入门",
     "description": "入门学员",
+    "teacher_id": 2,
+    "teacher_name": "张老师",
     "student_count": 5,
+    "active": true,
     "created_at": "2026-04-17 10:00"
   }
 ]
@@ -201,7 +210,9 @@ POST /api/classes
 ```json
 {
   "name": "钢琴中级班",
-  "description": "进阶学员"
+  "level": "入门",
+  "description": "进阶学员",
+  "teacher_id": 2
 }
 ```
 
@@ -217,7 +228,10 @@ PUT /api/classes/<id>
 ```json
 {
   "name": "钢琴中级班（2026）",
-  "description": "进阶学员"
+  "level": "入门",
+  "description": "进阶学员",
+  "teacher_id": 2,
+  "active": true
 }
 ```
 
@@ -436,22 +450,91 @@ POST /api/generate-plan
 ```json
 {
   "student_id": 1,
-  "use_ai": true
+  "use_ai": true,
+  "template_id": 1
 }
 ```
 
 **参数说明**:
 - `student_id`: 学员ID
 - `use_ai`: 是否使用AI生成个性化报告（默认true）
+- `template_id`: AI提示词模板ID（可选，不传则使用排序第一的默认模板）
+
+**AI提示词模板参数**:
+| 参数 | 说明 |
+|------|------|
+| `{student_name}` | 学员姓名 |
+| `{practice_time}` | 每日练习时间 |
+| `{problems}` | 学员问题列表（含严重程度、级别、建议练习时间） |
+| `{student_goals}` | 学员未达成的目标内容（Markdown格式） |
+| `{schedule_table}` | ~~每日练习安排表~~（已废弃，AI报告已包含） |
+
+**响应**: SSE 流，包含进度信息
+
+**SSE 事件说明**:
+| step | 说明 |
+|------|------|
+| collecting | 收集问题数据 |
+| basic | 生成基础练习方案 |
+| basic_done | 基础方案生成完成 |
+| ai_config | AI配置信息 |
+| ai_start | 开始调用AI |
+| ai_problems | 发送给AI的问题摘要 |
+| ai_request | 等待AI响应 |
+| ai_prompt | AI提示词已生成（含字数） |
+| ai_generating | AI报告生成中 |
+| ai_response | AI响应已接收 |
+| ai_done | AI报告生成完成 |
+| saved | 方案已保存 |
+| complete | 全部完成 |
+
+**complete 事件包含**:
+```json
+{
+  "step": "complete",
+  "prompt_length": 1234,
+  "ai_report_length": 567,
+  "plan_id": 1
+}
+```
+
+---
+
+### 预览提示词
+
+```
+POST /api/generate-plan/preview
+```
+
+**功能**: 根据学员ID和模板生成提示词，但不保存方案。用于在生成前预览提示词内容。
+
+**请求体**:
+```json
+{
+  "student_id": 1,
+  "template_id": 1
+}
+```
 
 **响应示例**:
 ```json
 {
-  "plan_id": 1,
-  "ai_report": "## 个性化练习方案报告\n\n..."
+  "prompt": "根据学员张三的每日练习时间30分钟和以下问题，为其生成个性化练习方案...\n\n问题列表：\n1. 手小（中等）\n...",
+  "prompt_length": 1234,
+  "student_goals_length": 200,
+  "problems_length": 150
 }
 ```
 
+**SSE 事件说明**:
+| step | 说明 |
+|------|------|
+| collecting | 收集数据 |
+| prompt_generated | 提示词已生成（含字数统计） |
+| complete | 预览完成 |
+
+---
+
 ### 获取方案详情
 
 ```
@@ -464,32 +547,80 @@ GET /api/plans/<plan_id>
   "id": 1,
   "student_id": 1,
   "student_name": "张三",
+  "is_typical": false,
   "created_at": "2026-04-17 10:30",
   "content": {
     "student_name": "张三",
     "practice_time": "30分钟",
     "total_daily_minutes": 30,
-    "problems": [...],
-    "daily_schedule": [...],
+    "problems": [
+      {"name": "手小", "level": "入门", "severity": "中等"}
+    ],
     "ai_report": "..."
   }
 }
 ```
 
-### 获取学员的方案列表
+---
+
+### 获取学员方案列表
 
 ```
 GET /api/students/<student_id>/plans
 ```
 
+---
+
+### 设为典型方案
+
+```
+POST /api/plans/<plan_id>/typical
+```
+
+**响应**:
+```json
+{
+  "success": true,
+  "is_typical": true
+}
+```
+
+---
+
+### 删除方案
+
+```
+DELETE /api/plans/<plan_id>
+```
+}
+```
+
 ### 导出PDF
 
 ```
 GET /api/plans/<plan_id>/pdf
 ```
 
+**参数**:
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| template_id | int | 报告模板ID（可选，不传则使用排序第一的默认模板） |
+
 **返回**: PDF文件下载
 
+### 导出Markdown
+
+```
+GET /api/plans/<plan_id>/md
+```
+
+**参数**:
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| template_id | int | 报告模板ID（可选，不传则使用排序第一的默认模板） |
+
+**返回**: Markdown文件下载
+
 ### 微信卡片展示
 
 ```
@@ -498,12 +629,6 @@ GET /plans/<plan_id>/wechat
 
 **返回**: HTML页面，用于微信分享
 
-### 删除方案
-
-```
-DELETE /api/plans/<plan_id>
-```
-
 ---
 
 ## 问题配置（仅管理员）
@@ -598,7 +723,18 @@ POST /api/config/test
 更新目标
 
 ### DELETE /api/goals/{id}
-删除目标
+删除目标（仅管理员）
+
+**权限**: 仅管理员
+
+**依赖检查**：如果存在以下依赖关系，禁止删除：
+- 已被学员分配的目标
+- 作为父目标或子目标被其他目标关联
+
+**错误响应示例**:
+```json
+{"error": "无法删除：已被 3 名学员分配, 有 2 个子目标关联"}
+```
 
 ### GET /api/goals/{id}/children
 获取目标的子目标
@@ -632,6 +768,7 @@ POST /api/config/test
     "student_id": 1,
     "goal_id": 1,
     "goal_name": "掌握基本音阶",
+    "goal_content": "目标详细描述内容（Markdown）...",
     "goal_level": "入门",
     "goal_category": "演奏能力",
     "status": "进行中",
@@ -692,7 +829,161 @@ POST /api/config/test
 | comment | String | 评语 |
 
 ### DELETE /api/students/{id}/goals/{goal_id}
-移除学员的目标
+移除学员的目标（仅管理员，会级联删除关联的评估记录）
+
+**权限**: 仅管理员
+
+---
+
+## 学员目标评估 API
+
+### GET /api/students/{id}/evaluations
+获取学员的所有评估记录
+
+**响应**：
+```json
+[
+  {
+    "id": 1,
+    "student_goal_id": 1,
+    "goal_name": "掌握基本音阶",
+    "evaluator_id": 1,
+    "evaluator_name": "管理员",
+    "assessment_date": "2026-04-15",
+    "mastery_level": 3,
+    "comment": "进步明显",
+    "is_final": false,
+    "created_at": "2026-04-15T10:00:00"
+  }
+]
+```
+
+### POST /api/students/{id}/evaluations
+创建评估记录
+
+**请求体**：
+```json
+{
+  "student_goal_id": 1,
+  "assessment_date": "2026-04-15",
+  "mastery_level": 3,
+  "comment": "进步明显",
+  "is_final": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| student_goal_id | Integer | 学员目标ID |
+| assessment_date | String | 评估日期（YYYY-MM-DD） |
+| mastery_level | Integer | 掌握程度 1-5 |
+| comment | String | 评语 |
+| is_final | Boolean | 是否为最终评估 |
+
+### PUT /api/evaluations/{id}
+更新评估记录
+
+**请求体**：
+```json
+{
+  "assessment_date": "2026-04-16",
+  "mastery_level": 4,
+  "comment": "已完全掌握",
+  "is_final": true
+}
+```
+
+### DELETE /api/evaluations/{id}
+删除评估记录
+
+---
+
+## 模板管理 API
+
+### GET /templates/templates
+获取所有模板（按sort_order排序）
+
+**参数**:
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| type | string | 可选，按类型筛选（`ai_prompt`/`report`） |
+
+**响应**：
+```json
+[
+  {
+    "id": 1,
+    "name": "AI提示词模板",
+    "type": "ai_prompt",
+    "description": "生成练习方案时发送给AI的提示词",
+    "content": "...",
+    "sort_order": 0,
+    "created_at": "2026-04-23T10:00:00"
+  },
+  {
+    "id": 2,
+    "name": "报告导出模板",
+    "type": "report",
+    "description": "导出方案时使用的Markdown模板",
+    "content": "...",
+    "sort_order": 0,
+    "created_at": "2026-04-23T10:00:00"
+  }
+]
+```
+
+### GET /templates/templates/{id}
+获取单个模板
+
+### POST /templates/templates
+创建模板
+
+**请求体**：
+```json
+{
+  "name": "新模板名称",
+  "type": "ai_prompt",
+  "content": "模板内容...",
+  "description": "模板描述",
+  "sort_order": 1
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| name | String | 模板名称 |
+| type | String | 类型：`ai_prompt`（AI提示词）或 `report`（报告导出） |
+| content | String | 模板内容（Markdown格式） |
+| description | String | 描述 |
+| sort_order | Integer | 排序序号（越小越靠前） |
+
+### PUT /templates/templates/{id}
+更新模板
+
+### DELETE /templates/templates/{id}
+删除模板
+
+### POST /templates/templates/{type}/render
+渲染模板预览
+
+**参数**: `type` 为 `ai_prompt` 或 `report`
+
+**请求体**：用于替换模板中的变量
+```json
+{
+  "student_name": "张三",
+  "practice_time": "30分钟",
+  "problems": "...",
+  "student_goals": "..."
+}
+```
+
+**响应**：
+```json
+{
+  "rendered": "渲染后的内容..."
+}
+```
 
 ---
 
@@ -705,7 +996,8 @@ POST /api/config/test
 | 班级查询/分配学员 | ✅ | ✅ |
 | 学员管理 | ✅ | ✅ |
 | 问题记录 | ✅ | ✅ |
-| 方案生成 | ✅ | ✅ |
+| 方案生成/预览 | ✅ | ✅ |
+| 模板管理 | ✅ | ❌ |
 | 系统设置 | ✅ | ❌ |
 | 修改自己密码 | ✅ | ✅ |