cfc/docs/flows/knowledge-invite-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_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}	奖励结果消息

数据实体关系

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方法名与代码逻辑一致