# 清北记食第一阶段数据字典

核验日期：2026-07-26

## 1. 数据模型

```text
school
  └─ canteen
       └─ floor/location
            └─ window
                 └─ dish_sale
                      └─ nutrition_version（后续表）
```

- `canteens_seed.csv` 同时保存食堂和楼层节点，用 `record_type` 区分；楼层通过 `parent_location_id` 指向食堂。
- `windows_seed.csv` 保存窗口、档口或经营区域；`exactness` 明确它是精确窗口还是仅能确认的品类区域。
- `dishes_seed.csv` 保存“菜品售卖记录”，而不是全局唯一菜名。同名菜在不同学校、食堂或窗口必须是不同记录。
- `nutrition_sources.csv` 只登记来源能力和许可，不把健康App数值写入正式菜品。

## 2. 主键与关联

| 字段 | 含义 | 规则 |
|---|---|---|
| location_id | 食堂或楼层节点ID | 稳定英文ID，不随展示名轻易修改 |
| parent_location_id | 父节点 | 楼层指向食堂；食堂为空 |
| window_id | 窗口/档口ID | 必须能关联到食堂，可选关联楼层 |
| dish_sale_id | 售卖记录ID | 同名菜跨窗口不得共用 |
| canteen_id | 食堂外键 | 必须存在于 canteens_seed 的 canteen 节点 |
| floor_location_id | 楼层外键 | 若公开资料未给楼层可以为空 |

## 3. 来源等级

| 等级 | 定义 | 例子 | 能否直接作为正式事实 |
|---|---|---|---|
| A | 校方原始页面、权威营养机构、现场多次核验 | 两校餐饮中心官网、清华手册、USDA、中国疾控 | 可，但旧页面仍要标“待现场核验” |
| B | 标准化出版物、校方专题报道、正式许可API | 《水木食集》、FatSecret正式API | 取决于授权和时效 |
| C | 校内媒体、健康App、社区开放库、单次公开报道 | 清新时报、薄荷、Open Food Facts | 只能作候选/参考，不能直接变成食堂正式热量 |
| D | 单个用户提交、未经审核的众包估算 | 用户评论或一次拍照估算 | 只进入待审核队列 |

## 4. 数据状态

- `已公开确认`：来源明确给出该事实，且不是从描述中猜测。
- `待现场核验`：来源可信但页面较旧、缺窗口号，或经营状态可能变化。
- `历史线索` / `旧网页`：仅证明过去出现过，不能显示为“当前在售”。
- `暂无可靠热量，保留空值`：所有首轮菜品的营养状态。空值是合规结果，不是缺陷。

## 5. 营养字段与正式值晋升规则

正式热量不得仅来自通用App。后续建议为每个菜品建立 `nutrition_version`：

| 字段 | 含义 |
|---|---|
| energy_kcal | 对应一份的千卡 |
| serving_weight_g | 一份可食重量 |
| protein_g / fat_g / carbohydrate_g | 对应一份的三大营养素 |
| method | official_recipe / recipe_calculation / field_measurement / reference_prior |
| sample_count | 称重或重复制作次数 |
| valid_from / valid_to | 版本有效期 |
| source_id | 来源或实测批次 |
| confidence_grade | A-D |

晋升建议：

1. 校方已给营养和份量，完成字段核验后可为 A。
2. 获授权标准配方 + 权威食材成分表 + 成品份量，可为 B；多批现场称重后可升 A。
3. 通用数据库或健康App只能形成参考区间，保持 C，不覆盖校内正式值。
4. 单个用户填写为 D；至少经过审核并与其他证据交叉后再升级。

## 6. 称重规则

- 先记录空盘/容器皮重，再称装菜后的总重；可食重量 = 总重 - 皮重。
- 同一食堂、楼层、窗口、菜名、份量档位分别采样。
- 建议普通菜至少 5 份起步，波动大的自选菜或套餐至少 10 份。
- 保存称具型号、精度、采样日期、时段、样本数、均值和标准差。
- 仅有重量无法推出热量；油、酱汁、原料比例和烹调损耗仍需配方或合理模型。

## 7. 版权与授权边界

- 校方网页：只提取事实字段与URL，不复制图片或长段文字。
- 《水木食集》《团餐食谱1234》《中国食物成分表》：本轮只登记元数据；购买不自动等于获得数据库化或商业展示权。
- 中国疾控网页库：页面明确声明数据版权和解释权，本轮仅作为需授权的权威参考。
- FatSecret：必须按账户版本、缓存、署名和用途条款使用，不能混成无来源“自有数据”。
- Open Food Facts：导入前必须接受并实现 ODbL/DbCL/图片许可要求。
- 薄荷健康等App：无公开API或批量许可时只做人工参考，禁止爬取。

## 8. 更新策略

- 食堂/楼层：每学期复核一次。
- 窗口/菜单：重点食堂每月或每两周复核；用户提交仅作为变更线索。
- 营业时间：寒暑假、节假日与临时公告单独建版本。
- 营养值：历史记录锁定当时版本，新版本不得回写修改过去饮食记录。