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. 克隆项目（如果从远程仓库）

git clone <repository-url>
cd qiangdanxitong

2. 项目结构说明

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

💾 数据库配置

1. 创建数据库

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

# 方式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. 验证数据库

-- 登录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：

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：使用命令行启动

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. 安装依赖

cd frontend

# 使用npm
npm install

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

# 或使用yarn
yarn install

2. 启动开发服务器

# 使用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 规范：

# 功能开发
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

# 格式化代码
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:

<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镜像源

# 临时使用淘宝镜像
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. 配置回调地址和权限

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 已启动：

# 启动 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. 早上：拉取最新代码

   git checkout develop
   git pull origin develop
   

2. 开发：创建功能分支

   git checkout -b feature/task-hall
   # 编码...
   git add .
   git commit -m "feat: 完成任务大厅页面"
   

3. 提交：推送到远程并创建PR

   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

---

祝开发愉快！ 🎉