feat(docs): 重构文档结构并更新内容

refactor(docs): 迁移文档到src目录并优化配置 style(docs): 统一代码格式和样式 chore(docs): 移除不必要的配置文件和依赖 fix(docs): 修正锁屏对话框的翻译和占位符 feat(components): 添加ElDescriptions组件支持 perf(docs): 优化文档图片加载和缩放功能
2026-10-04 17:14:21 +00:00 · 2026-05-01 22:48:13 +08:00
parent ab460ec9f6
commit e44f96740f
63 changed files with 284 additions and 3223 deletions
@@ -0,0 +1,451 @@
+---
+outline: "deep"
+title: 开发规范
+---
+# 开发规范
+
+## 📚规范概述
+
+为了保证项目代码的一致性、可读性和可维护性，FastapiAdmin 项目制定了以下开发规范。所有参与项目开发的开发者都应该遵循这些规范。
+
+## 🎨前端开发规范
+
+### 1. 代码风格
+
+#### 1.1 TypeScript 规范
+
+- 使用 TypeScript 严格模式（`"strict": true`）
+- 为所有变量、函数、接口添加类型注解
+- 避免使用 `any` 类型，除非确实无法确定类型
+- 使用接口定义对象类型，而不是类型别名
+- 使用枚举定义常量集合
+- 使用 `type` 定义联合类型和交叉类型
+- 使用 `as const` 断言确保类型安全
+- 使用 `readonly` 修饰符保护不可变数据
+- 使用 `unknown` 类型处理不确定类型的数据
+
+#### 1.2 Vue 规范
+
+- 使用 Composition API
+- 使用 `<script setup lang="ts">` 语法
+- 组件命名使用 PascalCase
+- 变量和函数命名使用 camelCase
+- 常量命名使用 UPPER_SNAKE_CASE
+- 使用 `ref()` 定义响应式变量
+- 使用 `computed()` 定义计算属性
+- 使用 `watch()` 或 `watchEffect()` 监听变化
+- 使用 `onMounted()`、`onUnmounted()` 等生命周期钩子
+- 组件 props 使用 `defineProps()` 定义并添加类型
+- 组件事件使用 `defineEmits()` 定义并添加类型
+- 组件暴露的属性和方法使用 `defineExpose()` 定义
+
+#### 1.3 CSS 规范
+
+- 使用 UnoCSS 原子化 CSS
+- 避免使用内联样式
+- 使用 BEM 命名规范（如果不使用 UnoCSS）
+- 类名使用 kebab-case
+- 避免使用 ID 选择器
+- 使用 CSS 变量管理主题
+- 避免使用 `!important` 修饰符
+- 使用 flexbox 布局确保跨平台一致性
+- 合理使用 CSS Grid 布局
+- 优化 CSS 选择器优先级
+
+### 2. 组件开发最佳实践
+
+- **单一职责原则**：每个组件只负责一个功能
+- **props 设计**：
+  - 使用 `required` 和 `default` 明确 props 要求
+  - 为复杂 props 添加验证
+  - 使用 `withDefaults()` 为 props 设置默认值
+- **事件设计**：
+  - 使用 kebab-case 命名事件
+  - 事件参数类型明确
+  - 避免在事件中传递过多参数
+- **插槽设计**：
+  - 使用具名插槽提高可读性
+  - 为插槽添加默认内容
+  - 使用作用域插槽传递数据
+- **样式设计**：
+  - 使用 `scoped` 样式避免冲突
+  - 合理使用 `:deep()` 选择器
+  - 避免在组件中使用全局样式
+
+### 3. 状态管理最佳实践
+
+- **模块化设计**：按功能模块拆分 store
+- **状态定义**：
+  - 使用 `interface` 定义 state 类型
+  - 初始化所有状态
+  - 避免使用嵌套过深的状态结构
+- **Actions 设计**：
+  - 处理异步操作
+  - 使用 try/catch 捕获错误
+  - 提交多个 mutations 时使用事务
+- **Getters 设计**：
+  - 缓存计算结果
+  - 避免在 getters 中修改状态
+  - 合理使用参数化 getters
+
+### 4. API 调用最佳实践
+
+- **模块化管理**：按功能模块组织 API 接口
+- **请求封装**：
+  - 统一处理请求头
+  - 统一处理错误
+  - 统一处理 loading 状态
+- **响应处理**：
+  - 类型定义响应数据结构
+  - 统一处理响应状态码
+  - 合理处理空数据和边界情况
+- **请求优化**：
+  - 使用防抖和节流
+  - 缓存频繁请求的结果
+  - 合理使用并发请求
+
+### 5. 性能优化建议
+
+- **代码分割**：使用路由懒加载和组件懒加载
+- **资源优化**：
+  - 压缩图片和静态资源
+  - 使用 WebP 格式图片
+  - 合理使用 CDN
+- **渲染优化**：
+  - 使用 `v-memo` 缓存计算结果
+  - 合理使用 `v-if` 和 `v-show`
+  - 避免在模板中使用复杂表达式
+- **网络优化**：
+  - 使用 HTTP/2 或 HTTP/3
+  - 启用 Gzip 或 Brotli 压缩
+  - 合理设置缓存策略
+
+### 6. 测试最佳实践
+
+- **测试分层**：单元测试、集成测试、端到端测试
+- **测试覆盖率**：
+  - 核心功能 100% 覆盖
+  - 复杂逻辑 80% 以上覆盖
+  - 简单功能 50% 以上覆盖
+- **测试工具**：
+  - 使用 Vitest 进行单元测试
+  - 使用 Playwright 进行端到端测试
+  - 使用 Vue Test Utils 进行组件测试
+
+### 7. 代码审查要点
+
+- **类型安全**：检查 TypeScript 类型定义是否正确
+- **代码质量**：检查代码是否简洁、清晰
+- **性能问题**：检查是否存在性能瓶颈
+- **安全问题**：检查是否存在安全漏洞
+- **规范遵循**：检查是否遵循项目开发规范
+
+## 🐍后端开发规范
+
+### 1. 代码风格
+
+#### 1.1 Python 规范
+
+- 遵循 PEP 8 代码风格
+- 使用 4 个空格缩进
+- 行长度不超过 100 字符
+- 函数和类之间空两行
+- 方法之间空一行
+- 导入语句按标准库、第三方库、本地库分组
+
+#### 1.2 FastAPI 规范
+
+- 使用 FastAPI 装饰器定义路由
+- 使用 Pydantic 模型定义请求和响应数据
+- 使用依赖注入处理认证和权限
+- 使用路径参数和查询参数
+- 使用 HTTPException 处理错误
+- 使用 Depends 注入依赖
+
+### 2. 目录结构
+
+```
+backend/app/
+├── api/             # API 接口
+├── common/          # 公共代码
+├── config/          # 配置管理
+├── core/            # 核心功能
+├── plugin/          # 插件系统
+├── scripts/         # 脚本工具
+└── utils/           # 工具函数
+```
+
+### 3. 插件开发规范
+
+- 插件目录应该以 `module_` 开头
+- 插件应该包含 `controller.py`、`model.py`、`schema.py`、`service.py`、`crud.py` 等文件
+- 控制器应该使用 `APIRouter` 定义路由
+- 路由前缀应该与模块名对应（module_xxx -> /xxx）
+- 控制器应该使用 `OperationLogRoute` 记录操作日志
+- 接口应该使用 `AuthPermission` 进行权限控制
+
+### 4. 数据库规范
+
+- 使用 SQLAlchemy 2.0 ORM
+- 使用 Alembic 进行数据库迁移
+- 模型类应该继承自 `Base`
+- 模型类应该定义 `__tablename__` 属性
+- 字段命名应该使用 snake_case
+- 表名应该使用 snake_case 复数形式
+- 外键应该使用 `ForeignKey` 定义
+- 关系应该使用 `relationship` 定义
+
+### 5. 认证和权限规范
+
+- 使用 JWT 进行身份认证
+- 使用 RBAC 模型进行权限管理
+- 接口应该添加权限控制装饰器
+- 权限字符串格式：`module:controller:action`
+- 权限应该在角色管理中配置
+
+### 6. 错误处理规范
+
+- 使用 `HTTPException` 处理 HTTP 错误
+- 使用自定义异常处理全局错误
+- 错误响应应该有统一的格式
+- 错误应该记录到日志
+
+### 7. 日志规范
+
+- 使用 Python 标准库 `logging` 模块
+- 日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL
+- 日志应该包含时间、级别、模块、消息等信息
+- 关键操作应该记录日志
+- 错误应该记录详细信息
+
+## 📦FastApp 移动端开发规范
+
+### 1. 代码风格
+
+- 遵循前端开发规范
+- 使用 TypeScript 严格模式
+- 使用 Vue 3 Composition API
+- 使用 `<script setup lang="ts">` 语法
+- 组件命名使用 PascalCase
+- 变量和函数命名使用 camelCase
+
+### 2. 目录结构
+
+```
+FastApp/src/
+├── api/             # API 接口
+├── components/      # 组件
+├── composables/     # 组合式函数
+├── constants/       # 常量定义
+├── enums/           # 枚举定义
+├── layouts/         # 布局组件
+├── pages/           # 页面文件
+├── router/          # 路由配置
+├── static/          # 静态资源
+├── store/           # 状态管理
+├── styles/          # 样式文件
+├── types/           # TypeScript 类型定义
+├── utils/           # 工具函数
+├── App.vue          # 应用根组件
+└── main.ts          # 应用入口文件
+```
+
+### 3. 页面开发规范
+
+- 页面组件应该放在 `pages` 目录下
+- 页面目录应该使用 kebab-case
+- 页面组件应该包含 `index.vue` 文件
+- 页面组件可以包含 `data.ts`、`types.ts` 等辅助文件
+- 页面组件应该使用 `onLoad()`、`onShow()` 等生命周期钩子
+- 页面跳转应该使用 `uni.navigateTo()`、`uni.switchTab()` 等 API
+
+### 4. API 调用规范
+
+- 遵循前端 API 调用规范
+- 使用封装的 `request.ts` 工具
+- API 接口应该按模块分类
+- API 调用应该处理错误情况
+- API 调用应该显示加载状态
+
+### 5. 跨平台适配规范
+
+- 使用条件编译处理平台差异
+- 使用 `#ifdef`、`#ifndef`、`#endif` 指令
+- 平台特有 API 应该添加条件编译
+- 样式应该考虑不同平台的差异
+- 布局应该使用 flexbox 确保跨平台一致性
+
+## 🎯Git 提交规范
+
+### 1. 分支管理
+
+- `master`：主分支，用于发布生产版本
+- `dev`：开发分支，用于集成开发
+- `feature/xxx`：功能分支，用于开发新功能
+- `bugfix/xxx`：修复分支，用于修复 bug
+- `hotfix/xxx`：热修复分支，用于紧急修复生产环境问题
+
+### 2. 提交信息规范
+
+提交信息应该遵循以下格式：
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+#### 2.1 Type
+
+- `feat`：新功能
+- `fix`：修复 bug
+- `docs`：文档修改
+- `style`：代码风格修改
+- `refactor`：代码重构
+- `test`：测试代码修改
+- `chore`：构建工具或依赖修改
+- `revert`：回滚提交
+
+#### 2.2 Scope
+
+- 可选，用于指定修改的范围
+- 例如：`api`、`component`、`page`、`store` 等
+
+#### 2.3 Subject
+
+- 简短的提交信息，不超过 50 个字符
+- 使用祈使句，动词开头
+- 首字母小写
+- 不需要句号结尾
+
+#### 2.4 Body
+
+- 可选，详细的提交信息
+- 每行不超过 72 个字符
+- 解释为什么修改，而不是如何修改
+
+#### 2.5 Footer
+
+- 可选，用于引用 issue 或 BUG
+- 例如：`Closes #123`、`Fixes #456`
+
+### 3. 提交示例
+
+```
+feat(api): 添加用户登录接口
+
+- 实现用户登录功能
+- 添加 JWT 认证
+- 处理登录错误情况
+
+Closes #123
+```
+
+```
+fix(frontend): 修复首页轮播图显示问题
+
+- 修复轮播图高度计算错误
+- 优化轮播图切换动画
+
+Fixes #456
+```
+
+```
+docs: 更新开发文档
+
+- 添加 API 文档说明
+- 完善部署指南
+```
+
+### 4. Pull Request 规范
+
+- Pull Request 应该从功能分支合并到 dev 分支
+- Pull Request 标题应该清晰、语义化
+- Pull Request 描述应该详细说明修改内容
+- Pull Request 应该包含相关的 issue 链接
+- Pull Request 应该通过所有测试
+- Pull Request 应该由至少一个 reviewer 审核
+
+## 🔧工具链规范
+
+### 1. 前端工具链
+
+- 使用 Vite 作为构建工具
+- 使用 ESLint 进行代码检查
+- 使用 Prettier 进行代码格式化
+- 使用 Stylelint 进行样式检查
+- 使用 Husky 进行 Git 钩子管理
+- 使用 Commitlint 进行提交信息检查
+
+### 2. 后端工具链
+
+- 使用 Poetry 或 pip 管理依赖
+- 使用 Pylint 或 Flake8 进行代码检查
+- 使用 Black 进行代码格式化
+- 使用 MyPy 进行类型检查
+- 使用 pytest 进行测试
+
+## 💡开发流程规范
+
+### 1. 需求分析
+
+- 明确功能需求
+- 分析业务逻辑
+- 确定技术方案
+
+### 2. 设计阶段
+
+- 设计数据库表结构
+- 设计 API 接口
+- 设计前端页面
+- 设计组件结构
+
+### 3. 开发阶段
+
+- 创建分支
+- 实现功能
+- 编写测试
+- 运行测试
+
+### 4. 测试阶段
+
+- 单元测试
+- 集成测试
+- 端到端测试
+- 性能测试
+
+### 5. 部署阶段
+
+- 构建生产版本
+- 部署到测试环境
+- 进行回归测试
+- 部署到生产环境
+
+### 6. 维护阶段
+
+- 监控系统运行状态
+- 处理 bug 和问题
+- 进行性能优化
+- 进行功能迭代
+
+## 📚参考资料
+
+- [TypeScript 官方文档](https://www.typescriptlang.org/docs/)
+- [Vue 官方文档](https://vuejs.org/docs/)
+- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
+- [SQLAlchemy 官方文档](https://docs.sqlalchemy.org/)
+- [PEP 8 代码风格指南](https://peps.python.org/pep-0008/)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [ESLint 官方文档](https://eslint.org/docs/)
+- [Prettier 官方文档](https://prettier.io/docs/en/)
+
+## 🤝贡献指南
+
+如果您对开发规范有任何建议或改进意见，欢迎提交 Issue 或 Pull Request。我们会认真考虑每一个建议，不断完善开发规范。
+
+## 📄许可协议
+
+本开发规范文档采用 MIT 许可协议，与 FastapiAdmin 项目保持一致。
+