@tx5dr/contracts 1.2.0

package/src/schema/api-response.schema.ts

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+import {
+  HamlibConfigSchema,
+  RadioInfoSchema,
+  RadioConnectionStatusSchema,
+  PresetFrequencySchema,
+  SupportedRigSchema,
+  SerialPortSchema,
+  TunerCapabilitiesSchema,
+  TunerStatusSchema,
+} from './radio.schema.js';
+
+/**
+ * API 响应基础类型定义
+ * 用于统一 API 响应格式
+ */
+
+// ========== 通用响应 Schema ==========
+
+/**
+ * 基础成功响应
+ */
+export const BaseSuccessResponseSchema = z.object({
+  success: z.literal(true),
+  message: z.string().optional(),
+});
+
+/**
+ * 基础错误响应
+ */
+export const BaseErrorResponseSchema = z.object({
+  success: z.literal(false),
+  message: z.string(),
+  code: z.string().optional(),
+  userMessage: z.string().optional(),
+  suggestions: z.array(z.string()).optional(),
+  severity: z.enum(['info', 'warning', 'error', 'critical']).optional(),
+  context: z.record(z.any()).optional(),
+});
+
+// ========== 电台配置相关响应 ==========
+
+/**
+ * 获取电台配置响应 (已存在于 radio.schema.ts)
+ * RadioConfigResponseSchema
+ */
+
+/**
+ * 更新电台配置响应
+ */
+export const UpdateRadioConfigResponseSchema = z.object({
+  success: z.boolean(),
+  config: HamlibConfigSchema,
+  message: z.string().optional(),
+});
+
+/**
+ * 支持的电台列表响应 (已存在于 radio.schema.ts)
+ * SupportedRigsResponseSchema
+ */
+
+/**
+ * 串口列表响应 (已存在于 radio.schema.ts)
+ * SerialPortsResponseSchema
+ */
+
+/**
+ * 电台测试响应 (已存在于 radio.schema.ts)
+ * TestResponseSchema
+ */
+
+/**
+ * 电台状态响应
+ */
+export const RadioStatusResponseSchema = z.object({
+  success: z.boolean(),
+  status: z.object({
+    connected: z.boolean(),
+    connectionStatus: RadioConnectionStatusSchema.optional(),
+    radioInfo: RadioInfoSchema.nullable(),
+    radioConfig: HamlibConfigSchema.optional(),
+    connectionHealth: z.object({
+      connectionHealthy: z.boolean(),
+    }).optional(),
+  }),
+});
+
+/**
+ * 连接电台响应
+ */
+export const ConnectRadioResponseSchema = z.object({
+  success: z.boolean(),
+  message: z.string(),
+  radioInfo: RadioInfoSchema.optional(),
+});
+
+/**
+ * 断开电台响应
+ */
+export const DisconnectRadioResponseSchema = z.object({
+  success: z.boolean(),
+  message: z.string(),
+});
+
+// ========== 频率管理相关响应 ==========
+
+/**
+ * 预设频率列表响应 (已存在于 radio.schema.ts)
+ * FrequencyListResponseSchema
+ */
+
+/**
+ * 最后使用频率响应
+ */
+export const LastFrequencyResponseSchema = z.object({
+  success: z.boolean(),
+  lastFrequency: PresetFrequencySchema.nullable(),
+});
+
+/**
+ * 设置频率响应
+ */
+export const SetFrequencyResponseSchema = z.object({
+  success: z.boolean(),
+  message: z.string(),
+  frequency: z.number(),
+  mode: z.string().optional(),
+  band: z.string().optional(),
+  radioMode: z.string().optional(),
+  radioConnected: z.boolean().optional(),
+});
+
+// ========== 时隙包相关响应 ==========
+
+/**
+ * 时隙包列表响应
+ */
+export const SlotPacksResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.array(z.any()), // 使用 SlotPackSchema，但这里暂时用 any 避免循环依赖
+  timestamp: z.number(),
+});
+
+/**
+ * 单个时隙包响应
+ */
+export const SlotPackResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.any(), // 使用 SlotPackSchema
+  timestamp: z.number(),
+});
+
+/**
+ * 时隙包统计响应
+ */
+export const SlotPackStatsResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.object({
+    activeSlotPacks: z.number(),
+    totalProcessed: z.number(),
+    totalFrames: z.number(),
+    averageFramesPerSlot: z.number(),
+    lastActivity: z.number(),
+  }),
+  timestamp: z.number(),
+});
+
+// ========== 天调相关响应 (已存在于 radio.schema.ts) ==========
+// TunerCapabilitiesResponseSchema
+// TunerStatusResponseSchema
+
+// ========== 导出 TypeScript 类型 ==========
+
+export type BaseSuccessResponse = z.infer<typeof BaseSuccessResponseSchema>;
+export type BaseErrorResponse = z.infer<typeof BaseErrorResponseSchema>;
+
+export type UpdateRadioConfigResponse = z.infer<typeof UpdateRadioConfigResponseSchema>;
+export type RadioStatusResponse = z.infer<typeof RadioStatusResponseSchema>;
+export type ConnectRadioResponse = z.infer<typeof ConnectRadioResponseSchema>;
+export type DisconnectRadioResponse = z.infer<typeof DisconnectRadioResponseSchema>;
+
+export type LastFrequencyResponse = z.infer<typeof LastFrequencyResponseSchema>;
+export type SetFrequencyResponse = z.infer<typeof SetFrequencyResponseSchema>;
+
+export type SlotPacksResponse = z.infer<typeof SlotPacksResponseSchema>;
+export type SlotPackResponse = z.infer<typeof SlotPackResponseSchema>;
+export type SlotPackStatsResponse = z.infer<typeof SlotPackStatsResponseSchema>;

package/src/schema/audio-sidecar.schema.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+
+/**
+ * AudioSidecar 状态：描述本地音频子系统的旁路生命周期。
+ * 与电台 CAT 连接解耦——主引擎已进入 RUNNING，但音频可能仍在重试或已停用。
+ */
+export enum AudioSidecarStatus {
+  /** 引擎未运行或 sidecar 未启动 */
+  IDLE = 'idle',
+  /** 首次尝试启动音频流中 */
+  CONNECTING = 'connecting',
+  /** 音频输入/输出/监听均已就绪 */
+  CONNECTED = 'connected',
+  /** 上一次尝试失败，等待下一次退避重试 */
+  RETRYING = 'retrying',
+  /** 配置错误或不可恢复的失败，已停止重试 */
+  DISABLED = 'disabled',
+}
+
+export const AudioSidecarStatusSchema = z.nativeEnum(AudioSidecarStatus);
+
+export const AudioSidecarErrorSchema = z.object({
+  code: z.string().optional(),
+  message: z.string(),
+  userMessage: z.string().optional(),
+  userMessageKey: z.string().optional(),
+  userMessageParams: z.record(z.union([z.string(), z.number()])).optional(),
+});
+
+export type AudioSidecarError = z.infer<typeof AudioSidecarErrorSchema>;
+
+/**
+ * AudioSidecar 状态变化载荷。
+ * 前端以此渲染 RadioControl 中的音频副状态 spinner + Popover。
+ */
+export const AudioSidecarStatusPayloadSchema = z.object({
+  /** 当前状态 */
+  status: AudioSidecarStatusSchema,
+  /** 音频输入/输出是否已就绪可用 */
+  isConnected: z.boolean(),
+  /** 当前重试尝试计数（0 表示首次未重试过） */
+  retryAttempt: z.number().int().min(0),
+  /** 下次重试延迟 ms（仅 RETRYING 有值） */
+  nextRetryMs: z.number().int().min(0).nullable(),
+  /** 连续失败超过阈值时置 true，用于前端提示"长时间未就绪" */
+  longRunning: z.boolean(),
+  /** 最近一次错误摘要 */
+  lastError: AudioSidecarErrorSchema.nullable(),
+  /** 当前目标设备名（来自 AudioConfig.inputDeviceName） */
+  deviceName: z.string().nullable(),
+});
+
+export type AudioSidecarStatusPayload = z.infer<typeof AudioSidecarStatusPayloadSchema>;

package/src/schema/audio.schema.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+
+// 音频设备信息
+export const AudioDeviceSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  isDefault: z.boolean(),
+  channels: z.number(),
+  sampleRate: z.number(),
+  type: z.enum(['input', 'output']),
+});
+
+// 音频设备列表响应
+export const AudioDevicesResponseSchema = z.object({
+  inputDevices: z.array(AudioDeviceSchema),
+  outputDevices: z.array(AudioDeviceSchema),
+});
+
+// 音频设备设置请求
+export const AudioDeviceSettingsSchema = z.object({
+  inputDeviceName: z.string().optional(),  // 使用设备名称而非ID
+  outputDeviceName: z.string().optional(), // 使用设备名称而非ID  
+  sampleRate: z.number().optional(),
+  bufferSize: z.number().optional(),
+});
+
+// 音频设备设置响应
+export const AudioDeviceSettingsResponseSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+  currentSettings: AudioDeviceSettingsSchema,
+});
+
+// 音频流配置参数 (用于 Audify/RtAudio)
+export const AudioStreamConfigSchema = z.object({
+  channelCount: z.number().int().min(1).max(32),
+  sampleFormat: z.number().int(), // RtAudio SampleFormat 枚举值
+  sampleRate: z.number().int().min(8000).max(192000),
+  deviceId: z.string().optional(),
+  maxQueue: z.number().int().optional(),
+  queueHighWaterMark: z.number().int().optional(),
+});
+
+// 音频流事件数据
+export const AudioStreamEventDataSchema = z.object({
+  type: z.enum(['started', 'stopped', 'error', 'audioData']),
+  error: z.string().optional(),
+  samples: z.number().optional(), // audioData 事件的样本数
+});
+
+// 音频混音配置
+export const AudioMixerConfigSchema = z.object({
+  operatorId: z.string(),
+  audioData: z.instanceof(Float32Array).optional(), // 实际数据在运行时传递
+  targetPlaybackTime: z.number(), // 目标播放时间戳 (ms)
+  volumeGain: z.number().min(0).max(10).default(1.0),
+});
+
+// 音频音量控制
+export const VolumeGainSchema = z.object({
+  gain: z.number().min(0.001).max(10), // 线性增益
+  gainDb: z.number().min(-60).max(20), // dB 单位增益
+});
+
+// 导出类型
+export type AudioDevice = z.infer<typeof AudioDeviceSchema>;
+export type AudioDevicesResponse = z.infer<typeof AudioDevicesResponseSchema>;
+export type AudioDeviceSettings = z.infer<typeof AudioDeviceSettingsSchema>;
+export type AudioDeviceSettingsResponse = z.infer<typeof AudioDeviceSettingsResponseSchema>;
+export type AudioStreamConfig = z.infer<typeof AudioStreamConfigSchema>;
+export type AudioStreamEventData = z.infer<typeof AudioStreamEventDataSchema>;
+export type AudioMixerConfig = z.infer<typeof AudioMixerConfigSchema>;
+export type VolumeGain = z.infer<typeof VolumeGainSchema>; 

package/src/schema/auth.schema.ts

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+import { PermissionGrantSchema } from './ability.js';
+
+// ===== 角色枚举 =====
+
+export enum UserRole {
+  VIEWER = 'viewer',
+  OPERATOR = 'operator',
+  ADMIN = 'admin',
+}
+
+/** 角色权限等级（用于比较） */
+export const USER_ROLE_LEVEL: Record<UserRole, number> = {
+  [UserRole.VIEWER]: 0,
+  [UserRole.OPERATOR]: 1,
+  [UserRole.ADMIN]: 2,
+};
+
+// ===== Token 数据结构（持久化） =====
+
+export const AuthTokenSchema = z.object({
+  id: z.string(),
+  tokenHash: z.string(),
+  tokenPlain: z.string().optional(), // plaintext stored so admins can retrieve it later
+  label: z.string(),
+  role: z.nativeEnum(UserRole),
+  operatorIds: z.array(z.string()),
+  createdBy: z.string().nullable(),
+  createdAt: z.number(),
+  expiresAt: z.number().optional(),
+  lastUsedAt: z.number().optional(),
+  revoked: z.boolean(),
+  system: z.boolean().optional(),
+  maxOperators: z.number().min(0).optional(), // 该 Token 可创建的操作员上限
+  permissionGrants: z.array(PermissionGrantSchema).optional(), // CASL permission grants
+  allowSelfLoginCredential: z.boolean().optional(),
+  loginCredential: z.object({
+    username: z.string(),
+    usernameNormalized: z.string(),
+    passwordHash: z.string(),
+    updatedAt: z.number(),
+  }).optional(),
+});
+
+export type AuthToken = z.infer<typeof AuthTokenSchema>;
+
+// ===== JWT Payload =====
+
+export const JWTPayloadSchema = z.object({
+  tokenId: z.string(),
+  role: z.nativeEnum(UserRole),
+  operatorIds: z.array(z.string()),
+  iat: z.number(),
+  exp: z.number(),
+});
+
+export type JWTPayload = z.infer<typeof JWTPayloadSchema>;
+
+// ===== 登录请求/响应 =====
+
+export const LoginRequestSchema = z.object({
+  token: z.string().min(1),
+});
+
+export type LoginRequest = z.infer<typeof LoginRequestSchema>;
+
+export const PasswordLoginRequestSchema = z.object({
+  username: z.string().trim().min(3).max(32),
+  password: z.string().min(1),
+});
+
+export type PasswordLoginRequest = z.infer<typeof PasswordLoginRequestSchema>;
+
+export const LoginResponseSchema = z.object({
+  jwt: z.string(),
+  role: z.nativeEnum(UserRole),
+  label: z.string(),
+  operatorIds: z.array(z.string()),
+  maxOperators: z.number().optional(),
+  permissionGrants: z.array(PermissionGrantSchema).optional(),
+});
+
+export type LoginResponse = z.infer<typeof LoginResponseSchema>;
+
+// ===== Token 管理（Admin API） =====
+
+export const LoginCredentialSummarySchema = z.object({
+  username: z.string(),
+  allowSelfService: z.boolean(),
+});
+
+export type LoginCredentialSummary = z.infer<typeof LoginCredentialSummarySchema>;
+
+export const AuthMeLoginCredentialSchema = z.object({
+  configured: z.boolean(),
+  username: z.string().nullable(),
+  allowSelfService: z.boolean(),
+});
+
+export type AuthMeLoginCredential = z.infer<typeof AuthMeLoginCredentialSchema>;
+
+export const CreateTokenLoginCredentialRequestSchema = z.object({
+  username: z.string().trim().min(3).max(32).regex(/^[A-Za-z0-9._-]+$/),
+  password: z.string().min(8).max(128),
+});
+
+export type CreateTokenLoginCredentialRequest = z.infer<typeof CreateTokenLoginCredentialRequestSchema>;
+
+export const UpdateTokenLoginCredentialRequestSchema = z.object({
+  username: z.string().trim().min(3).max(32).regex(/^[A-Za-z0-9._-]+$/),
+  password: z.string().min(8).max(128).optional(),
+});
+
+export type UpdateTokenLoginCredentialRequest = z.infer<typeof UpdateTokenLoginCredentialRequestSchema>;
+
+export const CreateTokenRequestSchema = z.object({
+  label: z.string().min(1).max(100),
+  role: z.nativeEnum(UserRole),
+  operatorIds: z.array(z.string()),
+  expiresAt: z.number().optional(),
+  maxOperators: z.number().min(0), // 必选，0 表示不限制
+  permissionGrants: z.array(PermissionGrantSchema).optional(),
+  allowSelfLoginCredential: z.boolean().optional(),
+  loginCredential: CreateTokenLoginCredentialRequestSchema.optional(),
+});
+
+export type CreateTokenRequest = z.infer<typeof CreateTokenRequestSchema>;
+
+export const CreateTokenResponseSchema = z.object({
+  id: z.string(),
+  token: z.string(),
+  label: z.string(),
+  role: z.nativeEnum(UserRole),
+  operatorIds: z.array(z.string()),
+  maxOperators: z.number().optional(),
+  permissionGrants: z.array(PermissionGrantSchema).optional(),
+  allowSelfLoginCredential: z.boolean().optional(),
+  loginCredential: LoginCredentialSummarySchema.optional(),
+});
+
+export type CreateTokenResponse = z.infer<typeof CreateTokenResponseSchema>;
+
+export const TokenInfoSchema = z.object({
+  id: z.string(),
+  token: z.string().optional(), // plaintext token value (admin only)
+  label: z.string(),
+  role: z.nativeEnum(UserRole),
+  operatorIds: z.array(z.string()),
+  createdBy: z.string().nullable(),
+  createdAt: z.number(),
+  expiresAt: z.number().optional(),
+  lastUsedAt: z.number().optional(),
+  revoked: z.boolean(),
+  system: z.boolean().optional(),
+  maxOperators: z.number().optional(),
+  permissionGrants: z.array(PermissionGrantSchema).optional(),
+  allowSelfLoginCredential: z.boolean().optional(),
+  loginCredential: LoginCredentialSummarySchema.optional(),
+});
+
+export type TokenInfo = z.infer<typeof TokenInfoSchema>;
+
+export const UpdateTokenRequestSchema = z.object({
+  label: z.string().min(1).max(100).optional(),
+  role: z.nativeEnum(UserRole).optional(),
+  operatorIds: z.array(z.string()).optional(),
+  expiresAt: z.number().nullable().optional(),
+  maxOperators: z.number().min(0).nullable().optional(), // null 表示移除限制
+  permissionGrants: z.array(PermissionGrantSchema).nullable().optional(), // null to clear
+  allowSelfLoginCredential: z.boolean().optional(),
+  loginCredential: UpdateTokenLoginCredentialRequestSchema.nullable().optional(),
+});
+
+export type UpdateTokenRequest = z.infer<typeof UpdateTokenRequestSchema>;
+
+// ===== 认证状态（GET /api/auth/status） =====
+
+export const AuthStatusSchema = z.object({
+  enabled: z.boolean(),
+  allowPublicViewing: z.boolean(),
+});
+
+export type AuthStatus = z.infer<typeof AuthStatusSchema>;
+
+// ===== 当前用户信息（GET /api/auth/me） =====
+
+export const AuthMeResponseSchema = z.object({
+  role: z.nativeEnum(UserRole),
+  label: z.string(),
+  operatorIds: z.array(z.string()),
+  tokenId: z.string(),
+  maxOperators: z.number().optional(),
+  permissionGrants: z.array(PermissionGrantSchema).optional(),
+  loginCredential: AuthMeLoginCredentialSchema,
+});
+
+export type AuthMeResponse = z.infer<typeof AuthMeResponseSchema>;
+
+export const UpdateSelfLoginCredentialRequestSchema = z.object({
+  username: z.string().trim().min(3).max(32).regex(/^[A-Za-z0-9._-]+$/),
+  password: z.string().min(8).max(128).optional(),
+});
+
+export type UpdateSelfLoginCredentialRequest = z.infer<typeof UpdateSelfLoginCredentialRequestSchema>;
+
+// ===== 更新认证配置请求（PATCH /api/auth/config） =====
+
+export const UpdateAuthConfigRequestSchema = z.object({
+  allowPublicViewing: z.boolean().optional(),
+});
+
+export type UpdateAuthConfigRequest = z.infer<typeof UpdateAuthConfigRequestSchema>;
+
+// ===== 认证配置（持久化到 auth.json） =====
+
+export const AuthConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  allowPublicViewing: z.boolean().default(true),
+  jwtSecret: z.string().optional(),
+  jwtExpiresInSeconds: z.number().default(7 * 24 * 3600), // 7 days
+  tokens: z.array(AuthTokenSchema).default([]),
+});
+
+export type AuthConfig = z.infer<typeof AuthConfigSchema>;

package/src/schema/cycle.schema.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+/**
+ * FT8周期枚举
+ */
+export enum FT8Cycle {
+  EVEN = 0,
+  ODD = 1
+}
+
+/**
+ * 周期信息
+ */
+export const CycleInfoSchema = z.object({
+  /** 当前周期 */
+  cycle: z.number(),
+  /** 是否为发射周期 */
+  isTransmit: z.boolean(),
+  /** 周期开始时间（毫秒时间戳） */
+  startTime: z.number(),
+  /** 周期结束时间（毫秒时间戳） */
+  endTime: z.number()
+});
+
+export type CycleInfo = z.infer<typeof CycleInfoSchema>; 

package/src/schema/desktop-https.schema.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+export const DesktopHttpsModeSchema = z.enum(['self-signed', 'imported-pem']);
+export type DesktopHttpsMode = z.infer<typeof DesktopHttpsModeSchema>;
+
+export const DesktopHttpsCertificateStatusSchema = z.enum(['missing', 'valid', 'invalid']);
+export type DesktopHttpsCertificateStatus = z.infer<typeof DesktopHttpsCertificateStatusSchema>;
+
+export const DesktopHttpsAccessSchemeSchema = z.enum(['http', 'https']);
+export type DesktopHttpsAccessScheme = z.infer<typeof DesktopHttpsAccessSchemeSchema>;
+
+export const DesktopHttpsCertificateMetaSchema = z.object({
+  source: DesktopHttpsModeSchema,
+  subject: z.string().nullable(),
+  issuer: z.string().nullable(),
+  validFrom: z.string().nullable(),
+  validTo: z.string().nullable(),
+  fingerprintSha256: z.string().nullable(),
+  altNames: z.array(z.string()).default([]),
+  createdAt: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+});
+export type DesktopHttpsCertificateMeta = z.infer<typeof DesktopHttpsCertificateMetaSchema>;
+
+export const DesktopHttpsSettingsSchema = z.object({
+  enabled: z.boolean().default(false),
+  mode: DesktopHttpsModeSchema.default('self-signed'),
+  httpsPort: z.number().int().min(1).max(65535).default(8443),
+  redirectExternalHttp: z.boolean().default(true),
+});
+export type DesktopHttpsSettings = z.infer<typeof DesktopHttpsSettingsSchema>;
+
+export const DesktopHttpsStatusSchema = DesktopHttpsSettingsSchema.extend({
+  activeScheme: DesktopHttpsAccessSchemeSchema.default('http'),
+  browserAccessUrl: z.string().nullable(),
+  shareUrls: z.array(z.string()).default([]),
+  certificateStatus: DesktopHttpsCertificateStatusSchema.default('missing'),
+  certificateMeta: DesktopHttpsCertificateMetaSchema.nullable(),
+  usingSelfSigned: z.boolean().default(false),
+  needsCertificate: z.boolean().default(true),
+});
+export type DesktopHttpsStatus = z.infer<typeof DesktopHttpsStatusSchema>;
+