# 文案、枚举与字段映射

[返回目录](../README.md)

## aliases

覆盖接口返回的分类、属性、属性值、推荐类型和布尔值显示名。`aliases` 只影响前端展示，不改变接口请求参数。

先确认要覆盖的是哪类后端数据：

| 要改的显示名 | 配置位置 | key 来源 |
| --- | --- | --- |
| 分类名称 | `aliases.categories` | 分类树接口返回的 `code` |
| 属性名称 | `aliases.attributes` | `/filter-options` 或详情属性里的 `code` |
| 属性值名称 | `aliases.attributeValues` | 接口返回的真实 `value` |
| 推荐类型名称 | `aliases.recommendTypes` | 推荐类型值，如 `hot_sale` |
| 布尔值名称 | `aliases.booleans` 或 `aliases.booleans.byAttribute` | `true` / `false` |

```json
{
  "aliases": {
    "categories": {
      "category_a": { "zh-CN": "CATEGORY A", "en": "CATEGORY A" }
    },
    "attributes": {
      "material": { "zh-CN": "材质", "en": "Material" }
    },
    "attributeValues": {
      "metal": { "zh-CN": "金属", "en": "Metal" }
    },
    "recommendTypes": {
      "hot_sale": { "zh-CN": "热销推荐", "en": "Best Sellers" }
    },
    "booleans": {
      "true": { "zh-CN": "是", "en": "Yes" },
      "false": { "zh-CN": "否", "en": "No" }
    }
  }
}
```

回退规则：

- 命中 `aliases[kind][key][locale]` 时使用别名。
- 分类名称使用 `aliases.categories`，key 为分类接口返回的 `code`。
- 属性值使用 `aliases.attributeValues`，key 为接口返回的 value；列表页和侧边栏的动态筛选选项即使没有后端 label，也会优先用这里的别名显示。
- 推荐类型优先命中 `aliases.recommendTypes`。
- 布尔值可使用 `aliases.booleans.byAttribute` 做字段级覆盖。
- 英文环境未命中时优先显示 code/value。

排查显示名不生效时，优先检查：

1. `siteConfig.locale` 或 `initSDK({ locale })` 是否是当前语言。
2. alias 的 key 是否使用后端真实 `code` / `value`，不是展示文案。
3. `aliases.attributeValues` 是否把不同属性下的同名 value 混在一起；该映射按 value 全局命中。
4. 推荐类型是否写在 `aliases.recommendTypes`，不要只依赖旧的 `attributeValues` 兜底。

常见 shape 属性值可以按实际接口值补充别名，例如 `round`、`rectangle`、`straight_sided`、`curved`、`tapered`。

分类、属性和属性值如果需要统一全大写，不需要改后端数据，直接在对应 aliases 中配置大写文案即可：

```json
{
  "aliases": {
    "categories": {
      "category_a": { "zh-CN": "CATEGORY A", "en": "CATEGORY A" }
    },
    "attributes": {
      "shape": { "zh-CN": "SHAPE", "en": "SHAPE" },
      "type": { "zh-CN": "TYPE", "en": "TYPE" },
      "process": { "zh-CN": "PROCESS", "en": "PROCESS" }
    }
  }
}
```

## enumwhitelist

页面展示白名单，只影响 UI，不改变搜索请求协议。

```json
{
  "enumWhitelist": {
    "categories": ["category_a", "category_b"],
    "attributeValues": {
      "type": ["standard", "premium"],
      "material": ["metal", "plastic"]
    }
  }
}
```

说明：

- `categories` 使用分类树接口返回的 `code`。
- `attributeValues` 的 key 使用属性 code。
- 未配置白名单的字段不过滤。

## attributemappings

把已有字段名或显示字段映射到接口属性 code。

```json
{
  "attributeMappings": {
    "Display Size": { "target": "size", "label": "Size" },
    "Display Material": { "target": "material", "label": "Material" }
  }
}
```

常用于 `detailFields.source` 和 `filterFields.source` 的解析。