refactor(docs): 更新API接口文档结构，优化环境配置说明并移除冗余文件

2025-09-22 15:29:23 +08:00
parent cc2a351f84
commit 00cf840e6f
74 changed files with 620 additions and 5203 deletions
--- a/admin-system/src/api/supplier.ts
+++ b/admin-system/src/api/supplier.ts
@@ -1,4 +1,5 @@
 import request from '@/utils/request'
+import type { ApiResponse, PaginatedResponse } from '@/utils/request'
 import type { 
  Supplier, 
  SupplierListParams, 
@@ -8,68 +9,39 @@ import type {
 } from '@/types/supplier'

 // 获取供应商列表
-export const getSupplierList = (params: SupplierListParams) => {
-  return request<{
-    list: Supplier[]
-    pagination: {
-      page: number
-      pageSize: number
-      total: number
-      totalPages: number
-    }
-  }>({
-    url: '/suppliers',
-    method: 'GET',
-    params
-  })
+export const getSupplierList = (params: SupplierListParams): Promise<ApiResponse<PaginatedResponse<Supplier>>> => {
+  return request.get('/suppliers', { params })
 }

 // 获取供应商详情
-export const getSupplierDetail = (id: number) => {
-  return request<Supplier>({
-    url: `/suppliers/${id}`,
-    method: 'GET'
-  })
+export const getSupplierDetail = (id: number): Promise<ApiResponse<Supplier>> => {
+  return request.get(`/suppliers/${id}`)
 }

 // 创建供应商
-export const createSupplier = (data: SupplierCreateForm) => {
-  return request<Supplier>({
-    url: '/suppliers',
-    method: 'POST',
-    data: {
-      ...data,
-      cattleTypes: Array.isArray(data.cattleTypes) ? data.cattleTypes : JSON.parse(data.cattleTypes || '[]'),
-      certifications: Array.isArray(data.certifications) ? data.certifications : JSON.parse(data.certifications || '[]')
-    }
+export const createSupplier = (data: SupplierCreateForm): Promise<ApiResponse<Supplier>> => {
+  return request.post('/suppliers', {
+    ...data,
+    cattleTypes: Array.isArray(data.cattleTypes) ? data.cattleTypes : JSON.parse(data.cattleTypes || '[]'),
+    certifications: Array.isArray(data.certifications) ? data.certifications : JSON.parse(data.certifications || '[]')
  })
 }

 // 更新供应商
-export const updateSupplier = (id: number, data: SupplierUpdateForm) => {
-  return request<Supplier>({
-    url: `/suppliers/${id}`,
-    method: 'PUT',
-    data: {
-      ...data,
-      cattleTypes: data.cattleTypes ? (Array.isArray(data.cattleTypes) ? data.cattleTypes : JSON.parse(data.cattleTypes)) : undefined,
-      certifications: data.certifications ? (Array.isArray(data.certifications) ? data.certifications : JSON.parse(data.certifications)) : undefined
-    }
+export const updateSupplier = (id: number, data: SupplierUpdateForm): Promise<ApiResponse<Supplier>> => {
+  return request.put(`/suppliers/${id}`, {
+    ...data,
+    cattleTypes: data.cattleTypes ? (Array.isArray(data.cattleTypes) ? data.cattleTypes : JSON.parse(data.cattleTypes)) : undefined,
+    certifications: data.certifications ? (Array.isArray(data.certifications) ? data.certifications : JSON.parse(data.certifications)) : undefined
  })
 }

 // 删除供应商
-export const deleteSupplier = (id: number) => {
-  return request({
-    url: `/suppliers/${id}`,
-    method: 'DELETE'
-  })
+export const deleteSupplier = (id: number): Promise<ApiResponse> => {
+  return request.delete(`/suppliers/${id}`)
 }

 // 获取供应商统计信息
-export const getSupplierStats = () => {
-  return request<SupplierStatistics>({
-    url: '/suppliers/stats/overview',
-    method: 'GET'
-  })
+export const getSupplierStats = (): Promise<ApiResponse<SupplierStatistics>> => {
+  return request.get('/suppliers/stats/overview')
 }
--- a/admin-system/src/api/transport.ts
+++ b/admin-system/src/api/transport.ts
@@ -1,4 +1,5 @@
-import request from '@/utils/request';
+import request from '@/utils/request'
+import type { ApiResponse, PaginatedResponse } from '@/utils/request'
 import type { 
  Transport, 
  TransportCreateForm, 
@@ -8,8 +9,7 @@ import type {
  VehicleCreateForm,
  VehicleUpdateForm,
  VehicleListParams
-} from '@/types/transport';
-import type { PaginatedResponse, ApiResponse } from '@/types/api';
+} from '@/types/transport'

 // 运输管理相关API接口

@@ -19,12 +19,8 @@ import type { PaginatedResponse, ApiResponse } from '@/types/api';
 * @returns 运输列表
 */
 export const getTransportList = (params: TransportListParams): Promise<ApiResponse<PaginatedResponse<Transport>>> => {
-  return request({
-    url: '/transports',
-    method: 'get',
-    params
-  });
-};
+  return request.get('/transports', { params })
+}

 /**
 * 获取运输详情
@@ -32,11 +28,8 @@ export const getTransportList = (params: TransportListParams): Promise<ApiRespon
 * @returns 运输详情
 */
 export const getTransportDetail = (id: number): Promise<ApiResponse<Transport>> => {
-  return request({
-    url: `/transports/${id}`,
-    method: 'get'
-  });
-};
+  return request.get(`/transports/${id}`)
+}

 /**
 * 创建运输记录
@@ -44,12 +37,8 @@ export const getTransportDetail = (id: number): Promise<ApiResponse<Transport>>
 * @returns 创建的运输记录
 */
 export const createTransport = (data: TransportCreateForm): Promise<ApiResponse<Transport>> => {
-  return request({
-    url: '/transports',
-    method: 'post',
-    data
-  });
-};
+  return request.post('/transports', data)
+}

 /**
 * 更新运输记录
@@ -58,24 +47,17 @@ export const createTransport = (data: TransportCreateForm): Promise<ApiResponse<
 * @returns 更新的运输记录
 */
 export const updateTransport = (id: number, data: TransportUpdateForm): Promise<ApiResponse<Transport>> => {
-  return request({
-    url: `/transports/${id}`,
-    method: 'put',
-    data
-  });
-};
+  return request.put(`/transports/${id}`, data)
+}

 /**
 * 删除运输记录
 * @param id 运输ID
 * @returns 删除结果
 */
-export const deleteTransport = (id: number): Promise<ApiResponse<null>> => {
-  return request({
-    url: `/transports/${id}`,
-    method: 'delete'
-  });
-};
+export const deleteTransport = (id: number): Promise<ApiResponse> => {
+  return request.delete(`/transports/${id}`)
+}

 /**
 * 获取车辆列表
@@ -83,12 +65,8 @@ export const deleteTransport = (id: number): Promise<ApiResponse<null>> => {
 * @returns 车辆列表
 */
 export const getVehicleList = (params: VehicleListParams): Promise<ApiResponse<PaginatedResponse<Vehicle>>> => {
-  return request({
-    url: '/transports/vehicles',
-    method: 'get',
-    params
-  });
-};
+  return request.get('/transports/vehicles', { params })
+}

 /**
 * 获取车辆详情
@@ -96,11 +74,8 @@ export const getVehicleList = (params: VehicleListParams): Promise<ApiResponse<P
 * @returns 车辆详情
 */
 export const getVehicleDetail = (id: number): Promise<ApiResponse<Vehicle>> => {
-  return request({
-    url: `/transports/vehicles/${id}`,
-    method: 'get'
-  });
-};
+  return request.get(`/transports/vehicles/${id}`)
+}

 /**
 * 创建车辆记录
@@ -108,12 +83,8 @@ export const getVehicleDetail = (id: number): Promise<ApiResponse<Vehicle>> => {
 * @returns 创建的车辆记录
 */
 export const createVehicle = (data: VehicleCreateForm): Promise<ApiResponse<Vehicle>> => {
-  return request({
-    url: '/transports/vehicles',
-    method: 'post',
-    data
-  });
-};
+  return request.post('/transports/vehicles', data)
+}

 /**
 * 更新车辆记录
@@ -122,21 +93,14 @@ export const createVehicle = (data: VehicleCreateForm): Promise<ApiResponse<Vehi
 * @returns 更新的车辆记录
 */
 export const updateVehicle = (id: number, data: VehicleUpdateForm): Promise<ApiResponse<Vehicle>> => {
-  return request({
-    url: `/transports/vehicles/${id}`,
-    method: 'put',
-    data
-  });
-};
+  return request.put(`/transports/vehicles/${id}`, data)
+}

 /**
 * 删除车辆记录
 * @param id 车辆ID
 * @returns 删除结果
 */
-export const deleteVehicle = (id: number): Promise<ApiResponse<null>> => {
-  return request({
-    url: `/transports/vehicles/${id}`,
-    method: 'delete'
-  });
-};
+export const deleteVehicle = (id: number): Promise<ApiResponse> => {
+  return request.delete(`/transports/vehicles/${id}`)
+}
--- a/admin-system/src/types/user.ts
+++ b/admin-system/src/types/user.ts
@@ -6,7 +6,7 @@ export interface User {
  email: string
  phone?: string
  avatar?: string
-  role: string
+  user_type: string
  status: 'active' | 'inactive' | 'banned'
  createdAt: string
  updatedAt: string
@@ -29,7 +29,7 @@ export interface UserListParams {
  page?: number
  pageSize?: number
  keyword?: string
-  role?: string
+  user_type?: string
  status?: string
 }

--- a/admin-system/src/views/user/index.vue
+++ b/admin-system/src/views/user/index.vue
@@ -443,7 +443,7 @@ const handleSubmit = async () => {
        username: form.username,
        email: form.email,
        phone: form.phone,
-        role: form.role,
+        user_type: form.role,  // 将前端的role映射到后端的user_type
        status: form.status
      }
      await updateUser(form.id, updateData)
@@ -454,7 +454,7 @@ const handleSubmit = async () => {
        email: form.email,
        phone: form.phone,
        password: form.password,
-        role: form.role,
+        user_type: form.role,  // 将前端的role映射到后端的user_type
        status: form.status
      }
      await createUser(createData)