jinye_huang/TravelContentCreator
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
TravelContentCreator/docs/FIELD_MAPPING.md

343 lines
10 KiB
Markdown
Raw Normal View History

完成了大部分的模块设计，包括新的笔记创作系统
2025-12-09 21:16:44 +08:00
# 字段映射与规范
> 更新日期: 2024-12-09
> 版本: 2.0.0
> 状态: 重构中
**重要更新**: 详细的字段重构设计请参考 [FIELD_REFACTOR_DESIGN.md](./FIELD_REFACTOR_DESIGN.md)
---
## 1. 测试结果总结
### 1.1 已验证功能
| 功能 | 状态 | 耗时 | 备注 |
|-----|------|------|------|
| 配置查询 API | ✅ 通过 | <1s | 风格 2 个，人群 3 个 |
| 选题生成 | ✅ 通过 | ~40s | LLM 调用正常 |
| 内容生成 | ✅ 通过 | ~25s | LLM 调用正常 |
| 海报生成 | ⚠️ 待修复 | - | 依赖旧模块 |
### 1.2 生成示例
**选题生成结果**:
```json
{
"index": "1",
"date": "2025-02-10",
"logic": "春节假期期间，针对周边家庭游客推出团圆主题宣传",
"object": "上海迪士尼",
"product": "双人票",
"productLogic": "双人票满足夫妻/情侣陪同长辈或子女的春节出游需求",
"style": "极力推荐风",
"styleLogic": "通过强烈号召性语言突出春节限定体验价值",
"targetAudience": "周边游",
"targetAudienceLogic": "辐射长三角地区家庭客群，利用高铁/自驾3小时可达优势",
"scenic_spot_id": 1,
"product_id": 20,
"style_id": "tuijian",
"audience_id": "zhoubianyou"
}
```
**内容生成结果**:
```json
{
"title": "天津亲子玩水首选！全家畅玩冒险湾🎢👶",
"content": "还在为带娃找消暑去处发愁？\n天津冒险湾直接给你安排全套解暑方案~\n✅大人小孩都能嗨：\n刺激控冲浪屋水上过山车\n宝妈安心区3000㎡儿童戏水乐园\n还有超治愈的漂流河和海浪池\n一家三口总能找到心头好...",
"tag": "#天津旅游 #天津周边游 #滨海新区游玩 #天津冒险湾 #冒险湾攻略"
}
```
---
## 2. 字段映射
### 2.1 输入字段 (Java → Python)
#### scenic_spot (景区)
| 字段 | 类型 | 必填 | 说明 | Java 来源 |
|-----|------|------|------|----------|
| id | int/str | ✅ | 景区 ID | ScenicSpot.id |
| name | str | ✅ | 景区名称 | ScenicSpot.name |
| description | str | ❌ | 景区描述 | ScenicSpot.description |
| address | str | ❌ | 详细地址 | ScenicSpot.address |
| location | str | ❌ | 所在城市 | ScenicSpot.location |
| traffic_info | str | ❌ | 交通信息 | ScenicSpot.trafficInfo |
| highlights | list | ❌ | 亮点列表 | ScenicSpot.highlights |
| opening_hours | str | ❌ | 营业时间 | ScenicSpot.openingHours |
| ticket_info | str | ❌ | 票价信息 | ScenicSpot.ticketInfo |
| tips | str | ❌ | 游玩提示 | ScenicSpot.tips |
#### product (产品)
| 字段 | 类型 | 必填 | 说明 | Java 来源 |
|-----|------|------|------|----------|
| id | int/str | ✅ | 产品 ID | Product.id |
| name | str | ✅ | 产品名称 | Product.name |
| price | number | ❌ | 现价 | Product.price |
| original_price | number | ❌ | 原价 | Product.originalPrice |
| description | str | ❌ | 产品描述 | Product.description |
| includes | list | ❌ | 包含内容 | Product.includes |
| valid_period | str | ❌ | 有效期 | Product.validPeriod |
| usage_rules | str | ❌ | 使用规则 | Product.usageRules |
#### style (风格)
| 字段 | 类型 | 必填 | 说明 | Java 来源 |
|-----|------|------|------|----------|
| id | str | ✅ | 风格 ID | 从配置 API 获取 |
| name | str | ✅ | 风格名称 | 从配置 API 获取 |
**可用值**: `gonglue` (攻略风), `tuijian` (极力推荐风)
#### audience (人群)
| 字段 | 类型 | 必填 | 说明 | Java 来源 |
|-----|------|------|------|----------|
| id | str | ✅ | 人群 ID | 从配置 API 获取 |
| name | str | ✅ | 人群名称 | 从配置 API 获取 |
**可用值**: `qinzi` (亲子向), `zhoubianyou` (周边游), `gaoshe` (高奢酒店)
### 2.2 输出字段 (Python → Java)
#### topic (选题)
| 字段 | 类型 | 说明 | Java 映射 |
|-----|------|------|----------|
| index | str | 选题序号 | Topic.index |
| date | str | 发布日期 (YYYY-MM-DD) | Topic.date |
| object | str | 景区名称 | Topic.object |
| product | str | 产品名称 | Topic.product |
| style | str | 风格名称 | Topic.style |
| targetAudience | str | 人群名称 | Topic.targetAudience |
| logic | str | 选题逻辑 | Topic.logic |
| productLogic | str | 产品逻辑 | Topic.productLogic |
| styleLogic | str | 风格逻辑 | Topic.styleLogic |
| targetAudienceLogic | str | 人群逻辑 | Topic.targetAudienceLogic |
| scenic_spot_id | int | 景区 ID (引擎增强) | Topic.scenicSpotId |
| product_id | int | 产品 ID (引擎增强) | Topic.productId |
| style_id | str | 风格 ID (引擎增强) | Topic.styleId |
| audience_id | str | 人群 ID (引擎增强) | Topic.audienceId |
#### content (内容)
| 字段 | 类型 | 说明 | Java 映射 |
|-----|------|------|----------|
| title | str | 文案标题 | Content.title |
| content | str | 文案正文 | Content.content |
| tag | str | 标签 (空格分隔) | Content.tag |
---
## 3. 字段问题与改进建议
### 3.1 已修复问题 ✅
#### 问题 1: 缺少 title 字段 → 已修复
**修复**: 在 Prompt 中添加了 `title` 字段要求
#### 问题 2: index 类型不一致 → 已修复
**修复**: Prompt 示例中 index 改为整数
### 3.2 保留问题 (兼容性考虑)
#### 字段命名不一致
**现状**:
- `object` vs `scenic_spot_id` (景区)
- `targetAudience` vs `audience_id` (人群)
- 驼峰命名 vs 下划线命名混用
**决定**: 保持现有命名以兼容 Java 端，通过 Java 端适配层处理
```json
// 改进后
{
"index": 1,
"date": "2025-02-10",
"scenic_spot_name": "上海迪士尼",
"scenic_spot_id": 1,
"product_name": "双人票",
"product_id": 20,
"style_name": "极力推荐风",
"style_id": "tuijian",
"audience_name": "周边游",
"audience_id": "zhoubianyou",
"logic": "...",
"product_logic": "...",
"style_logic": "...",
"audience_logic": "..."
}
```
#### 问题 2: index 类型不一致
**现状**: LLM 返回 `"index": "1"` (字符串)
**建议**: 在引擎中转换为整数
#### 问题 3: 缺少 title 字段
**现状**: 选题没有生成标题，只有 `object` (景区名)
**建议**: 在 Prompt 中要求生成 `title` 字段
### 3.2 Prompt 改进建议
```yaml
# 改进后的输出格式
## JSON 输出示例
```json
[
{
"index": 1,
"date": "2024-07-01",
"title": "暑假遛娃首选！天津冒险湾全家畅玩攻略",
"scenic_spot_name": "天津冒险湾",
"product_name": "家庭套票",
"style_name": "攻略风",
"audience_name": "亲子向",
"logic": "暑假初期，针对家庭出游进行预热宣传",
"product_logic": "结合住宿和导览，提供便捷的家庭游解决方案",
"style_logic": "强调家庭共享时光和文化体验",
"audience_logic": "满足家长带娃出游，寓教于乐的需求"
}
]
```
### 3.3 Java 端适配建议
```java
// TopicGenerateResponse.java 字段映射
public class Topic {
private Integer index; // 选题序号
private String date; // 发布日期
private String title; // 选题标题 (新增)
// 名称字段 (LLM 生成)
private String object; // 景区名称 (兼容旧字段)
private String scenicSpotName; // 景区名称 (新字段)
private String product; // 产品名称 (兼容旧字段)
private String productName; // 产品名称 (新字段)
private String style; // 风格名称
private String styleName; // 风格名称 (新字段)
private String targetAudience; // 人群名称 (兼容旧字段)
private String audienceName; // 人群名称 (新字段)
// ID 字段 (引擎增强)
private Long scenicSpotId;
private Long productId;
private String styleId;
private String audienceId;
// 逻辑字段
private String logic;
private String productLogic;
private String styleLogic;
private String targetAudienceLogic;
// 兼容方法
public String getScenicSpotName() {
return scenicSpotName != null ? scenicSpotName : object;
}
}
```
---
## 4. API 调用示例
### 4.1 选题生成
```bash
curl -X POST http://localhost:8001/api/v2/aigc/execute \
-H "Content-Type: application/json" \
-d '{
"engine": "topic_generate",
"params": {
"month": "2025-02",
"num_topics": 3,
"scenic_spot": {
"id": 1,
"name": "上海迪士尼",
"description": "全球第六座迪士尼乐园",
"location": "上海市浦东新区"
},
"product": {
"id": 20,
"name": "双人票",
"price": 798
},
"style": {"id": "tuijian", "name": "极力推荐风"},
"audience": {"id": "zhoubianyou", "name": "周边游"}
}
}'
```
### 4.2 内容生成
```bash
curl -X POST http://localhost:8001/api/v2/aigc/execute \
-H "Content-Type: application/json" \
-d '{
"engine": "content_generate",
"params": {
"topic": {
"index": 1,
"date": "2025-02-10",
"title": "春节迪士尼双人游",
"object": "上海迪士尼",
"product": "双人票",
"style": "极力推荐风",
"targetAudience": "周边游"
},
"scenic_spot": {
"id": 1,
"name": "上海迪士尼",
"description": "全球第六座迪士尼乐园"
},
"product": {
"id": 20,
"name": "双人票",
"price": 798
},
"style": {"id": "tuijian", "name": "极力推荐风"},
"audience": {"id": "zhoubianyou", "name": "周边游"},
"enable_judge": false
}
}'
```
---
## 5. 待办事项
### 5.1 Python 端
- [ ] 修复海报生成引擎依赖
- [ ] 统一选题输出字段命名
- [ ] 添加 title 字段到选题 Prompt
- [ ] index 类型转换 (str → int)
### 5.2 Java 端
- [ ] 新增 AIGCConfigService
- [ ] 改造 TopicGenerateServiceImpl
- [ ] 改造 ContentGenerateServiceImpl
- [ ] 更新 Topic 实体类字段
- [ ] 添加字段兼容映射
### 5.3 测试
- [ ] 完整链路测试 (选题 → 内容 → 海报)
- [ ] 多风格/人群组合测试
- [ ] 性能测试
- [ ] 异常场景测试
Reference in New Issue Copy Permalink