docs(engineering): add project audit report and improvement plan

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.
This commit is contained in:
xiaomai
2025-11-06 10:15:00 +08:00
parent 8cc04b7f59
commit 40b3ee147f
14 changed files with 744 additions and 0 deletions

147
docs/CODEX-PROMPT.md Normal file
View File

@@ -0,0 +1,147 @@
你现在是 **Tootaio Studio 项目的高级工程化顾问兼代码审计师**
你的职责是对这个基于 **Nuxt 4.2.0** 的项目进行一次**全方位工程级分析与优化规划**
以生成一份可以直接落地的**架构与工程化报告**。
---
## 一、项目背景
本仓库托管的是 **Tootaio Studio 网站**,基于以下技术栈:
* **Nuxt 4.2.0**
* **@nuxt/content**(内容驱动)
* **@nuxt/ui**
* **i18n**
* 包管理器:**pnpm**
* 参考规范见 `AGENTS.md`(已提供)。
项目结构(符合最新 Nuxt 4.2.0
```
app/
├─ assets/
├─ composables/
├─ layouts/
├─ pages/
├─ app.vue
content/
i18n/
public/
docs/
```
---
## 二、分析目标
请你以拥有 10 年以上经验的 **Nuxt / 前端架构师** 的身份,
对整个项目进行一次性全面分析与输出,目标包括但不限于:
1. **架构审计**
* 分析模块划分、Nuxt 4 特性使用Nitro routes、auto-import、runtime config 等)。
* 指出结构异味与潜在设计风险,并提供优化策略。
* 判断 app/ 层结构是否遵循最新 Nuxt 4.2.0 官方建议。
2. **代码质量与维护性**
* 检查类型定义、composables 命名规范、逻辑分层是否清晰。
* 判断是否存在可重构点(如 utils / composables / layouts 中重复逻辑)。
* 给出统一命名与约定规范建议(含具体命名示例与代码片段)。
3. **性能与构建流程**
* 检查 SSR / CSR 渲染策略是否合理;有无未按需加载的模块。
* 给出针对 Nuxt 4 的性能优化建议build options, code-splitting, lazy loading, runtime config 优化等)。
* 分析缓存策略、图片优化、CDN 使用、Nitro 部署模式Node / Edge / Static
4. **开发体验与工程体系DX**
* 审查 eslint、prettier、tsconfig、vitest、commitlint、husky 等工具配置。
* 给出一份推荐的现代化工程工具链pnpm workspace + lint + test + CI/CD配置清单。
* 输出改进示例配置文件、命令、package.json scripts
5. **CI/CD 与部署**
* 检查是否存在 GitHub Actions / CI 流程;如无,请生成完整示例:
包含 lint → type-check → test → build → deploy 的 workflow 文件。
* 同时给出 Vercel / Docker / 自建部署方案的对比说明。
6. **安全与可观测性**
* 检查敏感信息暴露、dotenv 安全、runtimeConfig 泄露风险。
* 建议增加 Sentry/LogRocket/Datadog 等监控与日志方案,并提供示例代码。
7. **内容与多语言结构**
* 确认 `content/``i18n/` 结构是否合理、是否符合 `AGENTS.md` 规范。
* 检查 YAML schema 与 JSON locale 对齐情况,建议自动化同步方案。
8. **改进路线图Roadmap**
* 生成一个可执行的工程化升级路线图:
分为四个阶段(基础规范化 → 模块解耦 → 自动化部署 → 性能与监控)。
* 每个阶段列出要点、执行命令和预期产出。
---
## 三、输出要求(一次性全部完成)
请将你的分析结果写入 `docs/20251106/` 目录中,包含以下文件(全部在本次回复中完整输出):
| 文件路径 | 内容说明 |
| -------------------------------- | ---------------------------------------- |
| `docs/20251106/README.md` | 分析概要与执行总结 |
| `docs/20251106/architecture.md` | 架构结构与改进方案 |
| `docs/20251106/code-quality.md` | 代码规范与质量分析 |
| `docs/20251106/performance.md` | 性能诊断与优化建议 |
| `docs/20251106/ci-cd.md` | CI/CD 设计与部署方案 |
| `docs/20251106/security.md` | 安全审计与防护建议 |
| `docs/20251106/observability.md` | 监控、日志与运行时可观测性 |
| `docs/20251106/roadmap.md` | 分阶段工程化改进计划 |
| `docs/20251106/patches/` | 含至少 3 个可应用的 `.patch` 文件unified diff 格式) |
每个 patch 文件需附带:
* 修改目标与理由;
* 应用命令(`git apply patches/xxx.patch`
* 改动前后对比(`--- a/... +++ b/...`
* 若涉及配置文件,请保持类型安全与 Nuxt 4.2.0 兼容。
---
## 四、格式要求
* 所有输出以 Markdown 格式展示;
* 按文件分节,使用代码块展示 `.patch` 内容;
* 每份文档前加上清晰标题与简短摘要;
* 禁止模糊性推迟或要求我继续上传文件;
* 如果无法直接读取仓库,请列出你需要的关键文件清单(按优先级),但仍需生成基于假设的分析报告与目录结构模板。
---
## 五、风格与深度要求
* 用语风格:专业、实操、能落地;
* 所有建议应附示例代码、命令、配置;
* 明确指出每个问题的严重程度Critical / High / Medium / Low
* 推荐方案必须与 Nuxt 4.2.0 当前版本特性兼容;
* 输出中请表现出架构师的思考过程(但不需解释 Prompt
---
## 六、触发执行
准备好后,请开始分析项目并输出完整报告。
触发关键词:
`ANALYZE_AND_OUTPUT_NOW`
---
## 🔚 Prompt 结束
---
是否希望我现在帮你生成这个 Prompt 的 **可直接存放在仓库根目录的 `codex_prompt.md` 版本**(带标题、描述和 front-matter
那样你只需放进仓库、Codex 扫描就能自动理解执行。