为 VTEX Sales App 构建/定制/部署扩展时…

在 FastStore 项目中为 VTEX Sales App 开发 cart/PDP/menu 扩展点，从环境检查到代码生成、文档、构建部署的完整流程。

适用场景

解决思路

1. Step 0 检查前置条件：项目根目录必须包含 biome.json、faststore.json、package.json、tsconfig.json、turbo.json；若缺失则停止，先运行 `npx @vtex/fsp-cli init`（提示应用名时输入名称或回车用默认值），然后 `cd <application-name> && yarn`。
2. Step 0 检查 Sales App 模块：在 FastStore 项目内需存在 Sales App 工作区（通常在 packages/sales-app），含 src/、package.json、tsconfig.json；检查根 package.json 的 "workspaces" 是否包含 sales-app 路径。若缺失则停止，运行 `yarn add @vtex/sales-app -D -W`，再运行 `npx fsp create`（依次输入 account name → "Sales App" → 路径），把路径加入根 package.json 的 "workspaces" 数组，最后 `yarn install`。两个前置条件都确认前不要进入发现或代码生成。
3. Step 1 发现需求：根据关键词识别用例，提出追问，确定 API 认证策略；若用户提供 API 文档（URL、OpenAPI/Swagger 文件、Markdown 或内联文本），先摄取以提取端点细节和响应结构，跳过等价的手动问题，并与用户确认提取的信息。加载 references/discovery-and-use-cases.md。
4. Step 2 需求与计划：把需求映射到扩展点 + hooks + 模板，展示计划并列出将创建的文件：components/<ComponentName>.tsx、components/<ComponentName>.css（纯 CSS，绝不用 .module.css）、index.tsx，等待用户批准。
5. Step 3 代码生成与验证：生成 <ComponentName>.tsx、<ComponentName>.css（纯 CSS，绝不用 .module.css）、index.tsx。生成前加载 references/code-templates-and-patterns.md（组件模板、含完整 Sales App 设计系统的 CSS 模板、index.tsx 模板、类型生成规则、自定义 fetch hook 模式）、references/extension-points-hooks-and-types.md（hook 返回类型与 TS 定义）、references/static-analysis-rules.md（沙箱安全、CSS 包含、React 性能规则，用 @vtex/fsp-analyzer 检查）、references/design-guidelines.md（渲染 UI 文本时用 sentence case，使用图标时用 Phosphor Icons）。若 Step 1 摄取了 API 文档，从提取的响应结构生成 TypeScript 接口并替换 ${DATA_INTERFACE} 占位符；若调用 2+ 端点，把 fetch 逻辑抽到自定义 hook。按 code-templates-and-patterns.md 的 12 点清单验证，修复所有违规后再展示代码，并向用户提示警告。
6. Step 4 文档：在 Sales App 包内生成 docs/<ExtensionName>.md（必要时创建 docs/ 文件夹），加载 references/documentation-template.md 按 9 节结构填写。
7. Step 5 本地测试：提供本地开发命令和测试 URL，加载 references/local-dev-build-and-deploy.md。
8. Step 6 构建与部署：执行构建命令并提供部署指南，加载 references/local-dev-build-and-deploy.md。
9. 扩展点选择：cart.cart-list.after（Cart，useCart/useExtension，无布局位移）、cart.cart-item.after（Cart，useCart/useCartItem/useExtension，有布局位移）、cart.order-summary.after（Cart，useCart/useExtension，有布局位移）、pdp.sidebar.before（PDP，usePDP/useCart/useExtension，有布局位移）、pdp.sidebar.after（PDP，usePDP/useCart/useExtension，有布局位移）、pdp.content.after（PDP，usePDP/useCart/useExtension，有布局位移）、menu.item（Menu，useExtension，无布局位移）、menu.drawer-content（Menu，useCurrentUser/useExtension，无布局位移）。
10. Hook 可用性：useCart 用于所有 cart + PDP 扩展；useCartItem 仅用于 cart.cart-item.after；useCurrentUser 仅用于 menu.drawer-content；usePDP 仅用于 PDP 扩展；useExtension 用于所有扩展点。
11. 模板选择：无 API 且无 hooks → simple 模板；无 API 有 hooks → hook 模板；有 API 无认证 → API 模板；有 API 用 VTEX IO proxy → IO proxy 模板（推荐）；有 API 直接认证 → direct auth 模板（不安全，需警告用户）；提供 API 文档 → 从提取的响应结构生成 TypeScript 接口，无文档 → 使用 ${DATA_INTERFACE} 占位符。
12. API 认证策略：推荐用 VTEX IO Proxy App，IO 应用在服务端保存密钥，扩展用 credentials: 'include' 和相对路径（/_v/my-api/data）；不安全方案是 Direct Auth，密钥在前端代码中可见于浏览器，仅用于测试/开发。
13. 硬约束：组件必须返回 JSX.Element 而非 null（defineExtensions 期望返回 Element），无数据时返回 (<></>)；使用前守卫可选属性 CartItem.manualPrice、CartItem.productRefId、CartItem.attachments（用 ?.、??、&& 或 != null）；useCartItem().item 可能为 undefined，使用前用 if (!item) 守卫；index.tsx 必须使用 @vtex/sales-app 的 defineExtensions；扩展点名称必须精确匹配 8 个固定 ID 之一，否则静默失败；hooks 必须在兼容的扩展点中使用，否则运行时抛错。
14. 常见失败模式：跳过前置检查；不展示计划；跳过文档；臆造 API 响应类型（有文档就从文档推导，无文档就向用户要示例 JSON）；忽略用户提供的 API 文档；2+ 端点时在组件体内内联 fetch（应抽到 hooks/use{Purpose}.ts）；把代码放在 packages/sales-app/src/ 之外（不会被打包）。
15. 审查清单：FastStore 已安装？Sales App 模块已安装？发现完成且用例已识别？执行计划已获用户批准？扩展点有效？hooks 与扩展点兼容？文档已生成在 docs/<ExtensionName>.md（9 节）？若提供 API 文档，TS 接口与文档响应结构一致？若用 2+ 端点，fetch 逻辑已抽到 hooks/？构建通过 `yarn fsp build {account} sales-app`？本地测试 `yarn fsp dev {account}`？组件返回 JSX.Element 而非 null？可选属性已守卫？useCartItem().item 已检查 undefined？index.tsx 已配置 defineExtensions？

适用边界 · 注意事项

• 不要用于常规 FastStore 店面定制（应使用 faststore-storefront 技能）
• 不要用于构建 VTEX IO 应用（应使用 vtex-io-* 技能）
• 不要用于 Sales App 核心开发或框架修改