# 项目概述

<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 流程与消息通知
  - 基础数据：企业、联系人、分类等基础信息管理
- 使用价值
  - 通过元数据驱动，缩短需求到上线周期
  - 多租户隔离，支持集团化部署与数据边界管控
  - 细粒度权限，满足合规与安全要求
  - 前后端解耦，便于团队并行开发与持续迭代

[本节为概念性说明，不直接分析具体文件]