# 开发规范

<cite>
**本文引用的文件**
- [fms-vue/.oxlintrc.json](file://fms-vue/.oxlintrc.json)
- [fms-vue/.oxfmtrc.json](file://fms-vue/.oxfmtrc.json)
- [fms-vue/package.json](file://fms-vue/package.json)
- [fms-vue/src/main.js](file://fms-vue/src/main.js)
- [fms-vue/src/App.vue](file://fms-vue/src/App.vue)
- [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/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/DataController.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/FileController.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java)
</cite>

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

## 简介
本规范面向FMS项目的开发与维护，统一前后端代码风格、模块组织与质量保障流程。内容覆盖：
- JavaScript/Vue 代码风格与命名约定、文件组织、注释标准
- Vue 组件开发最佳实践（结构设计、Props、事件、样式）
- 后端 Java 分层规范（Controller/Service/Repository）、异常处理、日志记录
- 代码质量工具配置与使用（Oxlint、OxFmt）
- 模块划分原则与目录结构规范

## 项目结构
仓库采用多模块组织：
- fms-vue：前端工程，基于 Vue 3 + Vite + Pinia，使用 Oxlint/OxFmt 进行代码检查与格式化
- fms-api：后端工程，基于 Spring Boot 4.x，提供认证、数据、文件等 API
- 其他辅助目录用于演示、测试与迁移脚本

```mermaid
graph TB
subgraph "前端 fms-vue"
A["src/main.js"]
B["src/App.vue"]
C[".oxlintrc.json"]
D[".oxfmtrc.json"]
E["package.json"]
end
subgraph "后端 fms-api"
F["application.yaml"]
G["pom.xml"]
H["FmsApiApplication.java"]
I["controller/*"]
J["service/*"]
K["exception/*"]
end
A --> B
C --> A
D --> A
E --> A
H --> I
I --> J
I --> K
F --> H
G --> H
```

**图表来源**
- [fms-vue/src/main.js:1-78](file://fms-vue/src/main.js#L1-L78)
- [fms-vue/src/App.vue:1-15](file://fms-vue/src/App.vue#L1-L15)
- [fms-vue/.oxlintrc.json:1-21](file://fms-vue/.oxlintrc.json#L1-L21)
- [fms-vue/.oxfmtrc.json:1-8](file://fms-vue/.oxfmtrc.json#L1-L8)
- [fms-vue/package.json:1-48](file://fms-vue/package.json#L1-L48)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-api/pom.xml:1-108](file://fms-api/pom.xml#L1-L108)
- [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-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)
- [fms-api/pom.xml:5-31](file://fms-api/pom.xml#L5-L31)

## 核心组件
- 前端应用入口与启动流程：main.js 负责创建应用、注册插件、路由就绪后挂载；App.vue 作为根组件仅渲染当前路由
- 后端应用入口：FmsApiApplication 初始化雪花ID生成器并启动Spring容器
- 配置中心：application.yaml 定义服务端口、上下文路径、JWT、数据库连接池、文件存储策略等

**章节来源**
- [fms-vue/src/main.js:14-22](file://fms-vue/src/main.js#L14-L22)
- [fms-vue/src/main.js:41-77](file://fms-vue/src/main.js#L41-L77)
- [fms-vue/src/App.vue:1-15](file://fms-vue/src/App.vue#L1-L15)
- [fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java:9-18](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L9-L18)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

## 架构总览
前后端通过HTTP交互，前端通过Pinia管理状态，后端以Spring MVC暴露REST接口，统一异常处理与鉴权。

```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant FE as "Vue应用(main.js)"
participant BE as "Spring Boot(FmsApiApplication)"
participant CTRL as "Controller层"
participant SVC as "Service层"
participant DB as "数据库"
U->>FE : 访问页面
FE->>FE : 路由就绪、主题同步
FE-->>U : 挂载根组件(App.vue)
U->>BE : HTTP请求(/api/...)
BE->>CTRL : 分发到对应控制器
CTRL->>SVC : 调用业务服务
SVC->>DB : 读写数据
DB-->>SVC : 结果
SVC-->>CTRL : 返回业务对象
CTRL-->>U : JSON响应或错误
```

**图表来源**
- [fms-vue/src/main.js:41-77](file://fms-vue/src/main.js#L41-L77)
- [fms-vue/src/App.vue:11-14](file://fms-vue/src/App.vue#L11-L14)
- [fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java:9-18](file://fms-api/src/main/java/cn/g3soft/fmsapi/FmsApiApplication.java#L9-L18)
- [fms-api/src/main/resources/application.yaml:1-5](file://fms-api/src/main/resources/application.yaml#L1-L5)

## 详细组件分析

### 前端代码风格与质量工具
- 代码检查：使用 Oxlint，启用 vue、unicorn、oxc 插件；correctness 为 error，suspicious 为 warn；浏览器环境默认开启；vite.config.js 单独启用 node 环境
- 代码格式化：使用 OxFmt，行宽100，不加分号，单引号，尾随逗号全量
- 脚本命令：lint、lint:fix、fmt、fmt:check、build、test 等

```mermaid
flowchart TD
Start(["开发者提交代码"]) --> Lint["运行 oxlint<br/>校验规则"]
Lint --> |通过| Fmt["运行 oxfmt --check<br/>格式检查"]
Lint --> |失败| Fix["运行 oxlint --fix<br/>自动修复"]
Fix --> Fmt
Fmt --> |通过| Build["构建与测试"]
Fmt --> |失败| ReFmt["运行 oxfmt --write<br/>自动格式化"]
ReFmt --> Build
```

**图表来源**
- [fms-vue/.oxlintrc.json:1-21](file://fms-vue/.oxlintrc.json#L1-L21)
- [fms-vue/.oxfmtrc.json:1-8](file://fms-vue/.oxfmtrc.json#L1-L8)
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)

**章节来源**
- [fms-vue/.oxlintrc.json:1-21](file://fms-vue/.oxlintrc.json#L1-L21)
- [fms-vue/.oxfmtrc.json:1-8](file://fms-vue/.oxfmtrc.json#L1-L8)
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)

### Vue 组件开发规范
- 组件结构：推荐单文件组件 .vue，模板、脚本、样式分离；根组件 App.vue 仅负责路由渲染与可选的性能监控浮层
- Props 定义：在 <script setup> 中使用 defineProps 明确类型与默认值，避免隐式 any
- 事件处理：优先使用 emits 声明事件；组合式函数封装复用逻辑（composables）
- 样式编写：全局样式集中于 styles/index.css；组件级样式使用 scoped 或模块化；主题通过 CSS 变量与类名切换
- 状态管理：使用 Pinia 管理跨组件状态，结合持久化插件恢复主题等设置

```mermaid
classDiagram
class AppVue {
+template : "#app"
+router-view
+FpsMonitor(条件渲染)
}
class MainJS {
+createApp()
+use(Pinia, Router)
+initThemeSync()
+bootstrap()
}
AppVue <.. MainJS : "被挂载"
```

**图表来源**
- [fms-vue/src/App.vue:1-15](file://fms-vue/src/App.vue#L1-L15)
- [fms-vue/src/main.js:14-22](file://fms-vue/src/main.js#L14-L22)
- [fms-vue/src/main.js:41-77](file://fms-vue/src/main.js#L41-L77)

**章节来源**
- [fms-vue/src/App.vue:1-15](file://fms-vue/src/App.vue#L1-L15)
- [fms-vue/src/main.js:1-78](file://fms-vue/src/main.js#L1-L78)

### 后端 Java 开发规范
- 分层组织
  - Controller：接收HTTP请求，参数校验，委托Service处理
  - Service：业务编排与事务边界
  - Repository/DAO：数据访问（本项目通过JDBC/Druid访问）
- 异常处理：集中式异常处理器 GlobalExceptionHandler 统一捕获并返回标准错误体
- 日志记录：建议按模块与级别输出关键操作与异常堆栈
- 配置管理：application.yaml 管理服务端口、上下文路径、JWT、数据库连接池、文件存储策略

```mermaid
sequenceDiagram
participant Client as "客户端"
participant AuthCtrl as "AuthController"
participant AuthService as "AuthService"
participant DB as "数据库"
Client->>AuthCtrl : POST /api/auth/login
AuthCtrl->>AuthService : 验证凭据
AuthService->>DB : 查询用户信息
DB-->>AuthService : 用户数据
AuthService-->>AuthCtrl : 登录结果
AuthCtrl-->>Client : JWT令牌或错误
```

**图表来源**
- [fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java)
- [fms-api/src/main/resources/application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)

**章节来源**
- [fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/controller/AuthController.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/AuthService.java)
- [fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

### 数据保存与变更追踪
- DataSaveService 负责数据落库与变更追踪，确保一致性
- 建议在Service层对批量操作进行事务控制，并在异常时回滚

```mermaid
flowchart TD
Start(["开始保存"]) --> Validate["参数与权限校验"]
Validate --> |通过| Save["执行保存/更新"]
Validate --> |失败| ReturnErr["返回错误"]
Save --> Track["记录变更日志"]
Track --> Commit{"是否成功?"}
Commit --> |是| Done(["完成"])
Commit --> |否| Rollback["回滚并抛出异常"]
Rollback --> Done
```

**图表来源**
- [fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java)

**章节来源**
- [fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/service/DataSaveService.java)

## 依赖分析
- 前端依赖：Vue 3、Vue Router、Pinia、Axios、Dayjs、stk-table-vue 等；开发依赖包含 Vite、Vitest、Oxlint、OxFmt、Sass
- 后端依赖：Spring Boot WebMVC/JDBC、Druid、JWT、Jackson、IP地址解析、UA解析、SQL Server驱动

```mermaid
graph LR
subgraph "前端依赖"
VUE["Vue 3"]
ROUTER["Vue Router"]
PINIA["Pinia"]
AXIOS["Axios"]
TABLE["stk-table-vue"]
LINT["Oxlint/OxFmt"]
end
subgraph "后端依赖"
SB["Spring Boot"]
JDBC["Spring JDBC"]
DRUID["Druid"]
JWT["JWT"]
JACKSON["Jackson"]
SQL["SQL Server Driver"]
end
VUE --> ROUTER
ROUTER --> PINIA
PINIA --> AXIOS
AXIOS --> TABLE
SB --> JDBC
JDBC --> DRUID
SB --> JWT
SB --> JACKSON
JDBC --> SQL
```

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

**章节来源**
- [fms-vue/package.json:21-45](file://fms-vue/package.json#L21-L45)
- [fms-api/pom.xml:32-96](file://fms-api/pom.xml#L32-L96)

## 性能考虑
- 前端首屏优化：路由就绪后再挂载应用，减少白屏时间；按需加载FPS监控组件；主题同步在挂载前完成，避免闪烁
- 表格性能：使用 stk-table-vue 的虚拟滚动与区域选择特性，提升大数据量下的交互体验
- 后端连接池：合理配置 Druid 初始大小、最大活跃数、空闲回收策略，降低数据库压力
- 缓存与幂等：对读多写少的接口增加缓存；写接口保证幂等，避免重复提交

[本节为通用指导，无需特定文件引用]

## 故障排查指南
- 前端启动失败：main.js 中捕获异常并显示重试按钮；检查网络与路由守卫前置逻辑
- 后端异常：GlobalExceptionHandler 统一捕获业务与系统异常，返回标准化错误码与信息；查看日志定位问题
- 配置问题：application.yaml 中的端口、上下文路径、JWT密钥、数据库连接池参数需与环境一致

**章节来源**
- [fms-vue/src/main.js:24-39](file://fms-vue/src/main.js#L24-L39)
- [fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

## 结论
本规范明确了FMS项目在前后端的代码风格、模块组织、质量工具与异常处理策略。遵循本规范可提升代码可读性、可维护性与交付质量。建议在新功能开发中严格对照执行，并通过CI集成自动化检查。

## 附录
- 命名约定
  - JS/Vue：文件名使用 kebab-case；组件名使用 PascalCase；常量 UPPER_SNAKE_CASE
  - Java：包名小写；类名 PascalCase；方法/字段 camelCase；常量 UPPER_SNAKE_CASE
- 文件组织
  - 前端：按功能域划分 views/components/services/stores/utils/styles
  - 后端：controller/service/exception/config/database/utils 分层清晰
- 注释标准
  - 公共API与复杂逻辑必须添加JSDoc/Javadoc说明
  - 关键分支与边界条件需补充行内注释
- 质量门禁
  - 提交前执行 lint、fmt:check、build、test
  - 合并前确保无警告与错误

[本节为通用指导，无需特定文件引用]