# 模块间通信规范

## 🎯 设计原则

1. **松耦合** - 模块间通过 REST API 通信，禁止直接引用代码
2. **接口契约** - 通过 API 定义进行协作
3. **独立部署** - 每个模块可独立构建和部署
4. **版本管理** - API 支持版本控制

## 🔗 通信方式

### 1. 模块 → 框架（spring-ai）

```java
// 使用 FeignClient 调用框架服务
@FeignClient("rui-service-user")
public interface UserFeignClient {
    
    @GetMapping("/api/v1/user/{id}")
    Result<UserDTO> getUserById(@PathVariable Long id);
    
    @GetMapping("/api/v1/user/current")
    Result<UserDTO> getCurrentUser();
}
```

### 2. 模块 → 模块（如收银 → 支付）

```java
// 通过 FeignClient 调用其他业务模块
@FeignClient("rui-payment")
public interface PaymentFeignClient {
    
    @PostMapping("/api/v1/pay/order")
    Result<PayResult> createPayOrder(@RequestBody PayOrderDTO dto);
    
    @GetMapping("/api/v1/pay/status/{orderNo}")
    Result<PayStatus> getPayStatus(@PathVariable String orderNo);
}
```

### 3. 前端 → 后端

```typescript
// 前端通过网关调用服务
const API_GATEWAY = '/api';

// 调用收银服务
const cashierApi = {
    createOrder: (data) => axios.post(`${API_GATEWAY}/cashier/order`, data),
    getOrderList: () => axios.get(`${API_GATEWAY}/cashier/order/list`)
};

// 调用支付服务
const paymentApi = {
    createPay: (data) => axios.post(`${API_GATEWAY}/pay/order`, data),
    queryPayStatus: (orderNo) => axios.get(`${API_GATEWAY}/pay/status/${orderNo}`)
};
```

## 📐 API 规范

### URL 设计
```
/api/v1/{模块}/{资源}/{操作}

示例：
- GET    /api/v1/cashier/order/list      查询订单列表
- POST   /api/v1/cashier/order            创建订单
- GET    /api/v1/cashier/order/{id}       查询订单详情
- PUT    /api/v1/cashier/order/{id}       更新订单
- DELETE /api/v1/cashier/order/{id}       删除订单
```

### 返回格式
```json
{
    "code": 200,
    "message": "success",
    "data": {
        // 业务数据
    }
}
```

### 错误处理
```json
{
    "code": 500,
    "message": "支付失败：余额不足",
    "data": null
}
```

## 🗄️ 数据库隔离

| 模块 | 数据库/Schema | 说明 |
|------|--------------|------|
| rui-service | `rui_system` | 系统服务数据 |
| rui-cashier | `rui_cashier` | 收银业务数据 |
| rui-payment | `rui_payment` | 支付业务数据 |

**禁止**：
- 直接访问其他模块的数据库
- 直接查询其他模块的表

## 🚀 部署架构

```
┌─────────────┐
│   Nginx     │  ← 网关入口
└──────┬──────┘
       │
┌──────▼──────┐
│  rui-gateway │  ← Spring Cloud Gateway
└──────┬──────┘
       │
   ┌───┼───┐
   ▼   ▼   ▼
┌──┐ ┌──┐ ┌──┐
│用户│ │收银│ │支付│  ← 微服务模块
│服务│ │服务│ │服务│
└──┘ └──┘ └──┘
```

## 📋 开发流程

1. **模块 A 需要模块 B 的接口**
   - 模块 A 在自身仓库定义 FeignClient 接口
   - 模块 B 实现并暴露 REST API
   - 不需要依赖模块 B 的代码

2. **模块间数据传递**
   - 使用 DTO（Data Transfer Object）
   - DTO 定义在各自模块，不共享
   - 字段名保持一致

3. **接口变更**
   - 向后兼容
   - 版本号控制
   - 通知相关模块

## 🔔 注意事项

1. **超时设置**：FeignClient 默认超时 1 秒，根据业务调整
2. **熔断降级**：使用 Sentinel 或 Hystrix
3. **链路追踪**：使用 SkyWalking 或 Zipkin
4. **日志规范**：统一日志格式，包含 traceId

---

> **核心原则**：模块间只通过 REST API 通信，禁止任何直接代码引用！