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：

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 部署

# 克隆项目
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

手动部署

# 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

开发指南

项目结构

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 或联系项目维护者。