# 架构结构与改进方案

本文审计 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`，安全可用。