docs: overhaul README with detailed project guide

Replace the generic Nuxt starter README with comprehensive documentation specific to the Tootaio Studio website project. The new README provides a detailed guide for developers, covering: - Project features and technology stack (Nuxt 4, Content, UI, i18n). - Setup, installation, and environment configuration. - Directory structure and code organization. - Content management workflow using YAML and zod schemas. - i18n implementation for UI text. - UI components, theming, and dark mode. - SEO and security best practices (CSP, routeRules). - Contribution guidelines and deployment suggestions.
2025-11-07 14:11:08 +08:00
parent cc0cb01d28
commit fb67355a15
1 changed files with 165 additions and 49 deletions
--- a/README.md
+++ b/README.md
@@ -1,75 +1,191 @@
-# Nuxt Minimal Starter
+# Tootaio Studio 网站（Nuxt 4）

-Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
+Tootaio Studio 的官方网站代码仓库，基于 Nuxt 4、@nuxt/content、@nuxt/ui 与 i18n 构建，采用 TypeScript 与 ESM 配置。项目默认使用 pnpm 进行依赖与脚本管理。

-## Setup
+- 在线地址：`https://tootaio.com`
+- 技术要点：内容与 UI 分离（YAML 内容 + JSON 翻译）、类型安全的内容加载、内置 SEO 与 CSP 头部策略

-Make sure to install dependencies:
+---
+
+## 特性概览
+
+- Nuxt 4 与 Vue 3 `<script setup lang="ts">`，全量 TypeScript 化
+- @nuxt/content 管理结构化 YAML 内容，zod 校验 schema，类型安全
+- @nuxt/ui 负责 UI 组件与样式，支持暗色模式与主题定制
+- @nuxtjs/i18n 多语言（英文、简中），消息分包按需加载
+- @nuxtjs/seo 统一 SEO 元信息配置（OG/Twitter/keywords）
+- Nitro routeRules 内置严格 CSP、缓存与安全响应头
+- 运行时配置集成 WhatsApp 咨询（公开变量）
+
+---
+
+## 快速开始
+
+### 先决条件
+
+- Node.js 18.20+ 或 20+
+- pnpm 8+
+
+### 安装依赖

 ```bash
-# npm
-npm install
-
-# pnpm
-pnpm install
-
-# yarn
-yarn install
-
-# bun
-bun install
+pnpm i
 ```

-## Development Server
+安装后会自动执行 `nuxt prepare`（见 `package.json:postinstall`）。

-Start the development server on `http://localhost:3000`:
+### 配置环境变量

 ```bash
-# npm
-npm run dev
+cp .env.example .env
+```

-# pnpm
+必须设置：
+
+- `NUXT_PUBLIC_WHATSAPP_NUMBER`：用于页面内“立刻咨询”按钮，走 WhatsApp H5 链接。
+
+注：`nuxt.config.ts` 提供默认占位值，生产环境应以 `.env` 覆盖。
+
+### 本地开发
+
+```bash
 pnpm dev
-
-# yarn
-yarn dev
-
-# bun
-bun run dev
 ```

-## Production
+访问 `http://localhost:3000`，支持热更新（HMR）与暗色模式切换。

-Build the application for production:
+---

-```bash
-# npm
-npm run build
+## 常用脚本

-# pnpm
-pnpm build
+- 开发：`pnpm dev`
+- 构建：`pnpm build`（产物在 `.output/`）
+- 预览：`pnpm preview`（以生产模式本地运行）
+- 静态生成：`pnpm generate`（SSG 场景）
+- 代码检查：`pnpm exec eslint .`

-# yarn
-yarn build
+---

-# bun
-bun run build
+## 目录结构
+
+- `app/`：Nuxt 应用源码
+  - `pages/`：页面组件（如 `app/pages/index.vue`, `app/pages/webDev.vue`）
+  - `layouts/`：布局（默认头部含语言与主题切换）
+  - `assets/css/main.css`：主题与样式（集成 `@nuxt/ui` 与 `tailwindcss`）
+  - `composables/`：组合式函数（如 `LocalizedCollection.ts`, `NavLinks.ts`）
+  - `schemas/`：zod 定义（如 `pricingPlanSchema.ts`, `buttonSchema.ts`）
+- `content/`：YAML 内容（按语言区分 `en-US/`, `zh-CN/`）
+- `i18n/locales/<locale>/`：UI 文案 JSON 包（按页面拆分，如 `common.json`, `index.json`）
+- `public/`：静态资源（如 `favicon.ico`, `og-image-1.png`, `_robots.txt`）
+- 根配置：`nuxt.config.ts`, `content.config.ts`, `eslint.config.mjs`
+- 文档：`docs/`（工程审计、路线等）
+
+---
+
+## 内容与多语言
+
+### 内容模型（@nuxt/content）
+
+项目在 `content.config.ts` 中用 zod 定义了页面内容的 schema，并建立集合与源文件的对应关系：
+
+- `index_en` ↔ `content/en-US/index.yml`
+- `index_zh` ↔ `content/zh-CN/index.yml`
+- `webDev_en` ↔ `content/en-US/webDev.yml`
+- `webDev_zh` ↔ `content/zh-CN/webDev.yml`
+
+在页面中通过类型安全的加载器获取内容：
+
+```ts
+// 示例：在页面/组件中获取本地化内容
+const { data: page } = await useLocalizedCollection('index')
 ```

-Locally preview production build:
+上述加载器会根据当前语言自动选择集合，并在缺失时回退到英文。

-```bash
-# npm
-npm run preview
+### UI 文案（@nuxtjs/i18n）

-# pnpm
-pnpm preview
+- 语言：`en`（en-US）、`zh-CN`
+- 加载策略：`strategy: "no_prefix"`
+- 文案文件：`i18n/locales/<locale>/*.json`

-# yarn
-yarn preview
+示例 key：`index.featuredProjects.viewDemo`, `common.button.submit`。

-# bun
-bun run preview
-```
+新增页面或模块时，请同步维护中英文版本的 YAML 与 JSON，保持 key 一致。

-Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+---
+
+## UI 与主题
+
+- 组件库：`@nuxt/ui`（`UPage*`, `UHeader`, `UButton`, `UTabs`, `UModal` 等）
+- 主题：`app/assets/css/main.css` 中可定制字体与主色（项目默认霓虹红 `--color-primary`）
+- 暗色模式：内置 `UColorModeButton`，图标与样式随模式自适应
+- 图标：`@iconify-json/mdi` 与 `skill-icons` 系列（通过 `UIcon` 使用）
+
+---
+
+## SEO 与安全
+
+- SEO：`@nuxtjs/seo` 统一设置标题、描述、OG、Twitter 等元信息（见 `nuxt.config.ts` 中 `DEFAULT_SEO`）
+- 站点地址：`site.url = https://tootaio.com`
+- 安全头：在 `routeRules` 配置了 CSP、`X-Content-Type-Options`, `Referrer-Policy` 等；静态资源（`/_nuxt/**`）设置了长期缓存
+- 图片白名单：`img-src` 允许 `self` 与 `https://img.tootaio.com` 与 `data:`
+
+---
+
+## 运行时配置与外部集成
+
+- 环境变量：`NUXT_PUBLIC_WHATSAPP_NUMBER`（公开变量，用于发起 WhatsApp 咨询）
+- 组合式函数：`useWhatsAppMsgSender()` 会根据该号码构造 WhatsApp H5 链接并 `window.open`
+- 示例入口：`app/components/webDev/ContactSalesModal.vue` 在提交后拼接多语言消息并发起咨询
+
+---
+
+## 代码规范与校验
+
+- 风格：TypeScript、2 空格缩进、ESM 配置、组合式函数使用 PascalCase
+- ESLint：`@nuxt/eslint` 预设，配置见 `eslint.config.mjs`
+- 手动检查：`pnpm exec eslint .`
+
+---
+
+## 测试（当前状态）
+
+- 暂未配置自动化测试
+- 建议：单测使用 Vitest，E2E 使用 Playwright
+- 在此之前请进行本地验证：
+  - `pnpm dev` 运行并切换语言
+  - 校验 `content/*.yml` 是否符合 `content.config.ts` 中的 schema
+  - `pnpm build` 与 `pnpm preview` 能否成功
+
+---
+
+## 提交与协作
+
+- 提交规范：Conventional Commits（含 scope），如：`feat(content): ...`, `refactor(ui): ...`
+- 分支命名：`feat/<desc>`、`fix/<desc>`
+- PR 说明：改动目的 / 关联 Issue / UI 截图 / 测试步骤
+- 内容改动请确保中英文同步更新（YAML 与 i18n JSON）
+
+---
+
+## 部署建议
+
+- 服务器渲染（默认）：`pnpm build` 生成 `.output/` 后按 Nuxt/Nitro 的 Node 运行方式部署
+- 静态站点：`pnpm generate` 进行 SSG（请根据实际路由策略评估可行性）
+- 常见平台：Vercel / Netlify / 任意 Node 主机（注意保留 `routeRules` 与响应头设置）
+
+---
+
+## 参考文件
+
+- 配置：`nuxt.config.ts:1`、`content.config.ts:1`
+- 页面：`app/pages/index.vue:1`、`app/pages/webDev.vue:1`
+- 主题：`app/assets/css/main.css:1`
+- 多语言：`i18n/locales/en-US/common.json:1`、`i18n/locales/zh-CN/common.json:1`
+- 环境：`.env.example:1`（复制为 `.env` 并填写）
+
+---
+
+## 许可
+
+如无单独说明，本仓库内容归 Tootaio Studio 所有。