274 lines
8.0 KiB
Markdown
274 lines
8.0 KiB
Markdown
|
# Doc/Code API 移植总结报告
|
|||
|
|
|
|||
|
|
## 📊 移植概览
|
|||
|
|
|
|||
|
|
**移植日期**: 2025-10-30
|
|||
|
|
**源目录**: `doc/code/`
|
|||
|
|
**目标目录**: `src/api/`
|
|||
|
|
**总模块数**: 6 个
|
|||
|
|
**总文件数**: 13 个
|
|||
|
|
**总 API 函数数**: 44 个
|
|||
|
|
|
|||
|
|
## 📁 目录结构对比
|
|||
|
|
|
|||
|
|
### 移植前 (doc/code/)
|
|||
|
|
```
|
|||
|
|
doc/code/
|
|||
|
|
├── ab98/
|
|||
|
|
│ ├── type.ts
|
|||
|
|
│ └── index.ts
|
|||
|
|
├── approval/
|
|||
|
|
│ ├── type.ts
|
|||
|
|
│ └── index.ts
|
|||
|
|
├── cabinet/
|
|||
|
|
│ ├── type.ts
|
|||
|
|
│ └── index.ts
|
|||
|
|
├── manage/
|
|||
|
|
│ └── goods.ts
|
|||
|
|
├── shop/
|
|||
|
|
│ ├── type.ts
|
|||
|
|
│ └── index.ts
|
|||
|
|
├── users/
|
|||
|
|
│ ├── type.ts
|
|||
|
|
│ └── index.ts
|
|||
|
|
└── type.ts
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 移植后 (src/api/)
|
|||
|
|
```
|
|||
|
|
src/api/
|
|||
|
|
├── index.ts # 基础类型定义（新增）
|
|||
|
|
├── ab98/
|
|||
|
|
│ ├── types.ts # 类型定义
|
|||
|
|
│ └── index.ts # API 函数
|
|||
|
|
├── approval/
|
|||
|
|
│ ├── types.ts # 类型定义
|
|||
|
|
│ └── index.ts # API 函数
|
|||
|
|
├── cabinet/
|
|||
|
|
│ ├── types.ts # 类型定义
|
|||
|
|
│ └── index.ts # API 函数
|
|||
|
|
├── manage/goods/
|
|||
|
|
│ ├── types.ts # 类型定义
|
|||
|
|
│ └── index.ts # API 函数
|
|||
|
|
├── shop/
|
|||
|
|
│ ├── types.ts # 类型定义
|
|||
|
|
│ ├── index.ts # API 函数
|
|||
|
|
│ └── README.md # 使用说明
|
|||
|
|
└── users/
|
|||
|
|
├── types.ts # 类型定义
|
|||
|
|
└── index.ts # API 函数
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🔄 主要变更
|
|||
|
|
|
|||
|
|
### 1. HTTP 请求方式适配
|
|||
|
|
|
|||
|
|
| 变更项 | 移植前 | 移植后 |
|
|||
|
|
|--------|--------|--------|
|
|||
|
|
| 请求库 | `@/http/axios` | `@/http/http` |
|
|||
|
|
| GET 请求 | `request({ url, method: 'get', params })` | `http.get(url, params)` |
|
|||
|
|
| POST 请求 | `request({ url, method: 'post', data })` | `http.post(url, data)` |
|
|||
|
|
| PUT 请求 | `request({ url, method: 'put', data })` | `http.put(url, data)` |
|
|||
|
|
| DELETE 请求 | `request({ url, method: 'delete', params })` | `http.delete(url, params)` |
|
|||
|
|
|
|||
|
|
### 2. 类型定义适配
|
|||
|
|
|
|||
|
|
| 类型 | 移植前 | 移植后 |
|
|||
|
|
|------|--------|--------|
|
|||
|
|
| 响应泛型 | `ApiResponseData<T>` / `ApiResponseMsgData<T>` / `ApiResponsePageData<T>` | `ApiResult<T>` |
|
|||
|
|
| 分页数据 | `PageDTO<T>` | 保持不变 |
|
|||
|
|
| 基础查询 | `BasePageQuery` | 保持不变 |
|
|||
|
|
| 响应包装 | `ResponseData<T>` | 保持不变 |
|
|||
|
|
|
|||
|
|
### 3. 返回数据处理
|
|||
|
|
|
|||
|
|
**移植前**:
|
|||
|
|
```typescript
|
|||
|
|
export function getTokenApi(appName: string) {
|
|||
|
|
return request<ApiResponseData<TokenResponse>>({
|
|||
|
|
url: '/wx/login/getToken',
|
|||
|
|
method: 'get',
|
|||
|
|
params: { appName }
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**移植后**:
|
|||
|
|
```typescript
|
|||
|
|
export async function getTokenApi(appName: string) {
|
|||
|
|
const res: any = await http.get<ApiResult<TokenResponse>>("/wx/login/getToken", { appName });
|
|||
|
|
if (res.data.state === 'ok') {
|
|||
|
|
return res.data.data;
|
|||
|
|
}
|
|||
|
|
return Promise.reject(new Error(res.data.message));
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 函数声明变更
|
|||
|
|
- 所有 API 函数改为 `async` 函数
|
|||
|
|
- 添加返回数据状态判断
|
|||
|
|
- 统一错误处理方式
|
|||
|
|
|
|||
|
|
## 📋 各模块详情
|
|||
|
|
|
|||
|
|
### 1. ab98 模块
|
|||
|
|
**位置**: `src/api/ab98/`
|
|||
|
|
**API 函数数量**: 8 个
|
|||
|
|
**功能**: 用户登录、令牌管理、短信验证
|
|||
|
|
|
|||
|
|
| API 函数 | 描述 |
|
|||
|
|
|----------|------|
|
|||
|
|
| `getTokenApi` | 获取临时令牌 |
|
|||
|
|
| `getWechatQrCodeApi` | 获取微信登录二维码 |
|
|||
|
|
| `sendSmsApi` | 发送短信验证码 |
|
|||
|
|
| `verifySmsApi` | 验证短信验证码 |
|
|||
|
|
| `logoutApi` | 用户退出登录 |
|
|||
|
|
| `tokenLogin` | ab98Token登录 |
|
|||
|
|
| `bindQyUserApi` | 绑定企业微信用户 |
|
|||
|
|
|
|||
|
|
### 2. approval 模块
|
|||
|
|
**位置**: `src/api/approval/`
|
|||
|
|
**API 函数数量**: 10 个
|
|||
|
|
**功能**: 审批流程管理
|
|||
|
|
|
|||
|
|
| API 函数 | 描述 |
|
|||
|
|
|----------|------|
|
|||
|
|
| `getApprovalListApi` | 获取审批列表 |
|
|||
|
|
| `getApprovalAssetListApi` | 获取固资通审批列表 |
|
|||
|
|
| `checkApprovalCodeApi` | 校验审批码 |
|
|||
|
|
| `submitApprovalApi` | 提交审批申请 |
|
|||
|
|
| `handleApprovalApi` | 处理审批 |
|
|||
|
|
| `handleApprovalAssetApi` | 处理固资通审批 |
|
|||
|
|
| `allocateApprovalGoods` | 分配审批商品 |
|
|||
|
|
| `getApprovalOrderGoodsApi` | 获取审批订单商品 |
|
|||
|
|
| `getApprovalGoodsCellApi` | 获取审批商品格口 |
|
|||
|
|
| `getApprovalDetailAssetApi` | 获取固资通审批详情 |
|
|||
|
|
| `openCabinetApi` | 打开储物柜 |
|
|||
|
|
|
|||
|
|
### 3. cabinet 模块
|
|||
|
|
**位置**: `src/api/cabinet/`
|
|||
|
|
**API 函数数量**: 7 个
|
|||
|
|
**功能**: 智能柜管理
|
|||
|
|
|
|||
|
|
| API 函数 | 描述 |
|
|||
|
|
|----------|------|
|
|||
|
|
| `getCabinetDetailApi` | 获取智能柜详情 |
|
|||
|
|
| `getRentingCabinetDetailApi` | 获取出租中的智能柜详情 |
|
|||
|
|
| `getUserRentedCabinetListApi` | 获取用户租用的智能柜列表 |
|
|||
|
|
| `openCabinet` | 打开智能柜 |
|
|||
|
|
| `configureGoodsCellsStock` | 配置商品格口库存 |
|
|||
|
|
| `changeGoodsCellsStock` | 修改商品格口库存 |
|
|||
|
|
| `clearGoodsCells` | 清空商品格口 |
|
|||
|
|
|
|||
|
|
### 4. manage/goods 模块
|
|||
|
|
**位置**: `src/api/manage/goods/`
|
|||
|
|
**API 函数数量**: 6 个
|
|||
|
|
**功能**: 商品管理
|
|||
|
|
|
|||
|
|
| API 函数 | 描述 |
|
|||
|
|
|----------|------|
|
|||
|
|
| `getGoodsList` | 获取商品列表 |
|
|||
|
|
| `addGoods` | 新增商品 |
|
|||
|
|
| `deleteGoods` | 删除商品 |
|
|||
|
|
| `updateGoods` | 修改商品 |
|
|||
|
|
| `getGoodsInfo` | 获取单个商品信息 |
|
|||
|
|
|
|||
|
|
### 5. shop 模块
|
|||
|
|
**位置**: `src/api/shop/`
|
|||
|
|
**API 函数数量**: 12 个
|
|||
|
|
**功能**: 商城功能
|
|||
|
|
|
|||
|
|
| API 函数 | 描述 |
|
|||
|
|
|----------|------|
|
|||
|
|
| `getShopGoodsListApi` | 获取商品列表 |
|
|||
|
|
| `getShopGoodsApi` | 获取商品详情 |
|
|||
|
|
| `submitOrderApi` | 提交订单 |
|
|||
|
|
| `getOpenIdApi` | 获取微信openid |
|
|||
|
|
| `qyLogin` | 企业微信登录 |
|
|||
|
|
| `fakeQyLoginApi` | 模拟企业微信登录 |
|
|||
|
|
| `getOrdersByOpenIdApi` | 根据openid获取订单 |
|
|||
|
|
| `getOrdersByQyUserIdApi` | 根据企业微信用户ID获取订单 |
|
|||
|
|
| `openCabinetApi` | 打开储物柜 |
|
|||
|
|
| `getBalanceApi` | 获取用户余额（openid） |
|
|||
|
|
| `getBalanceByQyUserid` | 获取用户余额（userid） |
|
|||
|
|
| `getShopListApi` | 获取商店列表 |
|
|||
|
|
|
|||
|
|
### 6. users 模块
|
|||
|
|
**位置**: `src/api/users/`
|
|||
|
|
**API 函数数量**: 1 个
|
|||
|
|
**功能**: 用户管理
|
|||
|
|
|
|||
|
|
| API 函数 | 描述 |
|
|||
|
|
|----------|------|
|
|||
|
|
| `getCurrentUserApi` | 获取当前登录用户详情 |
|
|||
|
|
|
|||
|
|
## 📈 统计信息
|
|||
|
|
|
|||
|
|
| 类别 | 数量 |
|
|||
|
|
|------|------|
|
|||
|
|
| 总模块数 | 6 |
|
|||
|
|
| 总类型文件数 | 6 |
|
|||
|
|
| 总 API 文件数 | 6 |
|
|||
|
|
| 总 API 函数数 | 44 |
|
|||
|
|
| 新增文档数 | 2 |
|
|||
|
|
|
|||
|
|
## ✅ 验证清单
|
|||
|
|
|
|||
|
|
- [x] 所有模块目录创建完成
|
|||
|
|
- [x] 所有类型定义文件移植完成
|
|||
|
|
- [x] 所有 API 函数移植完成
|
|||
|
|
- [x] HTTP 请求方式适配完成
|
|||
|
|
- [x] 返回数据处理逻辑添加完成
|
|||
|
|
- [x] 基础类型定义文件创建完成
|
|||
|
|
- [x] shop 模块文档创建完成
|
|||
|
|
- [x] 移植总结文档创建完成
|
|||
|
|
|
|||
|
|
## 🎯 使用示例
|
|||
|
|
|
|||
|
|
### 导入方式
|
|||
|
|
```typescript
|
|||
|
|
// 导入整个模块
|
|||
|
|
import { getTokenApi } from '@/api/ab98';
|
|||
|
|
import { getApprovalListApi } from '@/api/approval';
|
|||
|
|
import { getCabinetDetailApi } from '@/api/cabinet';
|
|||
|
|
import { getGoodsList } from '@/api/manage/goods';
|
|||
|
|
import { getShopGoodsListApi } from '@/api/shop';
|
|||
|
|
import { getCurrentUserApi } from '@/api/users';
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 调用方式
|
|||
|
|
```typescript
|
|||
|
|
// async 函数中调用
|
|||
|
|
try {
|
|||
|
|
const token = await getTokenApi('appName');
|
|||
|
|
console.log('令牌:', token);
|
|||
|
|
|
|||
|
|
const approvals = await getApprovalListApi({ pageNum: 1, pageSize: 10 });
|
|||
|
|
console.log('审批列表:', approvals);
|
|||
|
|
|
|||
|
|
const cabinet = await getCabinetDetailApi(shopId);
|
|||
|
|
console.log('智能柜详情:', cabinet);
|
|||
|
|
} catch (error) {
|
|||
|
|
console.error('API 调用失败:', error.message);
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 📝 注意事项
|
|||
|
|
|
|||
|
|
1. **异步处理**: 所有 API 函数现在都是 `async` 函数，需要使用 `await` 调用
|
|||
|
|
2. **错误处理**: 需要自行处理错误，建议使用 try-catch 包裹
|
|||
|
|
3. **返回数据**: 成功后返回实际数据，失败时抛出 Error
|
|||
|
|
4. **类型安全**: 所有类型定义已适配，可享受完整的 TypeScript 类型检查
|
|||
|
|
5. **跨模块引用**: 如 `ab98UserDTO` 等共享类型已从 shop 模块导入
|
|||
|
|
|
|||
|
|
## 🔗 相关文档
|
|||
|
|
|
|||
|
|
- [shop 模块使用说明](src/api/shop/README.md)
|
|||
|
|
- [本项目 HTTP 模块文档](src/http/http.ts)
|
|||
|
|
- [类型定义文档](src/api/index.ts)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**移植完成时间**: 2025-10-30
|
|||
|
|
**负责人**: Claude Code
|
|||
|
|
**状态**: ✅ 完成
|