gitadmin/erp-backend

Fork 0

Yatu 32685b3b01 Initial commit: ERP Backend baseline

2026-04-01 17:07:04 +08:00

4.5 KiB

Raw Blame History

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}	删除店铺授权

请求示例:

// 获取授权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}	删除商品

请求示例:

// 创建平台商品
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. 其他已完成模块

采购单模块 (PurchaseOrderController)
收货单模块 (ReceivingOrderController)
模板模块 (TemplateController)
仓库模板绑定模块 (WarehouseTemplateBindingController)
订单模块 (OrderController)

数据库迁移

已创建的迁移文件:

create_shop_auths_table.php - 店铺授权表
create_platforms_table.php - 平台商品表

运行迁移命令:

php artisan migrate

路由配置

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

前端对接说明

店铺授权流程

前端调用 /api/shops/auth-url 获取授权URL
用户点击授权URL跳转到平台授权页面
平台回调到 /api/shops/callback
系统保存授权信息并返回成功

平台商品管理流程

先完成店铺授权
调用 /api/platforms/sync 同步平台商品
使用 /api/platforms 接口管理商品
支持批量操作和状态管理

注意事项

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

测试

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

运行测试:

php artisan test --filter ModulesTest

下一步开发建议

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

4.5 KiB Raw Blame History