跨模块 VTEX 电商架构设计时，用…

当需要在 VTEX 店面、IO、Headless、Marketplace、支付等多个模块之间做跨领域架构决策、方案评审或 RFP 级技术结构设计时，用三支柱框架对齐方向并把实现细节路由到对应产品技能。

适用场景

解决思路

1. 在会话中先让团队对齐三大支柱框架：Technical Foundation（可靠性、信任、诚信；安全、基础设施、合规）、Future-proof（创新、简洁、效率；可扩展可适配方案）、Operational Excellence（准确、问责、数据驱动改进；流程与客户体验）。需要扩展框架措辞或最新叙述时使用 Well-Architected Commerce MCP。
2. 把每个重大决策归类到一个或多个支柱下；如果某个选择无法映射到任何支柱，质疑其必要性。
3. 当扩展平台（VTEX IO、Master Data、集成）时，按路由表把实现细节交给对应产品技能：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 技能。并记录该选择如何支撑 Future-proof 与 Operational Excellence 且不削弱 Technical Foundation。
4. 遵守跨领域 VTEX 规则：原生与开箱即用优先于 VTEX IO——优先使用原生 VTEX 能力与配置，仅当没有合适原生路径时才用 IO；若仍选 IO，必须记录“为何不用原生”。
5. 对商品化能力优先使用平台原生行为；把自定义工作留给差异化能力或真实缺口，而不是用来替代流程或所有权修复。
6. 集成纪律：优先减少跳数、明确所有权、API 中心化设计；详细模式见 IO、headless 和 marketplace 技能。
7. 在自定义代码不可避免处优先减少集成跳数：每一跳都增加故障模式与运维负担。额外服务或后端只有在隔离故障域或明确团队边界时才合理，不应默认添加。
8. 架构选择明确后，把执行分配给产品轨道技能；本技能定方向，产品技能执行 VTEX 特定契约。
9. 运维纪律要求可定义的指标与所有权（谁运行、如何检测事件、如何发布变更）；未文档化的“尽力而为”运维即使设计精简也违反 Operational Excellence。
10. 硬约束：不得为速度绕过 Technical Foundation——安全、凭据处理、PCI 范围、私有 API 访问必须遵循 VTEX 与行业基线；将 VTEX_APP_KEY/VTEX_APP_TOKEN、原始卡数据或购物者会话令牌放入浏览器代码、公开仓库或日志中的设计必须停止并重新设计（如 headless BFF、支付 Secure Proxy）。正确做法：分类数据与 API；密钥与私有调用保留在服务端；参考所选集成风格的 PCI 与认证指南。决策日志示例：私有 VTEX API → 仅服务端（BFF 或 IO 服务）；卡数据 → 仅 Payment Provider Protocol / Secure Proxy 模式。
11. 硬约束：Future-proof 意味着有理由的复杂度，而非最大化解耦——每个新服务、队列或数据存储必须有明确所有者、故障模式以及绑定到支柱的理由（如隔离、扩展、监管边界）。检测：图中新增“为了灵活性”的框但无支柱映射 → 质疑；两个服务本可合并为一个模块清晰的 VTEX IO 应用 → 合并或推迟。正确做法：记录“服务 X 负责合作伙伴 webhook 转换；Technical Foundation：审计日志；Future-proof：可替换适配器；Ops：值班轮换 Z”。添加服务前自问：哪些支柱要求它？缺失它会怎样失败？原生/开箱即用、现有 BFF 或最小 IO 面能否覆盖？
12. 硬约束：VTEX IO 扩展必须先穷尽原生/开箱即用选项——用 IO 实现已原生或开箱即用（或可通过配置与标准集成满足）的能力且无书面例外理由，会造成长期成本、升级风险和运维债务。检测：提案先写“我们将为 X 构建 IO 应用”而未列出考虑过的原生/开箱即用替代方案；Help Center 或 Developers 指南描述标准路径时没有书面“为何不用原生”。正确做法：决策日志记录原生/开箱即用选项已评估 → 因[具体缺口]被拒 → IO 范围最小化到该缺口。IO 前原生/开箱即用检查：VTEX 为此提供了什么（admin、模块、API、合作伙伴应用）？若仍要构建 IO：究竟什么无法原生完成？
13. 硬约束：Master Data 不是通用或结账关键数据存储——在不理解其存储模型、限制与一致性的情况下使用 MD，或把它作为所有自定义数据的默认存储，或放在购买关键路径上，会带来规模化下的延迟、可靠性与支持问题。检测：同步订单流在每次购物车变更时调用 MD；“把所有自定义字段放进 MD”而无模式纪律；在评估 catalog、profile 或 OMS 原生选项之前就选 MD。正确做法：遵循 vtex-io-masterdata（存储适配性、catalog 优先、BFF）；实体范围限定在有理由的用例；购买期间非必要 MD 访问放在关键路径之外或使用异步模式。新数据用 MD 前自问：Catalog、Checkout、Profile 或其他原生存储能否承载？访问是否在购买热路径上？若是，重新设计或给出理由。
14. 首选模式：1) 在会话中让团队对齐三大支柱；需要扩展框架措辞或最新叙述时使用 Well-Architected Commerce MCP。2) 把 IO、MD 和 marketplace 关注点路由到路由表——原生/开箱即用优先；然后是有文档理由的范围化 IO 或 MD。3) 区分差异化与运维缺口：对每个自定义构建标注“战略差异化”还是“流程/运维修复”；若是后者，优先流程或原生工具而非代码。4) 产出简短决策日志：涉及的支柱、原生 vs IO vs MD 选择、适用处的“为何不用原生”、开放风险。5) 为每个实现流附上相关产品轨道指南（店面、支付、IO、marketplace）。6) 上线前重新审视 Operational Excellence：商品化能力放在平台上，团队聚焦支持与差异化，加上指标、发布流程与事件响应。
15. 避免常见失败模式：元技能过度使用（对已由产品技能完全定义的问题花架构叙述，如 PPP 幂等规则）；支柱表演（幻灯片标注三支柱但不改变具体决策或所有权）；IO 默认偏见（未证明原生/开箱即用无法满足就伸手用 VTEX IO，把自定义当第一步）；MD 当 Postgres（无建模地对每个实体用 Master Data，或让结账耦合同步 MD 读写）；误解简洁（把“简单架构”理解为“一个做所有事的大 IO 应用”而非“最小自定义面、最大原生利用”）；技术替代流程（自动化或编码绕过破损的运维工作流，而非修复所有权、SLA 或培训）；商品化定制（客户技术团队维护 VTEX 已作为标准产品提供的行为的定制实现，饿死真正的差异化）；缺失交接（架构文档没有指向开发者必须遵循哪些产品技能和哪些官方 VTEX 指南）。
16. 用评审清单自检：Technical Foundation 关注点（认证、密钥、PCI 范围、私有 API）是否明确处理？对每个 VTEX IO 扩展：是否先评估原生/开箱即用，选择 IO 时是否有书面“为何不用原生”？对 Master Data 使用：团队是否理解 MD 架构，MD 是否在购买关键路径之外（除非有强理由）？每个自定义组件是否标注差异化 vs 运维/流程缺口，是否先考虑流程修复再写新代码？Future-proof 是否成立：每个新服务、队列或数据存储有所有者、故障模式和基于支柱的理由，无无动机蔓延？集成跳数是否最小化，额外服务是否由故障隔离或团队边界证明合理？Operational Excellence 是否显示商品化能力在平台上、支持与差异化焦点清晰，加上指标、监控和发布/事件所有权？每个实现流是否映射到产品轨道技能？有平台特定约束的领域是否链接了官方 VTEX 文档？
17. 参考官方文档：Headless commerce 概览（店面集成模型与平台边界）、工程最佳实践（与 Technical Foundation 对齐的可扩展性与 IO 开发实践）、Master Data v2 JSON Schema 使用（选择 MD 前的存储模型与模式行为）、避免速率限制错误的最佳实践（可靠集成 VTEX API）、VTEX 中的 PCI DSS 合规（支付安全基线）、应用密钥使用最佳实践（API 密钥卫生与信任）。

适用边界 · 注意事项

• 当任务已经局部化、由单一产品技能完全定义时，不要用本技能替代产品技能（如“实现 PPP 退款”→支付轨道；“Feed v3 vs Hook”→marketplace 轨道）。
• 不要把它当作产品技能说明书摘要来用；它是跨领域决策与评审的方向框架，具体实现契约由产品技能执行。
• 不要在没有 VTEX 平台上下文时套用；本技能特定于 VTEX 模块与 Well-Architected Commerce 框架。