压缩历史至 95081aff

frontend/lib/services/dispute/dispute.service.ts

@@ -0,0 +1,128 @@
+import { BaseService } from '../core/base.service';
+import type {
+  ListDisputesRequest,
+  ListDisputesResponse,
+  RefundReviewRequest,
+  CloseDisputeRequest,
+  CreateDisputeRequest,
+  CreateDisputeResponse,
+} from './types';
+
+/**
+ * 争议服务
+ * 处理争议相关的 API 请求
+ */
+export class DisputeService extends BaseService {
+  protected static readonly basePath = '/api/v1/order';
+
+  /**
+   * 创建争议
+   * @param data - 争议信息
+   * @returns void
+   * @throws {UnauthorizedError} 当未登录时
+   * @throws {NotFoundError} 当订单不存在或不符合争议条件时
+   * @throws {ValidationError} 当参数验证失败时
+   * 
+   * @example
+   * ```typescript
+   * await DisputeService.createDispute({
+   *   order_id: 123,
+   *   reason: '商品质量问题'
+   * });
+   * ```
+   */
+  static async createDispute(data: CreateDisputeRequest): Promise<CreateDisputeResponse> {
+    return this.post<CreateDisputeResponse>('/dispute', data);
+  }
+
+  /**
+   * 查询用户发起的争议列表
+   * @param params - 查询参数
+   * @returns 争议列表
+   * @throws {UnauthorizedError} 当未登录时
+   * @throws {ValidationError} 当参数验证失败时
+   * 
+   * @example
+   * ```typescript
+   * const result = await DisputeService.listDisputes({
+   *   page: 1,
+   *   page_size: 20,
+   *   status: 'disputing'
+   * });
+   * console.log('争议数量:', result.total);
+   * ```
+   */
+  static async listDisputes(
+    params: ListDisputesRequest
+  ): Promise<ListDisputesResponse> {
+    return this.post<ListDisputesResponse>('/disputes', params);
+  }
+
+  /**
+   * 查询商户的争议列表
+   * @param params - 查询参数
+   * @returns 争议列表
+   * @throws {UnauthorizedError} 当未登录时
+   * @throws {ValidationError} 当参数验证失败时
+   * 
+   * @example
+   * ```typescript
+   * const result = await DisputeService.listMerchantDisputes({
+   *   page: 1,
+   *   page_size: 20
+   * });
+   * console.log('商户争议数量:', result.total);
+   * ```
+   */
+  static async listMerchantDisputes(
+    params: ListDisputesRequest
+  ): Promise<ListDisputesResponse> {
+    return this.post<ListDisputesResponse>('/disputes/merchant', params);
+  }
+
+  /**
+   * 退款审核（商户使用）
+   * @param data - 审核请求
+   * @returns void
+   * @throws {UnauthorizedError} 当未登录时
+   * @throws {NotFoundError} 当争议不存在时
+   * @throws {ValidationError} 当参数验证失败时
+   * 
+   * @example
+   * ```typescript
+   * // 同意退款
+   * await DisputeService.refundReview({
+   *   dispute_id: 123,
+   *   status: 'refund'
+   * });
+   * 
+   * // 拒绝退款
+   * await DisputeService.refundReview({
+   *   dispute_id: 123,
+   *   status: 'closed',
+   *   reason: '不符合退款条件'
+   * });
+   * ```
+   */
+  static async refundReview(data: RefundReviewRequest): Promise<void> {
+    return this.post('/refund-review', data);
+  }
+
+  /**
+   * 关闭争议（用户主动关闭）
+   * @param data - 关闭争议请求
+   * @returns void
+   * @throws {UnauthorizedError} 当未登录时
+   * @throws {NotFoundError} 当争议不存在时
+   * 
+   * @example
+   * ```typescript
+   * await DisputeService.closeDispute({
+   *   dispute_id: 123
+   * });
+   * ```
+   */
+  static async closeDispute(data: CloseDisputeRequest): Promise<void> {
+    return this.post('/dispute/close', data);
+  }
+}

frontend/lib/services/dispute/index.ts

@@ -0,0 +1,31 @@
+/**
+ * 争议服务模块
+ * 
+ * @description
+ * 提供争议处理相关的功能，包括：
+ * - 创建争议
+ * - 查询用户发起的争议列表
+ * - 查询商户的争议列表
+ * - 退款审核（商户）
+ * - 关闭争议（用户）
+ * 
+ * @example
+ * ```typescript
+ * import { DisputeService } from '@/lib/services';
+ * 
+ * // 创建争议
+ * await DisputeService.createDispute({
+ *   order_id: 123,
+ *   reason: '商品质量问题'
+ * });
+ * 
+ * // 查询争议列表
+ * const disputes = await DisputeService.listDisputes({
+ *   page: 1,
+ *   page_size: 20
+ * });
+ * ```
+ */
+
+export { DisputeService } from './dispute.service';
+export type * from './types';

frontend/lib/services/dispute/types.ts

@@ -0,0 +1,105 @@
+/**
+ * 争议状态
+ */
+export type DisputeStatus = 'disputing' | 'refund' | 'closed';
+
+/**
+ * 争议信息
+ */
+export interface Dispute {
+  /** 争议 ID */
+  id: string;
+  /** 订单 ID */
+  order_id: string;
+  /** 发起者用户 ID */
+  initiator_user_id: number;
+  /** 争议原因 */
+  reason: string;
+  /** 争议状态 */
+  status: DisputeStatus;
+  /** 处理者用户 ID */
+  handler_user_id?: number;
+  /** 发起者账户 */
+  initiator_username: string;
+  /** 处理者账户 */
+  handler_username: string;
+  /** 创建时间 */
+  created_at: string;
+  /** 更新时间 */
+  updated_at: string;
+}
+
+/**
+ * 争议列表项（包含订单信息）
+ */
+export interface DisputeWithOrder extends Dispute {
+  /** 订单名称 */
+  order_name: string;
+  /** 收款方账户 */
+  payee_username: string;
+  /** 订单金额 */
+  amount: string;
+}
+
+/**
+ * 查询争议列表请求
+ */
+export interface ListDisputesRequest {
+  /** 页码，从 1 开始 */
+  page: number;
+  /** 每页数量，1-100 */
+  page_size: number;
+  /** 状态筛选（可选） */
+  status?: DisputeStatus;
+  /** 争议 ID（可选） */
+  dispute_id?: string;
+}
+
+/**
+ * 争议列表响应
+ */
+export interface ListDisputesResponse {
+  /** 总记录数 */
+  total: number;
+  /** 当前页码 */
+  page: number;
+  /** 每页数量 */
+  page_size: number;
+  /** 争议列表 */
+  disputes: DisputeWithOrder[];
+}
+
+/**
+ * 退款审核请求
+ */
+export interface RefundReviewRequest {
+  /** 争议 ID */
+  dispute_id: string;
+  /** 审核结果 */
+  status: 'refund' | 'closed';
+  /** 拒绝原因（status 为 closed 时必填，最大 100 字符） */
+  reason?: string;
+}
+
+/**
+ * 关闭争议请求
+ */
+export interface CloseDisputeRequest {
+  /** 争议 ID */
+  dispute_id: string;
+}
+
+/**
+ * 创建争议请求
+ */
+export interface CreateDisputeRequest {
+  /** 订单 ID */
+  order_id: string;
+  /** 争议原因（最大 100 字符） */
+  reason: string;
+}
+
+/**
+ * 创建争议响应
+ */
+export type CreateDisputeResponse = Dispute;