number/openclaw-backend/openclaw-backend/README.md

OpenClaw 后端系统

OpenClaw 是一个 Skill 交易平台的后端系统，采用 Spring Boot 3.x + MyBatis Plus 的单体架构。

📋 项目概览

• 项目名称: OpenClaw Backend
• 版本: v1.0.0
• 开发周期: 2026-03-16 至 2026-03-17
• 技术栈: Java 17 + Spring Boot 3.2 + MyBatis Plus 3.5 + MySQL 8.0 + Redis 7.x
• 项目规模: 86 个 Java 文件，7 大核心模块，15 个数据库表

✨ 核心特性

✅ 完整的用户认证与授权系统

• JWT Token 认证
• Spring Security 集成
• 自动拦截器验证
• Token 黑名单机制

✅ 7 大核心业务模块

• 用户服务 (User)
• Skill 服务 (Skill)
• 积分服务 (Points)
• 订单服务 (Order)
• 支付服务 (Payment)
• 邀请服务 (Invite)
• 基础设施层

✅ 完整的数据设计

• 15 个数据库表
• 完整的关系设计
• 软删除机制
• 事务管理

✅ 全局异常处理

• 统一响应格式
• 30+ 错误码定义
• 业务异常处理

✅ 积分系统

• 积分冻结/解冻机制
• 多种积分来源
• 积分流水记录

✅ 邀请机制

• 邀请码生成
• 邀请验证
• 双方积分奖励

✅ 订单与支付

• 订单生命周期管理
• 积分抵扣
• 退款流程
• 支付回调接口

🚀 快速开始

环境要求

• Java 17+
• MySQL 8.0+
• Redis 7.x+
• Maven 3.6+

安装步骤

1. 克隆项目

cd openclaw-backend

2. 初始化数据库

mysql -u root -p < src/main/resources/db/init.sql

3. 配置应用 编辑 src/main/resources/application.yml:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/openclaw
    username: root
    password: root
  redis:
    host: localhost
    port: 6379

jwt:
  secret: change-this-to-a-256-bit-random-secret-key-for-production
  expire-ms: 86400000

4. 启动应用

mvn spring-boot:run

应用将在 http://localhost:8080 启动

📚 文档指南

📖 主要文档

文档	说明
DEVELOPMENT_SUMMARY.md	项目完整总结，包含所有模块详情
DEVELOPMENT_PROGRESS.md	开发进度表，详细的完成情况统计
QUICK_START.md	快速参考指南，API 速查表
API_EXAMPLES.md	API 测试示例，包含 curl 命令

📌 快速导航

• 想快速了解项目？ → 阅读 DEVELOPMENT_SUMMARY.md
• 想查看开发进度？ → 查看 DEVELOPMENT_PROGRESS.md
• 想快速启动项目？ → 参考 QUICK_START.md
• 想测试 API？ → 使用 API_EXAMPLES.md 中的示例

🏗️ 项目结构

openclaw-backend/
├── src/main/java/com/openclaw/
│   ├── controller/          # 7 个 Controller
│   ├── service/             # 7 个 Service 接口 + 7 个实现
│   ├── repository/          # 13 个 Repository
│   ├── entity/              # 13 个 Entity
│   ├── dto/                 # 8 个 DTO
│   ├── vo/                  # 10 个 VO
│   ├── config/              # 6 个配置类
│   ├── exception/           # 异常处理
│   ├── interceptor/         # 拦截器
│   ├── util/                # 工具类
│   ├── constant/            # 常量定义
│   └── OpenclawApplication.java
├── src/main/resources/
│   ├── application.yml      # 应用配置
│   ├── db/
│   │   └── init.sql         # 数据库初始化脚本
│   └── logback-spring.xml   # 日志配置
├── pom.xml                  # Maven 配置
├── README.md                # 本文件
├── DEVELOPMENT_SUMMARY.md   # 项目总结
├── DEVELOPMENT_PROGRESS.md  # 开发进度表
├── QUICK_START.md           # 快速参考
└── API_EXAMPLES.md          # API 示例

📊 模块概览

1. 用户服务 (User)

• 用户注册、登录、登出
• 个人信息管理
• 密码修改和重置
• 短信验证码

API 端点: 8 个

2. Skill 服务 (Skill)

• Skill 列表查询（支持分页/筛选/排序）
• Skill 详情查询
• Skill 上传
• Skill 评价

API 端点: 4 个

3. 积分服务 (Points)

• 积分余额查询
• 积分流水查询
• 每日签到
• 积分冻结/解冻

API 端点: 3 个

4. 订单服务 (Order)

• 订单创建
• 订单查询
• 订单支付
• 订单取消
• 退款申请

API 端点: 5 个

5. 支付服务 (Payment)

• 充值发起
• 支付记录查询
• 充值状态查询
• 支付回调处理

API 端点: 4 个

6. 邀请服务 (Invite)

• 邀请码获取
• 邀请码绑定
• 邀请记录查询
• 邀请统计

API 端点: 4 个

🔐 认证方式

所有需要认证的 API 都需要在请求头中添加 JWT Token:

Authorization: Bearer <token>

获取 Token

1. 调用 /api/v1/users/login 获取 Token
2. 在响应中获取 data.token
3. 在后续请求的 Authorization 头中使用

📝 API 响应格式

成功响应

{
  "code": 200,
  "message": "success",
  "data": { ... },
  "timestamp": 1710604800000
}

错误响应

{
  "code": 1001,
  "message": "用户不存在",
  "data": null,
  "timestamp": 1710604800000
}

🛠️ 开发指南

添加新的 API 端点

按照分层架构：

1. 定义 Entity

@Data
@TableName("table_name")
public class MyEntity extends BaseEntity {
    // 字段定义
}

2. 定义 Repository

public interface MyRepository extends BaseMapper<MyEntity> {
    // 自定义查询方法
}

3. 定义 Service

public interface MyService {
    // 业务方法
}

@Service
@RequiredArgsConstructor
public class MyServiceImpl implements MyService {
    // 实现
}

4. 定义 Controller

@RestController
@RequestMapping("/api/v1/my")
@RequiredArgsConstructor
public class MyController {
    // API 端点
}

处理业务异常

throw new BusinessException(ErrorCode.USER_NOT_FOUND);

获取当前用户

Long userId = UserContext.getUserId();

🧪 测试

使用 curl 测试 API

# 用户登录
curl -X POST http://localhost:8080/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "password": "password123"
  }'

# 获取个人信息
curl -X GET http://localhost:8080/api/v1/users/profile \
  -H "Authorization: Bearer <token>"

更多示例请参考 API_EXAMPLES.md

📦 依赖管理

主要依赖版本：

• Spring Boot: 3.2.0
• MyBatis Plus: 3.5.7
• MySQL Connector: 8.x
• Redis: Lettuce
• JWT: 0.11.5
• Lombok: Latest

🚨 生产环境检查清单

• 修改 JWT secret key
• 修改数据库密码
• 修改 Redis 密码
• 配置 HTTPS
• 启用 SQL 日志
• 配置日志输出路径
• 集成支付 SDK（微信、支付宝）
• 配置短信服务
• 配置文件存储（腾讯云 COS）
• 配置监控告警
• 进行压力测试
• 进行安全审计

📞 常见问题

Q: 如何修改数据库连接？

A: 编辑 application.yml 中的 spring.datasource 配置

Q: 如何修改 JWT 过期时间？

A: 编辑 application.yml 中的 jwt.expire-ms 配置

Q: 如何添加新的积分规则？

A: 在 points_rules 表中插入新记录

Q: 如何处理支付回调？

A: 实现 PaymentService 中的回调方法

🔗 相关资源

• Spring Boot 官方文档
• MyBatis Plus 官方文档
• MySQL 官方文档
• Redis 官方文档

📄 许可证

本项目采用 MIT 许可证

👥 贡献者

• AI Assistant

📅 更新日志

v1.0.0 (2026-03-17)

• ✅ 完成 7 大核心模块开发
• ✅ 完成 86 个 Java 文件
• ✅ 完成 15 个数据库表设计
• ✅ 完成全局异常处理
• ✅ 完成 JWT 认证系统
• ✅ 完成积分系统
• ✅ 完成邀请系统
• ✅ 完成订单与支付流程

📞 技术支持

如有问题，请检查：

1. 数据库连接是否正常
2. Redis 连接是否正常
3. 应用日志是否有错误
4. 请求参数是否正确
5. Token 是否过期

---

项目版本: v1.0.0 完成日期: 2026-03-17 开发者: AI Assistant 最后更新: 2026-03-17