# 字段映射与规范

> 更新日期: 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 测试

- [ ] 完整链路测试 (选题 → 内容 → 海报)
- [ ] 多风格/人群组合测试
- [ ] 性能测试
- [ ] 异常场景测试