# 接口冻结文档（Interface Freeze）
本文档定义了MCP串口工具所有模块、类、函数的接口规范，作为开发阶段的契约和指导。
## 1. 核心引擎层接口（Core Layer）
### 1.1 SerialEngine（串口引擎）
```typescript
interface ISerialEngine {
// 端口管理
openPort(config: PortConfig): Promise<SerialPortInfo>;
closePort(port: string): Promise<void>;
getPortStatus(port: string): PortStatus;
// 数据操作（带会话隔离）
writeAndRead(
port: string,
data: Buffer,
timeout: number,
sessionId: string
): Promise<ReadResult>;
// 事件订阅
subscribe(
port: string,
types: EventType[],
listener: EventListener
): Subscription;
unsubscribe(subscriptionId: string): void;
}
```
### 1.2 EventBus（事件总线）
```typescript
interface IEventBus {
publish<T extends EventType>(type: T, event: EventMap[T]): void;
subscribe<T extends EventType>(type: T, handler: EventHandler<T>): string;
unsubscribe(subscriptionId: string): void;
once<T extends EventType>(type: T, handler: EventHandler<T>): string;
clear(): void;
}
```
### 1.3 DataProcessor（数据处理器）
```typescript
interface IDataProcessor {
hexToBuffer(hex: string): Buffer;
bufferToHex(buffer: Buffer): string;
bufferToText(buffer: Buffer, encoding?: string): string;
textToBuffer(text: string, encoding?: string): Buffer;
splitData(data: Buffer, delimiter: Buffer[]): Buffer[];
validateData(data: Buffer, rules: any): boolean;
}
```
### 1.4 WriteMutex（写入互斥锁）
```typescript
interface IWriteMutex {
acquire(port: string, timeoutMs: number): Promise<LockTicket>;
release(port: string, ticket: LockTicket): void;
getLockInfo(port: string): LockInfo;
forceRelease(port: string): void;
}
```
### 1.5 PortSession（端口会话）
```typescript
interface IPortSession {
createSession(port: string, options?: SessionOptions): SessionContext;
endSession(sessionId: string): void;
getSession(sessionId: string): SessionContext | null;
getActiveSession(port: string): string | null;
isSessionData(data: Buffer, sessionId: string): boolean;
extractURC(data: Buffer, port: string): { urc: string[]; data: Buffer };
cleanupExpired(): void;
}
```
### 1.6 URCDetector（URC识别器）
```typescript
interface IURCDetector {
loadConfig(configPath: string): Promise<void>;
reloadConfig(): Promise<void>;
isURC(line: string, port?: string): boolean;
extract(data: Buffer, port?: string): { urc: string[]; data: Buffer };
getConfig(): URCConfig;
addPattern(pattern: string | RegExp, description?: string): void;
removePattern(id: string): void;
}
```
## 2. 适配器层接口（Adapter Layer）
### 2.1 SerialPortAdapter（串口适配器）
```typescript
interface ISerialPortAdapter {
open(config: PortConfig): Promise<void>;
close(): Promise<void>;
write(data: Buffer): Promise<void>;
drain(): Promise<void>;
flush(): Promise<void>;
set(options: any): Promise<void>;
get(): Promise<any>;
on(event: string, handler: Function): void;
off(event: string, handler: Function): void;
isOpen(): boolean;
}
```
### 2.2 PlatformAdapter（平台适配器）
```typescript
interface IPlatformAdapter {
listPorts(): Promise<SerialPortInfo[]>;
checkPermissions(): Promise<boolean>;
getPlatformInfo(): PlatformInfo;
}
```
## 3. 服务层接口（Service Layer）
### 3.1 SerialService（串口服务）
```typescript
interface ISerialService {
openPort(config: SerialOpenRequest): Promise<SerialOpenResponse>;
closePort(request: SerialCloseRequest): Promise<SerialCloseResponse>;
writeAndRead(request: SerialWriteRequest): Promise<SerialWriteResponse>;
listPorts(): Promise<SerialListResponse>;
getPortStatus(request: SerialStatusRequest): Promise<SerialStatusResponse>;
subscribe(clientId: string, request: SerialSubscribeRequest): Promise<SerialSubscribeResponse>;
unsubscribe(clientId: string, subscriptionId: string): Promise<void>;
}
```
### 3.2 LogService（日志服务）
```typescript
interface ILogService {
log(level: string, message: string, meta?: any): void;
getLogs(query: TraceGetLogRequest): Promise<TraceGetLogResponse>;
clearLogs(port?: string): Promise<void>;
rotateLogs(): Promise<void>;
}
```
### 3.3 HealthService（健康检查服务）
```typescript
interface IHealthService {
getStatus(): Promise<HealthStatusResponse>;
getMetrics(): Promise<HealthMetricsResponse>;
startMonitoring(): void;
stopMonitoring(): void;
}
```
## 4. MCP协议层接口（MCP Layer）
### 4.1 MCPServer（MCP服务器）
```typescript
interface IMCPServer {
start(): Promise<void>;
stop(): Promise<void>;
registerMethod(name: string, handler: MethodHandler): void;
unregisterMethod(name: string): void;
sendNotification(method: string, params: any): void;
getServerInfo(): MCPServerInfo;
}
```
### 4.2 MethodRouter（方法路由器）
```typescript
interface IMethodRouter {
register(methodName: string, handler: MethodHandler): void;
unregister(methodName: string): void;
route(methodName: string, params: any): Promise<any>;
hasMethod(methodName: string): boolean;
getRegisteredMethods(): string[];
}
```
### 4.3 NotificationManager（通知管理器）
```typescript
interface INotificationManager {
subscribe(clientId: string, subscription: any): void;
unsubscribe(clientId: string, subscriptionId: string): void;
sendNotification(method: string, params: any, filter?: (clientId: string) => boolean): void;
getSubscriptions(clientId: string): any[];
}
```
## 5. 工具模块接口（Utils）
### 5.1 Logger（日志器）
```typescript
interface ILogger {
debug(message: string, meta?: any): void;
info(message: string, meta?: any): void;
warn(message: string, meta?: any): void;
error(message: string, error?: Error, meta?: any): void;
setLevel(level: string): void;
createChild(context: string): ILogger;
}
```
### 5.2 ConfigManager（配置管理器）
```typescript
interface IConfigManager {
load<T>(path: string): Promise<T>;
save<T>(path: string, data: T): Promise<void>;
watch(path: string, callback: (data: any) => void): void;
get<T>(key: string): T;
set(key: string, value: any): void;
}
```
## 6. 数据类型定义
### 6.1 核心数据类型
- `PortConfig` - 串口配置
- `SerialPortInfo` - 串口信息
- `PortStatus` - 串口状态
- `ReadResult` - 读取结果
- `SessionContext` - 会话上下文
- `LockTicket` - 锁票据
- `URCConfig` - URC配置
### 6.2 事件类型
- `EventType` - 事件类型枚举
- `EventMap` - 事件映射
- `EventHandler` - 事件处理器
- `Subscription` - 订阅信息
### 6.3 MCP协议类型
- `JSONRPCRequest` - JSON-RPC请求
- `JSONRPCResponse` - JSON-RPC响应
- `JSONRPCNotification` - JSON-RPC通知
- `SerialOpenRequest/Response` - 串口打开请求/响应
- `SerialWriteRequest/Response` - 串口写入请求/响应
- `SerialReportNotification` - 串口报告通知
## 7. 错误类型定义
```typescript
class SerialError extends Error {
constructor(code: string, message: string, port?: string, details?: any);
}
class ConfigError extends Error {
constructor(message: string, path?: string, details?: any);
}
class URCError extends Error {
constructor(message: string, patternId?: string, data?: string);
}
```
## 8. 实现约束
1. **接口不可变更**：接口冻结后，任何修改必须经过评审
2. **类型安全**：所有实现必须严格遵循TypeScript类型定义
3. **错误处理**：所有方法必须正确抛出定义的异常类型
4. **异步规范**：所有IO操作必须返回Promise
5. **事件规范**：事件发布必须符合EventMap定义
6. **生命周期**：资源管理必须实现IDisposable接口
## 9. 测试约束
1. **接口测试**：每个接口必须有对应的单元测试
2. **Mock规范**：测试时必须使用接口定义创建Mock对象
3. **覆盖要求**：接口方法覆盖率必须达到100%
4. **异常测试**：必须测试所有错误路径和异常情况
## 10. 版本控制
- 当前接口版本：v1.0
- 向后兼容策略：小版本更新保持兼容，大版本更新可能不兼容
- 变更流程：接口变更 → 文档更新 → 评审 → 批准 → 实施