# Design Document

## Overview

本设计文档描述前端 API 接口调用重构的技术方案。核心目标是将分散在页面和组件中的接口调用统一收敛到 `common/server/` 模块，实现接口集中管理、统一错误处理，并在改造过程中生成完整的 API 清单用于核对 C# 后端迁移完整性。

## Architecture

### 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                      Pages / Components                      │
│  (pages/shouye/*.vue, pages/user/*.vue, components/*.vue)   │
└─────────────────────────────┬───────────────────────────────┘
                              │ import { funcName } from '@/common/server/xxx.js'
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Server Modules                           │
│  common/server/                                              │
│  ├── auth.js      (登录、注册、绑定)                          │
│  ├── user.js      (用户信息、VIP)                            │
│  ├── goods.js     (商品列表、详情、奖品)                      │
│  ├── order.js     (订单、抽奖)                               │
│  ├── warehouse.js (仓库、回收、发货)                          │
│  ├── coupon.js    (优惠券)                                   │
│  ├── welfare.js   (福利屋、签到、任务)                        │
│  ├── collection.js(收藏)                                     │
│  ├── address.js   (收货地址) - 已有 userAddress.js           │
│  ├── config.js    (系统配置) - 已有                          │
│  ├── rank.js      (排行榜)                                   │
│  ├── invitation.js(邀请)                                     │
│  ├── redeem.js    (兑换码)                                   │
│  └── pay.js       (支付)                                     │
└─────────────────────────────┬───────────────────────────────┘
                              │ RequestManager.get/post()
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     RequestManager                           │
│  common/request.js                                           │
│  - 统一请求封装                                               │
│  - 签名机制                                                   │
│  - 错误处理                                                   │
│  - Content-Type: application/json                            │
└─────────────────────────────┬───────────────────────────────┘
                              │ HTTP Request
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     C# Backend API                           │
│  http://localhost:5238/api/*                                 │
└─────────────────────────────────────────────────────────────┘
```

### 调用流程

```mermaid
sequenceDiagram
    participant P as Page/Component
    participant S as Server Module
    participant R as RequestManager
    participant B as Backend API

    P->>S: import { getGoodsList } from '@/common/server/goods.js'
    P->>S: await getGoodsList({ page: 1, type: 0 })
    S->>R: RequestManager.post('/goods_list', data)
    R->>R: 添加签名参数 (timestamp, nonce, sign)
    R->>B: POST /api/goods_list (JSON)
    B-->>R: { status: 1, data: {...} }
    R-->>S: response
    S->>S: 统一错误处理
    S-->>P: 标准格式结果
```

## Components and Interfaces

### 1. RequestManager (已有，需修改)

**文件**: `honey_box/common/request.js`

**修改内容**: POST 请求 Content-Type 改为 `application/json`

```javascript
// 修改前
if (method.toUpperCase() == 'POST') {
    header = {
        'content-type': 'application/x-www-form-urlencoded',
        // ...
    }
}

// 修改后
if (method.toUpperCase() == 'POST') {
    header = {
        'content-type': 'application/json',
        // ...
    }
}
```

**接口保持不变**:
- `static get(url, data, showLoading)` - GET 请求
- `static post(url, data, showLoading)` - POST 请求
- `static getCache(url, data, showLoading)` - 带缓存的 GET 请求

### 2. Server Module 标准结构

每个 Server Module 遵循统一的结构：

```javascript
// common/server/xxx.js
import RequestManager from '../request';

/**
 * 函数名使用语义化命名
 * @param {Object} params 请求参数
 * @returns {Promise<Object>} 标准响应格式
 */
export const getFunctionName = async (params = {}) => {
    const res = await RequestManager.post('/api_endpoint', params);
    return res;
};

// 如需数据处理
export const getProcessedData = async (params = {}) => {
    const res = await RequestManager.post('/api_endpoint', params);
    if (res.status === 1 && res.data) {
        // 数据处理逻辑
        return res.data;
    }
    return null;
};
```

### 3. Server Modules 详细设计

#### 3.1 auth.js (认证模块)

```javascript
// 微信登录
export const wxLogin = async (code, userInfo) => {...}

// 手机号登录
export const mobileLogin = async (mobile, code) => {...}

// 微信绑定手机号
export const bindMobileByWx = async (encryptedData, iv) => {...}

// 验证码绑定手机号
export const bindMobileByCode = async (mobile, code) => {...}

// 记录登录
export const recordLogin = async () => {...}

// 账号注销
export const logOff = async () => {...}
```

#### 3.2 user.js (用户模块 - 扩展已有)

```javascript
// 已有
export const getUserInfo = async () => {...}

// 新增
export const updateUserInfo = async (data) => {...}
export const getVipList = async () => {...}
export const getProfitMoney = async (page) => {...}
export const getProfitIntegral = async (page) => {...}
export const getProfitScore = async (page) => {...}
export const getProfitPay = async (page) => {...}
```

#### 3.3 goods.js (商品模块)

```javascript
// 商品列表
export const getGoodsList = async (params) => {...}

// 商品详情
export const getGoodsDetail = async (goodsId) => {...}

// 子奖品列表
export const getGoodsChildren = async (goodsId) => {...}

// 商品扩展配置
export const getGoodsExtend = async (goodsId) => {...}

// 箱号列表
export const getGoodsNumList = async (goodsId) => {...}

// 箱号详情
export const getGoodsNumDetail = async (goodsId, goodsNum) => {...}

// 奖品数量统计
export const getGoodsPrizeCount = async (goodsId) => {...}

// 奖品内容
export const getGoodsPrizeContent = async (goodsId, shangId) => {...}

// 中奖记录
export const getGoodsPrizeLogs = async (params) => {...}
```

#### 3.4 order.js (订单模块 - 扩展已有)

```javascript
// 一番赏金额计算
export const calcOrderMoney = async (params) => {...}

// 一番赏下单
export const createOrder = async (params) => {...}

// 无限赏金额计算
export const calcInfiniteOrderMoney = async (params) => {...}

// 无限赏下单
export const createInfiniteOrder = async (params) => {...}

// 商城金额计算
export const calcMallOrderMoney = async (params) => {...}

// 订单列表
export const getOrderList = async (page, pageSize) => {...}

// 订单详情
export const getOrderDetail = async (orderId) => {...}

// 抽奖结果
export const getPrizeOrderLog = async (orderId) => {...}

// 无限赏抽奖结果
export const getInfinitePrizeOrderLog = async (orderId) => {...}

// 道具卡抽奖
export const useItemCard = async (params) => {...}
```

#### 3.5 warehouse.js (仓库模块)

```javascript
// 仓库首页
export const getWarehouseIndex = async (params) => {...}

// 回收奖品
export const recoveryPrize = async (ids) => {...}

// 发货奖品
export const sendPrize = async (params) => {...}

// 确认发货
export const confirmSend = async (params) => {...}

// 发货记录
export const getSendRecord = async (page) => {...}

// 发货详情
export const getSendRecordDetail = async (id) => {...}

// 回收记录
export const getRecoveryRecord = async (page) => {...}

// 物流信息
export const getLogistics = async (orderId) => {...}
```

#### 3.6 coupon.js (优惠券模块)

```javascript
// 优惠券列表
export const getCouponList = async (params) => {...}

// 优惠券详情
export const getCouponDetail = async (couponId) => {...}

// 领取优惠券
export const receiveCoupon = async (couponId) => {...}

// 分享优惠券
export const shareCoupon = async (couponId) => {...}

// 合成优惠券
export const synthesisCoupon = async (ids) => {...}

// 计算合成
export const calcSynthesis = async (ids) => {...}
```

#### 3.7 welfare.js (福利模块)

```javascript
// 福利屋列表
export const getWelfareHouseList = async () => {...}

// 福利屋详情
export const getWelfareHouseDetail = async (goodsId) => {...}

// 福利屋下单
export const buyWelfareHouse = async (params) => {...}

// 签到信息
export const getSignInfo = async () => {...}

// 执行签到
export const doSign = async () => {...}

// 任务列表
export const getTaskList = async () => {...}

// 领取任务奖励
export const receiveTaskReward = async (taskId) => {...}
```

#### 3.8 collection.js (收藏模块)

```javascript
// 收藏列表
export const getCollectionList = async (page) => {...}

// 添加收藏
export const addCollection = async (goodsId) => {...}

// 取消收藏
export const cancelCollection = async (goodsId) => {...}

// 收藏状态
export const getCollectionStatus = async (goodsId) => {...}
```

#### 3.9 rank.js (排行榜模块)

```javascript
// 排行榜列表
export const getRankList = async (type, page) => {...}
```

#### 3.10 invitation.js (邀请模块)

```javascript
// 邀请信息
export const getInvitationInfo = async () => {...}

// 邀请记录
export const getInvitationRecord = async (page) => {...}
```

#### 3.11 redeem.js (兑换码模块)

```javascript
// 使用兑换码
export const useRedeemCode = async (code) => {...}
```

#### 3.12 pay.js (支付模块)

```javascript
// 微信支付
export const wxPay = async (orderId) => {...}

// 余额支付
export const balancePay = async (orderId) => {...}

// 充值
export const recharge = async (amount) => {...}
```

## Data Models

### 标准响应格式

```typescript
interface ApiResponse<T> {
    status: number;      // 1=成功, 0=失败, -1=未登录, -9=需绑定手机号
    msg: string;         // 提示信息
    data: T;             // 业务数据
}

interface PaginatedResponse<T> {
    status: number;
    msg: string;
    data: {
        data: T[];       // 列表数据
        total: number;   // 总数
        currentPage: number;
        lastPage: number;
    };
}
```

### 状态码定义

| 状态码 | 含义 | 处理方式 |
|-------|------|---------|
| 1 | 成功 | 返回数据 |
| 0 | 业务失败 | 显示 msg 提示 |
| -1 | 未登录 | 跳转登录页 |
| -9 | 需绑定手机号 | 跳转绑定页 |
| 2222 | 特殊状态 | 返回数据 |

## Correctness Properties

*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*

### Property 1: POST 请求使用 JSON 格式

*For any* POST 请求通过 RequestManager 发送, 请求头的 Content-Type 应为 `application/json`

**Validates: Requirements 1.1**

### Property 2: 签名机制一致性

*For any* 请求数据对象, 生成的签名应与原有算法保持一致：参数按键名排序 → 拼接为 key=value& 格式 → 添加密钥(host+timestamp) → MD5 加密

**Validates: Requirements 1.2**

### Property 3: 响应格式一致性

*For any* API 响应, 返回格式应包含 status、msg、data 三个字段，且 status 为数字类型

**Validates: Requirements 1.3**

### Property 4: 错误处理统一性

*For any* 接口调用返回 status !== 1 的响应, Server Module 应返回包含 status 和 msg 的标准格式对象

**Validates: Requirements 2.3, 6.2**

## Error Handling

### RequestManager 层错误处理

RequestManager 已实现以下错误处理逻辑（保持不变）：

1. **网络异常**: 显示 "网络连接异常，请检查网络"
2. **status = 0**: 显示 msg 提示
3. **status = -1**: 清除 token，跳转登录页
4. **status = -9**: 显示 msg，跳转绑定手机号页面
5. **请求失败**: 显示错误信息

### Server Module 层错误处理

Server Module 不额外处理错误，直接返回 RequestManager 的响应：

```javascript
export const getGoodsList = async (params) => {
    // 直接返回，错误由 RequestManager 统一处理
    return await RequestManager.post('/goods_list', params);
};
```

如需数据转换，在成功时处理：

```javascript
export const getUserInfo = async () => {
    const res = await RequestManager.post('/user');
    if (res.status === 1 && res.data) {
        // 数据处理
        res.data.money = common.removeTrailingZeros(res.data.money);
        return res.data;
    }
    return null;
};
```

## Testing Strategy

### 单元测试

由于前端 UniApp 项目的特殊性，主要通过以下方式验证：

1. **手动测试**: 在开发环境使用 eruda 调试工具检查请求
2. **接口测试**: 使用 Postman/curl 验证接口响应格式

### 测试用例

| 测试项 | 预期结果 |
|-------|---------|
| POST 请求 Content-Type | application/json |
| 签名参数存在 | timestamp, nonce, sign |
| 成功响应格式 | { status: 1, msg: "...", data: {...} } |
| 错误响应处理 | 显示 msg 提示 |
| 未登录处理 | 跳转登录页 |
| 需绑定手机号处理 | 跳转绑定页 |

### 集成测试清单

按模块逐一测试：

1. **认证模块**: 登录、绑定手机号
2. **用户模块**: 获取用户信息、VIP 信息
3. **商品模块**: 商品列表、详情、奖品
4. **订单模块**: 下单、支付、抽奖结果
5. **仓库模块**: 回收、发货
6. **优惠券模块**: 列表、领取、合成
7. **福利模块**: 签到、任务
8. **其他模块**: 收藏、排行榜、邀请、兑换码