# 🌐 Runtime_Architecture.md（运行态架构 · 可落地版）

---

# 🎯 一、设计目标

> 将系统从“接口驱动”升级为“事件驱动 + 自动运行系统”，实现业务闭环自动推进、可计费、可监控。

---

# 🧠 二、核心设计原则

### 1️⃣ 事件驱动（Event Driven）

所有业务流转必须通过事件触发，而不是手动串流程

---

### 2️⃣ 状态驱动（State Driven）

所有实体必须由 STATE_MACHINE 控制流转

---

### 3️⃣ 服务编排（Service Orchestration）

所有业务逻辑必须在 Service 层执行

---

### 4️⃣ 自动化优先（Automation First）

能自动执行的流程，禁止依赖用户点击

---

### 5️⃣ 可计费（Billable by Design）

所有关键行为必须具备计费能力

---

# 🧩 三、Runtime 四大核心模块

---

## 1️⃣ Event System（事件系统）

### 🎯 作用

解耦模块，实现系统自动联动

---

### 📌 事件结构

```typescript
interface DomainEvent {
  id: string
  type: string
  payload: any
  timestamp: number
  source: string
  merchantId?: string
}
```

---

### 📌 核心事件定义

```typescript
// 商品
PRODUCT_CREATED
PRODUCT_UPDATED

// 订单
ORDER_CREATED
ORDER_PAID
ORDER_COMPLETED

// 库存
INVENTORY_LOW
INVENTORY_UPDATED

// 功能
FEATURE_ENABLED
FEATURE_DISABLED

// AI
AI_TASK_CREATED
AI_TASK_COMPLETED

// 广告
AD_STARTED
AD_PERFORMANCE_UPDATED

// 任务
JOB_CREATED
JOB_UPDATED
JOB_COMPLETED

// 计费
BILLING_GENERATED
```

---

### 📌 事件流

```typescript
Controller → Service → Emit Event → EventBus → Listener → Service
```

---

### 📌 示例

```typescript
await productService.createProduct(data)

eventBus.emit({
  type: 'PRODUCT_CREATED',
  payload: { productId },
  source: 'ProductService',
  merchantId: data.merchantId
})
```

---

## 2️⃣ Job / Worker System（任务系统）

### 🎯 作用

执行异步任务 & 自动推进系统

---

### 📌 任务模型

```typescript
interface Job {
  id: string
  type: string
  status: 'pending' | 'running' | 'success' | 'failed'
  payload: any
  result?: any
  retryCount: number
  merchantId?: string
  priority?: number
}
```

---

### 📌 核心任务类型

```typescript
AI_OPTIMIZE_PRODUCT
SYNC_INVENTORY
RUN_ADS
CALCULATE_PROFIT
GENERATE_BILL
UPDATE_AD_BUDGET
STOP_AD
```

---

### 📌 执行流程

```typescript
Event → 创建 Job → Worker 消费 → 调用 Service → 更新状态 → 触发新 Event
```

---

### 📌 示例

```typescript
eventBus.on('PRODUCT_CREATED', async (event) => {
  await jobService.create({
    type: 'AI_OPTIMIZE_PRODUCT',
    payload: { productId: event.payload.productId },
    merchantId: event.merchantId
  })
})
```

---

## 3️⃣ Scheduler（调度系统）

### 🎯 作用

周期性驱动系统（无人值守）

---

### 📌 示例调度

```typescript
// 每5分钟
syncInventory()

// 每1小时
calculateROI()

// 每天
runSettlement()
```

---

### 📌 实现方式

```typescript
node-cron / bullmq / agenda
```

---

### 📌 调度 → Job

```typescript
cron.schedule('*/5 * * * *', async () => {
  await jobService.create({ type: 'SYNC_INVENTORY' })
})
```

---

## 4️⃣ State Engine（状态推进器）

### 🎯 作用

统一控制所有状态流转

---

### 📌 原则

❌ Service 随意改状态
✅ 必须通过 State Machine

---

### 📌 示例

```typescript
orderStateMachine.transition(order, 'PAY')
```

---

### 📌 自动推进

```typescript
Worker → 调用 Service → 推动状态
```

---

# 💰 四、计费系统（Billing Runtime）

---

## 📊 1️⃣ 计费模型

```typescript
FeatureBilling
UsageBilling
ResultBilling
SubscriptionBilling
```

---

## 📌 2️⃣ 使用量计费

```typescript
UsageService.track({
  feature: 'AI_OPTIMIZE',
  usage: 1,
  merchantId,
  source: 'AI'
})
```

---

## 📌 3️⃣ 账单生成

```typescript
BillingService.generateBill(merchantId)
```

---

## 📌 4️⃣ 收费触发点

| 行为 | 是否计费 |
| --- | --- |
| AI优化 | ✅ |
| 广告投放 | ✅ |
| 自动补货 | ✅ |
| API调用 | ✅ |

---

# 🔄 五、完整运行链路（核心）

---

## 🎯 示例：商品自动赚钱闭环

```typescript
用户创建商品
→ PRODUCT_CREATED

→ 创建 Job（AI优化）
→ AI_TASK_COMPLETED

→ 自动上架
→ AD_STARTED

→ 产生订单
→ ORDER_PAID

→ CALCULATE_PROFIT

→ GENERATE_BILL
```

---

# 🎯 六、前端 Runtime 对应设计（关键）

---

## 1️⃣ Task Center（必须做）

### 字段

```typescript
任务名称
状态（运行中/完成/失败）
进度
结果
触发来源
```

---

## 2️⃣ Event Log

```typescript
时间
事件类型
来源
结果
```

---

## 3️⃣ Billing Timeline

```typescript
时间
费用类型
金额
来源功能
```

---

## 4️⃣ ROI Dashboard（核心）

```typescript
商品ID
ROI
点击数
订单数
成本
收入
```

---

# 🧱 七、Service 分层强化（必须执行）

---

## ❗ 强制规则

```typescript
Controller ❌ 不允许写逻辑
Service ✅ 唯一逻辑入口
Worker ✅ 调用 Service
```

---

# 🔐 八、运行安全设计

---

## 必须补

### 1️⃣ 幂等性

```typescript
jobId: productId + type
```

---

### 2️⃣ 重试机制

```typescript
失败 → retry 3 次
```

---

### 3️⃣ 日志系统

```typescript
Event Log + Job Log + Error Log
```

---

# 🚀 九、实施步骤

---

## 1️⃣ 新建模块

```bash
/src/runtime
  ├── eventBus.ts
  ├── jobQueue.ts
  ├── worker.ts
  ├── scheduler.ts
  ├── jobProcessor.ts
```

---

## 2️⃣ 实现 BullMQ 分布式队列

```bash
/src/runtime/queue
  ├── index.ts
  ├── worker.ts
  ├── processor.ts
  ├── priority.ts
```

---

## 3️⃣ 实现 WebSocket 实时推送

```bash
/src/runtime/ws
  ├── server.ts
  ├── client.ts
  ├── broadcast.ts
```

---

## 4️⃣ 实现计费系统

```bash
/src/services
  ├── UsageService.ts
  ├── BillingService.ts
```

---

## 5️⃣ 实现 AI 策略系统

```bash
/src/runtime/strategy
  ├── engine.ts
  ├── roi.ts
  ├── ad.ts
```

---

## 6️⃣ 前端实现

```bash
/pages/TaskCenter/index.tsx
/pages/EventLog/index.tsx
/pages/Billing/index.tsx
/pages/ROIDashboard/index.tsx
```

---

# 🧠 最终结论

你现在系统的阶段是：

> ✅ 架构完成
> ❗ Runtime 未建立

---

# 🔥 一句话

> **没有 Runtime，你的系统只是“能用”；
> 有 Runtime，才是“能赚钱 + 能自动跑”的系统。**