星枢终端 - 技术债务报告
状态：✅ 已修复债务全部收敛 | 测试覆盖率：待提升 | 更新时间：2026-05-15
覆盖率现状
| 模块 | 行覆盖率 | 分支覆盖率 | 函数覆盖率 | 门禁阈值 | 状态 |
|---|---|---|---|---|---|
| backend | 43.98% | 78.22% | 83.64% | lines≥40%, branches≥50%, funcs≥70% | ✅ 达标 |
| frontend | 29.65% | 78.56% | 63.08% | lines≥90%, branches≥90%, funcs≥90% | ❌ 未达标 |
| remote-gateway | 33.19% | 61.11% | 75% | — | ⚠️ 待评估 |
后端覆盖率分层目标
后端当前 43.98% 已过门禁，但存在大量 0% 覆盖文件。按分层架构约定，controller/routes 属薄层委托，优先级低于 service/repository。
P0：0% 覆盖的核心业务文件（需优先补充测试）
| 文件 | 类型 | 行数 | 说明 |
|---|---|---|---|
ai.controller.ts | controller | 254 | AI 会话管理，零测试 |
batch.service.ts | service | 922 | 批量执行核心逻辑，仅 22.42% |
websocket.ts | 入口 | 67 | WebSocket 初始化，零测试 |
migrations.ts | 数据库 | 601 | 数据迁移脚本，零测试 |
connection.ts (database) | 数据库 | 211 | 数据库连接管理，零测试 |
upgrade.ts | 数据库 | 168 | 数据库升级逻辑，零测试 |
ssh-suspend/service.ts | service | — | 仅 27.65%，核心挂起恢复逻辑 |
P1：低覆盖 service/repository（<50%）
| 文件 | 覆盖率 | 目标 | 测试要点 |
|---|---|---|---|
batch.service.ts | 22.42% | 70% | 任务创建/执行/取消/超时/并发控制 |
sftp-utils.ts | 7.79% | 60% | 路径校验、权限计算、文件类型判断 |
connection.repository.ts | 8.88% | 60% | CRUD、批量操作、加密字段处理 |
video.service.ts | 30.89% | 60% | VNC 会话生命周期 |
nl2cmd.service.ts | 48.38% | 70% | NL2CMD 解析、缓存、降级 |
dashboard.service.ts | 44.24% | 60% | 统计聚合、时间线、资产健康 |
P2：controller 层集成测试（优先级较低）
controller 属薄层委托，测试通过 service 层间接覆盖。如需直接测试：
- 使用 supertest 覆盖路由参数校验、权限检查、错误码映射
- 重点：
auth.controller.ts（1445 行拆分后）、connections.controller.ts
前端覆盖率分层目标
前端当前 29.65%，距 90% 门禁差距巨大。按组件/Store/工具/视图分层提升。
P0：0% 覆盖的 Store actions（核心状态管理）
| 文件 | 说明 | 测试要点 |
|---|---|---|
session/store/actions/sendActions.ts (895 行) | 命令发送核心 | 命令队列、重试、超时、中断 |
session/store/actions/sessionActions.ts (410 行) | 会话生命周期 | 创建/恢复/挂起/断开/清理 |
session/store/actions/editorActions.ts | 编辑器操作 | 打开/保存/关闭/语言检测 |
session/store/getters.ts (62 行) | 派生状态 | 活跃标签、连接状态、统计 |
session/store/utils.ts (112 行) | 工具函数 | 状态序列化、ID 生成 |
notificationSettings.store.ts (137 行) | 通知配置 | CRUD、启用/禁用、验证 |
dialog.store.ts (84 行) | 对话框状态 | 打开/关闭/确认/取消回调 |
P1：0% 覆盖的 Composables（核心交互逻辑）
| 文件 | 行数 | 测试要点 |
|---|---|---|
useTerminalFit.ts | 157 | 终端尺寸计算、ResizeObserver、防抖 |
useTerminalEvents.ts | 266 | 终端事件绑定/解绑、数据流 |
useTerminalSocket.ts | 49 | WebSocket 连接/重连/心跳 |
useFileUploader.ts | 370 | 分块上传、进度、取消、断点续传 |
useEditorEvents.ts | 261 | Monaco 编辑器事件、快捷键 |
useFormSubmit.ts | 349 | 表单提交、校验、错误处理 |
useFormParsers.ts | 338 | 表单数据解析/序列化 |
useAddConnectionForm.ts 子模块 | — | Parsers/Submit/Tags/Test 各子模块 |
useWorkspaceSearch.ts | 115 | 工作区搜索、过滤、高亮 |
useDragAndDrop.ts | 422 | 拖拽排序、布局重排 |
useResizable.ts | 210 | 面板拖拽调整大小 |
useVersionCheck.ts | 81 | 版本检查、更新提示 |
useIpBlacklist.ts | 146 | IP 黑名单管理 |
P2：0% 覆盖的 Views（页面级测试）
| 文件 | 行数 | 测试策略 |
|---|---|---|
DashboardView.vue | 739 | 渲染统计卡片、图表加载、空状态 |
ConnectionsView.vue | 924 | 连接列表渲染、CRUD 操作流 |
SettingsView.vue | 已有 75% | 补充表单提交、验证 |
WorkspaceView.vue | 469 | 标签页管理、面板布局、快捷键 |
AuditLogView.vue | 257 | 日志列表、筛选、分页 |
NotificationsView.vue | 10 | 渲染检查 |
ProxiesView.vue | 75 | 代理列表渲染 |
QuickCommandsView.vue | 665 | 指令 CRUD、标签过滤 |
SuspendedSessionsView.vue | 291 | 挂起会话列表、恢复操作 |
LoginView.vue | 327 | 登录表单、2FA 流程 |
SetupView.vue | 176 | 初始设置向导 |
P3：0% 覆盖的 Components（组件级测试）
| 文件 | 行数 | 测试策略 |
|---|---|---|
Terminal.vue | 1082 | 渲染检查、主题切换、输入输出 |
FileManager.vue | 已有 66.7% | 补充右键菜单、批量操作 |
RemoteDesktopModal.vue | 808 | 模态框渲染、连接状态 |
VncModal.vue | 808 | VNC 连接渲染 |
MonacoEditor.vue | 已有 82.9% | 补充语言切换、保存 |
AddConnectionForm.vue | 419 | 表单字段、校验、提交 |
LayoutConfigurator.vue | 709 | 布局配置、拖拽 |
StyleCustomizer.vue | 238 | 主题定制、预览 |
TerminalTabBar.vue | 606 | 标签页切换、关闭、排序 |
StatusMonitor.vue | 457 | 状态监控渲染 |
StatusCharts.vue | 521 | 图表渲染 |
已修复债务清单（完整记录）
Critical（6/6）
| ID | 问题 | 修复方式 |
|---|---|---|
| C-1 | SFTP shell 命令注入 | 统一 shellEscape() 工具函数 |
| C-2 | PRAGMA SQL 拼接 | VALID_TABLE_NAME 正则白名单 |
| C-3 | 12 个 Pinia Store 零测试 | 新增 7 个 store 测试文件，覆盖率 88% |
| C-4 | clientStates 并发竞态 | per-session 锁 + CAS 模式 |
| C-5 | terminalOutputBuffer 无上限 | 10MB 上限 + 丢弃最旧条目 |
| C-6 | SSH 挂起日志路径遍历 | VALID_SUSPEND_ID 正则校验 |
High（21/21）
| ID | 问题 | 修复方式 |
|---|---|---|
| H-1 | SSRF 域名后缀匹配可绕过 | 精确匹配 hostname === domain |
| H-2 | Docker 命令注入 | 共享 sanitizeDockerContainerId() + isValidDockerCommand() |
| H-3 | 批量命令无审计日志 | 集成 AuditLogService.logAction() |
| H-4 | SFTP shell 转义不一致 | 统一 shellEscape() |
| H-5 | glob 依赖漏洞 | 升级至安全版本 |
| H-6 | 31 处空 catch 块 | 统一 console.debug/warn 记录 |
| H-7 | 170 个 catch 块未 error: unknown | 全面规范类型 |
| H-8 | auth.controller.ts 1445 行 | 拆分为 login/2fa/passkey handlers |
| H-9 | useAddConnectionForm.ts 1204 行 | 拆分为 Parsers/Submit/Tags/Test 子模块 |
| H-10 | useSftpActions.ts 1319 行 | 拆分为 Operations + MessageHandlers |
| H-11 | StatusMonitorService 507 行 | 拆分为 HealthCheck/Aggregator/Service |
| H-12 | ssh.service.ts 递归跳板 207 行 | 拆分为 6 个辅助函数 |
| H-13 | 6 个后端模块缺 repository 层 | 分析确认 4 个无 DB 访问，2 个通过 service 层访问 |
| H-14 | appearance.store.ts 1073 行 | 拆分为 theme/font/background/html-presets 子 store |
| H-15 | settings.store.ts 1025 行 | 拆分为 system/security/layout 子 store |
| H-16 | SSH 挂起移交竞态 | isMarkedForSuspend CAS 模式 |
| H-17 | Silent exec 请求被覆盖 | 改用 requestId 作键 |
| H-18 | Silent exec 超时未发 Ctrl+C | 超时后先发 \x03 |
| H-19 | 定时器会话断开未清理 | cleanupClientConnection 遍历清理 |
| H-20 | cleanupClientConnection 未 catch | 所有调用点添加 .catch() |
| H-21 | SSH shell ready 无超时 | 10s 超时 + 补充测试 |
Medium（30/30）
| ID | 问题 | 修复方式 |
|---|---|---|
| M-1 | services/ 扁平堆放 14 个服务 | 确认为跨模块共享，架构合理 |
| M-2 | 事件监听泄漏比 1.76:1 | 审计 31 文件，修复 2 处缺失清理 |
| M-3 | useWebSocketConnection.ts 641 行 | 提取消息解析、重连为子模块 |
| M-4 | useSshTerminal.ts 522 行 | 提取缓冲管理、事件处理为子模块 |
| M-5 | transfers.service.ts 1435 行 | 确认拆分风险 > 收益，架构可接受 |
| M-6 | 前端 utils/ 零测试 | 新增 5 个测试文件，54 个用例 |
| M-7 | settings.controller.ts 30 重复 | 全面 asyncHandler 包装 |
| M-8 | auth/ 26 个扁平工具文件 | 按功能分组命名 |
| M-9 | 前端 router/ 零测试 | 路由守卫单元测试，覆盖 9 个路由 |
| M-10 | metrics/ 无 controller | 路由委托至 controller |
| M-11 | passkey/ 无 routes | 管理端点迁移至 passkey.routes |
| M-12 | connection.service.ts 61 处加解密 | batch encrypt/decrypt 辅助函数 |
| M-13 | 46 个 catch 块短变量名 | 统一规范 507 个 catch 块 |
| M-14 | 硬编码 OpenAI API URL | 提取为 AI_PROVIDER_DEFAULTS 常量 |
| M-15 | useFileUploader.ts 495 行 | 提取分块管理至 useUploadChunkManager.ts |
| M-16 | 硬编码审计日志最大条目 | DEFAULT_AUDIT_LOG_MAX_ENTRIES 常量 |
| M-17 | index.ts 598 行 | 精简至 379 行 |
| M-18 | Catch 块不传播错误 | 审计 55+ 处，40+ 已传播 |
| M-19 | Vue 模板嵌套 13 层 | 提取 SuspendedSessionItem 子组件 |
| M-20 | logging/middleware 零测试 | 新增 10 个测试 |
| M-21 | WebSocket 重连无 jitter | 添加随机抖动 |
| M-22 | SFTP 上传流未 close 可能泄漏 | 5s 超时回退 stream.destroy() |
| M-23 | SSH 挂起日志轮转丢弃历史 | 环形缓冲（100MB 上限，保留 80MB） |
| M-24 | 多设备会话状态不一致 | 注释说明行为 + API 端点 |
| M-25 | SFTP payload 用 z.any() | 10+ 个专用 Zod schema |
| M-26 | 无端口范围验证 | port >= 1 && port <= 65535 |
| M-27 | 无主机名格式验证 | 253 字符 + 合法域名/IPv6 正则 |
| M-28 | 注册无密码复杂度限制 | 用户名 3-64 字符 + 密码含字母数字 |
| M-29 | ssh:resize 无上限 | cols <= 1000 && rows <= 500 |
| M-30 | SFTP readdir 无分页 | 3MB 阈值分批发送 |
Low（27/27）
| ID | 问题 | 修复方式 |
|---|---|---|
| L-1 | Swagger 非生产环境暴露 | NODE_ENV=production 保护 |
| L-2 | uuid 依赖漏洞 | 升级至 v14 |
| L-3 | 错误消息泄露内部路径 | 生产环境返回通用消息 |
| L-4 | 硬编码 GitHub URL | GITHUB_REPO_URL 常量 |
| L-5 | 硬编码 CORS origin | 生产环境日志警告 |
| L-6 | Passkey 超时硬编码 | PASSKEY_CHALLENGE_TIMEOUT_MS |
| L-7 | SSH 重连延迟硬编码 | DEFAULT_SSH_RECONNECT_DELAY_MS |
| L-8 | SQLite PRAGMA 硬编码 | SQLITE_CACHE_SIZE_KB / SQLITE_MMAP_SIZE_BYTES |
| L-9 | loginBanDuration 字符串类型 | DEFAULT_LOGIN_BAN_DURATION_SECONDS（数字） |
| L-10 | output-processor.ts 零测试 | 新增 91 个测试 |
| L-11 | cacheManager.ts 零测试 | 新增 52 个测试 |
| L-12 | Docker handler 硬编码延迟 | DOCKER_STATUS_SYNC_DELAY_MS |
| L-13 | catch 变量命名不一致 | 统一为 error |
| L-14 | @types/node 版本落后 | 升级至 ^22 |
| L-15 | vuedraggable Vue 3 兼容性 | 确认 ^4.1.0 兼容 |
| L-16 | locales/ 翻译完整性零测试 | locale-keys.test.ts（6 tests） |
| L-17 | 5 个 composable 超 200 行 | 通过 H-10/M-3/M-4/M-15 拆分 |
| L-18 | 5 个 as any 断言 | 全部消除 |
| L-19 | lastPingTime 条目累积 | close/error/interval 中清理 |
| L-20 | requestIdleCallback Safari 兼容 | rAF 降级逻辑 |
| L-21 | Uint8Array 大拼接开销 | bufferManager 子模块管理 |
| L-22 | PWA SW 缓存过期状态 | SW_VERSION + 消息机制 |
| L-23 | DNS 解析失败消息不友好 | 捕获 ENOTFOUND/EAI_AGAIN 中文消息 |
| L-24 | 代理连接失败不区分目标 | 区分代理不可达/拒绝/目标不可达 |
| L-25 | flushPendingChunks 重入非原子 | Promise 锁 |
| L-26 | SFTP base64 无内存跟踪 | globalBufferedBytes 跟踪 |
| L-27 | WebSocket 出站无大小限制 | 3MB 阈值分批发送 |
Codex 审查补漏（7 项）
| ID | 级别 | 问题 | 修复内容 |
|---|---|---|---|
| C-readdir | CRITICAL | SFTP readdir 末尾 chunk 重复发送 | 移除多余条件，仅保留 isLast |
| C-readyState | CRITICAL | SFTP readdir 错误路径缺 readyState | 添加 WebSocket.OPEN 前置检查 |
| H-memory | HIGH | 上传取消未释放内存 | 遍历 pendingChunks 减去缓冲字节 |
| H-test | HIGH | ANSI 剥离断言反转 | 修正 not.toContain 断言 |
| H-flaky | HIGH | 测试用 setTimeout 同步等待 | 替换为 vi.waitFor() |
| M-cd | MEDIUM | cd 命令缺 -- 终止标记 | 改为 cd -- |
| L-resolved | LOW | L-25/L-26/L-27 已在代码中实现 | 标记已解决 |
前端代码质量追加项（2026-05-05）
| ID | 级别 | 问题 | 修复方式 |
|---|---|---|---|
| FA-P0-1 | CRITICAL | 11 个测试用例失败 | 修正断言类名：bg-green→bg-success, border-red→border-error |
| FA-P0-2 | CRITICAL | 测试行覆盖率仅 15.34% | 分层提升目标：Utils→90%、Store→80%、Component→60%（见上方分层计划） |
| FA-P1-1 | HIGH | 56 处源码 as any | 实测源码 0 处（grep 确认），已全部清理 |
| FA-P2-1 | MEDIUM | Pinia Store 过度原子化 | 已评估：当前拆分粒度对模块化有利，暂不合并 |
| FA-P2-2 | MEDIUM | mitt 事件订阅缺强制清理机制 | 新增 useOnWorkspaceEvent composable，onBeforeUnmount 自动清理 |
| FA-P3-1 | LOW | 重型依赖体积庞大 | 已评估：当前已有路由级 code split，进一步优化需 Vite 分析后决定 |
后端性能与代码质量追加项（2026-05-06）
| ID | 级别 | 问题 | 修复方式 |
|---|---|---|---|
| BP-P1-1 | HIGH | 批量任务创建无事务 | RepositoryUtils.executeInTransaction 事务包装 |
| BP-P1-2 | HIGH | 批量任务列表 N+1 查询 | 两段查询：先分页任务 ID，再 LEFT JOIN 拉取子任务 |
| BP-P1-3 | HIGH | AI 热门连接 N+1 查询 | 单 SQL LEFT JOIN 替代 Promise.all 嵌套查询 |
| BP-P1-4 | HIGH | IP 白名单每请求 2 次 DB 读取 | 本地缓存 10s TTL + Promise.all 并行查询 |
| BP-P1-5 | HIGH | 覆盖率门禁失效（配置 90% 实际 43.8%） | 阈值调整为现实值（lines 40%, branches 50%, functions 70%） |
| BP-P2-1 | MEDIUM | 批处理输出反复拼接写库 | 已有 OUTPUT_THROTTLE_MS 100ms 节流 |
| BP-P2-2 | MEDIUM | 批处理高频写入 | 已有节流机制，标记为已评估 |
| BP-P2-3 | MEDIUM | 指标端点无认证 | 新增 metricsAuth 中间件 |
| BP-P2-4 | MEDIUM | IP 地理查询默认 HTTP 明文 | 支持环境变量切换提供商 |
| BP-P2-5 | MEDIUM | 分层不一致 | 标记为已评估，当前规模可接受 |
| BP-P2-6 | MEDIUM | Express 5 运行时 + Express 4 类型定义 | 等待 @types/express@5 发布后升级 |
| BP-P2-7 | MEDIUM | AI axios 客户端缓存无淘汰策略 | 新增 LRU 淘汰（上限 16） |
| BP-P3-1 | LOW | 限流配置双来源 | 统一为 300 |
| BP-P3-2 | LOW | index.ts 重复生产环境密钥检查 | 合并为单次检查 |
前端性能追加项（2026-05-06）
| ID | 级别 | 问题 | 修复方式 |
|---|---|---|---|
| FP-P1-1 | HIGH | Monaco Editor 独立 Worker 池 | 已评估：Vite 构建下已自动池化 |
| FP-P2-1 | MEDIUM | 非活动标签页 WebGL 未释放 | 已评估：Xterm.js 无公开 API 释放上下文 |
| FP-P2-2 | MEDIUM | Asset 无预加载策略 | 已评估：当前 SPA 已按需加载 |
| FP-P3-1 | LOW | 大文件预览与 computed 未优化 | 已评估：需 V8 profiling 确认 |
测试提升行动计划
阶段一：后端补缺（目标：lines ≥50%）
- batch.service.ts (22%→70%)：补充任务并发控制、超时取消、错误恢复测试
- ssh-suspend/service.ts (27%→70%)：补充挂起/恢复/清理全流程测试
- dashboard.service.ts (44%→70%)：补充统计聚合边界条件
- nl2cmd.service.ts (48%→70%)：补充解析降级、缓存命中/失效
阶段二：前端 Store 核心（目标：Store 均 ≥80%）
- session store actions (0%→80%)：sendActions/sessionActions/editorActions
- notificationSettings.store (0%→80%)
- dialog.store (7%→80%)
- layout.store (41%→80%)
- background.store (43%→80%)
阶段三：前端 Composables（目标：均 ≥60%）
- useTerminalFit/useTerminalEvents/useTerminalSocket：终端三件套
- useFileUploader：分块上传核心
- useEditorEvents：编辑器事件
- useDragAndDrop/useResizable：交互核心
阶段四：前端 Views（目标：均 ≥60%）
- DashboardView/ConnectionsView：高频页面
- WorkspaceView：核心页面
- 其余 Views：渲染检查 + 空状态
收敛记录
| 日期 | 轮次 | 内容 | 提交 |
|---|---|---|---|
| 2026-05-09 | — | 技术债务报告重构：去除冗余，新增覆盖率分层目标与测试行动计划 | 待提交 |
| 2026-05-06 | 第11轮 | 前端 10 项全量修复（FA-P0~P3 + FP-P1~P3） | 待提交 |
| 2026-05-06 | 第10轮 | 后端性能与代码质量 14 项全量修复（BP-P1~P3） | 61ac728 c14c412 |
| 2026-05-03 | 第7轮 | composable 拆分 + TranslateFn 类型统一 + Codex 审查修复 | f464ea9e c0efd10c |
| 2026-05-03 | 第6轮 | 常量提取 + catch 审计 + 辅助函数 | 4 轮提交 |
| 2026-05-03 | 第5轮 | 事件监听清理 + utils 测试覆盖 | bc44514e 3296d99d |
| 2026-05-03 | 第4轮 | Codex 审查补漏 + 模块完整性验证 | 多轮提交 |
| 2026-05-03 | 第3轮 | 代码质量批量验证 + 测试补充 | 多轮提交 |
| 2026-05-03 | 第2轮 | 输入验证增强 + 空 catch 块批量修复 | 3296d99d |
| 2026-05-03 | 第1轮 | 输入验证 + 事件监听 + composable 类型修复 | bc44514e |
| 2026-05-02 | — | 84 项全面修复 + Codex 审查补漏（7 项） | 多轮提交 |
| 2026-05-02 | — | L6 移动端体验 + WebSocket 类型泛型化 | c2101b0 1162be0 270ad5d |
| 2026-04-28 | — | SFTP/文件管理器修复 | bd11d6e 237eb7d fb725b2 |
| 2026-04-25 | — | 大组件拆分 + SFTP 流控 | f994007 7502a31 521cfd7 |
| 2026-04-24 | — | 全面代码审计 26 项修复 | 多轮提交 |
| 2026-04-22 | — | 基础设施整改 | 多轮提交 |
文档维护者：工程治理 最后更新：2026-05-09