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.
53 lines
2.3 KiB
Markdown
53 lines
2.3 KiB
Markdown
# 架构结构与改进方案
|
||
|
||
本文审计 Nuxt 4.2.0 架构与模块使用，指出结构异味并提供可落地改进。
|
||
|
||
## 现状评估
|
||
- 模块与目录（Low）
|
||
- `app/`（pages/layouts/composables/utils/assets）职责清晰。
|
||
- `content/` 与 `content.config.ts` 使用 zod 定义 Schema，利于类型驱动内容。
|
||
- `i18n/` 采用 `locales/<locale>` 结构；`no_prefix` 策略与当前站点定位一致。
|
||
- Nuxt 4 特性使用（Medium）
|
||
- 自动导入：已使用（如 `useLocalizedCollection`）。建议将文件命名统一为 `useXxx.ts` 便于识别。
|
||
- Runtime Config：未使用。建议引入 `runtimeConfig` 管理外部域名、监控 DSN 等。
|
||
- Nitro Route Rules/缓存：未配置。建议为首页与静态资源设置 `prerender`+`swr` 与长缓存。
|
||
- 设计风险（Critical）
|
||
- `content.config.ts` 的 Index Schema 与 YAML 不一致：缺少 `title/description/seo` 字段；`icon/highlight/spotlight` 约束与内容不符。
|
||
|
||
## 改进策略
|
||
1) 内容 Schema 对齐（Critical）
|
||
- 为 Index 增加 `title/description/seo`；将 `icon` 设为可选，将 `highlight/spotlight` 设为可选并默认 `false`。
|
||
- 参见补丁：`0001-content-config-align.patch`。
|
||
2) 运行时配置（Medium）
|
||
- 在 `nuxt.config.ts` 中：
|
||
```ts
|
||
export default defineNuxtConfig({
|
||
runtimeConfig: {
|
||
sentryDsn: '',
|
||
public: { assetBase: 'https://img.tootaio.com' },
|
||
},
|
||
})
|
||
```
|
||
- 在代码中读取 `useRuntimeConfig()`，避免硬编码外链与密钥。
|
||
3) 路由规则与缓存（Medium）
|
||
- 为首页预渲染并设置 SWR，为构建产物设置 immutable 缓存：
|
||
```ts
|
||
export default defineNuxtConfig({
|
||
routeRules: {
|
||
'/': { prerender: true, swr: 3600 },
|
||
'/_nuxt/**': {
|
||
headers: { 'cache-control': 'public, max-age=31536000, immutable' },
|
||
},
|
||
},
|
||
})
|
||
```
|
||
- 参见补丁：`0004-nuxt-route-rules.patch`。
|
||
4) 组合式命名与分层（Low）
|
||
- 将 `app/composables/LocalizedCollection.ts` 重命名为 `useLocalizedCollection.ts`。
|
||
- 保持 composable 只做“取数+组装”，复杂 UI/状态拆到组件/Pinia（若引入）。
|
||
|
||
## 与 Nuxt 4.2.0 兼容性
|
||
- 现有 `compatibilityDate: '2025-07-15'` 符合要求。
|
||
- 上述配置属于稳定 API：`routeRules/runtimeConfig/auto-import`，安全可用。
|
||
|