feat: 建立商品颜色映射数据模型 (#293)

docs/admin/03-data-model.md

@@ -1163,3 +1163,23 @@ CREATE TABLE purchase_spec_resolutions (
 - `original_options_json`、`candidates_json` 和 `resolved_options_json` 只保存接口定义的
   颜色/尺码字符串。不得保存原始无障碍 XML、截图、订单号、收货信息、Cookie、Token、
   密码或 API Key；时间统一保存为 UTC ISO 8601。
+
+## 19. 商品级颜色映射与审计（MySQL v30）
+
+`product_color_mappings` 保存一个蝦皮商品颜色到当前 PDD 商品颜色维度值的人工映射。
+主键是 `(shopee_goods_id, shopee_color_key, pdd_goods_id)`：PDD 商品更换后，旧商品映射
+仍留库备查，但当前页面和采购链路只读取当前关联商品的映射，避免静默套用。
+
+- `shopee_color_key` 只折叠首尾和连续空白，不做同义词、繁简或大小写猜测；
+  `shopee_color_raw` 保留用于人工核对的来源文字。
+- PDD 颜色维度只能由采集结果中唯一的显式颜色维度确定，目标值只能来自当前
+  `available=true` 的完整规格组合。候选价格区间以整数分聚合。
+- `context_version` 同时包含 PDD 关联、PDD 采集快照、蝦皮颜色集合和规则版本；保存任一行前
+  都要在事务中重算，批次内任何上下文过期都会整体拒绝。
+- 当前映射的有效性由最新候选动态判断。PDD 重采集后目标消失时保留旧映射并显示失效，
+  不自动改成另一个相似颜色。
+- 本表只建立颜色层的人工关系，不直接表示可采购。采购仍必须得到唯一、完整且当前可购买的
+  `spec_mappings` 规格组合。
+
+`product_color_mapping_audits` 是只追加审计表，记录 `upsert/clear` 的旧值、新值、操作账号、
+上下文版本和时间。清除操作只删除当前态，不删除审计；两张表都不保存提示词、模型响应或凭据。