Imported from JohnsonJinyu/spk-cavity-tool (AGENTS.md). Install upstream with npx skills add JohnsonJinyu/spk-cavity-tool. Copyright stays with the author.

SPK Cavity Tool — 技术规范 (AGENTS.md)

项目概述

手机 SPK 后音腔前处理桌面工具。输入结构 STP/ASM 装配体，自动识别 SPK 零件、检测间隙、 合并边界结构、提取流体域腔体，输出可用于 COMSOL 声学仿真的几何模型。

技术栈

Boundaries — 修改约束

严禁操作

• 禁止 在 FastAPI async handler 中直接调用同步 OCP/Gmsh 函数（必须通过 asyncio.to_thread()）
• 禁止 在 tauri_commands.py 中新增核心引擎逻辑（应放在 cavity_engine/ 子模块中）
• 禁止 在前端组件中手动管理状态副本（应使用 Zustand usePipelineStore）
• 禁止 删除或重命名 cavity_engine/ 的公开导出函数而不更新 __init__.py 和 __all__
• 禁止 硬编码颜色、字体、间距值（应使用 CSS 自定义属性，设计令牌见 DESIGN.md）

文件边界

• orchestrator/cavity_engine/ — 纯引擎逻辑，不依赖 FastAPI/Tauri/任何通信层
• orchestrator/tauri_commands.py — 命令边界，只做参数转换和错误包装，核心逻辑委托给 cavity_engine
• orchestrator/api_server.py — FastAPI 端点 + 任务编排，不包含 CAD 逻辑
• apps/desktop-tauri/src/stores/ — Zustand stores，前端唯一状态来源
• apps/desktop-tauri/src/components/ — React 组件，纯视图 + 用户交互
• apps/desktop-tauri/src-tauri/ — Rust 桥接层，仅窗口管理 + 文件对话框（逐步减少 Python 子进程调用）

通信架构

• 主通道: FastAPI REST + SSE（管线操作 + 实时进度）
• 遗留通道: Tauri invoke（仅保留 read_stl_file_base64, open_output_dir, get_version）
• 目标: 将 PartPreview 的 STL 导出迁移到 FastAPI，退役 Rust 中的 preview_part_stl 命令

错误处理

• Python: try/except → traceback.print_exc() → raise 或 return {"success": False, "message": ...}
• TypeScript: try/catch → get()._addLog(..., "error") + 用户可见错误提示
• 禁止 except: pass（静默吞错），必须至少记录 traceback

测试要求

• cavity_engine/ 核心模块：每个公开函数至少一个 pytest
• api_server.py 端点：关键路径的集成测试
• 前端组件：关键用户交互的 Vitest + Testing Library 测试

目录结构约定

orchestrator/
  cavity_engine/     # 核心 CAD 引擎（纯逻辑）
  api_server.py      # FastAPI 服务
  tauri_commands.py  # Tauri 命令边界
  pipeline_model.py  # 管线数据模型（前后端对齐）
  job_manager.py     # 异步任务管理
  pipeline.py        # 共享工具函数
  interfaces.py      # Step2/Step3 协议接口
  pipeline_step2.py  # COMSOL 仿真编排
  comsol_client.py   # COMSOL mph 客户端
  input_resolver.py  # 文件路径解析
apps/desktop-tauri/src/
  components/        # React 组件
  stores/            # Zustand stores
  types.ts           # 共享类型定义
  App.tsx            # 应用壳
configs/             # YAML 配置文件
tests/               # 测试文件
docs/                # 设计文档

命名规范

• Python: snake_case (函数/变量/文件), PascalCase (类)
• TypeScript: camelCase (函数/变量), PascalCase (组件/接口), kebab-case (文件)
• 前端 store 文件以 -store.ts 结尾
• 类型定义文件以 types.ts 或 -types.ts 结尾