HaniBlindBox/.kiro/specs/miniprogram-api-migration/design.md

# Design Document: 小程序 API 迁移

## Overview

本设计文档描述了将 honey_box 小程序的 API 请求从旧的 PHP 后端迁移到新的 .NET 8 后端的技术方案。迁移的核心目标是：

1. 更新环境配置文件中的 API 基础地址
2. 更新需要变更的 API 路径映射
3. 确保请求管理器与新后端的兼容性
4. 保持前端代码的最小改动

## Architecture

### 当前架构

```
┌─────────────────────────────────────────────────────────────┐
│                    honey_box 小程序                          │
├─────────────────────────────────────────────────────────────┤
│  Pages/Components                                            │
│  ├── pages/shouye/index.vue (首页)                          │
│  ├── pages/shouye/detail.vue (一番赏详情)                   │
│  ├── pages/shouye/detail_wuxian.vue (无限赏详情)            │
│  ├── pages/user/login.vue (登录)                            │
│  ├── pages/user/index.vue (用户中心)                        │
│  └── ... (其他页面)                                         │
├─────────────────────────────────────────────────────────────┤
│  Common Layer                                                │
│  ├── common/request.js (RequestManager - 统一请求管理)      │
│  ├── common/env.js (EnvConfig - 环境配置)                   │
│  ├── common/config.js (ConfigManager - 全局配置)            │
│  └── common/server/*.js (API 服务模块)                      │
├─────────────────────────────────────────────────────────────┤
│  HTTP Request (MD5签名 + Token认证)                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    .NET 8 API 后端                           │
│  Base URL: https://youdas.api.zpc-xy.com/api/               │
└─────────────────────────────────────────────────────────────┘
```

### 迁移策略

采用**最小改动原则**，主要修改以下文件：

1. `common/env.js` - 更新 API 基础地址
2. 页面组件中的 API 路径 - 仅更新需要变更的路径

## Components and Interfaces

### 1. 环境配置模块 (env.js)

**修改内容**：更新各环境的 API 基础地址

```javascript
// 开发环境配置
const development = {
  baseUrl: 'https://dev-api.zfunbox.cn',  // 开发环境
  imageUrl: 'https://image.zfunbox.cn',
  // ...
};

// 测试环境配置
const testing = {
  baseUrl: 'https://youdas.api.zpc-xy.com',  // .NET 8 测试环境
  imageUrl: 'https://youdas-1308826010.cos.ap-shanghai.myqcloud.com',
  // ...
};

// 生产环境配置
const production = {
  baseUrl: 'https://api.zfunbox.cn',  // .NET 8 生产环境
  imageUrl: 'https://image.zfunbox.cn',
  // ...
};
```

### 2. 请求管理器 (request.js)

**无需修改**：现有的请求管理器已经支持：
- MD5 签名机制
- Token 认证
- 响应状态码处理
- 错误处理逻辑

### 3. API 路径映射

根据 API 接口文档，以下接口路径需要更新：

| 旧路径 | 新路径 | 使用位置 |
|--------|--------|----------|
| `/goods` | `/goods_list` | pages/shouye/index.vue |
| `/goodsdetail` | `/goods_detail` | pages/shouye/detail.vue |
| `/shang_log` | `/goods_prize_logs` | pages/shouye/detail.vue |
| `/goodslist_count` | `/goods_prize_count` | 相关组件 |
| `/goodslist_content` | `/goods_prize_content` | 相关组件 |

**注意**：根据 API 文档，新后端同时支持旧路径和新路径，因此可以选择：
- 方案A：保持旧路径不变（后端已兼容）
- 方案B：更新为新路径（推荐，更规范）

**推荐方案B**：更新为新路径，保持代码与 API 文档一致。

### 4. API 服务模块

以下服务模块需要检查和更新：

#### 4.1 用户服务 (common/server/user.js)
- `/userInfo` → 保持不变（后端兼容）

#### 4.2 订单服务 (common/server/order.js)
- `/get_order_status` → 保持不变
- `/get_order_list` → 保持不变
- `/create_web_pay_order` → 保持不变
- `/get_order_url_link` → 保持不变

#### 4.3 商城服务 (common/server/mall.js)
- `/get_diamond_list` → 保持不变
- `/createOrderProducts` → 保持不变
- `/get_diamond_order_log` → 保持不变

#### 4.4 地址服务 (common/server/userAddress.js)
- 所有接口保持不变

## Data Models

### 请求数据格式

所有请求保持现有格式：

```javascript
{
  // 业务参数
  ...data,
  // 签名参数
  timestamp: Math.floor(Date.now() / 1000),
  nonce: md5(Date.now() + Math.random().toString(36).substring(2, 15)),
  sign: md5(signStr)
}
```

### 响应数据格式

新后端响应格式与旧后端一致：

```javascript
{
  status: 1,        // 1=成功, 0=失败, -1=未登录, -9=需绑定手机号, 2222=特殊状态
  msg: "success",   // 消息
  data: {},         // 数据
  timestamp: 1640995200  // 时间戳
}
```

## 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: 签名机制一致性
*For any* API 请求，签名算法应产生与旧系统相同的签名结果，确保新后端能正确验证请求。
**Validates: Requirements 3.1**

### Property 2: 响应处理一致性
*For any* API 响应，状态码处理逻辑应与旧系统保持一致，确保用户体验不变。
**Validates: Requirements 3.3, 3.4**

### Property 3: 环境配置完整性
*For any* 环境配置，应包含完整的 baseUrl、imageUrl 等必要字段，确保应用正常运行。
**Validates: Requirements 1.1, 1.2, 1.3, 1.4**

## Error Handling

### 错误处理策略

保持现有的错误处理逻辑：

1. **网络错误**：显示"网络连接异常，请检查网络"
2. **未登录 (status < 0)**：跳转到登录页面
3. **需绑定手机号 (status = -9)**：跳转到绑定页面
4. **业务错误 (status = 0)**：显示错误消息

### 回滚机制

在 `env.js` 中保留旧的配置，便于快速回滚：

```javascript
// 旧的 PHP 后端配置（备份）
const production_php = {
  baseUrl: 'https://api.zfunbox.cn',  // PHP 后端
  // ...
};

// 新的 .NET 8 后端配置
const production = {
  baseUrl: 'https://api.zfunbox.cn',  // .NET 8 后端（同域名）
  // ...
};
```

## Testing Strategy

### 测试方法

由于本次迁移主要是配置更新，采用以下测试策略：

1. **单元测试**：验证签名算法的正确性
2. **集成测试**：验证各 API 接口的请求和响应
3. **手动测试**：验证核心业务流程

### 测试清单

#### 用户认证测试
- [ ] 微信登录
- [ ] 手机号登录
- [ ] 获取用户信息
- [ ] 绑定手机号

#### 商品浏览测试
- [ ] 商品列表加载
- [ ] 一番赏详情
- [ ] 无限赏详情
- [ ] 中奖记录

#### 订单流程测试
- [ ] 计算订单金额
- [ ] 创建订单
- [ ] 支付流程
- [ ] 订单列表

#### 仓库功能测试
- [ ] 仓库列表
- [ ] 回收奖品
- [ ] 申请发货
- [ ] 物流查询

#### 其他功能测试
- [ ] 签到功能
- [ ] 优惠券功能
- [ ] 任务系统
- [ ] 提现功能

### 测试环境

1. **测试环境**：`https://youdas.api.zpc-xy.com`
2. **生产环境**：`https://api.zfunbox.cn`

### 灰度发布策略

1. 先在测试环境验证所有功能
2. 小范围用户测试（5%流量）
3. 逐步扩大（20% → 50% → 100%）
4. 监控错误日志和用户反馈