# 用户使用流程图 — 天盘与运势

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 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_TEACHER(("📋 规划师")):::actor
    ROLE_ADMIN(("🖥 管理员")):::actor

    %% ================================================================
    %% 阶段一：天盘首页与仪表盘
    %% ================================================================
    subgraph 阶段一[阶段一：天盘首页与仪表盘]
        P1["🏠 家长端：天盘首页"]:::page
        P1 -->|"familyId, year, daysAhead"| A1["🔗 POST /api/tianpan/dashboard"]:::api
        A1 -->|"familyId, year, daysAhead"| S1["⚙️ TianpanService.buildDashboard()"]:::service
        S1 -->|"成员列表, 年度能量摘要, 近期运势, 兼容性概览"| D_DASH["📦 TianpanDashboardVO（聚合）"]:::data
        D_DASH -->|"仪表盘数据"| P1

        P1 -->|"点击成员"| P2["🏠 家长端：成员天盘页"]:::page
        P2 -->|"memberId, memberType"| A2["🔗 POST /api/tianpan/member/{memberId}"]:::api
        A2 -->|"memberId, memberType"| S2["⚙️ TianpanService.buildMemberDetail()"]:::service
        S2 -->|"成员基本信息, 生肖, 八字, 年度能量, 近期运势"| D_MEMBER["📦 TianpanMemberVO（聚合）"]:::data
        D_MEMBER -->|"成员详情"| P2
    end

    %% ================================================================
    %% 阶段二：兼容性与分析
    %% ================================================================
    subgraph 阶段二[阶段二：兼容性与分析]
        P2 -->|"选择2个成员"| P3["🏠 家长端：兼容性页面"]:::page
        P3 -->|"member1Id, member2Id"| A3["🔗 POST /api/tianpan/compatibility"]:::api
        A3 -->|"member1Id, member2Id, memberType"| S3["⚙️ TianpanService.computeCompatibility()"]:::service
        S3 -->|"五行匹配得分, 生肖相合, 兼容性评分"| D_COMP["📦 CompatibilityResultVO"]:::data
        D_COMP -->|"兼容性结果"| P3

        P2 -->|"查看年度能量"| P4["🏠 家长端：年度能量页"]:::page
        P4 -->|"memberId, year"| A4["🔗 POST /api/tianpan/annual-energy"]:::api
        A4 -->|"memberId, year"| S4["⚙️ TianpanService.buildAnnualEnergy()"]:::service
        S4 -->|"五维能量得分, 木星土星相位, 年度亮点"| D_ENERGY["📦 MemberAnnualEnergyVO"]:::data
        S4 -.->|"读写"| DE_TABLE["📦 tianpan_member_annual_energy 表"]:::data
        D_ENERGY -->|"年度能量"| P4
    end

    %% ================================================================
    %% 阶段三：每日运势
    %% ================================================================
    subgraph 阶段三[阶段三：每日运势]
        P1 -->|"查看运势"| P5["🏠 家长端：今日运势页"]:::page
        P5 -->|"familyId"| A5["🔗 POST /api/tianpan/daily-fortune"]:::api
        A5 -->|"familyId"| S5["⚙️ TianpanService.buildDailyFortune()"]:::service
        S5 -->|"农历日期, 干支, 五行, 宜忌, 家庭建议"| D_FORTUNE["📦 DailyFortuneVO"]:::data
        S5 -.->|"读写"| DF_TABLE["📦 tianpan_daily_fortune 表"]:::data
        D_FORTUNE -->|"运势数据"| P5

        P1 -->|"查看相关事项"| P6["🏠 家长端：相关事项页"]:::page
        P6 -->|"familyId, daysAhead"| A6["🔗 POST /api/tianpan/related-items"]:::api
        A6 -->|"familyId, daysAhead"| S6["⚙️ TianpanService.buildRelatedItems()"]:::service
        S6 -->|"近日重要事项, 重点关注成员"| D_ITEMS["📦 RelatedItemsVO"]:::data
        D_ITEMS -->|"事项列表"| P6

        P5 -->|"刷新运势"| A7["🔗 POST /api/mind/fortune/refresh"]:::api
        A7 -->|"系统自动触发"| S7["⚙️ FortuneService.getFamilyFortune() + calculateLuckyDirection()"]:::service
        S7 -->|"dominantElement, luckyDirection, fortuneLevel"| D_FAMILY["📦 family_fortune 表（新存）"]:::data
    end

    %% ================================================================
    %% 阶段四：预览与导出
    %% ================================================================
    subgraph 阶段四[阶段四：天盘周报导出]
        P5 -->|"导出周报PDF"| P7["🏠 家长端：导出天盘周报"]:::page
        P7 -->|"imageBase64, element, luckyDirection"| A8["🔗 POST /api/mind/fortune/export"]:::api
        A8 -->|"图片, 五行元素, 吉位, 提示"| S8["⚙️ PdfReportService.generatePdfReport()"]:::service
        S8 -->|"PDF字节数组"| S8a["⚙️ PdfReportService.savePdfReport()"]:::service
        S8a -->|"存储PDF文件"| D_FILE["📦 文件系统 /storage/reports/"]:::data
        S8a -->|"记录报告元数据"| D_REPORT["📦 family_fortune_reports 表"]:::data
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    ROLE_PARENT -.- P1
    ROLE_PARENT -.- P2
    ROLE_PARENT -.- P5
    ROLE_PARENT -.- P7
    ROLE_CHILD -.- P2
    ROLE_TEACHER -.- P2
    ROLE_ADMIN -.- P1
```

## 端点明细

### 天盘主接口

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/tianpan/dashboard` | 获取天盘仪表盘 | 📱小程序 | `{familyId, year, daysAhead, viewerRole}` | `TianpanDashboardVO`（成员列表、年度能量摘要、近期运势、兼容性概览） |
| `POST /api/tianpan/member/{memberId}` | 获取成员详情 | 📱小程序 | `{memberType, viewerRole}` | `TianpanMemberVO`（基本信息、生肖、八字、年度能量、近期运势） |
| `POST /api/tianpan/compatibility` | 计算兼容性 | 📱小程序 | `{member1Id, member2Id, memberType1, memberType2}` | `CompatibilityResultVO`（五行匹配得分、生肖相合、兼容性评分） |
| `POST /api/tianpan/annual-energy` | 获取年度能量 | 📱小程序 | `{memberId, year}` | `MemberAnnualEnergyVO`（五维能量得分、木星土星相位、年度亮点） |
| `POST /api/tianpan/daily-fortune` | 获取每日运势 | 📱小程序 | `{familyId}` | `DailyFortuneVO`（农历日期、干支、五行、宜忌、家庭建议） |
| `POST /api/tianpan/related-items` | 获取相关事项 | 📱小程序 | `{familyId, daysAhead}` | `RelatedItemsVO`（近日重要事项、重点关注成员） |

### 家庭运势接口

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/mind/fortune` | 获取今日家庭运势 | 📱小程序 | —（从用户ID取家庭） | `{dominantElement, luckyDirection, fortuneLevel, moodScore, ...}` |
| `POST /api/mind/fortune/refresh` | 手动刷新运势 | 📱小程序 | —（从用户ID取家庭） | `FamilyFortune` 完整对象 |
| `POST /api/mind/fortune/export` | 导出天盘周报PDF | 📱小程序 | `{imageBase64, element, luckyDirection, tip}` | `{pdfUrl, fileName, fileSize, element}` |

## 数据实体关系

```
family_fortune ←→ tianpan_daily_fortune （不同粒度的运势数据）
family_fortune_reports ←→ family_fortune （周报导出关联）
```

| 表名 | 主键 | 核心字段 | 说明 |
|------|------|---------|------|
| `family_fortune` | `id` | familyId, dominantElement, luckyDirection, fortuneLevel, moodScore, dailyTip, weeklyTip, fortuneDate | 家庭每日运势（含心情、提示） |
| `tianpan_daily_fortune` | `id` | familyId, date, lunarDate, dayGanzhi, fiveElementsMain, auspicious, inauspicious, familyAdvice | 天盘每日运势（含农历、干支、宜忌） |
| `tianpan_member_annual_energy` | `id` | memberId, year, dimensionsBody/Mind/Wisdom/Action/Wealth, jupiterPhase, saturnPhase | 成员年度五维能量 |
| `family_fortune_reports` | `id` | familyId, element, luckyDirection, pdfPath | 天盘周报PDF记录 |

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖天盘首页、成员详情、兼容性、年度能量、每日运势、相关事项、周报导出7个阶段 |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 权限校验（checkAccess）在Controller层统一处理，403拒绝已覆盖；成员不存在（404）已覆盖；生成占位数据（family_fortune无缓存时）逻辑在Service层，图中未展示 |
| 3 | **端点覆盖** | ✅ 完整 | 9个端点全部映射到流程图中，与TianpanController和MindFortuneController的`@PostMapping`一致 |
| 4 | **角色覆盖** | ✅ 完整 | 家长(parent)为天盘主要使用者；孩子(child)和规划师(teacher)可查看成员详情；管理员(admin)可访问天盘首页 |
| 5 | **数据实体** | ✅ 完整 | family_fortune、tianpan_daily_fortune、tianpan_member_annual_energy、family_fortune_reports均在图中映射 |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与TianpanController、MindFortuneController中的实际`@PostMapping`匹配 |