bindbox-game/docs/standardize_points_ratio/DESIGN_standardize_points_ratio.md

架构设计：统一积分与元比例 (Design)

1. 总体架构

本次改造主要涉及 计算逻辑层的标准化 和 配置数据的动态化，不涉及大规模架构重构。 核心思路：后端收敛计算逻辑，前端收敛展示逻辑。

graph TD
    A[Admin User] -->|配置 ExchangeRate| B(Admin Panel)
    B -->|API: upsertSystemConfig| C(Backend API)
    C -->|Update| D[(MySQL: sys_configs)]
    
    E[App User] -->|Action: Pay/Refund| F(Backend Service)
    F -->|Read Config| D
    F -->|Call| G{pkg/points/convert}
    G -->|Calculate based on Rate| F
    F -->|Save Integer Points| D
    
    H[Mini App] -->|Read Points| F
    H -->|Display Raw Integer| I[UI Display]

2. 模块设计

2.1 后端 (bindbox_game)

• internal/pkg/points: 核心计算包。
  • 职责：提供基于汇率的 Cents <-> Points 转换函数。
  • 变更：
    • CentsToPoints(cents, rate): 逻辑改为 cents * rate / 100。
    • PointsToCents(points, rate): 逻辑改为 points * 100 / rate。
• internal/service/user: 业务服务层。
  • 职责：在积分变动（增加、扣减、退款）时，从 sys_configs 读取最新 points_exchange_rate 并传入计算包。
  • 变更：检查所有调用点，确保不再硬编码。

2.2 数据库 (MySQL)

• Schema: 无变更。
• Data Migration:
  • 需执行数据清洗，将现有的积分数值 x 更新为 x / 100 (假设之前是按分存的)。
  • Risk: 需要用户确认是否执行此 SQL。默认提供 SQL 但不自动运行。

2.3 管理后台 (web/admin)

• SystemConfigs:
  • 新增 "积分配置" Section。
  • Key: points_exchange_rate。
  • 验证：必须为正整数，默认为 1。

2.4 小程序 (bindbox-mini)

• Utils:
  • formatPoints: 移除除以 100 的逻辑，仅保留千分位格式化。
• Pages:
  • 检查积分明细、下单抵扣、商品兑换等页面的展示。
• Vue Filters/Formatters: 全局搜索使用 / 100 展示积分的地方进行替换。

3. 接口规范

• API: POST /admin/system/configs (现有)
  • Payload: { "key": "points_exchange_rate", "value": "1" }

4. 迁移策略

1. 停机维护 (建议): 防止数据在迁移过程中变动。
2. 代码部署: 部署新版后端（新算法）。
3. 数据清洗:

   -- 假设所有用户的积分都需要缩小 100 倍以适配新算法
   UPDATE user_points SET points = FLOOR(points / 100);
   UPDATE user_points_ledger SET points = FLOOR(points / 100);
   

4. 验证: 检查某测试账号积分是否符合预期。