# 目录结构设计 本章详细说明项目目录结构设计，包括后端 `src/` 和前端 `ui/src/` 的完整目录树及各目录的设计意图。 :::tip 设计原则 目录结构遵循「按功能分组、按职责分层」的原则。后端 `src/` 按技术层次组织（core / middleware / routes / modules），前端 `ui/src/` 按功能领域组织（api / views / components / store）。每个目录有明确的边界和单一职责。 ::: ## 后端目录结构 ``` src/ ├── app.py # 应用入口：create_app() 组装中间件、路由、异常处理 ├── core/ # 核心基础设施层 │ ├── __init__.py # 统一导出 │ ├── database.py # 数据库引擎：SQLAlchemy 初始化 │ ├── redis_client.py # Redis 客户端：连接池、Lua 脚本 │ ├── jwt.py # JWT 工具：签发 / 解析 / 续签 / 黑名单 │ ├── password.py # 密码工具：bcrypt 哈希 + 盐值 │ ├── security.py # 安全工具：get_user_id / get_username / get_realname │ ├── response.py # 统一响应：R.ok() / R.failed() / R.page() │ ├── exceptions.py # 自定义异常：BizError │ ├── permission.py # 权限装饰器：check_permission │ ├── logger.py # 日志配置：结构化日志、文件输出 │ └── scheduler.py # 定时任务调度器 │ ├── middleware/ # HTTP 中间件层 │ ├── __init__.py # 统一导出 │ ├── auth.py # JWT 认证中间件：login_required │ ├── cors.py # CORS 跨域中间件 │ ├── demo.py # 演示模式中间件：check_demo │ ├── errors.py # 全局异常处理 │ ├── operation_log.py # 操作日志中间件 │ └── transaction.py # AOP 事务管理中间件 │ ├── common/ # 公共模块层 │ ├── __init__.py # 统一导出 │ ├── base_model.py # 模型基类：通用字段 + to_dict() 序列化 │ ├── base_db.py # 数据库操作基类：save() 持久化方法 │ ├── base_repository.py # 仓库基类：通用 CRUD + 软删除 + 分页 │ ├── base_service.py # 服务基类：模板方法 CRUD + 差异点钩子 │ ├── forms/ # 表单基类 │ │ ├── __init__.py # 统一导出 │ │ ├── base_form.py # BaseForm 基类 │ │ └── fields.py # 自定义字段 │ ├── constants/ # 常量与枚举 │ │ ├── __init__.py # 统一导出 │ │ └── common.py # 通用常量 │ └── utils/ # 工具函数 │ ├── __init__.py # 统一导出 │ ├── captcha.py # 验证码生成 │ ├── case_converter.py # 驼峰/下划线互转 │ ├── excel_utils.py # Excel 导入导出 │ ├── file.py # 文件工具 │ ├── ip.py # IP 工具：客户端 IP 提取 │ ├── ip2region.py # IP 地理位置解析 │ ├── json.py # JSON 工具 │ ├── model_utils.py # 模型工具 │ ├── regular.py # 正则工具 │ ├── request.py # 请求工具：parse_request_body / parse_id_list │ ├── rich_text.py # 富文本处理 │ ├── time_utils.py # 时间工具 │ └── user_agent.py # User-Agent 解析 │ ├── routes/ # 路由装配层 │ ├── __init__.py # 统一导出 │ └── v1.py # API v1 路由注册中心 │ ├── modules/ # 业务模块层（纯业务逻辑） │ ├── auth/ # 认证模块 │ │ ├── router.py # 登录/登出/验证码/Token 刷新 │ │ ├── schema.py # 登录表单校验 │ │ └── service.py # 登录/登出/验证码/锁定逻辑 │ ├── system/ # 系统管理模块组 │ │ ├── position/ # 岗位管理 │ │ │ ├── models.py # Position 模型 │ │ │ ├── repository.py # PositionRepository │ │ │ ├── schema.py # PositionForm / PositionStatusForm │ │ │ ├── service.py # PositionService │ │ │ └── router.py # 路由定义 │ │ ├── level/ # 职级管理（同结构） │ │ ├── dept/ # 部门管理（支持树形） │ │ ├── role/ # 角色管理 │ │ ├── menu/ # 菜单管理（支持树形） │ │ └── user/ # 用户管理（复杂模块） │ ├── association/ # 关联模块组 │ │ ├── role_menu/ # 角色菜单关联 │ │ └── user_role/ # 用户角色关联 │ ├── dictionary/ # 字典模块组 │ │ ├── dict/ # 字典 │ │ └── dict_item/ # 字典项 │ ├── configuration/ # 配置模块组 │ │ ├── config/ # 配置 │ │ └── config_item/ # 配置项 │ ├── cms/ # 内容管理模块组 │ │ ├── article/ # 文章管理 │ │ ├── category/ # 文章分类 │ │ └── link/ # 友链管理 │ ├── city/ # 城市/行政区划 │ ├── notice/ # 通知公告 │ ├── param/ # 参数管理 │ ├── job/ # 定时任务（含调度器） │ ├── job_log/ # 任务执行日志 │ ├── login_log/ # 登录日志 │ ├── operation_log/ # 操作日志 │ ├── upload/ # 文件上传 │ ├── file_template/ # 文件模板 │ ├── generator/ # 代码生成器 │ └── example/ # 案例演示 │ ├── models_registry.py # 模型注册表 │ └── migrations/ # Flask-Migrate 迁移 ├── env.py # 迁移环境配置 └── versions/ # 迁移版本文件 └── 0001_baseline.py # 基线迁移 ``` ### 目录设计意图 | 目录 | 设计意图 | |:---|:---| | `core/` | 基础设施层，提供所有模块共用的工具和配置。不包含业务逻辑 | | `middleware/` | 中间件独立于 core，职责单一，便于按需注册和测试 | | `common/` | 公共模块层，提供基类、常量和工具函数 | | `routes/` | 路由装配层，将所有模块的 Blueprint 集中注册 | | `modules/` | 业务模块层，按功能域分组（system / dictionary / configuration / cms），每个模块包含 models + repository + schema + service + router | | `modules/{group}/` | 模块组：将关联模块归组（如 system 下的 user / role / menu / dept） | ## 前端目录结构 ``` ui/src/ ├── main.ts # 应用入口 ├── App.vue # 根组件 ├── api/ # API 接口层（按后端模块对应） │ ├── system/ # 系统管理 API │ │ ├── position.ts # 岗位管理 API │ │ ├── level.ts # 职级管理 API │ │ ├── dept.ts # 部门管理 API │ │ ├── role.ts # 角色管理 API │ │ ├── menu.ts # 菜单管理 API │ │ └── user.ts # 用户管理 API │ ├── content/ # 内容管理 API │ │ ├── article.ts # 文章管理 API │ │ ├── category.ts # 文章分类 API │ │ ├── notice.ts # 通知公告 API │ │ └── link.ts # 友链管理 API │ ├── data/ # 数据管理 API │ │ ├── dict.ts # 字典管理 API │ │ ├── config.ts # 配置管理 API │ │ └── param.ts # 参数管理 API │ ├── common/ # 公共 API │ │ └── index.ts # 登录/登出/验证码 │ ├── dashboard/ # 仪表盘 API │ ├── file/ # 文件管理 API │ ├── monitor/ # 监控 API │ ├── region/ # 行政区划 API │ ├── setting/ # 设置 API │ └── tool/ # 工具 API │ ├── views/ # 页面视图（按功能域分组） │ ├── login/ # 登录页 │ ├── dashboard/ # 仪表盘 │ ├── system/ # 系统管理页面 │ │ ├── position/ # 岗位管理页面 │ │ ├── level/ # 职级管理页面 │ │ ├── dept/ # 部门管理页面 │ │ ├── role/ # 角色管理页面 │ │ ├── menu/ # 菜单管理页面 │ │ └── user/ # 用户管理页面 │ ├── content/ # 内容管理页面 │ ├── data/ # 数据管理页面 │ ├── monitor/ # 监控页面 │ ├── setting/ # 设置页面 │ ├── tool/ # 工具页面 │ ├── file/ # 文件管理页面 │ ├── exception/ # 异常页面（404/403/500） │ ├── about/ # 关于页面 │ ├── iframe/ # 内嵌页面 │ └── redirect/ # 重定向页面 │ ├── components/ # 全局公共组件 │ ├── Table/ # 表格组件 │ ├── Form/ # 表单组件 │ ├── Modal/ # 弹窗组件 │ ├── Upload/ # 上传组件 │ ├── Editor/ # 富文本编辑器 │ ├── Excel/ # Excel 导入导出 │ ├── Select/ # 选择器组件 │ ├── Cropper/ # 图片裁剪 │ ├── Qrcode/ # 二维码 │ ├── Page/ # 分页组件 │ ├── Password/ # 密码组件 │ ├── Authority/ # 权限组件 │ ├── CheckToken/ # Token 检查 │ ├── ChinaArea/ # 中国行政区划 │ ├── Websocket/ # WebSocket 组件 │ ├── Lockscreen/ # 锁屏 │ ├── CountTo/ # 数字动画 │ ├── Render/ # 自定义渲染 │ ├── Application/# 应用组件 │ ├── Region/ # 区域选择 │ ├── TableSelect/# 表格选择 │ ├── icon/ # 图标组件 │ ├── importFile/ # 文件导入 │ ├── numberInput/# 数字输入 │ └── pagination/ # 分页组件 │ ├── store/ # Pinia 状态管理 │ └── modules/ # 状态模块 │ ├── user.ts # 用户状态（Token/用户信息/权限） │ ├── app.ts # 应用状态（主题/布局/语言） │ ├── permission.ts # 权限状态（动态路由） │ ├── tabs.ts # 标签页状态 │ └── dict.ts # 字典缓存 │ ├── router/ # Vue Router 路由 │ ├── index.ts # 路由配置入口 │ └── menus/ # 菜单路由 │ ├── hooks/ # Composition API Hooks │ ├── core/ # 核心 Hooks │ ├── event/ # 事件 Hooks │ ├── setting/ # 设置 Hooks │ └── web/ # Web Hooks │ ├── layout/ # 布局组件 │ └── components/ # 布局子组件（侧边栏/头部/标签页） │ ├── directives/ # 自定义指令 ├── enums/ # 前端枚举 ├── plugins/ # 插件 ├── settings/ # 应用设置 ├── styles/ # 全局样式 │ ├── theme/ # 主题样式 │ └── transition/ # 过渡动画 ├── utils/ # 工具函数 │ ├── http/ # Axios 封装 │ ├── file/ # 文件工具 │ ├── helper/ # 辅助函数 │ ├── is/ # 类型判断 │ └── lib/ # 第三方库封装 └── assets/ # 静态资源 ├── icons/ # 图标 └── images/ # 图片 ``` ### 前后端目录对应关系 | 前端目录 | 后端目录 | 说明 | |:---|:---|:---| | `api/system/position.ts` | `modules/system/position/router.py` | API 接口定义一一对应 | | `views/system/position/` | `modules/system/position/` | 页面视图对应业务模块 | | `store/modules/user.ts` | `modules/auth/service.py` | 用户状态对应认证服务 | | `components/` | `common/utils/` + `core/` | 公共组件对应后端工具 | ## 目录规范 :::warning 目录命名规范 1. **后端**：目录名使用小写下划线（snake_case），与 Python 模块命名一致 2. **前端**：目录名使用小写 kebab-case 或 camelCase，与 Vue 生态习惯一致 3. **模块文件**：每个模块固定包含 `models.py` / `repository.py` / `schema.py` / `service.py` / `router.py` 五个文件 4. **路由文件**：每个模块对应一个路由文件，文件名与模块名一致 ::: ## 总结 目录结构是项目可维护性的基础。后端按技术层次（core / middleware / common / routes / modules）组织，前端按功能领域（api / views / components / store）组织。每个目录有明确的边界和单一职责，模块内部遵循固定的文件结构（models + repository + schema + service + router）。这种设计使得新开发者能快速定位代码，新模块能按既定模式快速创建。