102 lines
5.7 KiB
Markdown
102 lines
5.7 KiB
Markdown
---
|
||
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"` // 选择理由
|
||
}
|
||
``` |