@tx5dr/contracts 1.2.0

package/src/schema/mode.schema.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+
+/**
+ * 模式描述符 - 定义 FT8/FT4 等模式的时序参数
+ */
+export const ModeDescriptorSchema = z.object({
+  /** 模式名称，如 "FT8", "FT4" */
+  name: z.string(),
+  /** 时隙长度（毫秒），FT8=15000, FT4=7500, VOICE=0 */
+  slotMs: z.number().nonnegative(),
+  /** 时钟容差（毫秒） */
+  toleranceMs: z.number().nonnegative().default(100),
+  /** 
+   * 窗口时机（毫秒）- 必需
+   * 使用这些时机作为从时隙结束时间的偏移量
+   * 每个窗口都会获取固定长度的解码数据（FT8: 15秒，FT4: 7.5秒）
+   * 数组长度决定了子窗口的数量
+   * 支持负偏移，可以获取时隙结束前或其他周期的音频数据
+   */
+  windowTiming: z.array(z.number()),
+  /**
+   * 发射时机（毫秒）- 从时隙开始的延迟
+   * 对齐 WSJT-X 标准：信号在时隙边界后 ~0.5s 开始
+   * FT8: 500ms（信号 T+0.5s 起，12.64s 长，T+13.14s 结束）
+   * FT4: 500ms（信号 T+0.5s 起，6.0s 长，T+6.5s 结束，留 1.0s 给末端解码）
+   */
+  transmitTiming: z.number().nonnegative(),
+  /**
+   * 编码提前量（毫秒）- 在transmitTiming之前多久开始编码
+   * 默认400ms,用于补偿编码+混音时间
+   */
+  encodeAdvance: z.number().nonnegative().default(400)
+});
+
+export type ModeDescriptor = z.infer<typeof ModeDescriptorSchema>;
+
+/**
+ * 预定义的模式
+ */
+export const MODES = {
+  FT8: {
+    name: 'FT8',
+    slotMs: 15000,
+    toleranceMs: 100,
+    windowTiming: [-3200, -1500, -300], // WSJT-X 标准：11.8s / 13.5s / 14.7s 三轮解码
+    transmitTiming: 500,  // WSJT-X 标准：信号在时隙边界后 ~0.5s 开始
+    encodeAdvance: 0      // 编码在 transmitStart 时触发，留出 500ms 给策略决策
+  } as ModeDescriptor,
+  FT4: {
+    name: 'FT4',
+    slotMs: 7500,
+    toleranceMs: 50,
+    // 双 pass 解码：T+6000ms 早 pass（让下一周期 encodeStart 之前能拿到对端消息）+ T+7500ms 末 pass
+    windowTiming: [-1500, 0],
+    transmitTiming: 500, // WSJT-X 标准：FT4 信号 T+0.5s 起，6.0s 长
+    encodeAdvance: 300   // encodeStart 在 T+200ms 触发，留 ~300ms 给编码完成，使 transmitStart 时音频已就绪
+  } as ModeDescriptor,
+  VOICE: {
+    name: 'VOICE',
+    slotMs: 0,            // 语音模式无时隙概念
+    toleranceMs: 0,
+    windowTiming: [],     // 无解码窗口
+    transmitTiming: 0,
+    encodeAdvance: 0,
+  } as ModeDescriptor,
+} as const;
+
+/**
+ * 解码窗口预设
+ */
+export const DecodeWindowPreset = {
+  MAXIMUM: 'maximum',
+  BALANCED: 'balanced',
+  LIGHTWEIGHT: 'lightweight',
+  MINIMUM: 'minimum',
+  CUSTOM: 'custom',
+} as const;
+
+/**
+ * FT8 解码窗口预设映射
+ * 偏移量基于时隙结束时间（T+15000ms），即 offset = 实际触发时间 - 15000
+ * FT8 信号：T+500ms 开始，T+13140ms 结束（12.64s）
+ * WSJT-X 标准三轮：T+11.8s(-3200) / T+13.5s(-1500) / T+14.7s(-300)
+ */
+export const FT8_WINDOW_PRESETS: Record<string, number[]> = {
+  maximum: [-3200, -1500, -800, -300, -150],  // 5 轮
+  balanced: [-3200, -1500, -300],               // 3 轮：WSJT-X 标准时序
+  lightweight: [-3200, -300],                    // 2 轮：首尾两轮
+  minimum: [-300],                               // 1 轮：信号结束后最终解码
+};
+
+/**
+ * FT4 解码窗口预设映射
+ * 偏移量基于时隙结束时间（T+7500ms）
+ * FT4 信号：T+500ms 开始，T+6500ms 结束（6.0s）
+ * 双 pass 设计对齐 WSJT-X/JTDX：早 pass 让下一周期 encodeStart 前能用上结果
+ */
+export const FT4_WINDOW_PRESETS: Record<string, number[]> = {
+  maximum: [-2000, -1000, 0],   // 3 轮：T+5.5s / T+6.5s / T+7.5s
+  balanced: [-1500, 0],          // 2 轮：T+6.0s（早 pass）+ T+7.5s（末 pass）
+  lightweight: [0],              // 1 轮：仅末端
+};
+
+/**
+ * 解码窗口设置 Schema
+ */
+export const DecodeWindowSettingsSchema = z.object({
+  ft8: z.object({
+    preset: z.enum(['maximum', 'balanced', 'lightweight', 'minimum', 'custom']).default('balanced'),
+    customWindowTiming: z.array(z.number().int().min(-5000).max(1000)).optional(),
+  }).optional(),
+  ft4: z.object({
+    preset: z.enum(['maximum', 'balanced', 'lightweight', 'custom']).default('balanced'),
+    customWindowTiming: z.array(z.number().int().min(-5000).max(1000)).optional(),
+  }).optional(),
+});
+
+export type DecodeWindowSettings = z.infer<typeof DecodeWindowSettingsSchema>;
+
+export const DEFAULT_DECODE_WINDOW_SETTINGS: DecodeWindowSettings = {
+  ft8: {
+    preset: 'balanced',
+  },
+  ft4: {
+    preset: 'balanced',
+  },
+};
+
+/**
+ * 根据模式名和设置解析实际的 windowTiming
+ * 返回 null 表示使用 MODES 中的默认值
+ */
+export function resolveWindowTiming(
+  modeName: string,
+  settings?: DecodeWindowSettings
+): number[] | null {
+  if (!settings) return null;
+
+  const modeKey = modeName.toUpperCase();
+
+  if (modeKey === 'FT8' && settings.ft8) {
+    const { preset, customWindowTiming } = settings.ft8;
+    if (preset === 'custom' && customWindowTiming && customWindowTiming.length > 0) {
+      return [...customWindowTiming].sort((a, b) => a - b);
+    }
+    return FT8_WINDOW_PRESETS[preset] ?? null;
+  }
+
+  if (modeKey === 'FT4' && settings.ft4) {
+    const { preset, customWindowTiming } = settings.ft4;
+    if (preset === 'custom' && customWindowTiming && customWindowTiming.length > 0) {
+      return [...customWindowTiming].sort((a, b) => a - b);
+    }
+    return FT4_WINDOW_PRESETS[preset] ?? null;
+  }
+
+  return null;
+}

package/src/schema/openwebrx.schema.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+
+/**
+ * OpenWebRX SDR Profile 频率覆盖范围（持久化缓存）
+ * Profile API 只返回 {id, name}，覆盖范围需切换到该 profile 后从 config 获取。
+ * 缓存后避免重复探测（每次探测需 11s 冷却以规避 bot 检测）。
+ */
+export const OpenWebRXProfileCoverageSchema = z.object({
+  profileId: z.string(),
+  profileName: z.string(),
+  centerFreq: z.number(),
+  sampRate: z.number(),
+  lastUpdated: z.number(),
+});
+
+/**
+ * OpenWebRX SDR 站点配置 Schema
+ */
+export const OpenWebRXStationConfigSchema = z.object({
+  /** 站点唯一ID */
+  id: z.string(),
+  /** 用户定义的站点名称 */
+  name: z.string().min(1),
+  /** WebSocket URL，如 "ws://host:8073" 或 "wss://..." */
+  url: z.string().url(),
+  /** 站点描述 */
+  description: z.string().optional(),
+  /** 已知的 Profile 频率覆盖范围缓存（持久化，重启后无需重新探测） */
+  profileCoverages: z.array(OpenWebRXProfileCoverageSchema).optional(),
+});
+
+/**
+ * OpenWebRX SDR Profile 信息（远端服务器返回）
+ */
+export const OpenWebRXProfileSchema = z.object({
+  /** Profile ID，格式为 "sdr_id|profile_id" */
+  id: z.string(),
+  /** 显示名称 */
+  name: z.string(),
+});
+
+/**
+ * OpenWebRX 连接测试结果
+ */
+export const OpenWebRXTestResultSchema = z.object({
+  success: z.boolean(),
+  /** 服务器版本 */
+  serverVersion: z.string().optional(),
+  /** 可用的 SDR Profile 列表 */
+  profiles: z.array(OpenWebRXProfileSchema).optional(),
+  /** 错误信息 */
+  error: z.string().optional(),
+});
+
+/**
+ * OpenWebRX 试听状态
+ */
+export const OpenWebRXListenStatusSchema = z.object({
+  /** 试听会话ID，用于生成 LiveKit preview 房间 */
+  previewSessionId: z.string().optional(),
+  /** 站点ID */
+  stationId: z.string(),
+  /** 是否已连接 */
+  connected: z.boolean(),
+  /** 服务器版本 */
+  serverVersion: z.string().optional(),
+  /** 可用 Profile 列表 */
+  profiles: z.array(OpenWebRXProfileSchema),
+  /** 当前选中的 Profile ID */
+  currentProfileId: z.string().optional(),
+  /** 当前中心频率 (Hz) */
+  centerFreq: z.number().optional(),
+  /** 当前采样率 (Hz) */
+  sampleRate: z.number().optional(),
+  /** 当前 tune 频率 (Hz) */
+  frequency: z.number().optional(),
+  /** 当前调制模式 */
+  modulation: z.string().optional(),
+  /** S-Meter 读数 (dBFS) */
+  smeterDb: z.number().optional(),
+  /** 是否正在试听 */
+  isListening: z.boolean(),
+  /** 错误信息 */
+  error: z.string().optional(),
+});
+
+/**
+ * OpenWebRX 试听启动参数
+ */
+export const OpenWebRXListenStartSchema = z.object({
+  /** 站点ID */
+  stationId: z.string(),
+  /** 指定 Profile ID（可选，不指定则使用默认） */
+  profileId: z.string().optional(),
+  /** 频率 (Hz) */
+  frequency: z.number().optional(),
+  /** 调制模式 */
+  modulation: z.string().optional(),
+});
+
+/**
+ * OpenWebRX 试听调整参数
+ */
+export const OpenWebRXListenTuneSchema = z.object({
+  /** 切换到的 Profile ID */
+  profileId: z.string().optional(),
+  /** 频率 (Hz) */
+  frequency: z.number().optional(),
+  /** 调制模式 */
+  modulation: z.string().optional(),
+  /** 带通滤波器低端 (Hz) */
+  bandpassLow: z.number().optional(),
+  /** 带通滤波器高端 (Hz) */
+  bandpassHigh: z.number().optional(),
+});
+
+/**
+ * Server → Client: 请求管理员手动选择 SDR Profile
+ * 当引擎自动匹配（缓存 + 名称启发式）全部失败时发出
+ */
+export const OpenWebRXProfileSelectRequestSchema = z.object({
+  requestId: z.string(),
+  targetFrequency: z.number(),
+  profiles: z.array(z.object({ id: z.string(), name: z.string() })),
+  currentProfileId: z.string().optional(),
+});
+
+/**
+ * Client → Server: 用户选择了 Profile 并请求验证
+ */
+export const OpenWebRXProfileSelectResponseSchema = z.object({
+  requestId: z.string(),
+  profileId: z.string(),
+  targetFrequency: z.number(),
+});
+
+/**
+ * Server → Client: Profile 验证结果
+ */
+export const OpenWebRXProfileVerifyResultSchema = z.object({
+  requestId: z.string(),
+  success: z.boolean(),
+  profileId: z.string(),
+  profileName: z.string().optional(),
+  centerFreq: z.number().optional(),
+  sampRate: z.number().optional(),
+  error: z.string().optional(),
+});
+
+// 导出类型
+export type OpenWebRXStationConfig = z.infer<typeof OpenWebRXStationConfigSchema>;
+export type OpenWebRXProfile = z.infer<typeof OpenWebRXProfileSchema>;
+export type OpenWebRXProfileCoverage = z.infer<typeof OpenWebRXProfileCoverageSchema>;
+export type OpenWebRXTestResult = z.infer<typeof OpenWebRXTestResultSchema>;
+export type OpenWebRXListenStatus = z.infer<typeof OpenWebRXListenStatusSchema>;
+export type OpenWebRXListenStart = z.infer<typeof OpenWebRXListenStartSchema>;
+export type OpenWebRXListenTune = z.infer<typeof OpenWebRXListenTuneSchema>;
+export type OpenWebRXProfileSelectRequest = z.infer<typeof OpenWebRXProfileSelectRequestSchema>;
+export type OpenWebRXProfileSelectResponse = z.infer<typeof OpenWebRXProfileSelectResponseSchema>;
+export type OpenWebRXProfileVerifyResult = z.infer<typeof OpenWebRXProfileVerifyResultSchema>;

package/src/schema/operator.schema.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { ModeDescriptorSchema } from './mode.schema.js';
+
+// 操作员配置 Schema (重命名以避免冲突)
+export const RadioOperatorConfigSchema = z.object({
+  id: z.string().min(1, '操作员ID不能为空'),
+  createdByTokenId: z.string().optional(), // 创建者 Token ID（仅用于审计，不参与权限判断）
+  myCallsign: z.string().min(1, '呼号不能为空').max(10, '呼号不能超过10个字符'),
+  myGrid: z.string().min(4, '网格坐标至少4位').max(8, '网格坐标不能超过8位').optional(),
+  frequency: z.number().min(0).max(1000000000, '频率必须在0-1GHz之间').default(1000), // 音频偏移频率（Hz），默认1000Hz，创建时自动分配不重复值
+  transmitCycles: z.array(z.number().min(0).max(1)).default([0]), // 0=偶数周期，1=奇数周期
+  mode: ModeDescriptorSchema.optional(),
+  logBookId: z.string().optional(), // 连接的日志本ID，如果未指定则使用默认日志本
+});
+
+// 创建操作员请求（客户端不能指定 id 和 createdByTokenId，由服务端自动设置）
+export const CreateRadioOperatorRequestSchema = RadioOperatorConfigSchema.omit({
+  id: true,
+  createdByTokenId: true,
+});
+
+// 更新操作员请求（客户端不能修改 id 和 createdByTokenId）
+export const UpdateRadioOperatorRequestSchema = RadioOperatorConfigSchema.partial().omit({
+  id: true,
+  createdByTokenId: true,
+});
+
+// 操作员列表响应
+export const RadioOperatorListResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.array(RadioOperatorConfigSchema),
+});
+
+// 操作员详情响应
+export const RadioOperatorDetailResponseSchema = z.object({
+  success: z.boolean(),
+  data: RadioOperatorConfigSchema,
+});
+
+// 操作员操作响应
+export const RadioOperatorActionResponseSchema = z.object({
+  success: z.boolean(),
+  message: z.string(),
+  data: RadioOperatorConfigSchema.optional(),
+});
+
+// 操作员状态响应（从websocket.schema.ts导入）
+export const RadioOperatorStatusResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.object({
+    id: z.string(),
+    isActive: z.boolean(),
+    isTransmitting: z.boolean(),
+    currentSlot: z.string().optional(),
+    context: z.object({
+      myCall: z.string(),
+      myGrid: z.string(),
+      targetCall: z.string(),
+      targetGrid: z.string().optional(),
+      frequency: z.number().optional(),
+      reportSent: z.number().optional(),
+      reportReceived: z.number().optional(),
+    }),
+    strategy: z.object({
+      name: z.string(),
+      state: z.string(),
+      availableSlots: z.array(z.string()),
+    }),
+    runtime: z.object({
+      currentState: z.string(),
+      slots: z.object({
+        TX1: z.string().optional(),
+        TX2: z.string().optional(),
+        TX3: z.string().optional(),
+        TX4: z.string().optional(),
+        TX5: z.string().optional(),
+        TX6: z.string().optional(),
+      }).optional(),
+      context: z.object({
+        targetCallsign: z.string().optional(),
+        targetGrid: z.string().optional(),
+        reportSent: z.number().optional(),
+        reportReceived: z.number().optional(),
+        actualFrequency: z.number().optional(),
+      }).optional(),
+      availableSlots: z.array(z.string()).optional(),
+    }).optional(),
+    cycleInfo: z.object({
+      currentCycle: z.number(),
+      isTransmitCycle: z.boolean(),
+      cycleProgress: z.number().min(0).max(1),
+    }).optional(),
+    slots: z.object({
+      TX1: z.string().optional(),
+      TX2: z.string().optional(),
+      TX3: z.string().optional(),
+      TX4: z.string().optional(),
+      TX5: z.string().optional(),
+      TX6: z.string().optional(),
+    }).optional(),
+    transmitCycles: z.array(z.number()).optional(),
+  }),
+});
+
+// TypeScript 类型导出
+export type RadioOperatorConfig = z.infer<typeof RadioOperatorConfigSchema>;
+export type CreateRadioOperatorRequest = z.infer<typeof CreateRadioOperatorRequestSchema>;
+export type UpdateRadioOperatorRequest = z.infer<typeof UpdateRadioOperatorRequestSchema>;
+export type RadioOperatorListResponse = z.infer<typeof RadioOperatorListResponseSchema>;
+export type RadioOperatorDetailResponse = z.infer<typeof RadioOperatorDetailResponseSchema>;
+export type RadioOperatorActionResponse = z.infer<typeof RadioOperatorActionResponseSchema>;
+export type RadioOperatorStatusResponse = z.infer<typeof RadioOperatorStatusResponseSchema>;