From 926485b6eb8a09ef237f703b34f09fb0aa183f48 Mon Sep 17 00:00:00 2001 From: zhonghua Date: Thu, 12 Mar 2026 13:41:32 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E5=89=8D=E7=AB=AF=E8=A7=84?= =?UTF-8?q?=E8=8C=83=EF=BC=8C=E6=B7=BB=E5=8A=A0=E5=8E=9F=E5=AD=90=E6=A0=B7?= =?UTF-8?q?=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/前端项目规范.md | 266 ++++ reading-platform-frontend/package-lock.json | 1359 +++++++++++++++++ reading-platform-frontend/package.json | 1 + reading-platform-frontend/src/components.d.ts | 22 + reading-platform-frontend/src/main.ts | 1 + .../src/views/admin/LayoutView.vue | 7 +- reading-platform-frontend/vite.config.ts | 5 + 7 files changed, 1658 insertions(+), 3 deletions(-) create mode 100644 docs/前端项目规范.md diff --git a/docs/前端项目规范.md b/docs/前端项目规范.md new file mode 100644 index 0000000..2dd1edd --- /dev/null +++ b/docs/前端项目规范.md @@ -0,0 +1,266 @@ +# AI 开发规范(media-science-frontend) + +本文档基于当前仓库的真实配置与现有代码风格整理,目标是让 **AI/新同学**在不“自作主张改风格/改架构”的前提下,稳定产出可合并的代码。 + +## 技术栈与关键约束 + +- **框架**:Vue 3 + TypeScript + Vite(`type: module` +- **路由**:`unplugin-vue-router` 文件路由(`vue-router/auto`),Hash 模式(`createWebHashHistory()`) +- **状态**:Pinia(setup store 风格) +- **图表**:图表:echarts +- **UI**:Ant Design Vue +- **样式**:UnoCSS(`virtual:uno.css`),允许在模板里大量使用原子类(复杂样式例如动画,渐变等使用class声明,其余使用原子样式) +- **国际化**:`@intlify/unplugin-vue-i18n`(`src/locales/*.json`) +- **格式化门禁**:Husky + lint-staged + Prettier(提交前会对 `*.{vue,ts,tsx,js,jsx,md,css,less,json}` 自动 `prettier --write`) +- **TypeScript 严格性**:`strict: true`,并开启 `noUnusedLocals/noUnusedParameters` +- **自动导入**:`unplugin-auto-import`(`vue`、`pinia`、`@vueuse/core`、router auto imports),因此代码里可能**未显式 import** `ref/computed/watch/...` + +## 项目架构(目录分层) + +以 `src/` 为根: + +- **入口**:`src/main.ts`(创建 app、挂载 router/pinia/Antd、全局指令) +- **根组件**:`src/App.vue`(全局初始化逻辑、主题/locale、监听生命周期等) +- **页面**:`src/pages/**`(文件路由:一个目录通常对应一个页面模块;页面内可用 `definePage({ alias: [...] })`) +- **通用组件**:`src/components/**`(跨页面复用的 UI/布局组件,如 `Layout.vue`) +- **状态管理**:`src/store/**`(Pinia stores) +- **接口层**:`src/api/**` + - `src/api/generated/**`:Orval 自动生成(接口类型与路径的唯一真源,禁止手改) + - `src/api/client.ts`:项目侧统一入口/别名层(导出客户端实例与类型工具) + - `src/api/*.ts`:业务适配层(可选:解包 Result、分页扁平化、兼容旧页面结构等) +- **工具**:`src/utils/**`(如 `useRouteUtil.ts`、`useLocalStorage.ts`、`useWebSocket.ts` 等) +- **类型声明**:`src/**/*.d.ts`、`src/global.d.ts`、`src/vite-env.d.ts` + +### 仓库根目录速览(常用) + +``` +. +├─ src/ # 应用源码 +├─ public/ # 静态资源(按 Vite 约定) +├─ vite/ # Vite 插件/构建辅助(如 LocaleType) +├─ vite.config.ts # 构建与插件配置(含 proxy、自动路由、自动导入等) +├─ uno.config.ts # UnoCSS 主题/shortcuts +├─ tsconfig*.json # TS 严格配置(strict + noUnused*) +├─ .prettierrc # 代码格式标准(提交前会强制执行) +├─ .husky/pre-commit # 提交钩子:lint-staged +├─ .env* # 环境变量(通过 import.meta.env 读取) +└─ AI_DEV_GUIDE.md # 本规范 +``` + +## 编码风格(必须遵守) + +### 代码格式(Prettier 为准) + +来自 `.prettierrc`: + +- **单引号**:`'...'` +- **缩进**:2 空格,禁用 tab +- **行宽**:100 + +> 任何“手动对齐/自定义格式化习惯”都会被提交前的 Prettier 重写,AI 不要和格式化对抗。 + +### Vue SFC 约定 + +- **优先使用**:`