shop-web/doc/API接口文档.md

# API 接口文档

## 概述

本文档详细描述了 MobVue 项目的 API 接口规范和使用方法。

## 基础配置

### 请求配置
- **基础 URL**: 通过环境变量 `VITE_BASE_URL` 配置
- **超时时间**: 10 秒
- **Content-Type**: `application/json`

### 响应格式
```typescript
interface ApiResponse<T> {
  code: number;      // 业务状态码
  data: T;          // 响应数据
  msg?: string;     // 响应消息
  message?: string; // 响应消息（兼容字段）
}
```

### 状态码说明
- `0`: 成功
- `401`: 登录过期
- `403`: 拒绝访问
- `500`: 服务器内部错误

## 用户认证模块

### 微信登录

#### 获取 OpenID
```typescript
// 接口: GET /api/v1/wx/getOpenId
interface GetOpenIdParams {
  code: string;
}

interface GetOpenIdResponse {
  openid: string;
}
```

#### 企业微信登录
```typescript
// 接口: POST /api/v1/wx/qyLogin
interface QyLoginParams {
  corpid: string;
  code: string;
  state?: string;
}

interface QyLoginResponse {
  userid: string;
  openid: string;
  isCabinetAdmin: number;
  name: string;
  qyUserId: number;
  ab98User: Ab98UserDTO;
}
```

### AB98 用户系统

#### Token 登录
```typescript
// 接口: POST /api/v1/ab98/tokenLogin
interface TokenLoginParams {
  token: string;
  userid: string;
  openid: string;
}

interface LoginData {
  face_img: string;
  success: boolean;
  sex: string;
  name: string;
  userid: string;
  registered: boolean;
  tel: string;
}
```

## 商品模块

### 商品列表
```typescript
// 接口: GET /api/v1/product/list
interface ProductListResponse {
  products: Product[];
  total: number;
}

interface Product {
  id: number;
  name: string;
  price: number;
  image: string;
  description: string;
  stock: number;
}
```

### 商品详情
```typescript
// 接口: GET /api/v1/product/{id}
interface ProductDetailResponse extends Product {
  specifications: Specification[];
  images: string[];
}

interface Specification {
  id: number;
  name: string;
  value: string;
}
```

## 订单模块

### 创建订单
```typescript
// 接口: POST /api/v1/order/create
interface CreateOrderParams {
  productId: number;
  quantity: number;
  specifications?: Record<string, any>;
  deliveryInfo?: DeliveryInfo;
}

interface CreateOrderResponse {
  orderId: string;
  totalAmount: number;
  status: string;
}
```

### 订单列表
```typescript
// 接口: GET /api/v1/order/list
interface OrderListParams {
  page?: number;
  size?: number;
  status?: string;
}

interface OrderListResponse {
  orders: Order[];
  total: number;
  page: number;
  size: number;
}

interface Order {
  id: string;
  productName: string;
  totalAmount: number;
  status: string;
  createTime: string;
}
```

### 订单详情
```typescript
// 接口: GET /api/v1/order/{id}
interface OrderDetailResponse extends Order {
  items: OrderItem[];
  deliveryInfo: DeliveryInfo;
  paymentInfo: PaymentInfo;
}

interface OrderItem {
  productId: number;
  productName: string;
  quantity: number;
  price: number;
}
```

## 柜机管理模块

### 柜机列表
```typescript
// 接口: GET /api/v1/cabinet/list
interface CabinetListResponse {
  cabinets: Cabinet[];
}

interface Cabinet {
  id: number;
  name: string;
  location: string;
  status: string;
  capacity: number;
  usedCapacity: number;
}
```

### 绑定商品
```typescript
// 接口: POST /api/v1/cabinet/bind
interface BindGoodsParams {
  cabinetId: number;
  productId: number;
  quantity: number;
}

interface BindGoodsResponse {
  success: boolean;
  message: string;
}
```

## 审批模块

### 提交审批
```typescript
// 接口: POST /api/v1/approval/submit
interface SubmitApprovalParams {
  type: string;
  content: Record<string, any>;
  attachments?: string[];
}

interface SubmitApprovalResponse {
  approvalId: string;
  status: string;
}
```

### 审批列表
```typescript
// 接口: GET /api/v1/approval/list
interface ApprovalListResponse {
  approvals: Approval[];
  total: number;
}

interface Approval {
  id: string;
  type: string;
  status: string;
  submitter: string;
  submitTime: string;
  content: Record<string, any>;
}
```

### 处理审批
```typescript
// 接口: POST /api/v1/approval/handle
interface HandleApprovalParams {
  approvalId: string;
  action: 'approve' | 'reject';
  comment?: string;
}

interface HandleApprovalResponse {
  success: boolean;
  message: string;
}
```

## 余额管理

### 获取余额
```typescript
// 接口: GET /api/v1/balance
interface GetBalanceParams {
  corpid: string;
  openid: string;
}

interface GetBalanceResponse {
  balance: number;
  useBalance: number;
  balanceLimit: number;
  userid: string;
  corpid: string;
  ab98User?: Ab98UserDTO;
}
```

### 企业微信用户余额
```typescript
// 接口: GET /api/v1/balance/qyUser
interface GetBalanceByQyUseridParams {
  corpid: string;
  userid: string;
}

interface GetBalanceByQyUseridResponse extends GetBalanceResponse {
  // 继承 GetBalanceResponse 的所有字段
}
```

## 数据模型

### Ab98UserDTO
```typescript
interface Ab98UserDTO {
  faceImg?: string;
  sex?: string;
  name?: string;
  userid?: string;
  tel?: string;
}
```

### DeliveryInfo
```typescript
interface DeliveryInfo {
  recipient: string;
  phone: string;
  address: string;
  deliveryTime?: string;
}
```

### PaymentInfo
```typescript
interface PaymentInfo {
  paymentMethod: string;
  paymentTime?: string;
  transactionId?: string;
}
```

## 错误处理

### 常见错误码
- `400`: 请求参数错误
- `401`: 未授权访问
- `403`: 权限不足
- `404`: 资源不存在
- `500`: 服务器内部错误

### 错误处理示例
```typescript
try {
  const response = await getDataApi(params);
  // 处理成功响应
} catch (error) {
  // 处理错误
  console.error('API 调用失败:', error.message);
  // 显示错误提示给用户
}
```

## 使用示例

### 调用 API
```typescript
import { getProductListApi } from '@/common/apis/product';

// 获取商品列表
const fetchProducts = async () => {
  try {
    const response = await getProductListApi({
      page: 1,
      size: 20
    });
    if (response.code === 0) {
      return response.data.products;
    }
  } catch (error) {
    console.error('获取商品列表失败:', error);
  }
};
```

### 状态管理集成
```typescript
import { useProductStore } from '@/pinia/stores/product';

const productStore = useProductStore();

// 在组件中使用
const loadProducts = async () => {
  await productStore.fetchProducts();
};
```