qiangdanxitong/DEVELOPMENT_GUIDE.md

# DesignHub 开发启动指南

## 📋 目录

- [环境准备](#环境准备)
- [项目初始化](#项目初始化)
- [数据库配置](#数据库配置)
- [后端启动](#后端启动)
- [前端启动](#前端启动)
- [开发规范](#开发规范)
- [常见问题](#常见问题)

## 🛠️ 环境准备

### 必备软件

确保您的开发环境已安装以下软件：

| 软件 | 版本要求 | 说明 |
|------|---------|------|
| Java | >= 17 | 后端运行环境 |
| Node.js | >= 18.0 | 前端运行环境 |
| MySQL | >= 8.0 | 数据库 |
| Redis | >= 7.0 | 缓存服务（可选，开发阶段可不启用） |
| Maven | >= 3.8 | Java构建工具 |
| Git | 最新版本 | 版本控制 |

### 推荐开发工具

- **后端开发**: IntelliJ IDEA / Eclipse
- **前端开发**: VS Code
- **数据库管理**: Navicat / DBeaver / MySQL Workbench
- **API测试**: Postman / Apifox
- **Redis管理**: RedisInsight / Another Redis Desktop Manager

## 🚀 项目初始化

### 1. 克隆项目（如果从远程仓库）

```bash
git clone <repository-url>
cd qiangdanxitong
```

### 2. 项目结构说明

```
qiangdanxitong/
├── frontend/          # 前端项目（Vue 3）
├── backend/           # 后端项目（Spring Boot）
├── database/          # 数据库脚本
├── docs/              # 文档
├── PROJECT_REQUIREMENTS.md    # 需求文档
└── README.md         # 项目说明
```

## 💾 数据库配置

### 1. 创建数据库

使用 MySQL 客户端或管理工具执行以下命令：

```bash
# 方式1：使用命令行
mysql -u root -p < database/schema.sql
mysql -u root -p < database/init-data.sql

# 方式2：使用 MySQL 客户端
mysql -u root -p
source /Users/lanmu/Desktop/qiangdanxitong/database/schema.sql;
source /Users/lanmu/Desktop/qiangdanxitong/database/init-data.sql;
```

### 2. 验证数据库

```sql
-- 登录MySQL
mysql -u root -p

-- 切换到designhub数据库
USE designhub;

-- 查看所有表
SHOW TABLES;

-- 查看部门数据
SELECT * FROM sys_dept;

-- 查看任务类型
SELECT * FROM task_type;
```

### 3. 配置数据库连接

编辑 `backend/src/main/resources/application-dev.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/designhub?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 你的MySQL密码
```

## 🔧 后端启动

### 方式1：使用IDE启动（推荐）

1. 用 IntelliJ IDEA 打开 `backend` 目录
2. 等待 Maven 自动下载依赖
3. 找到 `DesignHubApplication.java` 主类
4. 右键 -> Run 'DesignHubApplication'

### 方式2：使用命令行启动

```bash
cd backend

# 首次启动需要先编译
mvn clean install

# 启动应用
mvn spring-boot:run

# 或者直接运行jar包
java -jar target/designhub-backend-1.0.0.jar
```

### 验证后端启动

启动成功后，访问以下地址：

- **API文档**: http://localhost:8080/api/doc.html
- **健康检查**: http://localhost:8080/api/actuator/health（如果配置了actuator）

控制台应该输出：

```
╔═══════════════════════════════════════════════════════╗
║                                                       ║
║       🎨 DesignHub Backend Service Started 🎨        ║
║                                                       ║
║   Port: 8080                                          ║
║   Swagger UI: http://localhost:8080/api/doc.html     ║
║   Version: 1.0.0                                      ║
║                                                       ║
╚═══════════════════════════════════════════════════════╝
```

## 🎨 前端启动

### 1. 安装依赖

```bash
cd frontend

# 使用npm
npm install

# 或使用pnpm（推荐，更快）
pnpm install

# 或使用yarn
yarn install
```

### 2. 启动开发服务器

```bash
# 使用npm
npm run dev

# 使用pnpm
pnpm dev

# 使用yarn
yarn dev
```

### 3. 访问前端

浏览器自动打开或手动访问：

- **开发地址**: http://localhost:3000

控制台应该输出：

```
VITE v5.0.0  ready in 500 ms

➜  Local:   http://localhost:3000/
➜  Network: use --host to expose
➜  press h + enter to show help
```

## 📝 开发规范

### Git提交规范

使用 Conventional Commits 规范：

```bash
# 功能开发
git commit -m "feat: 添加任务大厅页面"

# Bug修复
git commit -m "fix: 修复任务列表显示问题"

# 文档更新
git commit -m "docs: 更新README文档"

# 样式调整
git commit -m "style: 调整按钮样式"

# 代码重构
git commit -m "refactor: 重构任务服务层代码"

# 性能优化
git commit -m "perf: 优化数据库查询性能"

# 测试相关
git commit -m "test: 添加任务模块单元测试"
```

### 分支策略

```
main/master    -> 生产环境分支
develop        -> 开发分支
feature/*      -> 功能分支
hotfix/*       -> 紧急修复分支
release/*      -> 发布分支
```

### 代码风格

#### 前端（TypeScript/Vue）

- 使用 ESLint + Prettier 格式化代码
- 组件命名使用 PascalCase
- 文件命名使用 kebab-case
- 使用 Composition API

```bash
# 格式化代码
npm run format

# 检查代码
npm run lint
```

#### 后端（Java/Spring Boot）

- 遵循 阿里巴巴 Java 开发手册
- 类名使用 PascalCase
- 方法名使用 camelCase
- 常量使用 UPPER_SNAKE_CASE

## 🔍 常见问题

### Q1: 后端启动失败，提示数据库连接错误

**A**: 检查以下几点：
1. MySQL 是否已启动
2. 数据库密码是否正确配置在 `application-dev.yml`
3. 数据库 `designhub` 是否已创建
4. 数据库端口是否为 3306

### Q2: 前端启动后页面空白

**A**: 
1. 检查浏览器控制台是否有报错
2. 确认后端API是否正常运行（访问 http://localhost:8080/api/doc.html）
3. 检查前端代理配置（vite.config.ts）

### Q3: Maven 依赖下载缓慢

**A**: 配置国内Maven镜像（阿里云）

编辑 `~/.m2/settings.xml`:

```xml
<mirror>
  <id>aliyun</id>
  <mirrorOf>central</mirrorOf>
  <name>Aliyun Maven Mirror</name>
  <url>https://maven.aliyun.com/repository/public</url>
</mirror>
```

### Q4: npm 安装依赖失败

**A**: 切换npm镜像源

```bash
# 临时使用淘宝镜像
npm install --registry=https://registry.npmmirror.com

# 永久设置
npm config set registry https://registry.npmmirror.com

# 使用 nrm 管理镜像源（推荐）
npm install -g nrm
nrm use taobao
```

### Q5: 钉钉登录如何配置

**A**: 
1. 登录钉钉开放平台 https://open.dingtalk.com
2. 创建应用，获取 AppKey 和 AppSecret
3. 配置到 `application.yml` 的 `dingtalk` 部分
4. 配置回调地址和权限

```yaml
dingtalk:
  app-key: your-app-key
  app-secret: your-app-secret
  agent-id: your-agent-id
  corp-id: your-corp-id
```

### Q6: Redis 连接失败

**A**: 开发阶段可以暂时禁用 Redis

在 `application-dev.yml` 中注释掉 Redis 配置，或确保 Redis 已启动：

```bash
# 启动 Redis（Mac）
brew services start redis

# 启动 Redis（Linux）
redis-server

# 启动 Redis（Windows）
redis-server.exe

# 测试连接
redis-cli ping
# 应该返回 PONG
```

## 📚 下一步

### 开发优先级

1. ✅ **基础架构** - 已完成
   - 项目结构
   - 数据库设计
   - 前后端框架搭建

2. 🔄 **核心功能开发** - 进行中
   - [ ] 用户认证模块（Casdoor + 钉钉登录）
   - [ ] 任务管理模块
   - [ ] 积分管理模块
   - [ ] 通知系统

3. ⏳ **进阶功能** - 待开发
   - [ ] 激励系统
   - [ ] 数据分析
   - [ ] 管理后台

### 推荐开发顺序

```
1. 用户认证 → 2. 组织架构 → 3. 任务发起 → 4. 任务大厅 → 
5. 我的任务 → 6. 设计师大厅 → 7. 积分系统 → 8. 数据分析 → 
9. 激励系统 → 10. 系统配置 → 11. 通知系统
```

## 🤝 团队协作

### 每日开发流程

1. **早上**：拉取最新代码
   ```bash
   git checkout develop
   git pull origin develop
   ```

2. **开发**：创建功能分支
   ```bash
   git checkout -b feature/task-hall
   # 编码...
   git add .
   git commit -m "feat: 完成任务大厅页面"
   ```

3. **提交**：推送到远程并创建PR
   ```bash
   git push origin feature/task-hall
   # 在 GitLab/GitHub 创建 Merge Request / Pull Request
   ```

4. **审查**：代码审查通过后合并到 develop

### 代码审查清单

- [ ] 代码符合规范
- [ ] 没有明显的 bug
- [ ] 功能完整
- [ ] 已添加必要的注释
- [ ] 通过单元测试
- [ ] UI 符合 OpenAI 设计规范

## 📞 技术支持

如有问题，请联系：

- **技术负责人**: [姓名] - [邮箱]
- **项目文档**: PROJECT_REQUIREMENTS.md
- **API文档**: http://localhost:8080/api/doc.html

---

**祝开发愉快！** 🎉