• 文档版本：V3.0
• 修订日期：2026-11-05
• 对应版本：第三轮挑战需求 A 功能完善版
• 源码目录：project/mvp-v1.0/backend

本文说明当前后端业务接口，包含前两轮保留功能以及第三轮商品管理升级、客户升级功能。

erDiagram
    categories o|--o{ categories : parent_id
    categories o|--o{ products : category_id
    products ||--o{ purchase_intents : product_id
    customer_accounts o|--o{ purchase_intents : customer_id

    categories {
        BIGINT id PK
        VARCHAR name
        BIGINT parent_id FK
    }

    products {
        BIGINT id PK
        VARCHAR name
        DECIMAL price
        VARCHAR description
        VARCHAR image_urls
        INTEGER stock
        BIGINT category_id FK
        VARCHAR status
        BOOLEAN active_slot
        TIMESTAMP created_at
        TIMESTAMP updated_at
    }

    purchase_intents {
        BIGINT id PK
        BIGINT product_id FK
        BIGINT customer_id FK
        VARCHAR product_name_snapshot
        DECIMAL price_snapshot
        VARCHAR meeting_location
        VARCHAR name
        VARCHAR phone
        VARCHAR passcode UK
        VARCHAR status
        TIMESTAMP submitted_at
        TIMESTAMP queue_at
    }

    customer_accounts {
        BIGINT id PK
        VARCHAR username
        VARCHAR username_key UK
        VARCHAR password_hash
        VARCHAR phone
        VARCHAR default_location
        TIMESTAMP created_at
    }

    seller_accounts {
        BIGINT id PK
        VARCHAR password_hash
        BIGINT session_version
    }

客户历史查询索引包含customer_id、submitted_at、id。

当前共43条业务路由，包含兼容路径。

• 开发基址：http://localhost:8080
• JSON请求：Content-Type: application/json
• 上传请求：multipart/form-data
• 上传字段：file
• 卖家和客户身份使用HTTP Session Cookie。
• 页码page从0开始，size范围1～100。

示例：

{
  "name": "机械键盘",
  "price": 88.50,
  "stock": 3,
  "categoryId": 2,
  "images": [
    "/uploads/example-a.png",
    "/uploads/example-b.jpg"
  ],
  "description": "<h3>商品介绍</h3><p><strong>九成新</strong></p>"
}

图片地址应使用实际上传接口返回值。

{
  "username": "buyer01",
  "password": "Buyer1234",
  "phone": "13800000001",
  "defaultLocation": "学校南门"
}

{
  "username": "buyer01",
  "password": "Buyer1234"
}

用户名和密码必填，最大长度分别为32和128。

{
  "name": "客户联系人",
  "phone": "13900000001",
  "meetingLocation": "学校南门"
}

meetingLocation为本次交易地点，必填且最多200字符，不自动修改账号默认地点。

成功：

{
  "success": true,
  "disposition": null
}

失败重排：

{
  "success": false,
  "disposition": "REQUEUE"
}

失败作废时使用VOID。

不返回密码、密码哈希和归一用户名内部字段。

未登录查询客户会话返回：

{
  "authenticated": false,
  "customer": null
}

返回name、phone、status、position、productStatus。

返回passcode:string和position:number。

GET /api/public/products

公开列表排除下架商品。手动冻结或交易中的商品可展示，但不接受新意向。

GET /api/public/products/{id}

返回商品及库存、分类、图片和描述。不存在或已下架时返回404。

GET /api/public/categories

返回分类数组，通过parentId组织一级与二级结构。

POST /api/public/products/{id}/intents

仅指定商品在售且有库存时允许提交。成功返回201及口令码、排位。

修改不改变原编号、口令码、提交时间及排队顺序。

口令码忽略大小写并去除首尾空格；无效或失效返回404。

• POST /api/customer/register：创建成功返回201，自动登录。
• POST /api/customer/login：登录成功返回200，错误账号或密码401。
• 重复用户名忽略大小写，返回409。
• 登录时轮换会话编号。

• GET /api/customer/session：未登录仍返回200及authenticated=false。
• POST /api/customer/logout：返回204，仅移除客户身份。

GET /api/customer/orders

需要客户登录，支持page、size。

客户编号从服务端会话取得，不接受其他客户编号作为查询条件。按提交时间和编号倒序返回，包含等待、交易、成功、失败、撤销、作废和下架结束记录。

POST /api/customer/products/{id}/intents

需要客户登录。保存当前客户归属、本次地点和商品名称价格快照，成功返回201。

访客历史不按相同姓名或电话自动认领。

库存0创建商品时返回201，但商品状态为DELISTED。

禁止三级分类、循环引用、同级重名和有引用分类删除。

POST /api/seller/products/image

上传字段为file，支持JPG和PNG，单张不超过5MB。

成功返回：

{
  "url": "/uploads/实际文件名.png"
}

商品相册最多9张。富文本支持允许的格式化标签和本地描述图片，服务端清理危险标签及属性，拒绝非法相册地址。

• POST /api/seller/products/{id}/freeze
• POST /api/seller/products/{id}/unfreeze

手动冻结保留队列，停止新意向。交易冻结不能通过手动解冻解除。

POST /api/seller/products/{id}/trades/start

自动选择该商品有效队首，返回当前交易意向。

POST /api/seller/trades/{intentId}/result

• 成功：当前意向成功，库存减1。
• 有库存：商品恢复在售，其他等待者保留。
• 库存归零：商品下架，其他等待意向结束。
• 失败VOID：当前意向失败并清空口令码。
• 失败REQUEUE：保留原码，回到队尾。
• 失败不扣库存。
• 状态不允许或重复登记返回409。

POST /api/seller/intents/{intentId}/action

请求action为VOID或REQUEUE，分别作废或移到队尾。

仅卖家可访问。客户资料不包含密码或密码哈希；历史中的passcode固定为null。

• POST /api/seller/login：验证凭据并建立卖家身份。
• GET /api/seller/session：返回当前卖家身份是否有效。
• POST /api/seller/logout：移除卖家身份。
• PUT /api/seller/password：验证原密码并保存新密码，成功返回204。

改密请求：

{
  "currentPassword": "原密码",
  "newPassword": "不少于8位的新密码"
}

新密码8～128位。改密递增会话版本，使所有旧卖家身份失效。

密码采用PBKDF2-HMAC-SHA256、600000次迭代、16字节随机盐和32字节结果。

客户与卖家身份分开保存。客户退出不清除卖家身份，卖家退出或改密不清除客户身份。

旧current和无商品编号的工作台、交易入口需要唯一有效商品上下文。

当存在多个有效商品、无法唯一确定目标时返回409。当前多商品页面使用带商品编号的接口。

第三轮包含64个接口实例及64个功能实例。现有记录中接口实例全部通过，页面功能实例待人工执行。详细数据、步骤与测试设计方法见第三轮测试文档。