forked from datawhale/whale-town-end
3dd5f23d79
- Standardize author attribution across 27 files in the Zulip integration module - Maintain consistent code documentation and authorship tracking
515 lines
10 KiB
TypeScript
515 lines
10 KiB
TypeScript
/**
|
||
* Zulip集成系统接口定义
|
||
*
|
||
* 功能描述：
|
||
* - 定义Zulip集成系统中使用的所有接口和类型
|
||
* - 提供类型安全和代码提示支持
|
||
* - 统一数据结构定义
|
||
*
|
||
* @author angjustinl
|
||
* @version 1.0.0
|
||
* @since 2025-12-25
|
||
*/
|
||
|
||
/**
|
||
* 游戏协议消息接口
|
||
*/
|
||
export namespace GameProtocol {
|
||
/**
|
||
* 登录消息接口
|
||
*/
|
||
export interface LoginMessage {
|
||
type: 'login';
|
||
token: string;
|
||
}
|
||
|
||
/**
|
||
* 聊天消息接口
|
||
*/
|
||
export interface ChatMessage {
|
||
t: 'chat';
|
||
content: string;
|
||
scope: string; // "local" 或 topic名称
|
||
}
|
||
|
||
/**
|
||
* 位置更新消息接口
|
||
*/
|
||
export interface PositionMessage {
|
||
t: 'position';
|
||
x: number;
|
||
y: number;
|
||
mapId: string;
|
||
}
|
||
|
||
/**
|
||
* 聊天渲染消息接口 - 发送给客户端
|
||
*/
|
||
export interface ChatRenderMessage {
|
||
t: 'chat_render';
|
||
from: string;
|
||
txt: string;
|
||
bubble: boolean;
|
||
}
|
||
|
||
/**
|
||
* 登录成功消息接口
|
||
*/
|
||
export interface LoginSuccessMessage {
|
||
t: 'login_success';
|
||
sessionId: string;
|
||
currentMap: string;
|
||
}
|
||
|
||
/**
|
||
* 错误消息接口
|
||
*/
|
||
export interface ErrorMessage {
|
||
t: 'error';
|
||
message: string;
|
||
code?: string;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Zulip API接口
|
||
*/
|
||
export namespace ZulipAPI {
|
||
/**
|
||
* Zulip消息接口
|
||
*/
|
||
export interface Message {
|
||
id: number;
|
||
sender_email: string;
|
||
sender_full_name: string;
|
||
content: string;
|
||
stream_id: number;
|
||
subject: string;
|
||
timestamp: number;
|
||
}
|
||
|
||
/**
|
||
* Zulip事件接口
|
||
*/
|
||
export interface Event {
|
||
type: string;
|
||
message?: Message;
|
||
queue_id: string;
|
||
}
|
||
|
||
/**
|
||
* Zulip Stream接口
|
||
*/
|
||
export interface Stream {
|
||
stream_id: number;
|
||
name: string;
|
||
description: string;
|
||
}
|
||
|
||
/**
|
||
* 发送消息请求接口
|
||
*/
|
||
export interface SendMessageRequest {
|
||
type: 'stream';
|
||
to: string;
|
||
subject: string;
|
||
content: string;
|
||
}
|
||
|
||
/**
|
||
* 事件队列注册请求接口
|
||
*/
|
||
export interface RegisterQueueRequest {
|
||
event_types: string[];
|
||
narrow?: Array<[string, string]>;
|
||
}
|
||
|
||
/**
|
||
* 事件队列响应接口
|
||
*/
|
||
export interface RegisterQueueResponse {
|
||
queue_id: string;
|
||
last_event_id: number;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 系统内部接口
|
||
*/
|
||
export namespace Internal {
|
||
/**
|
||
* 位置信息接口
|
||
*/
|
||
export interface Position {
|
||
x: number;
|
||
y: number;
|
||
}
|
||
|
||
/**
|
||
* 游戏会话接口
|
||
*
|
||
* 功能描述：
|
||
* - 维护WebSocket连接ID与Zulip队列ID的映射关系
|
||
* - 跟踪玩家位置和地图信息
|
||
* - 支持会话状态的序列化和反序列化
|
||
*
|
||
* Redis存储结构：
|
||
* - Key: zulip:session:{socketId}
|
||
* - Value: JSON序列化的GameSession对象
|
||
* - TTL: 3600秒（1小时）
|
||
*
|
||
* @since 2025-12-25
|
||
*/
|
||
export interface GameSession {
|
||
socketId: string; // WebSocket连接ID
|
||
userId: string; // 用户ID
|
||
username: string; // 用户名
|
||
zulipQueueId: string; // Zulip事件队列ID (关键绑定)
|
||
currentMap: string; // 当前地图ID
|
||
position: Position; // 当前位置
|
||
lastActivity: Date; // 最后活动时间
|
||
createdAt: Date; // 会话创建时间
|
||
}
|
||
|
||
/**
|
||
* 游戏会话序列化格式（用于Redis存储）
|
||
*/
|
||
export interface GameSessionSerialized {
|
||
socketId: string;
|
||
userId: string;
|
||
username: string;
|
||
zulipQueueId: string;
|
||
currentMap: string;
|
||
position: Position;
|
||
lastActivity: string; // ISO 8601格式的日期字符串
|
||
createdAt: string; // ISO 8601格式的日期字符串
|
||
}
|
||
|
||
/**
|
||
* 创建会话请求接口
|
||
*/
|
||
export interface CreateSessionRequest {
|
||
socketId: string;
|
||
userId: string;
|
||
username?: string;
|
||
zulipQueueId: string;
|
||
initialMap?: string;
|
||
initialPosition?: Position;
|
||
}
|
||
|
||
/**
|
||
* 会话统计信息接口
|
||
*/
|
||
export interface SessionStats {
|
||
totalSessions: number;
|
||
mapDistribution: Record<string, number>;
|
||
oldestSession?: Date;
|
||
newestSession?: Date;
|
||
}
|
||
|
||
/**
|
||
* Zulip客户端接口
|
||
*/
|
||
export interface ZulipClient {
|
||
userId: string;
|
||
apiKey: string;
|
||
queueId?: string;
|
||
client?: any;
|
||
createdAt: Date;
|
||
lastActivity: Date;
|
||
}
|
||
|
||
/**
|
||
* 地图配置接口
|
||
*
|
||
* 功能描述：
|
||
* - 定义游戏地图到Zulip Stream的映射关系
|
||
* - 包含地图内的交互对象配置
|
||
*
|
||
* 验证规则：
|
||
* - mapId: 必填，非空字符串，唯一标识
|
||
* - mapName: 必填，非空字符串，用于显示
|
||
* - zulipStream: 必填，非空字符串，对应Zulip Stream名称
|
||
* - interactionObjects: 可选，交互对象数组
|
||
*
|
||
* @since 2025-12-25
|
||
*/
|
||
export interface MapConfig {
|
||
mapId: string; // 地图ID (例如: "whale_port")
|
||
mapName: string; // 地图名称 (例如: "新手村")
|
||
zulipStream: string; // 对应的Zulip Stream (例如: "Whale Port")
|
||
description?: string; // 地图描述（可选）
|
||
interactionObjects: InteractionObject[]; // 交互对象配置
|
||
}
|
||
|
||
/**
|
||
* 交互对象接口
|
||
*
|
||
* 功能描述：
|
||
* - 定义地图内交互对象到Zulip Topic的映射关系
|
||
* - 包含对象位置信息用于空间过滤
|
||
*
|
||
* 验证规则：
|
||
* - objectId: 必填，非空字符串，唯一标识
|
||
* - objectName: 必填，非空字符串，用于显示
|
||
* - zulipTopic: 必填，非空字符串，对应Zulip Topic名称
|
||
* - position: 必填，包含有效的x和y坐标
|
||
*
|
||
* @since 2025-12-25
|
||
*/
|
||
export interface InteractionObject {
|
||
objectId: string; // 对象ID (例如: "notice_board")
|
||
objectName: string; // 对象名称 (例如: "公告板")
|
||
zulipTopic: string; // 对应的Zulip Topic (例如: "Notice Board")
|
||
position: { // 对象位置
|
||
x: number;
|
||
y: number;
|
||
};
|
||
}
|
||
|
||
/**
|
||
* 地图配置文件结构接口
|
||
*
|
||
* 功能描述：
|
||
* - 定义配置文件的根结构
|
||
* - 用于配置文件的加载和验证
|
||
*
|
||
* @since 2025-12-25
|
||
*/
|
||
export interface MapConfigFile {
|
||
maps: MapConfig[]; // 地图配置数组
|
||
version?: string; // 配置版本（可选）
|
||
lastModified?: string; // 最后修改时间（可选）
|
||
}
|
||
|
||
/**
|
||
* 配置验证结果接口
|
||
*
|
||
* 功能描述：
|
||
* - 定义配置验证的结果结构
|
||
* - 包含验证状态和错误信息
|
||
*
|
||
* @since 2025-12-25
|
||
*/
|
||
export interface ConfigValidationResult {
|
||
valid: boolean; // 是否有效
|
||
errors: string[]; // 错误信息列表
|
||
warnings?: string[]; // 警告信息列表（可选）
|
||
}
|
||
|
||
/**
|
||
* 配置统计信息接口
|
||
*
|
||
* 功能描述：
|
||
* - 定义配置统计信息的结构
|
||
* - 用于监控和调试
|
||
*
|
||
* @since 2025-12-25
|
||
*/
|
||
export interface ConfigStats {
|
||
mapCount: number; // 地图数量
|
||
totalObjects: number; // 交互对象总数
|
||
configLoadTime: Date; // 配置加载时间
|
||
isValid: boolean; // 配置是否有效
|
||
}
|
||
|
||
/**
|
||
* 上下文信息接口
|
||
*/
|
||
export interface ContextInfo {
|
||
stream: string;
|
||
topic?: string;
|
||
}
|
||
|
||
/**
|
||
* 消息过滤结果接口
|
||
*/
|
||
export interface ContentFilterResult {
|
||
allowed: boolean;
|
||
filtered?: string;
|
||
reason?: string;
|
||
}
|
||
|
||
/**
|
||
* 错误处理结果接口
|
||
*/
|
||
export interface ErrorHandlingResult {
|
||
success: boolean;
|
||
shouldRetry: boolean;
|
||
retryAfter?: number;
|
||
degradedMode?: boolean;
|
||
message: string;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 服务请求接口
|
||
*/
|
||
export namespace ServiceRequests {
|
||
/**
|
||
* 玩家登录请求
|
||
*/
|
||
export interface PlayerLoginRequest {
|
||
token: string;
|
||
socketId: string;
|
||
}
|
||
|
||
/**
|
||
* 聊天消息请求
|
||
*/
|
||
export interface ChatMessageRequest {
|
||
socketId: string;
|
||
content: string;
|
||
scope: string;
|
||
}
|
||
|
||
/**
|
||
* 位置更新请求
|
||
*/
|
||
export interface PositionUpdateRequest {
|
||
socketId: string;
|
||
x: number;
|
||
y: number;
|
||
mapId: string;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 服务响应接口
|
||
*/
|
||
export namespace ServiceResponses {
|
||
/**
|
||
* 基础响应接口
|
||
*/
|
||
export interface BaseResponse {
|
||
success: boolean;
|
||
error?: string;
|
||
}
|
||
|
||
/**
|
||
* 登录响应
|
||
*/
|
||
export interface LoginResponse extends BaseResponse {
|
||
sessionId?: string;
|
||
}
|
||
|
||
/**
|
||
* 聊天消息响应
|
||
*/
|
||
export interface ChatMessageResponse extends BaseResponse {
|
||
messageId?: string;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 配置接口
|
||
*/
|
||
export namespace Config {
|
||
/**
|
||
* Zulip配置接口
|
||
*/
|
||
export interface ZulipConfig {
|
||
zulipServerUrl: string;
|
||
zulipBotEmail: string;
|
||
zulipBotApiKey: string;
|
||
websocketPort: number;
|
||
websocketNamespace: string;
|
||
messageRateLimit: number;
|
||
messageMaxLength: number;
|
||
sessionTimeout: number;
|
||
cleanupInterval: number;
|
||
enableContentFilter: boolean;
|
||
allowedStreams: string[];
|
||
}
|
||
|
||
/**
|
||
* 重试配置接口
|
||
*/
|
||
export interface RetryConfig {
|
||
maxRetries: number;
|
||
baseDelay: number;
|
||
maxDelay: number;
|
||
backoffMultiplier: number;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 枚举定义
|
||
*/
|
||
export namespace Enums {
|
||
/**
|
||
* 服务状态枚举
|
||
*/
|
||
export enum ServiceStatus {
|
||
NORMAL = 'normal',
|
||
DEGRADED = 'degraded',
|
||
UNAVAILABLE = 'unavailable',
|
||
}
|
||
|
||
/**
|
||
* 错误类型枚举
|
||
*/
|
||
export enum ErrorType {
|
||
ZULIP_API_ERROR = 'zulip_api_error',
|
||
CONNECTION_ERROR = 'connection_error',
|
||
TIMEOUT_ERROR = 'timeout_error',
|
||
AUTHENTICATION_ERROR = 'authentication_error',
|
||
RATE_LIMIT_ERROR = 'rate_limit_error',
|
||
UNKNOWN_ERROR = 'unknown_error',
|
||
}
|
||
|
||
/**
|
||
* 违规类型枚举
|
||
*/
|
||
export enum ViolationType {
|
||
CONTENT = 'content',
|
||
RATE = 'rate',
|
||
PERMISSION = 'permission',
|
||
}
|
||
|
||
/**
|
||
* 消息范围枚举
|
||
*/
|
||
export enum MessageScope {
|
||
LOCAL = 'local',
|
||
GLOBAL = 'global',
|
||
TOPIC = 'topic',
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 常量定义
|
||
*/
|
||
export namespace Constants {
|
||
/**
|
||
* Redis键前缀
|
||
*/
|
||
export const REDIS_PREFIXES = {
|
||
SESSION: 'zulip:session:',
|
||
MAP_PLAYERS: 'zulip:map_players:',
|
||
RATE_LIMIT: 'zulip:rate_limit:',
|
||
VIOLATION: 'zulip:violation:',
|
||
} as const;
|
||
|
||
/**
|
||
* 默认配置值
|
||
*/
|
||
export const DEFAULTS = {
|
||
SESSION_TIMEOUT: 3600, // 1小时
|
||
RATE_LIMIT: 10, // 每分钟10条消息
|
||
RATE_LIMIT_WINDOW: 60, // 60秒窗口
|
||
MESSAGE_MAX_LENGTH: 1000,
|
||
RETRY_MAX_ATTEMPTS: 3,
|
||
RETRY_BASE_DELAY: 1000,
|
||
WEBSOCKET_NAMESPACE: '/game',
|
||
} as const;
|
||
|
||
/**
|
||
* 默认地图配置
|
||
*/
|
||
export const DEFAULT_MAPS = {
|
||
NOVICE_VILLAGE: 'novice_village',
|
||
TAVERN: 'tavern',
|
||
MARKET: 'market',
|
||
} as const;
|
||
} |