# 用户使用流程图 — 财富与保险

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

    %% ================================================================
    %% 阶段一：财商打卡
    %% ================================================================
    subgraph 阶段一[阶段一：财商打卡]
        P1["🏠 家长/孩子端：打卡列表页"]:::page
        P1 -->|"查看当月打卡"| A1["🔗 GET /api/wealth/checkin/list"]:::api
        A1 -->|"userId, childId, yearMonth"| S1["⚙️ FinanceCheckinService.getCheckins()"]:::service
        S1 -->|"查询打卡记录"| D1["📦 finance_checkins 表"]:::data

        P1 -->|"查看打卡统计"| A2["🔗 GET /api/wealth/checkin/stats"]:::api
        A2 -->|"userId, childId"| S2["⚙️ FinanceCheckinService.getCheckinStats()"]:::service
        S2 -->|"统计连续打卡天数, 本月次数"| D1

        P1 -->|"创建打卡"| A3["🔗 POST /api/wealth/checkin/create"]:::api
        A3 -->|"checkinType, userId, childId"| S3["⚙️ FinanceCheckinService.createCheckin()"]:::service
        S3 -->|"插入一条打卡记录"| D1

        P1 -->|"删除打卡"| A4["🔗 POST /api/wealth/checkin/delete"]:::api
        A4 -->|"id"| S4["⚙️ FinanceCheckinService.deleteCheckin()"]:::service
        S4 -->|"删除指定打卡记录"| D1
    end

    %% ================================================================
    %% 阶段二：保险规划
    %% ================================================================
    subgraph 阶段二[阶段二：保险规划]
        D1 -->|"用户ID"| P2["🏠 家长端：保险规划页"]:::page
        P2 -->|"生成规划报告"| A5["🔗 POST /api/insurance/planning"]:::api
        A5 -->|"userId"| S5["⚙️ InsurancePlanningService.generatePlanningReport()"]:::service
        S5 -->|"家庭维度评分 + 保单覆盖分析"| D2["📦 PlanningReportDTO（内存中）"]:::data
        D2 -->|"评分数据, 已购保单"| D3["📦 dan_assessment_results + 已有保单"]:::data
    end

    %% ================================================================
    %% 阶段三：保单管理
    %% ================================================================
    subgraph 阶段三[阶段三：保单管理]
        D2 -->|"覆盖缺口建议"| P3["🏠 家长端：保单管理页"]:::page
        P3 -->|"查看保单列表"| A6["🔗 POST /api/wealth/insurance/list"]:::api
        A6 -->|"userId, status"| S6["⚙️ InsurancePolicyService.getPolicies()"]:::service
        S6 -->|"用户所有保单"| D4["📦 insurance_policies 表"]:::data

        P3 -->|"查看保单详情"| A7["🔗 POST /api/wealth/insurance/detail"]:::api
        A7 -->|"id"| S7["⚙️ InsurancePolicyService.getById()"]:::service
        S7 -->|"单条保单完整信息"| D4

        P3 -->|"创建保单"| A8["🔗 POST /api/wealth/insurance/create"]:::api
        A8 -->|"userId, policyJson"| S8["⚙️ InsurancePolicyService.createPolicy()"]:::service
        S8 -->|"插入一条保单记录"| D4

        P3 -->|"更新保单"| A9["🔗 POST /api/wealth/insurance/update"]:::api
        A9 -->|"policyJson"| S9["⚙️ InsurancePolicyService.updatePolicy()"]:::service
        S9 -->|"更新保单字段"| D4

        P3 -->|"删除保单"| A10["🔗 POST /api/wealth/insurance/delete"]:::api
        A10 -->|"id"| S10["⚙️ InsurancePolicyService.deletePolicy()"]:::service
        S10 -->|"逻辑/物理删除保单"| D4
    end

    %% ================================================================
    %% 阶段四：家庭收益
    %% ================================================================
    subgraph 阶段四[阶段四：家庭收益]
        D4 -->|"家庭ID"| P4["🏠 家长端：家庭收益页"]:::page
        P4 -->|"查看收益总览"| A11["🔗 POST /api/earnings/family/summary"]:::api
        A11 -->|"userId → familyId"| S11["⚙️ FamilyEarningsService.getFamilySummary()"]:::service
        S11 -->|"总收入, 可提现, 已分配"| D5["📦 family_earnings 表"]:::data

        P4 -->|"查看成员贡献"| A12["🔗 POST /api/earnings/family/members"]:::api
        A12 -->|"userId → familyId"| S12["⚙️ FamilyEarningsService.getMemberContributions()"]:::service
        S12 -->|"各成员贡献金额/次数"| D6["📦 family_earnings_members 表"]:::data

        P4 -->|"查看收支流水"| A13["🔗 POST /api/earnings/family/records"]:::api
        A13 -->|"familyId, type"| S13["⚙️ FamilyEarningsService.getRecords()"]:::service
        S13 -->|"筛选后的流水列表"| D7["📦 family_earnings_records 表"]:::data
    end

    %% ================================================================
    %% 阶段五：收益管理（管理员）
    %% ================================================================
    subgraph 阶段五[阶段五：收益管理（管理员）]
        D5 -->|"家庭ID"| P5["🖥 管理后台：收益管理页"]:::page
        P5 -->|"收益分配"| A14["🔗 POST /api/earnings/admin/distribute"]:::api
        A14 -->|"家庭管理员ID, userId, amount"| S14["⚙️ FamilyEarningsService.distribute()"]:::service
        S14 -->|"插入收益分配记录"| D5

        P5 -->|"切换成员访问权限"| A15["🔗 POST /api/earnings/admin/toggle-member"]:::api
        A15 -->|"管理员ID, userId, enabled"| S15["⚙️ FamilyEarningsService.toggleMemberAccess()"]:::service
        S15 -->|"更新成员状态"| D6

        P5 -->|"提现"| A16["🔗 POST /api/earnings/admin/withdraw"]:::api
        A16 -->|"管理员ID, amount"| S16["⚙️ FamilyEarningsService.withdraw()"]:::service
        S16 -->|"创建提现申请/记录"| D7
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    ROLE_PARENT -.- P1
    ROLE_PARENT -.- P2
    ROLE_PARENT -.- P3
    ROLE_PARENT -.- P4
    ROLE_CHILD -.- P1
    ROLE_ADMIN -.- P5
```

## 端点明细

### 财商打卡

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/wealth/checkin/list` | 获取打卡列表 | 📱小程序 | `{userId, childId, yearMonth}` | `List<FinanceCheckin>` |
| `POST /api/wealth/checkin/stats` | 获取打卡统计 | 📱小程序 | `{userId, childId}` | `{totalDays, consecutiveDays, monthlyCount}` |
| `POST /api/wealth/checkin/create` | 创建打卡记录 | 📱小程序 | `{checkinType, childId, ...}` | `FinanceCheckin` |
| `POST /api/wealth/checkin/delete` | 删除打卡记录 | 📱小程序 | `{id}` | `{success}` |

### 保险规划

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/insurance/planning` | 获取家庭保险规划报告 | 📱小程序 | Header: `Authorization` | `PlanningReportDTO（覆盖缺口, 建议保额）` |

### 保单管理

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/wealth/insurance/list` | 获取保单列表 | 📱小程序 | `{status}` | `List<InsurancePolicy>` |
| `POST /api/wealth/insurance/detail` | 获取保单详情 | 📱小程序 | `{id}` | `InsurancePolicy` |
| `POST /api/wealth/insurance/create` | 创建保单 | 📱小程序 | `InsurancePolicy JSON（含保单类型/金额/到期日）` | `InsurancePolicy` |
| `POST /api/wealth/insurance/update` | 更新保单 | 📱小程序 | `InsurancePolicy JSON（含id）` | `{success}` |
| `POST /api/wealth/insurance/delete` | 删除保单 | 📱小程序 | `{id}` | `{success}` |

### 家庭收益

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/earnings/family/summary` | 获取家庭收益总览 | 📱小程序 | Header: `Authorization` | `FamilyEarningsSummaryDTO（总收入/可提现/已分配）` |
| `POST /api/earnings/family/members` | 获取成员贡献列表 | 📱小程序 | Header: `Authorization` | `List（各成员贡献金额/次数）` |
| `POST /api/earnings/family/records` | 获取收支流水 | 📱小程序 | `{type}` | `List<FamilyEarningsRecord>` |
| `POST /api/earnings/admin/distribute` | 管理员分配收益 | 🖥管理后台 | `{userId, amount}` | `{success}` |
| `POST /api/earnings/admin/toggle-member` | 切换成员收益池权限 | 🖥管理后台 | `{userId, enabled}` | `{success}` |
| `POST /api/earnings/admin/withdraw` | 管理员提现 | 🖥管理后台 | `{amount}` | `{success}` |

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖财商打卡→保险规划→保单管理→家庭收益→管理员收益管理共5个阶段，路径完整 |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 打卡删除时id为空返回错误；保单详情id为空/不存在返回错误；收益管理员无权限时返回错误；其余异常由Service层处理 |
| 3 | **端点覆盖** | ✅ 完整 | 16个端点全部映射到流程图中，与代码实际暴露的`/api/wealth/*`、`/api/insurance/*`、`/api/earnings/*`一致 |
| 4 | **角色覆盖** | ✅ 完整 | 家长可进行打卡/规划/保单/收益查看；孩子可参与打卡；管理员可进行收益分配/提现操作 |
| 5 | **数据实体** | ✅ 完整 | finance_checkins表、insurance_policies表、family_earnings表、family_earnings_members表、family_earnings_records表均在图中映射 |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller（FinanceCheckinController、InsurancePolicyController、InsurancePlanningController、FamilyEarningsController、AdminEarningsController）中的`@PostMapping`匹配 |
| 7 | **废弃端点** | ✅ 已标记 | 无废弃端点；`/api/earnings/admin/*`实际在`FamilyEarningsController`中处理，虽命名为admin但靠角色检查控制权限 |