algolia-data-modeling

Algolia 数据建模

使用此技能，在代码将记录写入 Algolia 前塑造数据。良好的相关性通常始于符合用户使用路径的记录，而不是照搬源数据库的架构。

面向客户的标准

• 在对记录结构作出判断前，先索取样例记录和边缘情况。
• 如果缺少源数据，请明确说明假设。
• 如需基于来源的信息，请使用公开的 academy.algolia.com 对齐学习内容，并使用公开的 algolia.com/doc 获取当前实施指南。
• 如果有 Academy 元数据参考包，只能使用其中的 title、url、course、module、learning_objectives 和 updated_at 字段来确定结构。如果元数据已过时或没有匹配项，请改为查询实时 Academy/docs。不要将缓存的元数据视为课程内容或实施依据。
• 不要要求访问自定义 Academy/docs；客户提供的来源只能作为可选背景信息。
• 如果需要实时 Algolia 数据、分析、索引检查、设置变更或账户操作，请使用 Algolia MCP、Algolia CLI 或官方 Algolia 技能执行实时操作，然后使用此技能解读结果并验证适合客户的实施路径。
• 提供索引契约、验证查询、负责人交接说明以及重新索引／更新路径。
• 对于电商目录，在讨论商品陈列或 UI 行为前，明确选择变体级、变体组级或商品级记录模型。

官方配套技能

• 如果需要检查实时样例记录、现有索引结构、对象数量、导入或导出，请使用官方的 algolia-mcp 或 algolia-cli。
• 在调用官方工具后使用此技能，将发现转化为面向客户的索引契约、变体策略和验证计划。

事实来源规则

• 不要仅根据数据库表推断最终记录模型。必须了解样例记录、UI 预期、事件需求和更新责任方。
• 未通过官方的 algolia-cli、algolia-mcp 或当前文档确认实时操作前，不要指定确切的 Algolia 设置、API 命令或迁移步骤。
• 如果架构没有稳定 ID、变体归属、时间戳归属、库存策略和事件标识符，则应将其视为暂定方案。
• 在索引记录或开始 UI 实施前，尽可能创建或更新索引契约。如果用户需要快速原型，可先使用最简的暂定契约，并列出后续需要重新确认的假设。
• 不要用商品陈列规则来替代缺失的商品陈列数据。新品、促销状态、品牌归属、库存、畅销状态、利润率和人气必须是明确字段，或有文档说明的上游计算结果。

索引契约决策要点

在索引或开展 UI 工作前，尽可能创建 algolia/index-contract.md 或等效文档。如果在契约不完整的情况下继续，请指出哪些决策仍是暂定的：

• 索引名称。
• 记录模型：变体级、变体组级、商品级，或非电商场景下的等效模型。
• 记录粒度。
• objectID 策略。
• 可搜索属性。
• 显示属性。
• 分面属性。
• 排名信号。
• 排名指标的粒度、顺序、方向、精度和分桶逻辑。
• 商品陈列字段。
• 库存字段。
• 事件归因字段。
• 更新责任方和频率。
• 验证查询。

对于演示和原型，请提供一段话的数据契约、三个验证查询，以及明确列出的暂缓处理的生产环境问题。

工作流

1. 在确定数据形状前，先阅读 references/data-modeling-guide.md。
2. 在编写面向客户的索引契约或展示优质输出示例时，先阅读 references/example-output.md。
3. 如果记录粒度、业务目标或筛选要求未知，请询问相关背景信息。
4. 先设计索引契约：索引名称、环境、objectID 策略、记录形状、可搜索属性、可分面属性、排序信号和更新责任归属。
5. 编写代码前先选择变体策略：产品记录、变体记录、分组变体，或按语言区域、地区、租户、渠道、价格表或权限集拆分记录。
6. 建立索引前，先检查商品运营数据缺口：模式是否清晰、时间戳／新近度、促销属性、库存分档、畅销分档、利润率／人气指标、指标精度以及上游责任归属。
7. 优先使用反规范化、适合搜索的记录。避免强迫 UI 在查询时联接数据或推断关键排序／筛选字段。
8. 将自定义排序输入设计为业务层面的平局判定因素，而不是原始数据库转储。确定哪些指标优先、数值越高还是越低越好，以及是否应对数值进行舍入或分档，以便后续排序属性仍能影响平局结果。
9. 如果更改 objectID、记录粒度或影响相关性的设置，请制定迁移和重新建立索引的计划。
10. 告知业务用户，许多商品运营问题首先是数据准备问题。如果索引记录中没有体现“新品”“促销”“自有品牌”“高库存”“高利润率”“高人气”或“畅销”等概念，规则和提升无法可靠地推广这些商品。

要询问的问题

只询问最少且有用的问题：

• 能否提供 5 条常规记录和 5 条边缘情况记录，包括变体、不可用商品、受限内容、地区差异或经常搜索效果不佳的记录？
• 搜索结果应代表什么实体：产品、变体、SKU、文章、地点、账户，还是其他单元？
• 变体应显示为独立命中项、每个产品一个命中项、每种共享属性（例如颜色）一个命中项、单个命中项内的分组选项，还是根据可用性、渠道、地区、账户或权限静默筛选？
• 用户必须能够搜索、筛选、排序、查看或用于排序的属性有哪些？
• 商品运营必须使用哪些属性来提升或降低产品排名：新品、评分、销量、人气、利润率、促销、自有品牌、高库存、畅销、季节性、营销活动，还是编辑优先级？
• 业务如何针对不同类别定义“新品”“高库存”和“畅销”？这些分档在建立索引前由哪里计算？
• 当文本相关性相同时，哪些自定义排序指标应依次生效：销量、利润率、评分、人气、新近度、库存，还是编辑优先级？
• 排序指标的精度是否过高，难以有效判定平局？是否应进行舍入或分档，例如 sales_30d_bucket、margin_band 或 freshness_bucket？
• 哪些属性是稳定标识符，哪些是易变的显示或排序字段？
• 哪些记录应按用户／账户／地区／渠道隐藏、延迟显示或保护？
• 记录多久会更改一次？由哪个系统负责这些更改？
• 同一内容是否需要按语言区域、地区、租户、环境或用户群组建立单独的索引？

实施标准

• 将 objectID 视为稳定契约。不要根据可变的展示字段推导它。
• 明确建模变体。如果用户期望每个产品只返回一个结果，就不要误将每个源数据行按 SKU 建立索引；如果颜色、尺码、库存情况、价格、地区或权限会实质性影响搜索行为，就不要合并变体。
• 有意识地控制记录大小：包含检索、排序、分面、展示、分析上下文和事件归因所需的字段。
• 将生产、预发布和开发索引分开。不要针对生产环境测试破坏性索引操作。
• 在适当情况下，使用副本支持其他排序方式，并使用虚拟副本进行相关排序。
• 构造 UI 响应时，确保事件所需的 queryID/objectID/位置保持兼容。
• 将公开响应允许列表纳入记录契约：内部排序依据（原始值或分桶后的人气度、销售速度、利润率）用于排序，而非对外提供——规划好 attributesToRetrieve（以及适当情况下的 unretrievableAttributes），确保公开响应仅包含展示和事件归因字段，并使用公开搜索密钥通过实时查询进行验证。
• 选择一个有效价格属性，并在展示、排序、筛选、范围分面和副本设置中始终如一地使用。展示促销价，却按基础价格排序或筛选，是用户能察觉的缺陷（商品会出现顺序错误或不符合筛选条件），而非风格选择。
• 除非有明确的运营原因，否则不要要求 Algolia 使用精确库存数量进行商品运营。优先使用稳定的分桶值或布尔值，例如 in_stock、stock_bucket 或 high_inventory，避免每次销售都触发不必要的重新索引。
• 在索引前预先计算特定品类的新鲜度、高库存、促销、自有品牌和畅销标记。不要指望 Algolia 规则能从不完整记录中推断出缺失的业务定义。
• 说明连续值与分桶值的区别。精确的销量、利润率、库存或时间戳值可能有用，但分桶值通常更便于理解商品运营和自定义排序，也更不易受噪声影响。
• 将自定义排序视为文本相关性之后依次进行的平局判定。如果第一个排序指标过于精确，后续指标可能很少起作用；如果业务期望第二或第三个指标参与排序，就应降低精度或对数值进行分桶。
• 对于电商，保留产品身份、变体身份和 SKU 身份之间的区别。当 UI 必须将一个产品系列显示为一个结果，但事件或筛选仍需要变体级数据时，应使用父级 ID 和所选变体字段。

反模式

• 默认按每个 SKU 建立一行索引，但用户实际期望一个产品系列只显示一条结果。
• 当库存情况、价格、权限、颜色、尺码或事件归因必须因变体而异时，合并变体。
• 当分桶值就能以更少的更新满足业务需求时，仍使用精确库存数量作为商品运营输入。
• 在没有可靠时间戳或明确的新品属性时，推广“新品”。
• 在没有明确时间范围、品类范围和刷新负责人的情况下，推广“畅销品”。
• 在未确定业务排序顺序、方向、时间范围、品类范围和精度时，按原始销量、利润率、评分或人气度排序。
• 使用精度过高的首个自定义排序指标，导致后续业务指标无法判定平局。
• 因为源系统中使用方便，就将仅用于展示或内部使用的字段添加到可搜索文本中。
• 在记录契约确定之后才设计事件，导致后续出现 objectID、index、queryID 或变体聚合问题。
• 仅仅因为没有报错，就在公开搜索响应中发送内部排序依据（原始人气度、销售速度、利润率或其分桶值）——竞争对手和爬虫会读取命中结果负载。
• UI 展示促销价，却按基础价格排序或筛选（反之亦然）——所有场景都应遵循同一套有效价格契约。

索引前检查项

索引记录前，请说明以下项目的状态是已就绪、暂定还是延期：

• objectID 的稳定性。
• UI 使用的 Facet 及其规范化方式。
• 排名字段及其重要性。
• 排名指标精度：原始值、四舍五入值、分桶值或精选值。
• 可检索的显示字段。
• 公开响应允许列表：从可检索负载中排除内部排名字段。
• 选择一个有效价格属性，用于显示、排序、筛选和范围 Facet。
• 图片、URL、标题、价格、可用性或其他 UI 必需字段。
• 事件归因字段。
• UI 所需的库存、可用性或权限字段。
• 易变字段的更新负责人和频率。

电商记录模型策略

选择以下一种模式，并说明其权衡：

• 变体级记录：一条记录代表一种具体的可售变体，例如某个颜色／尺码 SKU。适用于用户需要按变体进行搜索、筛选、比较、定价或转化；颜色／尺码／可用性／图片必须准确；或需要进行细粒度更新的情况。如果 UI 应显示产品系列，请规划分组或 distinct 行为。
• 变体组级记录：一条记录将共享某个关键属性（例如颜色）的多个变体归为一组。适用于 UI 和商品运营通常以产品／颜色为单位，但筛选和图片需要比主产品记录更精确的情况。
• 产品级或主产品记录：一条记录代表基础产品，并包含所有变体。适用于商品运营、分析和 AI 行为应以产品为单位，且用户希望看到一个产品结果的情况。请记录筛选后显示正确变体所需的前端工作。
• 语言区域、地区、渠道或账户变体：当文本、价格、可用性、权限或事件差异足以改变搜索行为时，将其拆分为单独的记录或索引。
• 受保护的变体：切勿仅依赖 UI 隐藏。对权限敏感的变体需要使用受保护的筛选器、单独的索引或记录级访问策略。

对于每种模型，请说明其对文本相关性、Facet 准确性、商品运营控制、AI／个性化行为、分析聚合、更新成本、记录数量和 UI 复杂度的影响。

Academy 与客户教育对齐

需要有来源支持的指导时，请搜索公开的 Academy 资料，了解索引和数据就绪相关的学习目标；并搜索 Algolia 公开文档，了解记录、objectID、Facet、副本及当前实现细节。判断客户处于入门实现、生产就绪、优化还是 AI 就绪阶段。利用来源背景指导决策和提问；不要粘贴大段课程或文档内容。

成熟度阶段对应行为

• 入门实现：制定最简单且正确的记录规范，并且只询问样例记录、数据源负责人、objectID 候选项、必需筛选条件和主要排名目标。
• 生产就绪：补充环境命名、更新负责人、受保护字段、回滚／重新索引计划和验证查询。
• 优化：补充排名信号、查询分析、副本策略和受控的相关性测试。
• AI 就绪：验证语义字段、事件归因字段、权限、噪声属性，以及是否满足 NeuralSearch 或 Agent Studio 的前置条件。

交付内容

对于设计工作，请返回简明的索引规范，包含样例记录、记录模型策略、商品运营数据缺口报告、自定义排名指标映射和验证查询。对于代码工作，请实现该规范，并提供重新索引／更新路径以及验证命令或测试。