第 7 课：用 TRAE 分里程碑开发云南大蒜 B2B 网站

1. 这一节解决什么问题

前六节已经有证据、PRD、规则和 UI 规格。本节把它们变成可运行代码，重点不是背 React，而是学会让 TRAE 每次完成一个可验证里程碑，并能判断路由、内容、组件和响应式是否正确。

2. 学完要拿到什么结果

• 本地可运行的 React + TypeScript + Vite 项目。
• /zh 与 /en 双语首页和对应导航。
• 产品分类、3 个产品详情、公司/产地供应、质量、市场/流程、FAQ、联系页。
• 集中的中英文内容数据与可复用组件。
• 每个里程碑都有构建结果和 Git 提交。

3. 对应的开源对标及链接

• export-website-template：仅研究外贸多页面、集中配置和询盘入口；不复制代码。
• Startup Next.js：MIT；研究共享导航、页脚、多页面组织。
• shadcn/ui 与 21st.dev：研究可复用组件与状态设计，不复制组件代码。
• TRAE Agent 官方文档：按计划、上下文、工具和验证推进。

4. 完整图文课程正文

4.1 先读示范项目，不先叫 AI 重写

示范站位于 cases/garlic-b2b-website/。src/data/siteData.ts 是内容事实层；src/components/ 是可复用体验；src/pages/ 是页面；src/styles.css 是设计系统；public/ 放 SEO 与部署文件。新手先理解这些边界，后续改行业只需替换内容与少量组件，而不是改遍所有页面。

4.2 路由约定

/:lang                         首页
/:lang/products                产品分类
/:lang/products/:slug          产品详情
/:lang/about                   公司、产地、种植与供应能力
/:lang/quality                 质量控制与证书展示规则
/:lang/markets                 出口意向市场与合作流程
/:lang/faq                     FAQ
/:lang/contact                 RFQ 与联系方式

lang 只接受 zh 或 en；未知语言回到英文首页；未知产品显示有返回入口的 404，而不是空白页。语言切换保留当前页面和产品 slug。

4.3 集中内容避免双语漂移

产品对象包含 slug、中英文名称、描述、要点、拟议规格、包装和声明。组件不硬编码商业事实，只接收数据。更新一类产品时，中文和英文在同一对象旁边修改，更容易审核。

4.4 里程碑顺序

1. 基础脚手架：安装、空首页、检查和构建。
2. 设计系统：CSS 变量、布局、按钮、卡片、焦点。
3. 外壳：Header、LanguageSwitcher、Footer、路由和 404。
4. 内容层：首页、产品列表、产品详情。
5. 信任层：公司/产地供应、质量、市场/流程、FAQ。
6. 行动层：联系入口与 RFQ UI；真实提交在第 8 课接通。

每个里程碑都运行 npm run check 和 npm run build，再查看 375/768/1440px。后一步失败时回到最近提交，而不是同时修十个页面。

4.5 “完整”不等于虚构

公司页可以完整解释应展示哪些事实，同时明确示范数据。质量页可以完整展示原料验收、分级、包装前检查、装运前记录等流程，但不声称已获得某证书。客户案例位置改成“示例采购场景/合作流程”，明确不代表成交或客户背书。

5. 零基础用户能够执行的操作步骤

1. 在 TRAE 打开 cases/garlic-b2b-website/，在终端运行 npm install。
2. 复制 .env.example 为 .env.local；本课先不填真实 Web3Forms Key，保留未配置提示。
3. 运行 npm run dev，打开终端显示的本地地址。
4. 用 #Folder:src 请 Agent 解释目录、路由和内容数据，不改文件；你要能复述每层职责。
5. 从一个全新练习分支复现时，依次发送本课“里程碑提示词”，一次只做一个阶段。
6. 每阶段运行 npm run check、npm run build，再点中英文导航、产品卡与详情。
7. 查看代码变更，确认没有密钥、虚构数字或对标图片。
8. 提交 Git：feat: 完成双语站点外壳、feat: 完成产品与详情、feat: 完成信任内容页面。

6. 可直接复制给 TRAE 或其他 AI 的提示词

请实现里程碑 3“站点外壳”。先阅读 #File:README.md、#File:src/data/siteData.ts、#File:src/styles.css、#Rule:项目规则。
只允许修改 src/components、src/App.tsx 和必要的类型文件；不要实现 RFQ 提交，不新增依赖。
要求：
- React Router 路由支持 /zh 与 /en；根路径重定向到 /en；
- Header 有桌面导航、手机菜单、当前页状态、语言切换和 RFQ 按钮；
- 切换语言保留当前子路径；
- Footer 显示课程示范站声明、示例邮箱与 WhatsApp 配置说明；
- 语义 nav/main/footer、键盘焦点、Escape 关闭手机菜单；
- 375px 无页面横向滚动。
完成后运行 npm run check 和 npm run build，列出修改文件、验证结果和仍未实现项。不要顺手改其他页面。

页面开发、UI 修改和排错的通用版本见 prompts/。

7. 云南大蒜项目中的具体示范

产品详情“鲜白蒜”展示：

• 用途：国际批发采购的信息准备，不承诺具体用途效果。
• 拟议尺寸：按直径区间与供应方协商；示范表展示常见询价表达，发布前确认。
• 包装：网袋、纸箱等作为可讨论选项，净重、标签、托盘与通风孔由书面报价确认。
• 运输：预冷、储存温度、装柜方式应由供应方、货代和质量负责人确认，示范站不写未经核验的固定参数。
• CTA：Request a quote for Fresh White Garlic，进入 RFQ 后预选产品。

公司页使用“云岭蒜业出口服务中心（课程示例名）”，不展示工商注册号、成立年份、种植面积或年产能。供应能力卡写“发布前由企业填写可核验数字”，让页面结构完整而商业事实诚实。

8. 可填写模板

开发里程碑记录：

完整页面提示词见页面开发提示词。

9. 常见错误

• 先改 CSS，数据却散落在十个组件中。
• 中文和英文用两套不对应的路由，切换后丢失当前页。
• 用数组索引或中文名称做产品 URL，内容改动就断链。
• 所有卡片套相同模板，却遗漏每页用户任务。
• 为填满页面编造证书、客户、市场、产能和交期。

10. 排错方法

白屏先看浏览器控制台和终端第一条错误；路由 404 检查路径、Route 与 SPA 重写；语言错位检查 lang 参数和内容字典键；产品详情空白检查 slug 是否与数据一致。CSS 问题先在开发者工具找到造成溢出的具体元素，再修宽度/布局，不用全局 overflow-x:hidden 掩盖问题。

11. 完成标准

• 所有规定路由本地可直接打开，未知路由有友好返回。

• 中英文内容完整，语言切换保留对应页面。

• 3 类产品都有详情、规格/包装说明和 RFQ 入口。

• 公司、产地供应、质量、市场、流程、FAQ 页面齐全。

• 没有虚构资质、评价或未标记的企业数据。

• check、build 和三个宽度检查通过，每阶段有 Git 提交。

12. 本节成果如何进入下一节

下一节接通 RFQ，并把“能看”升级为“能收信、能搜索、能在手机上完成”。第 7 课的路由和集中数据会生成 sitemap、页面元信息和表单产品选项。

---

上一节：第 6 课：从网站结构到可实现的 UI 规格
下一节：第 8 课：RFQ、SEO、测试与手机端验收