软件项目资源登记平台 — 项目架构与模块功能文档

一、项目概述

项目名称：软件项目资源登记平台（resource-platform）

项目定位：面向团队内部的云资源/服务套餐台账管理系统，用于登记每个项目使用了哪些资源、资源的到期时间、负责人信息，并在到期前自动发送邮件提醒，避免资源过期影响业务。

核心价值：

集中管理分散在各人手中的云资源信息，形成统一台账
自动跟踪资源到期状态，分阶段邮件提醒，减少人工遗漏
建立项目与资源的关联关系，清晰掌握每个项目的资源使用情况
提供费用统计维度，辅助成本管控决策

二、技术架构

2.1 技术栈总览

层次	技术选型	版本
前端框架	Vue 3 (Composition API + `<script setup>`)	3.4.21
构建工具	Vite	5.1.6
UI 组件库	Element Plus	2.6.1
状态管理	Pinia	2.1.7
HTTP 客户端	Axios	1.6.8
路由	Vue Router 4	4.3.0
后端框架	Spring Boot 3	3.2.5
编程语言	Java	17
ORM 框架	MyBatis-Plus	3.5.5
安全框架	Spring Security + JWT (jjwt)	0.11.5
数据库	MySQL	8.0+
邮件	Spring Boot Starter Mail	—
Excel导出	Alibaba EasyExcel	3.3.2
参数校验	Jakarta Validation (Spring Boot Starter Validation)	—
工具库	Lombok、Day.js	—

2.2 系统架构图

┌─────────────────────────────────────────────────────────────┐
│                        浏览器 (前端)                          │
│  Vue 3 + Element Plus + Pinia + Vue Router + Axios          │
│  ┌──────────┬──────────┬──────────┬──────────┬───────────┐  │
│  │ 工作台   │ 资源管理  │ 项目管理  │ 费用统计  │ 系统管理  │  │
│  └──────────┴──────────┴──────────┴──────────┴───────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP (REST API + JWT)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     Spring Boot 后端 (:8080/api)             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Controller 层 (REST 接口)                 │   │
│  │  AuthController · ResourceController · ProjectController │
│  │  DashboardController · UserController · OperationLogController │
│  │  ResourceTypeController · ProviderController          │   │
│  └──────────────────────┬───────────────────────────────┘   │
│  ┌──────────────────────▼───────────────────────────────┐   │
│  │              Service 层 (业务逻辑)                     │   │
│  │  ResourceService · ProjectService · DashboardService  │   │
│  │  SysUserService · OperationLogService · EmailService  │   │
│  │  ResourceTypeService · ProviderService                │   │
│  └──────────────────────┬───────────────────────────────┘   │
│  ┌──────────────────────▼───────────────────────────────┐   │
│  │              Mapper 层 (MyBatis-Plus DAO)             │   │
│  └──────────────────────┬───────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Security: JwtAuthenticationFilter + SecurityConfig   │   │
│  │  Task: ResourceExpireTask (定时到期扫描 + 邮件提醒)    │   │
│  │  Common: Result / BusinessException / GlobalExceptionHandler │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────┬──────────────────────────────────┘
                           │ JDBC
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     MySQL 8.0 数据库                         │
│  resource_platform (8张表)                                   │
└─────────────────────────────────────────────────────────────┘

2.3 前后端交互机制

通信协议：RESTful HTTP API，后端统一前缀 /api
认证方式：JWT Token，前端存储在 localStorage，通过 Axios 拦截器自动附加到 Authorization: Bearer <token> 请求头
数据格式：统一响应结构 { code: 200, message: "success", data: ... }
错误处理：
- 前端 Axios 响应拦截器统一处理 code !== 200 的业务错误和 HTTP 状态码错误
- 401 自动跳转登录页，403 提示无权限
文件下载：Excel 导出使用 responseType: 'blob' 直接下载

2.4 部署架构

前端 (Vite dev / dist 静态文件)
  ├── 开发环境: vite.config.js 代理 /api → localhost:8080
  └── 生产环境: Nginx 反向代理

后端 (Spring Boot JAR)
  ├── 端口: 8080
  ├── 上下文路径: /api
  └── 数据库: 阿里云 RDS MySQL

三、数据库设计

3.1 ER 关系图

sys_user (用户表)
    │
    ├──< project (项目表) [owner_id → sys_user.id]
    │        │
    │        └──< project_resource (关联表) [project_id → project.id]
    │                  │
    │                  └──> resource (资源表) [resource_id → resource.id]
    │                           │
    │                           ├──> resource_type (类型字典) [type_id → resource_type.id]
    │                           ├──> provider (服务商字典) [provider_id → provider.id]
    │                           └──< expire_notify_log (提醒记录) [resource_id → resource.id]
    │
    └──< operation_log (操作日志) [user_id → sys_user.id]

3.2 数据表说明

表名	说明	核心字段	特殊设计
`sys_user`	系统用户表	username(唯一), password(BCrypt加密), real_name, email, role(1管理员/2普通), status	无逻辑删除
`resource_type`	资源类型字典表	name(唯一), sort(排序), remark	可扩展字典，用户自行维护
`provider`	服务商字典表	name(唯一), remark	可扩展字典
`project`	项目表	name, owner_id, status(1进行中/0已下线), remark	逻辑删除(deleted字段)
`resource`	资源表(核心)	name, type_id, provider_id, account_info, start_date, expire_date, cost, cost_cycle, owner_id, status	逻辑删除；status 自动刷新
`project_resource`	项目资源关联表	project_id, resource_id (联合唯一)	多对多关系中间表
`expire_notify_log`	到期提醒记录	resource_id, notify_stage(1提前30天/2提前7天/3已过期), notify_email	resource_id+notify_stage 唯一约束，防重复发送
`operation_log`	操作日志表	user_id, module, action, target_id, content	记录关键业务操作

3.3 初始数据

默认管理员账号：admin / admin123（BCrypt 加密存储）
预置资源类型：云服务器、云数据库、对象存储、域名、SSL证书、CDN、短信套餐、邮件套餐、其他
预置服务商：阿里云、腾讯云、华为云、AWS、其他

四、后端模块功能详解

4.1 认证与鉴权模块 (`security` + `AuthController`)

功能：

用户登录：通过 Spring Security AuthenticationManager 校验账号密码，成功后生成 JWT Token 返回
Token 解析：JwtUtil 负责生成和解析 Token，载荷存储 userId 和 username
请求过滤：JwtAuthenticationFilter 拦截每个请求，从 Authorization 头提取并验证 Token，设置 SecurityContext
获取当前用户：/auth/me 接口，前端刷新页面后通过 Token 换取用户信息
修改密码：/auth/password 接口，校验原密码后更新

权限控制（SecurityConfig）：

/auth/login：公开访问，无需认证
/user/enabled-list：所有已登录用户可访问（负责人下拉选择使用）
/user/**：仅 ROLE_ADMIN（管理员）可访问
其余接口：登录即可访问

4.2 资源管理模块 (`ResourceController` + `ResourceServiceImpl`)

功能：

分页查询 GET /resource/page：支持按名称模糊搜索、类型、服务商、负责人、状态、到期天数范围、关联项目 ID 多维度筛选
详情查询 GET /resource/{id}：返回资源完整信息，含关联项目列表
新增/编辑 POST /resource：保存资源基本信息，同时维护项目关联关系（先删后插策略保证数据一致性）
删除 DELETE /resource/{id}：逻辑删除资源，同时清理关联关系
关联操作 POST /resource/relate：从项目详情页批量关联资源
解除关联 DELETE /resource/unrelate：解除项目与资源的关联
费用统计 GET /resource/cost-stat/project 和 /cost-stat/type：按项目和按资源类型两个维度统计费用
Excel 导出 GET /resource/export：使用 EasyExcel 将查询结果导出为 .xlsx 文件

核心设计：

VO 组装采用批量查询策略（assembleVOList），收集所有关联 ID 后批量查询类型/服务商/负责人/项目名称，避免 N+1 查询问题
资源状态（使用中/即将到期/已过期）由定时任务自动刷新，而非在查询时实时计算

4.3 项目管理模块 (`ProjectController` + `ProjectServiceImpl`)

功能：

分页查询 GET /project/page：支持按名称、负责人、状态筛选，列表展示关联资源数量
详情查询 GET /project/{id}：返回项目信息及其关联的全部资源列表
新增/编辑 POST /project
删除 DELETE /project/{id}：逻辑删除项目，同时清理关联关系
活跃项目列表 GET /project/active-list：供资源表单中"关联项目"多选下拉使用

4.4 工作台模块 (`DashboardController` + `DashboardServiceImpl`)

功能：

统计面板：项目总数、资源总数、即将到期资源数、已过期资源数
到期关注列表：展示即将到期和已过期资源（按到期日期升序，最多10条）
资源类型分布：各类型的资源数量统计

4.5 字典管理模块 (`ResourceTypeController` + `ProviderController`)

功能：

资源类型 CRUD：列表（按 sort 排序）、新增/编辑、删除
服务商 CRUD：列表、新增/编辑、删除

4.6 用户管理模块 (`UserController` + `SysUserServiceImpl`)

功能（仅管理员可操作）：

用户列表 GET /user/list
启用用户列表 GET /user/enabled-list（所有登录用户可用，用于负责人选择）
新增/编辑用户 POST /user：新增必须设置初始密码，编辑时密码非必填
删除用户 DELETE /user/{id}

4.7 操作日志模块 (`OperationLogController` + `OperationLogServiceImpl`)

功能：

分页查询操作日志 GET /operation-log/page：按时间倒序
日志记录：在资源/项目/用户的增删改操作中自动记录，包含操作模块、操作类型、操作对象 ID 和详情

4.8 到期提醒定时任务 (`ResourceExpireTask`)

功能：

每天定时执行（默认每天 8:00，cron 可配置）
第一步：刷新所有非停用资源的状态（refreshExpireStatus）
- 已过期 → status=3
- 30天内到期 → status=2
- 其他 → status=1
第二步：扫描需要邮件提醒的资源
- 提前30天（stage=1）、提前7天（stage=2）、已过期（stage=3）三个阶段
- 通过 expire_notify_log 唯一约束确保每个资源每个阶段只发送一次
- 邮件内容根据阶段不同采用不同措辞（普通提醒/紧急/已过期）

4.9 公共模块 (`common`)

类	功能
`Result<T>`	统一 API 响应结构 {code, message, data}
`BusinessException`	业务异常，携带错误信息
`GlobalExceptionHandler`	全局异常处理器，捕获 BusinessException、参数校验异常、认证异常等，统一返回错误响应
`PageQuery`	分页查询基类 (pageNum, pageSize)

五、前端模块功能详解

5.1 路由结构

路径	页面	说明	权限
`/login`	Login.vue	登录页	公开
`/dashboard`	Dashboard.vue	工作台（默认首页）	登录用户
`/resource`	ResourceList.vue	资源列表	登录用户
`/project`	ProjectList.vue	项目列表	登录用户
`/project/:id`	ProjectDetail.vue	项目详情	登录用户
`/cost-stat`	CostStat.vue	费用统计	登录用户
`/dict`	DictManage.vue	字典管理（资源类型+服务商）	登录用户
`/user`	UserManage.vue	用户管理	仅管理员
`/log`	OperationLog.vue	操作日志	登录用户

路由守卫：未登录用户自动跳转登录页（携带 redirect 参数），已登录用户访问登录页自动跳转工作台。

5.2 页面功能

5.2.1 登录页 (Login.vue)

账号密码表单，调用 /auth/login 获取 Token
Token 存储到 localStorage 和 Pinia Store
登录成功后跳转到 redirect 地址或默认工作台

5.2.2 布局 (Layout.vue)

左侧导航栏 + 顶部标题栏 + 内容区
导航菜单根据用户角色动态显示（用户管理仅管理员可见）
右上角用户下拉菜单：修改密码、退出登录

5.2.3 工作台 (Dashboard.vue)

四个统计卡片：项目总数、资源总数、即将到期、已过期
左侧表格：需要关注的资源列表（即将到期/已过期）
右侧：资源类型分布条形图

5.2.4 资源管理 (ResourceList.vue + ResourceForm.vue)

列表页：多维度筛选（名称、类型、负责人、状态）+ 分页表格 + Excel 导出
表单弹窗：新增/编辑资源，选择类型、服务商、负责人、关联项目等

5.2.5 项目管理 (ProjectList.vue + ProjectDetail.vue)

列表页：项目筛选、分页展示，显示关联资源数量
详情页：展示项目基本信息、关联资源列表，支持关联/解除资源操作

5.2.6 费用统计 (CostStat.vue)

按项目维度统计费用（资源数 + 总费用）
按资源类型维度统计费用

5.2.7 字典管理 (DictManage.vue)

资源类型管理：列表展示、新增/编辑、删除
服务商管理：列表展示、新增/编辑、删除

5.2.8 用户管理 (UserManage.vue)

用户列表、新增/编辑（含角色分配、初始密码设置）、删除

5.2.9 操作日志 (OperationLog.vue)

分页展示操作日志，显示操作人、模块、操作类型、操作时间

5.3 状态管理 (Pinia)

User Store (store/user.js)：

token：JWT Token（持久化到 localStorage）
userInfo：当前用户信息（id, username, realName, role）
login()：登录并保存 Token
fetchMe()：通过 Token 获取用户信息
isAdmin()：判断是否为管理员
clearToken()：清除登录状态

5.4 API 封装

文件	接口
`api/auth.js`	loginApi, getMeApi, updatePasswordApi
`api/dashboard.js`	dashboardApi
`api/resource.js`	resourcePageApi, resourceDetailApi, resourceSaveApi, resourceDeleteApi, resourceRelateApi, resourceUnrelateApi, costStatByProjectApi, costStatByTypeApi, resourceExportApi
`api/project.js`	projectPageApi, projectDetailApi, projectSaveApi, projectDeleteApi, projectActiveListApi
`api/dict.js`	resourceTypeListApi, resourceTypeSaveApi, resourceTypeDeleteApi, providerListApi, providerSaveApi, providerDeleteApi
`api/user.js`	userListApi, userEnabledListApi, userSaveApi, userDeleteApi
`api/log.js`	operationLogPageApi

六、后端 API 接口清单

方法	路径	说明	权限
POST	`/auth/login`	用户登录	公开
PUT	`/auth/password`	修改密码	登录用户
GET	`/auth/me`	获取当前用户信息	登录用户
GET	`/dashboard`	工作台数据	登录用户
GET	`/resource/page`	资源分页查询	登录用户
GET	`/resource/{id}`	资源详情	登录用户
POST	`/resource`	新增/编辑资源	登录用户
DELETE	`/resource/{id}`	删除资源	登录用户
POST	`/resource/relate`	关联资源到项目	登录用户
DELETE	`/resource/unrelate`	解除资源关联	登录用户
GET	`/resource/cost-stat/project`	按项目费用统计	登录用户
GET	`/resource/cost-stat/type`	按类型费用统计	登录用户
GET	`/resource/export`	导出 Excel	登录用户
GET	`/project/page`	项目分页查询	登录用户
GET	`/project/{id}`	项目详情	登录用户
POST	`/project`	新增/编辑项目	登录用户
DELETE	`/project/{id}`	删除项目	登录用户
GET	`/project/active-list`	活跃项目列表	登录用户
GET	`/resource-type/list`	资源类型列表	登录用户
POST	`/resource-type`	新增/编辑类型	登录用户
DELETE	`/resource-type/{id}`	删除类型	登录用户
GET	`/provider/list`	服务商列表	登录用户
POST	`/provider`	新增/编辑服务商	登录用户
DELETE	`/provider/{id}`	删除服务商	登录用户
GET	`/user/list`	用户列表	管理员
GET	`/user/enabled-list`	启用用户列表	登录用户
POST	`/user`	新增/编辑用户	管理员
DELETE	`/user/{id}`	删除用户	管理员
GET	`/operation-log/page`	操作日志分页	登录用户

01-项目架构与模块功能文档.md 22 KB History Raw