zpms-redis-message-sdk

@zpms/redis-message-sdk

ZPMS 中台内部 Redis 隧道消息发布 SDK。

该包用于统一不同业务服务向 Redis Pub/Sub 隧道发布消息的格式、路由和基础校验逻辑。

功能特性

• 统一系统消息与业务消息发布入口
• 自动生成 messageId
• 默认生成 timestamp，允许外部覆盖
• 自动生成 Redis 路由
• 校验 type、staffCd、source、tenantId、hotelId 等协议字段
• 对 payload 保持宽松约束

路由规则

• 系统消息：sse:system:channel
• 租户级业务消息：sse:{tenantId}:-1:channel
• 酒店级业务消息：sse:{tenantId}:{hotelId}:channel

安装

npm install @zpms/redis-message-sdk

快速开始

import Redis from 'ioredis';
import { createRedisMessagePublisher, SystemChannel } from '@zpms/redis-message-sdk';

const redisClient = new Redis({
  host: '127.0.0.1',
  port: 6379,
});

const publisher = createRedisMessagePublisher({
  publisher: redisClient,
});

发布系统消息

await publisher.publishSystemMessage({
  systemChannel: SystemChannel.NOTICE,
  type: 'system.notice',
  eventName: 'system.global.notice',
  staffCd: 'EMP001',
  source: 'zpms-message-center',
  payload: {
    title: '系统通知',
    content: '全局消息通知',
  },
});

发布业务消息

await publisher.publishBusinessMessage({
  tenantId: '10001',
  hotelId: '20001',
  type: 'order.created',
  eventName: 'order.status.changed',
  staffCd: 'EMP001',
  source: 'zpms-order-service',
  businessKey: 'order',
  businessId: 'ORDER_202605150001',
  payload: {
    orderNo: 'ORDER_202605150001',
    status: 'CREATED',
  },
});

发布租户级业务消息

await publisher.publishBusinessMessage({
  tenantId: '10001',
  hotelId: '-1',
  type: 'member.updated',
  eventName: 'member.profile.updated',
  staffCd: 'EMP002',
  source: 'zpms-member-service',
  businessKey: 'member',
  businessId: 'MEMBER_10086',
  payload: {
    memberId: '10086',
    level: 'GOLD',
  },
});

协议约束

系统消息

• systemChannel 当前仅支持 SystemChannel.NOTICE
• type 必须以 system. 开头
• 不允许传入 tenantId
• 不允许传入 hotelId
• eventName 为可选字符串字段

业务消息

• tenantId 必填
• hotelId 必填
• 当 hotelId = '-1' 时表示租户级业务消息
• eventName 为可选字符串字段，位于 businessId 同级

通用约束

• staffCd 必填
• source 必填
• payload 必须为对象
• type 仅允许小写字母和 .
• type 正则：^[a-z]+(\.[a-z]+)*$

返回结果

interface PublishMessageResult {
  success: boolean;
  messageId: string;
  route: string;
  subscriberCount: number;
}

本地开发

npm install
npm run typecheck
npm run test
npm run build

发布前检查

npm run check
npm run pack:dry-run

发布到公共 npm 前，请先确认：

• 已更新 version
• 已更新 CHANGELOG.md
• 已检查 npm pack --dry-run 输出文件列表
• 已登录 npm 官方源
• 已确认当前账号拥有 @zpms scope 的发布权限

发布检查清单见 docs/publish-checklist.md。

相关文档

• docs/redis-message-protocol-v1.md
• docs/redis-message-sdk-design-v1.md
• docs/publish-checklist.md