# 快速开始

<cite>
**本文引用的文件**
- [fms-api/pom.xml](file://fms-api/pom.xml)
- [fms-api/src/main/resources/application.yaml](file://fms-api/src/main/resources/application.yaml)
- [fms-api/config/dbconfigs/README.md](file://fms-api/config/dbconfigs/README.md)
- [fms-api/config/dbconfigs/G3HD.properties](file://fms-api/config/dbconfigs/G3HD.properties)
- [fms-api/start.cmd](file://fms-api/start.cmd)
- [fms-vue/package.json](file://fms-vue/package.json)
- [fms-vue/vite.config.js](file://fms-vue/vite.config.js)
- [fms-vue/src/views/login/index.vue](file://fms-vue/src/views/login/index.vue)
- [fms-api/config/migrations/100_initialize_fms_new.sql](file://fms-api/config/migrations/100_initialize_fms_new.sql)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本快速开始指南帮助你在本地环境搭建并运行 FMS 财务管理系统，包括：
- 环境要求（Node.js、Java、数据库）
- 后端服务启动与配置说明
- 前端开发环境启动与代理配置
- 首次登录与基础操作示例
- 常见问题与排错建议

## 项目结构
FMS 采用前后端分离架构：
- 后端：Spring Boot 应用（fms-api），提供 REST API、认证鉴权、数据访问与文件存储能力
- 前端：Vue 3 + Vite（fms-vue），提供管理界面与交互逻辑
- 数据库：SQL Server（通过 JDBC 连接），支持按机构分库配置
- 文件存储：默认本地文件系统，可切换至对象存储

```mermaid
graph TB
subgraph "前端"
FE["fms-vue<br/>Vite 开发服务器"]
end
subgraph "后端"
BE["fms-api<br/>Spring Boot 应用"]
DB[("SQL Server<br/>数据库")]
FS["本地文件存储<br/>./data/files"]
end
FE --> |HTTP /api/*| BE
BE --> |JDBC| DB
BE --> |读写| FS
```

**图表来源**
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)
- [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）
  - 基于 Spring Boot，端口 8088，上下文路径 /api
  - 使用 Druid 连接池与 SQL Server JDBC 驱动
  - 支持 JWT 认证与过期时间配置
  - 文件存储默认本地目录 ./data/files，可通过配置切换
- 前端应用（fms-vue）
  - 基于 Vue 3 + Vite，开发端口 5082
  - 开发时通过代理将 /api 请求转发到后端 http://127.0.0.1:8088
  - 登录页面收集机构码、账号、密码，调用后端登录接口
- 数据库与迁移
  - 每个机构一个 properties 配置文件，存放数据库连接信息
  - 提供初始化脚本，创建基础表结构与初始数据

**章节来源**
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
- [fms-api/config/migrations/100_initialize_fms_new.sql:1-200](file://fms-api/config/migrations/100_initialize_fms_new.sql#L1-L200)

## 架构总览
下图展示了从浏览器到后端再到数据库的完整请求链路，以及文件存储的位置。

```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant FE as "fms-vue(Vite)"
participant BE as "fms-api(Spring Boot)"
participant DB as "SQL Server"
participant FS as "本地文件存储"
U->>FE : 打开登录页
FE->>BE : POST /api/auth/login (携带 orgId/account/password)
BE->>DB : 校验用户凭据
DB-->>BE : 返回用户信息
BE-->>FE : 返回 token 与用户信息
FE->>FE : 保存会话(持久化)
U->>FE : 进入首页/功能模块
FE->>BE : GET/POST 业务接口
BE->>DB : 读取/写入业务数据
BE->>FS : 上传/下载文件
FS-->>BE : 文件结果
BE-->>FE : 响应数据
```

**图表来源**
- [fms-vue/src/views/login/index.vue:48-68](file://fms-vue/src/views/login/index.vue#L48-L68)
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

## 详细组件分析

### 后端服务（fms-api）
- 启动方式
  - 使用 Maven 插件直接运行，或执行 start.cmd（需配置 JAVA_HOME 与 MAVEN_HOME）
- 关键配置
  - 服务端口与上下文路径
  - JWT 密钥与过期时间
  - 数据库连接池参数
  - 文件存储类型与本地目录
- 数据库连接
  - 在 config/dbconfigs 目录下为每个机构创建 {ORG_ID}.properties 文件
  - 包含 url、username、password、driver 等必要项
- 初始化
  - 执行初始化迁移脚本以创建基础表结构与数据

```mermaid
flowchart TD
Start(["启动 fms-api"]) --> LoadCfg["加载 application.yaml"]
LoadCfg --> ReadDBCfg["读取 dbconfigs/*.properties"]
ReadDBCfg --> InitPool["初始化 Druid 连接池"]
InitPool --> Ready{"服务就绪?"}
Ready --> |是| Serve["处理 HTTP 请求"]
Ready --> |否| Error["输出错误日志并退出"]
```

**图表来源**
- [fms-api/src/main/resources/application.yaml:10-34](file://fms-api/src/main/resources/application.yaml#L10-L34)
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)

**章节来源**
- [fms-api/start.cmd:1-8](file://fms-api/start.cmd#L1-L8)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
- [fms-api/config/migrations/100_initialize_fms_new.sql:1-200](file://fms-api/config/migrations/100_initialize_fms_new.sql#L1-L200)

### 前端开发环境（fms-vue）
- 安装依赖与启动
  - 安装依赖：npm install（或 pnpm install）
  - 启动开发服务器：npm run dev
- 代理配置
  - 开发服务器监听 5082 端口
  - 将 /api 请求代理到 http://127.0.0.1:8088
- 登录流程
  - 输入机构码、账号、密码后调用后端登录接口
  - 成功后保存会话并跳转到首页

```mermaid
sequenceDiagram
participant Dev as "开发者终端"
participant FE as "fms-vue(Vite)"
participant BE as "fms-api"
Dev->>FE : npm install
Dev->>FE : npm run dev
Note over FE : 启动于 5082，代理 /api -> 8088
FE->>BE : 登录请求
BE-->>FE : 返回 token 与用户信息
FE->>FE : 保存会话并跳转
```

**图表来源**
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)
- [fms-vue/src/views/login/index.vue:48-68](file://fms-vue/src/views/login/index.vue#L48-L68)

**章节来源**
- [fms-vue/package.json:1-48](file://fms-vue/package.json#L1-L48)
- [fms-vue/vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
- [fms-vue/src/views/login/index.vue:1-253](file://fms-vue/src/views/login/index.vue#L1-L253)

## 依赖分析
- 后端依赖
  - Spring Boot WebMVC、JDBC、Druid、JWT、SQL Server JDBC 驱动
- 前端依赖
  - Vue 3、Vue Router、Pinia、Axios、Vite、测试与代码质量工具

```mermaid
graph LR
A["fms-vue"] --> B["axios"]
A --> C["vue-router"]
A --> D["pinia"]
E["fms-api"] --> F["spring-boot-starter-webmvc"]
E --> G["spring-boot-starter-jdbc"]
E --> H["druid"]
E --> I["jjwt-*"]
E --> J["mssql-jdbc"]
```

**图表来源**
- [fms-vue/package.json:21-46](file://fms-vue/package.json#L21-L46)
- [fms-api/pom.xml:32-96](file://fms-api/pom.xml#L32-L96)

**章节来源**
- [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)

## 性能考虑
- 数据库连接池
  - 合理设置初始大小、最小空闲、最大活跃数与等待超时
  - 启用空闲检测与借还连接时的验证查询
- 文件存储
  - 本地存储适合开发与单机部署；生产环境可切换至对象存储以提升扩展性
- 前端代理
  - 开发阶段通过 Vite 代理减少跨域问题；生产环境建议使用反向代理统一入口

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 无法连接数据库
  - 检查 dbconfigs/{ORG_ID}.properties 中的 url、用户名、密码与驱动是否正确
  - 确认 SQL Server 服务可达且端口开放
  - 若连接旧版仅支持 TLS 1.0 的 SQL Server，参考 README 中提供的 JVM 参数方式启动
- 后端启动失败
  - 确认 JAVA_HOME 与 MAVEN_HOME 已正确设置
  - 检查 application.yaml 中的端口是否被占用
  - 查看控制台日志定位异常堆栈
- 前端无法访问后端接口
  - 确认后端已在 8088 端口启动
  - 确认 Vite 代理目标地址为 http://127.0.0.1:8088
  - 检查浏览器网络面板中 /api 请求是否被正确转发
- 登录失败
  - 核对机构码、账号、密码是否正确
  - 查看后端日志确认认证流程是否成功
  - 若提示会话相关错误，检查 JWT 密钥配置是否一致

**章节来源**
- [fms-api/config/dbconfigs/README.md:18-28](file://fms-api/config/dbconfigs/README.md#L18-L28)
- [fms-api/start.cmd:1-8](file://fms-api/start.cmd#L1-L8)
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)
- [fms-vue/src/views/login/index.vue:48-68](file://fms-vue/src/views/login/index.vue#L48-L68)

## 结论
按照本指南完成环境准备、后端与前端启动、数据库初始化后，即可通过浏览器访问前端进行登录与基础操作。建议在开发过程中关注日志与网络请求，以便快速定位问题。生产部署时请根据实际环境调整数据库连接、文件存储与安全策略。

[本节为总结性内容，不直接分析具体文件]

## 附录

### 环境要求
- Node.js：用于运行 fms-vue 前端开发环境
- Java：21（由后端项目属性指定）
- 数据库：SQL Server（通过 mssql-jdbc 驱动连接）

**章节来源**
- [fms-api/pom.xml:29-31](file://fms-api/pom.xml#L29-L31)
- [fms-api/pom.xml:87-90](file://fms-api/pom.xml#L87-L90)

### 环境搭建步骤
- 后端
  - 准备 SQL Server 实例并创建数据库
  - 在 fms-api/config/dbconfigs 下为当前机构创建 {ORG_ID}.properties，填写连接信息
  - 执行初始化迁移脚本以创建基础表结构与数据
  - 启动后端服务（使用 Maven 或 start.cmd）
- 前端
  - 进入 fms-vue 目录，安装依赖并启动开发服务器
  - 打开浏览器访问开发端口，进入登录页

**章节来源**
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
- [fms-api/config/migrations/100_initialize_fms_new.sql:1-200](file://fms-api/config/migrations/100_initialize_fms_new.sql#L1-L200)
- [fms-api/start.cmd:1-8](file://fms-api/start.cmd#L1-L8)
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)

### 配置文件要点
- 后端 application.yaml
  - 服务端口与上下文路径
  - JWT 密钥与过期时间
  - 数据库连接池参数
  - 文件存储类型与本地目录
- 数据库连接
  - 每个机构一个 properties 文件，包含 url、用户名、密码、驱动
- 前端 vite.config.js
  - 开发端口与代理目标地址

**章节来源**
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-api/config/dbconfigs/G3HD.properties:1-5](file://fms-api/config/dbconfigs/G3HD.properties#L1-L5)
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)

### 首次登录与基础操作示例
- 打开前端登录页，输入机构码、账号、密码
- 提交后若成功，系统将保存会话并跳转到首页
- 可在首页或系统菜单中进行基础业务操作（如查看模块列表、数据录入等）

**章节来源**
- [fms-vue/src/views/login/index.vue:48-68](file://fms-vue/src/views/login/index.vue#L48-L68)