961bae1bd8
- Add push_to_gitea.sh script for manual Git push instructions - Update README.md with correct repository URL - Include deployment and troubleshooting guides
272 lines
6.7 KiB
Markdown
272 lines
6.7 KiB
Markdown
# 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 或联系项目维护者。 |