# OpenClaw Skills 后端Java架构设计 - 单体架构

## 一、架构概览

### 1.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                    前端应用层                                    │
│              Web / 小程序 / App                                  │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│                  单体应用 (Spring Boot)                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Controller 层 (API接口)                     │   │
│  │  UserController  SkillController  OrderController ...   │   │
│  └─────────────────────────────────────────────────────────┘   │
│                          ↓                                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Service 层 (业务逻辑)                       │   │
│  │  UserService  SkillService  PointsService ...           │   │
│  └─────────────────────────────────────────────────────────┘   │
│                          ↓                                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Repository 层 (数据访问)                    │   │
│  │  UserRepository  SkillRepository  OrderRepository ...   │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│                  基础设施层                                      │
├─────────────────────────────────────────────────────────────────┤
│  MySQL 8.0  │  Redis 7.x  │  RabbitMQ  │  Elasticsearch       │
└─────────────────────────────────────────────────────────────────┘
```

### 1.2 技术栈

| 层级 | 技术选型 | 说明 |
|------|--------|------|
| **框架** | Spring Boot 3.x | Web框架 |
| **ORM** | MyBatis Plus | 数据访问 |
| **数据库** | MySQL 8.0 | 主数据存储 |
| **缓存** | Redis 7.x | 会话、缓存 |
| **搜索** | Elasticsearch 8.x | Skill搜索 |
| **消息队列** | RabbitMQ 3.x | 异步处理 |
| **认证** | JWT + Spring Security | 用户认证 |
| **文件存储** | 七牛云 / 阿里云OSS | 文件上传 |
| **支付** | 微信支付SDK / 支付宝SDK | 支付集成 |
| **部署** | Docker | 容器化 |

## 二、项目结构

```
openclaw-backend/
├── src/main/java/com/openclaw/
│   ├── controller/              # 控制层
│   │   ├── UserController.java
│   │   ├── SkillController.java
│   │   ├── OrderController.java
│   │   ├── PointsController.java
│   │   ├── PaymentController.java
│   │   └── InviteController.java
│   │
│   ├── service/                 # 业务层
│   │   ├── UserService.java
│   │   ├── SkillService.java
│   │   ├── OrderService.java
│   │   ├── PointsService.java
│   │   ├── PaymentService.java
│   │   ├── InviteService.java
│   │   └── impl/
│   │       ├── UserServiceImpl.java
│   │       ├── SkillServiceImpl.java
│   │       └── ...
│   │
│   ├── repository/              # 数据访问层
│   │   ├── UserRepository.java
│   │   ├── SkillRepository.java
│   │   ├── OrderRepository.java
│   │   ├── PointsRepository.java
│   │   └── ...
│   │
│   ├── entity/                  # 实体类
│   │   ├── User.java
│   │   ├── Skill.java
│   │   ├── Order.java
│   │   ├── UserPoints.java
│   │   └── ...
│   │
│   ├── dto/                     # 数据传输对象
│   │   ├── UserRegisterDTO.java
│   │   ├── SkillListDTO.java
│   │   ├── OrderCreateDTO.java
│   │   └── ...
│   │
│   ├── config/                  # 配置类
│   │   ├── SecurityConfig.java
│   │   ├── RedisConfig.java
│   │   ├── MybatisPlusConfig.java
│   │   └── ...
│   │
│   ├── exception/               # 异常处理
│   │   ├── BusinessException.java
│   │   ├── GlobalExceptionHandler.java
│   │   └── ...
│   │
│   ├── util/                    # 工具类
│   │   ├── JwtUtil.java
│   │   ├── EncryptUtil.java
│   │   ├── IdGenerator.java
│   │   └── ...
│   │
│   ├── constant/                # 常量
│   │   ├── ErrorCode.java
│   │   ├── PointsConstant.java
│   │   └── ...
│   │
│   ├── interceptor/             # 拦截器
│   │   └── AuthInterceptor.java
│   │
│   ├── listener/                # 消息监听
│   │   ├── OrderEventListener.java
│   │   ├── PaymentEventListener.java
│   │   └── ...
│   │
│   └── OpenclawApplication.java # 启动类
│
├── src/main/resources/
│   ├── application.yml          # 主配置
│   ├── application-dev.yml      # 开发环境
│   ├── application-prod.yml     # 生产环境
│   ├── db/
│   │   └── migration/
│   │       ├── V1__init_users.sql
│   │       ├── V2__init_skills.sql
│   │       ├── V3__init_orders.sql
│   │       └── ...
│   └── logback-spring.xml       # 日志配置
│
├── pom.xml                      # Maven配置
├── Dockerfile                   # Docker配置
├── docker-compose.yml           # 容器编排
└── README.md                    # 项目说明
```

## 三、核心模块设计

### 3.1 用户模块 (User Module)

**职责**：用户注册、登录、个人信息管理

**核心表**：
- `users` - 用户基本信息
- `user_profiles` - 用户详细资料
- `user_auth` - 第三方授权

**关键API**：
- POST /api/v1/users/register - 注册
- POST /api/v1/users/login - 登录
- GET /api/v1/users/profile - 获取个人信息
- PUT /api/v1/users/profile - 更新个人信息
- POST /api/v1/users/logout - 登出

### 3.2 Skill模块 (Skill Module)

**职责**：Skill管理、浏览、搜索、下载

**核心表**：
- `skills` - Skill基本信息
- `skill_categories` - 分类
- `skill_reviews` - 评价评论
- `skill_downloads` - 下载记录

**关键API**：
- GET /api/v1/skills - 列表
- GET /api/v1/skills/{id} - 详情
- POST /api/v1/skills - 上传Skill
- GET /api/v1/skills/search - 搜索
- POST /api/v1/skills/{id}/reviews - 发表评价

### 3.3 积分模块 (Points Module)

**职责**：积分获取、消耗、明细

**核心表**：
- `user_points` - 用户积分账户
- `points_records` - 积分流水
- `points_rules` - 积分规则

**关键API**：
- GET /api/v1/points/balance - 获取余额
- GET /api/v1/points/records - 积分明细
- POST /api/v1/points/sign-in - 签到
- POST /api/v1/points/consume - 消耗积分

### 3.4 订单模块 (Order Module)

**职责**：订单创建、支付、退款

**核心表**：
- `orders` - 订单主表
- `order_items` - 订单项
- `order_refunds` - 退款记录

**关键API**：
- POST /api/v1/orders - 创建订单
- GET /api/v1/orders/{id} - 订单详情
- POST /api/v1/orders/{id}/pay - 支付
- POST /api/v1/orders/{id}/refund - 申请退款

### 3.5 支付模块 (Payment Module)

**职责**：支付处理、充值

**核心表**：
- `recharge_orders` - 充值订单
- `payment_records` - 支付记录

**关键API**：
- POST /api/v1/payments/recharge - 发起充值
- POST /api/v1/payments/callback - 支付回调
- GET /api/v1/payments/records - 支付记录

### 3.6 邀请模块 (Invite Module)

**职责**：邀请码、邀请奖励

**核心表**：
- `invite_codes` - 邀请码
- `invite_records` - 邀请记录

**关键API**：
- POST /api/v1/invites/generate - 生成邀请码
- GET /api/v1/invites/records - 邀请记录

## 四、API响应格式

### 4.1 成功响应

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三"
  },
  "timestamp": 1710604800000
}
```

### 4.2 分页响应

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      { "id": 1, "name": "Skill1" },
      { "id": 2, "name": "Skill2" }
    ],
    "total": 100,
    "size": 10,
    "current": 1,
    "pages": 10
  },
  "timestamp": 1710604800000
}
```

### 4.3 错误响应

```json
{
  "code": 400,
  "message": "请求参数错误",
  "data": null,
  "timestamp": 1710604800000
}
```

### 4.4 错误码定义

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（需要登录） |
| 403 | 禁止访问（无权限） |
| 404 | 资源不存在 |
| 500 | 服务器错误 |
| 1001 | 用户不存在 |
| 1002 | 密码错误 |
| 1003 | 手机号已注册 |
| 2001 | Skill不存在 |
| 2002 | Skill已下架 |
| 3001 | 积分不足 |
| 3002 | 积分规则不存在 |
| 4001 | 订单不存在 |
| 4002 | 订单状态错误 |
| 5001 | 支付失败 |
| 5002 | 充值订单不存在 |

## 五、数据库设计

### 5.1 用户表

```sql
CREATE TABLE users (
  id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
  phone VARCHAR(20) UNIQUE NOT NULL COMMENT '手机号',
  password_hash VARCHAR(255) NOT NULL COMMENT '密码哈希',
  nickname VARCHAR(100) COMMENT '昵称',
  avatar_url VARCHAR(500) COMMENT '头像URL',
  status ENUM('active', 'inactive', 'banned') DEFAULT 'active' COMMENT '状态',
  member_level ENUM('normal', 'silver', 'gold', 'diamond') DEFAULT 'normal' COMMENT '会员等级',
  growth_value INT DEFAULT 0 COMMENT '成长值',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  deleted_at TIMESTAMP NULL COMMENT '删除时间',
  INDEX idx_phone (phone),
  INDEX idx_status (status),
  INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户表';
```

### 5.2 积分表

```sql
CREATE TABLE user_points (
  id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '积分ID',
  user_id BIGINT NOT NULL UNIQUE COMMENT '用户ID',
  available_points INT DEFAULT 0 COMMENT '可用积分',
  frozen_points INT DEFAULT 0 COMMENT '冻结积分',
  total_earned INT DEFAULT 0 COMMENT '累计获取',
  total_consumed INT DEFAULT 0 COMMENT '累计消耗',
  last_sign_in_date DATE COMMENT '最后签到日期',
  sign_in_streak INT DEFAULT 0 COMMENT '连续签到天数',
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  FOREIGN KEY (user_id) REFERENCES users(id),
  INDEX idx_user_id (user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户积分表';
```

### 5.3 积分流水表

```sql
CREATE TABLE points_records (
  id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '流水ID',
  user_id BIGINT NOT NULL COMMENT '用户ID',
  points_type ENUM('earn', 'consume') NOT NULL COMMENT '类型',
  source ENUM('register', 'sign_in', 'invite', 'join_community', 'recharge', 'skill_purchase', 'review', 'activity') NOT NULL COMMENT '来源',
  amount INT NOT NULL COMMENT '积分数量',
  description VARCHAR(255) COMMENT '描述',
  related_id BIGINT COMMENT '关联ID',
  related_type VARCHAR(50) COMMENT '关联类型',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  FOREIGN KEY (user_id) REFERENCES users(id),
  INDEX idx_user_id (user_id),
  INDEX idx_source (source),
  INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='积分流水表';
```

### 5.4 订单表

```sql
CREATE TABLE orders (
  id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '订单ID',
  order_no VARCHAR(50) NOT NULL UNIQUE COMMENT '订单号',
  user_id BIGINT NOT NULL COMMENT '用户ID',
  total_amount DECIMAL(10, 2) NOT NULL COMMENT '总金额',
  paid_amount DECIMAL(10, 2) DEFAULT 0 COMMENT '已支付金额',
  points_used INT DEFAULT 0 COMMENT '使用积分',
  status ENUM('pending', 'paid', 'completed', 'cancelled', 'refunding', 'refunded') DEFAULT 'pending' COMMENT '订单状态',
  payment_method ENUM('wechat', 'alipay', 'points', 'mixed') DEFAULT 'wechat' COMMENT '支付方式',
  remark VARCHAR(500) COMMENT '备注',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  paid_at TIMESTAMP NULL COMMENT '支付时间',
  FOREIGN KEY (user_id) REFERENCES users(id),
  INDEX idx_user_id (user_id),
  INDEX idx_status (status),
  INDEX idx_created_at (created_at),
  INDEX idx_order_no (order_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单表';
```

## 六、配置文件

### 6.1 application.yml

```yaml
spring:
  application:
    name: openclaw-backend
  
  datasource:
    url: jdbc:mysql://localhost:3306/openclaw?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=UTC
    username: root
    password: wang200314
    driver-class-name: com.mysql.cj.jdbc.Driver
  
  redis:
    host: localhost
    port: 6379
    password: 
    timeout: 10000ms
    jedis:
      pool:
        max-active: 8
        max-idle: 8
        min-idle: 0
  
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
  
  jackson:
    default-timezone: GMT+8
    date-format: yyyy-MM-dd HH:mm:ss

mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml
  type-aliases-package: com.openclaw.entity
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

server:
  port: 8080
  servlet:
    context-path: /
  compression:
    enabled: true
    min-response-size: 1024

logging:
  level:
    root: INFO
    com.openclaw: DEBUG
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/openclaw.log
    max-size: 10MB
    max-history: 30
```

## 七、开发流程

### 7.1 本地开发环境启动

```bash
# 1. 启动MySQL
docker run -d --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=root mysql:8.0

# 2. 启动Redis
docker run -d --name redis -p 6379:6379 redis:7-alpine

# 3. 启动RabbitMQ
docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management

# 4. 创建数据库
mysql -u root -p < init.sql

# 5. 启动应用
mvn spring-boot:run
```

### 7.2 代码提交规范

```
feat: 新增用户注册功能
fix: 修复积分计算错误
docs: 更新API文档
refactor: 重构订单服务
test: 添加支付测试用例
chore: 更新依赖版本
```

---

**文档版本**：v1.0  
**创建日期**：2026-03-16