---
name: product-management
description: 商品管理模块的业务规则、数据模型、状态机与 UI 交互规范。当涉及商品相关功能开发时必须参考此 Skill。
---

# 商品管理 (Product Management) 业务 Skill

## 适用范围

当任务涉及以下场景时，必须加载并遵循此 Skill：

- 商品列表、商品详情、商品创建/编辑
- SKU 管理、库存管理、价格体系
- 商品分类与属性管理

## 业务规则

### 1. 商品状态机

```
草稿 (draft) → 待审核 (pending_review) → 已上架 (online) → 已下架 (offline)
                    ↓                                           ↑
                  驳回 (rejected) ────────────────────────────→ ┘
```

**关键约束**:

- 草稿状态可直接删除
- 已上架商品必须先下架才能编辑核心字段（名称、价格、SKU）
- 已上架商品的**非核心字段**（描述、图片）允许直接编辑
- 删除操作仅限于「草稿」和「已下架」状态

### 2. 价格体系

- `originalPrice`: 原价（必填，> 0）
- `salePrice`: 售价（必填，> 0，且 ≤ 原价）
- `costPrice`: 成本价（选填，仅管理员可见）
- 价格精度: 统一保留 **2 位小数**，使用 `number` 类型，前端展示时通过 `valueType: 'money'` 格式化

### 3. 库存规则

- 库存低于 `safetyStock`（安全库存）时在列表显示 ⚠️ 警告标识
- 库存为 0 时自动标记为「缺货」状态（不影响上下架状态）
- 库存变更必须记录变更日志（调拨、入库、出库、盘点）

## 数据模型

### 核心接口

```typescript
// src/services/product.ts
export async function getProductList(
  params: ProductQueryParams,
): Promise<API.PageResult<ProductItem>> {}
export async function getProductDetail(id: string): Promise<ProductItem> {}
export async function createProduct(
  data: ProductFormData,
): Promise<ProductItem> {}
export async function updateProduct(
  id: string,
  data: Partial<ProductFormData>,
): Promise<ProductItem> {}
export async function updateProductStatus(
  id: string,
  status: ProductStatus,
): Promise<void> {}
export async function deleteProduct(id: string): Promise<void> {}
```

### 关键类型

```typescript
// src/pages/ProductList/data.d.ts
type ProductStatus =
  | 'draft'
  | 'pending_review'
  | 'online'
  | 'offline'
  | 'rejected';

interface ProductItem {
  id: string;
  name: string;
  categoryId: string;
  categoryName: string;
  originalPrice: number;
  salePrice: number;
  costPrice?: number;
  stock: number;
  safetyStock: number;
  status: ProductStatus;
  images: string[];
  description: string;
  attributes: Record<string, string>;
  createdAt: string;
  updatedAt: string;
}
```

## UI 交互规范

### 1. 商品列表页

- **组件**: `ProTable`
- **必须包含列**: 商品名称、分类、售价、库存、状态、操作
- **状态筛选**: 使用 `valueEnum` 映射状态标签颜色
  - draft → 灰色
  - pending_review → 橙色
  - online → 绿色
  - offline → 默认
  - rejected → 红色
- **批量操作**: 支持批量上架/下架

### 2. 商品编辑

- **组件**: `ProForm` + `StepsForm`（分步表单）
- **步骤**: 基本信息 → SKU/价格 → 图片/描述 → 确认提交
- **价格输入**: 使用 `ProFormMoney` 或 `ProFormDigit` 并配置 `precision={2}`

### 3. 库存警告

- 库存 < 安全库存: 单元格显示橙色 + ⚠️
- 库存 = 0: 单元格显示红色 + "缺货" 标签

## i18n Key 规范

菜单和页面文案 Key 前缀:

- 菜单: `menu.product.*`
- 页面: `pages.product.*`
- 表单: `product.form.*`
- 状态: `product.status.*`