40b3ee147f
This commit introduces a comprehensive engineering audit report for the Tootaio Studio project. The report is structured into documents covering architecture, code quality, performance, security, CI/CD, and observability. It also includes a phased improvement roadmap and a set of `.patch` files to apply immediate fixes for content schemas, package scripts, and CI configuration.
85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
当然可以，下面是完整的中文翻译版，保持了原文的结构与语气，适合直接放在项目的 `AGENTS.zh-CN.md` 中使用👇
|
||
|
||
---
|
||
|
||
# 仓库指南（Repository Guidelines）
|
||
|
||
本仓库托管了 **Tootaio Studio** 网站项目，基于 **Nuxt 4**、`@nuxt/content`、`@nuxt/ui` 和 i18n 构建。
|
||
项目使用 **pnpm** 进行全部工作流程。
|
||
|
||
---
|
||
|
||
## 项目结构与模块组织
|
||
|
||
* `app/` — Nuxt 应用源码目录，包含：`pages/`、`layouts/`、`assets/`、`composables/`、`utils/` 等（例如：`app/pages/index.vue`）。
|
||
* `content/` — 基于 YAML 的多语言内容文件（如：`content/en-US`、`content/zh-CN`）。内容结构定义在 `content.config.ts` 中。
|
||
* `i18n/` — UI 翻译文件（JSON 格式），位于 `i18n/locales/<locale>/`。
|
||
* `public/` — 静态资源目录，内容将原样提供给客户端。
|
||
* 根级配置文件包括：`nuxt.config.ts`、`eslint.config.mjs`、`pnpm-workspace.yaml`。项目文档存放于 `docs/`。
|
||
|
||
---
|
||
|
||
## 构建、测试与开发命令
|
||
|
||
* **安装依赖**：`pnpm i`（会自动执行 `nuxt prepare`）
|
||
* **开发服务器**：`pnpm dev` — 启动后访问 [http://localhost:3000](http://localhost:3000)，支持 HMR。
|
||
* **生产构建**：`pnpm build` — 生成 `.output/` 目录。
|
||
* **预览构建**：`pnpm preview` — 以生产模式运行构建产物。
|
||
* **静态生成**：`pnpm generate` — 执行 SSG（静态站点生成）。
|
||
* **代码检查**：`pnpm exec eslint .`（手动执行时使用；CI 流程中会自动运行）。
|
||
|
||
---
|
||
|
||
## 代码风格与命名规范
|
||
|
||
* 使用 **TypeScript** 与 Vue 3 `<script setup lang="ts">`；配置文件采用 **ESM 模块** 格式。
|
||
* 缩进统一为 **2 空格**；保持与现有代码库的引号与风格一致。
|
||
* Vue 单文件组件（SFC）位于 `pages/` 下，文件名简洁（例如：`webDev.vue`）；
|
||
自定义组合式函数（composables）使用 **PascalCase**（如：`LocalizedCollection.ts`）。
|
||
* ESLint 通过 `@nuxt/eslint` 配置，依赖编辑器集成与 CI/构建阶段反馈。
|
||
* i18n 多语言 key 使用 **点号嵌套命名法**，例如：`$t('index.featuredProjects.viewDemo')`。
|
||
|
||
---
|
||
|
||
## 测试指南
|
||
|
||
* 当前尚未配置自动化测试。
|
||
推荐在未来使用 **Vitest** 进行单元测试，**Playwright** 进行端到端（e2e）测试。
|
||
* 在此之前，请进行本地验证：
|
||
|
||
* 运行 `pnpm dev`；
|
||
* 切换多语言；
|
||
* 检查 `content/*.yml` 是否符合 `content.config.ts` 中的 schema；
|
||
* 确认 `pnpm build` 与 `pnpm preview` 能成功执行。
|
||
|
||
---
|
||
|
||
## 提交与 Pull Request 规范
|
||
|
||
* 遵循 **Conventional Commits** 规范，并带有 scope（可参考提交历史）：
|
||
|
||
* 示例：`feat(content): …`、`refactor(ui): …`、`feat(pages): …`
|
||
* 分支命名格式：
|
||
|
||
* `feat/<简短描述>`、`fix/<简短描述>`
|
||
* Pull Request 要包含以下信息：
|
||
|
||
* **改动目的**
|
||
* **关联的 Issue（如有）**
|
||
* **UI 改动截图**
|
||
* **测试步骤**
|
||
* 若涉及内容文件，请确保 **中英文版本同步更新**。
|
||
|
||
---
|
||
|
||
## 内容与多语言（i18n）建议
|
||
|
||
* 在 `content/en-US/` 与 `content/zh-CN/` 下维护平行的内容文件。
|
||
若新增页面类型，请同时扩展 `content.config.ts` 的 schema。
|
||
* 使用 `useLocalizedCollection('index')` 或类似函数来获取内容，以获得类型支持与语言回退（fallback）。
|
||
* 保持多语言翻译文件在各个 locale 目录下同步更新：`i18n/locales/<locale>/`。
|
||
|
||
---
|
||
|
||
是否希望我帮你把这份翻译排版成一个更正式、带 Front Matter 的文档版本（例如带 `title`, `lastUpdated`, `description` 的 YAML 头部），以便直接放进 Nuxt Content 或 docs 目录？
|