bindbox-game/docs/standardize_points_ratio/ALIGNMENT_standardize_points_ratio.md

4.0 KiB
Raw Blame History

任务对齐:统一积分与元比例 (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积分
    • 后端配置缺失,且计算公式需要适配 "元" 为单位。

2. 需求确认

  • 目标:
    1. 统一比例: 全局统一为 1 元 = 1 积分 (即 1 积分价值 100 分钱)。
    2. 配置化: 后台可配置 "积分/元 兑换比例" (Rate),当前固定为 1。
    3. 整改范围: 修正后端转换公式,修正前端展示逻辑,添加后台配置界面。
    4. 业务场景: 暂时不涉及"消费送积分" (即订单完成后自动按比例赠送),主要关注积分价值本身(如充值、抵扣、退款等场景的换算)。

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 积分 (即 1 元)。
    • 变更: 现在的 100 (分) 对应 1 元,未来 1 (积分) 对应 1 元。需要明确是否存在历史数据需要迁移(或者是新项目/可重置)。假设目前无存量包袱或接受重置/迁移,或者我们调整代码适配现有数值
    • 风险提示: 如果仅仅改代码不改数据,原来的 100 积分 (1元) 瞬间变成 100 积分 (100元)。必须确认是否需要数据清洗脚本
  2. 兑换比例配置:

    • 配置项: points_exchange_rate (1 元对应多少积分)。
    • 默认值: 1。
    • 公式:
      • 元转积分 (Amount -> Points): points = amount_yuan * rate => points = (cents / 100) * rate
      • 积分转元 (Points -> Amount): cents = (points / rate) * 100

5. 实施方案 (Architecture)

5.1 数据库与配置

  • 配置表 (sys_configs):
    • Key: points_exchange_rate
    • Value: 1 (Default)
    • Description: "积分/元 兑换比例(多少积分=1元)"。

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)
    • PointsToCents(points, rate):
      • Old: points / rate
      • New: (points * 100) / rate
    • RefundPointsAmount: 适配新公式。
  • Service Layer:
    • 确保读取新的配置 Key。
    • 检查所有手动计算积分的地方,全部收敛到 convert 包。

5.3 后台改造 (web/admin)

  • 界面: 在 SystemConfigs (系统配置) -> 新增 "积分配置" 分组。
  • 功能: 编辑 points_exchange_rate

5.4 小程序/前端改造 (bindbox-mini)

  • 展示逻辑:
    • 移除 formatPoints 中的 / 100
    • 直接展示后端返回的整数积分。
    • 检查 "积分抵扣" 等页面,确保传给后端的数值正确。

6. 执行计划 (Task Split)

  1. Design: 确认方案无误 (当前步骤)。
  2. Backend:
    • 修改 Convert 算法。
    • 确保 Config 读取逻辑正确。
    • (Optional) 数据迁移脚本/重置脚本 (如果已有数据)。
  3. Frontend (Admin): 添加配置界面。
  4. Frontend (App): 修正展示逻辑。
  5. Verify: 验证 1 元订单是否对应 1 积分(模拟),或者充值/手动增加 1 积分是否显示为 1。