foodie-server/specs/002-table-qrcode/contracts/api.md

API Contracts: Table QR Code

Base URL: /table-qrcode

Authentication: 所有接口需要 @Anonymous + @Auth，通过 @RequestHeader String token 进行 JWT 认证。

---

1. 创建餐桌码

POST /table-qrcode/add

Request

{
  "tableNo": "A01",
  "type": 0,
  "storeId": 100,
  "remark": "靠窗位置"
}

Field	Type	Required	Description
tableNo	string	YES	桌号，1-32 字符
type	int	YES	0=摊位码, 1=公用码
storeId	long	CONDITIONAL	摊位码时必填，公用码时忽略
remark	string	NO	备注

Response

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "tableNo": "A01",
    "type": 0,
    "storeId": 100,
    "nightMarketId": 5,
    "qrCode": "https://xxx.com/scan?type=0&storeId=100&tableId=1",
    "status": 0,
    "useStatus": 0,
    "createTime": "2026-04-29 10:00:00"
  }
}

Business Rules

• 摊主只能创建 type=0，storeId 自动从用户信息获取
• 夜市管理员可创建 type=0（需指定 storeId）和 type=1
• 同一摊位/夜市下桌号不能重复

---

2. 获取餐桌码列表

GET /table-qrcode/list

Request Parameters

Parameter	Type	Required	Description
storeId	long	NO	按摊位筛选
type	int	NO	按类型筛选
status	int	NO	按启用状态筛选
useStatus	int	NO	按使用状态筛选
pageNum	int	NO	页码，默认 1
pageSize	int	NO	每页条数，默认 10

Response

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "tableNo": "A01",
      "type": 0,
      "storeId": 100,
      "storeName": "烧烤摊",
      "nightMarketId": 5,
      "status": 0,
      "useStatus": 0,
      "createTime": "2026-04-29 10:00:00"
    }
  ]
}

Business Rules

• 摊主只能看到自己摊位的餐桌码
• 夜市管理员可以看到夜市下所有餐桌码

---

3. 获取餐桌码详情

GET /table-qrcode/{id}

Response

同创建响应中的 data 结构，额外包含 storeName。

---

4. 更新餐桌码

PUT /table-qrcode/update

Request

{
  "id": 1,
  "tableNo": "A02",
  "remark": "更新备注"
}

Field	Type	Required	Description
id	long	YES	餐桌码 ID
tableNo	string	NO	桌号
remark	string	NO	备注

Response

{
  "code": 200,
  "msg": "操作成功"
}

Business Rules

• 不允许修改 type 和 storeId（创建后不可变更）
• 摊主只能修改自己的码，夜市管理员可修改所有码

---

5. 删除餐桌码

DELETE /table-qrcode/delete/{id}

Response

{
  "code": 200,
  "msg": "操作成功"
}

Business Rules

• 使用中的餐桌码（useStatus=1）不能删除
• 摊主只能删除自己的码，夜市管理员可删除所有码

---

6. 切换启用状态

PUT /table-qrcode/changeStatus

Request

{
  "id": 1,
  "status": 1
}

Response

{
  "code": 200,
  "msg": "操作成功"
}

---

7. 获取二维码图片

GET /table-qrcode/qrcode/{id}

Response

返回二维码图片的 Base64 编码：

{
  "code": 200,
  "msg": "操作成功",
  "data": "data:image/png;base64,iVBORw0KGgo..."
}

Business Rules

• 根据餐桌码信息动态生成二维码图片
• 二维码内容为 qrCode 字段中的 URL
• 如果 qrCode 为空，先根据 id 生成 URL 并保存到 qrCode 字段

---

8. 扫码入口（C端）

GET /table-qrcode/scan

Request Parameters

Parameter	Type	Required	Description
type	int	YES	0=摊位码, 1=公用码
storeId	long	CONDITIONAL	type=0 时必填
tableId	long	YES	餐桌码 ID

Response

返回重定向到对应的前端页面：

• type=0: 重定向到摊位商品列表页（携带 storeId + tableId）
• type=1: 重定向到摊位选择页（携带 nightMarketId + tableId）

Business Rules

• 餐桌码必须处于启用状态（status=0）
• 同时更新 useStatus 为 1（使用中）