Template
admin
792131228a
Port pages for data forms, score admin, student maintenance, vacation records, menu routing, and workbench. Add team switching, dynamic menu loading, viewport scaling, and bundled local fast-crud packages.
146 lines
5.4 KiB
Markdown
146 lines
5.4 KiB
Markdown
## 原则
|
||
|
||
### 1. 编码前思考
|
||
|
||
**不要假设，不要隐藏困惑，呈现权衡**
|
||
|
||
在实现之前：
|
||
|
||
- 明确陈述你的假设，如果不确定，请提问
|
||
- 如果存在多种解读，把它们都列出来，不要默默选择其一
|
||
- 如果有更简单的方案，就指出来，在必要时提出反对意见
|
||
- 如果有不清楚的地方，停下来，说出哪里让你困惑，然后提问
|
||
|
||
### 2. 简洁优先
|
||
|
||
**用最少的代码解决问题，不要过度推测**
|
||
|
||
- 不要添加要求之外的功能
|
||
- 不要为一次性代码创建抽象
|
||
- 不要添加未要求的 "灵活性" 或 "可配置性"
|
||
- 不要为不可能发生的场景做错误处理
|
||
- 如果 200 行代码可以写成 50 行，重写它
|
||
|
||
**检验标准：** 资深工程师会觉得这过于复杂吗？如果是，简化
|
||
|
||
### 3. 精准修改
|
||
|
||
**只碰必须碰的，只清理自己造成的混乱**
|
||
|
||
编辑现有代码时：
|
||
|
||
- 不要 "改进" 相邻的代码、注释或格式
|
||
- 不要重构没坏的东西
|
||
- 匹配现有风格，即使你更倾向于不同的写法
|
||
- 如果注意到无关的死代码，提一下，不要删除它
|
||
|
||
当你的改动产生孤儿代码时：
|
||
|
||
- 删除因你的改动而变得无用的导入、变量或函数
|
||
- 不要删除预先存在的死代码，除非被要求
|
||
|
||
**检验标准：** 每一行修改都应该能直接追溯到用户的请求
|
||
|
||
### 4. 目标驱动执行
|
||
|
||
**定义成功标准，循环验证直到达成**
|
||
|
||
将指令式任务转化为可验证的目标：
|
||
|
||
"添加验证" → "为无效输入编写测试，然后让它们通过"
|
||
"修复 bug" → "编写重现 bug 的测试，然后让它通过"
|
||
"重构 X" → "确保重构前后测试都能通过"
|
||
|
||
对于多步骤任务，说明一个简短的计划：
|
||
|
||
```
|
||
1. [步骤] → 验证: [检查]
|
||
2. [步骤] → 验证: [检查]
|
||
3. [步骤] → 验证: [检查]
|
||
```
|
||
|
||
明确有力的成功标准能让你独立循环推进，模糊的标准（"让它工作"）只会不断需要澄清
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
pnpm i # 安装依赖
|
||
pnpm dev # 启动服务
|
||
pnpm build:staging # 打包构建预发布环境
|
||
pnpm build # 打包构建生产环境
|
||
pnpm preview # 先执行打包构建命令生成 dist 目录后再执行以下预览命令
|
||
pnpm lint # 代码校验与格式化
|
||
pnpm test # 单元测试
|
||
```
|
||
|
||
## 架构
|
||
|
||
### 技术栈
|
||
|
||
- 框架: Vue 3.5
|
||
- 打包构建工具: Vite 7
|
||
- 路由管理: Vue Router 5
|
||
- 状态管理: Pinia 3
|
||
- UI 组件库: Element Plus
|
||
- CSS 预处理器: Scss
|
||
- 代码校验与格式化: ESLint
|
||
- 开发语言: TypeScript
|
||
- 包管理工具: pnpm
|
||
- 网络请求: Axios
|
||
|
||
### 目录结构
|
||
|
||
```sh
|
||
v3-admin-vite
|
||
├─ .husky # commit 时进行代码校验和格式化
|
||
├─ .vscode # vscode 配置和插件
|
||
├─ public
|
||
│ ├─ favicon.ico # 网站头像
|
||
│ ├─ app-loading.css # 首屏 loading 动画
|
||
│ └─ detect-ie.js # 检测 ie
|
||
├─ src
|
||
│ ├─ common # 通用目录
|
||
│ │ ├─ apis # 通用目录 - 接口
|
||
│ │ ├─ assets # 通用目录 - 静态资源
|
||
│ │ ├─ components # 通用目录 - 组件
|
||
│ │ ├─ composables # 通用目录 - 组合式函数
|
||
│ │ ├─ constants # 通用目录 - 常量
|
||
│ │ └─ utils # 通用目录 - 工具函数
|
||
│ ├─ http # 网络请求
|
||
│ ├─ layouts # 布局
|
||
│ ├─ pages # 页面
|
||
│ │ └─ login # 登录模块
|
||
│ │ ├─ apis # 登录模块 - 私有接口
|
||
│ │ ├─ components # 登录模块 - 私有组件
|
||
│ │ ├─ composables # 登录模块 - 私有组合式函数
|
||
│ │ ├─ images # 登录模块 - 私有图片
|
||
│ │ └─ index.vue # 登录模块 - 页面
|
||
│ ├─ pinia # 状态管理
|
||
│ ├─ plugins # 插件（全局组件、自定义指令等）
|
||
│ ├─ router # 路由
|
||
│ ├─ App.vue # 入口页面
|
||
│ └─ main.ts # 入口文件
|
||
├─ tests # 单元测试
|
||
├─ types # 类型声明
|
||
│ └─ auto # 自动生成的类型（禁止手动修改）
|
||
├─ .editorconfig # 编辑器配置
|
||
├─ .env # 所有环境
|
||
├─ .env.development # 开发环境
|
||
├─ .env.production # 生产环境
|
||
├─ .env.staging # 预发布环境
|
||
├─ eslint.config.js # eslint 配置
|
||
├─ tsconfig.json # ts 配置
|
||
├─ uno.config.ts # unocss 配置
|
||
└─ vite.config.ts # vite 配置
|
||
```
|
||
|
||
- 保持目录结构清晰，遵循现有目录规范
|
||
- 同一个业务逻辑的代码和资源应当被收拢到了一起，避免在不同的目录间来回跳跃 (例如登录模块的接口应该放在 `src/pages/login/apis` 而不是 `src/common/apis`)
|
||
|
||
## 约定
|
||
|
||
- 按需参考 `.cursor/rules` 目录下规则
|
||
- 任何时候都禁止主动删除文件，必须经过同意
|
||
- **只做 PC 端（设计稿 1920 宽）**：不兼容手机/平板，禁止新增设备判断（`useDevice`、`isMobile`）与移动端媒体查询，详见 `docs/PC端适配约定.md`
|
||
- **每个业务页面都必须放 `<Title />`**（`src/common/components/Title/index.vue`，自动取路由菜单名），顶部导航型页面放在 `<PageNav>` 上方；不要手写 `<div class="head-title"><div class="tle">xxx</div></div>`。确实要还原老平台「无标题栏」形态时，先问用户，得到明确同意才可省略
|