# 数据源上线清单（上线环境持续采集）

> 版本：1.0  
> 关联文档：《架构设计》《产品设计-蔬菜价格指数平台》  
> 适用：**生产环境长期、自动化**从外部网站或接口拉取价格类数据（非一次性演示快照）。

本文约定「能不能上」与「上了怎么运维」，**不**描述绕过风控或非授权抓取的技术细节。

---

## 1. 文档目的

- 把 **合规边界、运行 SLA、观测告警、降级与对外话术** 固化成评审与上线门禁，避免「能跑」但不可持续。  
- 与架构分层一致：**Python 仅写 raw**；**Java** 治理、指数与对外 API；前台透传 **`source_code`** 与更新时间。

---

## 2. 上线前：合规与授权（必过项）

| 序号 | 检查项 | 说明 / 证据形式 |
|------|--------|------------------|
| 2.1 | **权利来源** | 官方 **API/数据产品合同**、**书面授权函**、或 **开放数据许可**（条款需可归档）。无书面依据的默认网页抓取，**不作为生产唯一依赖**。 |
| 2.2 | **授权范围** | 明确：用途（展示/指数/再加工）、字段、是否可缓存、**留存期限**、是否可向第三方披露、地域与账号限制。 |
| 2.3 | ** robots / 用户协议** | 已阅读并与法务或采购结论一致；若冲突以 **合同** 为准。 |
| 2.4 | **个人信息与敏感信息** | 采集字段清单评审；禁止纳入非必要个保；商户级敏感数据按组织脱敏与权限策略。 |
| 2.5 | **对外展示** | 产品文案：**数据来源、更新时间、免责声明**；多源时禁止无说明的 **静默混源**。 |
| 2.6 | **分包与外包** | 若采集由第三方实施，合同中约定 **安全、保密、删除与违约责任**。 |

---

## 3. SLA 与数据契约（产品 + 研发对齐）

建议在 OpenAPI / 内部契约中至少约定以下字段或等价物：

| 项 | 说明 |
|----|------|
| **更新频率** | 例如 T+1 日批、日内每 N 小时；**延迟上限**（超过则前台显示「延迟」态）。 |
| **业务日期** | 价格对应的 **交易日/发布日** 与时区。 |
| **缺失策略** | 节假日无盘、源故障时是否补数、是否允许空窗。 |
| **口径变更** | 指数/品种映射变更需带 **`config_version`**；变更 **提前通知期**（若有）。 |
| **`source_code`** | 枚举值写入维表；每条指标结果可追溯到源。 |

---

## 4. `source_code` 与多源规则

| 规则 | 说明 |
|------|------|
| **一源一码** | 每个授权通道对应稳定 `source_code`（如 `XFD`、`MOA_…`，以维表为准）；**禁止**多源合并后丢失来源。 |
| **演示** | `DEMO` 仅用于非生产或明确标注的演示环境，**不得**与生产数据混写同一张对外事实表而不打标。 |
| **混排展示** | 若同一屏多源：UI/API 须 **分行或分卡** 标明来源；算法侧「综合指数」须单独版本说明与评审。 |

---

## 5. 技术运行要求（采集层）

| 序号 | 要求 | 说明 |
|------|------|------|
| 5.1 | **频控与退避** | 固定 QPS 上限、失败退避、错峰；禁止故障时放大并发「刷数」。 |
| 5.2 | **Raw 只增与指纹** | 原始层追加；去重键/指纹与《架构设计》一致，支持审计与重放。 |
| 5.3 | **适配器版本** | 一源一包；对方页面/接口变更时 **仅升适配器版本**，不动核心业务表结构。 |
| 5.4 | **密钥与账号** | 凭据走配置中心或密钥管理，**禁止**入库或进镜像明文。 |
| 5.5 | **任务幂等** | 同一业务日重复跑不产生重复对外指标（由 Java 批算幂等保证，与架构一致）。 |

---

## 6. 观测与告警（建议阈值）

以下为初始建议，上线后按源实际调参。

| 指标 | 建议阈值（可调） | 动作 |
|------|------------------|------|
| 任务连续失败 | **≥ 3 次**（同任务同窗口） | 告警 + 暂停该源自动重试（可选）+ 通知负责人 |
| HTTP 5xx 比例 | **> 20%** 持续 15 分钟 | 告警 |
| 解析成功率 | **< 95%**（日级） | 日报 + 评估对方改版 |
| 入库条数环比 | **±50%** 相对近 7 日均值（排除已知节假日） | 数据质量工单，防静默错抓 |
| 延迟 | 超过 SLA 约定 `max_lag` | 前台「延迟」态 + 运营公告模板 |

日志与 trace：与《架构设计》中 **结构化日志 + trace id** 一致，便于与 Java 治理链路关联。

---

## 7. 降级与用户可见话术

### 7.1 降级策略（内部）

1. **源不可用**：停止写入该源 raw 或标记失败批次；Java 侧不生成该源当日对外指标（或沿用上一成功日，**须产品事先约定**）。  
2. **部分品种失败**：单品种缺数，榜单/详情显示缺数原因码，不编造插值（除非有明确业务规则与版本）。  
3. **多源之一中断**：仅隐藏该源数据或切换至备用源展示，**界面须标明当前生效来源**。

### 7.2 用户侧话术（示例，需法务过目）

- **延迟**：「数据来源更新延迟，所示价格为最近一次成功同步时间：{updated_at}。」  
- **维护/中断**：「{来源名称} 数据暂时无法更新，正在处理中。」  
- **免责声明**：「价格仅供参考，以实际交易为准。」（与数据源声明对齐）

---

## 8. 上线评审门禁（Checklist）

- [ ] 2.1～2.6 合规项已归档  
- [ ] 第 3 节 SLA 已写入契约或附件  
- [ ] `source_code` 已录入维表并与前台展示方案一致  
- [ ] 5.1～5.5 技术项已实现或已排期  
- [ ] 第 6 节告警已接入值班渠道  
- [ ] 第 7 节降级策略与话术已产品/法务确认  

**签字角色建议**：产品负责人、研发负责人、运维/ SRE 或等价角色、法务或授权审批人（视组织要求）。

---

## 9. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0 | 2026-04-23 | 初稿：上线持续采集门禁与运维基线 |