179 lines
4.5 KiB
Markdown
179 lines
4.5 KiB
Markdown
# 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. 完善错误处理和日志记录 |