first commit

2026-09-11 01:41:52 +08:00
commit 9f22e6ccae
263 changed files with 28935 additions and 0 deletions
@@ -0,0 +1,102 @@
+---
+name: tokenhub 穿搭推荐 prompt 与输出字段对齐
+overview: 优化 tokenhub 穿搭推荐的 prompt 与输出结构：补充「适合场景 scene」和「衣物 UUID clothes_uuid」字段，使推荐结果对齐 mysqlmodel.Outfit/OutfitItem 与 dto.AIRecommendCreateResponse。
+todos:
+  - id: align-fields
+    content: 补充 RecommendLLMResponse.Scene 与 RecommendLLMItem.ClothesUUID 字段，并在 FormatClothesInfo 中输出 UUID
+    status: completed
+  - id: optimize-prompt
+    content: 优化 buildRecommendPrompt：明确 style/scene 语义、更新 JSON 示例并加入 clothes_uuid 精确复制约束
+    status: completed
+    dependencies:
+      - align-fields
+  - id: sync-schema
+    content: 同步 buildRecommendSchema：新增 scene 与 items.clothes_uuid 字段及 required 描述
+    status: completed
+    dependencies:
+      - align-fields
+  - id: enhance-validate
+    content: 增强 ValidateClothesIDs：以衣橱实际数据回填正确的 ClothesUUID，保留品类对齐与去重
+    status: completed
+    dependencies:
+      - align-fields
+  - id: verify-build
+    content: 执行 go build 与 go vet 验证 tokenhub 包编译与静态检查通过
+    status: completed
+    dependencies:
+      - align-fields
+      - optimize-prompt
+      - sync-schema
+      - enhance-validate
+---
+
+## 产品概述
+
+完善 tokenhub 穿搭推荐的结果字段，使大模型输出可直接对齐 `mysqlmodel.Outfit/OutfitItem` 与 `dto.AIRecommendCreateResponse`，重点优化穿搭推荐的 prompt 与 JSON Schema，让推荐结果补齐「适合场景 Scene」与「衣物 ClothesUUID」两个关键字段。
+
+## 核心功能
+
+- **新增「适合场景 Scene」字段**：推荐结果在保留风格 `Style` 的基础上，新增 `Scene`（适合场景），与 `Outfit.Scene`、`dto.AIRecommendCreateResponse.Scene` 对齐。
+- **新增「衣物 ClothesUUID」字段**：推荐单品在保留 `ClothesID` 的基础上，新增 `ClothesUUID`，与 `dto.OutfitItem.ClothesUUID` 对齐。
+- **衣物摘要补充 UUID**：`FormatClothesInfo` 输出衣橱衣物时同时给出 `ID` 与 `UUID`，供大模型精确引用。
+- **优化 prompt**：明确区分 `style`（风格：简约/复古/街头等）与 `scene`（适合场景：通勤/约会/休闲/运动等），要求分别输出；要求 `clothes_uuid` 从衣橱信息中精确复制并与 `clothes_id` 一一对应。
+- **同步 JSON Schema**：补充 `scene` 与 `items.clothes_uuid` 字段定义及必填约束。
+- **校验回填 UUID**：`ValidateClothesIDs` 以衣橱实际数据为准回填正确的 `ClothesUUID`，防止大模型抄错长 UUID，同时保留品类对齐与去重逻辑。
+
+## 约束
+
+- 仅修改 `/root/zt-closet-backend/pkg/tokenhub/outfit_recommend.go`。
+- 不改 `main.go`、不接接口、不改配置、不新增依赖。
+- 导出函数与方法签名保持不变。
+
+## 技术栈
+
+- 语言：Go（沿用现有项目技术栈）
+- 依赖：仅标准库（`fmt`、`strings`、`encoding/json`），不新增任何外部依赖
+- 改动文件：仅 `pkg/tokenhub/outfit_recommend.go`
+
+## 实现方法
+
+### 总体策略
+
+以 `mysqlmodel.Outfit/OutfitItem` 与 `dto.AIRecommendCreateResponse/OutfitItem` 为字段对齐目标，对 tokenhub 包内的推荐结构体、衣物摘要格式、prompt、JSON Schema 与结果校验做一次一致性完善。核心是让 LLM 输出结果具备可直接映射到模型层的 `Scene` 与 `ClothesUUID` 字段，同时通过校验逻辑兜底纠偏。
+
+### 关键决策
+
+1. **`Style` 与 `Scene` 并存**：`Style` 表示穿搭风格（简约/复古/街头/甜美等），`Scene` 表示适合场景（通勤/约会/休闲/运动等）。两者语义不同，在 prompt 中明确区分并要求分别输出，避免模型把「风格」和「场合」混为一谈。
+2. **`ClothesID` 与 `ClothesUUID` 并存**：保留 `ClothesID`（整数，便于模型快速引用与校验），新增 `ClothesUUID`（对齐 dto 的落库字段）。由于 UUID 较长且易抄错，`ValidateClothesIDs` 在过滤后**以衣橱实际数据回填正确的 `ClothesUUID`**，而非信任模型输出，保证最终结果可靠。
+3. **`FormatClothesInfo` 并列输出 `ID` 与 `UUID`**：在现有「字段名:值」标注格式基础上，首列增加 `UUID`，形成 `- ID:1 | UUID:xxx | 大类:上装 | ...`，让模型能同时看到两个标识并建立对应关系。
+4. **保持导出 API 兼容**：`GenerateOutfitRecommendation`、`FormatClothesInfo`、`ValidateClothesIDs`、`GetClothesIDs` 等签名不变，仅改内部实现与结构体字段，避免影响未来接入方。
+
+### 性能与可靠性
+
+- `ValidateClothesIDs` 继续使用 `map[int64]mysqlmodel.Clothes` 建立 ID→衣物映射，过滤、type 对齐、UUID 回填、去重均在单次遍历内完成，整体 O(n)，无额外性能负担。
+- 不改变网络调用、模型参数与调度流程，对运行期无副作用。
+
+## 目录结构
+
+```
+pkg/tokenhub/
+└── outfit_recommend.go  # [MODIFY] 完善推荐结构体字段、衣物摘要、prompt、JSON Schema 与结果校验
+```
+
+## 关键代码结构
+
+```
+// RecommendLLMResponse 大模型返回的穿搭推荐。
+type RecommendLLMResponse struct {
+	OutfitName  string             `json:"outfit_name"`
+	Description string             `json:"description"`
+	Style       string             `json:"style"`  // 穿搭风格
+	Scene       string             `json:"scene"`  // 适合场景
+	Items       []RecommendLLMItem `json:"items"`
+}
+
+// RecommendLLMItem 大模型返回的单品推荐。
+type RecommendLLMItem struct {
+	Type       string `json:"type"`        // 品类：上装/下装/连衣裙/外套/鞋/配饰
+	ClothesID  int64  `json:"clothes_id"`  // 衣橱衣物 ID
+	ClothesUUID string `json:"clothes_uuid"` // 衣橱衣物 UUID
+	Reason     string `json:"reason"`      // 选择理由
+}
+```