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

## 一、项目概述

**项目名称**：软件项目资源登记平台（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`             | 操作日志分页     | 登录用户 |