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

API 接口文档

概述

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

基础配置

请求配置

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

响应格式

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

状态码说明

• 0: 成功
• 401: 登录过期
• 403: 拒绝访问
• 500: 服务器内部错误

用户认证模块

微信登录

获取 OpenID

// 接口: GET /api/v1/wx/getOpenId
interface GetOpenIdParams {
  code: string;
}

interface GetOpenIdResponse {
  openid: string;
}

企业微信登录

// 接口: 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 登录

// 接口: 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;
}

商品模块

商品列表

// 接口: 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;
}

商品详情

// 接口: GET /api/v1/product/{id}
interface ProductDetailResponse extends Product {
  specifications: Specification[];
  images: string[];
}

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

订单模块

创建订单

// 接口: 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;
}

订单列表

// 接口: 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;
}

订单详情

// 接口: 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;
}

柜机管理模块

柜机列表

// 接口: GET /api/v1/cabinet/list
interface CabinetListResponse {
  cabinets: Cabinet[];
}

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

绑定商品

// 接口: POST /api/v1/cabinet/bind
interface BindGoodsParams {
  cabinetId: number;
  productId: number;
  quantity: number;
}

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

审批模块

提交审批

// 接口: POST /api/v1/approval/submit
interface SubmitApprovalParams {
  type: string;
  content: Record<string, any>;
  attachments?: string[];
}

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

审批列表

// 接口: 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>;
}

处理审批

// 接口: POST /api/v1/approval/handle
interface HandleApprovalParams {
  approvalId: string;
  action: 'approve' | 'reject';
  comment?: string;
}

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

余额管理

获取余额

// 接口: GET /api/v1/balance
interface GetBalanceParams {
  corpid: string;
  openid: string;
}

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

企业微信用户余额

// 接口: GET /api/v1/balance/qyUser
interface GetBalanceByQyUseridParams {
  corpid: string;
  userid: string;
}

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

数据模型

Ab98UserDTO

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

DeliveryInfo

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

PaymentInfo

interface PaymentInfo {
  paymentMethod: string;
  paymentTime?: string;
  transactionId?: string;
}

错误处理

常见错误码

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

错误处理示例

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

使用示例

调用 API

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);
  }
};

状态管理集成

import { useProductStore } from '@/pinia/stores/product';

const productStore = useProductStore();

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