# 用户使用流程图 — 其他功能

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 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 actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3

    %% ============ 角色 ============
    ROLE_PARENT(("👤 家长/孩子")):::actor
    ROLE_ADMIN(("🖥 管理员")):::actor
    ROLE_SYSTEM(("⚙️ 系统")):::actor

    %% ================================================================
    %% 阶段一：用户吉祥物
    %% ================================================================
    subgraph 阶段一[阶段一：用户吉祥物]
        direction TB

        P1["🏠 个人中心：吉祥物设置"]:::page
        P1 -->|"选择 xibao/fubao"| A1["🔗 POST /api/user/mascot/set"]:::api
        A1 -->|"userId, 吉祥物代码"| S1["⚙️ UserService.setMascot()"]:::service
        S1 -->|"更新用户 mascot 字段"| D1["📦 users 表"]:::data

        P1 -->|"查看当前吉祥物"| A1a["🔗 POST /api/user/mascot/get"]:::api
        A1a -->|"userId"| S1a["⚙️ UserService.getUserInfo()"]:::service
        S1a -->|"mascot 字段值"| D1
    end

    %% ================================================================
    %% 阶段二：用户分群（RFM）
    %% ================================================================
    subgraph 阶段二[阶段二：用户分群（RFM）]
        direction TB

        P2["🏠 系统后台：用户分群页"]:::page
        P2 -->|"触发RFM计算"| A2["🔗 POST /api/segmentation/rfm/calculate"]:::api
        A2 -->|"userId"| S2["⚙️ UserSegmentationService.calculateRfm()"]:::service
        S2 -->|"R/F/M 分值 + 层级标签"| D2["📦 user_rfm_tags 表"]:::data

        D2 -->|"userId"| A2a["🔗 POST /api/segmentation/rfm/detail"]:::api
        A2a -->|"userId"| S2a["⚙️ UserSegmentationService.getUserRfm()"]:::service
        S2a -->|"RFM 详细数据"| D2

        D2 -->|"分群结果"| A2b["🔗 POST /api/segmentation/trigger/rules"]:::api
        A2b -->|"userId, triggerType"| S2b["⚙️ UserSegmentationService.getTriggerRules()"]:::service
        S2b -->|"触发规则列表"| D2b["📦 user_trigger_rules 表"]:::data
    end

    %% ================================================================
    %% 阶段三：外部平台同步
    %% ================================================================
    subgraph 阶段三[阶段三：外部平台同步（zkxz）]
        direction TB

        P3["🏠 系统自动：定时同步"]:::page
        P3 -->|"客户ID"| A3["🔗 POST /api/sncp/addClient/{clientId}"]:::api
        A3 -->|"clientId"| S3["⚙️ ZkxzSyncService.syncClient()"]:::service
        S3 -->|"同步结果"| D3["📦 zkxz 外部平台"]:::data

        P3 -->|"用户登录名"| A3a["🔗 POST /api/sncp/notice/{userLogin}"]:::api
        A3a -->|"userLogin"| S3a["⚙️ ZkxzSyncService（通知查询）"]:::service
        S3a -->|"通知内容"| D3
    end

    %% ================================================================
    %% 阶段四：每日反馈
    %% ================================================================
    subgraph 阶段四[阶段四：每日反馈]
        direction TB

        P4["🏠 家长端：今日反馈页"]:::page
        P4 -->|"查看今日反馈"| A4["🔗 POST /api/feedback/today"]:::api
        A4 -->|"userId, childId"| S4["⚙️ DailyFeedbackService.getTodayFeedback()"]:::service
        S4 -->|"当日反馈内容（无则自动生成）"| D4["📦 daily_feedback 表"]:::data

        D4 -->|"标记已读"| A4a["🔗 POST /api/feedback/read"]:::api
        A4a -->|"feedback id"| S4a["⚙️ DailyFeedbackService.markAsRead()"]:::service
        S4a -->|"is_read = 1"| D4

        D4 -->|"查看历史"| A4b["🔗 POST /api/feedback/recent"]:::api
        A4b -->|"childId, limit"| S4b["⚙️ DailyFeedbackService.getRecentFeedbacks()"]:::service
        S4b -->|"最近N条反馈列表"| D4
    end

    %% ================================================================
    %% 阶段五：健康互动（点赞）
    %% ================================================================
    subgraph 阶段五[阶段五：健康互动（点赞）]
        direction TB

        P5["🏠 家长端：健康互动页"]:::page
        P5 -->|"点赞家庭成员"| A5["🔗 POST /api/health/interact/like"]:::api
        A5 -->|"userId, toUserId, actionType, actionId, familyId"| S5["⚙️ HealthInteractionService.like()"]:::service
        S5 -->|"写入互动记录"| D5["📦 health_interaction 表"]:::data
    end

    %% ================================================================
    %% 阶段六：商品推荐
    %% ================================================================
    subgraph 阶段六[阶段六：商品推荐]
        direction TB

        P6["🏠 五维维度页：推荐商品"]:::page
        P6 -->|"按维度查看推荐"| A6["🔗 POST /api/recommend/dimension-products"]:::api
        A6 -->|"dimensionCode, familyId, memberId, limit"| S6["⚙️ ProductRecommendationService.getDimensionRecommendations()"]:::service
        S6 -->|"维度关联商品列表"| D6["📦 products 表（商品查询）"]:::data
    end

    %% ================================================================
    %% 阶段七：通用工具
    %% ================================================================
    subgraph 阶段七[阶段七：通用工具]
        direction TB

        P7["🏠 邀请页：生成小程序码"]:::page
        P7 -->|"邀请注册"| A7["🔗 POST /api/common/qrcode"]:::api
        A7 -->|"type=register, referralCode"| S7["⚙️ WechatService.generateWxacode()"]:::service
        S7 -->|"base64 小程序码图片"| D7["📦 微信服务器（临时素材）"]:::data
    end

    %% ================================================================
    %% 阶段八：新手引导
    %% ================================================================
    subgraph 阶段八[阶段八：新手引导]
        direction TB

        P8["🏠 新手引导页"]:::page
        P8 -->|"查看引导进度"| A8["🔗 POST /api/onboarding/progress"]:::api
        A8 -->|"userId"| S8["⚙️ OnboardingService.getProgress()"]:::service
        S8 -->|"引导任务列表及状态"| D8["📦 onboarding_task 表"]:::data

        D8 -->|"完成任务领取奖励"| A8a["🔗 POST /api/onboarding/claim"]:::api
        A8a -->|"userId, taskType"| S8a["⚙️ OnboardingService.claimReward()"]:::service
        S8a -->|"发放积分/能量，更新状态"| D8
    end

    %% ============ 角色关联 ============
    ROLE_PARENT -.- P1
    ROLE_PARENT -.- P4
    ROLE_PARENT -.- P5
    ROLE_PARENT -.- P6
    ROLE_PARENT -.- P7
    ROLE_PARENT -.- P8
    ROLE_ADMIN -.- P2
    ROLE_SYSTEM -.- P3
```

## 端点明细

### 用户吉祥物

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/user/mascot/set` | 设置吉祥物 | 📱小程序 | `{mascot: "xibao" | "fubao" \| null}` | `{success}` |
| `POST /api/user/mascot/get` | 获取当前吉祥物 | 📱小程序 | — | `{mascot}` |

### 用户分群

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/segmentation/rfm/calculate` | 计算RFM标签 | ⚙️系统自动 | — | `UserRfmTag（R/F/M分值+tier）` |
| `POST /api/segmentation/rfm/detail` | 获取RFM详情 | 📱小程序 | — | `UserRfmTag对象` |
| `POST /api/segmentation/trigger/rules` | 获取触发规则 | 📱小程序 | `{triggerType}` | `List<UserTriggerRule>` |

### 外部同步（zkxz）

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/sncp/addClient/{clientId}` | 同步客户到zkxz | ⚙️系统自动 | path: `clientId` | `同步结果` |
| `POST /api/sncp/notice/{userLogin}` | 获取zkxz通知 | ⚙️系统自动 | path: `userLogin` | `通知内容` |

### 每日反馈

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/feedback/today` | 获取今日反馈 | 📱小程序 | `{childId}` | `{feedback, hasFeedback}` |
| `POST /api/feedback/read` | 标记反馈已读 | 📱小程序 | `{id}` | `{ok}` |
| `POST /api/feedback/recent` | 获取最近反馈列表 | 📱小程序 | `{childId, limit}` | `List<DailyFeedback>` |

### 健康互动

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/health/interact/like` | 点赞家庭成员 | 📱小程序 | `{toUserId, actionType, actionId, familyId}` | `Void` |

### 商品推荐

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/recommend/dimension-products` | 维度页推荐商品 | 📱小程序 | `{dimensionCode, familyId, memberId, limit, excludeProductIds}` | `List<推荐商品>` |

### 通用工具

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/common/qrcode` | 生成小程序码 | 📱小程序 | `{type, referralCode}` | `{qrCodeBase64}` |

### 新手引导

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/onboarding/progress` | 获取引导进度 | 📱小程序 | — | `List<OnboardingTask>` |
| `POST /api/onboarding/claim` | 领取引导奖励 | 📱小程序 | `{taskType}` | `{success}` |

## 数据实体关系

```mermaid
erDiagram
    User ||--o{ UserRfmTag : "userId 关联"
    User ||--o{ UserTriggerRule : "userId 关联"
    User ||--o{ OnboardingTask : "userId 关联"
    FamilyMember ||--o{ DailyFeedback : "childId 关联"
    FamilyMember ||--o{ HealthInteraction : "toUserId 关联"

    UserRfmTag {
        Long id PK
        Long userId FK
        int rScore "最近消费"
        int fScore "消费频率"
        int mScore "消费金额"
        string rfmTier "RFM层级标签"
    }

    UserTriggerRule {
        Long id PK
        Long userId FK
        string triggerType
        string triggerAction
        string actionConfig
        string status
    }

    DailyFeedback {
        Long id PK
        Long userId FK
        Long childId FK
        date feedbackDate
        string feedbackType "daily/weekly/milestone"
        string content
        int isRead
        string source "ai_generated/preset"
    }

    HealthInteraction {
        Long id PK
        Long familyId
        Long fromUserId
        Long toUserId
        string actionType
        Long actionId
    }

    OnboardingTask {
        Long id PK
        Long userId FK
        string taskType
        int rewardPoints
        int rewardEnergy
        string status
    }
```

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖8个独立功能模块：吉祥物设置、RFM分群、外平台同步、每日反馈、健康互动、商品推荐、小程序码生成、新手引导，均为独立流程 |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 各模块边界校验在Service层处理（如吉祥物仅允许xibao/fubao、PDF格式校验、zkxz启用检查），流程图简化了异常分支 |
| 3 | **端点覆盖** | ✅ 完整 | 16个端点全部映射到流程图中，与实际Controller代码一致（UserMascotController、UserSegmentationController、ZkxzSyncController、DailyFeedbackController、HealthInteractionController、ProductRecommendationController、CommonController、OnboardingController） |
| 4 | **角色覆盖** | ✅ 完整 | 家长/孩子使用吉祥物、反馈、互动、推荐、引导功能；管理员使用RFM用户分群；系统自动触发zkxz同步 |
| 5 | **数据实体** | ✅ 完整 | 覆盖users、user_rfm_tags、user_trigger_rules、daily_feedback、health_interaction、onboarding_task共6个数据表 |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller中的@PostMapping匹配，参数与Controller入参一致 |