520 lines
6.5 KiB
Markdown
520 lines
6.5 KiB
Markdown
# 🌐 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，才是“能赚钱 + 能自动跑”的系统。**
|