11产品系统

架构设计

后端采用 FastAPI 四层分层架构：API 层负责路由和参数校验，Service 层统一处理业务逻辑与权限校验，Repository 层封装数据库访问，Model 层定义 ORM
模型。每一层职责清晰、边界明确，模块间通过依赖注入解耦。前端采用 Vue 3 + Vite + Naive UI，Pinia 状态管理，Axios 封装请求拦截，Vue Router 实现路由守卫与权限控制。

数据库与缓存

使用 MySQL 作为主数据库，SQLModel + SQLAlchemy 双 ORM 方案——SQLModel 定义模型结构与 Pydantic 校验，SQLAlchemy 处理复杂查询和异步会话。Redis 多 DB
路由设计，不同业务（会话、组织架构、缓存）隔离到独立 DB，避免 key 冲突。组织架构树数据通过 Redis 缓存，定时任务使用 pipeline 原子切换保证数据一致性。

认证与安全

用户密码使用 Argon2 哈希加密存储，登录后签发 JWT Token，会话信息存入 Redis 并设置过期时间。每次请求通过中间件校验 Token 有效性，退出登录时主动清除 Redis 会话。邮箱验证码通过 aiosmtplib
异步发送，开发环境直接返回验证码方便调试。CORS 跨域配置通过环境变量控制，生产环境严格限制来源域名。

权限控制实现

RBAC 权限体系通过四张表实现——用户表、角色表、权限表、以及用户-角色和角色-权限两张关联表。权限校验统一封装为 check_permission 方法，在 Service 层调用，避免 API
层遗漏。前端通过路由守卫拦截无权限页面，按钮级别通过自定义指令控制显示隐藏。数据职级隔离通过组织架构过滤实现——查询时自动注入当前用户的组织条件，同级数据互不可见。

异步任务调度

集成 Celery + RedBeat 实现异步任务和定时调度。系统通知发送、每日日报生成、过期文件清理、组织架构树重建四个任务分别调度。通知发送通过 delay() 异步分发，API 立即返回，Worker
后台执行。导出文件由定时任务每日自动扫描 MinIO 并批量删除过期文件。所有任务执行结果通过企业微信实时推送通知管理员。

文件存储

MinIO 对象存储按业务分桶管理——图片桶和文档桶隔离。文件按 年/月/日 三级目录归档，文件名使用 UUID 避免冲突。大文件（≥50MB）自动启用分片上传，8MB 分片大小，4 并发上传，提升上传稳定性。

数据导出

基于 pandas + openpyxl 实现 Excel 导出功能。导出任务通过 FastAPI BackgroundTasks 在后台执行，生成文件后上传至 MinIO 并通过消息通知推送下载链接给用户，避免大数据量导出阻塞请求。

容器化部署

Docker Compose 编排三个服务：Web 服务（Gunicorn + Uvicorn Worker，2 进程）、Celery Worker（异步任务执行）、Celery Beat（定时任务调度）。每个服务设置内存限制，Web 512M、Worker 256M、Beat
128M。日志使用 json-file 驱动，限制单文件 10MB、最多 3 个文件。所有服务共享 bridge 网络，通过 Docker 内部 DNS 通信。

前端实现

Vue 3 组合式 API 开发，Vite 构建工具链。封装 Axios 请求拦截器统一处理 Token 注入和响应错误。Pinia 管理用户状态、应用配置、标签页视图。路由守卫实现未登录跳转和权限页拦截。提取公共组件如组
织架构筛选器、权限树选择器，多处复用。构建时自动注入版本时间戳，前端定时检测版本更新并提示用户刷新。

工程规范

Git 提交遵循 feat/refactor/fix 规范，每个模块配有完整的 Pydantic Schema 定义（请求模型、响应模型分离）。统一响应格式 {code, msg, data}，统一异常处理中间件。雪花算法生成分布式
ID，保证全局唯一。项目配有《开发文档》和《接口文档》双重文档，接口文档覆盖全部 14 个模块的请求参数、响应格式、分页规范。

架构设计

后端采用 FastAPI 四层分层架构：API 层负责路由和参数校验，Service 层统一处理业务逻辑与权限校验，Repository 层封装数据库访问，Model 层定义 ORM
模型。每一层职责清晰、边界明确，模块间通过依赖注入解耦。前端采用 Vue 3 + Vite + Naive UI，Pinia 状态管理，Axios 封装请求拦截，Vue Router 实现路由守卫与权限控制。

数据库与缓存

使用 MySQL 作为主数据库，SQLModel + SQLAlchemy 双 ORM 方案——SQLModel 定义模型结构与 Pydantic 校验，SQLAlchemy 处理复杂查询和异步会话。Redis 多 DB
路由设计，不同业务（会话、组织架构、缓存）隔离到独立 DB，避免 key 冲突。组织架构树数据通过 Redis 缓存，定时任务使用 pipeline 原子切换保证数据一致性。

认证与安全

用户密码使用 Argon2 哈希加密存储，登录后签发 JWT Token，会话信息存入 Redis 并设置过期时间。每次请求通过中间件校验 Token 有效性，退出登录时主动清除 Redis 会话。邮箱验证码通过 aiosmtplib
异步发送，开发环境直接返回验证码方便调试。CORS 跨域配置通过环境变量控制，生产环境严格限制来源域名。

权限控制实现

RBAC 权限体系通过四张表实现——用户表、角色表、权限表、以及用户-角色和角色-权限两张关联表。权限校验统一封装为 check_permission 方法，在 Service 层调用，避免 API
层遗漏。前端通过路由守卫拦截无权限页面，按钮级别通过自定义指令控制显示隐藏。数据职级隔离通过组织架构过滤实现——查询时自动注入当前用户的组织条件，同级数据互不可见。

异步任务调度

集成 Celery + RedBeat 实现异步任务和定时调度。系统通知发送、每日日报生成、过期文件清理、组织架构树重建四个任务分别调度。通知发送通过 delay() 异步分发，API 立即返回，Worker
后台执行。导出文件由定时任务每日自动扫描 MinIO 并批量删除过期文件。所有任务执行结果通过企业微信实时推送通知管理员。

文件存储

MinIO 对象存储按业务分桶管理——图片桶和文档桶隔离。文件按 年/月/日 三级目录归档，文件名使用 UUID 避免冲突。大文件（≥50MB）自动启用分片上传，8MB 分片大小，4 并发上传，提升上传稳定性。

数据导出

基于 pandas + openpyxl 实现 Excel 导出功能。导出任务通过 FastAPI BackgroundTasks 在后台执行，生成文件后上传至 MinIO 并通过消息通知推送下载链接给用户，避免大数据量导出阻塞请求。

容器化部署

Docker Compose 编排三个服务：Web 服务（Gunicorn + Uvicorn Worker，2 进程）、Celery Worker（异步任务执行）、Celery Beat（定时任务调度）。每个服务设置内存限制，Web 512M、Worker 256M、Beat
128M。日志使用 json-file 驱动，限制单文件 10MB、最多 3 个文件。所有服务共享 bridge 网络，通过 Docker 内部 DNS 通信。

前端实现

Vue 3 组合式 API 开发，Vite 构建工具链。封装 Axios 请求拦截器统一处理 Token 注入和响应错误。Pinia 管理用户状态、应用配置、标签页视图。路由守卫实现未登录跳转和权限页拦截。提取公共组件如组
织架构筛选器、权限树选择器，多处复用。构建时自动注入版本时间戳，前端定时检测版本更新并提示用户刷新。

工程规范

Git 提交遵循 feat/refactor/fix 规范，每个模块配有完整的 Pydantic Schema 定义（请求模型、响应模型分离）。统一响应格式 {code, msg, data}，统一异常处理中间件。雪花算法生成分布式
ID，保证全局唯一。项目配有《开发文档》和《接口文档》双重文档，接口文档覆盖全部 14 个模块的请求参数、响应格式、分页规范。

架构设计

后端采用 FastAPI 四层分层架构：API 层负责路由和参数校验，Service 层统一处理业务逻辑与权限校验，Repository 层封装数据库访问，Model 层定义 ORM
模型。每一层职责清晰、边界明确，模块间通过依赖注入解耦。前端采用 Vue 3 + Vite + Naive UI，Pinia 状态管理，Axios 封装请求拦截，Vue Router 实现路由守卫与权限控制。

数据库与缓存

使用 MySQL 作为主数据库，SQLModel + SQLAlchemy 双 ORM 方案——SQLModel 定义模型结构与 Pydantic 校验，SQLAlchemy 处理复杂查询和异步会话。Redis 多 DB
路由设计，不同业务（会话、组织架构、缓存）隔离到独立 DB，避免 key 冲突。组织架构树数据通过 Redis 缓存，定时任务使用 pipeline 原子切换保证数据一致性。

认证与安全

用户密码使用 Argon2 哈希加密存储，登录后签发 JWT Token，会话信息存入 Redis 并设置过期时间。每次请求通过中间件校验 Token 有效性，退出登录时主动清除 Redis 会话。邮箱验证码通过 aiosmtplib
异步发送，开发环境直接返回验证码方便调试。CORS 跨域配置通过环境变量控制，生产环境严格限制来源域名。

权限控制实现

RBAC 权限体系通过四张表实现——用户表、角色表、权限表、以及用户-角色和角色-权限两张关联表。权限校验统一封装为 check_permission 方法，在 Service 层调用，避免 API
层遗漏。前端通过路由守卫拦截无权限页面，按钮级别通过自定义指令控制显示隐藏。数据职级隔离通过组织架构过滤实现——查询时自动注入当前用户的组织条件，同级数据互不可见。

异步任务调度

集成 Celery + RedBeat 实现异步任务和定时调度。系统通知发送、每日日报生成、过期文件清理、组织架构树重建四个任务分别调度。通知发送通过 delay() 异步分发，API 立即返回，Worker
后台执行。导出文件由定时任务每日自动扫描 MinIO 并批量删除过期文件。所有任务执行结果通过企业微信实时推送通知管理员。

文件存储

MinIO 对象存储按业务分桶管理——图片桶和文档桶隔离。文件按 年/月/日 三级目录归档，文件名使用 UUID 避免冲突。大文件（≥50MB）自动启用分片上传，8MB 分片大小，4 并发上传，提升上传稳定性。

数据导出

基于 pandas + openpyxl 实现 Excel 导出功能。导出任务通过 FastAPI BackgroundTasks 在后台执行，生成文件后上传至 MinIO 并通过消息通知推送下载链接给用户，避免大数据量导出阻塞请求。

容器化部署

Docker Compose 编排三个服务：Web 服务（Gunicorn + Uvicorn Worker，2 进程）、Celery Worker（异步任务执行）、Celery Beat（定时任务调度）。每个服务设置内存限制，Web 512M、Worker 256M、Beat
128M。日志使用 json-file 驱动，限制单文件 10MB、最多 3 个文件。所有服务共享 bridge 网络，通过 Docker 内部 DNS 通信。

前端实现

Vue 3 组合式 API 开发，Vite 构建工具链。封装 Axios 请求拦截器统一处理 Token 注入和响应错误。Pinia 管理用户状态、应用配置、标签页视图。路由守卫实现未登录跳转和权限页拦截。提取公共组件如组
织架构筛选器、权限树选择器，多处复用。构建时自动注入版本时间戳，前端定时检测版本更新并提示用户刷新。

工程规范

Git 提交遵循 feat/refactor/fix 规范，每个模块配有完整的 Pydantic Schema 定义（请求模型、响应模型分离）。统一响应格式 {code, msg, data}，统一异常处理中间件。雪花算法生成分布式
ID，保证全局唯一。项目配有《开发文档》和《接口文档》双重文档，接口文档覆盖全部 14 个模块的请求参数、响应格式、分页规范。