用户使用流程图 — 勋章与微行动

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

分层说明: 🏠 页面 → 🔗 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_ADMIN(("🔧 管理员")):::actor

    %% ================================================================
    %% 阶段一：勋章浏览
    %% ================================================================
    subgraph 阶段一[阶段一：勋章浏览]
        direction TB

        P1["🏠 小程序：勋章列表页"]:::page
        P1 -->|"查看所有启用勋章"| A1["🔗 POST /api/badges/list"]:::api
        A1 -->|"无参数"| S1["⚙️ BadgeService.getActiveBadges()"]:::service
        S1 -->|"查询isActive=1, 按sortOrder排序"| S1a["⚙️ BadgeMapper.selectList()"]:::service
        S1a -->|"Badge列表"| D1["📦 badge 表"]:::data

        P1 -->|"查看勋章详情"| P1a["🏠 勋章详情页"]:::page
        P1a -->|"id"| A2["🔗 POST /api/badges/detail"]:::api
        A2 -->|"id"| S2["⚙️ BadgeService.getBadgeById()"]:::service
        S2 -->|"按主键查询"| S2a["⚙️ BadgeMapper.selectById()"]:::service
        S2a -->|"Badge详情"| D1

        P1 -->|"收藏/取消收藏"| P1b["🏠 收藏按钮"]:::page
        P1b -->|"childId, badgeId"| A3["🔗 POST /api/badges/favorite"]:::api
        A3 -->|"childId, badgeId"| S3["⚙️ BadgeService.toggleFavorite()"]:::service
        S3 -->|"查询child_badge记录, 翻转isFavorite"| S3a["⚙️ ChildBadgeMapper.updateById()"]:::service
        S3a -->|"child_badge记录"| D2["📦 child_badge 表"]:::data
    end

    %% ================================================================
    %% 阶段二：勋章获得与统计
    %% ================================================================
    subgraph 阶段二[阶段二：勋章获得与统计]
        D2 -->|"childId"| P2["🏠 小程序：孩子勋章页"]:::page
        P2 -->|"查看孩子勋章列表"| A4["🔗 POST /api/badges/child/list"]:::api
        A4 -->|"childId"| S4["⚙️ BadgeService.getActiveChildBadges()"]:::service
        S4 -->|"查询status=1, 按收藏/获得时间排序"| S4a["⚙️ ChildBadgeMapper.selectList()"]:::service
        S4a -->|"ChildBadge列表"| D2
        S4 -->|"关联Badge定义"| S4b["⚙️ BadgeMapper.selectById()"]:::service
        S4b -->|"Badge详情"| D1
        S4b -->|"合并后返回"| D3["📦 {childBadge, badge}（返回前端）"]:::data

        P2 -->|"勋章统计"| P2a["🏠 勋章统计面板"]:::page
        P2a -->|"childId"| A5["🔗 POST /api/badges/statistics/child"]:::api
        A5 -->|"childId"| S5["⚙️ BadgeService.getChildBadgeStats()"]:::service
        S5 -->|"统计总数/活跃/过期/撤销"| S5a["⚙️ 按status筛选"]:::service
        S5a -->|"分类统计+等级统计"| S5b["⚙️ ChildBadgeMapper.selectCategoryStats/selectLevelStats"]:::service
        S5b -->|"聚合统计结果"| D4["📦 {total, active, expired, revoked, categoryStats, levelStats}"]:::data

        P2 -->|"家庭内勋章排行"| P2b["🏠 家庭勋章排行页"]:::page
        P2b -->|"familyId"| A6["🔗 POST /api/badges/ranking/family"]:::api
        A6 -->|"familyId"| S6["⚙️ BadgeService.getFamilyRanking()"]:::service
        S6 -->|"按家庭内孩子统计勋章数排序"| S6a["⚙️ ChildBadgeMapper.selectFamilyRanking()"]:::service
        S6a -->|"排行列表(childId, total)"| D5["📦 排行数据（返回前端）"]:::data
    end

    %% ================================================================
    %% 阶段三：管理后台勋章管理
    %% ================================================================
    subgraph 阶段三[阶段三：管理后台勋章管理]
        P3["🏠 管理后台：勋章管理页"]:::page
        P3 -->|"查看所有勋章（含未启用）"| A7["🔗 POST /api/badges/all"]:::api
        A7 -->|"无参数"| S7["⚙️ BadgeService.getAllBadges()"]:::service
        S7 -->|"全部勋章按sortOrder排序"| D1

        P3 -->|"创建勋章"| P3a["🏠 创建表单"]:::page
        P3a -->|"Badge对象"| A8["🔗 POST /api/badges/create"]:::api
        A8 -->|"Badge对象"| S8["⚙️ BadgeService.createBadge()"]:::service
        S8 -->|"设置创建/更新时间"| S8a["⚙️ BadgeMapper.insert()"]:::service
        S8a -->|"新Badge记录"| D1

        P3 -->|"编辑勋章"| P3b["🏠 编辑表单"]:::page
        P3b -->|"Badge对象（含id）"| A9["🔗 POST /api/badges/update"]:::api
        A9 -->|"Badge对象"| S9["⚙️ BadgeService.updateBadge()"]:::service
        S9 -->|"更新字段"| D1

        P3 -->|"删除勋章"| P3c["🏠 删除确认弹窗"]:::page
        P3c -->|"id"| A10["🔗 POST /api/badges/delete"]:::api
        A10 -->|"id"| S10["⚙️ BadgeService.deleteBadge()"]:::service
        S10 -->|"按id删除"| D1

        P3 -->|"手动授予勋章"| P3d["🏠 授勋弹窗：选择孩子"]:::page
        P3d -->|"childId, badgeId"| A11["🔗 POST /api/badges/grant"]:::api
        A11 -->|"childId, badgeId"| S11["⚙️ BadgeService.grantBadge()"]:::service
        S11 -->|"检查是否已授予（去重）"| S11a["⚙️ 查ChildBadgeMapper"]:::service
        S11a -->|"已授予则跳过"| P3d
        S11 -->|"创建ChildBadge记录"| S11b["⚙️ ChildBadgeMapper.insert()"]:::service
        S11b -->|"child_badge记录(初始状态=1)"| D2
    end

    %% ================================================================
    %% 阶段四：微行动
    %% ================================================================
    subgraph 阶段四[阶段四：微行动]
        P4["🏠 小程序：微行动页"]:::page
        P4 -->|"查看所有微行动"| A12["🔗 POST /api/micro-action/list"]:::api
        A12 -->|"无参数"| S12["⚙️ MicroActionService.getAllActions()"]:::service
        S12 -->|"查询status=1, 按sortOrder排序"| S12a["⚙️ MicroActionMapper.selectList()"]:::service
        S12a -->|"MicroAction列表"| D6["📦 micro_actions 表"]:::data

        P4 -->|"获取今日推荐"| P4a["🏠 今日推荐卡片"]:::page
        P4a -->|"childId"| A13["🔗 POST /api/micro-action/today"]:::api
        A13 -->|"userId, childId"| S13["⚙️ MicroActionService.getTodayAction()"]:::service
        S13 -->|"按日期取模随机选择一个行动"| S13a["⚙️ 日期取模算法"]:::service
        S13a -->|"MicroAction/null(当日已完成)"| D6
        S13 -->|"检查当日是否已完成"| S13b["⚙️ MicroActionService.getTodayRecord()"]:::service
        S13b -->|"已有记录返回true"| D7["📦 micro_action_records 表"]:::data
        S13b -->|"completed=true/false"| D8["📦 {action, completed}（返回前端）"]:::data

        P4a -->|"完成微行动"| P4b["🏠 完成按钮"]:::page
        P4b -->|"childId, actionId"| A14["🔗 POST /api/micro-action/complete"]:::api
        A14 -->|"userId, childId, actionId"| S14["⚙️ MicroActionService.completeAction()"]:::service
        S14 -->|"校验: 今日未完成、未健康打卡"| S14a["⚙️ 互斥校验"]:::service
        S14a -->|"校验失败抛出RuntimeException"| P4b
        S14 -->|"验证微行动存在且启用"| S14b["⚙️ MicroActionMapper.selectById()"]:::service
        S14b -->|"MicroAction"| D6
        S14 -->|"创建完成记录"| S14c["⚙️ MicroActionRecordMapper.insert()"]:::service
        S14c -->|"记录(earnedEnergy=1)"| D7
        S14 -->|"自动创建任务+积分+能量"| S14d["⚙️ TaskMapper.insert() + PointsLog + EnergyService.awardEnergy()"]:::service
        S14d -->|"task记录 + points_log记录"| D9["📦 tasks + points_logs 表"]:::data
        S14 -->|"触发新手引导+成长任务"| S14e["⚙️ OnboardingService + GrowthTaskService"]:::service
        S14e -->|"进度更新"| D10["📦 状态更新"]:::data

        P4 -->|"检查今日是否已完成"| P4c["🏠 加载时自动检查"]:::page
        P4c -->|"childId"| A15["🔗 POST /api/micro-action/check-today"]:::api
        A15 -->|"childId"| S15["⚙️ MicroActionService.hasCompletedToday()"]:::service
        S15 -->|"按childId+今日日期查询记录"| D7
        S15 -->|"completed=true/false"| D8
    end

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

端点明细

勋章（用户端）

端点	说明	端口	请求数据	响应数据
`POST /api/badges/list`	获取启用的勋章列表	📱小程序	—	`List<Badge>`（仅isActive=1）
`POST /api/badges/detail`	获取勋章详情	📱小程序	`{id}`	`Badge`（含描述、图标、等级、稀有度等）
`POST /api/badges/favorite`	收藏/取消收藏勋章	📱小程序	`{childId, badgeId}`	`String`
`POST /api/badges/child/list`	获取孩子获得的勋章列表	📱小程序	`{childId}`	`List<{childBadge, badge}>`
`POST /api/badges/statistics/child`	孩子勋章统计	📱小程序	`{childId}`	`{total, active, expired, revoked, categoryStats[], levelStats[]}`
`POST /api/badges/ranking/family`	家庭内勋章排行	📱小程序	`{familyId}`	`List<{childId, total}>`

勋章（管理后台）

端点	说明	端口	请求数据	响应数据
`POST /api/badges/all`	获取全部勋章（含未启用）	🖥管理后台	—	`List<Badge>`
`POST /api/badges/create`	创建勋章	🖥管理后台	`Badge`对象	`String`
`POST /api/badges/update`	更新勋章	🖥管理后台	`Badge`对象（含id）	`String`
`POST /api/badges/delete`	删除勋章	🖥管理后台	`{id}`	`String`
`POST /api/badges/grant`	手动授予勋章	🖥管理后台	`{childId, badgeId}`	`String`

微行动

端点	说明	端口	请求数据	响应数据
`POST /api/micro-action/list`	获取所有微行动列表	📱小程序	—	`List<MicroAction>`
`POST /api/micro-action/today`	获取今日推荐微行动	📱小程序	`{childId}`	`{action, completed}`
`POST /api/micro-action/complete`	完成微行动	📱小程序	`{childId, actionId}`	`MicroActionRecord`
`POST /api/micro-action/check-today`	检查今日是否已完成	📱小程序	`{childId}`	`{completed}`

数据实体关系

erDiagram
    Badge ||--o{ ChildBadge : "一个勋章可授予多个孩子"
    Child ||--o{ ChildBadge : "一个孩子可获多个勋章"
    MicroAction ||--o{ MicroActionRecord : "一个行动有多次完成记录"
    Child ||--o{ MicroActionRecord : "一个孩子可有多次记录"
    User ||--o{ MicroActionRecord : "一个用户可操作多次"

    Badge {
        Long id PK
        string badgeId "逻辑编码"
        string name
        string description
        string icon
        string category "分类"
        string level "等级"
        string rarity "稀有度"
        string triggerType "触发类型"
        int threshold "阈值"
        bool needApproval "需审批"
        int expireDays "有效期天数"
        int sortOrder
        int isActive "1启用 0禁用"
        datetime createdAt
        datetime updatedAt
    }

    ChildBadge {
        Long id PK
        Long childId FK
        Long badgeId FK
        datetime earnedAt "获得时间"
        datetime expireAt "过期时间"
        int status "1活跃 0过期 -1撤销"
        bool isFavorite "是否收藏"
        datetime createdAt
        datetime updatedAt
    }

    MicroAction {
        Long id PK
        string code "DRINK_WATER, DEEP_BREATH"
        string name "喝一杯水"
        string icon
        string description
        int sortOrder
        int status "1启用 0禁用"
        datetime createdAt
    }

    MicroActionRecord {
        Long id PK
        Long userId FK "操作人"
        Long childId FK "执行孩子"
        Long actionId FK
        date completedDate "完成日期"
        int earnedEnergy "获得能量值"
        string note
        datetime createdAt
    }

完整性分析

#	维度	评估	说明
1	流程完整性	✅ 完整	覆盖勋章浏览/收藏、孩子勋章查询/统计/排行、管理后台CRUD/授勋、微行动列表/今日推荐/完成/检查4个阶段
2	异常路径	⚠️ 部分覆盖	微行动与健康打卡互斥逻辑（当日只能选择一种）、行动已下架校验、勋章重复授予跳过在图中体现；勋章自动触发（triggerType/threshold）的自动授勋逻辑未画入（当前仅支持手动授予）
3	端点覆盖	✅ 完整	15个端点全部映射到流程图中，与代码实际暴露的BadgeController（11个）、MicroActionController（4个）一致
4	角色覆盖	✅ 完整	家长和孩子可浏览勋章和微行动；管理员在后管端进行勋章CRUD和手动授勋
5	数据实体	✅ 完整	badge表、child_badge表、micro_actions表、micro_action_records表、tasks表、points_logs表均在图中映射
6	一致性	✅ 与代码一致	所有端点路径与实际Controller中的`@PostMapping`匹配，Service方法名与BadgeService、MicroActionService一致

badge-microaction-flow.md 14 KB Lịch sử Raw

用户使用流程图 — 勋章与微行动

端点明细

勋章（用户端）

勋章（管理后台）

微行动

数据实体关系

完整性分析

badge-microaction-flow.md 14 KB

Lịch sử Raw