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

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

```mermaid
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. **数据清洗**: 
    ```sql
    -- 假设所有用户的积分都需要缩小 100 倍以适配新算法
    UPDATE user_points SET points = FLOOR(points / 100);
    UPDATE user_points_ledger SET points = FLOOR(points / 100);
    ```
4. **验证**: 检查某测试账号积分是否符合预期。