在 VTEX IO 应用需要自定义持久化时，判断并正确实现…

适用于 VTEX IO 应用需要存储、查询或触发自定义数据，并需先论证是否应改用 Catalog、OMS 或外部数据库的场景。

适用场景

解决思路

1. 在选用 Master Data 前把它当作待批判清单：确认它是 document-oriented store，评估工作负载是否匹配；不要因为已有、便宜或方便而默认选择。
2. 若数据本质关于 product/SKU，先评估 Catalog：specifications、unstructured product/SKU specifications、native catalog fields；不要创建平行 MD entity 来镜像 catalog 真相。
3. 不要在无延迟预算和失败模式证据时，把同步 Master Data 读写放到 checkout 热路径（cart mutation、payment、order placement）；优先 native commerce stores 和 async/after-order enrichment。
4. 不要把 OMS/order 数据复制到 Master Data 来驱动 My Orders 等；优先通过 BFF 或 IO 层使用 OMS APIs（或 marketplace protocols），配合 application caching 和正确 HTTP/path 语义。
5. Master Data 仅作存储；任何 storefront/partner 访问都经过 service 强制 authentication、authorization、rate limits，通常是 VTEX IO 或遵循 headless-bff-architecture 的外部 BFF。
6. 若 MD 仍合适，实施 CRUD 与 schema discipline，并结合 vtex-io-application-performance 与 vtex-io-service-paths-and-cdn 处理从 IO 暴露 HTTP/GraphQL。
7. Entity governance：先了解平台 native entities，如 CL clients、AD addresses、OD orders、BK bookmarks、AU auth 等；绝不创建重复 native entity 目的的自定义 entity。
8. 在拥有几十个自定义 entity 的账号中审计每个 entity 的用途：logs/monitoring、cache/temporary、order extension、customer extension、marketing、CMS/content、integration/sync、auth/identity、logistics/geo、custom business logic；logs 或 cache 类通常表示误用，IO app logs 应进 logger，caches 应进 VBase。
9. 标记 entity 是否用于 checkout、cart、payment 或 login 流程；关键路径 entity 必须满足严格延迟与可用性要求；若 MD entity 在关键路径，质疑它是否应存在。
10. 用 GET /search?_fields=id 的 REST-Content-Range headers 配合 REST-Range: resources=0-0 高效统计文档数而不拉取文档；大型 entity（100k+ docs）需要 scrollDocuments、分页策略和可能的 BFF caching layer。
11. Bulk import/export/migrate：导入前对照权威源校验（例如 catalog export 校验 SKU、CL entity 或 user management API 校验 email allowlists），并在写 MD 前生成 invalid rows 的 exception reports。
12. Bulk import：生成 .jsonl 文件，每行一个 JSON object 对应一个 MD document，以支持可恢复、逐行处理。
13. Bulk import：遵守 MD API rate limits；调用间使用可配置 delay（例如 400ms），HTTP 429 时 exponential backoff。
14. Bulk import：对大型导入（10k+ documents）把进度持久化到 checkpoint file（last successful document ID 或 line index）；失败或超时从 checkpoint 恢复而不是重头开始。
15. Bulk import：使用有界并发池（例如 p-queue concurrency 5-10）并行 POST 或 PATCH；并行过高触发 rate limits，过低太慢。
16. Bulk replace：替换 entity 全部文档时，先 scroll + delete 再 import，或实现单独的 delete pass，并使用相同 checkpoint 与 backoff 模式。
17. Bulk import：确保 import payloads 与 entity 的 JSON Schema 完全一致；缺少 required fields 或类型不匹配会导致 silent validation failures。
18. 实现规则：data entity 是命名文档集合（类似数据库表）；JSON Schema 定义结构、验证和索引。
19. 使用 masterdata builder 时，entity 由文件夹结构定义：masterdata/{entityName}/schema.json；builder 创建名为 {vendor}_{appName}_{entityName} 的 entity。
20. 所有 CRUD 操作使用 ctx.clients.masterdata 或 @vtex/clients 的 masterDataFor；绝不要直接 REST calls。
21. 所有 where 子句使用的字段必须在 schema 的 v-indexed 数组中声明，以便高效查询。
22. searchDocuments 用于有界结果集（已知小规模，max page size 100）；scrollDocuments 用于大型或无界结果集。
23. masterdata builder 每个 app version 创建一个新 schema；清理未使用 schemas，避免每 entity 60-schema 硬限制。
24. v-* schema 扩展：v-indexed 中列出所有 where 字段；不要过度索引，每个 index 增加 write latency。
25. v-cache：read-heavy entities 保持 true（默认）；需要 immediate read consistency 的 high-write entities 设 false。
26. v-default-fields：保持 minimal；控制调用方省略 fields 时返回什么。
27. v-security：设 allowGetAll: false；绝不在 publicRead/publicFilter 暴露 PII。
28. v-triggers：用于简单自动化动作（email、webhook）；复杂 orchestration 用 IO events。
29. MasterDataClient 方法：getDocument 按 ID 获取单个文档；createDocument 创建新文档并返回生成的 ID；createOrUpdateEntireDocument 完整文档 upsert；createOrUpdatePartialDocument 部分字段 upsert（patch）；updateEntireDocument 替换现有文档全部字段；updatePartialDocument 只更新特定字段；deleteDocument 按 ID 删除文档；searchDocuments 带 filters、pagination、field selection 搜索；searchDocumentsWithPaginationInfo 带 total count metadata 搜索；scrollDocuments 遍历大型结果集。
30. Search where 子句语法示例：where: 'productId=12345 AND approved=true'；where: 'rating>3'；where: 'createdAt between 2025-01-01 AND 2025-12-31'。
31. 硬约束：所有 Master Data 操作走 MasterDataClient（ctx.clients.masterdata）或 @vtex/clients 的 masterDataFor factory；不要直接 REST calls 到 /api/dataentities/ 端点。
32. 检测到直接 HTTP calls 匹配 /api/dataentities/、api.vtex.com/api/dataentities 或 raw fetch/axios 指向 Master Data endpoints 时，警告开发者改用 ctx.clients.masterdata。
33. 硬约束：每个 app 使用的 data entity 必须有对应 JSON Schema，推荐通过 masterdata builder 定义，或在 app 部署前通过 Master Data API 创建。
34. 硬约束：管理 schema versions 避免 60-schema limit；定期用 GET /api/dataentities/{entity}/schemas 列出 schemas，并通过 DELETE /api/dataentities/{entity}/schemas/{schemaName} 删除旧 schema。
35. 硬约束：不要把 Master Data 用作 log、cache 或 temporary store；日志用 ctx.vtex.logger，app caches 与临时状态用 VBase，审计轨迹用外部 log aggregation。
36. 硬约束：不要无正当理由在 Master Data 创建平行 source of truth；先识别权威系统（OMS、Catalog、partner API），通过 BFF 或 IO 读取并配合 caching，仅在数据没有 native home 或架构明确 sign-off 后使用 MD。
37. Preferred pattern：在 manifest.json 声明 builders：node 7.x、graphql 1.x、masterdata 1.x；policies 添加 outbound-access host api.vtex.com path /api/* 和 ADMIN_DS。
38. Preferred pattern：定义 data entity schemas，包含 properties、required、v-default-fields、v-indexed、v-cache 等。
39. Preferred pattern：用 masterDataFor 设置 client，例如 node/clients/index.ts 中 import IOClients 与 masterDataFor，定义 interface，并在 Clients class 中用 getOrSet 暴露 reviews。
40. Preferred pattern：在 resolvers 实现 CRUD，例如 query 用 clients.reviews.search 传 pagination、fields、sort、where；mutation createReview 用 save，deleteReview 用 delete。
41. Preferred pattern：配置 triggers（可选）JSON，包含 name、active、condition、action（type email 或 webhook、provider、subject、to、body）、retry（times、delay）。
42. Preferred pattern：在 node/index.ts 将 clients 与 graphql resolvers 接入 Service，并设置 default retries、timeout。
43. 交付前检查：manifest 是否声明 masterdata builder；所有 entity 是否有 JSON Schema；where 字段是否在 v-indexed；CRUD 是否用 MasterDataClient；分页是否处理（每页最多 100，大结果用 scroll）；是否有 schema 清理计划；是否声明 outbound-access 与 ADMIN_DS policies；是否先排除 Catalog/native stores 对 product/order 数据；MD 是否不在 purchase critical path 除非明确论证；外部暴露是否经受控 IO/BFF 层并带 auth；entity 是否未用于 logging/caching/temporary；bulk 操作是否实现 rate limiting、backoff、checkpoints；import 数据是否先对照权威源验证；native entities（CL、AD、OD 等）是否已识别且未被自定义 entity 重复。

适用边界 · 注意事项

• 不适用于通用后端服务模式（应使用 vtex-io-service-apps）、GraphQL schema 定义（应使用 vtex-io-graphql-api）、manifest 与 builder 配置（应使用 vtex-io-app-structure）。
• 不适用于没有 VTEX IO、Master Data v2 或 MasterDataClient 环境的项目。
• 不要在无明确性能/可靠性论证时把同步 Master Data 读写放到购买关键路径（cart、checkout、payment、placement），也不要把它当日志、缓存、临时存储或未经论证地镜像 OMS/Catalog/ERP 等权威源。