karword项目开发日志

该程序是一个卡片式树的综合多人辅助开发平台，内置功能，可视为迷你飞书

项目概述

开发一个面向团队的知识管理协作平台，核心功能包括：

卡片式文档管理系统
可视化图表编辑（流程图/结构图/甘特图）
实时团队协作
集成通讯功能

技术架构

前端技术栈

模块	技术选型	备注
框架	React 18 + TypeScript	使用Vite构建工具
状态管理	Redux Toolkit	配合RTK Query处理API
UI组件库	Ant Design 5.x	企业级UI组件
富文本编辑器	Tiptap	基于ProseMirror的现代编辑器
图表渲染	Mermaid + ECharts	Mermaid用于流程图/时序图
实时协作	Socket.IO Client	与后端WebSocket通信
拖拽交互	react-dnd	卡片和图表元素拖拽

后端技术栈

模块	技术选型	备注
主框架	Spring Boot 3.x	Java 17+
数据库	PostgreSQL 15	关系型数据库
ORM	Spring Data JPA	配合Hibernate
缓存	Redis 7	会话缓存和频繁访问数据
实时通讯	WebSocket (STOMP)	通过Spring Messaging实现
文件存储	MinIO	自托管对象存储
搜索	Elasticsearch 8.x	全文检索功能
安全	Spring Security + JWT	OAuth2.0备用方案

以上为明确使用的技术栈，本篇日志为第一部分，暨搭建Karwork项目的基础框架，包括Spring Boot后端和React前端。

整体过程可以视为
Spring Boot后端搭建—>React前端搭建—>前后端连接（本项目不提前连接）

Spring Boot后端搭建

1. 创建Spring Boot项目

打开IntelliJ IDEA，点击”New Project”
选择”Spring Initializr”
配置项目信息：
- Name: karwork-backend
- Location: 选择你的项目目录
- Type: Maven
- Language: Java
- Group: com.karwork
- Artifact: karwork-backend
- Package name: com.karwork
- Java: 选择17或更高版本

以上的是可选条目，告知详细操作过程

2. 添加依赖

选择以下依赖：

Spring Web
Spring Data JPA
PostgreSQL Driver
Lombok
Spring Security
Spring Boot DevTools

点击”Create”完成项目创建。

3. 配置数据库

数据库需要提前配置，注意以下字段的’password=yourpassword’和’username=postgres’字段更改，检查5432端口是否被占用

我会标记出所在项目的文件夹位置，帮助项目构建

在src/main/resources/application.properties中添加：

# 开发环境配置
spring.datasource.url=jdbc:postgresql://localhost:5432/karwork
spring.datasource.username=postgres
spring.datasource.password=yourpassword
spring.datasource.driver-class-name=org.postgresql.Driver

# JPA配置
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

# 开发时关闭安全验证
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration

4. 创建基础包结构

在src/main/java/com/karwork下创建以下包：

config
controller
service
repository
model
dto
exception
websocket

以上均为文件名，自行创建，也可以使用指令创建

5. 创建基础实体类

在model包中创建User.java：

package com.karwork.model;

import jakarta.persistence.*;
import lombok.Data;
import org.hibernate.annotations.GenericGenerator;

import java.time.LocalDateTime;
import java.util.UUID;

@Data
@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(generator = "UUID")
    @GenericGenerator(name = "UUID", strategy = "org.hibernate.id.UUIDGenerator")
    @Column(updatable = false, nullable = false)
    private UUID userId;

    @Column(nullable = false, unique = true)
    private String username;

    @Column(nullable = false, unique = true)
    private String email;

    @Column(nullable = false)
    private String passwordHash;

    @Column(nullable = false, updatable = false)
    private LocalDateTime createdAt = LocalDateTime.now();
}

6. 创建Repository接口

在repository包中创建UserRepository.java：

package com.karwork.repository;

import com.karwork.model.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.util.Optional;
import java.util.UUID;

@Repository
public interface UserRepository extends JpaRepository<User, UUID> {
    Optional<User> findByUsername(String username);
    Optional<User> findByEmail(String email);
}

7. 创建基础Controller

在controller包中创建AuthController.java：

package com.karwork.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/auth")
public class AuthController {
    
    @GetMapping("/status")
    public String status() {
        return "Auth service is running";
    }
}

8. 运行项目

确保PostgreSQL已安装并运行
创建名为karwork的数据库
右键点击KarworkBackendApplication.java -> Run
访问http://localhost:8080/api/auth/status测试

React前端搭建

1. 创建React项目

运行命令：

1
2
3

npm create vite@latest karwork-frontend -- --template react-ts
cd karwork-frontend
npm install

2. 安装必要依赖

1
2

npm install @reduxjs/toolkit react-redux axios antd @ant-design/icons react-router-dom socket.io-client react-dnd react-dnd-html5-backend
npm install --save-dev @types/react @types/react-dom @types/react-router-dom

3. 配置项目结构

按照以下结构组织你的前端项目：

karwork-frontend/
├── public/
├── src/
│   ├── api/
│   ├── assets/
│   ├── components/
│   ├── features/
│   │   ├── auth/
│   │   ├── editor/
│   │   ├── diagram/
│   │   └── chat/
│   ├── hooks/
│   ├── stores/
│   ├── types/
│   ├── utils/
│   ├── App.tsx
│   ├── main.tsx
│   └── vite-env.d.ts

4. 创建基础Redux Store

在stores文件夹中创建store.ts：

import { configureStore } from '@reduxjs/toolkit';
import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux';

export const store = configureStore({
  reducer: {
    // 这里添加你的reducer
  },
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

export const useAppDispatch = () => useDispatch<AppDispatch>();
export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;

5. 创建基础布局

在components文件夹中创建Layout.tsx：

import { Layout as AntdLayout, Menu } from 'antd';
import { Outlet } from 'react-router-dom';

const { Header, Content } = AntdLayout;

export const Layout = () => {
  return (
    <AntdLayout style={{ minHeight: '100vh' }}>
      <Header>
        <div style={{ color: 'white' }}>Karwork</div>
      </Header>
      <Content style={{ padding: '24px' }}>
        <Outlet />
      </Content>
    </AntdLayout>
  );
};

6. 配置路由

修改App.tsx：

import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { Layout } from './components/Layout';
import { HomePage } from './features/auth/HomePage';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Layout />}>
          <Route index element={<HomePage />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
}

export default App;

7. 创建首页

在features/auth中创建HomePage.tsx：

export const HomePage = () => {
  return (
    <div>
      <h1>Welcome to Karwork</h1>
    </div>
  );
};

8. 配置API客户端

在api文件夹中创建client.ts：

import axios from 'axios';

export const apiClient = axios.create({
  baseURL: 'http://localhost:8080/api',
  withCredentials: true,
});

9. 运行前端项目

1	npm run dev

访问http://localhost:5173测试

到此为止基本已完成前后端的框架构建，以下是可能遇见的问题

1.时刻校验准备项目结构清单

这是项目标准化的重要工作，这个项目本身就是在简化这个过程，一定时刻确认项目结构清单

2.清理依赖，用到的时候再启动

<dependencies>
    <!-- Web核心 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- 数据访问（保留JPA或MyBatis任选其一） -->
    <!-- 选项1：使用JPA -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    
    <!-- 选项2：使用MyBatis（注释掉JPA） -->
    <!--
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>3.0.4</version>
    </dependency>
    -->

    <!-- 数据库驱动（只保留你实际使用的） -->
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!-- 如果使用MySQL，注释掉PostgreSQL -->
    <!--
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    -->

    <!-- 开发工具 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>

    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <!-- 测试 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

防止xml文件污染，适当截取

3.确认包扫描路径找到，必要时请使用标签标注

所遇到的问题，我之后会单独拉一个页面来展示