zhengchiliu/zt-closet-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bugfix

Browse Source
This commit is contained in:
zhengchiliu
2026-09-15 16:02:45 +08:00
parent 112c5f8e46
commit ade2453083
70 changed files with 1441 additions and 707 deletions
Download Patch File Download Diff File Expand all files Collapse all files
接口文档.md
+68 -15
View File
@@ -283,12 +283,13 @@ Authorization: Bearer <access_token>
| PUT | `/clothes/:uuid` | 更新衣物属性 |
| DELETE | `/clothes/:uuid` | 删除衣物（满足条件时回退上传额度） |
**穿搭（6）**
**穿搭（7）**
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/outfit` | 创建穿搭 |
| GET | `/outfit` | 我的穿搭列表 |
| GET | `/outfit/community` | 社区穿搭列表（其他用户公开的穿搭） |
| GET | `/outfit/:uuid` | 穿搭详情 |
| PUT | `/outfit/:uuid` | 更新穿搭 |
| DELETE | `/outfit/:uuid` | 删除穿搭 |
@@ -315,7 +316,7 @@ Authorization: Bearer <access_token>
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/outfit-share` | 创建穿搭分享（不扣额度，需穿搭已公开） |
| POST | `/outfit-share` | 创建穿搭分享（无需公开到社区；私密穿搭扣 1 次衣柜分享额度） |
| GET | `/outfit-share` | 我的穿搭分享列表 |
| GET | `/outfit-share/received` | 分享给我的穿搭分享 |
| GET | `/outfit-share/:uuid` | 穿搭分享详情（属主 / 访客视角） |
@@ -350,7 +351,7 @@ Authorization: Bearer <access_token>
| POST | `/order/:orderNo/cancel` | 取消订单 |
| POST | `/order/refund` | 申请退款 |
> **注意**：当前**没有"社区广场 / 发现页"列表接口**。公开穿搭只能通过 UUID 直接访问详情（`GET /outfit/:uuid`），或出现在"我的收藏"列表中。
> **说明**：社区广场列表接口为 `GET /outfit/community`（分页返回其他用户已公开且审核通过的穿搭，含作者信息与点赞/收藏计数）。
---
@@ -794,9 +795,9 @@ Authorization: Bearer <access_token>
**业务逻辑（可见性）**
- 属主：始终可见。
- 非属主：**仅当携带有效 `share_uuid`**（该分享正常、穿搭仍公开可见、且该衣物属于该分享的穿搭明细）时返回**只读**衣物信息；否则 `50005`。
- 非属主：**仅当携带有效 `share_uuid`**（该分享正常、穿搭未被删除 / 封禁、且该衣物属于该分享的穿搭明细）时返回**只读**衣物信息；否则 `50005`。
**错误码**：`10000` 参数错误（uuid 为空）· `50000` 衣物不存在 · `50005` 无权操作该衣物 · `90103` 穿搭分享不存在（含穿搭已删除 / 取消公开）· `90104` 穿搭分享已取消
**错误码**：`10000` 参数错误（uuid 为空）· `50000` 衣物不存在 · `50005` 无权操作该衣物 · `90103` 穿搭分享不存在（含穿搭已删除 / 已封禁）· `90104` 穿搭分享已取消
---
@@ -932,6 +933,49 @@ Authorization: Bearer <access_token>
---
#### GET `/outfit/community` — 社区穿搭列表（鉴权）
**业务逻辑**
- 返回**其他用户**已公开的穿搭：`is_public=2` + `audit_status=2` + `status=1`（与详情页他人可见性口径一致），并**排除本人**的穿搭（自己的公开穿搭在"我的穿搭"中查看）。
- 列表按发布时间倒序（`id DESC`）。
- 每项聚合作者信息与互动计数：`owner_name` / `owner_avatar`（无头像为空串）、`like_count` / `collect_count`（仅统计有效点赞/收藏）。
**请求**（query）
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| page / page_size | int | 否 | 分页，page_size 上限 50 |
**响应** `data`
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| total | int64 | 总条数 |
| page | int | 当前页 |
| page_size | int | 每页条数 |
| list | array | 社区穿搭数组，见下表 |
`list[]`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| outfit_uuid | string | 穿搭 UUID |
| outfit_name | string | 穿搭名称 |
| outfit_desc | string | 穿搭描述 |
| scene | string | 适合场景 |
| source | int | `1`=用户创建 `2`=AI 推荐 |
| created_at | int64 | 发布时间（秒级时间戳） |
| items | array | 衣物明细 `[{clothes_uuid, processed_image}]`，`processed_image` 为可访问 URL |
| owner_name | string | 作者昵称 |
| owner_avatar | string | 作者头像 URL（无则空串） |
| like_count | int64 | 点赞数 |
| collect_count | int64 | 收藏数 |
**错误码**：`10000` 参数错误 · `19001` 数据库错误
---
#### GET `/outfit/:uuid` — 穿搭详情（鉴权）
**请求**（path）
@@ -944,6 +988,7 @@ Authorization: Bearer <access_token>
- 本人穿搭：始终可见。
- 他人穿搭：必须同时满足 `is_public=2` + `audit_status=2` + `status=1`，否则返回 `40004`。
- 通过好友分享链接查看穿搭请使用 `GET /outfit-share/:uuid`（不要求穿搭已公开）。
**响应** `data` = [穿搭对象](#43-穿搭对象-outfititem)
@@ -1236,15 +1281,20 @@ Authorization: Bearer <access_token>
**状态枚举** `status`：`1`=正常 `2`=用户取消
> 穿搭分享用于把「自己的公开穿搭」以链接形式分享给好友。与衣柜分享不同，**创建分享不消耗任何额度**，但**要求穿搭已公开可见**（`is_public=2` 且 `audit_status=2` 且 `status=1`）；一旦穿搭取消公开或被删除，相关分享即视为失效。
> 穿搭分享用于把「自己的穿搭」以链接形式分享给好友，**与「公开到社区」完全解耦**：仅自己可见的穿搭同样可以分享，好友凭 `share_uuid` 只读查看整套穿搭与单品图。
>
> **额度**：分享**仅自己可见**的穿搭扣 1 次**衣柜分享额度**（`quota_type=4`，与衣柜分享共用同一个额度池）；分享**已公开**的穿搭**不扣**（公开到社区时已扣过社区分享额度）。额度不足 → `80000` 且不创建分享。
>
> 分享一旦发出即独立于穿搭的公开状态——取消公开不影响已发出的分享，仅「取消分享」「删除穿搭」「封禁穿搭」才使分享失效。
#### POST `/outfit-share` — 创建穿搭分享（鉴权）
**业务逻辑**
1. 仅能分享**本人**的穿搭（他人 → `40004`）。
2. 穿搭必须已公开可见，否则 `10000` + `details:["请先公开该穿搭再分享"]`。
3. **不扣额度**；创建成功后返回 `share_uuid`，分享链接携带该值。
2. **无需先公开到社区**：仅自己可见的穿搭同样可分享（分享与公开解耦）；穿搭已被删除 → `40000`，已被封禁 → `40004`。
3. **额度**：`is_public=1`（仅自己可见）→ 扣 1 次衣柜分享额度（`quota_type=4`，与衣柜分享共用池），额度不足 → `80000` 且**不创建分享**；`is_public=2`（已公开）→ **不扣**。扣额成功后分享落库失败会**自动回退** 1 次额度。
4. 创建成功后返回 `share_uuid`，分享链接携带该值。
**请求**（json）
@@ -1258,7 +1308,7 @@ Authorization: Bearer <access_token>
| --- | --- | --- |
| share_uuid | string | 分享 UUID，供他人访问分享详情 |
**错误码**：`10000` 参数错误 · `40000` 穿搭不存在 · `40004` 无权操作该穿搭 · `19001` 数据库错误
**错误码**：`10000` 参数错误 · `40000` 穿搭不存在 · `40004` 无权操作该穿搭 · `80000` 额度不足 · `19001` 数据库错误
---
@@ -1295,7 +1345,7 @@ Authorization: Bearer <access_token>
**业务逻辑**
- "访问即视为收到"：登录用户（非分享属主）成功访问他人穿搭分享详情时，自动记录接收关系；重复访问不重复记录，属主访问不记录。
- 列表按接收记录倒序分页返回，支持按 `status` 筛选。
- 列表按接收记录倒序分页返回，支持按 `status` 筛选；**仅排除已删除 / 已封禁的穿搭**（穿搭是否公开不影响，分享与公开解耦）。
- 字段同「我的穿搭分享列表」，并额外返回 `owner_name` / `owner_avatar`。
**错误码**：`10000` 参数错误 · `19001` 数据库错误
@@ -1308,7 +1358,7 @@ Authorization: Bearer <access_token>
- 属主与访客都可访问（需已登录，`is_owner` 区分视角）。
- **访客访问成功即记录接收关系**；属主访问不记录。
- 分享已取消 → `90104`；分享不存在或对应穿搭已删除 / 取消公开 → `90103`。
- 分享已取消 → `90104`；分享不存在或对应穿搭已删除 / 已封禁 → `90103`（穿搭取消公开**不影响**已发出的分享）。
**请求**（path）
@@ -1327,7 +1377,7 @@ Authorization: Bearer <access_token>
| is_owner | bool | 是否本人分享 |
| outfit | object | [穿搭对象](#43-穿搭对象-outfititem)，`items[]` 含 `processed_image`（可直接展示） |
**错误码**：`10000` 参数错误 · `90103` 穿搭分享不存在（含穿搭已删除 / 取消公开）· `90104` 穿搭分享已取消
**错误码**：`10000` 参数错误 · `90103` 穿搭分享不存在（含穿搭已删除 / 已封禁）· `90104` 穿搭分享已取消
---
@@ -1869,6 +1919,9 @@ stateDiagram-v2
| **取消公开后再次公开** | **再扣 1 个额度** | ⚠️ 重点提示用户 |
| 穿搭取消公开 | **不返还** | — |
| 穿搭删除 | **不返还** | — |
| 分享「仅自己可见」的穿搭给好友 | **扣 1 个衣柜分享额度**（与衣柜分享共用池） | 额度不足时引导购买 |
| 分享「已公开」的穿搭给好友 | **不扣**（公开到社区时已扣社区分享额度） | — |
| 私密穿搭分享但分享记录落库失败 | **自动回退** | 重试即可 |
| AI 推荐生成（成功） | **扣 1 个 AI 额度** | 生成前展示剩余次数 |
| AI 推荐失败（衣橱为空/模型失败/无有效单品/落库失败） | **自动回退** | 可安全重试 |
| **AI 推荐成功但未保存** | **不返还** | ⚠️ 重点提示用户及时保存 |
@@ -1878,7 +1931,7 @@ stateDiagram-v2
| 购买商品支付成功 | **发放**（按订单快照） | 展示"已到账" |
| 退款成功 | **回收**（`total >= used`，已用部分不退） | 提示额度已回收 |
**额度不足时**：前端跳商品列表引导购买。注意 AI 额度不足返回的是 `90401`（不是 `80000`）。
**额度不足时**：前端跳商品列表引导购买。注意 AI 额度不足返回的是 `90401`（不是 `80000`）。私密穿搭分享额度不足返回 `80000`，此时**不要**回退为普通穿搭详情链接（私密穿搭对他人不可见，对方打开会是无权限的空页），应提示用户补充衣柜分享额度。
---
@@ -2220,8 +2273,8 @@ A：过期是**惰性**的。前端需同时判断 `status` 与 `expire_time`。
**Q：`GET /outfit` 里混进了 AI 推荐的穿搭？**
A：列表**不过滤 `status=3`（待用户保存）**。前端用 `source` 区分来源，AI 未保存的单独入口展示。
**Q：没有"社区广场"列表接口怎么办？**
A：当前确实没有。公开穿搭只能通过 UUID 直接访问详情，或在"我的收藏"中出现。如需广场列表，需后端新增接口。
**Q：如何浏览"社区广场"的公开穿搭？**
A：调用 `GET /outfit/community` 分页获取其他用户已公开（公开 + 审核通过 + 正常）的穿搭列表，含作者信息与点赞/收藏计数；点击卡片进入 `GET /outfit/:uuid` 详情（他人视角）互动。
### 9.2 联调检查清单