wurenzhi
136c2fa579
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
3.0 KiB
3.0 KiB
📊 Data & API Specifications (Crawlful Hub)
定位：Crawlful Hub 数据架构与接口规格书 - 包含数据库 Schema、核心业务流程及全量 API 定义。 更新日期: 2026-03-17
1. 数据库结构 (Data Schema)
1.1 命名规范
- 表前缀:
cf_(crawlful) - 字段命名: snake_case
- 金額字段:
decimal(10,2)或更高精度。 - 物理单位: 长度 (cm), 重量 (kg), 体积 (m³)。
1.2 核心表定义
租户与用户
cf_tenant: 租户 ID、名称、配额、状态。cf_user: 邮箱、密码哈希、角色 (ADMIN/MANAGER 等)、租户 ID。
店铺与商品
cf_shop: 租户 ID、平台 (AMAZON/TIKTOK 等)、授权 Token。cf_product: 租户 ID、源平台 ID、标题、描述、JSON 图片列表。cf_product_sku: SKU 编码、属性 JSON、成本价、零售价、重量/尺寸。
订单与库存
cf_inventory: SKU ID、仓库 ID、总数量、可用/预留数量。cf_order: 平台订单号、总金额、货币、利润/利润率、状态。cf_order_item: 订单项、SKU ID、单价、数量。
供应链与财务
cf_supplier: 供应商名称、联系方式、评分、状态。cf_purchase_order: 采购单号、供应商 ID、总金额、状态。cf_finance_reconciliation: 对账周期、总销售/利润、差异状态。
2. 核心业务流程 (Business Processes)
2.1 商品采集与刊登 (Collection & Listing)
- 采集: 用户输入 URL → Extension 解析 DOM → 发送至 Hub 草稿箱。
- 刊登: 选择草稿 → 平台适配器转换字段 → 调用平台 API 发布 → 记录刊登历史。
2.2 订单履约与财务 (Fulfillment & Finance)
- 订单: 平台 Webhook 推送 → 解析并入库 → 利润审计 (红线校验) → 状态流转。
- 库存: 平台同步 → 更新本地库存 → 低于阈值自动触发补货提醒。
- 对账: 拉取平台账单 → 自动差异匹配 → 生成报告 → 人工审核异常项。
3. 全量 API 端点映射 (API Map)
3.1 基础管理
POST /api/auth/login: 用户登录。GET /api/users: 获取用户列表。GET /api/shops: 获取授权店铺。
3.2 商品与库存 (Product & Inventory)
GET /api/products: 获取商品列表。POST /api/products/publish: 发布商品到平台。GET /api/inventory/aging: 库存老化分析。GET /api/inventory/forecast: 库存预测。
3.3 订单与支付 (Order & Payment)
GET /api/orders: 获取订单列表。PUT /api/orders/:id/status: 更新订单状态。POST /api/payments: 创建支付订单。POST /api/payments/callback: 处理支付回调。
3.4 财务管理 (Finance)
GET /api/finance/reconciliation: 财务对账。
4. 通用响应与状态码
响应格式
{
"success": true,
"data": { ... },
"error": "optional error message"
}
常用状态码
200: 成功 |401: 未授权 |403: 禁止访问 |404: 资源不存在 |500: 服务器错误。