architecture-well-architected-commerce

VTEX 上架构完善的商务

何时适用此技能

当任务涉及 VTEX 商务功能的跨领域问题或决策时，使用此技能；如果某个产品技能已完整定义相关工作，则无需使用此技能。

• 定义或评审解决方案架构（店面模式 + 集成 + 运营）。
• 在 VTEX 原生功能与自定义服务（IO 应用、外部 BFF、中间件）之间做出选择。
• 开展架构或就绪度评审（安全基线、可扩展性态势、可观测性、交付流程）。
• 为涉及 FastStore、Headless、VTEX IO、Marketplace、Payments 和/或任何其他 VTEX 模块的工作确定范围。

不要将此技能用作产品技能的替代品，尤其是任务范围已明确限定时（例如，“实现 PPP 退款” → 支付方向；“Feed v3 与 Hook” → Marketplace 方向）。

三大支柱（框架）

这三大支柱构成了每项架构决策的架构完善的商务视角。以下概要遵循内部框架的叙述；如需查看完整目标、核心价值观和重点关注领域，请使用 Well-Architected Commerce MCP（以及项目的权威框架文档）。

技术基础

目标： 构建安全、可靠且合规的基础，赢得信任。

核心价值观： 可靠性（性能稳定）、信任（流程透明且责任明确）、完整性（以合乎道德的方式处理数据、代码和资源）。

关键领域（示例）： 高级安全（数据保护、交易安全、威胁意识）；可靠基础设施（可用性、可扩展性、恢复能力）；合规性（法规、审计跟踪、监控）。持续学习让指导内容与技术发展及 VTEX 的发展方向保持同步。

Future-proof 或 Operational Excellence 中的任何内容都不会降低此支柱的要求。

面向未来

目标： 随着业务和平台不断发展，解决方案仍能保持适应性和可维护性。

核心价值观： 创新（遵循当前 VTEX 和行业最佳实践）、简洁（统领全局的价值——将自定义范围控制在最低限度，确保整个解决方案协调一致）、效率（优化投入和平台使用）。

关键领域（示例）： 可扩展的解决方案；对业务和市场变化的适应能力；模块化 / 组合式设计；快速部署（敏捷交付、CI/CD）；系统集成（以 VTEX 为核心、API 优先的连接方式）。

卓越运营

目标： 以数据为依据做出决策，并以责任明确的方式执行项目。

核心价值观： 准确性、完整性、责任担当、数据驱动决策（以及作为一项准则的卓越运营）。

关键领域（示例）： 流程优化（效率、精益、自动化）；数据驱动策略（分析、预测性洞察、监控）；绩效改进（VTEX 洞察、持续监控、敏捷性）；客户体验（个性化、反馈、全渠道）。

路由到产品方向

平台特定的实现方式应放在产品技能中，而不是这个元技能中。完成支柱对齐后，请使用：

主题	方向技能
VTEX IO 服务路径、边缘/CDN 行为、Cache-Control 与数据范围的区别	vtex-io-service-paths-and-cdn
VTEX IO 应用性能（缓存层、AppSettings、并行获取、租户范围的内存键）	vtex-io-application-performance
Master Data 存储适用性（质疑 MD 是否是合适的位置）、购买路径、BFF、单一事实来源	vtex-io-masterdata
Marketplace 履约、模拟、集成流程	marketplace-fulfillment（以及相关 marketplace 技能）

跨领域 VTEX 规则（仍处于架构层面）：

1. 优先选择原生功能和开箱即用功能，而非 VTEX IO — 优先考虑 VTEX 原生功能和配置，再考虑 VTEX IO 扩展。仅在没有合适的原生方案时才使用 IO；如果仍选择 IO，请记录为何不采用原生方案。

2. 简单性与通用能力 — 对于通用功能，优先采用平台原生行为；自定义工作应留给差异化功能或实际缺口，而不是用来替代流程或所有权方面的修正。

3. 集成规范 — 优先选择更少的跳转、清晰的所有权和以 API 为中心的设计（参见“面向未来的系统集成”）；详细模式见 IO、无头和 marketplace 技能。

决策规则

1. 将每项重大决策归类到一个或多个支柱下（参见三大支柱（框架））。如果某个选择无法映射到任何支柱，应质疑它是否有必要。
2. 扩展平台时（VTEX IO、Master Data、集成），请使用路由到产品方向表——使用这些技能实现缓存、路径、MD 用法和 marketplace 流程，并记录该选择如何支持面向未来和卓越运营，且不削弱技术基础。
3. 在仍需自定义代码时，优先减少集成跳转：每增加一个跳转，都会增加故障模式和运维负担。只有在额外服务或后端能够隔离故障域或明确团队边界时，它们才是合理的，而不应默认采用。
4. 架构选择明确后，将执行工作分配给产品方向技能（参见路由到产品方向和相关技能）。此技能负责确定方向；产品技能负责落实 VTEX 特定契约。
5. 运维规范要求指标和所有权明确可定义（由谁运行、如何检测事件、如何发布变更）。即使设计精简，未记录的“尽力而为”运维也违反卓越运营。

硬性约束

约束：不得为了提速绕过技术基础

安全、凭据处理、PCI 范围和私有 API 访问必须遵循 VTEX 和行业基线。暴露密钥、扩大 PCI 范围或从不受信任的客户端调用私有 API 的架构捷径，绝不能作为提升速度的权衡方案。

为何重要——数据泄露、欺诈和账户遭入侵会摧毁客户信任，还可能使整个项目的合规状态失效。

检测——如果设计将 VTEX_APP_KEY/VTEX_APP_TOKEN、原始银行卡数据或购物者会话令牌放在浏览器代码、公共仓库或日志中 → 立即停止，并使用产品技能（例如，无头 BFF、支付 Secure Proxy）重新设计。

正确做法——对数据和 API 进行分类；将密钥和私有调用保留在服务端；参考所选集成方式对应的 PCI 和身份验证指南。

Architecture decision log:
- Private VTEX APIs → server-side only (BFF or IO service).
- Card data → Payment Provider Protocol / Secure Proxy patterns only.

错误做法——“为了提速，我们会从 SPA 调用 Checkout OMS”或“为了开发方便，将应用令牌存储在 NEXT_PUBLIC 中”。

约束：面向未来意味着复杂度有据可依，而非拆分至极致

每个新增服务、队列或数据存储都必须明确负责人、故障模式以及与某项支柱（例如隔离、规模或监管边界）相关的原因。无节制地增加服务违反了简单性核心价值。

为何重要——缺乏文档的分布式系统将变得无法运维、调试或升级；它们会增加成本并延长事故处理时间。

检测——如果图表中新增了一个“为了灵活性”的方框，却没有说明它对应哪项支柱 → 提出质疑。如果两个服务可以合并为一个模块划分清晰的 VTEX IO 应用 → 合并或推迟。

正确做法——记录：“服务 X 负责合作伙伴 webhook 转换；技术基础：审计日志；面向未来：可替换适配器；运维：值班轮换 Z。”

Before adding a service:
1. Which pillar(s) require it?
2. What fails if it is absent?
3. Can native/OOTB, existing BFF, or a minimal IO surface cover it?

错误做法——默认采用“微服务架构”，却没有运维模型，也未考虑产品技能中说明的 VTEX 集成限制。

约束：只有在原生功能和现成选项都用尽后，才能扩展 VTEX IO

若某项功能已经通过原生功能或现成选项（OOTB）实现，或可通过配置和标准集成满足，却选择使用 VTEX IO 来实现，且没有记录例外理由，就会带来长期成本、升级风险和运维负担。

为何重要——重复实现会偏离平台演进，可能在升级时出故障，还会占用本应用于差异化的工程资源。

检测——方案一开始就提出“我们将为 X 构建一个 IO 应用”，却没有先列出评估过的原生功能/现成选项。帮助中心或开发者指南介绍了标准方案，却没有书面说明“为何不采用原生功能”。

正确做法——在决策日志中记录：已评估原生功能/现成选项 → 因为[具体缺口]而放弃 → 将 IO 范围缩至仅解决该缺口。

Native/OOTB check before IO:
1. What does VTEX ship for this (admin, module, API, partner app)?
2. If still building IO: what exactly cannot be done natively?

错误做法——“我们总是通过 IO 定制”或“IO 比学习原生功能简单”，却没有证据证明原生功能无法满足要求。

约束：主数据不是通用数据存储，也不是结账关键路径上的存储

不了解主数据的存储模型、限制和一致性就使用它，或将其用作所有自定义数据的默认存储，或将其放在购买关键路径上，都可能导致规模化后的延迟、可靠性和支持问题。

为何重要 — MD 针对有文档说明的实体模式进行了优化，并非用于结账过程中的任意 OLTP；误用会影响营收和稳定性。

检测方式 — 同步订单流程在每次购物车变更时都会调用 MD；没有任何架构规范地“将所有自定义字段放进 MD”；尚未评估目录、档案或 OMS 原生选项，就选择了 MD。

正确做法 — 遵循 vtex-io-masterdata（存储适配性、目录优先、BFF）；仅将实体用于有充分理由的场景；购买过程中非必要的 MD 访问应避开关键路径或采用异步模式。

Before MD for new data:
1. Can Catalog, Checkout, Profile, or another native store hold this?
2. Is access in the hot path of purchase? If yes, redesign or justify.

错误做法 — “所有内容都用 MD”，或在没有确凿性能证明的情况下，于峰值负载期间因 MD 往返调用而阻塞结账。

首选模式

1. 在会议中让团队就三大支柱（框架）达成一致；需要扩展版框架表述或最新阐释时，使用 Well-Architected Commerce MCP。
2. 将 IO、MD 和 marketplace 相关问题引导至 Routing to product tracks 表——优先采用原生/OOTB 方案；然后再考虑范围明确且有文档记录理由的 IO 或 MD 方案。
3. 区分差异化优势与运营缺口：对每个自定义构建，标注其属于战略差异化优势还是流程/运营修复；如果属于后者，应优先考虑流程或原生工具，而不是编写代码。
4. 生成简短的决策日志：记录涉及的支柱、原生方案与 IO、MD 方案的选择、适用情况下“为何不选原生方案”，以及未解决的风险。
5. 为每条实施路径（店面、支付、IO、marketplace）附上相关的产品路径指南。
6. 上线前重新审视运营卓越：将标准功能交由平台提供，让团队专注于支持和差异化优势，并落实指标、发布流程和事件响应。

常见失败模式

• 过度使用元技能 — 对产品技能已完整规定的问题（例如 PPP 幂等性规则）仍花费大量篇幅阐述架构。
• 支柱作秀 — 只是在幻灯片上标出三大支柱，却没有改变具体决策或职责归属。
• 默认选择 IO 的倾向 — 尚未证明原生/OOTB 方案无法满足需求，就直接采用 VTEX IO；将自定义视为第一步。
• 把 MD 当作 Postgres — 不建模就用 Master Data 存储所有实体，或让结账依赖同步 MD 读写。
• 误解简单性 — 将“简单架构”理解为“一个大型 IO 应用包办一切”，而不是“尽量减少自定义范围，最大限度发挥原生能力”。
• 技术先于流程 — 不先明确职责、SLA 或培训来修复有问题的运营工作流，而是用自动化或代码绕开问题。
• 对标准功能进行自定义 — 客户的技术团队维护 VTEX 已作为标准产品提供的行为的定制实现，导致真正的差异化优势得不到关注。
• 缺少交接指引 — 架构文档没有指出开发人员应遵循哪些产品技能和哪些 VTEX 官方指南。

审查清单

• 是否明确处理了技术基础方面的关注点（身份验证、密钥、PCI 范围、私有 API）？
• 对于每个 VTEX IO 扩展：是否先评估了原生／开箱即用方案？若选择 IO，是否有书面说明“为何不采用原生方案”？
• 对于 Master Data 的使用：团队是否了解 MD 架构（见参考资料）？除非有充分理由，否则 MD 是否不在购买关键路径上？
• 每个自定义组件是否标明属于差异化功能还是运营／流程缺口？是否在编写新代码前考虑了流程改进？
• 是否符合面向未来的要求：每个新增服务、队列或数据存储都具备负责人、故障模式和基于支柱的理由，且没有缺乏依据的扩张？
• 是否尽量减少了集成跳转？额外服务是否有故障隔离或团队边界方面的合理依据？
• 卓越运营是否体现了由平台提供的通用能力、对支持工作和差异化功能的明确关注，以及指标、监控和发布／事件负责人？
• 是否已将每条实施工作流对应到一项产品轨道技能？
• 对于存在平台特定限制的领域，是否链接了官方 VTEX 文档？

相关技能

• vtex-io-service-paths-and-cdn — service.json 路径、边缘／CDN 和会话行为。
• vtex-io-application-performance — LRU/VBase、AppSettings、并行获取、共享 Pod 上的租户键。
• vtex-io-app-contract — IO 清单、构建器、策略（仅在排除原生／开箱即用方案后使用）。
• vtex-io-masterdata — 严格审视 Master Data v2 的存储适配性、BFF、单一事实来源。
• headless-bff-architecture — 无头架构的 BFF 和凭证边界。
• payment-pci-security — PCI 和 Secure Proxy 限制。
• faststore-storefront — GraphQL 扩展和数据层。
• marketplace-order-hook — Marketplace 订单集成模式。

参考资料

• 无头商务概述 — 店面集成模型和平台边界
• 工程最佳实践 — 与技术基础相一致的可扩展性和 IO 开发实践
• 在 Master Data v2 中使用 JSON Schema — 选择 MD 前了解其存储模型和架构行为
• 避免速率限制错误的最佳实践 — 与 VTEX API 进行可靠集成
• VTEX 中的 PCI DSS 合规性 — 支付安全基线
• 使用应用程序密钥的最佳实践 — API 密钥卫生和信任