393 lines
8.3 KiB
Markdown
393 lines
8.3 KiB
Markdown
# 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. **克隆项目**
|
||
```bash
|
||
cd openclaw-backend
|
||
```
|
||
|
||
2. **初始化数据库**
|
||
```bash
|
||
mysql -u root -p < src/main/resources/db/init.sql
|
||
```
|
||
|
||
3. **配置应用**
|
||
编辑 `src/main/resources/application.yml`:
|
||
```yaml
|
||
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. **启动应用**
|
||
```bash
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
应用将在 `http://localhost:8080` 启动
|
||
|
||
## 📚 文档指南
|
||
|
||
### 📖 主要文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [DEVELOPMENT_SUMMARY.md](./DEVELOPMENT_SUMMARY.md) | 项目完整总结，包含所有模块详情 |
|
||
| [DEVELOPMENT_PROGRESS.md](./DEVELOPMENT_PROGRESS.md) | 开发进度表，详细的完成情况统计 |
|
||
| [QUICK_START.md](./QUICK_START.md) | 快速参考指南，API 速查表 |
|
||
| [API_EXAMPLES.md](./API_EXAMPLES.md) | API 测试示例，包含 curl 命令 |
|
||
|
||
### 📌 快速导航
|
||
|
||
- **想快速了解项目？** → 阅读 [DEVELOPMENT_SUMMARY.md](./DEVELOPMENT_SUMMARY.md)
|
||
- **想查看开发进度？** → 查看 [DEVELOPMENT_PROGRESS.md](./DEVELOPMENT_PROGRESS.md)
|
||
- **想快速启动项目？** → 参考 [QUICK_START.md](./QUICK_START.md)
|
||
- **想测试 API？** → 使用 [API_EXAMPLES.md](./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 响应格式
|
||
|
||
### 成功响应
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": { ... },
|
||
"timestamp": 1710604800000
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
```json
|
||
{
|
||
"code": 1001,
|
||
"message": "用户不存在",
|
||
"data": null,
|
||
"timestamp": 1710604800000
|
||
}
|
||
```
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 添加新的 API 端点
|
||
|
||
按照分层架构：
|
||
|
||
1. **定义 Entity**
|
||
```java
|
||
@Data
|
||
@TableName("table_name")
|
||
public class MyEntity extends BaseEntity {
|
||
// 字段定义
|
||
}
|
||
```
|
||
|
||
2. **定义 Repository**
|
||
```java
|
||
public interface MyRepository extends BaseMapper<MyEntity> {
|
||
// 自定义查询方法
|
||
}
|
||
```
|
||
|
||
3. **定义 Service**
|
||
```java
|
||
public interface MyService {
|
||
// 业务方法
|
||
}
|
||
|
||
@Service
|
||
@RequiredArgsConstructor
|
||
public class MyServiceImpl implements MyService {
|
||
// 实现
|
||
}
|
||
```
|
||
|
||
4. **定义 Controller**
|
||
```java
|
||
@RestController
|
||
@RequestMapping("/api/v1/my")
|
||
@RequiredArgsConstructor
|
||
public class MyController {
|
||
// API 端点
|
||
}
|
||
```
|
||
|
||
### 处理业务异常
|
||
|
||
```java
|
||
throw new BusinessException(ErrorCode.USER_NOT_FOUND);
|
||
```
|
||
|
||
### 获取当前用户
|
||
|
||
```java
|
||
Long userId = UserContext.getUserId();
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
### 使用 curl 测试 API
|
||
|
||
```bash
|
||
# 用户登录
|
||
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](./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 官方文档](https://spring.io/projects/spring-boot)
|
||
- [MyBatis Plus 官方文档](https://baomidou.com/)
|
||
- [MySQL 官方文档](https://dev.mysql.com/doc/)
|
||
- [Redis 官方文档](https://redis.io/documentation)
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 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
|