dingdanquanliucheng/开发细节/02-API细化设计.md

API 细化设计

1. 通用规范

1.1 基础约定

项	约定
Base URL	/api
协议	HTTP/HTTPS + JSON
鉴权	Authorization: Bearer <token>
时间格式	YYYY-MM-DD HH:mm:ss
日期格式	YYYY-MM-DD
金额格式	number，保留 2 位小数
数量格式	number，最多 4 位小数

1.2 通用响应

{
  "code": 0,
  "message": "success",
  "data": {}
}

1.3 分页响应

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page_no": 1,
    "page_size": 20,
    "list": []
  }
}

1.4 错误码

code	含义	典型场景
0	成功	正常返回
40001	参数错误	必填缺失、格式错误、金额非法
40002	未登录或登录失效	token 缺失、过期、无效
40003	无权限	角色无权限、越权访问他人数据
40004	资源不存在	ID 不存在或已逻辑删除
40005	状态不允许当前操作	重复提交、非法状态流转
40006	数据重复	客户姓名 + 手机号重复、编号重复
40007	业务规则校验失败	利润计算异常、欠款规则不满足
40008	文件上传失败	OSS 上传失败
40009	第三方接口调用失败	阿里云 OCR/模型失败、快递 100 失败
50000	系统异常	未预期异常

2. 枚举定义

2.1 角色类型

值	说明
salesman	业务员
manager	管理层
driver	司机
admin	管理员

2.2 订单状态

值	说明
draft	草稿
pending_approve	待审核
approved	已通过，待生成/确认下发工厂文本
rejected	已退回
pending_factory	待下发工厂或已确认下发工厂待处理
pending_driver	待司机接单
accepted	已接单
picked_up	已揽货
delivered	已送达
production	生产中
shipped	已发货
completed	已完成
settled	已结算
cancel_pending	取消申请中
canceled	已取消

2.3 任务状态

值	说明
pending	待接单
accepted	已接单
picked_up	已揽货
delivered	已送达
canceled	已取消

2.4 审批结果

值	说明
pass	通过
reject	退回
refuse	拒绝

2.5 欠款生成模式

值	说明
shipped	订单进入已发货时生成欠款
delivered	订单进入已送达时生成欠款，默认值

2.6 提醒状态

值	说明
pending	待发送
sent	已发送
read	已读
canceled	已取消

3. 认证接口

3.1 登录

项	内容
Method	POST
Path	/api/auth/login
Auth	否

Request

{
  "username": "sales01",
  "password": "123456",
  "role_type": "salesman"
}

Response

{
  "user_id": 1,
  "username": "sales01",
  "real_name": "张三",
  "mobile": "13800000000",
  "role_id": 2,
  "role_name": "业务员",
  "role_code": "salesman",
  "token": "jwt-token",
  "menus": [],
  "permissions": []
}

错误场景

场景	code
账号或密码为空	40001
账号不存在或密码错误	40002
账号停用	40003
登录角色与账号角色不匹配	40003

3.2 当前用户

Method	Path	Auth
GET	/api/auth/me	是

Response

{
  "user_id": 1,
  "username": "sales01",
  "real_name": "张三",
  "mobile": "13800000000",
  "role_id": 2,
  "role_name": "业务员",
  "role_code": "salesman",
  "menus": [],
  "permissions": []
}

3.3 退出登录

Method	Path	Auth
POST	/api/auth/logout	是

Response

{
  "success": true
}

4. 订单接口

4.1 创建订单

Method	Path	Auth	权限
POST	/api/orders	是	业务员、管理员

Request

{
  "customer_name": "李四",
  "customer_mobile": "13900000000",
  "customer_address": "江苏省xx市xx路",
  "order_source": "线下",
  "delivery_type": "物流",
  "factory_id": 1001,
  "commission_amount": 50.00,
  "rebate_total": 5.00,
  "freight_total": 10.00,
  "tax_total": 3.00,
  "other_fee_total": 2.00,
  "remark": "备注",
  "items": [
    {
      "product_id": 2001,
      "product_name": "产品A",
      "specification": "10kg",
      "unit": "袋",
      "quantity": 1,
      "sale_price": 100.00,
      "cost_price": 60.00,
      "rebate_amount": 5.00,
      "freight_amount": 10.00,
      "tax_amount": 3.00,
      "other_fee_amount": 2.00,
      "remark": "明细备注"
    }
  ]
}

Response

{
  "order_id": 9001,
  "order_no": "SO202605140001",
  "order_status": "draft",
  "sale_price_total": 100.00,
  "cost_price_total": 60.00,
  "profit_total": 20.00,
  "profit_rate": 20.00,
  "commission_amount": 50.00
}

规则

规则	说明
新客户同步	姓名 + 手机号不存在时自动创建客户
默认状态	draft
利润公式	销售额 - 成本 - 回扣 - 运费 - 税费 - 其他费用
固定提成	只保存，不参与利润公式

错误场景

场景	code
客户姓名或手机号为空	40001
明细为空	40001
数量小于等于 0	40001
金额小于 0	40001
工厂不存在	40004

4.2 提交审核

Method	Path	Auth	权限
POST	/api/orders/{order_id}/submit	是	订单创建人、管理员

Response

{
  "order_id": 9001,
  "order_status": "pending_approve",
  "submitted_at": "2026-05-14 10:00:00"
}

错误场景

场景	code
订单不存在	40004
非本人订单	40003
当前状态不是 draft/rejected	40005
明细不完整	40007

4.3 订单详情

Method	Path	Auth
GET	/api/orders/{order_id}	是

Response

{
  "order_id": 9001,
  "order_no": "SO202605140001",
  "customer_id": 3001,
  "customer_name": "李四",
  "customer_mobile": "13900000000",
  "customer_address": "江苏省xx市xx路",
  "salesman_id": 1,
  "salesman_name": "张三",
  "order_source": "线下",
  "order_status": "approved",
  "delivery_type": "物流",
  "factory_id": 1001,
  "factory_name": "工厂A",
  "sale_price_total": 100.00,
  "cost_price_total": 60.00,
  "rebate_total": 5.00,
  "freight_total": 10.00,
  "tax_total": 3.00,
  "other_fee_total": 2.00,
  "profit_total": 20.00,
  "profit_rate": 20.00,
  "commission_amount": 50.00,
  "items": [],
  "approve_logs": [],
  "logistics_info": {
    "task": {},
    "trace_list": []
  },
  "attachments": [],
  "remark": "备注"
}

字段权限

角色	字段控制
业务员	不返回成本、回扣、利润、利润率等敏感字段，除非明确授权
管理层	返回完整财务字段
司机	不使用此接口查看订单详情，只通过司机任务详情
管理员	返回完整字段

4.4 订单列表

Method	Path	Auth
GET	/api/orders	是

Query

字段	类型	说明
order_status	string	订单状态
customer_name	string	客户姓名
customer_mobile	string	客户手机号
salesman_id	number	业务员 ID
factory_id	number	工厂 ID
order_source	string	订单来源
start_time	string	开始时间
end_time	string	结束时间
page_no	number	页码
page_size	number	每页条数

List Item

{
  "order_id": 9001,
  "order_no": "SO202605140001",
  "customer_name": "李四",
  "customer_mobile": "13900000000",
  "salesman_name": "张三",
  "order_status": "approved",
  "sale_price_total": 100.00,
  "profit_total": 20.00,
  "commission_amount": 50.00,
  "created_at": "2026-05-14 10:00:00"
}

4.5 取消订单

Method	Path	Auth
POST	/api/orders/{order_id}/cancel	是

Request

{
  "cancel_reason": "客户取消",
  "cancel_opinion": "客户临时取消订单"
}

Response

{
  "order_id": 9001,
  "order_status": "cancel_pending",
  "previous_status": "approved",
  "canceled_at": null
}

状态规则

当前状态	结果
draft	直接 canceled
pending_approve	直接 canceled
approved 及后续履约状态	cancel_pending
canceled/settled	返回 40005

4.6 状态变更

Method	Path	Auth	权限
POST	/api/orders/{order_id}/status	是	管理层、管理员、系统内部

Request

{
  "target_status": "shipped",
  "remark": "工厂已发货"
}

Response

{
  "order_id": 9001,
  "order_status": "shipped"
}

4.7 生成下发工厂文本

Method	Path	Auth
POST	/api/orders/{order_id}/supplier-text	是

Request

{
  "supplier_id": 1001
}

Response

{
  "order_id": 9001,
  "supplier_id": 1001,
  "template_type": "default",
  "text_content": "下发文本内容"
}

4.8 确认下发工厂

Method	Path	Auth
POST	/api/orders/{order_id}/supplier-text/confirm	是

Request

{
  "supplier_id": 1001,
  "text_content": "实际确认下发文本",
  "remark": "已复制给工厂"
}

Response

{
  "order_id": 9001,
  "order_status": "pending_factory",
  "confirmed_at": "2026-05-14 11:00:00"
}

错误场景

场景	code
订单不是 approved	40005
工厂不存在	40004

5. 审批接口

5.1 最终审批

Method	Path	Auth	权限
POST	/api/orders/{order_id}/approve	是	管理层

Request

{
  "approve_result": "pass",
  "approve_opinion": "同意"
}

Response

{
  "order_id": 9001,
  "order_status": "approved",
  "profit_total": 20.00,
  "profit_rate": 20.00,
  "approve_time": "2026-05-14 10:30:00"
}

规则

approve_result	结果
pass	状态变为 approved
reject	状态变为 rejected

5.2 取消审批

Method	Path	Auth	权限
POST	/api/orders/{order_id}/cancel-approve	是	管理层

Request

{
  "approve_result": "pass",
  "approve_opinion": "同意取消"
}

Response

{
  "order_id": 9001,
  "order_status": "canceled"
}

规则

approve_result	结果
pass	canceled
refuse	回到取消前状态

6. 客户接口

6.1 新增客户

Method	Path	Auth
POST	/api/customers	是

Request

{
  "customer_name": "李四",
  "mobile": "13900000000",
  "address": "地址",
  "settlement_type": "monthly",
  "settlement_days": 30,
  "settlement_start_type": "delivered",
  "customer_type": "普通客户",
  "salesman_id": 1,
  "credit_limit": 10000.00,
  "remark": "备注"
}

Response

{
  "customer_id": 3001,
  "customer_name": "李四",
  "mobile": "13900000000"
}

6.2 客户列表

Method	Path	Auth
GET	/api/customers	是

Query

字段	类型
customer_name	string
mobile	string
customer_type	string
settlement_type	string
salesman_id	number
page_no	number
page_size	number

6.3 客户详情

Method	Path	Auth
GET	/api/customers/{customer_id}	是

6.4 客户导入

Method	Path	Auth
POST	/api/customers/import	是

Request

{
  "file_url": "https://oss.example.com/import/customer.xlsx",
  "import_mode": "skip_duplicate"
}

Response

{
  "total_count": 100,
  "success_count": 90,
  "duplicate_count": 5,
  "fail_count": 5,
  "fail_list": [
    {
      "row_no": 12,
      "reason": "手机号为空"
    }
  ]
}

7. 产品与分类接口

7.1 产品分类列表

Method	Path	Auth
GET	/api/product-categories	是

Query

字段	类型
category_name	string
status	number
page_no	number
page_size	number

7.2 新增产品分类

Method	Path	Auth
POST	/api/product-categories	是

Request

{
  "category_name": "工业品",
  "category_code": "industry",
  "sort_no": 1,
  "status": 1,
  "remark": "备注"
}

7.3 更新产品分类

Method	Path	Auth
PUT	/api/product-categories/{category_id}	是

7.4 新增产品

Method	Path	Auth
POST	/api/products	是

Request

{
  "product_name": "产品A",
  "specification": "10kg",
  "unit": "袋",
  "category_id": 1,
  "category": "工业品",
  "cost_price": 60.00,
  "sale_price": 100.00,
  "status": 1,
  "remark": "备注"
}

7.5 产品列表

Method	Path	Auth
GET	/api/products	是

7.6 产品详情

Method	Path	Auth
GET	/api/products/{product_id}	是

8. 工厂/供应商接口

8.1 新增工厂/供应商

Method	Path	Auth
POST	/api/suppliers	是

Request

{
  "supplier_name": "工厂A",
  "supplier_type": "factory",
  "contact_name": "王五",
  "contact_mobile": "13800000001",
  "address": "地址",
  "template_type": "default",
  "status": 1,
  "remark": "备注"
}

8.2 工厂/供应商列表

Method	Path	Auth
GET	/api/suppliers	是

9. 司机任务接口

9.1 管理端创建司机任务

Method	Path	Auth	权限
POST	/api/logistics/tasks	是	管理层、管理员

Request

{
  "order_id": 9001,
  "driver_id": 10,
  "pickup_address": "取货地址",
  "delivery_address": "送达地址",
  "pickup_content": "产品A 1袋",
  "quantity": 1,
  "factory_id": 1001,
  "remark": "备注"
}

Response

{
  "task_id": 5001,
  "task_no": "LT202605140001",
  "status": "pending"
}

9.2 管理端任务列表

Method	Path	Auth
GET	/api/logistics/tasks	是

9.3 司机任务列表

Method	Path	Auth	权限
GET	/api/driver/tasks	是	司机

9.4 司机任务详情

Method	Path	Auth	权限
GET	/api/driver/tasks/{task_id}	是	司机本人

Response

{
  "task_id": 5001,
  "order_id": 9001,
  "task_no": "LT202605140001",
  "status": "pending",
  "pickup_address": "取货地址",
  "delivery_address": "送达地址",
  "pickup_content": "产品A 1袋",
  "quantity": 1,
  "factory_id": 1001,
  "factory_name": "工厂A",
  "salesman_name": "张三"
}

9.5 接单

Method	Path	Auth
POST	/api/driver/tasks/{task_id}/accept	是

9.6 确认揽货

Method	Path	Auth
POST	/api/driver/tasks/{task_id}/pickup	是

Request

{
  "photo_files": [
    {
      "file_url": "https://oss.example.com/a.jpg",
      "file_name": "a.jpg"
    }
  ],
  "video_files": [],
  "remark": "已揽货"
}

9.7 确认送达

Method	Path	Auth
POST	/api/driver/tasks/{task_id}/deliver	是

10. 文件接口

10.1 获取 OSS 上传凭证

Method	Path	Auth
POST	/api/files/upload-token	是

Request

{
  "biz_type": "logistics_task",
  "biz_id": 5001,
  "file_name": "pickup.jpg",
  "file_type": "image/jpeg",
  "file_size": 102400
}

Response

{
  "upload_url": "https://oss-upload-url",
  "file_url": "https://oss-public-url/pickup.jpg",
  "headers": {},
  "expire_at": "2026-05-14 12:00:00"
}

10.2 保存附件记录

Method	Path	Auth
POST	/api/files/attachments	是

Request

{
  "biz_type": "logistics_task",
  "biz_id": 5001,
  "file_name": "pickup.jpg",
  "file_url": "https://oss.example.com/pickup.jpg",
  "file_type": "image/jpeg",
  "file_size": 102400
}

11. 物流与 AI 接口

11.1 物流轨迹查询

Method	Path	Auth
GET	/api/logistics/{order_id}/trace	是

11.2 新增物流节点

Method	Path	Auth
POST	/api/logistics/{order_id}/trace	是

Request

{
  "task_id": 5001,
  "node_time": "2026-05-14 12:00:00",
  "node_desc": "司机已揽货",
  "node_type": "picked_up",
  "source_platform": "manual"
}

11.3 AI 图片识别

Method	Path	Auth
POST	/api/ai/recognize	是

Request

{
  "image_url": "https://oss.example.com/ocr.jpg",
  "biz_type": "sales_order",
  "biz_id": 9001
}

Response

{
  "log_id": 7001,
  "raw_result": {},
  "confidence": 0.92,
  "suggested_result": {}
}

11.4 AI 结果修正

Method	Path	Auth
POST	/api/ai/recognize/{log_id}/correct	是

Request

{
  "corrected_result": {
    "customer_name": "李四",
    "tracking_no": "SF123"
  }
}

12. 提醒接口

12.1 提醒列表

Method	Path	Auth
GET	/api/reminders	是

Query

字段	类型
reminder_type	string
status	string
receiver_user_id	number
page_no	number
page_size	number

12.2 标记已读

Method	Path	Auth
POST	/api/reminders/{reminder_id}/read	是

12.3 欠款提醒检查

Method	Path	Auth
POST	/api/reminders/arrears/check	是

12.4 沉默客户提醒检查

Method	Path	Auth
POST	/api/reminders/inactive-customers/check	是

13. 报表接口

13.1 业绩统计

Method	Path	Auth
GET	/api/reports/performance	是

Query

字段	类型
stat_type	string
start_date	string
end_date	string
category_id	number

Response

{
  "stat_type": "month",
  "list": [
    {
      "stat_period": "2026-05",
      "order_count": 10,
      "order_amount": 10000.00,
      "category_amounts": [
        {
          "category_id": 1,
          "category_name": "工业品",
          "amount": 6000.00
        }
      ],
      "commission_amount": 500.00
    }
  ]
}

13.2 报表导出

Method	Path	Auth
GET	/api/reports/performance/export	是

14. 配置接口

14.1 配置查询

Method	Path	Auth
GET	/api/configs/{config_key}	是

14.2 配置更新

Method	Path	Auth
PUT	/api/configs/{config_key}	是

常用配置键

config_key	说明	示例
arrears_generate_mode	欠款生成模式	delivered
logistics_timeout_hours	物流超时小时数	48
inactive_customer_days	沉默客户周期	90
inactive_customer_amount_threshold	沉默客户金额阈值	1000
report_category_mapping	报表分类映射	JSON

15. 审计日志接口

15.1 审计日志列表

Method	Path	Auth
GET	/api/audit-logs	是

Query

字段	类型
biz_type	string
biz_id	number
operator_name	string
operate_type	string
start_time	string
end_time	string
page_no	number
page_size	number

16. 系统管理接口

以下接口为后台用户、角色、菜单和权限配置页面的一期必备接口。所有接口仅 admin 可调用，管理层如需部分授权，需要在角色权限里单独配置。

16.1 用户列表

Method	Path	Auth	权限
GET	/api/system/users	是	管理员

Query

字段	类型	必填	说明
username	string	否	账号模糊查询
real_name	string	否	姓名模糊查询
mobile	string	否	手机号模糊查询
role_id	number	否	角色 ID
status	number	否	1 启用，0 停用
page_no	number	否	默认 1
page_size	number	否	默认 20

Response

{
  "total": 1,
  "page_no": 1,
  "page_size": 20,
  "list": [
    {
      "user_id": 1,
      "username": "sales01",
      "real_name": "张三",
      "mobile": "13800000000",
      "role_id": 2,
      "role_name": "业务员",
      "role_code": "salesman",
      "status": 1,
      "created_at": "2026-05-14 10:00:00",
      "updated_at": "2026-05-14 10:00:00"
    }
  ]
}

错误场景

场景	code
非管理员访问	40003
分页参数非法	40001

16.2 新增用户

Method	Path	Auth	权限
POST	/api/system/users	是	管理员

Request

{
  "username": "driver01",
  "password": "Init@123456",
  "real_name": "王司机",
  "mobile": "13700000000",
  "role_id": 3,
  "status": 1
}

Response

{
  "user_id": 10,
  "username": "driver01",
  "real_name": "王司机",
  "mobile": "13700000000",
  "role_id": 3,
  "status": 1
}

规则

规则	说明
账号唯一	username 不允许重复
密码存储	后端只保存加密后的密码摘要
角色有效	role_id 必须存在且启用
审计	成功新增后写入 audit_log

错误场景

场景	code
必填字段缺失	40001
账号重复	40006
角色不存在或停用	40004

16.3 更新用户

Method	Path	Auth	权限
PUT	/api/system/users/{user_id}	是	管理员

Request

{
  "real_name": "王司机",
  "mobile": "13700000001",
  "role_id": 3,
  "status": 1
}

Response

{
  "user_id": 10,
  "updated": true
}

错误场景

场景	code
用户不存在	40004
角色不存在或停用	40004
停用当前登录管理员本人	40007

16.4 重置密码

Method	Path	Auth	权限
POST	/api/system/users/{user_id}/reset-password	是	管理员

Request

{
  "new_password": "New@123456"
}

Response

{
  "user_id": 10,
  "reset": true
}

错误场景

场景	code
用户不存在	40004
密码强度不符合规则	40001

16.5 角色列表

Method	Path	Auth	权限
GET	/api/system/roles	是	管理员

Query

字段	类型	必填	说明
role_name	string	否	角色名称
role_code	string	否	角色编码
status	number	否	1 启用，0 停用
page_no	number	否	默认 1
page_size	number	否	默认 20

Response

{
  "total": 4,
  "page_no": 1,
  "page_size": 20,
  "list": [
    {
      "role_id": 1,
      "role_name": "管理员",
      "role_code": "admin",
      "status": 1,
      "remark": "系统管理",
      "created_at": "2026-05-14 10:00:00"
    }
  ]
}

16.6 新增角色

Method	Path	Auth	权限
POST	/api/system/roles	是	管理员

Request

{
  "role_name": "业务员",
  "role_code": "salesman",
  "status": 1,
  "remark": "业务录单和本人订单查询"
}

Response

{
  "role_id": 2,
  "role_name": "业务员",
  "role_code": "salesman",
  "status": 1
}

错误场景

场景	code
角色编码重复	40006
必填字段缺失	40001

16.7 更新角色

Method	Path	Auth	权限
PUT	/api/system/roles/{role_id}	是	管理员

Request

{
  "role_name": "业务员",
  "status": 1,
  "remark": "业务录单和本人订单查询"
}

Response

{
  "role_id": 2,
  "updated": true
}

错误场景

场景	code
角色不存在	40004
停用内置管理员角色	40007
角色下仍有启用用户时停用	40007

16.8 菜单树

Method	Path	Auth	权限
GET	/api/system/menus	是	管理员

Query

字段	类型	必填	说明
status	number	否	1 启用，0 停用
menu_type	string	否	catalog/page/button

Response

[
  {
    "menu_id": 1,
    "parent_id": 0,
    "menu_name": "订单管理",
    "menu_path": "/orders",
    "menu_type": "page",
    "permission_code": "order:list",
    "icon": "order",
    "sort_no": 10,
    "status": 1,
    "children": []
  }
]

16.9 新增菜单

Method	Path	Auth	权限
POST	/api/system/menus	是	管理员

Request

{
  "parent_id": 0,
  "menu_name": "订单管理",
  "menu_path": "/orders",
  "menu_type": "page",
  "permission_code": "order:list",
  "icon": "order",
  "sort_no": 10,
  "status": 1
}

Response

{
  "menu_id": 20,
  "menu_name": "订单管理",
  "permission_code": "order:list",
  "status": 1
}

错误场景

场景	code
父级菜单不存在	40004
权限编码重复	40006
菜单类型非法	40001

16.10 更新菜单

Method	Path	Auth	权限
PUT	/api/system/menus/{menu_id}	是	管理员

Request

{
  "parent_id": 0,
  "menu_name": "订单管理",
  "menu_path": "/orders",
  "menu_type": "page",
  "permission_code": "order:list",
  "icon": "order",
  "sort_no": 10,
  "status": 1
}

Response

{
  "menu_id": 20,
  "updated": true
}

错误场景

场景	code
菜单不存在	40004
将菜单父级设置为自身或子级	40007
权限编码重复	40006

16.11 角色授权

Method	Path	Auth	权限
PUT	/api/system/roles/{role_id}/menus	是	管理员

Request

{
  "menu_ids": [1, 2, 3, 20],
  "permission_codes": ["order:list", "order:create", "order:submit"]
}

Response

{
  "role_id": 2,
  "menu_count": 4,
  "permission_count": 3,
  "updated": true
}

规则

规则	说明
覆盖保存	每次提交以本次 menu_ids 和 permission_codes 为准
登录刷新	权限变更后，用户下一次登录或刷新 /api/auth/me 生效
审计	记录角色授权前后差异

错误场景

场景	code
角色不存在	40004
菜单不存在或停用	40004
给内置角色移除必要基础权限	40007