目录说明

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

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

项目根目录

├── src/                          // 后端源码
├── ui/                           // 前端源码（Vue3 + ElementPlus）
├── document/                     // 项目文档（SQL脚本、迁移日志等）
├── migrations/                   // Alembic 数据库迁移脚本
├── scripts/                      // 脚本工具（init_db、migrate_db、seed 等）
├── tests/                        // 测试代码（contract / unit / integration）
├── deploy/                       // 部署配置（nginx.conf、supervisor.conf）
├── wiki/                         // VitePress 文档站点
├── static/                       // 静态资源（验证码字体等）
├── .env.example                  // 环境变量模板
├── .env                          // 环境变量（不提交到版本控制）
├── docker-compose.yml            // Docker 编排配置
├── Dockerfile                    // 后端镜像构建文件
├── Makefile                      // 快捷命令（db-init、migrate-*、db-migrate）
├── requirements.txt              // Python 依赖清单
├── alembic.ini                   // Alembic 配置
└── README.md                     // 项目说明

后端目录 (src/)

src/
├── main.py                       // 应用入口（uvicorn 启动）
├── core/                         // 核心基础设施（与业务无关）
│   ├── app.py                    //   create_app 工厂函数 + lifespan
│   ├── config/                   //   配置模块
│   │   ├── __init__.py           //     加载 .env，统一导出
│   │   ├── app.py                //     应用配置（名称/版本/端口/调试模式）
│   │   ├── database.py           //     数据库配置（驱动/连接池/方言注册）
│   │   ├── redis.py              //     Redis 配置
│   │   ├── auth.py               //     JWT 配密钥/过期时间
│   │   ├── captcha.py            //     验证码配置
│   │   ├── email.py              //     邮件配置
│   │   └── sms.py                //     短信配置
│   ├── database.py               //   引擎 / SessionLocal / contextvars / get_db_session()
│   ├── redis_client.py           //   Redis 异步客户端 / get_redis()
│   ├── jwt.py                    //   JWT 签发 / 解析 / 刷新 / 黑名单
│   ├── password.py               //   bcrypt 密码加密 / 校验
│   ├── response.py               //   R.ok() / R.failed() 统一响应
│   ├── exceptions.py             //   BusinessException / AuthorizationException
│   ├── security.py               //   get_user_id() / get_username()
│   ├── access_decorators.py      //   @permission_required / @check_demo
│   ├── logger.py                 //   结构化日志配置
│   ├── base_model.py             //   ORM 基类（id / create_time / is_delete 等公共字段）
│   ├── base_db.py                //   save() / delete() 方法
│   ├── base_repository.py        //   通用 Repository 基类（CRUD / 分页 / 软删过滤）
│   ├── base_service.py           //   通用 Service 基类（声明差异 + 覆盖钩子）
│   └── base_schemas.py           //   通用 Schema 基类（BaseForm 含 id 字段）
├── api/                          // 路由层
│   ├── __init__.py               //   register_router：统一挂载路由到 /api/v1
│   ├── deps.py                   //   login_required 认证依赖
│   └── v1/
│       ├── router.py             //   路由注册中心（include_router + prefix + tags）
│       └── endpoints/            //   各模块 Endpoint（HTTP 层）
│           ├── user.py           //     用户管理
│           ├── role.py           //     角色管理
│           ├── menu.py           //     菜单管理
│           ├── position.py       //     岗位管理
│           ├── level.py          //     职级管理
│           ├── dept.py           //     部门管理
│           ├── article.py        //     文章管理
│           ├── notice.py         //     公告管理
│           ├── job.py            //     定时任务
│           ├── upload.py         //     文件上传
│           └── ...               //     其他模块
├── modules/                      // 业务模块（可插拔）
│   ├── auth/                     //   认证模块（登录/登出/验证码/刷新Token）
│   ├── system/                   //   系统管理
│   │   ├── user/                 //     用户（models / schemas / repository / service）
│   │   ├── role/                 //     角色
│   │   ├── menu/                 //     菜单
│   │   ├── dept/                 //     部门
│   │   ├── position/             //     岗位
│   │   ├── level/                //     职级
│   │   ├── user_role/            //     用户-角色关联
│   │   └── role_menu/            //     角色-菜单关联
│   ├── dictionary/               //   数据字典（dict / dict_item）
│   ├── configuration/            //   系统配置（config / config_item）
│   ├── article/                  //   文章管理
│   ├── category/                 //   分类管理
│   ├── notice/                   //   公告管理
│   ├── link/                     //   友情链接
│   ├── city/                     //   城市级联
│   ├── job/                      //   定时任务（job / job_log / job_executor）
│   ├── param/                    //   参数管理
│   ├── upload/                   //   文件上传
│   ├── login_log/                //   登录日志
│   ├── operation_log/            //   操作日志
│   └── generator/                //   代码生成器（含 templates/ui、templates/ui2 模板）
├── middleware/                   // 中间件
│   ├── cors.py                   //   CORS 跨域处理
│   ├── rate_limit.py             //   Redis 滑动窗口限流
│   ├── db_session.py             //   请求级 DB Session（自动 commit/rollback）
│   ├── operation_log.py          //   操作日志自动记录
│   ├── upload_size_limit.py      //   上传文件大小限制
│   └── logger.py                 //   请求日志钩子
├── utils/                        // 工具函数
│   ├── request.py                //   parse_batch_ids / like_escape / parse_id_list
│   ├── captcha.py                //   验证码生成（Pillow）
│   ├── file.py                   //   文件工具
│   ├── ip2region.py              //   IP 地理位置解析
│   ├── ip2region.xdb             //   离线 IP 数据库
│   ├── ua.py                     //   User-Agent 解析
│   ├── rich_text.py              //   富文本 XSS 过滤
│   ├── dict_util.py              //   数据字典进程内缓存
│   ├── perm_cache.py             //   权限列表 Redis 缓存
│   ├── string.py                 //   字符串工具
│   └── response_body.py          //   响应体工具
└── constants/                    // 常量与枚举
    ├── constants.py              //   PAGE_SIZE / DEFAULT_PASSWORD / SERIALIZE_EXCLUDE_FIELDS
    ├── enums.py                  //   枚举定义
    └── pagination.py             //   分页参数

前端目录 (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/                    //   关于页面
├── components/                   // 公共组件
│   ├── Table/                    //   BasicTable 表格组件
│   ├── Form/                     //   BasicForm 表单组件
│   ├── Modal/                    //   Modal 弹窗组件
│   ├── Page/                     //   PageWrapper 页面容器
│   ├── Upload/                   //   文件上传组件
│   ├── Editor/                   //   富文本编辑器
│   ├── Cropper/                  //   图片裁剪组件
│   ├── Qrcode/                   //   二维码组件
│   ├── Excel/                    //   Excel 导入导出组件
│   ├── ChinaArea/                //   省市区联动组件
│   ├── TableSelect/              //   表格选择器组件
│   ├── Select/                   //   下拉选择组件
│   ├── CountTo/                  //   数字动画组件
│   ├── Authority/                //   权限组件
│   ├── 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 文件中配置不需要跟踪的目录和文件。

总结

软件架构的目录结构是项目开发和维护的基础，直接影响到项目的可维护性、可扩展性和开发效率。采用分层的目录结构（后端 endpoint → service → repository，前端 api → views → components），结合模块化管理，是一个有效的解决方案。通过合理规划和遵循最佳实践，可以确保项目的结构清晰、功能明确，为团队开发和长期维护打下坚实的基础。