# ERP系统后端API文档

## 已完成模块

### 1. 店铺授权模块 (ShopAuthController)

**数据库表**: `shop_auths`

**字段说明**:
- `platform`: 平台类型 (taobao, tmall, jd, pdd, douyin)
- `shop_name`: 店铺名称
- `access_token`: 访问令牌
- `refresh_token`: 刷新令牌
- `expires_at`: 令牌过期时间
- `status`: 状态 (active, expired, revoked)
- `config`: 平台配置 (JSON格式)

**API接口**:

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/shops | 获取店铺授权列表 |
| GET | /api/shops/platforms | 获取支持的平台列表 |
| POST | /api/shops/auth-url | 获取授权URL |
| POST | /api/shops/callback | 授权回调处理 |
| GET | /api/shops/{id} | 获取店铺授权详情 |
| POST | /api/shops/{id}/refresh | 刷新访问令牌 |
| DELETE | /api/shops/{id} | 删除店铺授权 |

**请求示例**:
```json
// 获取授权URL
POST /api/shops/auth-url
{
  "platform": "taobao",
  "callback_url": "http://your-domain.com/callback"
}

// 授权回调
POST /api/shops/callback
{
  "platform": "taobao",
  "code": "authorization_code",
  "state": "optional_state"
}
```

### 2. 平台商品模块 (PlatformController)

**数据库表**: `platforms`

**字段说明**:
- `shop_auth_id`: 店铺授权ID (外键)
- `platform_product_id`: 平台商品ID
- `platform_sku_id`: 平台SKU ID (可选)
- `title`: 商品标题
- `description`: 商品描述
- `price`: 价格
- `original_price`: 原价
- `stock`: 库存
- `sold`: 已售数量
- `images`: 商品图片 (JSON数组)
- `specs`: 规格信息 (JSON格式)
- `status`: 商品状态 (on_sale, off_sale, deleted)
- `sync_status`: 同步状态 (pending, syncing, synced, failed)
- `last_sync_at`: 最后同步时间
- `sync_error`: 同步错误信息

**API接口**:

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/platforms | 获取平台商品列表 |
| POST | /api/platforms | 创建平台商品 |
| GET | /api/platforms/stats | 获取商品统计 |
| POST | /api/platforms/sync | 同步平台商品 |
| POST | /api/platforms/batch-update | 批量更新商品状态 |
| GET | /api/platforms/{id} | 获取商品详情 |
| PUT | /api/platforms/{id} | 更新商品信息 |
| DELETE | /api/platforms/{id} | 删除商品 |

**请求示例**:
```json
// 创建平台商品
POST /api/platforms
{
  "shop_auth_id": 1,
  "platform_product_id": "123456789",
  "title": "测试商品",
  "price": 99.99,
  "stock": 100,
  "status": "on_sale",
  "images": ["https://example.com/image1.jpg"],
  "specs": {"color": "红色", "size": "M"}
}

// 同步平台商品
POST /api/platforms/sync
{
  "shop_auth_id": 1,
  "sync_all": true
}

// 批量更新状态
POST /api/platforms/batch-update
{
  "ids": [1, 2, 3],
  "status": "off_sale"
}
```

**查询参数**:
- `shop_auth_id`: 按店铺授权ID筛选
- `platform`: 按平台类型筛选
- `title`: 按商品标题搜索
- `status`: 按商品状态筛选
- `sync_status`: 按同步状态筛选
- `sort_field`: 排序字段 (默认: created_at)
- `sort_order`: 排序顺序 (默认: desc)
- `limit`: 每页数量 (默认: 10)

### 3. 其他已完成模块

1. **采购单模块** (PurchaseOrderController)
2. **收货单模块** (ReceivingOrderController)
3. **模板模块** (TemplateController)
4. **仓库模板绑定模块** (WarehouseTemplateBindingController)
5. **订单模块** (OrderController)

## 数据库迁移

已创建的迁移文件:
1. `create_shop_auths_table.php` - 店铺授权表
2. `create_platforms_table.php` - 平台商品表

运行迁移命令:
```bash
php artisan migrate
```

## 路由配置

所有API路由已配置在 `routes/api.php` 文件中。

## 前端对接说明

### 店铺授权流程
1. 前端调用 `/api/shops/auth-url` 获取授权URL
2. 用户点击授权URL跳转到平台授权页面
3. 平台回调到 `/api/shops/callback`
4. 系统保存授权信息并返回成功

### 平台商品管理流程
1. 先完成店铺授权
2. 调用 `/api/platforms/sync` 同步平台商品
3. 使用 `/api/platforms` 接口管理商品
4. 支持批量操作和状态管理

### 注意事项
1. 平台商品同步需要根据具体平台实现API调用
2. 建议使用队列处理同步任务，避免超时
3. 定期刷新访问令牌，避免授权失效

## 测试

已创建测试文件: `tests/ModulesTest.php`

运行测试:
```bash
php artisan test --filter ModulesTest
```

## 下一步开发建议

1. 实现具体的平台API集成 (淘宝、京东、拼多多等)
2. 添加商品同步队列任务
3. 实现商品库存同步
4. 添加订单同步功能
5. 完善错误处理和日志记录