xianyan/docs/superpowers/plans/2026-05-14-gamification-v2.md

养成体系 v2.0 实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 实现EXP独立体系、等级展示、勋章系统、赛季排行榜、每日任务五大养成功能

Architecture: 服务端基于ThinkPHP5(FastAdmin)，新增7张数据库表、2个API控制器、7个管理控制器；客户端基于Flutter，新增排行榜/任务/勋章墙3个功能模块，修改用户中心/签到/成就等现有页面

Tech Stack: PHP(ThinkPHP5/FastAdmin) + MySQL + Flutter(Dart) + Python(测试脚本)

---

Phase 1: EXP独立体系 + 等级展示

Task 1.1: 数据库迁移

Files:

• Create: docs/toolsapi/application/admin/command/Install/migrate_v11.sql

• 创建迁移SQL: tool_user新增exp字段 + tool_user_exp_log表

Task 1.2: 服务端ExpEngine核心

Files:

• Modify: docs/toolsapi/application/common/model/User.php

• User模型新增exp字段类型定义

• 新增nextlevelByExp()方法: floor(exp^0.4/10)+1, 10级封顶

• 新增exp()静态方法: 带事务锁的EXP增减，自动计算level

• 修改score()方法: 积分变动时同时产出EXP

Task 1.3: 服务端UserCenter API

Files:

• Modify: docs/toolsapi/application/api/controller/UserCenter.php

• index()返回新增level/exp/exp_to_next/exp_progress字段

• 新增expLog()方法: EXP变动日志分页查询

• signin()方法: 签到时同时产出EXP(5+continuous*2)

• checkin相关: 打卡时产出EXP(10)

Task 1.4: 客户端数据模型

Files:

• Modify: lib/features/auth/models/user_model.dart

• Modify: lib/features/user_center/models/user_center_models.dart

• UserModel新增level/exp/expToNext/expProgress字段

• UserCenterInfo新增level/exp相关字段

Task 1.5: 客户端等级卡片组件

Files:

• Create: lib/shared/widgets/level_card.dart

• 创建等级卡片组件: 等级数字+称号+EXP进度条+下一级所需

Task 1.6: 客户端页面集成

Files:

• Modify: lib/features/signin/presentation/signin_page.dart

• Modify: lib/features/achievement/presentation/achievement_page.dart

• Modify: lib/features/user_center/presentation/user_center_page.dart

• 签到页: 签到卡片增加等级展示

• 成就页: 概要增加等级信息

• 用户中心: 增加等级卡片

Task 1.7: 上传服务器+测试

• 上传PHP文件到服务器
• 执行数据库迁移
• 编写EXP全流程测试脚本
• 运行测试并验证

---

Phase 2: 勋章系统

Task 2.1: 数据库迁移

Files:

• Modify: docs/toolsapi/application/admin/command/Install/migrate_v11.sql

• 追加tool_badge + tool_user_badge建表SQL

• 追加20个预置勋章INSERT语句

Task 2.2: 服务端BadgeEngine

Files:

• Modify: docs/toolsapi/application/api/controller/Achievement.php

• 新增badges()方法: 获取所有勋章列表(含用户解锁状态)

• 新增badgeDisplay()方法: 设置主页展示勋章(最多3个)

• 新增_checkBadges()方法: 勋章检测逻辑

• claim()方法: 领取成就后触发勋章检测

• signin()后触发勋章检测

Task 2.3: 管理员后台-勋章管理

Files:

• Create: docs/toolsapi/application/admin/controller/Badge.php

• Create: docs/toolsapi/application/admin/model/Badge.php

• Create: docs/toolsapi/application/admin/validate/Badge.php

• Create: docs/toolsapi/application/admin/view/badge/index.html

• Create: docs/toolsapi/application/admin/view/badge/add.html

• Create: docs/toolsapi/application/admin/view/badge/edit.html

• Create: docs/toolsapi/public/assets/js/backend/badge.js

• Create: docs/toolsapi/application/admin/lang/zh-cn/badge.php

• 勋章管理CRUD(列表/添加/编辑/删除)

• 勋章图标/稀有度/条件配置

Task 2.4: 管理员后台-用户勋章

Files:

• Create: docs/toolsapi/application/admin/controller/user/UserBadge.php

• Create: docs/toolsapi/application/admin/model/UserBadge.php

• Create: docs/toolsapi/application/admin/view/user/user_badge/index.html

• Create: docs/toolsapi/public/assets/js/backend/user/user_badge.js

• Create: docs/toolsapi/application/admin/lang/zh-cn/user/user_badge.php

• 用户勋章列表(查看/手动发放/收回)

Task 2.5: 客户端勋章墙

Files:

• Create: lib/features/achievement/presentation/badge_wall_page.dart

• Create: lib/features/achievement/providers/badge_provider.dart

• Create: lib/shared/widgets/badge_icon.dart

• 勋章图标组件(含稀有度边框颜色)

• 勋章墙页面(全部勋章网格+已解锁/未解锁状态)

• 主页展示设置(选择最多3个展示)

Task 2.6: 上传服务器+测试

• 上传PHP文件+执行迁移
• 编写勋章全流程测试脚本
• 运行测试并验证

---

Phase 3: 每日任务

Task 3.1: 数据库迁移

• 追加tool_daily_task + tool_user_task建表SQL
• 追加8个预置任务INSERT语句

Task 3.2: 服务端TaskEngine

Files:

• Create: docs/toolsapi/application/api/controller/Task.php

• today()方法: 获取今日任务列表(含进度)

• reportProgress()方法: 上报任务进度

• claim()方法: 领取任务奖励

• claimPerfect()方法: 领取完美日奖励

• registerCustom()方法: 注册自定义任务

Task 3.3: 管理员后台-任务管理

Files:

• Create: docs/toolsapi/application/admin/controller/DailyTask.php + 配套model/validate/view/js/lang

• Create: docs/toolsapi/application/admin/controller/user/UserTask.php + 配套

• 每日任务CRUD

• 用户任务进度查看

Task 3.4: 客户端每日任务页

Files:

• Create: lib/features/task/presentation/daily_task_page.dart

• Create: lib/features/task/providers/task_provider.dart

• Create: lib/features/task/services/task_service.dart

• Create: lib/shared/widgets/task_card.dart

• 任务卡片组件

• 每日任务页面(任务列表+进度+领取)

• 完美日动画效果

Task 3.5: 上传服务器+测试

• 上传+迁移+测试

---

Phase 4: 赛季排行榜

Task 4.1: 数据库迁移

• 追加tool_rank_season + tool_rank_record建表SQL

Task 4.2: 服务端RankEngine

Files:

• Create: docs/toolsapi/application/api/controller/Rank.php

• seasons()方法: 赛季列表

• leaderboard()方法: 排行榜查询

• myRank()方法: 我的排名

• claimReward()方法: 领取赛季奖励

• 赛季自动创建+结算逻辑

Task 4.3: 管理员后台-赛季管理

Files:

• Create: docs/toolsapi/application/admin/controller/RankSeason.php + 配套

• Create: docs/toolsapi/application/admin/controller/RankRecord.php + 配套

• 赛季CRUD+奖励配置+手动结算

• 排名记录查看+手动发放奖励

Task 4.4: 客户端排行榜页

Files:

• Create: lib/features/rank/presentation/rank_page.dart

• Create: lib/features/rank/providers/rank_provider.dart

• Create: lib/features/rank/services/rank_service.dart

• Create: lib/shared/widgets/rank_item.dart

• 排行榜页面(周赛/月赛Tab + 4种排行类型)

• 排行条目组件(排名+头像+等级+数值)

• 我的排名卡片+奖励领取

Task 4.5: 上传服务器+测试

• 上传+迁移+测试

---

Phase 5: 管理员后台完善

Task 5.1: 用户管理扩展

Files:

• Modify: docs/toolsapi/application/admin/controller/user/User.php

• Modify: docs/toolsapi/application/admin/view/user/user/edit.html

• edit()增加exp字段编辑

• edit.html增加exp输入框+level只读显示

Task 5.2: EXP日志管理

Files:

• Create: docs/toolsapi/application/admin/controller/user/ExpLog.php + 配套

• EXP日志查看(只读列表)

Task 5.3: 菜单权限配置

• fa_auth_rule INSERT: 养成管理一级菜单+7个二级菜单+权限节点

Task 5.4: 上传服务器+验证

• 上传所有管理后台文件
• 执行菜单SQL
• 验证后台功能

---

归档列表

Phase 1: EXP独立体系 + 等级展示

• ✅ Task 1.1: 数据库迁移
• ✅ Task 1.2: 服务端ExpEngine核心
• ✅ Task 1.3: 服务端UserCenter API
• ✅ Task 1.4: 客户端数据模型
• ✅ Task 1.5: 客户端等级卡片组件
• ✅ Task 1.6: 客户端页面集成
• ✅ Task 1.7: 上传服务器+测试(7/7通过)

Phase 2: 勋章系统

• ✅ Task 2.1: 数据库迁移
• ✅ Task 2.2: 服务端BadgeEngine
• ✅ Task 2.3: 管理员后台-勋章管理
• ✅ Task 2.4: 管理员后台-用户勋章
• ✅ Task 2.5: 客户端勋章墙
• ✅ Task 2.6: 上传服务器+测试(7/7通过)

Phase 3: 每日任务

• Task 3.1: 数据库迁移
• Task 3.2: 服务端TaskEngine
• Task 3.3: 管理员后台-任务管理
• Task 3.4: 客户端每日任务页
• Task 3.5: 上传服务器+测试

Phase 4: 赛季排行榜

• Task 4.1: 数据库迁移
• Task 4.2: 服务端RankEngine
• Task 4.3: 管理员后台-赛季管理
• Task 4.4: 客户端排行榜页
• Task 4.5: 上传服务器+测试

Phase 5: 管理员后台完善

• Task 5.1: 用户管理扩展
• Task 5.2: EXP日志管理
• Task 5.3: 菜单权限配置
• Task 5.4: 上传服务器+验证