# 用户使用流程图 — 心理与情绪管理

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

```mermaid
flowchart TD
    %% ============ 颜色定义 ============
    classDef page fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:1px
    classDef service fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
    classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
    classDef external fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:3 2
    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3

    %% ============ 角色 ============
    ROLE_PARENT(("👤 家长")):::actor
    ROLE_CHILD(("👶 孩子")):::actor
    ROLE_SYS(("⚙️ 心理引擎")):::actor

    %% ================================================================
    %% 阶段一：情绪打卡
    %% ================================================================
    subgraph 阶段一[阶段一：情绪打卡]
        direction TB

        P1["🏠 小程序：情绪打卡页"]:::page
        P1 -->|"选择操作"| P1_choice{"记录情绪 / 查看分析"}:::page

        P1_choice -->|"记录情绪"| P1a["🏠 情绪记录表单"]:::page
        P1a -->|"孩子ID, 情绪标签, 评分, 压力值, 照片"| A1["🔗 POST /api/mind/checkin/create"]:::api
        A1 -->|"情绪打卡数据"| S1["⚙️ EmotionCheckinService.createCheckin()"]:::service
        S1 -->|"写入一条情绪打卡记录"| D1["📦 emotion_checkin 表"]:::data

        P1_choice -->|"查看分析"| P1b["🏠 情绪分析面板"]:::page
        P1b -->|"孩子ID, 分页"| A2["🔗 POST /api/mind/checkin/list"]:::api
        A2 -->|"孩子ID, 页码, 每页数"| S2["⚙️ EmotionCheckinService.getCheckinList()"]:::service
        S2 -->|"分页打卡列表"| D1

        P1b -->|"查看最近"| A3["🔗 POST /api/mind/checkin/latest"]:::api
        A3 -->|"孩子ID"| S3["⚙️ EmotionCheckinService.getLatestCheckin()"]:::service
        S3 -->|"最新一条打卡记录"| D1

        P1b -->|"查看趋势"| A4["🔗 POST /api/mind/checkin/trend"]:::api
        A4 -->|"孩子ID, 周期(week/month)"| S4["⚙️ EmotionCheckinService.getTrend()"]:::service
        S4 -->|"情绪趋势数据(效价/激活度)"| D1

        P1b -->|"查看统计"| A5["🔗 POST /api/mind/checkin/stats"]:::api
        A5 -->|"孩子ID"| S5["⚙️ EmotionCheckinService.getStats()"]:::service
        S5 -->|"情绪统计汇总"| D1

        P1b -->|"查看周报"| A6["🔗 POST /api/mind/checkin/weekly-report"]:::api
        A6 -->|"孩子ID"| S6["⚙️ EmotionCheckinService.getWeeklyReport()"]:::service
        S6 -->|"本周情绪报告"| D1
    end

    %% ================================================================
    %% 阶段二：情绪预警
    %% ================================================================
    subgraph 阶段二[阶段二：情绪预警]
        D1 -->|"孩子ID"| P2["🏠 小程序：情绪预警页"]:::page
        P2 -->|"查看筛查告警"| A7["🔗 POST /api/mind/alert/active"]:::api
        A7 -->|"孩子ID"| S7["⚙️ MentalHealthScreenService.getActiveAlerts()"]:::service
        S7 -->|"未解决的筛查告警列表"| D2["📦 emotion_alerts 表（筛查）"]:::data

        P2 -->|"查看打卡告警"| A8["🔗 POST /api/mind/alert/checkin-alerts"]:::api
        A8 -->|"孩子ID"| S8["⚙️ EmotionAlertService.getActiveAlerts()"]:::service
        S8 -->|"打卡检测的情绪告警列表"| D3["📦 emotion_alerts 表（打卡）"]:::data

        P2 -->|"处理告警"| A9["🔗 POST /api/mind/alert/resolve"]:::api
        A9 -->|"告警ID, 来源(screening/checkin)"| S9["⚙️ EmotionAlertService.resolveAlert()"]:::service
        S9 -->|"标记告警为已解决"| D4["📦 emotion_alerts（状态更新）"]:::data
    end

    %% ================================================================
    %% 阶段三：心理筛查
    %% ================================================================
    subgraph 阶段三[阶段三：心理筛查]
        D2 -->|"触发筛查"| P3["🏠 小程序：心理筛查页"]:::page
        P3 -->|"提交问卷(PHQ-9/GAD-7)"| A10["🔗 POST /api/mind/screening/submit"]:::api
        A10 -->|"孩子ID, 类型, 答案列表"| S10["⚙️ MentalHealthScreenService.submitScreen()"]:::service
        S10 -->|"评分, 严重等级, 风险标记, 建议"| D5["📦 mental_health_screens 表"]:::data

        D5 -->|"高风险(中重度以上)"| AUTO_ALERT["⚙️ 自动创建告警 + 推送通知"]:::service
        AUTO_ALERT -->|"告警记录"| D2

        P3 -->|"查看历史"| A11["🔗 POST /api/mind/screening/history"]:::api
        A11 -->|"孩子ID, 类型, 数量限制"| S11["⚙️ MentalHealthScreenService.getScreenHistory()"]:::service
        S11 -->|"筛查历史列表"| D5

        P3 -->|"查看最新"| A12["🔗 POST /api/mind/screening/latest"]:::api
        A12 -->|"孩子ID, 类型"| S12["⚙️ MentalHealthScreenService.getLatestScreen()"]:::service
        S12 -->|"最近一次筛查结果"| D5
    end

    %% ================================================================
    %% 阶段四：神经递质与肠脑洞察
    %% ================================================================
    subgraph 阶段四[阶段四：神经递质与肠脑洞察]
        D1 -->|"菌群报告数据"| P4["🏠 小程序：肠脑洞察页"]:::page
        P4 -->|"查看神经递质"| A13["🔗 POST /api/mind/neurotransmitters"]:::api
        A13 -->|"孩子ID"| S13["⚙️ HealthReportService.getMindRelatedIndicators()"]:::service
        S13 -->|"神经递质与激素, 短链脂肪酸指标"| D6["📦 health_indicators（按类别筛选）"]:::data

        P4 -->|"查看肠脑洞察"| A14["🔗 POST /api/mind/gut-emotion-insight"]:::api
        A14 -->|"孩子ID"| S14["⚙️ HealthReportService.getGutEmotionInsight()"]:::service
        S14 -->|"菌群-情绪关联分析摘要"| D7["📦 数据分析结果（内存中）"]:::data

        P4 -->|"查看EMI报告"| A15["🔗 POST /api/mind/emireport/latest"]:::api
        A15 -->|"孩子ID"| S15["⚙️ EmiReportService.getChildLatestEmiReport()"]:::service
        S15 -->|"完整EMI心理报告"| D8["📦 emi_reports 表"]:::data
    end

    %% ================================================================
    %% 阶段五：管理端操作
    %% ================================================================
    subgraph 阶段五[阶段五：管理端操作]
        D2 -->|"告警数据"| P5["🖥 管理后台：告警管理页"]:::page
        P5 -->|"查看全部告警"| A16["🔗 POST /api/mind/alert/admin/list"]:::api
        A16 -->|"页码, 每页数, 是否已解决"| S16["⚙️ EmotionAlertService.getAdminAlerts()"]:::service
        S16 -->|"分页告警列表"| D2
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    ROLE_CHILD -.- P1
    ROLE_CHILD -.- P1a
    ROLE_PARENT -.- P1
    ROLE_PARENT -.- P2
    ROLE_PARENT -.- P3
    ROLE_PARENT -.- P4
    ROLE_SYS -.- AUTO_ALERT
    ROLE_SYS -.- S13
    ROLE_SYS -.- S14
```

## 端点明细

### 情绪打卡

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/mind/checkin/create` | 创建情绪打卡 | 📱小程序 | `{childId, moodScore, emotionType, stressLevel, arousalLevel, energyLevel, photoUrl, note}` | `EmotionCheckinVO` |
| `POST /api/mind/checkin/list` | 获取打卡列表 | 📱小程序 | `{childId, page, size}` | `Page<EmotionCheckinVO>` |
| `POST /api/mind/checkin/latest` | 获取最新打卡 | 📱小程序 | `{childId}` | `EmotionCheckinVO` |
| `POST /api/mind/checkin/trend` | 获取情绪趋势 | 📱小程序 | `{childId, period(week/month)}` | `EmotionTrendVO` |
| `POST /api/mind/checkin/stats` | 获取情绪统计 | 📱小程序 | `{childId}` | `EmotionStatsVO` |
| `POST /api/mind/checkin/weekly-report` | 获取情绪周报 | 📱小程序 | `{childId}` | `WeeklyReportVO` |

### 情绪预警

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/mind/alert/active` | 获取筛查告警 | 📱小程序 | `{childId}` | `List<EmotionAlertVO>` |
| `POST /api/mind/alert/checkin-alerts` | 获取打卡告警 | 📱小程序 | `{childId}` | `List<EmotionAlertVO>` |
| `POST /api/mind/alert/resolve` | 处理告警 | 📱小程序 | `{alertId, source(screening/checkin)}` | `null` |
| `POST /api/mind/alert/admin/list` | 管理端告警列表 | 🖥管理后台 | `{page, size, resolved}` | `Page<EmotionAlertVO>` |

### 心理筛查

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/mind/screening/submit` | 提交筛查问卷 | 📱小程序 | `{childId, screenType(PHQ-9/GAD-7), answers[]}` | `ScreenResultVO`(含评分/严重等级/风险标记) |
| `POST /api/mind/screening/history` | 获取筛查历史 | 📱小程序 | `{childId, screenType, limit}` | `List<ScreenResultVO>` |
| `POST /api/mind/screening/latest` | 获取最新筛查结果 | 📱小程序 | `{childId, screenType}` | `ScreenResultVO` |

### 神经递质与肠脑洞察

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/mind/neurotransmitters` | 获取神经递质指标 | 📱小程序 | `{childId}` | `List<HealthIndicator>`(神经递质与激素类) |
| `POST /api/mind/gut-emotion-insight` | 获取肠脑洞察摘要 | 📱小程序 | `{childId}` | `{summary, analysis}` |
| `POST /api/mind/emireport/latest` | 获取最新EMI心理报告 | 📱小程序 | `{childId}` | `EmiReportDTO` |

## 数据实体关系

```mermaid
erDiagram
    Child ||--o{ EmotionCheckin : "一个孩子多条打卡"
    Child ||--o{ MentalHealthScreen : "一个孩子多次筛查"
    Child ||--o{ EmotionAlert : "一个孩子多个告警"
    EmotionCheckin ||--o{ EmotionAlert : "打卡触发低风险告警"
    MentalHealthScreen ||--o{ EmotionAlert : "高风险筛查自动创建告警"

    EmotionCheckin {
        Long id PK
        Long childId FK
        Integer moodScore "效价 1-10"
        String emotionType "joy/sadness/anger/..."
        Integer stressLevel "压力 1-10"
        Integer arousalLevel "激活度 1-10"
        Integer energyLevel "精力 1-10"
        String photoUrl
        String note
        Integer energyAwarded "奖励能量值"
        Date checkinDate
    }

    MentalHealthScreen {
        Long id PK
        Long childId FK
        String screenType "PHQ-9 / GAD-7"
        String answers "JSON 答案数组"
        Integer totalScore
        String severityLevel "正常/轻度/中度/中重度/重度"
        String riskFlags "JSON 风险标记"
        String suggestions "建议文案"
        Date completedAt
    }

    EmotionAlert {
        Long id PK
        Long childId FK
        String source "screening / checkin"
        String alertType
        String severity "high / medium / low"
        String description
        String suggestion
        Boolean resolved
    }
```

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖情绪打卡(6个端点)、情绪预警(4个端点)、心理筛查(3个端点)、神经递质与肠脑洞察(3个端点)共4个阶段，以及管理端告警管理，路径完整 |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 打卡图片查看权限（家长端隐藏孩子照片）已在Service层处理；高风险筛查自动创建告警和微信推送已覆盖 |
| 3 | **端点覆盖** | ✅ 完整 | 16个端点全部映射到流程图中，与代码实际暴露的`/api/mind/*`一致 |
| 4 | **角色覆盖** | ✅ 完整 | 孩子(创建打卡/查看自身)、家长(查看打卡/预警/筛查/肠脑洞察)、管理端(告警管理)均已覆盖 |
| 5 | **数据实体** | ✅ 完整 | emotion_checkin表、mental_health_screens表、emotion_alerts表、emi_reports表均在图中映射 |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller（EmotionCheckinController、EmotionAlertController、ScreeningController、MindController）中的`@PostMapping`匹配 |