外观
项目结构
整体架构
系统采用「前后端分离 + 后端分层模块化」的架构。
后端分层设计
| 层 | 目录 | 职责 | 依赖方向 |
|---|---|---|---|
| 基础配置层 | backend/app/config | 全局配置、常量、路径、Banner | 被框架层与业务层使用 |
| 框架封装层 | backend/app/framework | 封装 FastAPI / SQLAlchemy / Redis / 文件 / 短信 / 任务队列 / WebSocket | 可调用配置层，不依赖业务层 |
| 业务逻辑层 | backend/app/api | 组合调用、编排具体业务逻辑 | 依赖配置层 + 框架层 |
依赖方向：业务层 → 框架层 → 配置层，禁止反向依赖。
后端业务模块分层
每个业务模块（如 module_system/user/）遵循统一的五文件分层：
| 文件 | 职责 |
|---|---|
controller.py | 路由定义与请求处理（薄层），用 XxxRouter 命名 |
service.py | 业务逻辑，用 XxxService 命名 |
crud.py | 数据库操作，继承 CRUDBase，用 XxxCRUD 命名 |
schema.py | 数据校验与序列化（Pydantic），用 Xxx*Schema 命名 |
model.py | 数据库模型，继承 ModelMixin + UserMixin，用 XxxModel 命名 |
目录结构
后端 backend/
text
backend/
├── main.py # 应用入口：create_app、CLI（start/revision/upgrade）
├── alembic/ # 数据库迁移脚本（alembic）
├── app/
│ ├── app_init.py # 应用初始化：生命周期、中间件、异常、静态、API 文档
│ ├── config/ # 基础配置层
│ │ ├── settings.py # 配置加载（按环境读取，含缓存）
│ │ ├── constants.py # 全局常量、枚举（如环境枚举）
│ │ ├── paths.py # 路径常量
│ │ └── banner.txt # 启动横幅
│ ├── framework/ # 框架封装层（与业务解耦）
│ │ ├── web/ # 统一响应、异常、中间件、请求封装、分页、状态码
│ │ ├── database/ # 数据库引擎、CRUDBase、Model/Schema 基类
│ │ ├── security/ # JWT、OAuth2、鉴权、权限、限流、加解密、脱敏
│ │ ├── common/ # Redis、日志、缓存等通用能力
│ │ ├── file/ # 文件存储封装
│ │ ├── sms/ # 短信能力
│ │ ├── task_queue/ # 任务队列
│ │ ├── websocket/ # WebSocket 封装
│ │ ├── validation/ # 校验与规整
│ │ └── util/ # 通用工具（控制台、导入等）
│ └── api/ # 业务逻辑层
│ └── v1/
│ ├── module_system/ # 系统管理
│ ├── module_infra/ # 基础设施
│ ├── module_ai/ # AI 大模型
│ └── module_bpm/ # 工作流
├── static/ # 静态资源目录
├── sql/ # 初始化 SQL
├── tests/ # 后端测试（含 BPM 用例、单元测试用例）
└── pyproject.toml # 依赖与工具配置（ruff 等）每个业务模块内部遵循统一的五层文件结构（以 module_infra/file_config 为例）：
text
module_infra/file_config/
├── __init__.py # 保持为空
├── model.py # 数据库模型（XxxModel，继承 ModelMixin/UserMixin）
├── schema.py # 数据校验与序列化（Base/Create/Update/Out + QueryParam）
├── crud.py # 数据访问（XxxCRUD，继承 CRUDBase）
├── service.py # 业务逻辑（XxxService）
├── controller.py # 路由定义（XxxRouter，薄层）
└── task.py # 可选的定时/异步任务前端 frontend/
text
frontend/
├── apps/
│ └── web-ele/ # 主业务应用（Vue 3 + Vite）
│ ├── src/
│ │ ├── api/ # 接口请求与适配层（按子系统分子目录）
│ │ │ ├── core/ request.ts # 请求出口与归一化
│ │ │ ├── system/ ai/ bpm/ infra/ # 各子系统接口
│ │ ├── views/ # 页面（system/ai/bpm/infra/dashboard）
│ │ ├── router/ # 路由与守卫（routes/modules 按模块拆分）
│ │ ├── layouts/ # 布局
│ │ ├── store/ # 状态管理
│ │ ├── components/ # 业务/通用组件
│ │ ├── adapter/ # 适配层
│ │ ├── locales/ # 国际化
│ │ ├── utils/ types/ assets/ plugins/
│ │ ├── app.vue main.ts bootstrap.ts preferences.ts
│ └── vite.config.ts
├── packages/ # 公共能力包
│ ├── @core/ # 框架核心：base / composables / preferences / ui-kit
│ ├── stores/ # 全局状态（access/user/auth…）
│ ├── utils/ constants/ effects/ icons/ locales/ styles/ types/
├── internal/ # 工程内部工具（不发布）
│ ├── lint-configs/ node-utils/ tailwind-config/ tsconfig/ vite-config/
├── scripts/ # 构建/代码生成脚本
├── turbo.json pnpm-workspace.yaml
└── oxlint.config.ts eslint.config.mjs stylelint.config.mjs前后端目录的对应关系（便于定位改动落点）：
| 后端子系统 | 后端目录 | 前端页面 | 前端接口 |
|---|---|---|---|
| 系统管理 | module_system | views/system | api/system |
| 基础设施 | module_infra | views/infra | api/infra |
| AI 大模型 | module_ai | views/ai | api/ai |
| BPM工作流 | module_bpm | views/bpm | api/bpm |
运维部署 devops/
text
devops/
├── docker/
│ ├── backend/ # 后端镜像构建（Dockerfile）
│ ├── mysql/ # MySQL 初始化脚本
│ ├── nginx/ # 反向代理：nginx.conf / ssl / web
│ ├── milvus/ # Milvus 官方脚本
│ └── docker-compose.prod.yaml # 生产环境容器编排
└── deploy.sh # 一键部署脚本端到端测试 tests/
text
tests/agent-browser/ # 端到端自动化测试：基于agent-browser
├── README.md # 本模块说明：环境准备、执行约定、命令对照表
├── cases/ # 测试用例（按模块组织，可复用）
│ └── system-post.md # 系统管理-岗位管理用例
├── results/ # 测试结果（按 日期-模块 归档）
│ └── 2026-09-20-system-post/
│ ├── report.md # 测试报告
│ └── assets/ # 过程截图（report.md 相对路径引用）
└── tmp/ # 临时产物（导出文件等），不入库