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
|
||
**状态**: ✅ 完成 |