# 用户使用流程图 — 健康知识库与邀请

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

    %% ================================================================
    %% 阶段一：健康知识库管理
    %% ================================================================
    subgraph 阶段一[阶段一：健康知识库管理]
        direction TB

        P1["🖥 管理后台：健康知识库页"]:::page
        P1 -->|"选择操作"| P1_choice{"查询 / 新增 / 编辑 / 删除 / 导入"}:::page

        P1_choice -->|"查询单条"| A1["🔗 POST /api/health/knowledge/query"]:::api
        A1 -->|"itemType, itemName"| S1["⚙️ HealthKnowledgeBaseService.query()"]:::service
        S1 -->|"类型+名称精确匹配"| D1["📦 health_knowledge_base 表"]:::data

        P1_choice -->|"批量查询"| A2["🔗 POST /api/health/knowledge/batch-query"]:::api
        A2 -->|"queries: [{itemType, itemName}]"| S2["⚙️ HealthKnowledgeBaseService.batchQuery()"]:::service
        S2 -->|"批量匹配返回Map"| D1

        P1_choice -->|"列表查询"| A3["🔗 POST /api/health/knowledge/list"]:::api
        A3 -->|"无参数"| S3["⚙️ HealthKnowledgeBaseService.listAll()"]:::service
        S3 -->|"返回全量知识库"| D1

        P1_choice -->|"新增条目"| P1a["🖥 知识库录入表单"]:::page
        P1a -->|"itemType, itemName, category, description, ..."| A4["🔗 POST /api/health/knowledge/add"]:::api
        A4 -->|"知识条目完整信息"| S4["⚙️ HealthKnowledgeBaseService.save()"]:::service
        S4 -->|"写入一条知识记录"| D1

        P1_choice -->|"编辑条目"| P1b["🖥 知识库编辑表单"]:::page
        P1b -->|"id及更新字段"| A5["🔗 POST /api/health/knowledge/update"]:::api
        A5 -->|"实体ID, 更新字段"| S5["⚙️ HealthKnowledgeBaseService.updateById()"]:::service
        S5 -->|"更新对应知识记录"| D1

        P1_choice -->|"删除条目"| P1c["🖥 确认删除"]:::page
        P1c -->|"id"| A6["🔗 POST /api/health/knowledge/delete"]:::api
        A6 -->|"知识条目ID"| S6["⚙️ HealthKnowledgeBaseService.removeById()"]:::service
        S6 -->|"物理删除"| D1

        P1_choice -->|"从JSON导入"| A7["🔗 POST /api/health/knowledge/import"]:::api
        A7 -->|"无参数（读取本地JSON）"| S7["⚙️ KnowledgeBaseDataImporter.importAll()"]:::service
        S7 -->|"批量导入菌属/指标/营养素等"| D1
    end

    %% ================================================================
    %% 阶段二：KB v3 查询
    %% ================================================================
    subgraph 阶段二[阶段二：KB v3 查询]
        direction TB

        D1 -->|"v3数据"| P2["🖥 管理后台：KB v3查询页"]:::page
        P2 -->|"选择查询类型"| P2_choice{"菌属 / 指标 / 食物 / 章节"}:::page

        P2_choice -->|"查询菌属功能"| A8["🔗 POST /api/health/knowledge/v3/bacteria/query"]:::api
        A8 -->|"name（菌名，支持属级回退）"| S8["⚙️ KnowledgeBaseV3Service.lookupBacteria()"]:::service
        S8 -->|"菌属功能说明"| D2["📦 v3索引（内存）"]:::data

        P2_choice -->|"批量查询菌属"| A9["🔗 POST /api/health/knowledge/v3/bacteria/batch-query"]:::api
        A9 -->|"names: [...]"| S9["⚙️ KnowledgeBaseV3Service.batchLookupBacteria()"]:::service
        S9 -->|"批量菌属功能说明"| D2

        P2_choice -->|"查询指标调整"| A10["🔗 POST /api/health/knowledge/v3/indicator/query"]:::api
        A10 -->|"name（指标名称）"| S10["⚙️ KnowledgeBaseV3Service.lookupIndicator()"]:::service
        S10 -->|"指标调整建议"| D2

        P2_choice -->|"查询食物营养"| A11["🔗 POST /api/health/knowledge/v3/food/query"]:::api
        A11 -->|"name（食物名称）"| S11["⚙️ KnowledgeBaseV3Service.lookupFood()"]:::service
        S11 -->|"食物营养数据"| D2

        P2_choice -->|"获取章节数据"| A12["🔗 POST /api/health/knowledge/v3/section"]:::api
        A12 -->|"section（章节名，空则返回目录）"| S12["⚙️ KnowledgeBaseV3Service.getSection()"]:::service
        S12 -->|"章节完整原始数据或目录结构"| D2
    end

    %% ================================================================
    %% 阶段三：Dify知识库
    %% ================================================================
    subgraph 阶段三[阶段三：Dify知识库管理]
        direction TB

        P3["🖥 管理后台：Dify知识库页"]:::page
        P3 -->|"选择操作"| P3_choice{"列表 / 查看 / 新增 / 删除"}:::page

        P3_choice -->|"列表查询"| A13["🔗 POST /api/admin/knowledge-base/list"]:::api
        A13 -->|"keyword, status, page, size"| S13["⚙️ DanKnowledgeBaseService.list()"]:::service
        S13 -->|"分页查询知识库"| D3["📦 dan_knowledge_base 表"]:::data

        P3_choice -->|"查看详情"| A14["🔗 POST /api/admin/knowledge-base/get"]:::api
        A14 -->|"id"| S14["⚙️ DanKnowledgeBaseService.getWithAssociations()"]:::service
        S14 -->|"知识完整信息+维度/标签关联"| D3

        P3_choice -->|"新增/编辑"| P3a["🖥 知识库编辑表单"]:::page
        P3a -->|"title, content, dimensionIds, tagIds, ..."| A15["🔗 POST /api/admin/knowledge-base/save"]:::api
        A15 -->|"知识条目+维度/标签绑定"| S15["⚙️ DanKnowledgeBaseService.saveWithAssociations()"]:::service
        S15 -->|"写入知识记录+关联, 同步Dify"| S15a["⚙️ DifySyncService.syncToDify()"]:::service
        S15a -->|"同步到Dify AI知识库"| D3a["📦 Dify外部API"]:::external

        P3_choice -->|"删除"| A16["🔗 POST /api/admin/knowledge-base/delete"]:::api
        A16 -->|"id"| S16["⚙️ DanKnowledgeBaseService.deleteKnowledge()"]:::service
        S16 -->|"逻辑删除知识记录"| D3

        P3_choice -->|"绑定维度"| A17["🔗 POST /api/admin/knowledge-base/bind-dimensions"]:::api
        A17 -->|"knowledgeId, dimensionIds"| S17["⚙️ DanKnowledgeBaseService.bindDimensions()"]:::service
        S17 -->|"写入维度关联表"| D3b["📦 知识-维度关联表"]:::data

        P3_choice -->|"绑定标签"| A18["🔗 POST /api/admin/knowledge-base/bind-tags"]:::api
        A18 -->|"knowledgeId, tagIds"| S18["⚙️ DanKnowledgeBaseService.bindTags()"]:::service
        S18 -->|"写入标签关联表"| D3c["📦 知识-标签关联表"]:::data

        P3_choice -->|"上传文件"| P3b["🖥 选择文件上传"]:::page
        P3b -->|"file (multipart)"| A19["🔗 POST /api/admin/knowledge-base/upload-file"]:::api
        A19 -->|"文件"| S19["⚙️ 文件存储到本地"]:::service
        S19 -->|"保存到 uploads/knowledge/ 目录"| D3d["📦 本地文件系统"]:::data

        P3_choice -->|"抓取网页"| P3c["🖥 输入网页URL"]:::page
        P3c -->|"url"| A20["🔗 POST /api/admin/knowledge-base/fetch-url"]:::api
        A20 -->|"网页URL"| S20["⚙️ RestTemplate抓取并解析"]:::service
        S20 -->|"提取标题+正文内容"| D3e["📦 抓取结果（内存）"]:::data
    end

    %% ================================================================
    %% 阶段四：邀请推广
    %% ================================================================
    subgraph 阶段四[阶段四：邀请推广]
        direction TB

        P4["📱 小程序：邀请推广页"]:::page
        P4 -->|"选择操作"| P4_choice{"生成邀请码 / 绑定 / 查看 / 二维码"}:::page

        P4_choice -->|"生成邀请码"| A21["🔗 POST /api/invite/code"]:::api
        A21 -->|"userId（从token提取）"| S21["⚙️ CommissionService.getOrCreateReferralCode()"]:::service
        S21 -->|"查询或生成推广码"| D4["📦 推广码（内存/用户关联）"]:::data

        P4_choice -->|"绑定邀请"| P4a["📱 输入/扫描邀请码"]:::page
        P4a -->|"referralCode"| A22["🔗 POST /api/invite/bind"]:::api
        A22 -->|"推广码"| S22["⚙️ CommissionService.bindReferral()"]:::service
        S22 -->|"建立邀请关系"| D4a["📦 邀请关系记录"]:::data

        P4_choice -->|"查看邀请列表"| A23["🔗 POST /api/invite/list"]:::api
        A23 -->|"page, size"| S23["⚙️ CommissionService.getMyReferrals()"]:::service
        S23 -->|"分页查询被我邀请的用户"| D4b["📦 users 表（通过推广码关联）"]:::data

        P4_choice -->|"邀请汇总"| A24["🔗 POST /api/invite/summary"]:::api
        A24 -->|"userId"| S24["⚙️ CommissionService.getReferralSummary()"]:::service
        S24 -->|"总邀请数, 奖励统计"| D4c["📦 ReferralSummaryDTO（内存）"]:::data

        P4_choice -->|"生成二维码"| A25["🔗 POST /api/invite/qrcode"]:::api
        A25 -->|"userId"| S25["⚙️ CommissionService.getOrCreateReferralCode()"]:::service
        S25 -->|"获取推广码"| S25a["⚙️ WechatService.generateWxacode()"]:::service
        S25a -->|"小程序码参数"| A25a["🔗 调用微信小程序码API"]:::external
        A25a -->|"小程序码图片base64"| D4d["📦 小程序码（返回前端）"]:::data
    end

    %% ================================================================
    %% 阶段五：邀请卡片
    %% ================================================================
    subgraph 阶段五[阶段五：邀请卡片]
        direction TB

        P5["📱 小程序：邀请卡片页"]:::page
        P5 -->|"选择操作"| P5_choice{"生成 / 验证 / 接受"}:::page

        P5_choice -->|"生成邀请卡片"| P5a["📱 选择邀请类型"]:::page
        P5a -->|"type(child/family/guide), refId"| A26["🔗 POST /api/invite-card/generate"]:::api
        A26 -->|"邀请类型, 关联ID, 创建人"| S26["⚙️ InviteCardService.generate()"]:::service
        S26 -->|"生成邀请码, 设定过期时间"| D5["📦 invite_card 表"]:::data

        P5_choice -->|"验证邀请码"| P5b["📱 输入/扫描邀请码"]:::page
        P5b -->|"code"| A27["🔗 POST /api/invite-card/verify"]:::api
        A27 -->|"邀请码字符串"| S27["⚙️ InviteCardService.verify()"]:::service
        S27 -->|"校验有效性, 返回邀请信息"| D5

        P5_choice -->|"接受邀请"| P5c["📱 填写手机号"]:::page
        P5c -->|"code, phone"| A28["🔗 POST /api/invite-card/accept"]:::api
        A28 -->|"邀请码, 手机号"| S28["⚙️ InviteCardService.accept()"]:::service
        S28 -->|"标记已使用, 完成邀请逻辑"| D5
    end

    %% ================================================================
    %% 阶段六：邀请里程碑与新手引导
    %% ================================================================
    subgraph 阶段六[阶段六：里程碑与引导]
        direction TB

        P6["📱 小程序：邀请奖励页"]:::page
        P6 -->|"里程碑列表"| A29["🔗 POST /api/invite/milestone/list"]:::api
        A29 -->|"userId"| S29["⚙️ 查询里程碑进度"]:::service
        S29 -->|"所有里程碑及当前达成状态"| D6["📦 invite_milestone 表"]:::data

        P6 -->|"领取里程碑奖励"| P6a["📱 点击领取按钮"]:::page
        P6a -->|"milestone"| A30["🔗 POST /api/invite/milestone/claim"]:::api
        A30 -->|"里程碑标识"| S30["⚙️ 发放积分/能量奖励"]:::service
        S30 -->|"更新状态为claimed"| D6

        P7["📱 小程序：新手引导页"]:::page
        P7 -->|"查看引导进度"| A31["🔗 POST /api/onboarding/progress"]:::api
        A31 -->|"userId"| S31["⚙️ OnboardingService.getProgress()"]:::service
        S31 -->|"引导任务列表及完成状态"| D7["📦 onboarding_task 表"]:::data

        P7 -->|"领取引导奖励"| P7a["📱 完成引导任务后领取"]:::page
        P7a -->|"taskType"| A32["🔗 POST /api/onboarding/claim"]:::api
        A32 -->|"任务类型"| S32["⚙️ OnboardingService.claimReward()"]:::service
        S32 -->|"发放积分/能量, 标记已领取"| D7
    end

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

## 端点明细

### 健康知识库

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/health/knowledge/query` | 查询知识库单条 | 🖥管理后台 | `{itemType, itemName}` | `HealthKnowledgeBase对象` |
| `POST /api/health/knowledge/batch-query` | 批量查询知识库 | 🖥管理后台 | `{queries: [{itemType, itemName}]}` | `{key: HealthKnowledgeBase}` |
| `POST /api/health/knowledge/list` | 知识库全量列表 | 🖥管理后台 | — | `[HealthKnowledgeBase对象]` |
| `POST /api/health/knowledge/add` | 新增知识条目 | 🖥管理后台 | `HealthKnowledgeBase实体JSON` | `{success}` |
| `POST /api/health/knowledge/update` | 更新知识条目 | 🖥管理后台 | `HealthKnowledgeBase实体JSON（含id）` | `{success}` |
| `POST /api/health/knowledge/delete` | 删除知识条目 | 🖥管理后台 | `{id}` | `{success}` |
| `POST /api/health/knowledge/import` | 从JSON全量导入 | 🖥管理后台 | — | `导入结果消息` |

### KB v3 查询

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/health/knowledge/v3/bacteria/query` | 查询菌属功能 | 🖥管理后台 | `{name}` | `{菌属功能说明}` |
| `POST /api/health/knowledge/v3/bacteria/batch-query` | 批量查询菌属 | 🖥管理后台 | `{names: [...]}` | `{name: {...}}` |
| `POST /api/health/knowledge/v3/indicator/query` | 查询指标调整建议 | 🖥管理后台 | `{name}` | `{指标调整建议}` |
| `POST /api/health/knowledge/v3/food/query` | 查询食物营养数据 | 🖥管理后台 | `{name}` | `{食物营养数据}` |
| `POST /api/health/knowledge/v3/section` | 获取章节原始数据 | 🖥管理后台 | `{section}`（空则返回目录） | `章节数据或目录结构` |

### Dify知识库

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/admin/knowledge-base/list` | 分页查询知识库 | 🖥管理后台 | `{keyword, status, page, size}` | `分页结果` |
| `POST /api/admin/knowledge-base/get` | 获取知识详情（含关联） | 🖥管理后台 | `id (RequestParam)` | `知识+维度+标签信息` |
| `POST /api/admin/knowledge-base/save` | 新增/编辑知识 | 🖥管理后台 | `{id?, title, content, dimensionIds, tagIds, ...}` | `DanKnowledgeBase对象` |
| `POST /api/admin/knowledge-base/delete` | 删除知识 | 🖥管理后台 | `id (RequestParam)` | `{success}` |
| `POST /api/admin/knowledge-base/bind-dimensions` | 绑定维度 | 🖥管理后台 | `{knowledgeId, dimensionIds}` | `{success}` |
| `POST /api/admin/knowledge-base/bind-tags` | 绑定标签 | 🖥管理后台 | `{knowledgeId, tagIds}` | `{success}` |
| `POST /api/admin/knowledge-base/upload-file` | 上传文件 | 🖥管理后台 | `file (multipart)` | `{fileUrl, fileName}` |
| `POST /api/admin/knowledge-base/fetch-url` | 抓取网页内容 | 🖥管理后台 | `{url}` | `{title, content, sourceUrl}` |

### 知识标签

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/admin/knowledge-tag/list` | 标签列表 | 🖥管理后台 | — | `[DanKnowledgeTag对象]` |
| `POST /api/admin/knowledge-tag/save` | 新增/编辑标签 | 🖥管理后台 | `DanKnowledgeTag实体JSON` | `DanKnowledgeTag对象` |
| `POST /api/admin/knowledge-tag/delete` | 删除标签 | 🖥管理后台 | `id (RequestParam)` | `{success}` |

### 邀请推广

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/invite/code` | 获取或生成推广码 | 📱小程序 | Header: `Authorization` | `推广码字符串` |
| `POST /api/invite/bind` | 绑定邀请关系 | 📱小程序 | `{referralCode}` | `"绑定成功"` |
| `POST /api/invite/list` | 我的邀请列表 | 📱小程序 | `{page, size}` | `Page<User>`（被邀请用户） |
| `POST /api/invite/summary` | 邀请汇总统计 | 📱小程序 | Header: `Authorization` | `ReferralSummaryDTO`（总数/奖励等） |
| `POST /api/invite/qrcode` | 生成推广小程序码 | 📱小程序 | Header: `Authorization` | `{qrCodeBase64, referralCode}` |

### 邀请卡片

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/invite-card/generate` | 生成邀请卡片（含码） | 📱小程序 | `{type, refId}` | `{code, expiresAt}` |
| `POST /api/invite-card/verify` | 验证邀请码有效性 | 📱小程序 | `{code}` | `{type, refId, expiresAt, valid}` |
| `POST /api/invite-card/accept` | 接受邀请 | 📱小程序 | `{code, phone}` | `{成员信息}` |

### 邀请里程碑

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/invite/milestone/list` | 里程碑列表及状态 | 📱小程序 | Header: `Authorization` | `[InviteMilestone对象]` |
| `POST /api/invite/milestone/claim` | 领取里程碑奖励 | 📱小程序 | `{milestone}` | `{success}` |

### 新手引导

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/onboarding/progress` | 获取引导任务进度 | 📱小程序 | Header: `Authorization` | `[OnboardingTask对象]` |
| `POST /api/onboarding/claim` | 领取引导任务奖励 | 📱小程序 | `{taskType}` | `奖励结果消息` |

## 数据实体关系

```mermaid
erDiagram
    User ||--o{ InviteMilestone : "一个用户多个里程碑"
    User ||--o{ OnboardingTask : "一个用户多个引导任务"
    User ||--o{ InviteCard : "一个用户生成多个邀请卡片"
    User ||--o{ ReferralRelation : "一个用户推广多个用户"
    DanKnowledgeBase ||--o{ DanKnowledgeTag : "多对多标签关联"
    DanKnowledgeBase ||--o{ Dimension : "多对多维度关联"

    HealthKnowledgeBase {
        Long id PK
        string itemType "bacteria/nutrient/indicator/vitamin/amino_acid/disease"
        string itemName
        string category
        string normalRange
        string description
        string suggestion
        string source
    }

    DanKnowledgeBase {
        Long id PK
        string title
        string content
        int sort
        int status
        string fileUrl
        string fileName
        string sourceUrl
        string sourceType
    }

    InviteCard {
        Long id PK
        string type "child/family/guide"
        string code "唯一邀请码"
        Long refId "关联ID"
        Long creatorId
        datetime expiresAt
        int used "0/1"
    }

    InviteMilestone {
        Long id PK
        Long userId FK
        string milestone
        int rewardPoints
        int rewardEnergy
        string status "PENDING/CLAIMED"
    }

    OnboardingTask {
        Long id PK
        Long userId FK
        string taskType
        int rewardPoints
        int rewardEnergy
        string status "PENDING/COMPLETED/CLAIMED"
    }
```

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖健康知识库（v1+v3）、Dify知识库管理、邀请推广、邀请卡片、里程碑/引导6个阶段，路径完整 |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 知识库查询时参数校验返回错误；邀请码绑定失败（重复/无效）catch异常返回错误信息；邀请卡生成时权限校验（非家庭成员拒绝生成） |
| 3 | **端点覆盖** | ✅ 完整 | 32个端点全部映射到流程图中，与HealthKnowledgeBaseController、KnowledgeBaseController、KnowledgeTagController、InviteController、InviteCardController、OnboardingController的`@PostMapping`一致 |
| 4 | **角色覆盖** | ✅ 完整 | 管理员(admin)管理知识库；家长(parent)使用邀请推广、邀请卡片、里程碑和引导功能；微信系统API参与小程序码生成 |
| 5 | **数据实体** | ✅ 完整 | health_knowledge_base、dan_knowledge_base、invite_card、invite_milestone、onboarding_task共5张核心表均在图中映射 |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller中的`@PostMapping`匹配，Service方法名与代码逻辑一致 |