Initial commit: Gitea Project Management System
Features: - Complete project management system with Epic/Story/Task hierarchy - Vue.js 3 + Element Plus frontend with kanban board - Go backend with Gin framework and GORM - OAuth2 integration with Gitea - Docker containerization with MySQL - RESTful API for project, task, and user management - JWT authentication and authorization - Responsive web interface with dashboard
This commit is contained in:
huxunan
272
README.md
Normal file
272
README.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Gitea Project Management
|
||||
|
||||
一个与 Gitea 深度集成的项目管理系统，支持需求管理、任务追踪、迭代规划和研发协作。
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 核心功能
|
||||
- **需求管理**: 支持 Epic/Story/Task 三级需求分解
|
||||
- **项目管理**: 项目创建、成员管理、权限控制
|
||||
- **任务看板**: 可视化任务状态管理，支持拖拽操作
|
||||
- **迭代规划**: Sprint 管理、燃尽图、速度跟踪
|
||||
- **时间跟踪**: 工时记录和统计分析
|
||||
|
||||
### Gitea 集成
|
||||
- **OAuth 登录**: 使用 Gitea 账号直接登录
|
||||
- **仓库关联**: 任务与 Git 分支、提交、PR 自动关联
|
||||
- **Webhook 支持**: 监听 Gitea 事件自动更新任务状态
|
||||
- **权限同步**: 复用 Gitea 的用户和组织权限体系
|
||||
|
||||
### 协作功能
|
||||
- **评论系统**: 任务讨论和进度更新
|
||||
- **标签管理**: 自定义标签分类管理
|
||||
- **通知提醒**: 任务状态变更通知
|
||||
- **权限控制**: 细粒度的项目和功能权限
|
||||
|
||||
## 技术架构
|
||||
|
||||
### 后端技术栈
|
||||
- **Go 1.21+**: 主要开发语言
|
||||
- **Gin**: Web 框架
|
||||
- **GORM**: ORM 数据库操作
|
||||
- **MySQL**: 主数据库
|
||||
- **JWT**: 身份认证
|
||||
- **OAuth2**: Gitea 集成认证
|
||||
|
||||
### 前端技术栈
|
||||
- **Vue 3**: 前端框架
|
||||
- **Element Plus**: UI 组件库
|
||||
- **Axios**: HTTP 客户端
|
||||
|
||||
### 部署架构
|
||||
- **Docker**: 容器化部署
|
||||
- **Docker Compose**: 本地开发环境
|
||||
- **MySQL**: 数据持久化
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
- Go 1.21+
|
||||
- MySQL 5.7+
|
||||
- Node.js 16+ (如需修改前端)
|
||||
- Docker & Docker Compose (可选)
|
||||
|
||||
### 配置 Gitea OAuth
|
||||
|
||||
1. 在 Gitea 中创建 OAuth 应用：
|
||||
- 进入 Gitea 管理后台 → 应用 → OAuth2 应用
|
||||
- 创建新应用，设置回调 URL: `http://localhost:8080/api/v1/auth/callback`
|
||||
- 记录 Client ID 和 Client Secret
|
||||
|
||||
2. 修改配置文件 `config/config.yaml`：
|
||||
```yaml
|
||||
gitea:
|
||||
base_url: "http://your-gitea-url"
|
||||
client_id: "your-client-id"
|
||||
client_secret: "your-client-secret"
|
||||
redirect_url: "http://localhost:8080/api/v1/auth/callback"
|
||||
```
|
||||
|
||||
### 使用 Docker Compose 部署
|
||||
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone <project-url>
|
||||
cd giteapm
|
||||
|
||||
# 修改配置文件
|
||||
cp config/config.yaml.example config/config.yaml
|
||||
# 编辑 config/config.yaml 设置 Gitea 连接信息
|
||||
|
||||
# 启动服务
|
||||
docker-compose up -d
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f giteapm
|
||||
```
|
||||
|
||||
### 手动部署
|
||||
|
||||
```bash
|
||||
# 1. 安装依赖
|
||||
make install
|
||||
|
||||
# 2. 创建数据库
|
||||
mysql -u root -p -e "CREATE DATABASE giteapm CHARACTER SET utf8mb4;"
|
||||
|
||||
# 3. 导入数据库结构
|
||||
mysql -u root -p giteapm < schema.sql
|
||||
|
||||
# 4. 修改配置文件
|
||||
cp config/config.yaml.example config/config.yaml
|
||||
# 编辑数据库连接和 Gitea 配置
|
||||
|
||||
# 5. 构建并运行
|
||||
make build
|
||||
make run
|
||||
|
||||
# 或者直接运行开发模式
|
||||
make dev
|
||||
```
|
||||
|
||||
### 访问应用
|
||||
|
||||
打开浏览器访问: http://localhost:8080
|
||||
|
||||
点击"使用 Gitea 登录"按钮，会跳转到 Gitea 进行 OAuth 认证。
|
||||
|
||||
## 数据库设计
|
||||
|
||||
### 核心实体关系
|
||||
|
||||
```
|
||||
projects (项目)
|
||||
├── epics (史诗需求)
|
||||
│ └── stories (用户故事)
|
||||
│ └── tasks (任务)
|
||||
├── sprints (迭代)
|
||||
├── project_members (项目成员)
|
||||
└── webhook_configs (Webhook配置)
|
||||
|
||||
tasks (任务)
|
||||
├── gitea_relations (Git关联)
|
||||
├── time_logs (工时记录)
|
||||
├── comments (评论)
|
||||
└── entity_tags (标签)
|
||||
```
|
||||
|
||||
### 主要数据表
|
||||
|
||||
- `users`: 用户信息（与 Gitea 用户同步）
|
||||
- `projects`: 项目信息
|
||||
- `epics`: 大需求/史诗
|
||||
- `stories`: 用户故事
|
||||
- `tasks`: 具体任务
|
||||
- `gitea_relations`: 任务与 Git 对象的关联关系
|
||||
- `sprints`: 迭代/冲刺
|
||||
- `time_logs`: 工时记录
|
||||
- `comments`: 评论系统
|
||||
- `tags` & `entity_tags`: 标签系统
|
||||
|
||||
## API 文档
|
||||
|
||||
### 认证接口
|
||||
|
||||
- `GET /api/v1/auth/login` - 获取 Gitea OAuth 登录链接
|
||||
- `GET /api/v1/auth/callback` - OAuth 回调处理
|
||||
- `POST /api/v1/auth/logout` - 退出登录
|
||||
|
||||
### 项目管理
|
||||
|
||||
- `GET /api/v1/projects` - 获取项目列表
|
||||
- `POST /api/v1/projects` - 创建项目
|
||||
- `GET /api/v1/projects/:id` - 获取项目详情
|
||||
- `PUT /api/v1/projects/:id` - 更新项目
|
||||
- `DELETE /api/v1/projects/:id` - 删除项目
|
||||
|
||||
### 任务管理
|
||||
|
||||
- `GET /api/v1/tasks` - 获取任务列表
|
||||
- `POST /api/v1/tasks` - 创建任务
|
||||
- `GET /api/v1/tasks/:id` - 获取任务详情
|
||||
- `PUT /api/v1/tasks/:id` - 更新任务
|
||||
- `POST /api/v1/tasks/:id/time-logs` - 记录工时
|
||||
- `POST /api/v1/tasks/:id/gitea-relations` - 关联 Git 对象
|
||||
|
||||
详细 API 文档请参考: [API.md](docs/API.md)
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 项目结构
|
||||
|
||||
```
|
||||
giteapm/
|
||||
├── cmd/ # 应用入口
|
||||
├── config/ # 配置文件
|
||||
├── internal/ # 内部代码
|
||||
│ ├── api/ # API 路由和处理器
|
||||
│ ├── models/ # 数据模型
|
||||
│ ├── services/ # 业务逻辑
|
||||
│ └── middleware/ # 中间件
|
||||
├── web/ # 前端资源
|
||||
│ ├── static/ # 静态文件
|
||||
│ └── templates/ # 模板文件
|
||||
├── docs/ # 文档
|
||||
├── schema.sql # 数据库结构
|
||||
├── docker-compose.yml # Docker 配置
|
||||
└── Makefile # 构建脚本
|
||||
```
|
||||
|
||||
### 添加新功能
|
||||
|
||||
1. **添加数据模型**: 在 `internal/models/` 中定义数据结构
|
||||
2. **实现业务逻辑**: 在 `internal/services/` 中实现业务逻辑
|
||||
3. **添加 API 接口**: 在 `internal/api/handlers/` 中添加 HTTP 处理器
|
||||
4. **更新路由**: 在 `internal/api/router.go` 中注册路由
|
||||
5. **更新前端**: 修改 `web/templates/index.html` 添加 UI 功能
|
||||
|
||||
### 代码规范
|
||||
|
||||
- 使用 `gofmt` 格式化代码
|
||||
- 遵循 Go 官方代码规范
|
||||
- API 返回统一的 JSON 格式
|
||||
- 数据库操作使用事务确保一致性
|
||||
- 添加适当的日志记录
|
||||
|
||||
## 部署建议
|
||||
|
||||
### 生产环境部署
|
||||
|
||||
1. **数据库优化**:
|
||||
- 使用独立的 MySQL 服务器
|
||||
- 配置数据库连接池
|
||||
- 定期备份数据
|
||||
|
||||
2. **安全配置**:
|
||||
- 使用 HTTPS
|
||||
- 配置防火墙规则
|
||||
- 定期更新依赖版本
|
||||
|
||||
3. **性能优化**:
|
||||
- 启用 Redis 缓存
|
||||
- 配置 CDN 加速静态资源
|
||||
- 使用负载均衡
|
||||
|
||||
4. **监控告警**:
|
||||
- 配置日志收集
|
||||
- 设置应用监控
|
||||
- 配置告警通知
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **OAuth 认证失败**:
|
||||
- 检查 Gitea OAuth 应用配置
|
||||
- 确认回调 URL 正确
|
||||
- 检查网络连通性
|
||||
|
||||
2. **数据库连接失败**:
|
||||
- 检查数据库服务状态
|
||||
- 验证连接配置
|
||||
- 确认数据库权限
|
||||
|
||||
3. **Webhook 不工作**:
|
||||
- 检查 Gitea Webhook 配置
|
||||
- 验证网络可达性
|
||||
- 查看应用日志
|
||||
|
||||
## 贡献指南
|
||||
|
||||
1. Fork 项目
|
||||
2. 创建功能分支
|
||||
3. 提交代码更改
|
||||
4. 创建 Pull Request
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
|
||||
## 联系我们
|
||||
|
||||
如有问题或建议，请提交 Issue 或联系项目维护者。
|
||||
Reference in New Issue
Block a user