目录说明

在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。

1. 清晰的层次结构：按照功能模块划分目录，方便团队成员快速定位代码。
2. 模块化管理：通过多模块结构，实现功能模块的独立管理，提高系统的可维护性和扩展性。
3. 分层架构：HTTP 层、业务层、数据层分离，职责清晰。
4. 提升开发效率：清晰的目录结构和模块划分，减少查找代码的时间，提高开发效率。

项目根目录

├── src/                          // 后端源码
├── ui/                           // 前端源码（Vue3 + ElementPlus）
├── config/                       // 配置文件（base / database / redis / auth）
├── docker/                       // Docker 部署配置（Dockerfile / docker-compose.yml）
├── document/                     // 项目文档（SQL脚本、迁移日志等）
├── migrations/                   // Alembic 数据库迁移脚本
├── scripts/                      // 脚本工具（setup_db / migrate_db 等）
├── tests/                        // 测试代码（contract / unit / integration）
├── wiki/                         // VitePress 文档站点
├── static/                       // 静态资源（验证码字体等）
├── uploads/                      // 上传文件存储目录
├── app.py                        // 后端启动入口
├── gunicorn.conf.py              // Gunicorn 生产环境配置
├── generator.py                  // 代码生成器 CLI 入口
├── config.json                   // 代码生成器配置
├── .env.example                  // 环境变量模板
├── .env                          // 环境变量（不提交到版本控制）
├── Makefile                      // 快捷命令（db-init、migrate-*、db-migrate）
├── pyproject.toml                // 项目元数据与工具配置
├── requirements.txt              // Python 依赖清单
├── requirements-dev.txt          // 开发依赖清单
├── .flake8                       // Flake8 代码检查配置
├── .pre-commit-config.yaml       // Pre-commit 钩子配置
├── .dockerignore                 // Docker 构建忽略规则
└── README.md                     // 项目说明

后端目录 (src/)

src/
├── app.py                        // 应用工厂（create_app()）
├── extensions.py                 // Flask 扩展注册
├── models_registry.py            // 模型注册中心（Flask-Migrate 全量识别）
├── core/                         // 核心基础设施（与业务无关）
│   ├── database.py               //   SQLAlchemy 引擎 / db 实例
│   ├── redis_client.py           //   Redis 同步客户端
│   ├── jwt.py                    //   JWT 签发 / 解析 / 刷新 / 黑名单
│   ├── password.py               //   bcrypt 密码加密 / 校验
│   ├── response.py               //   R.ok() / R.failed() 统一响应
│   ├── exceptions.py             //   BizError 业务异常
│   ├── security.py               //   get_user_id() / get_username() / get_realname()
│   ├── permission.py             //   @check_permission 装饰器
│   ├── scheduler.py              //   定时任务调度器管理
│   └── mail.py                   //   邮件发送
├── common/                       // 公共组件
│   ├── base_model.py             //   ORM 基类（id / create_time / is_delete 等公共字段）
│   ├── base_db.py                //   save() / save_all() 方法（flush 不 commit）
│   ├── base_repository.py        //   通用 Repository 基类（CRUD / 分页 / 软删过滤）
│   ├── base_service.py           //   通用 Service 基类（模板方法 + 覆写钩子）
│   ├── forms/                    //   表单校验
│   │   ├── base_form.py          //     BaseForm（WTForms 基类，含 ArrayField 处理）
│   │   └── fields.py             //     自定义字段（ArrayField）
│   ├── constants/                //   常量定义
│   │   └── common.py             //     PAGE_SIZE / DEFAULT_PASSWORD 等
│   └── utils/                    //   工具函数
│       ├── request.py            //     parse_request_body / parse_batch_ids / parse_batch_ids
│       ├── captcha.py            //     验证码生成（Pillow）
│       ├── file.py               //     文件工具
│       ├── ip.py                 //     IP 地址获取
│       ├── ip2region.py          //     IP 地理位置解析
│       ├── user_agent.py         //     User-Agent 解析
│       ├── rich_text.py          //     富文本 XSS 过滤 + 文件迁移
│       ├── case_converter.py     //     camelCase <-> snake_case 转换
│       ├── model_utils.py        //     model_to_dict / models_to_list
│       ├── regular.py            //     WTForms 错误提取
│       ├── json.py               //     自定义 JSON 编码器
│       ├── excel_utils.py        //     Excel 导入导出工具
│       └── time_utils.py         //     时间工具
├── middleware/                   // 中间件
│   ├── __init__.py               //   统一导出
│   ├── auth.py                   //   登录校验 + 白名单
│   ├── demo.py                   //   演示模式（@check_demo）
│   ├── transaction.py            //   AOP 事务拦截器
│   ├── operation_log.py          //   操作日志自动记录
│   └── errors.py                 //   异常处理器
├── routes/                       // 路由注册
│   └── v1.py                     //   API v1 路由注册中心（BLUEPRINTS 列表）
└── modules/                      // 业务模块（可插拔）
    ├── auth/                     //   认证模块（登录/登出/验证码/刷新Token）
    ├── system/                   //   系统管理
    │   ├── user/                 //     用户（models / schema / repository / service / router）
    │   ├── role/                 //     角色
    │   ├── menu/                 //     菜单
    │   ├── dept/                 //     部门
    │   ├── position/             //     岗位
    │   └── level/                //     职级
    ├── association/              //   关联表模块
    │   ├── user_role/            //     用户-角色关联
    │   └── role_menu/            //     角色-菜单关联
    ├── dictionary/               //   数据字典（dict / dict_item / dict_utils）
    ├── configuration/            //   系统配置（config / config_item）
    ├── cms/                      //   内容管理
    │   ├── article/              //     文章管理
    │   ├── category/             //     分类管理
    │   └── link/                 //     友情链接
    ├── city/                     //   行政区划
    ├── job/                      //   定时任务（含 scheduler_service / executor）
    ├── job_log/                  //   任务执行日志
    ├── notice/                   //   通知公告
    ├── param/                    //   参数管理
    ├── file_template/            //   文件模板
    ├── upload/                   //   文件上传
    ├── login_log/                //   登录日志
    ├── operation_log/            //   操作日志
    ├── example/                  //   示例模块
    └── generator/                //   代码生成器

前端目录 (ui/src/)

ui/src/
├── main.ts                       // 入口文件（注册插件、挂载应用）
├── App.vue                       // 根组件
├── api/                          // API 接口定义（按业务分组）
│   ├── system/                   //   系统管理接口（user.ts / role.ts / menu.ts 等）
│   ├── content/                  //   内容管理接口
│   ├── data/                     //   数据管理接口
│   ├── monitor/                  //   监控管理接口
│   ├── tool/                     //   工具接口
│   ├── file/                     //   文件接口
│   ├── region/                   //   地区接口
│   ├── setting/                  //   设置接口
│   ├── dashboard/                //   仪表盘接口
│   └── common/                   //   公共接口
├── views/                        // 页面视图（按业务分组）
│   ├── login/                    //   登录页
│   ├── dashboard/                //   控制台
│   ├── system/                   //   系统管理页面（user / role / menu / dept / position / level）
│   ├── content/                  //   内容管理页面（article / category / link）
│   ├── data/                     //   数据管理页面（dict / config / notice / param / city）
│   ├── monitor/                  //   监控管理页面（job / job/log）
│   ├── file/                     //   文件管理页面（fileTemplate）
│   ├── tool/                     //   工具页面（generator / example）
│   ├── setting/                  //   设置页面（profile / configWeb）
│   ├── exception/                //   异常页面（404 / 500）
│   ├── about/                    //   关于页面
│   ├── iframe/                   //   内嵌页面
│   └── redirect/                 //   重定向页面
├── components/                   // 公共组件
│   ├── Table/                    //   BasicTable 表格组件
│   ├── Form/                     //   BasicForm 表单组件
│   ├── Modal/                    //   Modal 弹窗组件
│   ├── Page/                     //   PageWrapper 页面容器
│   ├── Upload/                   //   文件上传组件
│   ├── Editor/                   //   富文本编辑器
│   ├── Cropper/                  //   图片裁剪组件
│   ├── Qrcode/                   //   二维码组件
│   ├── Excel/                    //   Excel 导入导出组件
│   ├── ChinaArea/                //   省市区联动组件
│   ├── TableSelect/              //   表格选择器组件
│   ├── Select/                   //   下拉选择组件
│   ├── CountTo/                  //   数字动画组件
│   ├── Authority/                //   权限组件
│   ├── CheckToken/               //   Token 检查组件
│   ├── Application/              //   应用组件
│   ├── Websocket/                //   WebSocket 组件
│   ├── Lockscreen/               //   锁屏组件
│   ├── Password/                 //   密码强度组件
│   ├── Region/                   //   区域选择组件
│   ├── numberInput/              //   数字输入组件
│   ├── priceInput/               //   价格输入组件
│   ├── pagination/               //   分页组件
│   ├── Render/                   //   渲染组件
│   ├── icon/                     //   图标组件
│   └── importFile/               //   文件导入组件
├── hooks/                        // 组合式函数
│   ├── core/                     //   核心 hooks
│   ├── event/                    //   事件 hooks
│   ├── setting/                  //   配置 hooks
│   ├── web/                      //   Web hooks
│   ├── use-async.ts              //   异步请求状态管理
│   ├── useBattery.ts             //   电量监听
│   ├── useDomWidth.ts            //   DOM 宽度监听
│   ├── useOnline.ts              //   网络状态监听
│   └── useTime.ts                //   时间工具
├── store/                        // Pinia 状态管理
│   ├── index.ts                  //   Store 入口
│   ├── modules/                  //   Store 模块（user / perm / dict / tabs / app）
│   ├── plugins/                  //   Store 插件
│   └── types.ts                  //   类型定义
├── router/                       // 路由配置
│   ├── index.ts                  //   路由实例
│   ├── base.ts                   //   静态路由（登录 / 404）
│   ├── constant.ts               //   常量路由
│   ├── generator-routers.ts      //   动态路由生成（后端菜单 → Vue Router）
│   ├── router-guards.ts          //   路由守卫（登录校验 / 菜单加载）
│   ├── router-icons.ts           //   路由图标映射
│   ├── menus/                    //   菜单配置
│   └── types.ts                  //   类型定义
├── utils/                        // 工具函数
│   ├── http/                     //   HTTP 请求封装（Axios 拦截器）
│   ├── auth.ts                   //   Token 管理 / 消息提示 / 确认对话框
│   ├── dateUtil.ts               //   日期格式化
│   ├── downloadFile.ts           //   文件下载
│   ├── validate.ts               //   表单校验
│   ├── env.ts                    //   环境变量
│   ├── color.ts                  //   颜色工具
│   ├── wartermark.ts             //   水印
│   ├── useLockFn.ts              //   防重复提交
│   └── Storage.ts                //   本地存储
├── directives/                   // 自定义指令（v-perm 权限指令）
├── plugins/                      // 插件注册（ElementPlus / 自定义组件 / 指令）
├── styles/                       // 全局样式（Tailwind CSS / ElementPlus 主题覆盖）
├── enums/                        // 枚举定义
└── assets/                       // 静态资源
    ├── icons/                    //   图标
    └── images/                   //   图片

注意事项

• 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。
• 合理划分模块：根据项目的实际需求，合理划分功能模块，避免过度模块化。
• 文档记录：在项目文档中详细说明目录结构和各模块的功能，便于新成员快速上手。
• 版本控制：使用 Git 等版本控制工具，并在 .gitignore 文件中配置不需要跟踪的目录和文件。

总结

软件架构的目录结构是项目开发和维护的基础，直接影响到项目的可维护性、可扩展性和开发效率。采用分层的目录结构（后端 router → service → repository，前端 api → views → components），结合模块化管理，是一个有效的解决方案。每个业务模块包含 models.py（模型）、schema.py（表单校验）、repository.py（数据访问）、service.py（业务逻辑）、router.py（路由控制）五个文件，职责清晰，便于维护。