20260823210241

2026-08-23 21:02:41 +08:00
1 parent 5ff4583aeb
commit f4c7413dc6
@@ -0,0 +1,340 @@
+# 项目概述
+
+<cite>
+**本文引用的文件**
+- [fms-vue/package.json](file://fms-vue/package.json)
+- [fms-api/pom.xml](file://fms-api/pom.xml)
+- [fms-vue/src/main.js](file://fms-vue/src/main.js)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java)
+- [fms-api/src/main/resources/application.yaml](file://fms-api/src/main/resources/application.yaml)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java)
+- [fms-vue/src/stores/permissions.js](file://fms-vue/src/stores/permissions.js)
+- [fms-vue/src/stores/auth.js](file://fms-vue/src/stores/auth.js)
+- [fms-api/config/migrations/100_initialize_fms_new.sql](file://fms-api/config/migrations/100_initialize_fms_new.sql)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+FMS财务管理系统采用前后端分离架构：前端基于 Vue 3 + Pinia + Vite，提供元数据驱动的动态表单与表格能力；后端基于 Spring Boot + SQL Server，提供统一 API、多租户数据隔离与 RBAC 权限控制。系统通过“模块-字段-权限”的元数据模型驱动页面渲染与数据访问，实现低代码化的业务快速构建与灵活扩展。
+
+- 目标与价值
+  - 以元数据驱动表单与表格，减少重复开发，提升交付效率
+  - 多租户数据隔离，支持企业级多组织部署
+  - 细粒度 RBAC 权限（菜单/模块/操作/字段），保障数据安全
+  - 前后端职责清晰，便于独立演进与团队协作
+
+- 技术栈选择原因
+  - 前端：Vue 3 生态成熟、组合式 API 利于逻辑复用；Pinia 轻量且易测试；Vite 构建快；stk-table 提供高性能表格能力
+  - 后端：Spring Boot 简化配置与集成；SQL Server 满足企业级数据库需求；Druid 连接池便于监控；JWT 无状态鉴权
+
+**章节来源**
+- [fms-vue/package.json:1-48](file://fms-vue/package.json#L1-L48)
+- [fms-api/pom.xml:1-108](file://fms-api/pom.xml#L1-L108)
+
+## 项目结构
+仓库为多模块工程，主要包含：
+- fms-vue：Vue 3 前端应用，负责路由、状态管理、UI 组件、元数据驱动的表单/表格展示与交互
+- fms-api：Spring Boot 后端服务，负责认证鉴权、多租户数据源路由、API 暴露、数据库迁移与工具类
+- 其他：演示与参考组件库、迁移脚本与工具等
+
+```mermaid
+graph TB
+subgraph "前端"
+A["Vue 3 应用<br/>main.js"]
+B["状态管理<br/>auth.js / permissions.js"]
+C["组件与页面<br/>ui/form, ui/grid, fms-table"]
+end
+subgraph "后端"
+D["Spring Boot 启动<br/>FmsApiApplication.java"]
+E["认证过滤<br/>JwtAuthFilter.java"]
+F["多租户数据源路由<br/>OrgRoutingDataSource.java"]
+G["配置与迁移<br/>application.yaml, migrations/*"]
+end
+A --> B
+B --> C
+A --> |HTTP 请求| E
+E --> D
+D --> F
+D --> G
+```
+
+**图表来源**
+- [fms-vue/src/main.js:1-78](file://fms-vue/src/main.js#L1-L78)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java:1-22](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L1-L22)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java:1-110](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java#L1-L110)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java:1-28](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L28)
+- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
+
+**章节来源**
+- [fms-vue/src/main.js:1-78](file://fms-vue/src/main.js#L1-L78)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java:1-22](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L1-L22)
+- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
+
+## 核心组件
+- 前端应用入口与初始化
+  - 创建应用、注册 Pinia 插件、挂载路由、主题同步与引导屏处理
+- 认证与会话
+  - 前端存储登录凭证与用户信息，支持跨会话持久化与标签页失效
+- 权限与菜单
+  - 根据用户与模块授权计算可访问页面与功能点，支持管理员提权
+- 后端启动与配置
+  - Spring Boot 应用启动、全局属性扫描、端口与上下文路径、JWT 密钥与过期时间、文件存储策略
+- 认证过滤器
+  - 解析 JWT、校验会话活性、设置租户上下文、拦截未授权请求
+- 多租户数据源路由
+  - 基于当前租户 ID 动态获取对应数据源连接，实现数据隔离
+- 元数据与动态表单/表格
+  - 后端读取表结构元数据，前端基于元数据渲染查询、列表与编辑界面
+
+**章节来源**
+- [fms-vue/src/main.js:1-78](file://fms-vue/src/main.js#L1-L78)
+- [fms-vue/src/stores/auth.js:1-49](file://fms-vue/src/stores/auth.js#L1-L49)
+- [fms-vue/src/stores/permissions.js:1-196](file://fms-vue/src/stores/permissions.js#L1-L196)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java:1-22](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L1-L22)
+- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java:1-110](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java#L1-L110)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java:1-28](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L28)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java:180-205](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java#L180-L205)
+
+## 架构总览
+系统采用前后端分离模式：
+- 前端负责 UI 渲染、用户交互、本地状态与权限判断
+- 后端负责接口、鉴权、多租户数据访问与元数据生成
+- 通过 JWT 进行无状态鉴权，结合会话登记实现单设备登录控制
+- 通过 OrgContext 与动态数据源路由实现多租户数据隔离
+- 通过元数据驱动表单与表格，降低定制成本
+
+```mermaid
+sequenceDiagram
+participant U as "用户浏览器"
+participant FE as "Vue 前端"
+participant BE as "Spring Boot 后端"
+participant DB as "SQL Server"
+U->>FE : 打开系统
+FE->>BE : 携带 Authorization : Bearer <token> 发起请求
+BE->>BE : JwtAuthFilter 解析并校验 JWT
+BE->>BE : 检查活跃会话与是否被顶替
+BE->>DB : 使用 OrgRoutingDataSource 按 orgId 路由到对应数据源
+DB-->>BE : 返回数据
+BE-->>FE : 返回 JSON 响应
+FE->>FE : 权限 store 计算菜单/按钮可见性
+FE-->>U : 渲染页面与数据
+```
+
+**图表来源**
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java:1-110](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java#L1-L110)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java:1-28](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L28)
+- [fms-vue/src/stores/permissions.js:1-196](file://fms-vue/src/stores/permissions.js#L1-L196)
+
+## 详细组件分析
+
+### 前端应用初始化与引导流程
+- 创建应用实例、注册 Pinia 与路由
+- 在挂载前完成主题同步，避免首屏闪烁
+- 等待路由就绪后挂载应用，并通过过渡动画移除引导屏
+
+```mermaid
+flowchart TD
+Start(["应用启动"]) --> Init["创建应用/注册插件"]
+Init --> Ready{"路由就绪?"}
+Ready -- 否 --> Wait["等待路由加载"]
+Wait --> Ready
+Ready -- 是 --> Mount["挂载应用到 #app"]
+Mount --> FadeOut["触发引导屏淡出"]
+FadeOut --> End(["完成"])
+```
+
+**图表来源**
+- [fms-vue/src/main.js:1-78](file://fms-vue/src/main.js#L1-L78)
+
+**章节来源**
+- [fms-vue/src/main.js:1-78](file://fms-vue/src/main.js#L1-L78)
+
+### 认证与会话管理
+- 前端将 token 与用户信息存入 sessionStorage/localStorage，退出时清理会话
+- 后端通过 JWT 过滤器校验令牌、检查会话活性，并在上下文中注入 orgId 与 userId
+- 支持单设备登录：当同一账号在其他设备登录时，旧会话将被拒绝
+
+```mermaid
+sequenceDiagram
+participant FE as "前端 auth store"
+participant BE as "JwtAuthFilter"
+participant SR as "ActiveSessionRegistry"
+FE->>BE : 请求携带 Authorization
+BE->>BE : 解析 JWT 获取 orgId/userId/sessionId
+BE->>SR : 校验会话是否活跃/是否被顶替
+SR-->>BE : 返回校验结果
+alt 有效
+BE-->>FE : 继续处理请求
+else 无效
+BE-->>FE : 返回未授权或会话被顶替
+end
+```
+
+**图表来源**
+- [fms-vue/src/stores/auth.js:1-49](file://fms-vue/src/stores/auth.js#L1-L49)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java:1-110](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java#L1-L110)
+
+**章节来源**
+- [fms-vue/src/stores/auth.js:1-49](file://fms-vue/src/stores/auth.js#L1-L49)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java:1-110](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java#L1-L110)
+
+### 权限与菜单控制（RBAC）
+- 前端权限 store 拉取模块、用户模块授权与功能点授权，计算可访问页面与功能点
+- 管理员账号具备提权能力，直接可见全部启用模块
+- 支持按模块编码向上查找所属 page 类型模块，用于权限判定
+
+```mermaid
+flowchart TD
+Load["加载权限数据"] --> Admin{"是否管理员?"}
+Admin -- 是 --> AllModules["加载全部启用模块"]
+Admin -- 否 --> Fetch["并发拉取模块/授权/功能点"]
+Fetch --> Build["构建模块映射/页面ID集合/功能点集合"]
+AllModules --> Build
+Build --> CheckAccess{"canAccess(moduleCode)"}
+CheckAccess --> Can["允许访问"]
+CheckAccess --> Deny["拒绝访问"]
+```
+
+**图表来源**
+- [fms-vue/src/stores/permissions.js:1-196](file://fms-vue/src/stores/permissions.js#L1-L196)
+
+**章节来源**
+- [fms-vue/src/stores/permissions.js:1-196](file://fms-vue/src/stores/permissions.js#L1-L196)
+
+### 多租户数据隔离
+- 后端通过 OrgRoutingDataSource 根据当前线程中的 orgId 动态选择数据源
+- 认证过滤器在鉴权后将 orgId 写入上下文，供后续数据访问使用
+- 数据库层通过迁移脚本维护权限、范围等基础表，支撑多租户与权限体系
+
+```mermaid
+sequenceDiagram
+participant Req as "请求"
+participant Filter as "JwtAuthFilter"
+participant DS as "OrgRoutingDataSource"
+participant DB as "SQL Server"
+Req->>Filter : 进入过滤器链
+Filter->>Filter : 从 JWT 提取 orgId/userId
+Filter->>DS : 设置上下文 orgId
+DS->>DB : 按 orgId 路由到对应数据源执行
+DB-->>DS : 返回结果
+DS-->>Req : 返回数据
+```
+
+**图表来源**
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java:1-110](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java#L1-L110)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java:1-28](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L28)
+
+**章节来源**
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java:1-110](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java#L1-L110)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java:1-28](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L28)
+- [fms-api/config/migrations/100_initialize_fms_new.sql:342-412](file://fms-api/config/migrations/100_initialize_fms_new.sql#L342-L412)
+
+### 元数据驱动的动态表单与表格
+- 后端通过 DbUtils 读取表结构元数据（列名、类型、是否自增/只读/时间戳等），用于生成表单与表格配置
+- 前端基于元数据渲染查询条件、列表字段与编辑控件，减少硬编码
+- 迁移脚本中定义了模块、权限、国际化等基础表，支撑元数据驱动的业务建模
+
+```mermaid
+flowchart TD
+Meta["读取表结构元数据"] --> Fields["解析列信息与约束"]
+Fields --> Config["生成表单/表格配置"]
+Config --> Render["前端渲染查询/列表/编辑"]
+Render --> Save["提交变更到后端"]
+Save --> DB["持久化到 SQL Server"]
+```
+
+**图表来源**
+- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java:180-205](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java#L180-L205)
+
+**章节来源**
+- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java:180-205](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java#L180-L205)
+
+## 依赖关系分析
+- 前端依赖
+  - Vue 3、Vue Router、Pinia、Axios、Dayjs、NProgress、stk-table-vue 等
+- 后端依赖
+  - Spring Boot Web/MVC、JDBC、Druid、JWT、Jackson、SQL Server JDBC、UA Parser、IP2Region 等
+- 运行时配置
+  - 应用端口、上下文路径、JWT 密钥与过期时间、数据库连接池参数、文件存储策略
+
+```mermaid
+graph LR
+FE["Vue 前端"] --> |HTTP| BE["Spring Boot 后端"]
+BE --> |JDBC| DB["SQL Server"]
+BE --> |配置| CFG["application.yaml"]
+```
+
+**图表来源**
+- [fms-vue/package.json:1-48](file://fms-vue/package.json#L1-L48)
+- [fms-api/pom.xml:1-108](file://fms-api/pom.xml#L1-L108)
+- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
+
+**章节来源**
+- [fms-vue/package.json:1-48](file://fms-vue/package.json#L1-L48)
+- [fms-api/pom.xml:1-108](file://fms-api/pom.xml#L1-L108)
+- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
+
+## 性能考虑
+- 前端
+  - 使用 stk-table 的高性能表格能力，配合区域选择等特性优化大数据量场景
+  - 首屏通过路由就绪后再挂载应用，减少白屏时间
+  - 权限数据并发加载与去重，避免重复请求
+- 后端
+  - 合理配置 Druid 连接池参数，平衡资源占用与吞吐
+  - 使用 JWT 无状态鉴权，减轻服务端会话存储压力
+  - 多租户数据源按需建立连接，避免空闲资源浪费
+
+[本节为通用指导，不直接分析具体文件]
+
+## 故障排查指南
+- 认证失败
+  - 检查 Authorization 头是否包含正确的 Bearer Token
+  - 确认后端会话登记是否生效，是否存在被顶替情况
+- 权限异常
+  - 核对用户模块授权与功能点授权是否正确
+  - 管理员提权逻辑仅对特定账号生效
+- 多租户数据问题
+  - 确认 JWT 中 orgId 正确，OrgContext 已设置
+  - 验证数据源路由是否指向正确的租户数据库
+- 元数据不一致
+  - 检查表结构与元数据生成逻辑，确保列名与类型一致
+  - 必要时重新运行迁移脚本或刷新元数据缓存
+
+**章节来源**
+- [fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java:1-110](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/JwtAuthFilter.java#L1-L110)
+- [fms-vue/src/stores/permissions.js:1-196](file://fms-vue/src/stores/permissions.js#L1-L196)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java:1-28](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L28)
+- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java:180-205](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/DbUtils.java#L180-L205)
+
+## 结论
+FMS 财务管理系统通过前后端分离、元数据驱动与多租户隔离，实现了高内聚、低耦合的可扩展架构。前端聚焦用户体验与交互，后端专注安全、数据与业务能力。借助 RBAC 与动态表单/表格，系统能够快速适配不同业务场景，降低定制成本，提升交付效率与维护质量。
+
+[本节为总结性内容，不直接分析具体文件]
+
+## 附录
+- 主要业务场景
+  - 财务管理：凭证、账簿、报表等业务的快速建模与可视化
+  - 合同与文件：合同相关数据与附件的统一管理
+  - 办公协同：OA 流程与消息通知
+  - 基础数据：企业、联系人、分类等基础信息管理
+- 使用价值
+  - 通过元数据驱动，缩短需求到上线周期
+  - 多租户隔离，支持集团化部署与数据边界管控
+  - 细粒度权限，满足合规与安全要求
+  - 前后端解耦，便于团队并行开发与持续迭代
+
+[本节为概念性说明，不直接分析具体文件]