market-assistant/docs/pipeline-job-output-spec.md

# 京东流水线单次任务 — 输出规范（v1）

> 与阶段 1「竞品分析 MVP」任务 **1.1** 对齐：约定任务产物、入库数据与接口能力。  
> **列与字段**：与任务产物入库及导出一致，以后端当前版本为准（研发可查内部说明）。

---

## 1. 任务生命周期与状态

| 状态 | 含义 |
|------|------|
| 待执行 | 已创建，等待运行 |
| 执行中 | 正在跑采集与报告 |
| 成功 | 本批次输出已写入指定目录 |
| 失败 | 可阅读错误说明排查 |

- **创建任务**：通过任务创建接口提交；执行在后台进行，需轮询任务详情直至结束。  
- **失败重试**：当前为「新建任务」模式；同一关键词可再次提交，**不会**对同一任务 ID 自动重试。  
- **环境**：数据根目录未配置时，创建任务会返回服务不可用类错误。

### 1.1 报告调参（可选）

任务可附带一份 **报告调参配置**（缺省为空对象）。为空时表示生成**在线分析报告**与**结构化摘要**时一律使用**系统内置默认**（关注词、场景组、外部市场表等）。

| 能力 | 说明 |
|------|------|
| **创建时带入** | 创建任务时可一并提交调参（仅允许约定字段；体积与未知字段由后端校验）。 |
| **成功后修改** | 可在任务成功后更新调参；更新后需再执行「重新生成报告」或刷新结构化摘要，才会反映到新文稿或接口结果。 |
| **默认模板** | 「报告调参默认」接口返回与内置规则一致的示例，供界面「填入推荐示例」。 |

可调字段包括：评价关注词列表、用途/场景分组、外部市场表行等，具体键名与结构以实现为准。

---

## 2. 本批次输出目录与可下载内容

成功任务会在数据根下生成**本批次输出目录**（绝对路径，由系统分配）。

可下载/预览的**内容类型**包括（名称以实现为准）：

| 类型 | 说明 |
|------|------|
| 合并宽表 | 搜索 + 商详子集 + 评论摘要（精简列） |
| 搜索列表导出 | 列表侧表格数据 |
| 商详导出 | 与合并表对齐的商详子集 |
| 评价扁平 | 评价明细表 |
| **分析报告** | 在线阅读用的主报告文稿 |

- **下载 / 预览**：通过任务对应的下载、预览能力获取（仅成功且文件已生成时可用）。  
- **重新生成报告**（不重新爬取）：仅用本批次已有表格与元数据刷新**分析报告**正文。  
- **结构化竞品摘要**：规则生成的 JSON，与在线分析报告**统计口径一致**；价格等指标在能解析列表价时以列表为准，否则以深入样本为准，响应内会标明口径。  
- **一键简报包**：ZIP，内含完整分析报告稿、结构化摘要、要点摘录与说明；须已生成主报告。  
- **市场策略制定**：提交可选业务备注后返回策略向文稿（策略框架 + 附录数据速览），数据与同任务结构化摘要一致；仅成功且数据齐全时可用。  
- **商详表离线修正再入库**：由运维/研发在侧链完成后再走全量入库能力。

---

## 3. 宽表与商详导出（精简列）

- 合并表列顺序与内部键由系统定义。  
- 商详表为 SKU 及与合并表对齐的商详子集。  
- 精简导出**不含** HTTP 状态类字段。

---

## 4. 入库后的浏览与导出

任务成功后自动入库（也可手动全量入库）。支持：

- **数据集摘要**：各表行数与列说明。  
- **分页浏览**：搜索 / 商详 / 评价 / 合并表等。  
- **导出**：按种类与格式（如 JSON、CSV、表格）；导出时**勿使用**名为「format」的查询参数（与框架保留字冲突）。

分页结果中的字段名与库表一致。

---

## 5. 全局商品与快照

商品主档、单 SKU、按任务的历史快照等能力，与 OpenAPI 中路径一致。

---

## 6. 机器可读约定

- **OpenAPI**：仓库内提供核心路径子集，可导入调试工具。  
- **示例数据**：仓库内提供 JSON 形状示例。  
- 与线上行为不一致时，**以当前部署版本为准**，并回写说明与 OpenAPI。

---

*流水线单次任务输出规范（v1）*