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）