initial commit

2026-02-16 12:46:37 +08:00
commit e10747feac
190 changed files with 49119 additions and 0 deletions
--- a/.opencode/skills/business/order-management/SKILL.md
+++ b/.opencode/skills/business/order-management/SKILL.md
@@ -0,0 +1,151 @@
+---
+name: order-management
+description: 订单管理模块的业务规则、订单流转状态机、支付与退款逻辑。当涉及订单相关功能开发时必须参考此 Skill。
+---
+
+# 订单管理 (Order Management) 业务 Skill
+
+## 适用范围
+
+当任务涉及以下场景时，必须加载并遵循此 Skill：
+
+- 订单列表、订单详情、订单创建
+- 支付流程、退款流程
+- 发货与物流跟踪
+- 订单统计与报表
+
+## 业务规则
+
+### 1. 订单状态机
+
+```
+待支付 (pending_payment)
+  ├─ 支付成功 → 待发货 (pending_shipment)
+  │                ├─ 发货 → 运输中 (shipping)
+  │                │            ├─ 签收 → 已完成 (completed)
+  │                │            └─ 拒收 → 退回中 (returning)
+  │                └─ 申请退款 → 退款中 (refunding)
+  ├─ 超时未付 → 已取消 (cancelled) [系统自动, 30分钟]
+  └─ 用户取消 → 已取消 (cancelled)
+```
+
+**关键约束**:
+
+- 超时取消: 下单后 **30 分钟**未支付自动取消，释放库存
+- 退款窗口: 仅在「待发货」状态可申请全额退款
+- 已发货订单: 需走退货退款流程（用户寄回 → 确认收货 → 退款）
+- 已完成订单: 签收后 **7 天**内可申请售后
+
+### 2. 金额计算规则
+
+- **订单总额** = Σ(商品售价 × 数量) - 优惠金额 + 运费
+- **金额精度**: 所有金额计算统一使用 **分 (cent)** 为单位（整数运算），前端展示时 ÷ 100 并保留 2 位小数
+- **⚠️ 严禁浮点运算**: 禁止使用 `0.1 + 0.2` 等浮点计算，必须转换为整数
+
+### 3. 订单号规则
+
+- 格式: `ORD{YYYYMMDD}{6位序号}`
+- 示例: `ORD2026021600001`
+- 订单号由后端生成，前端仅用于展示
+
+## 数据模型
+
+### 核心接口
+
+```typescript
+// src/services/order.ts
+export async function getOrderList(
+  params: OrderQueryParams,
+): Promise<API.PageResult<OrderItem>> {}
+export async function getOrderDetail(orderId: string): Promise<OrderDetail> {}
+export async function cancelOrder(
+  orderId: string,
+  reason: string,
+): Promise<void> {}
+export async function shipOrder(
+  orderId: string,
+  logistics: LogisticsInfo,
+): Promise<void> {}
+export async function refundOrder(
+  orderId: string,
+  refundData: RefundRequest,
+): Promise<void> {}
+```
+
+### 关键类型
+
+```typescript
+// src/pages/Order/data.d.ts
+type OrderStatus =
+  | 'pending_payment'
+  | 'pending_shipment'
+  | 'shipping'
+  | 'completed'
+  | 'cancelled'
+  | 'refunding'
+  | 'returning';
+
+interface OrderItem {
+  orderId: string;
+  orderNo: string;
+  userId: string;
+  userName: string;
+  items: OrderProduct[];
+  totalAmount: number; // 单位: 分
+  discountAmount: number; // 单位: 分
+  shippingFee: number; // 单位: 分
+  payableAmount: number; // 单位: 分 (实付)
+  status: OrderStatus;
+  paymentMethod?: string;
+  paidAt?: string;
+  shippedAt?: string;
+  completedAt?: string;
+  createdAt: string;
+  remark?: string;
+}
+
+interface OrderProduct {
+  productId: string;
+  productName: string;
+  skuId: string;
+  price: number; // 单位: 分
+  quantity: number;
+  subtotal: number; // 单位: 分
+}
+```
+
+## UI 交互规范
+
+### 1. 订单列表页
+
+- **组件**: 独立 `QueryFilter` + `ProTable`（字段 ≥ 4）
+- **必须筛选项**: 订单号、订单状态、下单时间范围、用户名
+- **状态标签颜色**:
+  - pending_payment → 橙色 (warning)
+  - pending_shipment → 蓝色 (processing)
+  - shipping → 青色 (cyan)
+  - completed → 绿色 (success)
+  - cancelled → 灰色 (default)
+  - refunding → 红色 (error)
+- **金额展示**: 使用 `valueType: 'money'`，需自定义 render 将分转换为元
+
+### 2. 订单详情页
+
+- **组件**: `ProDescriptions` + `Steps`（状态流转进度条）
+- **布局**: 顶部状态进度条 + 基本信息 + 商品清单 + 操作按钮
+- **操作按钮**: 根据当前状态动态显示（如待发货显示「发货」按钮，待支付显示「取消」按钮）
+
+### 3. 金额格式化工具函数
+
+```typescript
+// src/utils/currency.ts
+export const centToYuan = (cent: number): string => (cent / 100).toFixed(2);
+export const yuanToCent = (yuan: number): number => Math.round(yuan * 100);
+```
+
+## i18n Key 规范
+
+- 菜单: `menu.order.*`
+- 页面: `pages.order.*`
+- 表单: `order.form.*`
+- 状态: `order.status.*`