fix:分享

接口文档.md

@@ -21,7 +21,7 @@
   - [2.6 幂等与重试](#26-幂等与重试)
   - [2.7 需要轮询的场景](#27-需要轮询的场景)
   - [2.8 CORS 与链路追踪](#28-cors-与链路追踪)
-- [3. 接口总表（43 个）](#3-接口总表43-个)
+- [3. 接口总表（48 个）](#3-接口总表48-个)
 - [4. 公共数据结构](#4-公共数据结构)
 - [5. 接口详解](#5-接口详解)
   - [5.1 用户模块](#51-用户模块)
@@ -31,10 +31,11 @@
   - [5.5 穿搭模块](#55-穿搭模块)
   - [5.6 AI 推荐模块](#56-ai-推荐模块)
   - [5.7 衣柜分享模块](#57-衣柜分享模块)
-  - [5.8 收藏与点赞模块](#58-收藏与点赞模块)
-  - [5.9 通知模块](#59-通知模块)
-  - [5.10 商品模块](#510-商品模块)
-  - [5.11 订单与退款模块](#511-订单与退款模块)
+  - [5.8 穿搭分享模块](#58-穿搭分享模块)
+  - [5.9 收藏与点赞模块](#59-收藏与点赞模块)
+  - [5.10 通知模块](#510-通知模块)
+  - [5.11 商品模块](#511-商品模块)
+  - [5.12 订单与退款模块](#512-订单与退款模块)
 - [6. 业务逻辑与状态机](#6-业务逻辑与状态机)
 - [7. 核心调用时序图](#7-核心调用时序图)
 - [8. 错误码全表](#8-错误码全表)
@@ -239,7 +240,7 @@ Authorization: Bearer <access_token>
 
 ---
 
-## 3. 接口总表（43 个）
+## 3. 接口总表（48 个）
 
 ### 健康检查（1）
 
@@ -310,6 +311,16 @@ Authorization: Bearer <access_token>
 | GET | `/closet-share/:uuid` | 分享详情（属主 / 访客视角） |
 | POST | `/closet-share/:uuid/cancel` | 取消分享 |
 
+**穿搭分享（5）**
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| POST | `/outfit-share` | 创建穿搭分享（不扣额度，需穿搭已公开） |
+| GET | `/outfit-share` | 我的穿搭分享列表 |
+| GET | `/outfit-share/received` | 分享给我的穿搭分享 |
+| GET | `/outfit-share/:uuid` | 穿搭分享详情（属主 / 访客视角） |
+| POST | `/outfit-share/:uuid/cancel` | 取消穿搭分享 |
+
 **收藏 / 点赞（5）**
 
 | 方法 | 路径 | 说明 |
@@ -771,15 +782,21 @@ Authorization: Bearer <access_token>
 
 #### GET `/clothes/:uuid` — 衣物详情（鉴权）
 
-**请求**（path）
+**请求**（path + query）
 
 | 参数 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | uuid | string | ✅ | 衣物 UUID |
+| share_uuid | string | 否 | 穿搭分享 UUID：非属主通过穿搭分享只读查看该分享穿搭内的衣物时必传 |
 
 **响应** `data` = [衣物对象](#42-衣物对象-clothesitem)
 
-**错误码**：`10000` 参数错误（uuid 为空）· `50000` 衣物不存在 · `50005` 无权操作该衣物
+**业务逻辑（可见性）**
+
+- 属主：始终可见。
+- 非属主：**仅当携带有效 `share_uuid`**（该分享正常、穿搭仍公开可见、且该衣物属于该分享的穿搭明细）时返回**只读**衣物信息；否则 `50005`。
+
+**错误码**：`10000` 参数错误（uuid 为空）· `50000` 衣物不存在 · `50005` 无权操作该衣物 · `90103` 穿搭分享不存在（含穿搭已删除 / 取消公开）· `90104` 穿搭分享已取消
 
 ---
 
@@ -1125,6 +1142,7 @@ Authorization: Bearer <access_token>
 | status | int | `1`=正常 `2`=已取消 `3`=已过期 `4`=已封禁 |
 | owner_name | string | 分享者昵称（本接口暂不返回，恒为空） |
 | owner_avatar | string | 分享者头像（本接口暂不返回，恒为空） |
+| created_at | int64 | 分享创建时间（秒，前端合并排序用） |
 
 > ⚠️ **过期是"惰性"的**：`expire_time` 到了但没人访问时，列表里 `status` 可能仍是 `1`，直到有人访问详情才变成 `3`。**前端应同时判断 `status` 与 `expire_time`** 来展示"已过期"。
 
@@ -1214,7 +1232,122 @@ Authorization: Bearer <access_token>
 
 ---
 
-### 5.8 收藏与点赞模块
+### 5.8 穿搭分享模块
+
+**状态枚举** `status`：`1`=正常 `2`=用户取消
+
+> 穿搭分享用于把「自己的公开穿搭」以链接形式分享给好友。与衣柜分享不同，**创建分享不消耗任何额度**，但**要求穿搭已公开可见**（`is_public=2` 且 `audit_status=2` 且 `status=1`）；一旦穿搭取消公开或被删除，相关分享即视为失效。
+
+#### POST `/outfit-share` — 创建穿搭分享（鉴权）
+
+**业务逻辑**
+
+1. 仅能分享**本人**的穿搭（他人 → `40004`）。
+2. 穿搭必须已公开可见，否则 `10000` + `details:["请先公开该穿搭再分享"]`。
+3. **不扣额度**；创建成功后返回 `share_uuid`，分享链接携带该值。
+
+**请求**（json）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| outfit_uuid | string | ✅ | 穿搭 UUID |
+
+**响应** `data`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| share_uuid | string | 分享 UUID，供他人访问分享详情 |
+
+**错误码**：`10000` 参数错误 · `40000` 穿搭不存在 · `40004` 无权操作该穿搭 · `19001` 数据库错误
+
+---
+
+#### GET `/outfit-share` — 我的穿搭分享列表（鉴权）
+
+**请求**（query）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| page | int | 否 | 页码，默认 1 |
+| page_size | int | 否 | 每页数量，默认 10，最大 50 |
+| status | int | 否 | `1`=正常 `2`=已取消；不传 = 全部 |
+
+**响应** `data.list[]`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| share_uuid | string | 分享 UUID |
+| outfit_uuid | string | 穿搭 UUID |
+| outfit_name | string | 穿搭名称 |
+| cover_image | string | 封面（首件衣物抠图 URL，无则空） |
+| items_count | int | 包含衣物数量 |
+| status | int | `1`=正常 `2`=已取消 |
+| owner_name | string | 分享者昵称（本接口不返回，恒为空） |
+| owner_avatar | string | 分享者头像（本接口不返回，恒为空） |
+| created_at | int64 | 分享创建时间（秒） |
+
+**错误码**：`10000` 参数错误 · `19001` 数据库错误
+
+---
+
+#### GET `/outfit-share/received` — 分享给我的穿搭分享（鉴权）
+
+**业务逻辑**
+
+- "访问即视为收到"：登录用户（非分享属主）成功访问他人穿搭分享详情时，自动记录接收关系；重复访问不重复记录，属主访问不记录。
+- 列表按接收记录倒序分页返回，支持按 `status` 筛选。
+- 字段同「我的穿搭分享列表」，并额外返回 `owner_name` / `owner_avatar`。
+
+**错误码**：`10000` 参数错误 · `19001` 数据库错误
+
+---
+
+#### GET `/outfit-share/:uuid` — 穿搭分享详情（鉴权，属主 / 访客视角）
+
+**业务逻辑**
+
+- 属主与访客都可访问（需已登录，`is_owner` 区分视角）。
+- **访客访问成功即记录接收关系**；属主访问不记录。
+- 分享已取消 → `90104`；分享不存在或对应穿搭已删除 / 取消公开 → `90103`。
+
+**请求**（path）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| uuid | string | ✅ | 分享 UUID |
+
+**响应** `data`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| share_uuid | string | 分享 UUID |
+| owner_name | string | 分享者昵称 |
+| owner_avatar | string | 分享者头像 |
+| status | int | `1`=正常 `2`=已取消 |
+| is_owner | bool | 是否本人分享 |
+| outfit | object | [穿搭对象](#43-穿搭对象-outfititem)，`items[]` 含 `processed_image`（可直接展示） |
+
+**错误码**：`10000` 参数错误 · `90103` 穿搭分享不存在（含穿搭已删除 / 取消公开）· `90104` 穿搭分享已取消
+
+---
+
+#### POST `/outfit-share/:uuid/cancel` — 取消穿搭分享（鉴权）
+
+**业务逻辑**：**仅属主可操作**，他人 → `12000`（HTTP 403）；置 `status=2`，不可逆。
+
+**请求**（path）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| uuid | string | ✅ | 分享 UUID |
+
+**响应** `data` = `{}`
+
+**错误码**：`10000` 参数错误 · `12000` 无权限访问（403）· `90103` 穿搭分享不存在 · `19001` 数据库错误
+
+---
+
+### 5.9 收藏与点赞模块
 
 **动作枚举** `action`：`1`=执行（点赞/收藏）`2`=取消。两个接口都**幂等**，重复提交无副作用。
 
@@ -1309,7 +1442,7 @@ Authorization: Bearer <access_token>
 
 ---
 
-### 5.9 通知模块
+### 5.10 通知模块
 
 **`is_read` 取值**：⚠️ `1`=**未读** `2`=**已读**（非常规的 0/1，也不是布尔值）
 **`msg_type` 取值**：`1`=点赞通知 `2`=订单通知 `3`=系统通知（当前代码无发送点，预留）
@@ -1387,7 +1520,7 @@ Authorization: Bearer <access_token>
 
 ---
 
-### 5.10 商品模块（公开，无需登录）
+### 5.11 商品模块（公开，无需登录）
 
 **`goods_type` 枚举**：`1`=会员包 `2`=上传包 `3`=AI 推荐包 `4`=衣柜分享包 `5`=搭配分享包
 **`status`**：`1`=上架 `2`=下架（列表只返回上架商品）
@@ -1421,7 +1554,7 @@ Authorization: Bearer <access_token>
 
 ---
 
-### 5.11 订单与退款模块
+### 5.12 订单与退款模块
 
 **`order_status` 枚举**：`1`=待支付 `2`=已支付 `3`=已取消 `4`=已过期 `5`=已退款
 **退款 `status` 枚举**：`0`=待处理 `1`=退款中 `2`=退款成功 `3`=退款失败
@@ -2039,6 +2172,8 @@ sequenceDiagram
 | 90100 | 分享不存在 | 200 |
 | 90101 | 分享已过期 | 200 |
 | 90102 | 分享已取消 | 200 |
+| 90103 | 穿搭分享不存在 | 200 |
+| 90104 | 穿搭分享已取消 | 200 |
 | 90200 | 目标内容不存在 | 200 |
 | 90201 | 点赞操作失败 | 200 |
 | 90202 | 收藏操作失败 | 200 |