agent/.opencode/skills/business/product-management/SKILL.md

name, description

name	description
product-management	商品管理模块的业务规则、数据模型、状态机与 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 时自动标记为「缺货」状态（不影响上下架状态）
• 库存变更必须记录变更日志（调拨、入库、出库、盘点）

数据模型

核心接口

// 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> {}

关键类型

// 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.*