# 目标管理模块设计

> 日期：2026-04-23
> 状态：待评审

## 概述

目标管理模块用于管理系统化的钢琴学习目标，支持目标间的多对多关联（DAG结构），以及目标与学员的关联记录。

## 数据模型

### 1. Goal (目标)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键，自增 |
| name | String(100) | 目标名称，必填 |
| content | Text | Markdown 格式详细内容 |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

### 2. GoalRelation (目标关联 - 自关联多对多)

| 字段 | 类型 | 说明 |
|------|------|------|
| parent_goal_id | Integer | 外键 → goals.id |
| child_goal_id | Integer | 外键 → goals.id |
| PRIMARY KEY | (parent_goal_id, child_goal_id) | 联合主键 |

**约束**：
- 禁止循环引用（A→B→C→A）
- 自关联：goal 可以是自身的父/子节点

### 3. StudentGoal (学员目标记录)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键，自增 |
| student_id | Integer | 外键 → students.id |
| goal_id | Integer | 外键 → goals.id |
| status | String(20) | 状态：未开始/进行中/已完成 |
| mastery_level | Integer | 完成度：1-5（1最少，5最精通） |
| deadline | DateTime | 截止日期 |
| completed_at | DateTime | 完成日期 |
| created_at | DateTime | 创建时间 |

**显示规则**：
- `mastery_level` 直接渲染为对应数量的五角星（★）

---

## API 接口

### 目标管理

```
GET    /api/goals                      # 获取所有目标
POST   /api/goals                      # 创建目标
GET    /api/goals/<id>                 # 获取目标详情
PUT    /api/goals/<id>                 # 更新目标
DELETE /api/goals/<id>                 # 删除目标
```

### 目标关联

```
GET    /api/goals/<id>/parents          # 获取父目标列表
GET    /api/goals/<id>/children        # 获取子目标列表
POST   /api/goals/<id>/children        # 添加子目标关联
DELETE /api/goals/<id>/children/<child_id>  # 移除关联
```

### 学员目标

```
GET    /api/students/<student_id>/goals      # 获取学员的目标列表
POST   /api/students/<student_id>/goals      # 为学员添加目标
PUT    /api/students/<student_id>/goals/<goal_id>  # 更新学员目标状态
DELETE /api/students/<student_id>/goals/<goal_id>  # 移除学员的目标
```

---

## 循环引用检测

在添加关联时必须检测：

```python
def has_cycle(goal_id, new_child_id):
    """检测添加 new_child_id 作为 goal_id 的子目标是否会形成循环"""
    visited = set()
    stack = [new_child_id]

    while stack:
        current = stack.pop()
        if current == goal_id:
            return True  # 发现循环
        if current in visited:
            continue
        visited.add(current)
        # 获取 current 的所有子目标，继续检测
        for child in get_children(current):
            stack.append(child)

    return False
```

---

## 前端页面

### 1. 目标管理页面 (`/goals`)

- 目标列表（可树状展示）
- 创建/编辑/删除目标
- 目标内容 Markdown 编辑器
- 关联管理（拖拽或选择器添加关联）

### 2. 学员详情页目标区块

在现有 `student.html` 中扩展：
- 显示学员的目标列表
- 每项目标显示：名称、状态、★完成度、截止日期
- 可添加/移除/编辑目标
- 状态变更触发刷新

---

## 实现顺序

1. **数据模型** - goals, goal_relations, student_goals 表
2. **目标 CRUD API** - 基础的增删改查
3. **目标关联 API** - 关联管理 + 循环检测
4. **学员目标 API** - 学员与目标的关联管理
5. **目标管理页面** - 目标列表 + 关联管理
6. **学员详情页扩展** - 目标区块

---

## 依赖关系

- 无外部依赖
- 复用现有的 Markdown 编辑器（EasyMDE）和星级组件