# 数据契约

## 发布文件

- `data/textile-intelligence.json`：情报主数据，前端和 SEO 的唯一事实快照。
- `data/textile-trends.json`：趋势博客、灵感图库和时装趋势。
- `data/textile-intelligence-source-status.json`：生成期源状态，不复制到公开 `dist/data`。
- `data/textile-zh-cache.json`：翻译缓存，不复制到公开站点。

主数据顶层字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `version` | number | 数据结构版本 |
| `generated_at` | ISO 8601 | 生成时间，UTC |
| `as_of_date` | YYYY-MM-DD | 业务判断基准日 |
| `source_target/source_success` | number | 严格源目标与成功数 |
| `summary` | object | 各栏目数量、去重数、市场数 |
| `today` | array | 已排序的今日经营动作 |
| `calendar/calendar_insights` | array | 原始日期层与跨源聚合机会层 |
| `exhibitions` | array | 展会和报名信息 |
| `policies` | array | 政策、召回、平台规则与知识产权 |
| `standards` | array | 标准、认证、色彩和材料事实 |
| `platforms` | array | 平台目录与中国卖家准入边界 |
| `activities` | array | 跨境活动与报名入口 |
| `sources` | array | 已通过源的公开核验信息 |

## 公共字段

所有可展示条目至少包含稳定 `id`、`title`、`summary`、`source`、`source_url/url`、`verified_at`、`confidence`。外文条目可包含 `title_original`、`summary_original`、`translation_url` 和 `translation_fallback_url`。

日历聚合条目必须满足：

- `start_date`、`affected_countries`、`country_details.local_name`
- `stocking_start`、`stocking_end`、`planning_stage`
- `product_suggestions`、`platforms`、`platform_actions`
- `official_sources` 与事实/经营分析边界

进入“精准机会”的条目必须同时有目标国家、平台、产品、备货窗口，且窗口未在 `as_of_date` 前结束。不满足者只能进入全部节点或观察层。

展会条目要区分 `registration_url`、`visitor_url`、官网和机器翻译链接。正式报名、付款和验证码不得指向翻译代理。

平台条目必须包含 `homepage_url`、`official_url`、`seller_url`、`markets`、`access_level`、`access_label`、`cross_border` 和本地 SVG `logo`。不确定的中国主体准入不能标为无条件开放。

## 兼容策略

- 新增可选字段不提升 `version`；删除、改名或改变语义必须提升版本。
- 消费端忽略未知字段，不依赖数组索引。
- C# 反序列化建议启用大小写不敏感和未知字段忽略。
- Node/TypeScript 进入数据库前应以 JSON Schema 或 Zod 校验同一契约；不要在 UI 组件内修补脏数据。