开发 VTEX FastStore 店面时遵循的编码规则与…

在编写 FastStore 的 TypeScript/React 组件、section override、BFF 扩展或样式时，按此规则保证安全、正确并完成 CMS schema 同步。

适用场景

解决思路

1. 先理解问题再编码：明确用户目标、约束与缺失信息，信息缺失或有歧义时先向用户澄清，不要臆造 API、库或行为。
2. 未经用户要求不要给项目新增依赖。
3. 不要直接使用 Next.js Framework API，所有工具都必须通过 FastStore 框架使用。
4. 不要读取或编辑 `.faststore/` 文件夹，它是生成目录，每次构建都会被覆盖。
5. 组合 override 组件时始终使用 `@faststore/ui` 组件。
6. 所有 section override 必须使用来自 `@faststore/core` 的 `getOverriddenSection`。
7. 不要直接修改浏览器 history 或 location，始终使用 FastStore 已有的 hooks。
8. section key 的权威来源：`cms/faststore/components/*.jsonc` 中的 `"$componentKey"` 必须与 `<project_root>/src/components/index.tsx`（default export）中的对象 key 一致；不要把 `cms/faststore/schema.json` 当作 key 的权威来源，它是生成文件，绝不能手改。
9. 每个 section override 都必须在 `<project_root>/src/components/index.tsx` 中注册，key 与对应 `cms/faststore/components/cms_component__*.jsonc` 中的 `"$componentKey"` 相同。
10. `<project_root>/src/components/index.tsx` 只能使用 default export，不要使用 named exports。
11. `<project_root>/cms/faststore/schema.json` 不得编辑，它始终由 `vtex content generate-schema` 重新生成。
12. 如果 `.faststore/` 目录进入损坏状态（例如 GraphQL 优化失败后），用 `rm -rf .faststore` 删除并重启 `yarn dev`，CLI 会从头重新生成。
13. 创建 React 组件、SCSS、CMS 文件或 components index 文件（src/components/index.tsx）前，始终先用 shell（`ls`）验证文件是否存在，不要只信任 Read 工具（它可能返回已删除文件的缓存内容）。
14. 创建任何新文件（组件、SCSS、CMS schema）前必须运行 `ls -la <directory>`，确认目录结构存在、没有同名冲突文件、文件类型位置正确。
15. 对于 CMS 组件，同时检查 `src/components/` 和 `cms/faststore/components/`。
16. 严格遵循用户请求，使用 TypeScript，所有代码遵循 React 18，遵循 FastStore 框架架构，不要绕过它。
17. 利用用户提供的所有上下文（代码片段、架构、错误），不要忽略相关信息，优先使用 `@faststore/components` 或 `@faststore/ui` 中的组件。
18. 不要过度设计，提供满足需求的最简方案。
19. 对复杂决策简要说明理由，聚焦对另一位开发者有用的实用见解。
20. 代码输出：不要在 `.faststore/` 内创建或修改代码；使用符合项目配置的清晰格式；只在有帮助时加注释；遵循语言习惯与约定；优先提供完整可运行的示例。
21. 样式规则：所有样式使用 `.scss` 文件中的 SCSS 语法；不允许全局 SCSS；所有样式表必须声明在 wrapper class 内，作为 SCSS modules 在组件中导入并应用到 wrapper 元素。
22. 在 `.module.scss` 文件中，`@import` / `@use` `@faststore/ui` 组件样式必须嵌套在本地 class 内，根级导入会注入 `[data-fs-*]` 选择器破坏 CSS Modules 纯度（报错 "Selector [data-fs-*] is not pure"）。
23. 优先使用 FastStore 已有的 CSS 自定义属性（design tokens），仅在需要时创建新变量。
24. 当设计完全自定义时不要使用 `@faststore/ui` 组件：导入其样式再覆盖大部分视觉属性会与内部 `[data-fs-*]` 选择器产生优先级冲突，导致 `!important` 升级；应改用原生 HTML 元素加自定义 SCSS。仅在需要小幅调整或需要内置行为（loading 状态、校验、可访问性）时使用 `@faststore/ui`。
25. 将新的自定义 section 样式包裹在 `@layer components` 中，使 `@layer theme` 中的主题 token 无需 `!important` 即可覆盖它们，与原生 section 的级联顺序一致。
26. 假设 VTEX CLI 已全局安装，直接使用 `vtex`（例如 `vtex content …`），不要建议 `npx vtex`。
27. CMS schema 推荐同步方式：在项目根目录运行 `faststore cms-sync`，它会自动检测 `cms/faststore/components`（和 `cms/faststore/pages`）、生成 `cms/faststore/schema.json` 并上传（内部运行 `vtex content generate-schema` 和 `vtex content upload-schema`）；加 `--dry-run` 只生成不上传。
28. 如果 `faststore` 二进制不可用，安装 CLI：`npm install -g @faststore/cli`，或使用项目本地副本 `yarn faststore cms-sync`。
29. 不要使用遗留的 `yarn cms-sync` / `npm run cms-sync` 项目脚本（v3 风格全量同步），直接调用 `faststore cms-sync` 或使用下面的手动 `vtex content` 回退方案。
30. `faststore cms-sync` 的注意事项：需要最新的 `@vtex/cli-plugin-content`，旧版本（如 `1.0.4`）会报 `Failed to fetch the base schema from the registry. Not Found`，修复方式为 `vtex plugins install @vtex/cli-plugin-content`（已在 `1.10.2` 验证）。
31. 上传步骤是交互式的：提示输入 store ID 时，输入 `discovery.config.js` 中 `contentSource.project` 的值（不是硬编码的 `faststore`）；发布的 schema id 是 `{account}.{project}`，店面读取的正是该 id。
32. content-type 定义应放在 `cms/faststore/pages/` 中。
33. 范围说明：该合并命令覆盖 Content Platform（CP）项目（输出 `cms/faststore/schema.json`，检测 `components` + `pages` 目录）；`vtex content generate-schema` / `upload-schema` 对是同一流程的手动回退。当 `discovery.config.js` 中 `contentSource.type` 缺失或为 `"CMS"`（遗留 Headless CMS）时，`faststore cms-sync` 仍能正确运行（走内部不同路径 `vtex cms sync <project>`），但不产生 `schema.json`，store-ID 提示也不匹配 `contentSource.project`，上述 CP 专属步骤均不适用。
34. 每次修改 `cms/faststore/components/*.jsonc` 或 `cms/faststore/pages/*.jsonc` 后，在认为任务完成前必须完成以下序列：1) 生成并校验（dry-run）：在项目根目录运行 `faststore cms-sync --dry-run`（若 `faststore` 二进制缺失：`npm install -g @faststore/cli`，或用项目本地副本 `yarn faststore cms-sync --dry-run`），生成 `cms/faststore/schema.json` 但不上传。
35. 2) 校验：如果新增或重命名了 section，确认新的 `"$componentKey"`（或等价条目）出现在生成的 `cms/faststore/schema.json` 中；若缺失，修复 JSONC 或 `src/components/index.tsx` 中的注册并重新生成，绝不手动修补 `schema.json`。
36. 3) 同步（推荐）：校验通过后，不带 `--dry-run` 运行 `faststore cms-sync` 上传；上传步骤是交互式的（store ID 见第 4 步，非交互回退也见第 4 步）。
37. 4) 手动回退 / 非交互上传：如果 `faststore cms-sync` 不可用或需分步执行，用全局 VTEX CLI 生成并上传：`vtex content generate-schema -o cms/faststore/schema.json`，然后上传；提示 store ID 时输入 `discovery.config.js` 中 `contentSource.project` 的值（发布的 schema id 是 `{account}.{project}`，不是硬编码的 `faststore`）。自动化提示可用：`export STORE_ID=$(node -e "const c=require('./discovery.config.js'); console.log((c.contentSource&&c.contentSource.project)||'faststore')")`，再用 `expect -c 'spawn vtex content upload-schema cms/faststore/schema.json; expect "store ID"; send "$env(STORE_ID)\r"; expect -re "uploaded|confirm"; send "y\r"; expect -re "Are you sure|confirm"; send "y\r"; expect eof' 2>&1`（单引号防止 Tcl 误读 `$id` 等 `$` token，`$env(STORE_ID)` 由 Tcl 解释器求值）。
38. 5) 报告：明确说明上传是否成功；如果 CLI 提示 login、store ID 或确认，粘贴确切的提示或错误并说明人工下一步（例如运行 `vtex login`、确认账号与 `discovery.config.js` → `api.storeId` 一致），或指向 references/cms-schema-and-section-registration.md 中的非交互 `expect` 示例。
39. 理解上传做了什么与没做什么：`upload-schema` 在 Headless CMS 中注册 section 定义使其出现在编辑器中；section 在店面首页（或任何页面）显示前，必须在 Admin → Storefront → Content 中添加到该页面内容并照常保存/发布。唯一例外是项目自身策略通过 `cms/faststore/pages/*.jsonc` 预定义页面组成，但仍需按流程确保内容已发布。
40. 规范命令（项目根目录）：推荐 `faststore cms-sync`；手动回退两步 `vtex content generate-schema -o cms/faststore/schema.json` 和 `vtex content upload-schema cms/faststore/schema.json`。
41. 每个请求遵循工作流：1) 理解问题——识别用户目标、约束与缺失信息；2) 分析——确定根本问题并考虑多种方案；3) 决策——按 FastStore 框架能力选择最佳方案；4) 提供——代码 + 解释（如需要）+ 备选方案（可选）；5) 复查——确认没有在 `.faststore/` 内产生代码、代码由 `@faststore/components` 的 atoms 和 molecules 组成、若 CMS JSONC 或 pages JSONC 有改动则已运行 `faststore cms-sync`（或手动 generate-schema + upload-schema 回退）、已校验 `schema.json`（适用时检查新 `$componentKey`）、已在会话内尝试上传并报告结果（成功或确切 CLI 提示/错误 + 下一步）、对于新 CMS section 已明确仍需 Admin → Storefront → Content（或项目 `pages` JSONC 策略）才能让 section 出现在线上页面。
42. 响应格式（适当时）：Problem Understanding（用户需求简述）、Solution（代码或步骤）、Explanation（为何有效）、Optional Improvements（更好的模式、优化等）。
43. 按需加载参考文件，不要一次性全部加载：references/project-structure-routes-and-config.md（映射仓库结构、默认 URL 路由、`faststore dev`/`build` 如何合并定制、配置 `discovery.config.js`、文件命名约定）；references/section-overrides-and-custom-sections.md（`getOverriddenSection` 模式、注册组件、class-only override、替换内部 slot、memoized override、从零构建新的 CMS-backed section）；references/graphql-types-queries-and-mutations.md（只读 API 目录：内置 root Query/Mutation 字段、枚举、类型字段列表）；references/extending-graphql-with-custom-resolvers.md（在 `src/graphql/vtex/` 添加字段或在 `src/graphql/thirdParty/` 添加新操作、接线 resolver、`Server*`/`Client*` fragments、用 `usePDP`/`useQuery`/`useLazyQuery` 消费数据）；references/scss-styling-and-design-tokens.md（SCSS module 规则、`src/themes/custom-theme.scss` 中的主题与 CSS 变量、针对内部 UI 结构的样式覆盖）；references/cms-schema-and-section-registration.md（VTEX CMS：`cms_component__*.jsonc` + `index.tsx` 作为权威来源、生成的 `schema.json`、推荐的 `faststore cms-sync` 及手动 `vtex content` 回退、store ID = `contentSource.project`、Admin → Content 与 `pages` JSONC、scopes、仅 CMS props）；references/analytics-events-and-gtm.md（`@faststore/sdk` analytics：`sendAnalyticsEvent`、`useAnalyticsEvent`/handler 组件、在 `discovery.config.js` 设置 `gtmContainerId`）；references/injecting-head-scripts-and-meta-tags.md（通过 `src/scripts/ThirdPartyScripts.tsx` 注入自定义 `<head>` 内容，如验证 meta 标签、内联脚本、Partytown；GTM 主要不在此处，用 `discovery.config.js`）；references/native-sections-and-overridable-slots.md（仅查询：内置全局 section 列表及 `getOverriddenSection` 的确切 slot 名）；references/ui-components-and-data-attributes.md（`@faststore/ui` 中的 primitives 及 `data-fs-*` 属性参考，用于精确 SCSS 选择器）；references/search-facets-and-usesearch-api.md（搜索与 facets 参考、常见陷阱、访问搜索状态、在 PLP/Search 自定义 section 中切换过滤器）；references/faststore-v3-v4-migration.md（从 FastStore v3 升级到 v4 的分步迁移指南：Node 24 要求、`package.json` 变更、`discovery.config.js` plain-config 规则、SCSS `@import` → `@use`/`@forward` 迁移、GraphQL 导入迁移、v3 patch 评估、验证、迁移后 CMS 同步）。

适用边界 · 注意事项

• 不适用于非 VTEX FastStore 项目（如普通 Next.js/React 项目），因为规则依赖 FastStore 框架、`@faststore/ui`、`@faststore/core` 与 VTEX CLI。
• 不适用于未安装 VTEX CLI 或没有 VTEX 账号/Content Platform 访问权限的场景，CMS schema 同步与上传无法完成。
• 不适用于遗留 Headless CMS（`contentSource.type` 缺失或为 `"CMS"`）项目中的 CP 专属步骤，此时 `faststore cms-sync` 不产生 `schema.json`，store-ID 提示也不匹配 `contentSource.project`。