outsource/HaniBlindBox

Fork 0

zpc c282854736 调整

2026-01-03 14:47:28 +08:00

8.6 KiB

Raw Blame History

Design Document: 小程序 API 迁移

Overview

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

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

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/               │
└─────────────────────────────────────────────────────────────┘

迁移策略

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

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

Components and Interfaces

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

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

// 开发环境配置
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

请求数据格式

所有请求保持现有格式：

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

响应数据格式

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

{
  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

错误处理策略

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

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

回滚机制

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

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

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

Testing Strategy

测试方法

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

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

测试清单

用户认证测试

微信登录
手机号登录
获取用户信息
绑定手机号

商品浏览测试

商品列表加载
一番赏详情
无限赏详情
中奖记录

订单流程测试

计算订单金额
创建订单
支付流程
订单列表

仓库功能测试

仓库列表
回收奖品
申请发货
物流查询

其他功能测试

签到功能
优惠券功能
任务系统
提现功能

测试环境

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

灰度发布策略

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

8.6 KiB Raw Blame History Unescape Escape