deepdata: core product code (backend, frontend, runtime, deepflow module)

2026-08-30 19:23:38 +08:00
commit bd3db30be9
1405 changed files with 271727 additions and 0 deletions
@@ -0,0 +1,144 @@
+# 共享库
+
+## 概述
+
+共享库包含所有后端服务共用的代码和工具，包括领域构建块、异常处理、JWT 工具等。
+
+## 架构
+
+```
+backend/shared/
+├── domain-common/          # DDD 构建块、异常处理
+│   └── src/main/java/com/deepdata/common/
+│       ├── infrastructure/exception/  # BusinessException, ErrorCode
+│       ├── setting/                   # 系统参数、模型配置
+│       └── domain/                    # Base entities, repositories
+└── security-common/        # JWT 工具、认证辅助
+    └── src/main/java/com/deepdata/security/
+```
+
+## 库
+
+### 1. domain-common
+
+#### BusinessException
+统一的业务异常处理机制：
+
+```java
+// 抛出业务异常
+throw BusinessException.of(ErrorCode.DATASET_NOT_FOUND)
+    .withDetail("dataset_id", datasetId);
+
+// 带上下文的异常
+throw BusinessException.of(ErrorCode.VALIDATION_FAILED)
+    .withDetail("field", "email")
+    .withDetail("reason", "Invalid format");
+```
+
+#### ErrorCode
+错误码枚举接口：
+
+```java
+public interface ErrorCode {
+    String getCode();
+    String getMessage();
+    HttpStatus getHttpStatus();
+}
+
+// 示例
+public enum CommonErrorCode implements ErrorCode {
+    SUCCESS("0000", "Success", HttpStatus.OK),
+    DATABASE_NOT_FOUND("4001", "Database not found", HttpStatus.NOT_FOUND);
+}
+```
+
+#### BaseEntity
+所有实体的基类，包含审计字段：
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class BaseEntity<T> implements Serializable {
+    @TableId(type = IdType.ASSIGN_ID)
+    private String id;
+    
+    @TableField(fill = FieldFill.INSERT)
+    private LocalDateTime createdAt;
+    
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private LocalDateTime updatedAt;
+    
+    @TableField(fill = FieldFill.INSERT)
+    private String createdBy;
+    
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private String updatedBy;
+}
+```
+
+### 2. security-common
+
+#### JWT 工具
+JWT Token 生成和验证：
+
+```java
+// 生成 Token
+String token = JwtUtil.generateToken(userId, secret, expiration);
+
+// 验证 Token
+Claims claims = JwtUtil.validateToken(token, secret);
+String userId = claims.getSubject();
+```
+
+## 使用
+
+### 在服务中使用共享库
+
+#### Maven 依赖
+```xml
+<dependency>
+    <groupId>com.deepdata</groupId>
+    <artifactId>domain-common</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+</dependency>
+<dependency>
+    <groupId>com.deepdata</groupId>
+    <artifactId>security-common</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+</dependency>
+```
+
+#### 使用 BusinessException
+```java
+@RestController
+@RequiredArgsConstructor
+public class DatasetController {
+    
+    public ResponseEntity<DatasetResponse> getDataset(String id) {
+        Dataset dataset = datasetService.findById(id);
+        if (dataset == null) {
+            throw BusinessException.of(ErrorCode.DATASET_NOT_FOUND);
+        }
+        return ResponseEntity.ok(DatasetResponse.from(dataset));
+    }
+}
+```
+
+## 快速开始
+
+### 构建共享库
+```bash
+cd backend
+mvn clean install
+```
+
+### 在服务中使用
+共享库会自动被所有后端服务继承。
+
+## 文档
+
+- [AGENTS.md](./AGENTS.md)
+
+## 相关链接
+
+- [后端 README](../README.md)