feat: v1.4.0 - 典型方案采纳、推荐方案列表、审计字段、导航优化

- 添加典型方案采纳功能 (POST /api/plans/<id>/adopt) - 添加推荐方案列表 (GET /api/students/<id>/recommended-plans) - PracticePlan 新增 created_by/updated_by/updated_at 审计字段 - 方案编辑/详情页导航优化 (bfcache 处理、pageshow 事件) - 方案列表支持删除功能 - 学员列表'暂无方案/问题'样式统一 - 更新文档：问题文件已废弃（迁移到数据库） - 更新部署脚本和验证清单
2026-04-27 02:01:22 +08:00
parent 6abdd49c04
commit e50a9207b4
20 changed files with 873 additions and 88 deletions
@@ -2,7 +2,7 @@

 ## 基础信息

- **Base URL**: `http://127.0.0.1:5000`
+- **Base URL**: `http://127.0.0.1:5001`
 - **Content-Type**: `application/json`

 ---
@@ -547,8 +547,11 @@ GET /api/plans/<plan_id>
  "id": 1,
  "student_id": 1,
  "student_name": "张三",
+  "template_name": "默认模板",
  "is_typical": false,
  "created_at": "2026-04-17 10:30",
+  "updated_at": "2026-04-27 15:00",
+  "updated_by_name": "管理员",
  "content": {
    "student_name": "张三",
    "practice_time": "30分钟",
@@ -561,6 +564,8 @@ GET /api/plans/<plan_id>
 }
 ```

+> **注意**: `updated_at` 和 `updated_by_name` 仅在方案被编辑过后才会有值。
+
 ---

 ### 获取学员方案列表
@@ -571,6 +576,82 @@ GET /api/students/<student_id>/plans

 ---

+### 获取推荐方案列表
+
+```
+GET /api/students/<student_id>/recommended-plans
+```
+
+**参数**:
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| filter | string | 筛选条件：`all`（全部）或 `mine`（我的） |
+
+**响应示例**:
+```json
+[
+  {
+    "id": 5,
+    "student_name": "李四",
+    "template_name": "默认模板",
+    "is_typical": true,
+    "created_at": "2026-04-20 10:00",
+    "problem_names": ["手小", "识谱慢"],
+    "can_adopt": true,
+    "adopted": false
+  }
+]
+```
+
+---
+
+### 采纳典型方案
+
+```
+POST /api/plans/<plan_id>/adopt
+```
+
+**请求体**:
+```json
+{
+  "student_id": 1
+}
+```
+
+**响应**:
+```json
+{
+  "message": "方案已采纳",
+  "plan_id": 6
+}
+```
+
+---
+
+### 更新方案内容
+
+```
+PUT /api/plans/<plan_id>/content
+```
+
+**功能**: 编辑方案后保存内容
+
+**请求体**:
+```json
+{
+  "content": "{\"ai_report\": \"...\", \"daily_schedule\": [...]}"
+}
+```
+
+**响应**:
+```json
+{
+  "message": "保存成功"
+}
+```
+
+---
+
 ### 设为典型方案

 ```
@@ -592,8 +673,6 @@ POST /api/plans/<plan_id>/typical
 ```
 DELETE /api/plans/<plan_id>
 ```
-}
-```

 ### 导出PDF

@@ -1,11 +1,37 @@
 # 钢琴练习方案系统 - 部署 SOP

-> 版本：v1.3.6
-> 日期：2026-04-26
+> 版本：v1.4.0
+> 日期：2026-04-27
 > 核心原则：**不删除，只备份后新增/替换**

 ---

+## 重要更新（v1.4.0）
+
+### ⚠️ 问题文件已迁移到数据库
+
+**历史**：`/app/个性化方案/*.md`（15个问题文件）
+
+**现状**：所有问题数据已迁移到 `problems` 表，不再需要挂载问题文件目录。
+
+**影响**：
+- 部署时不再检查问题文件数量
+- 不再需要 `/opt/piano-plan/个性化方案` 挂载
+- 验证清单中"问题文件数量"检查已废弃
+
+### ⚠️ Docker 构建需要代理
+
+**本地代理端口**：`15000`
+
+构建命令：
+```powershell
+$env:HTTP_PROXY="http://127.0.0.1:15000"
+$env:HTTPS_PROXY="http://127.0.0.1:15000"
+docker build -t piano-plan:latest .
+```
+
+---
+
 ## 一、部署原则（铁律）

 | 操作 | 允许？ | 说明 |
@@ -121,11 +147,15 @@ with open('releases/v1.3.0/toRelease/schema.sql', 'w', encoding='utf-8') as f:
 ```powershell
 cd "D:\F\NewI\opencode\daily-workspace\projects\青年钢琴集体课\练习方案系统"

+# 0. 配置代理（必须！）
+$env:HTTP_PROXY="http://127.0.0.1:15000"
+$env:HTTPS_PROXY="http://127.0.0.1:15000"
+
 # 1. 构建镜像
-docker build -t piano-plan:v1.3.0 .
+docker build -t piano-plan:v1.4.0 .

 # 2. 保存镜像
-docker save piano-plan:v1.3.0 -o releases/v1.3.0/toRelease/program/piano-plan.tar
+docker save piano-plan:v1.4.0 -o releases/v1.4.0/toRelease/program/piano-plan.tar
 ```

 ---
@@ -358,11 +388,14 @@ A: 检查是否执行了 migrate_goals_v3.py 迁移脚本，该脚本创建 stud
 ```
 [ ] 容器状态：running
 [ ] 服务响应：HTTP 200/302
-[ ] 数据库表完整：users, students, classes, student_problems, practice_plans, problems, goals, goal_relations, student_goals, student_goal_evaluations
+[ ] 数据库表完整：users, students, classes, student_problems, practice_plans, templates, problems, goals, goal_relations, student_goals, student_goal_evaluations
+[ ] practice_plans 表有新字段：created_by, updated_by, updated_at, template_id, is_typical
 [ ] 目标管理功能正常：创建目标、分配目标、评估目标
 [ ] 时间线正常显示阶段评估和最终评估
 [ ] API 配置正确
 [ ] 功能验证：能生成练习方案
+[ ] 方案列表支持删除
+[ ] 学员列表"暂无方案/问题"样式正常
 ```

 ---
@@ -371,18 +404,19 @@ A: 检查是否执行了 migrate_goals_v3.py 迁移脚本，该脚本创建 stud

 | 版本 | 日期 | 变更 |
 |------|------|------|
-| v1.3.6 | 2026-04-24 | 方案详情导航优化（学员名→学员详情、返回按钮修复）；典型方案开关移至方案详情；方案列表显示问题级别+严重程度；plan.content新增level字段；学员生成方案增加模板选择器；生成时禁用按钮；完成后显示提示词/报告字数；学员目标删除支持级联删除评估；目标模板删除增加依赖检查；API文档更新 |
-| v1.3.5 | 2026-04-24 | 班级班主任字段；用户姓名name字段；班级/学员/方案增加"我的"筛选；用户管理：姓名字段+可编辑；方案管理：模板列表权限修复；时间线"我的"按钮样式优化 |
-| v1.3.4 | 2026-04-24 | 方案编辑按钮；问题增量添加；teachers API公开；用户管理权限修复 |
+| v1.4.0 | 2026-04-27 | 典型方案采纳；推荐方案列表；方案编辑/详情页导航优化（bfcache处理）；审计字段完善（created_by/updated_by/updated_at）；方案列表支持删除；学员列表"暂无方案/问题"样式统一 |
+| v1.3.6 | 2026-04-24 | 方案详情导航优化；典型方案开关移至方案详情；方案列表显示问题级别+严重程度 |
+| v1.3.5 | 2026-04-24 | 班级班主任字段；用户姓名name字段；班级/学员/方案增加"我的"筛选 |
+| v1.3.4 | 2026-04-24 | 方案编辑按钮；问题增量添加；teachers API公开 |
 | v1.3.3 | 2026-04-24 | 评估日期编辑；最终评估关联 StudentGoal 同步 |
-| v1.3.2 | 2026-04-24 | StudentGoal 新增 status 字段；新增 StudentGoalEvaluation 表；阶段评估+最终评估功能；时间线增强（尚余天数/提前或延迟达成） |
+| v1.3.2 | 2026-04-24 | StudentGoal 新增 status 字段；新增 StudentGoalEvaluation 表 |
 | v1.3.1 | 2026-04-24 | DRY 规范；Fragment 复用方案；班级批量分配目标 |
-| v1.3 | 2026-04-24 | 目标管理模块：Goal/GoalRelation/StudentGoal；问题分类重构；学习历程时间线 |
+| v1.3 | 2026-04-24 | 目标管理模块：Goal/GoalRelation/StudentGoal；问题分类重构 |
 | v1.2 | 2026-04-23 | 问题迁移到数据库；移除个性化方案挂载 |
 | v1.1 | 2026-04-20 | 模板管理；API配置界面 |
 | v1.0 | 2026-04-17 | 初始版本 |

 ---

-> **最后更新**：2026-04-24
-> **更新原因**：v1.3.6 发布；方案详情导航优化；典型方案开关移至详情页；列表显示级别+严重程度；生成方案增加模板选择器；提示词字数确认
+> **最后更新**：2026-04-27
+> **更新原因**：v1.4.0 发布；问题文件已废弃（迁移到数据库）；添加代理配置说明；审计字段；方案列表删除功能
@@ -200,7 +200,8 @@ deploy: v1.2.0 生产环境部署
 | V1.2 | 2026-04-18 | 添加用户管理、角色权限、班级管理 |
 | V1.2.0 | 2026-04-23 | 问题迁移到数据库；URL导航改造；侧边栏统一 |
 | V1.3 | 2026-04-25 | 目标管理模块上线；班级级别属性；{student_goals}参数；提示词预览 |
+| V1.4 | 2026-04-27 | 典型方案采纳；推荐方案列表；方案编辑/详情页导航优化；审计字段完善 |

 ---

-*最后更新：2026-04-25*
+*最后更新：2026-04-27*
@@ -255,3 +255,28 @@ app/templates/
 |------|------|----------|
 | 2026-04-21 | v1.0 | 初始文档，定义 base.html 模板继承模式 |
 | 2026-04-23 | v1.1 | 添加 URL 导航模式说明；新增 home.html, student.html, plan_edit.html |
+| 2026-04-27 | v1.2 | 方案编辑/详情页导航优化：bfcache 处理、pageshow 事件、sessionStorage 标记 |
+
+## 9. 方案编辑页面导航
+
+### 9.1 编辑流程
+
+```
+学员详情/方案列表 → 方案详情 → 编辑 → 保存 → 返回方案详情/学员详情/方案列表
+```
+
+### 9.2 导航实现
+
+| 操作 | 实现方式 |
+|------|----------|
+| 保存后返回 | `history.back()` 返回上一页（编辑页），浏览器从 bfcache 恢复方案详情页 |
+| 方案详情加载 | `pageshow` 事件检测 bfcache 恢复，自动调用 `loadPlan()` 刷新数据 |
+| 返回按钮 | `history.back()` 返回上一页 |
+
+### 9.3 sessionStorage 标记
+
+| 标记 | 用途 |
+|------|------|
+| `plan_detail_referrer` | 记录方案详情页的来源（student/plans），编辑保存后用于决定跳转目标 |
+| `needs_refresh_recommended` | 标记需要刷新推荐方案列表 |
+| `plans_needs_refresh` | 标记需要刷新方案列表页 |
@@ -104,8 +104,17 @@
 |------|------|------|
 | id | Integer | 主键，自增 |
 | student_id | Integer | 外键，关联 Student |
+| template_id | Integer | 外键，关联 Template（AI提示词模板） |
+| is_typical | Boolean | 是否为典型方案 |
 | content | Text | 方案内容（JSON格式） |
+| created_by | Integer | 外键，关联 User（创建人） |
 | created_at | DateTime | 创建时间 |
+| updated_by | Integer | 外键，关联 User（更新人，仅编辑时设置） |
+| updated_at | DateTime | 更新时间（仅编辑时设置） |
+
+**审计字段说明**：
+- `created_by`：创建时设置
+- `updated_by`、`updated_at`：仅在编辑更新时设置，初次创建时为空

 **content 字段结构**:
 ```json
@@ -36,7 +36,9 @@
 │       ├── index.html         # 学员管理页面（继承base）
 │       ├── home.html          # 默认首页（显示统计信息）
 │       ├── student.html       # 学员详情页（URL导航）
+│       ├── plan_detail.html   # 方案详情页（URL导航）
 │       ├── plan_edit.html     # 方案编辑页（URL导航）
+│       ├── plans.html         # 方案管理列表页
 │       ├── settings.html      # 问题配置页面（继承base）
 │       ├── login.html         # 登录页面（独立）
 │       ├── setup.html         # 初始设置页面（独立）
@@ -140,14 +142,18 @@ def create_app():

 | 路由 | 方法 | 说明 |
 |------|------|------|
-| `/api/generate-plan` | POST | 生成练习方案 |
+| `/api/generate-plan` | POST | 生成练习方案（SSE） |
 | `/api/generate-plan/preview` | POST | 预览提示词 |
 | `/api/plans/<id>` | GET | 获取方案详情 |
+| `/api/plans/<id>/content` | PUT | 更新方案内容 |
 | `/api/plans/<id>/pdf` | GET | 导出PDF |
 | `/api/plans/<id>/md` | GET | 导出Markdown |
 | `/plans/<id>/wechat` | GET | 微信卡片 |
 | `/api/plans/<id>` | DELETE | 删除方案 |
 | `/api/plans/<id>/typical` | POST | 设为典型方案 |
+| `/api/plans/<id>/adopt` | POST | 采纳典型方案 |
+| `/api/students/<id>/plans` | GET | 获取学员方案列表 |
+| `/api/students/<id>/recommended-plans` | GET | 获取推荐方案列表 |

 ### routes/settings.py

@@ -285,4 +291,5 @@ generate_pdf(plan_id, student_name, content, output_dir)
 | V1.1 | 2026-04-17 | 添加用户登录认证系统 |
 | V1.2 | 2026-04-18 | 添加用户管理、角色权限、班级管理 |
 | V1.2.0 | 2026-04-23 | 问题迁移到数据库；URL导航改造；侧边栏统一 |
-| V1.3 | 2026-04-25 | 目标管理模块上线；班级级别属性；{student_goals}参数；提示词预览 |
+| V1.3 | 2026-04-25 | 目标管理模块上线；班级级别属性；{student_goals}参数；提示词预览 |
+| V1.4 | 2026-04-27 | 典型方案采纳；推荐方案列表；方案编辑/详情页导航优化；审计字段完善 |