npm package: @step-monitor/core
Description: 一个轻量级的步骤监控工具，用于追踪和记录多步骤流程的执行状态。
Author: Zach
Latest version: 1.0.8

# Step Monitor

## 简介

一个轻量级的步骤监控工具，用于追踪和记录多步骤流程的执行状态。

## 功能特点

- 🌳 支持多层级步骤嵌套
- 🔄 异步流程监控
- 📝 自动记录每个步骤的状态
- ⏱️ 记录执行时间
- 🎯 支持自定义数据存储
- 🔍 详细的输入输出追踪
- 🔁 支持流程断点恢复

## 安装

```bash
npm install @step-monitor/core
```

## 快速开始

```typescript
import { StepMonitor,type MonitorRecord,type StepRecord } from "@step-monitor/core";

// 创建监控器实例
const monitor = new StepMonitor({
   // monitor.stepStart() 时会调用 insertMonitor
  insertStep: async (step: StepRecord): Promise<{ id: string }> => ({ id: "1" }),
  // monitor.stepEnd() 时会调用 updateStep
  updateStep: async (step: StepRecord): Promise<{ id: string }> => ({ id: step.id }),
  // monitor.start() 时会调用 insertMonitor
  insertMonitor: async (monitor: MonitorRecord): Promise<{ id: string }> => ({ id: "1" }),
  // monitor.end() 时会调用 updateMonitor
  updateMonitor: async (monitor: MonitorRecord): Promise<{ id: string }> => ({ id: monitor.id }),
  // monitor.recover() 时会调用 getMonitor
  getMonitor: async (monitorId: string): Promise<MonitorRecord | null> => null,
  // monitor.recover() 时会调用 getMonitorSteps
  getMonitorSteps: async (monitorId: string): Promise<StepRecord[]> => [],
});

// 使用监控器
async function example() {
  let currentMonitor;
  try {
    // 开始监控
    currentMonitor = (await monitor.start("示例流程"));

    // 执行顶级步骤
    const step1 = await monitor.stepStart("步骤1");
    await monitor.stepEnd(step1.step_id, { result: "ok" });

    // 执行带子步骤的步骤
    const step2 = await monitor.stepStart("步骤2");
    const childStep = await monitor.stepStart("子步骤2-1", step2.step_id);
    await monitor.stepEnd(childStep.step_id, { done: true });
    await monitor.stepEnd(step2.step_id, { success: true });

    // 从数据库恢复流程
    const recoveredMonitor = await monitor.recover(currentMonitor.monitor_id);
    console.log(JSON.stringify(recoveredMonitor, null, 2));

    // 恢复后可以继续执行子步骤的步骤
    const step3 = await monitor.stepStart("步骤3");
    await monitor.stepEnd(step3.step_id, { success: true });


    // 完成流程
    await monitor.end({ success: true });
  } catch (error) {
    await monitor.end(null, error);
  }

  // 获取监控树
  const monitorTree = monitor.getMonitorTree();
  console.log(JSON.stringify(monitorTree, null, 2));
}
```

## 使用示例

完整的示例代码可以在 [examples](./examples) 目录中找到：

- [基础使用](./examples/basic-usage.ts)
- [错误处理](./examples/error-handling.ts)
- [监控列表](./examples/list-monitors.ts)

### 运行示例

```bash
npm run example
```

## API 参考

### 核心方法

#### 流程控制

- `start(name, input?, description?)`: 开始新流程
- `recover(monitorId)`: 从数据库已有流程恢复
- `end(output, error?)`: 结束当前流程

#### 步骤控制

- `stepStart(name, parentId?, input?, description?)`: 开始新步骤
- `stepEnd(stepId, output, error?)`: 结束步骤

#### 状态查询

- `getMonitorTree()`: 获取当前活动监控的树状结构
- `getMonitorDetails(monitorId)`: 获取指定监控的详细信息
- `listMonitors(options?)`: 查询监控列表

## 数据表设计参考

使用单表设计存储监控流程和步骤记录：

```sql
CREATE TABLE monitor_records (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    monitor_id VARCHAR(64) NOT NULL,         -- 监控ID
    step_id VARCHAR(64) UNIQUE NOT NULL,    -- 步骤ID
    parent_id VARCHAR(64),                    -- 父级ID：level=0时为空，level=1时为monitor_id，level>=2时为step_id
    type ENUM('monitor', 'step') NOT NULL,    -- 记录类型：监控流程/步骤
    level INT NOT NULL DEFAULT 0,             -- 步骤层级：0=监控，1=顶级步骤，2=子步骤...
    name VARCHAR(255) NOT NULL,               -- 名称
    status ENUM('pending', 'running', 'success', 'failed') NOT NULL,
    step_index INT,                           -- 同级步骤中的序号（从0开始）
    input JSON,                               -- 输入参数
    output JSON,                              -- 输出结果
    error TEXT,                               -- 错误信息
    description TEXT,                         -- 描述信息
    duration BIGINT,                          -- 执行时长(毫秒)
    metadata JSON,                            -- 扩展字段
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    INDEX idx_step_id (step_id),
    INDEX idx_monitor_id (monitor_id),
    INDEX idx_parent (parent_id),
    INDEX idx_type_status (type, status),
    INDEX idx_level (level),
    INDEX idx_created_at (created_at)
);
```
### 设计说明

1. **ID 设计**

   - 使用自增主键作为内部 ID
   - step_id 作为业务 ID，用于外部引用
   - parent_id 用于关联流程和步骤

2. **类型区分**

   - type 字段区分记录类型
   - monitor: 监控流程记录
   - step: 步骤记录

3. **状态追踪**

   - 统一的状态定义
   - 包含时间戳和执行时长
   - 支持错误信息记录

4. **扩展性**
   - input/output 使用 JSON 类型存储
   - metadata 字段支持额外信息
   - 支持描述信息

### 使用建议

1. **步骤组织**

   - 使用 parentId 创建子步骤
   - 推荐最多使用三层步骤结构
   - 合理规划步骤粒度

2. **状态管理**

   - 子步骤状态会影响父步骤
   - 步骤完成后状态不可更改
   - 错误发生时及时结束流程

3. **性能考虑**
   - 合理使用分页查询
   - 避免过深的步骤嵌套
   - 及时清理历史数据

## 许可证

MIT