xinadmin/xin-procurement-weapp

Fork 0

Files

T

xinadmin c613b520a9 init

2026-08-06 15:24:03 +08:00

17 KiB

Raw Blame History

订货采购系统 · 小程序端 API 文档

版本：V1.0　更新日期：2026-08-06 适用：微信小程序门店端 / 供应商端；接口由后端 app/Http/Controllers/Mini/ 提供（Laravel 12 + Sanctum）。

1. 通用说明

1.1 基础信息

项目	说明
Base URL	`http://localhost:8000`（生产域名待定，通常为 HTTPS）
数据格式	JSON（请求/响应均 `Content-Type: application/json`）
金额字段	后端统一 `decimal` 字符串返回（如 `"13.00"`），下单/购物车金额一律服务端重算，前端传的金额字段会被忽略

1.2 认证方式

除「登录」接口外，全部接口需携带 Authorization: Bearer <token>（登录接口返回的 token，Sanctum plainTextToken）。

Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

token 附带 abilities: ["mini"] 仅作来源标记；后端按 users guard 解析用户。

1.3 统一响应格式

成功：

{ "success": true, "data": { ... } }

成功带提示：

{ "success": true, "data": { ... }, "msg": "下单成功" }

失败（业务错误/验证错误均返回 HTTP 200，success=false）：

{ "success": false, "msg": "尚未绑定门店，请联系客服处理", "showType": 1 }

分页数据统一结构（data 字段内）：

{
  "success": true,
  "data": {
    "data": [ ... ],
    "total": 35,
    "pageSize": 10,
    "current": 1
  }
}

1.4 角色前置校验

接口域	前置要求	未满足时提示
商品/购物车/订单/对账单/门店设置	用户 `type=门店(1)` 且已绑定正常门店	「尚未绑定门店，请联系客服处理」
供应商采购单	用户 `type=供应商(2)` 且已绑定正常供应商	「尚未绑定供应商，请联系客服处理」
商品价格展示	门店已设置客户等级（`store.level_id > 0`）	「门店未设置客户等级，无法展示价格，请联系客服」

登录后未绑定身份的用户 type=0（待绑定）：可通过绑定手机号自动匹配门店/供应商，或由后台人工绑定。

1.5 价格体系

商品价格按「门店客户等级」展示，同一商品不同等级价格不同
等级价格支持两种计价类型：
- 固定价（price_type=0）：直接存储实际单价
- 成本百分比（price_type=1）：实际价 = 成本价 × (100 + 上浮百分点) / 100
小程序端接口返回的 price 均为换算后的实际价；成本价为商业敏感数据，不会下发到小程序端

2. 认证

2.1 微信登录（自动注册）

POST /mini/auth/login

用 wx.login() 获取的 code 换 openid，已注册用户直接登录，新用户自动注册并返回 token。

请求参数：

参数	类型	必填	说明
code	string	是	`wx.login` 的临时凭证

响应（data）：

字段	类型	说明
token	string	Bearer 令牌（后续请求头携带）
user.id	int	用户ID
user.nickname	string	昵称
user.avatar	string	头像
user.phone	string	手机号（未绑定为空）
user.type	int	0 待绑定 / 1 门店 / 2 供应商
user.store	object\|null	绑定门店信息（含 `level`：客户等级 `{id,name}`）
user.supplier	object\|null	绑定供应商信息

响应示例：

{
  "success": true,
  "data": {
    "token": "1|abc...",
    "user": {
      "id": 5, "nickname": "微信用户1", "avatar": "", "phone": "",
      "type": 1,
      "store": { "id": 2, "name": "菜市场A店", "level": { "id": 1, "name": "一级客户" } },
      "supplier": null
    }
  },
  "msg": "登录成功"
}

错误：code 缺失 → 「缺少登录凭证 code」；账号被停用 → 「账号已被停用，请联系客服」。

2.2 绑定手机号

POST /mini/auth/phone（需登录）

用微信手机号授权码换手机号，并按手机号自动匹配门店/供应商（均未命中则保持待绑定，由后台处理）。

请求参数：

参数	类型	必填	说明
phoneCode	string	是	`wx.getPhoneNumber` 授权得到的 code

响应（data）：user 结构同 2.1。

2.3 当前用户信息

GET /mini/auth/info（需登录）

响应（data）：user 结构同 2.1（含门店客户等级——小程序全局价格体系的依据）。

3. 商品

3.1 商品分类树

GET /mini/product/categories（需登录 + 门店）

返回分类树，仅包含有上架商品的分类及其全部祖先（保证树结构完整）。

响应（data）：分类树数组，节点字段：

字段	类型	说明
id	int	分类ID
parent_id	int	父级分类ID（0 为顶级）
name	string	分类名称
children	array	子分类（递归）

3.2 商品列表

GET /mini/product/list?category_id=&keyword=&page=&pageSize=（需登录 + 门店 + 客户等级）

请求参数：

参数	类型	必填	默认	说明
category_id	int	否	-	分类ID过滤
keyword	string	否	-	搜索品名/规格（模糊）
page	int	否	1	页码
pageSize	int	否	10	每页条数

响应（data 为分页结构），每项字段：

字段	类型	说明
id	int	商品ID
category_id	int	分类ID
supplier_id	int	默认供应商ID
name	string	品名
spec	string	规格/包规
unit	string	计价单位
content	string	商品图文详情（HTML）
price	string\|null	当前门店等级的实际销售价（未设等级价为 null）
images_arr	array	商品图片数组（`{id, file_url, ...}`）
sort / shelf_life / stock / status	-	排序 / 保质期 / 库存 / 状态（仅返回上架商品）

注意：只返回上架商品；cost_price、计价类型、上浮百分点等成本信息不会下发。

4. 购物车

购物车为下单前的编辑容器，同商品重复加购自动合并数量；提交订单复用「5.1 下单」接口。

4.1 加购

POST /mini/cart（需登录 + 门店 + 客户等级）

请求参数：

参数	类型	必填	说明
product_id	int	是	商品ID（须上架且已设本等级价格）
quantity	number	是	数量（>0，最多 99999999.99）

响应（data）：

{ "id": 12, "quantity": "2.50" }

提示：已加入购物车。错误：商品未设本等级价格 → 「商品「xx」未设置您所在等级的价格，无法加购」；超上限 → 「该商品在购物车中的数量已达上限」。

4.2 购物车列表

GET /mini/cart（需登录 + 门店）

响应（data）：

字段	类型	说明
items	array	购物车项（倒序）
total_count	int	总项数
total_quantity	string	可购项总数量
total_amount	string	可购项总金额

items 每项：

字段	类型	说明
id	int	购物车项ID
product_id	int	商品ID
name / spec / unit	string	商品快照
image	string	商品首图 URL
price	string\|null	当前等级实际价（商品下架或未设等级价为 null）
quantity	string	数量
amount	string\|null	金额 = price × quantity（不可购为 null）
status	int	1 可购 / 0 商品下架、缺失或未设等级价

4.3 修改数量

PUT /mini/cart/{id}（需登录）

请求参数：quantity（number，必填，>0）。

响应：{ id, quantity }，提示「已修改数量」。

4.4 删除单项

DELETE /mini/cart/{id}（需登录）

响应：success=true，提示「已删除」；不存在 → 「购物车项不存在」。

4.5 清空购物车

DELETE /mini/cart（需登录）

仅清空当前用户；响应：success=true，提示「购物车已清空」。

5. 门店订单

5.1 下单

POST /mini/order（需登录 + 门店 + 客户等级）

请求参数：

参数	类型	必填	说明
items	array	是	订单明细（至少 1 行）
items[].product_id	int	是	商品ID（须上架）
items[].quantity	number	是	数量（>0）
remark	string	否	订单备注（≤255 字符）

金额不接受前端传入：服务端按商品当前等级实际价逐行快照并重算 amount 与 total_amount。

响应（data）：

{ "id": 23, "order_no": "SO202608060001", "total_amount": "39.00" }

提示：「下单成功」。错误示例：存在已下架商品 → 「存在已下架或不存在的商品，请刷新后重试」；未设等级价 → 「商品「xx」未设置您所在等级的价格，无法下单」。

5.2 历史订单

GET /mini/order?status=&page=&pageSize=（需登录 + 门店，强制本店隔离）

请求参数：

参数	类型	必填	默认	说明
status	int	否	-	0 待汇总 / 1 已汇总 / 2 配送中 / 3 已完成 / 9 已取消
page / pageSize	-	否	1 / 10	分页

响应（data 分页结构），订单字段：

字段	类型	说明
id	int	订单ID
order_no	string	单号（SO + 日期 + 序列）
order_date	string	订货日期（Y-m-d）
total_quantity / total_amount	string	总数量 / 总金额
status	int	状态（见上）
remark	string	备注

5.3 周期汇总

GET /mini/order/summary?period=day|week|month（需登录 + 门店）

请求参数：period（day/week/month，默认 month）。

响应（data）：

{
  "period": "month",
  "groups": [
    { "period_label": "2026-07", "total_amount": "1280.50", "total_quantity": "86.00", "order_count": 12 }
  ]
}

period_label 格式：day=Y-m-d、week=Y-W+周数、month=Y-m；不含已取消订单；最多返回 50 组。

5.4 订单详情

GET /mini/order/{id}（需登录 + 门店，校验本店归属）

响应（data）：订单对象 + items 数组（明细字段见下表）。

明细字段：

字段	类型	说明
id / order_id	int	明细ID / 订单ID
product_id / product_name / product_spec	-	商品快照
price	string	下单时等级实际价快照
quantity / weight	string	数量 / 称重（默认 0）
amount	string	金额 = price × quantity
remark	string	行备注

5.5 取消订单

PUT /mini/order/{id}/cancel（需登录 + 门店）

仅「待汇总(0)」可取消；响应提示「订单已取消」；非待汇总 → 「仅待汇总的订单可以取消」。

6. 对账单（门店自助）

6.1 对账单列表

GET /mini/statement?page=&pageSize=（需登录 + 门店，仅本店）

响应（data 分页结构），对账单字段：

字段	类型	说明
id	int	对账单ID
statement_no	string	单号（ST + 日期 + 序列）
period_start / period_end	string	对账周期
total_amount	string	总金额
payment_cycle_days	int	生成时快照的回款周期
settlement_date	string\|null	应结算日期 = 周期结束 + 回款周期天
status	int	0 待对账 / 1 已对账 / 2 已结算
reconciled_at / settled_at	string\|null	对账 / 结算时间
remark	string	备注

6.2 生成对账单

POST /mini/statement/generate（需登录 + 门店）

请求参数：

参数	类型	必填	说明
period_start	string	是	周期开始（Y-m-d）
period_end	string	是	周期结束（Y-m-d，不早于开始）

响应（data）：{ id, statement_no, total_amount, settlement_date }，提示「对账单已生成」。

快照当前回款周期计算结算日期。业务约束：周期内本店无订单 → 「周期内本店无订单数据，无法生成对账单」；周期内订单均已生成过对账单 → 「周期内的订单明细均已生成过对账单」。

6.3 对账单详情

GET /mini/statement/{id}（需登录 + 门店，校验归属）

响应（data）：对账单对象 + items 数组，明细字段：

字段	类型	说明
order_id / order_item_id	int	源订单 / 源明细ID
product_id / product_name	-	商品快照
price	string	单价
quantity / weight / amount	string	数量 / 称重 / 金额
is_reconciled	int	0 未对账 / 1 已对账
store_remark	string	门店备注

6.4 导出对账单

GET /mini/statement/{id}/export?format=xlsx|pdf（需登录 + 门店，校验归属）

format 默认 xlsx（支持 xlsx / pdf）
返回文件流（附件下载，含中文文件名），非 JSON

7. 门店设置

7.1 修改回款周期

PUT /mini/store/paymentCycle（需登录 + 门店）

请求参数：

参数	类型	必填	说明
payment_cycle_days	int	是	回款周期天数（≥0，无上限；0 = 当天结算）

响应（data）：{ "payment_cycle_days": 1 }，提示「回款周期已更新」。

该值影响后续生成对账单的 settlement_date（周期结束 + 回款周期天）。

8. 通知

8.1 通知列表

GET /mini/notice?page=&pageSize=（需登录）

返回本人通知 + 全员广播（本人已读的广播自动隐藏）。响应（data 分页结构 + 附加字段）：

字段	类型	说明
unread_count	int	未读总数
分页内字段	-	标准分页结构

通知字段：

字段	类型	说明
id	int	通知ID
type	string	`order` 订单 / `price` 价格变更 / `system` 系统
title / content	string	标题 / 内容
data	object	附加数据（价格变更通知含 `product_ids`、`level_ids`）
is_read	int	0 未读 / 1 已读
read_at	string\|null	已读时间

8.2 标记已读

PUT /mini/notice/{id}/read（需登录）

个人通知：直接标记已读
全员广播：复制一条本人专属已读记录（原广播对他人仍为未读）

响应：success=true；通知不存在 → 「通知不存在」。

9. 供应商端

9.1 收到的采购单

GET /mini/supplier/purchases?page=&pageSize=（需登录 + 供应商）

返回含本供应商已发送明细（is_sent=1）的采购单（去重，按日期倒序）。

响应（data 分页结构），采购单字段：

字段	类型	说明
id	int	采购单ID
purchase_no	string	单号（PO + 日期 + 序列）
purchase_date	string	采购日期
status	int	0 待发送 / 1 部分发送 / 2 全部发送 / 3 已完成
total_quantity / estimate_amount / actual_amount	string	总数量 / 估算金额 / 实际金额
remark	string	备注

9.2 采购单明细

GET /mini/supplier/purchases/{id}（需登录 + 供应商）

仅返回本供应商且已发送的明细行。响应（data）：

{
  "id": 3, "purchase_no": "PO202608060001", "purchase_date": "2026-08-06", "remark": "",
  "items": [
    { "id": 11, "product_id": 2, "product_name": "大白菜", "product_spec": "10斤/箱",
      "price": "4.00", "quantity": "10.00", "weight": "0.000", "amount": "40.00",
      "sort": 1, "is_sent": 1, "sent_at": "...", "supplier_confirmed_at": null }
  ]
}

无本供应商明细 → 「该采购单无贵司的采购明细」。

9.3 确认接单

PUT /mini/supplier/purchases/{id}/confirm（需登录 + 供应商）

批量记录本供应商全部已发送明细的 supplier_confirmed_at（幂等，已确认的跳过）。

响应（data）：{ "confirmed": 2 }（本次新确认条数），提示「已确认接单」。

10. 状态字典汇总

枚举	值	含义
用户类型 user.type	0 / 1 / 2	待绑定 / 门店 / 供应商
门店订单 status	0 / 1 / 2 / 3 / 9	待汇总 / 已汇总 / 配送中 / 已完成 / 已取消
采购单 status	0 / 1 / 2 / 3	待发送 / 部分发送 / 全部发送 / 已完成
采购明细 is_sent	0 / 1	未发送 / 已发送
对账单 status	0 / 1 / 2	待对账 / 已对账 / 已结算
对账明细 is_reconciled	0 / 1	未对账 / 已对账
通知 type	order / price / system	订单 / 价格变更 / 系统
通知 is_read	0 / 1	未读 / 已读
商品 status	0 / 1	下架 / 上架
门店/供应商 status	0 / 1	停用 / 正常

11. 常见错误提示

提示语	触发场景
尚未绑定门店，请联系客服处理	门店端接口但用户未绑定门店
尚未绑定供应商，请联系客服处理	供应商端接口但用户未绑定供应商
门店未设置客户等级，无法展示价格，请联系客服	门店 `level_id=0`（商品/购物车/下单）
商品「xx」未设置您所在等级的价格，无法下单	下单商品缺本等级价格
存在已下架或不存在的商品，请刷新后重试	下单商品已下架
账号不存在或已被停用	token 用户被停用
账号已被停用，请联系客服	登录时账号被停用

17 KiB Raw Blame History Unescape Escape

订货采购系统 · 小程序端 API 文档

1. 通用说明

1.1 基础信息

1.2 认证方式

1.3 统一响应格式

1.4 角色前置校验

1.5 价格体系

2. 认证

2.1 微信登录（自动注册）

2.2 绑定手机号

2.3 当前用户信息

3. 商品

3.1 商品分类树

3.2 商品列表

4. 购物车

4.1 加购

4.2 购物车列表

4.3 修改数量

4.4 删除单项

4.5 清空购物车

5. 门店订单

5.1 下单

5.2 历史订单

5.3 周期汇总

5.4 订单详情

5.5 取消订单

6. 对账单（门店自助）

6.1 对账单列表

6.2 生成对账单

6.3 对账单详情

6.4 导出对账单

7. 门店设置

7.1 修改回款周期

8. 通知

8.1 通知列表

8.2 标记已读

9. 供应商端

9.1 收到的采购单

9.2 采购单明细

9.3 确认接单

10. 状态字典汇总

11. 常见错误提示

17 KiB

Raw Blame History