# eh-pb

**Repository Path**: MISSMYSEIF/eh-pb

## Basic Information

- **Project Name**: eh-pb
- **Description**: 这是一款bug管理系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🐛 Bug Management System — 缺陷管理系统

> 前后端分离的 SaaS 多租户缺陷管理系统，类似禅道 / Jira，深度集成 Git 代码库。

<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-17-blue.svg)]()
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.12-brightgreen.svg)]()
[![Vue](https://img.shields.io/badge/Vue-3.4-green.svg)]()
[![SQLite](https://img.shields.io/badge/SQLite-Default-orange.svg)]()

</div>

---

## ✨ 功能特性

- 🔐 **多租户 SaaS**：支持多租户独立部署，自定义状态流
- 📊 **项目活动流**：汇总缺陷历史、评论，形成项目级活动时间线
- 🌙 **深色模式**：一键切换深色主题，保护视力
- ⌨️ **快捷键**：Ctrl+K/Cmd+K 快速打开全局搜索
- 🐛 **缺陷全生命周期**：创建 → 处理 → 验证 → 关闭，9 种状态流转
- 📁 **项目与成员管理**：项目、模块、成员、角色权限
- 🔗 **Git 平台集成**：GitHub / GitLab / Gitea 仓库关联、分支/提交/MR 管理
- 📊 **报表分析**：趋势图、燃尽图、人员负载、CSV/PDF/PNG 导出
- 🔔 **通知系统**：站内通知、邮件通知（HTML模板）、Webhook 推送
- 🗄️ **多数据库支持**：默认 SQLite，可切换 MySQL
- 📝 **迭代管理**：Sprint 计划/跟踪，缺陷关联迭代，迭代燃尽图
- 🏷️ **标签管理**：项目级标签，缺陷标签过滤与标签云，支持重命名和自定义颜色
- 🔗 **缺陷关联**：Duplicate/Blocked by/Related to 缺陷关联
- 🤖 **AI 智能分类**：自动建议标签/优先级/严重程度
- 📥 **批量导入/导出**：CSV 批量导入导出缺陷，支持模板下载
- 📦 **项目归档**：支持归档/恢复项目
- 👥 **用户管理**：用户搜索/启用/禁用
- 🎭 **角色管理**：自定义角色创建、权限分配、用户角色管理
- 🔒 **AccessToken 加密存储**：Git 平台令牌 AES 加密，API 响应自动脱敏
- ✅ **Assignee 项目成员校验**：处理人必须是项目成员，防止越权分配
- 📥 **Excel 导入/导出**：支持 xlsx 格式缺陷导入导出与模板下载，导入过程显示实时上传进度
- 🧪 **文件内容深度校验**：附件上传 magic bytes 校验，防伪装文件类型
- 🤖 **AI 分类 LLM 扩展**：可选接入大模型 API 进行智能分类
- 🔐 **Redis 分布式锁**：并发缺陷操作自动加锁防冲突
- 📋 **自定义字段必填校验**：创建缺陷时自动校验必填自定义字段
- 📈 **团队数据看板**：多项目汇总统计
- 📊 **缺陷统计分析**：状态/优先级/严重程度分布、30天趋势、解决率分析
- 🔒 **项目级权限控制**：全局权限 + 项目成员双重校验
- 🔄 **MR/PR 真实数据**：从 Git 平台拉取真实合并请求数据
- 📎 **附件管理**：上传/下载/在线预览/删除，支持批量上传与拖拽上传，支持图片/PDF/文本
- ⏱️ **WIP 限制**：看板进行中缺陷数量自动限制（含批量状态变更）
- 🏷️ **标签表精确关联**：缺陷-标签关联表精确统计与过滤，替代简单逗号字符串
- 🛡️ **附件深度安全扫描**：压缩包可执行文件检测、Office 文档宏检测
- 🔐 **Token 加密存储**：Git 平台 AccessToken 使用 AES/GCM 加密（随机 IV）
- 🔑 **邮箱验证码重置密码**：`/auth/reset-password/send-code` → 验证码确认，前端提供独立「忘记密码」页面
- 🌐 **WebSocket 白名单**：可配置允许的来源，防止跨域攻击
- 🛡️ **GitLab/Gitea Webhook 签名验证**：HMAC-SHA1/SHA256 签名校验
- 🔄 **REJECTED 状态可恢复**：被拒绝的缺陷可重新打开或确认
- 📊 **审计日志清理/统计**：自动归档与运维管理接口
- 🔄 **Redis 缓存统一封装**：统一缓存读写 + 跨实例缓存失效广播（pub/sub）
- 🔐 **前端路由级权限控制**：按权限动态过滤菜单与路由访问
- 📤 **审计日志导出**：审计日志一键导出 CSV，含操作/资源/IP/时间
- 🔍 **通知筛选**：按事件类型/关键字筛选通知消息
- 📦 **通知批量管理**：支持勾选多条批量标记已读/删除
- 🔍 **全局搜索**：跨项目搜索缺陷（关键词/状态/优先级/严重程度）
- 📅 **日历视图**：按月查看缺陷的计划修复时间分布
- 📈 **Dashboard 增强**：标签云、状态分布可视化
- ⏱️ **缺陷变更历史时间线**：详情页展示完整变更历史

- 🔔 **缺陷关注/订阅**：用户可关注缺陷，状态变更时自动收到通知
- 💬 **评论 @提及**：评论中 @ 用户名可实时通知被提及者
- 🔐 **WebSocket Token 黑名单校验**：登出后的 Token 无法连接 WebSocket
- 🛡️ **租户隔离加强**：内部服务间调用自动传递租户上下文，防止跨租户数据泄漏
- 📊 **Dashboard 标签云跳转**：点击标签云可直接跳转到对应项目的缺陷列表筛选
- 🔄 **JWT Refresh Token**：Token过期自动刷新，无需重新登录
- ⏰ **缺陷定时提醒**：为缺陷设置提醒时间，到点自动通知
- 📊 **Dashboard趋势图**：近30天缺陷创建趋势可视化折线图
- 🎨 **看板WIP限制显示**：看板进行中列显示WIP数量/上限，超限高亮警告
- 🔔 **通知声音/桌面通知**：通知到达时可播放声音并显示浏览器桌面通知
- 📝 **通知模板管理**：按事件类型自定义通知标题与内容模板（支持占位符）
- 📊 **缺陷列表自定义列**：支持显示/隐藏缺陷列表列（对标Jira列定制）
- 🔒 **SSO安全增强**：OAuth2 code不落日志，JWT不通过URL传递，LDAP登录需密码验证
- 🕐 **批量计划修复时间**：批量修改缺陷的计划修复时间
- 🏷️ **批量标签编辑**：批量添加/移除缺陷标签
- 📝 **评论Markdown预览**：评论支持Markdown格式渲染
- 📝 **描述Markdown渲染**：缺陷描述支持 Markdown 格式渲染，与评论一致
- 📋 **项目模板复制**：一键复制项目结构（模块/成员），自动重映射父子模块层级，保留完整模块树
- 📤 **Dashboard数据导出**：一键导出CSV
- 🔗 **Webhook精细订阅**：按缺陷ID粒度订阅事件，支持自定义重试次数与退避间隔（指数退避策略）
- ✏️ **缺陷编辑/删除**：详情页支持编辑缺陷全部字段与删除缺陷
- 💬 **评论编辑/删除**：支持编辑和删除自己的评论
- 🧩 **子任务/父子缺陷**：支持将缺陷设为另一个缺陷的子任务
- ⏱️ **工时跟踪 (Worklog)**：缺陷详情页记录团队实际耗时，支持录入/编辑/删除与按缺陷聚合累计工时；
  新增**工时统计**在"我的任务"页展示个人本月/累计投入，并支持按人员查看单缺陷工时分布
- 📊 **自定义Dashboard布局**：可自定义仪表盘组件显示与隐藏
- 📡 **消息队列监控**：实时查看消息积压情况，支持重发死信
- 🏷️ **工单类型管理**：支持 BUG/REQUIREMENT/TASK 三种工单类型
- 📤 **自定义导出列**：导出缺陷时可选自定义列
- 📥 **按筛选条件导出**：导出时支持按状态/优先级/严重程度/关键词/工单类型/处理人筛选
- 🔒 **SSO 单点登录**：支持 OAuth2（GitHub/Google）与 LDAP 认证
- 🔍 **全链路追踪**：Trace ID 跨服务传播，统一日志追踪
- 📱 **移动端适配**：响应式布局，支持手机端访问；支持 PWA「添加到主屏幕」安装（manifest + 图标 + 主题色）
- 🧪 **前端单元测试**：Vitest 框架覆盖核心业务逻辑
- 🔍 **全局搜索增强**：支持按工单类型/模块筛选、多状态联合查询，支持跨项目查看自己负责/创建的缺陷
- 🚀 **游标分页**：深度分页性能优化
- 📋 **API 版本管理**：统一版本策略与版本信息接口
- 🔄 **并发安全测试**：覆盖分布式锁与乐观锁场景
- 📊 **多项目对比报表**：跨项目对比缺陷量、解决率、修复速度等指标
- 📈 **累计流图 (CFD)**：可视化缺陷在各状态下的数量随时间变化
- 💾 **数据备份与恢复**：一键备份 SQLite/MySQL 数据库，支持下载和删除
- 📧 **报表邮件定时推送**：每日/每周自动发送项目统计报表到指定邮箱
- 🔖 **搜索收藏筛选**：保存常用搜索条件，一键复用
- 📊 **看板泳道配置**：按优先级/严重程度/模块/处理人维度分组展示看板
- 📝 **缺陷模板管理**：项目级缺陷模板管理，创建缺陷时可一键应用模板
- 📋 **自定义字段管理**：项目设置中可视化配置自定义字段，支持必填校验
- ⏱️ **缺陷时效分析**：Dashboard 新增时效分析，识别长期未处理积压缺陷
- 🐧 **Linux/Mac 启动脚本**：提供 `start-all.sh` / `stop-all.sh`

- 📌 **搜索收藏服务端化**：搜索条件收藏持久化到数据库，跨设备同步
- ⚡ **我的任务批量操作**：跨项目批量修改状态/优先级/计划修复时间
- 🔄 **一键复制为子任务**：缺陷克隆后可快速设置为父子缺陷关系
- 📊 **系统健康监控**：运维面板实时查看各微服务健康状态与响应耗时
- 🏷️ **版本号展示**：侧边栏底部展示系统版本信息

## 🏗️ 技术栈

### 后端
| 技术 | 版本 | 用途 |
|------|------|------|
| Java | 17 | 运行时 |
| Spring Boot | 3.2.12 | 应用框架 |
| Spring Cloud | 2023.0.3 | 微服务治理 |
| MyBatis-Plus | 3.5.7 | ORM |
| SQLite / MySQL | 3.x / 8.x | 数据库 |
| Redis | 7.x | 缓存与分布式锁 |
| JWT | 0.12.6 | 认证授权 |

### 前端
| 技术 | 版本 | 用途 |
|------|------|------|
| Vue | 3.4 | 框架 |
| TypeScript | 5.x | 类型安全 |
| Vite | 5.x | 构建工具 |
| Element Plus | 2.8 | UI 组件库 |
| Pinia | 2.x | 状态管理 |
| ECharts | 6.x | 图表 |

## 📦 项目结构

```
├── bug-management-system/
│   ├── bug-common/           # 公共模块
│   ├── bug-gateway/          # API 网关 (:8080)
│   ├── bug-auth/             # 认证服务 (:8081)
│   ├── bug-service/          # 缺陷服务 (:8082)
│   ├── project-service/      # 项目管理 (:8083)
│   ├── repo-service/         # 代码仓库 (:8084)
│   ├── notification-service/ # 通知服务 (:8085)
│   ├── report-service/       # 报表服务 (:8086)
│   ├── tenant-service/       # 租户服务 (:8087)
│   └── bug-management-frontend/  # 前端应用
├── docs/                     # 📚 项目文档中心
├── tests/                    # 🧪 Python 测试脚本
├── start-all.bat            # ▶️ Windows 一键启动
├── stop-all.bat             # ⏸️ Windows 一键暂停
└── LICENSE                  # MIT 开源协议
```

## 🚀 快速启动

### 环境要求

- JDK 17+, Maven 3.9+
- Node.js 18+, npm 9+
- Redis 7.0+（可选，默认使用本地模式）

### 一键启动

**Windows:**
```bat
start-all.bat
```

**Linux / Mac:**
```bash
chmod +x start-all.sh
./start-all.sh
```

**停止服务:**
```bash
./stop-all.sh  # Linux/Mac
stop-all.bat    # Windows
```

### 手动启动

```bash
# 1. 启动后端
cd bug-management-system
mvn install -pl bug-common -am
mvn spring-boot:run -pl bug-gateway &
mvn spring-boot:run -pl bug-auth &

# 2. 启动前端
cd bug-management-frontend
npm install
npm run dev
```

### 访问系统

- **前端**：http://localhost:3000
- **API 网关**：http://localhost:8080

### 默认账号

| 用户名 | 密码 | 说明 |
|--------|------|------|
| `admin` | `admin123` | 系统管理员 |

> ⚠️ 生产环境请修改默认密码！

## 🗄️ 数据库支持

### 默认使用 SQLite

项目默认使用 SQLite，无需安装数据库即可开发运行。

### 切换 MySQL

在 `application.yml` 中切换 profile：

```yaml
spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:sqlite}  # 改为 mysql
```

执行初始化脚本：

```bash
mysql -u root -p < bug-management-system/sql/01_tenant_db.sql
mysql -u root -p < bug-management-system/sql/02_auth_db.sql
# ... 依次执行所有 SQL 脚本
```

## 📚 文档中心

| 文档 | 说明 |
|------|------|
| [快速开始](docs/guides/quickstart.md) | 从零部署和运行 |
| [架构设计](docs/architecture/architecture.md) | 系统架构与技术选型 |
| [API 文档](docs/api/api-reference.md) | 全量 RESTful API |
| [前端开发指南](docs/guides/frontend-guide.md) | Vue 3 前端开发规范 |
| [环境变量参考](docs/operations/environment-variables.md) | 各服务环境变量配置 |
| [数据库设计](docs/architecture/database-design.md) | 表结构与关系 |
| [第三方集成](docs/guides/third-party-integration.md) | Git 平台 / 邮件 / Webhook 集成教程 |
| [开发指南](docs/guides/development-guide.md) | 开发环境搭建与规范 |
| [部署指南](docs/guides/deployment-guide.md) | 生产环境部署 |
| [测试指南](docs/guides/testing-guide.md) | Python 测试使用 |
| [数据库迁移](docs/architecture/database-migration-guide.md) | Schema 变更指南 |
| [错误码参考](docs/api/error-codes.md) | 完整错误码列表 |
| [安全部署清单](docs/operations/security-deployment-checklist.md) | 生产环境安全检查项 |
| [API 变更记录](docs/api/api-changelog.md) | API 变更追踪 |
| [FAQ](docs/operations/faq.md) | 常见问题解答 |
| [故障排查](docs/operations/troubleshooting.md) | 常见故障排查速查 |
| [性能调优](docs/operations/performance-guide.md) | 索引优化 / 缓存 / 分页策略 |
| [API 兼容性](docs/guides/api-compatibility-guide.md) | 前后端 API 契约保障 |
| [SSO 单点登录指南](docs/guides/sso-guide.md) | GitHub / Google 一键登录、LDAP 对接配置 |
| [AI 缺陷自动分类接入](docs/guides/ai-classification-guide.md) | 接入真实 LLM 自动建议标签 / 优先级 / 严重程度 |
| [生产运维手册 Runbook](docs/operations/runbook.md) | 日志归档 / 备份恢复 / 监控告警 / 升级回滚 |
| [项目变更日志](docs/changelog/CHANGELOG.md) | 完整变更历史追踪 |

## 🧪 测试

### Python 集成测试

```bash
cd tests
pip install -r requirements.txt
pytest -v
```

### Java 后端测试

```bash
cd bug-management-system
mvn test
```

### 前端单元测试

```bash
cd bug-management-system/bug-management-frontend
npm install
npm test
```

> 后端 2561 JUnit 用例（9 服务模块）、前端 834 Vitest 用例（62 文件，语句覆盖率 ~95.6%）、Python 集成测试 145+ 用例全部通过。

## 📋 更多功能

- **Kanban看板** - 拖拽式状态变更，遵守状态流转约束，非法拖拽回弹；支持列内卡片拖拽排序（持久化排序值）
- **甘特图视图** - 缺陷时间线可视化，展示创建/计划修复/实际修复时间轴
- **批量操作** - 批量修改状态/优先级/处理人/删除
- **Webhook配置管理** - 可视化配置第三方Webhook，支持测试发送和签名验证
- **通知偏好设置** - 按事件类型配置邮件/站内/Webhook开关
- **审计日志** - 关键操作自动记录审计日志，支持分页查询

## 🗄️ 数据库设计

5个逻辑库、22张核心业务表（bug_core_db 含 18 张业务表 + bug_repo_db 关联表等）：
- `bug_tenant_db` - t_tenant, t_audit_log
- `bug_auth_db` - t_user, t_role, t_permission, t_role_permission, **t_user_role**
- `bug_core_db` - t_project, t_module, t_project_member, t_bug, t_bug_history, t_bug_comment, t_bug_commit_relation, t_bug_mr_relation, t_bug_attachment, t_bug_custom_field, t_custom_field_def, t_bug_relation, t_bug_tag, t_tag, t_bug_sprint, t_sprint, t_webhook_retry, t_bug_template, t_kanban_swimlane, t_bug_watch, t_bug_reminder, t_saved_filter
- `bug_repo_db` - t_repository, t_commit_record, t_merge_request, t_code_review（与 bug_core_db 共用缺陷关联表 t_bug_commit_relation / t_bug_mr_relation）
- `bug_notify_db` - t_notification, t_notify_preference, t_webhook_config

## 🧱 详细项目结构

```
bug-management-system/
├── bug-common/              # 公共模块(统一响应/异常/错误码/租户上下文)
├── bug-gateway/             # Spring Cloud Gateway (路由/限流/鉴权)
├── bug-auth/                # 认证服务 (JWT/RBAC/SecurityConfig)
├── bug-service/             # 缺陷服务 (CRUD/状态机/搜索/看板)
├── project-service/         # 项目服务 (项目/模块/成员)
├── repo-service/            # 代码库服务 (Git客户端工厂/Webhook/Commit解析)
├── notification-service/    # 通知服务 (邮件/站内/Webhook/去重/重试)
├── report-service/          # 报表服务 (趋势/燃尽/导出)
├── tenant-service/          # 租户服务 (注册/配额/隔离)
├── sql/                     # 数据库脚本 (6个, 含外键约束和初始数据)
├── docker/                  # Docker构建文件
├── bug-management-frontend/ # Vue3前端工程
├── docker-compose.yml       # Docker编排(含Nacos)
├── pom.xml                  # Maven父工程
└── README.md
```

## 📄 开源协议

本项目基于 [MIT License](LICENSE) 开源。