task_track/DEVELOPMENT.md

开发指南

项目启动

1. 环境准备

确保已安装以下环境：

• Node.js >= 16
• Go >= 1.21
• MySQL >= 8.0

2. 快速安装

运行安装脚本：

Windows:

install.bat

Linux/macOS:

chmod +x install.sh
./install.sh

3. 数据库配置

创建数据库：

CREATE DATABASE task_track CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

修改 backend/config.yaml：

database:
  host: "localhost"
  port: "3306"
  username: "your_username"  # 替换为你的用户名
  password: "your_password"  # 替换为你的密码
  database: "task_track"

4. 启动服务

启动后端（在 backend 目录下）:

cd backend
go run main.go

启动前端（在 frontend 目录下）:

cd frontend
npm run dev

5. 访问应用

• 前端：http://localhost:5173
• 后端API：http://localhost:8080

开发规范

前端开发

目录结构

src/
├── components/     # 公共组件
├── views/          # 页面组件
├── router/         # 路由配置
├── store/          # 状态管理
├── api/            # API接口
├── utils/          # 工具函数
└── styles/         # 样式文件

命名规范

• 组件文件：PascalCase（如 UserList.vue）
• 页面文件：PascalCase（如 Dashboard.vue）
• 工具函数：camelCase（如 formatDate）
• 常量：UPPER_SNAKE_CASE（如 API_BASE_URL）

组件开发规范

1. 使用 <script setup> 语法
2. 使用 TypeScript
3. 使用 Composition API
4. 组件必须有 props 类型定义
5. 使用 Element Plus 组件库

状态管理

• 使用 Vuex 4.x
• 按模块组织 store
• 使用 TypeScript 类型

后端开发

目录结构

backend/
├── internal/
│   ├── config/     # 配置管理
│   ├── handler/    # 请求处理器
│   ├── middleware/ # 中间件
│   └── router/     # 路由配置
├── model/          # 数据模型
├── pkg/            # 公共包
└── main.go         # 入口文件

命名规范

• 包名：小写（如 handler）
• 文件名：小写下划线（如 user_handler.go）
• 函数名：PascalCase（如 GetUser）
• 变量名：camelCase（如 userID）

API 设计规范

1. 使用 RESTful API 设计
2. 统一的响应格式
3. 使用 HTTP 状态码
4. 使用 JWT 认证
5. 参数验证

响应格式

{
  "code": 200,
  "message": "Success",
  "data": {}
}

数据库设计

1. 使用 GORM ORM
2. 遵循数据库命名规范
3. 添加必要的索引
4. 使用软删除

API 文档

认证接口

登录

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password"
}

注册

POST /api/auth/register
Content-Type: application/json

{
  "username": "user",
  "email": "user@example.com",
  "password": "password",
  "real_name": "用户姓名"
}

任务接口

获取任务列表

GET /api/tasks?page=1&size=20&status=pending
Authorization: Bearer <token>

创建任务

POST /api/tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "任务标题",
  "description": "任务描述",
  "priority": "high",
  "assignee_id": 1,
  "end_time": "2025-07-10 18:00:00"
}

常见问题

1. 依赖安装失败

• 检查网络连接
• 使用国内镜像源
• 清除缓存重新安装

2. 数据库连接失败

• 检查数据库服务是否启动
• 验证连接参数
• 检查防火墙设置

3. 跨域问题

• 后端已配置 CORS
• 检查前端代理配置

4. JWT Token 过期

• 实现 Token 刷新机制
• 检查 Token 有效期设置

部署指南

开发环境部署

1. 按照上述步骤启动
2. 使用开发配置

生产环境部署

1. 构建前端：npm run build
2. 编译后端：go build -o task-track main.go
3. 配置 Nginx
4. 使用 PM2 或 systemd 管理进程
5. 配置 SSL 证书

Docker 部署

# 前端 Dockerfile
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=0 /app/dist /usr/share/nginx/html

# 后端 Dockerfile
FROM golang:1.21-alpine
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o main .
EXPOSE 8080
CMD ["./main"]

贡献指南

1. Fork 项目
2. 创建功能分支：git checkout -b feature/new-feature
3. 提交更改：git commit -am 'Add new feature'
4. 推送分支：git push origin feature/new-feature
5. 创建 Pull Request

许可证

MIT License