开发者接入指南

全部示例基于本机 Docker 部署的真实服务（http://localhost:3000/api/v1），已通过端到端回归验证，可直接复制运行。完整接口定义见 Swagger 在线文档。

快速开始

三步完成第一笔自助打印订单

获取访问令牌（演示环境免密登录）

# mock 模式（MOCK_ENABLED=true 的开发/演示环境）：任意用户名密码即可换取 JWT
curl -X POST http://localhost:3000/api/v1/auth/wx-login \
  -H "Content-Type: application/json" \
  -d '{"code": "mock_local_dev_user"}'

# 响应 data.accessToken 即 Bearer Token；正式环境请使用微信授权 code 换取。

上传打印文件（单文件直传）

# 小文件走单传接口；大文件支持分片上传（见 Swagger files 节点）
curl -X POST http://localhost:3000/api/v1/files/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./document.pdf"

# 响应 data.fileId 用于下单；服务端自动解析页数（PDF 精确、图片=1 页）。

创建订单并支付

curl -X POST http://localhost:3000/api/v1/orders \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "order_type": "document",           // document | photo | id_photo | poster | banner ...
    "delivery_mode": "pickup",          // pickup | express | same_city
    "product_name": "学习资料",
    "quantity": 1,
    "page_count": 3,                    // 文档类必填，按页计价
    "file_ids": ["上一步返回的 fileId"],
    "print_params": { "paperSize": "A4", "colorMode": "black_white", "sides": "single", "copies": 1 },
    "recipient_name": "测试用户", "recipient_phone": "13800138000",
    "recipient_address": "北京市海淀区", "recipient_province": "北京市",
    "recipient_city": "北京市", "recipient_district": "海淀区"
  }'

# 订单创建后为 pending_payment，调用支付（mock 模式直接成功）：   
curl -X POST http://localhost:3000/api/v1/payments \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"order_id": "orderId", "openid": "openid"}'

⚡ 支付成功后，30 秒内系统将按「距离 + 接单率 + 商户报价」智能评分自动分配至最优门店；也可由管理员调用 POST /orders/:id/assign 手动指定门店（需 admin 权限）。

端点速查

核心接口一览

方法	路径	说明	鉴权
POST	/auth/wx-login	登录换 JWT（mock / 微信 code 双模式）	公开
POST	/auth/switch-role	切换门店/代理身份，签发新 token	JWT
POST	/files/upload	单文件直传，返回 fileId 与下载 URL	JWT
POST	/orders/price-preview	价格预览（不下单）	JWT
POST	/orders	创建订单	JWT
POST	/payments	创建支付单并完成支付	JWT
GET	/stats/platform-overview	平台运营概览聚合数据	公开
GET	/health	健康检查（DB/Redis 连接明细）	公开
POST	/orders/:id/accept	商户接单（assigned → accepted）	商户 JWT
POST	/terminal/orders/:id/status	打印状态回传（PRINTING / PRINTED 等）	商户 JWT

订单状态机

全生命周期流转

pending_payment → paid → assigned → accepted → printing → printed
     ↑(拒单退回)                              ↓
   assigned ← (重新分配)              waiting_pickup → picked_up
                                          → in_transit → delivering → completed

旁路分支：
  pending_payment → cancelled            （取消）
  *                → refunding → refunded（退款）
  printing         → abnormal → paid     （异常 → 重处理）

所有状态变更基于乐观锁（请求需携带当前 version），非法流转将被状态机拒绝并返回 ORDER_STATUS_INVALID。

📘 更多能力（分片上传、优惠券、商城、电商对接、结算提现等）请查阅 Swagger 在线文档；平台实时运行指标见首页「实时数据」区块。