4.0 KiB
4.0 KiB
任务对齐:统一积分与元比例 (Standardize Points and Yuan Ratio)
1. 项目上下文分析
- 项目结构:
- 后端:
bindbox_game(Go) - 管理后台:
bindbox_game/web/admin(Vue 3) - 小程序:
bindbox-mini(UniApp / Vue)
- 后端:
- 核心问题:
- 当前代码逻辑隐含 "1积分 = 1分钱" (100积分=1元),前端通过
/100强行展示为 "1.00",导致逻辑割裂。 - 用户期望标准: 1元 = 1积分。
- 后端配置缺失,且计算公式需要适配 "元" 为单位。
- 当前代码逻辑隐含 "1积分 = 1分钱" (100积分=1元),前端通过
2. 需求确认
- 目标:
- 统一比例: 全局统一为 1 元 = 1 积分 (即 1 积分价值 100 分钱)。
- 配置化: 后台可配置 "积分/元 兑换比例" (Rate),当前固定为 1。
- 整改范围: 修正后端转换公式,修正前端展示逻辑,添加后台配置界面。
- 业务场景: 暂时不涉及"消费送积分" (即订单完成后自动按比例赠送),主要关注积分价值本身(如充值、抵扣、退款等场景的换算)。
3. 现状分析 (As-Is)
- 后端 (
bindbox_game):CentsToPoints: 依赖points_exchange_per_cent(分换积分比例),默认为 1。即 1 分钱 = 1 积分单位。RefundPointsAmount: 存在硬编码/ 100,逻辑存疑。
- 小程序 (
bindbox-mini):formatPoints:value / 100。- 如果后端给 100 积分单位,前端展示为 "1.0"。
- 含义模糊:是“1积分”还是“1.0元价值”?
- 后台 (
web/admin):- 缺少积分比例配置界面。
4. 关键决策点 (Resolved)
-
积分定义:
- 确认采用 1 积分 = 1 元 的价值锚点。
- 数据库存储: 存
1代表 1 积分 (即 1 元)。 - 变更: 现在的
100(分) 对应 1 元,未来1(积分) 对应 1 元。需要明确是否存在历史数据需要迁移(或者是新项目/可重置)。假设目前无存量包袱或接受重置/迁移,或者我们调整代码适配现有数值。 - 风险提示: 如果仅仅改代码不改数据,原来的 100 积分 (1元) 瞬间变成 100 积分 (100元)。必须确认是否需要数据清洗脚本。
-
兑换比例配置:
- 配置项:
points_exchange_rate(1 元对应多少积分)。 - 默认值: 1。
- 公式:
- 元转积分 (Amount -> Points):
points = amount_yuan * rate=>points = (cents / 100) * rate - 积分转元 (Points -> Amount):
cents = (points / rate) * 100
- 元转积分 (Amount -> Points):
- 配置项:
5. 实施方案 (Architecture)
5.1 数据库与配置
- 配置表 (
sys_configs):- Key:
points_exchange_rate - Value:
1(Default) - Description: "积分/元 兑换比例(多少积分=1元)"。
- Key:
5.2 后端改造 (bindbox_game)
internal/pkg/points/convert.go:CentsToPoints(cents, rate):- Old:
cents * rate(Assumed rate per cent) - New:
(cents * rate) / 100(Rate per Yuan)
- Old:
PointsToCents(points, rate):- Old:
points / rate - New:
(points * 100) / rate
- Old:
RefundPointsAmount: 适配新公式。
- Service Layer:
- 确保读取新的配置 Key。
- 检查所有手动计算积分的地方,全部收敛到
convert包。
5.3 后台改造 (web/admin)
- 界面: 在
SystemConfigs(系统配置) -> 新增 "积分配置" 分组。 - 功能: 编辑
points_exchange_rate。
5.4 小程序/前端改造 (bindbox-mini)
- 展示逻辑:
- 移除
formatPoints中的/ 100。 - 直接展示后端返回的整数积分。
- 检查 "积分抵扣" 等页面,确保传给后端的数值正确。
- 移除
6. 执行计划 (Task Split)
- Design: 确认方案无误 (当前步骤)。
- Backend:
- 修改 Convert 算法。
- 确保 Config 读取逻辑正确。
- (Optional) 数据迁移脚本/重置脚本 (如果已有数据)。
- Frontend (Admin): 添加配置界面。
- Frontend (App): 修正展示逻辑。
- Verify: 验证 1 元订单是否对应 1 积分(模拟),或者充值/手动增加 1 积分是否显示为 1。