# 商品域服务

> **入口**: [_index.md](_index.md)

---

## 服务列表

| 服务 | 文件 | 职责 |
|------|------|------|
| ProductService | services/ProductService.ts | 商品主数据管理 |
| SKUService | services/SKUService.ts | SKU变体管理 |
| ListingService | services/ListingService.ts | 平台刊登管理 |
| PricingService | services/PricingService.ts | 价格计算 |

---

## 核心流程

```
商品采集 → SPU创建 → SKU生成 → 平台刊登 → 价格同步
```

---

## ProductService

### 方法列表

| 方法 | 说明 | 参数 | 返回 |
|------|------|------|------|
| list | 商品列表 | ListParams | Product[] |
| get | 商品详情 | id | Product |
| create | 创建商品 | CreateRequest | Product |
| update | 更新商品 | id, UpdateRequest | Product |
| delete | 删除商品 | id | void |

### 示例

```typescript
// 获取商品列表
const products = await ProductService.list({
  tenantId: 'tenant-001',
  shopId: 'shop-001',
  status: 'ACTIVE',
  page: 1,
  pageSize: 20,
});

// 创建商品
const product = await ProductService.create({
  tenantId: 'tenant-001',
  shopId: 'shop-001',
  name: '商品名称',
  platform: 'SHOPIFY',
  // ...
});
```

---

## SKUService

### 方法列表

| 方法 | 说明 | 参数 | 返回 |
|------|------|------|------|
| list | SKU列表 | productId | SKU[] |
| get | SKU详情 | id | SKU |
| create | 创建SKU | CreateRequest | SKU |
| update | 更新SKU | id, UpdateRequest | SKU |
| updateStock | 更新库存 | id, quantity | SKU |

---

## ListingService

### 方法列表

| 方法 | 说明 | 参数 | 返回 |
|------|------|------|------|
| list | 刊登列表 | ListParams | Listing[] |
| get | 刊登详情 | id | Listing |
| publish | 刊登商品 | PublishRequest | Listing |
| updatePrice | 更新价格 | id, price | Listing |
| syncInventory | 同步库存 | id, stock | Listing |

---

## PricingService

### 方法列表

| 方法 | 说明 | 参数 | 返回 |
|------|------|------|------|
| calculate | 计算价格 | PriceParams | number |
| getStrategy | 获取策略 | id | PriceStrategy |
| createStrategy | 创建策略 | CreateRequest | PriceStrategy |
| updateStrategy | 更新策略 | id, UpdateRequest | PriceStrategy |

### 价格计算流程

```
基准价(SKU.basePrice)
    ↓
策略计算(PriceStrategy)
    ↓
最终价(Listing.price)
```

### 示例

```typescript
const finalPrice = await PricingService.calculate({
  basePrice: 100,
  strategy: {
    type: 'multiplier',
    value: 1.2,
  },
  platform: 'SHOPIFY',
});
// 结果: 120
```

---

## 状态机

```
DRAFT → PENDING_REVIEW → ACTIVE → INACTIVE
                              ↓
                         ARCHIVED
```

| 状态 | 说明 | 允许操作 |
|------|------|---------|
| DRAFT | 草稿 | 编辑、删除、提交审核 |
| PENDING_REVIEW | 待审核 | 审核通过、审核拒绝 |
| ACTIVE | 活跃 | 编辑、停用、刊登 |
| INACTIVE | 停用 | 启用、归档 |
| ARCHIVED | 归档 | 删除 |

---

## API端点

| 端点 | 方法 | 服务方法 |
|------|------|----------|
| /api/v1/products | GET | ProductService.list |
| /api/v1/products | POST | ProductService.create |
| /api/v1/products/:id | GET | ProductService.get |
| /api/v1/products/:id | PUT | ProductService.update |
| /api/v1/products/:id | DELETE | ProductService.delete |
| /api/v1/products/:id/skus | GET | SKUService.list |
| /api/v1/products/:id/listings | GET | ListingService.list |
| /api/v1/listings/:id/publish | POST | ListingService.publish |

---

*最后更新: 2026-03-22*