fao/docs/数据源上线清单.md

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

版本：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	初稿：上线持续采集门禁与运维基线