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.
42 lines
1.8 KiB
Markdown
42 lines
1.8 KiB
Markdown
# 代码规范与质量分析
|
||
|
||
## 主要发现
|
||
- 类型定义（High）
|
||
- `content.config.ts` 缺少 Index 页的 `title/description/seo`，导致 `page?.title` 等缺少类型提示；特定字段（`icon/highlight/spotlight`）与 YAML 不一致。
|
||
- 组合式命名（Medium）
|
||
- `LocalizedCollection.ts` 建议改为 `useLocalizedCollection.ts`，与 Nuxt 习惯保持一致，便于检索与自动导入心智统一。
|
||
|
||
## 统一约定
|
||
- 文件与目录
|
||
- composables：`useXxx.ts`（示例：`useLocalizedCollection.ts`）。
|
||
- 页面：`pages/webDev.vue`（帕斯卡命名不用于路由页）。
|
||
- 工具：`utils/some-helper.ts`，避免与 composables 混用。
|
||
- 代码风格
|
||
- TypeScript、ESM、Vue SFC `<script setup lang="ts">`。
|
||
- 缩进 2 空格；组件/组合式函数采用明确的返回类型。
|
||
- i18n 使用嵌套点式键：`$t('index.featuredProjects.viewDemo')`。
|
||
- 提交规范
|
||
- 参考历史：`feat(content): ...`、`refactor(ui): ...`、`feat(pages): ...`。
|
||
- 分支：`feat/<desc>`、`fix/<desc>`。
|
||
|
||
## 重构建议（示例）
|
||
1) 内容类型对齐（Critical）
|
||
- 见补丁 `0001-content-config-align.patch`。
|
||
2) 工程脚本完善（High）
|
||
- 新增脚本：`lint/typecheck/check`，见补丁 `0002-package-scripts.patch`。
|
||
3) 组合式命名（Medium）
|
||
- 将 `LocalizedCollection.ts` 重命名为 `useLocalizedCollection.ts`（建议）。
|
||
|
||
## 示例：更严格的返回类型
|
||
```ts
|
||
export function useLocalizedCollection<B extends string>(baseName: B) {
|
||
const { locale } = useI18n()
|
||
type LocalizedKey = keyof { [K in keyof Collections as K extends `${B}_${string}` ? K : never]: any }
|
||
type Schema = Collections[LocalizedKey]
|
||
return useAsyncData<Schema | null>(`${baseName}-${locale.value}`, async () => {
|
||
// ...
|
||
})
|
||
}
|
||
```
|
||
|