# 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 http://218.84.152.14:65001/huxunan/gitpm.git
cd gitpm

# 修改配置文件
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 或联系项目维护者。