cfc/docs/flows/tianpan-fortune-flow.md

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

端口说明: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动

分层说明: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

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匹配