azerbaijan-website-build

阿塞拜疆网站构建

从零开始，为阿塞拜疆企业打造令人惊艳、达到 7.5 万美元以上代理商品质的网站。每个网站都支持三种语言（阿塞拜疆语、俄语、英语），配有语言切换器，基于 Astro 5.x + Tailwind CSS v4 构建，并部署到 Vercel。

快速参考

项目	值
技术栈	Astro 5.x、Tailwind CSS v4（Vite 插件）、npm
语言	阿塞拜疆语（主要语言）、俄语、英语
i18n 方案	基于目录：/az/、/ru/、/en/
图片	Unsplash（本地）、抓取的素材、NanoBanana 2
字体	@fontsource，必须支持 Latin Extended + Cyrillic
部署	GitHub 仓库 → Vercel
项目位置	~/Azerbaijan/projects/<slug>/
品质标准	Apple/Stripe/Linear 级别。必须通过 AI Slop Test。

参考文件

构建前请阅读这些文件，其中包含不可妥协的规则和技术规范：

• references/design-rules.md — 视觉设计规则、禁用字体／颜色／布局、组件架构
• references/accessibility-spec.md — WCAG AA 要求、对比度最低标准、键盘导航
• references/i18n-spec.md — Astro i18n 路由、LanguageSwitcher 组件、hreflang、JSON 字符串
• references/interview-questionnaire.md — 面向没有线上业务的企业的结构化访谈
• references/azerbaijani-design-guide.md — 文化设计注意事项、字体覆盖范围、图片选择
• references/nano-banana-logo.md — 通过 NanoBanana 2 / Gemini API 生成 Logo

项目结构

~/Azerbaijan/projects/<slug>/
├── BUSINESS_PROFILE.md         # Phase 1 output
├── BRAND_BRIEF.md              # Phase 2 output
├── SITE_PLAN.md                # Phase 3 output
├── COPY_CHANGES.md             # Phase 6 output
├── QA_REPORT.md                # Phase 7 output
├── scraped/
│   ├── website/                # Crawled website content (markdown)
│   ├── instagram/              # Instagram data
│   ├── facebook/               # Facebook data
│   └── assets/                 # Downloaded images, logos
│       ├── logos/
│       ├── photos/
│       └── gallery/
└── site/                       # Astro project
    ├── src/
    │   ├── layouts/
    │   │   └── BaseLayout.astro
    │   ├── pages/
    │   │   ├── index.astro     # Redirects to /az/
    │   │   ├── az/             # Azerbaijani pages
    │   │   ├── ru/             # Russian pages
    │   │   └── en/             # English pages
    │   ├── components/
    │   │   ├── Header.astro
    │   │   ├── LanguageSwitcher.astro
    │   │   ├── Footer.astro
    │   │   ├── Hero.astro
    │   │   └── ...sections
    │   ├── content/
    │   │   └── i18n/
    │   │       ├── az.json
    │   │       ├── ru.json
    │   │       └── en.json
    │   ├── utils/
    │   │   └── i18n.ts
    │   ├── styles/
    │   │   └── global.css
    │   └── assets/
    │       └── images/
    ├── public/
    │   ├── images/
    │   ├── favicon.svg
    │   └── robots.txt
    ├── astro.config.mjs
    └── package.json

---

阶段 1：数据收集

输出： ~/Azerbaijan/projects/<slug>/BUSINESS_PROFILE.md

确定适用的输入路径，并按要求执行。所有路径都会生成相同的标准化输出。

路径 A — 有网站（可能也有社交媒体）

1. 抓取网站，使用 Apify RAG Web Browser（apify/rag-web-browser）：

   Query: the business website URL
   maxResults: 1
   outputFormats: ["markdown"]
   

   将 Markdown 输出保存到 scraped/website/。

2. JavaScript 密集型网站的备用方案（Wix、Squarespace 等）：使用 Chrome 自动化（mcp__Claude_in_Chrome）：

   • 访问每个页面
   • 截取屏幕截图
   • 使用 get_page_text 提取可见文本
   • 下载图片

3. 抓取社交媒体（如有）：

   • Instagram： 使用 Apify Instagram 抓取工具提取简介、最近的帖子（最近 20 条）、所有帖子图片和粉丝数。保存到 scraped/instagram/。
   • Facebook： 使用 Apify Facebook 抓取工具或 Chrome 自动化提取主页信息、简介部分、服务、评价和照片。保存到 scraped/facebook/。
   • Twitter/X： 检查账号是否存在。若存在，通过 Chrome 提取简介和最近的帖子。

4. 下载所有可用图片到 scraped/assets/：

   • Logo（可获取的最高分辨率版本）
   • 团队／员工照片
   • 产品／服务照片
   • 室内／室外照片
   • 图库图片
   • 验证：文件必须大于 1 KB（拒绝 HTML 错误页面）

5. 根据所有抓取的数据编写 BUSINESS_PROFILE.md。

路径 B — 仅有社交媒体（没有网站）

1. Instagram 是主要来源：

   • 抓取完整主页资料：简介、精选内容、所有帖子（最多 50 条）和所有图片
   • 提取：企业名称、类别、联系信息（通常在简介中）、位置
   • 将所有高质量图片下载到 scraped/assets/

2. Facebook 主页：

   • 提取：简介部分、服务列表、评价／推荐语、相册
   • 下载照片

3. Twitter/X： 检查账号是否存在；如存在，提取简介和近期内容。

4. 找出信息缺口——社交媒体通常缺少以下信息：

   • 详细的服务说明
   • 价格信息
   • 团队信息
   • 企业历史
   • 营业时间

   在 BUSINESS_PROFILE.md 的“待补充信息”部分标记这些缺口，并向用户询问相关信息。

5. 编写 BUSINESS_PROFILE.md。

路径 C — 没有线上资料（访谈）

1. 阅读 references/interview-questionnaire.md，了解完整的问题列表。
2. 分批向用户提问（不要一次性抛出全部 40 个问题）：
   • 从业务基础信息开始（名称、行业、地点、联系方式）
   • 然后询问服务与产品
   • 接着询问品牌与视觉形象
   • 最后询问内容与功能
3. 接受用户提供的任何信息。 最低要求：业务名称、描述、城市、电话、至少 3 项服务。
4. 索取素材： Logo 文件、照片及任何营销材料。
5. 整理并编写 BUSINESS_PROFILE.md。 对推断的字段标记 [INFERRED]，对缺失的字段标记 [NEEDED]。

BUSINESS_PROFILE.md 格式

# Business Profile: [Business Name]

**Data Source:** Path A (website + social) | Path B (social only) | Path C (interview)
**Date Gathered:** YYYY-MM-DD
**Slug:** [url-safe-slug]

## Business Overview
- **Name:** [Azerbaijani name]
- **Name (English):** [transliteration]
- **Industry:** [category]
- **Year Established:** [year or "Unknown"]
- **Description:** [2-3 sentences about what they do]
- **Unique Selling Points:** [what makes them different]

## Services / Products
| Service | Description | Price (if known) |
|---------|-------------|-----------------|
| ... | ... | ... |

## Target Audience
- **Primary customers:** [description]
- **Language preference:** [AZ / RU / both]
- **Geographic reach:** [local / national / international]

## Brand Personality
- **Tone:** [luxury / professional / friendly / modern / traditional / etc.]
- **Color preferences:** [if expressed or extracted]
- **Inspiration:** [competitor or admired sites]

## Contact & Location
- **Address:** [full address in Azerbaijani]
- **Phone:** [+994 XX XXX XX XX]
- **Email:** [if available]
- **Hours:** [operating hours]
- **WhatsApp:** [if available — very common in Azerbaijan]
- **Social media:**
  - Instagram: [URL]
  - Facebook: [URL]
  - Twitter: [URL]

## Content Inventory
- **About text:** [available / needs writing]
- **Service descriptions:** [available / needs writing]
- **Testimonials:** [count, or "none available"]
- **Team info:** [available / none]

## Image Inventory
| Type | Count | Quality | Notes |
|------|-------|---------|-------|
| Logo | ... | ... | ... |
| Team photos | ... | ... | ... |
| Product photos | ... | ... | ... |
| Interior/exterior | ... | ... | ... |
| Gallery | ... | ... | ... |

## Gaps to Fill
- [ ] [list anything missing that needs to be created, sourced, or asked about]

暂停点： 继续之前，先将 BUSINESS_PROFILE.md 提供给用户审核。询问用户是否需要补充任何缺失信息。

---

第 2 阶段：品牌开发

输出： ~/Azerbaijan/projects/<slug>/BRAND_BRIEF.md

开始前，阅读 references/design-rules.md 和 references/azerbaijani-design-guide.md。

步骤 1：Logo

如果业务有 Logo：

• 下载/复制到 scraped/assets/logos/
• 分析并提取颜色
• 确认分辨率足以用于网页（宽度至少 200px）

如果业务没有 Logo：

• 阅读 references/nano-banana-logo.md
• 收集信息：业务名称、行业，以及 BUSINESS_PROFILE.md 中的品牌个性
• 使用 Gemini API 通过 NanoBanana 2 生成 3 个 Logo 方案
• 向用户展示方案供其选择
• 如果经过 3 轮后仍没有满意的方案：改用选定的展示字体制作字体 Logo（使用 CSS/SVG 设置样式）
• 将最终 Logo 保存到 scraped/assets/logos/logo.png

步骤 2：配色方案

1. 如果有 Logo：从 Logo 中提取 2–3 种主色
2. 如果没有 Logo：根据行业和品牌个性制定配色方案
3. 定义完整的颜色系统：
   • 主色（主导色）
   • 次要色
   • 强调色（鲜明、醒目）
   • 背景色（暖调的米白色，而非纯白色）
   • 文本颜色（暖调的近黑色，而非纯黑色）
   • 中性色调（带有品牌色相的色调）
4. 验证每种颜色组合均符合 WCAG AA 标准：
   • 背景上的文本：最低 4.5:1
   • 大号文本：最低 3:1
   • UI 组件：最低 3:1 使用 scripts/contrast-check.js 进行验证。
5. 将颜色记录为 CSS 自定义属性，并在注释中注明对比度。

步骤 3：字体排版

1. 从 references/design-rules.md 中已验证的候选字体里，选择一种展示/标题字体和一种正文字体
2. 验证两种字体均可正确显示阿塞拜疆语测试字符串和西里尔字母
3. 定义字体层级：展示文字、h1、h2、h3、正文、小字、说明文字
4. 所有字号都使用 clamp() 实现流式缩放
5. 使用 @fontsource 安装，并选择正确的子集：latin、latin-ext、cyrillic、cyrillic-ext

步骤 4：品牌语调

为每种语言定义沟通语调：

• 阿塞拜疆语： [热情/正式/随意] — 这是主要语调
• 俄语： 通常略微正式
• 英语： 简洁、国际化、专业

步骤 5：品牌卡片

创建一张 HTML 品牌卡片（单个 HTML 文件），展示：

• Logo（或占位内容）
• 配色方案及其十六进制代码和对比度
• 三种语言的字体示例
• 品牌语调摘要
• 阿塞拜疆语标语/标题建议

保存到项目根目录并打开以供审核。

步骤 6：生成 DESIGN.md

完成品牌卡片后，使用 design-system-generator 技能及阿塞拜疆扩展，生成结构化的 DESIGN.md。

1. 阅读 00-design-references/design-md-format.md，了解基础的 9 个章节格式。
2. 从 00-design-references/references/by-aesthetic/ 中选择 1-2 个与品牌方向相符的参考 DESIGN.md 文件。
3. 生成 DESIGN.md，包含全部 9 个标准章节，再加上第 10 节：多语言注意事项：
   • 字体验证测试字符串："Əlaqə üçün bizə zəng edin. Ğəbul saatları: Ş. 09:00-18:00 | Связаться с нами"
   • 针对俄语文本扩展约 30% 的布局、按钮和导航适配规则
   • 阿塞拜疆文化色彩说明（低调使用国旗颜色，奢华风格使用金色）
   • 各语言的内容语气（AZ：亲切、正式；RU：略正式；EN：简洁、国际化）
4. BRAND_BRIEF.md 的 Color Palette 和 Typography 部分应写明“完整设计系统请参阅 DESIGN.md”——BRAND_BRIEF.md 保留品牌语气、徽标元数据及非设计内容。

输出： ~/Azerbaijan/projects/<slug>/DESIGN.md

BRAND_BRIEF.md 格式

# Brand Brief: [Business Name]

## Logo
- Source: [existing / generated / typographic]
- File: [path to logo file]

## Color Palette
| Token | Hex | Usage | Contrast vs bg |
|-------|-----|-------|----------------|
| --color-primary | #xxx | Headings, buttons | X.X:1 AA PASS |
| --color-secondary | #xxx | Accents | X.X:1 AA PASS |
| --color-accent | #xxx | CTAs, highlights | X.X:1 AA PASS |
| --color-bg | #xxx | Page background | — |
| --color-text | #xxx | Body text | X.X:1 AA PASS |

## Typography
- **Display:** [Font Name] — [weights]
- **Body:** [Font Name] — [weights]
- **Verified:** AZ characters ✓ | Cyrillic ✓

> **Note:** Complete design system specification (color tokens, typography hierarchy table, component stylings, shadow system, layout principles) is in `DESIGN.md`. The sections below are summaries — see DESIGN.md for exact values.

## Brand Voice
- **AZ:** [description]
- **RU:** [description]
- **EN:** [description]

## Aesthetic Direction
- **Tone:** [chosen aesthetic]
- **Differentiation:** [the unforgettable thing]

暂停点： 向用户展示 BRAND_BRIEF.md 和品牌卡片，以供审批。

---

第 3 阶段：内容策略与网站架构

输出： ~/Azerbaijan/projects/<slug>/SITE_PLAN.md

步骤 1：页面结构

根据业务类型和现有内容，定义网站地图。常见结构：

标准结构（适用于大多数企业）：

• 首页（/az/、/ru/、/en/）
• 关于（/az/haqqimizda/、/ru/o-nas/、/en/about/）
• 服务（/az/xidmetler/、/ru/uslugi/、/en/services/）
• 联系（/az/elaqe/、/ru/kontakty/、/en/contact/）

扩展结构（如果内容充足）：

• 画廊（/az/qalereya/、/ru/galereya/、/en/gallery/）
• 博客（/az/bloq/、/ru/blog/、/en/blog/）
• 价格（/az/qiymetler/、/ru/tseny/、/en/pricing/）
• 菜单（餐厅：/az/menyu/、/ru/menyu/、/en/menu/）

步骤 2：逐页内容计划

为每个页面定义：

• 版块（主视觉、关于、服务网格、客户评价、CTA 等）
• 阿塞拜疆语文案方向（每个版块应传达什么）
• 每个版块的图片需求（现有图片与待补充图片）
• 交互元素（折叠面板、画廊灯箱、联系表单、地图）

步骤 3：图片策略

对所有图片需求进行分类：

版块	所需图片	来源	状态
主视觉	主视觉背景	Unsplash / NanoBanana	[需要]
关于	团队/办公室照片	抓取	[已有]
服务	服务插图	Unsplash	[需要]
...	...	...	...

现在下载所有 Unsplash 图片——在构建阶段开始前完成：

1. 在 Unsplash 上搜索每张所需图片
2. 确认符合文化习俗（参见 references/azerbaijani-design-guide.md）
3. 下载到 site/src/assets/images/（用于 Astro 优化）或 site/public/images/（用于静态资源）
4. 使用描述性文件名：hero-restaurant-baku.jpg、team-working.jpg
5. 绝不热链外部 URL

步骤 4：SEO 计划

• 阿塞拜疆语（主要）、俄语、英语目标关键词
• JSON-LD 架构类型（LocalBusiness、Restaurant 等）
• 各页面 × 各语言的 Meta 标题/描述模板
• 包含 hreflang 替代链接的网站地图策略

SITE_PLAN.md 格式

记录以上所有内容。这是构建阶段的蓝图。

暂停点： 向用户展示 SITE_PLAN.md。这是开始构建前的最后一个检查点。

---

阶段 4：图片整理

**输出：**所有图片均已整理到 Astro 项目中

1. 处理抓取的图片：

   • 将可用图片从 scraped/assets/ 复制到 site/src/assets/images/
   • 缩小过大的图片（最大宽度为 2000px）
   • 确保图片质量足以用于网页

2. 下载 Unsplash 图片（遵循 SITE_PLAN.md 中的图片策略）：

   • 使用 Unsplash API 或通过网页搜索查找合适的图片
   • 将每张图片下载到 site/src/assets/images/ 或 site/public/images/
   • 遵循阿塞拜疆文化图片指南
   • 生产代码中绝不可使用外部 Unsplash URL

3. 使用 NanoBanana 2 生成图片（如有需要）：

   • 首页主视觉背景
   • 没有原始图片时使用的产品／服务图片
   • API 用法请参阅 references/nano-banana-logo.md

4. 核验每张图片：

   • 色温是否符合品牌配色？
   • 是否符合阿塞拜疆文化？
   • 人物是否符合实际客户群体？
   • 是否与该部分文案相符，而非仅仅是大致相关？

5. 整理到文件夹中：

   site/src/assets/images/
   ├── hero/
   ├── about/
   ├── services/
   ├── gallery/
   ├── team/
   └── general/
   

---

阶段 5：构建网站

构建前阅读所有参考文件：

• references/design-rules.md — 设计规则（必须遵守）
• references/accessibility-spec.md — WCAG AA 要求
• references/i18n-spec.md — i18n 路由、LanguageSwitcher、hreflang

步骤 1：初始化 Astro 项目

cd ~/Azerbaijan/projects/<slug>
npm create astro@latest site -- --template minimal --no-install
cd site
npm install
npx astro add tailwind --yes
npx astro add sitemap --yes
npm install -D prettier

安装字体（示例）：

npm install @fontsource/dm-sans @fontsource/playfair-display

步骤 2：配置 Astro

在 astro.config.mjs 中：

• 将 site 设置为预期的 Vercel URL
• 配置支持 i18n 的站点地图（参阅 references/i18n-spec.md）
• 配置 i18n 路由，并将 az 设为默认区域设置

步骤 3：构建设计系统

构建设计系统前，请阅读项目的 DESIGN.md。 将其作为所有 CSS 自定义属性、字体导入、字体排印比例、组件规范和阴影令牌的权威依据。继续之前，请确认 DESIGN.md 中的字体通过 AZ/RU 字符验证测试。

创建 src/styles/global.css：

• 导入字体包
• 定义 BRAND_BRIEF.md 中的所有 CSS 自定义属性
• 以注释形式记录对比度
• 使用 clamp() 定义字体排印比例
• 设置基础样式（body、标题、链接）

步骤 4：构建 i18n 基础设施

根据 references/i18n-spec.md：

• 创建 src/utils/i18n.ts，包含 getLang()、getStrings()、switchLang()、getAlternateLinks()
• 创建 src/content/i18n/az.json、ru.json、en.json，用于存放 UI 文本
• 创建根目录下的 src/pages/index.astro，将其重定向到 /az/

步骤 5：构建布局和共享组件

1. BaseLayout.astro：

   • 使用 i18n 工具设置 <html lang> 属性
   • 在 <head> 中为全部 3 种语言添加 hreflang 链接，并包含 x-default
   • Open Graph / Twitter Card 元信息（按语言设置）
   • 字体导入
   • 全局 CSS 导入
   • View Transitions
   • 跳转到内容的链接

2. Header.astro：

   • 导航链接（通过 i18n 字符串翻译）
   • LanguageSwitcher 组件
   • 移动端汉堡菜单
   • 粘性／固定定位

3. LanguageSwitcher.astro：

   • AZ | RU | EN，并显示国旗标识
   • 保留当前页面路径
   • 在当前语言上添加 aria-current
   • 完整实现请参阅 references/i18n-spec.md

4. Footer.astro：

   • 从 BUSINESS_PROFILE.md 获取联系信息
   • 社交媒体链接
   • 包含当前年份的版权信息
   • 所有文本均来自 i18n 字符串

步骤 6：将页面区块构建为组件

每个视觉上独立的区块都应使用独立的 .astro 组件：

• Hero.astro — 全宽主视觉区块，包含图片／叠加层、标题和 CTA
• About.astro — 业务故事／介绍
• Services.astro — 服务网格／卡片
• Testimonials.astro — 客户引言／评价
• CTA.astro — 行动号召横幅
• Gallery.astro — 图片网格／灯箱（如适用）
• Contact.astro — 联系表单、地图、联系信息
• 根据需要添加其他区块

**每个组件都通过 props 接收特定语言的内容。**各语言的页面文件会将相应内容传递给共享组件。

第 7 步：首先构建阿塞拜疆语页面

构建 src/pages/az/ 下的所有页面：

• az/index.astro — 首页
• az/haqqimizda.astro — 关于我们
• az/xidmetler.astro — 服务
• az/elaqe.astro — 联系我们
• 根据 SITE_PLAN.md 添加其他页面

所有内容都使用地道的阿塞拜疆语。这是主要语言，文字必须自然流畅，不能像翻译腔。

第 8 步：应用设计规则

逐项检查 references/design-rules.md 中的清单：

• 使用 4 种以上不同的布局模式
• 任意两个连续区块不使用相同的列结构
• 不使用禁用字体
• 色彩系统使用 CSS 自定义属性
• 所有对比度均符合 WCAG AA
• 使用 3 种以上不同的动画
• 至少在 2 个区块中使用滚动触发的显示效果
• 尊重 prefers-reduced-motion
• 增加视觉层次（噪点、渐变、SVG 形状、阴影）
• 组件化架构（避免使用单体页面）
• AI 糟粕测试：别人会觉得这是 AI 做的吗？如果会，重新设计。

第 9 步：响应式设计

• 移动端优先：基础样式适用于 320px 及以上
• 断点：640px（sm）、768px（md）、1024px（lg）、1280px（xl）、1536px（2xl）
• 使用 min-width 媒体查询，不要使用 max-width
• 触控目标：高度至少为 44px
• 在所有断点下验证，确保没有水平滚动条

第 10 步：SEO 实现

每个语言版本的每个页面都要包含：

• 独特的 <title> 和 <meta name="description">
• JSON-LD 结构化数据（LocalBusiness 或适当的类型）
• hreflang <link> 标签（参见 i18n-spec.md）
• 使用 @astrojs/sitemap 生成包含 i18n 替代链接的站点地图
• 在 public/ 中放置 robots.txt
• 语义化 HTML（<main>、<nav>、<article>、<section>）
• 为每张图片添加符合页面语言的描述性替代文本

第 11 步：网站图标

• 根据 Logo 生成
• 至少包含：public/favicon.svg
• 将其添加到 BaseLayout 的 <head> 中

---

第 6 阶段：文案与翻译

第 1 步：阿塞拜疆语文案（主要语言）

检查所有阿塞拜疆语页面内容：

• 用户能否在 5 秒内明白价值主张？
• 每个页面是否都有醒目且以利益为导向的 CTA？
• 文案是否优先突出利益，而非功能？
• 是否及早回应客户的疑虑？
• 是否尽可能使用具体数字？
• 句子是否简短有力？
• 阅读难度是否相当于八年级水平？

在 COPY_CHANGES.md 中记录改进内容。

第 2 步：俄语翻译

在 src/pages/ru/ 下创建所有页面：

• 应根据语境调整，不要逐字翻译。 俄语的句式结构和正式程度规范有所不同。
• 俄语文本比英语长约 30%，请确认布局不会错乱
• 遵循规范的俄语用法（商务网站使用正式的“вы”）
• URL 路径使用俄语转写：/ru/o-nas/、/ru/uslugi/、/ru/kontakty/

第 3 步：英语翻译

在 src/pages/en/ 下创建所有页面：

• 使用简洁、专业的国际英语
• 使用标准 URL 路径：/en/about/、/en/services/、/en/contact/
• 此版本面向游客、外籍人士和国际联系人

第 4 步：UI 文本

更新全部 3 个 JSON 文件（az.json、ru.json、en.json）：

• 导航标签
• 按钮文本（CTA、表单）
• 页脚内容
• 表单标签和占位符
• 错误消息
• 元描述

第 5 步：验证完整性

检查每种语言的每个页面：

• 不再有占位文本
• 不再有未翻译的字符串
• i18n 引用均有效
• 所有 JSON 字符串键的使用保持一致

---

第 7 阶段：QA（综合检查）

输出： ~/Azerbaijan/projects/<slug>/QA_REPORT.md

运行开发服务器并系统地检查所有内容：

cd ~/Azerbaijan/projects/<slug>/site
npm run dev

7.1 功能 QA（全部 3 种语言）

• 所有导航链接均可正常使用
• 所有页面上的语言切换器均可正常使用（并保留当前页面）
• 根路径 / 会重定向到 /az/
• 所有图片均可加载（没有损坏的图片）
• 联系表单可正常使用（如适用）
• 社交媒体链接可正常打开
• 电话和电子邮件链接可正常使用（tel:、mailto:）
• WhatsApp 链接可正常使用（如适用）
• 地图嵌入可正常使用（如适用）
• 所有语言前缀下的 404 页面均可正常使用

7.2 视觉 QA

• 设计规则清单检查通过（4 种以上布局，且不包含禁用元素）
• 动画流畅，没有卡顿
• 所有页面的品牌形象一致
• 图片质量高，尺寸合适
• 没有“AI 垃圾感”——人类设计师会认可这个设计吗？
• 图片文字区域使用深色叠加层
• 每个页面的视觉层次都清晰

7.3 响应式 QA（在每种视口下测试所有 3 种语言）

• 320px（移动设备）——所有语言
• 768px（平板）——所有语言
• 1024px（小型桌面设备）——所有语言
• 1280px（桌面设备）——所有语言
• 1536px+（大型设备）——所有语言
• 任何视口下都没有水平滚动条
• 俄语文本（最长）不会破坏布局
• 移动设备上的触控目标 ≥ 44px
• 移动端导航运行正常

7.4 无障碍 QA

• 在每个页面运行 axe-core（修复所有 CRITICAL/SERIOUS 问题）
• 检查所有颜色组合的对比度（scripts/contrast-check.js）
• 键盘导航正常（使用 Tab 键遍历所有交互元素）
• 提供“跳转到正文”链接且功能正常
• 所有图片都有替代文本（语言正确）
• prefers-reduced-motion 会禁用动画
• 焦点指示器清晰可见

7.5 SEO QA

• 每个页面的 hreflang 标签正确（AZ、RU、EN、x-default）
• 各语言的 JSON-LD 架构均有效
• Sitemap 包含所有页面 × 所有语言
• robots.txt 存在且内容正确
• 每个页面的每种语言都有独特的标题和 meta description
• 正确使用语义化 HTML
• Canonical URL 正确

7.6 内容 QA

• 三种语言的内容均完整——没有占位文本
• 阿塞拜疆语读起来自然（没有翻译腔）
• 俄语读起来自然，正式程度恰当
• 英语简洁、专业
• 没有未翻译的 UI 字符串
• 商家信息准确（名称、地址、电话、营业时间）

7.7 图片 QA

运行损坏图片检查：

Array.from(document.querySelectorAll('img')).filter(img => !img.complete || img.naturalWidth === 0).map(img => img.src)

• 所有页面均没有损坏的图片
• 没有外部图片或热链接图片 URL
• 所有图片均已优化（Astro <Image> 或使用合适的尺寸）

修复并重新验证

修复所有发现的问题。对已修复项目重新运行检查。将所有内容记录在 QA_REPORT.md 中。

---

阶段 8：部署

步骤 1：构建测试

cd ~/Azerbaijan/projects/<slug>/site
npm run build

修复所有构建错误。构建必须顺利成功。

步骤 2：Git 设置

cd ~/Azerbaijan/projects/<slug>/site
git init
# Ensure .gitignore exists (Astro generates one)
# Verify .env.local is in .gitignore
git add .
git commit -m "Initial build: [business name] - tri-lingual website (AZ/RU/EN)"

步骤 3：GitHub

创建一个新的 GitHub 仓库：<slug>-az

gh repo create <slug>-az --public --source=. --push

步骤 4：Vercel

部署到 Vercel：

npx vercel --yes
npx vercel --prod

或者通过 Vercel 控制面板连接，以便在推送时自动部署。

步骤 5：线上验证

打开 Vercel 线上 URL 并验证：

• 三种语言版本均可加载
• 语言切换器运行正常
• 所有图片均可加载
• 表单功能正常
• SSL 证书已启用（https）
• 性能符合要求（使用 Lighthouse 检查）

步骤 6：最终无障碍扫描

对线上 URL 运行 axe-core，进行最终检查。

步骤 7：交付

向用户提供：

• 线上 URL
• GitHub 仓库 URL
• 已构建内容摘要（页面、功能、语言）

---

规则与标准

不容妥协

1. 必须支持三种语言。 每个页面都必须提供 AZ、RU 和 EN 版本。所有 UI 字符串都必须翻译。
2. 阿塞拜疆语是主要语言。 先撰写阿塞拜疆语内容。内容必须地道自然，绝不能像翻译稿。
3. 符合 WCAG AA 标准。 验证对比度，确保键盘导航正常，并提供替代文本。
4. 所有图片都必须存放在本地。 绝不热链接外部 URL。下载所有图片。
5. 字体必须同时支持两种文字系统。 拉丁字母扩展集（AZ）+ 西里尔字母（RU）。使用前先验证。
6. 遵守设计规则。 参阅 references/design-rules.md。不得使用禁用的字体、颜色或布局。
7. AI 垃圾感测试。 如果看起来像 AI 制作的，就重新设计。
8. 符合文化习惯。 图片、语气和设计必须体现阿塞拜疆特色，而不是泛泛的美国风格。

技术标准

• Astro 5.x 搭配 Tailwind CSS v4（Vite 插件）
• 仅使用 npm（不使用 pnpm 或 yarn）
• 使用 @fontsource 托管字体
• 使用 Astro <Image> 组件优化图片
• 仅使用 CSS 动画（不使用 JS 动画库）
• 使用 View Transitions 实现页面导航
• 全面使用语义化 HTML
• 采用移动端优先的响应式设计
• Lighthouse 性能目标：95+

文案标准

• Hook → 问题 → 解决方案 → 佐证 → 行动（每个页面都遵循）
• 在 5 秒内清楚传达价值主张
• 优先介绍收益，而非功能
• 使用具体数字，而非模糊说法
• 阅读难度相当于美国八年级水平
• 使用简短有力的句子
• 在 CTA 和决策点附近展示客户评价