测试与调试

各模块测试

模块	框架	规模	运行命令
server	go test，含 httptest 与并发 -race	378，其中 18 个 PG 测试需 VIEWER_TEST_PG_DSN，未设自动跳过	cd server && go test ./... && go vet ./...
web	vitest + jsdom	323	cd web && npm test
services/ifc	pytest	262	cd services/ifc && uv run --group dev pytest
services/cad	pytest	238	cd services/cad && uv run --group dev pytest
services/sandbox	pytest，93 个用例配两套服务适配器	186	cd services/sandbox && uv run --group dev pytest
converter	node:test	真实 IFC 转换集成快照	cd converter && npm test
mcp	pytest	17	cd mcp && uv run --group dev pytest
skill 打包	pytest	83	python -m pytest tests/skill/ -q
端到端	bash 冒烟	上传、转换、下载、Issue、脚本管线全链路	./scripts/smoke.sh，需 server 运行

合计约 1,490 个自动化测试，CI 共 11 个 job。开发采用 TDD：先写失败测试再写实现，测试文件和源码放同一个目录。涉及异步写盘的测试，比如转换队列、SSE、后台 goroutine，必须用条件等待确认落盘，禁止固定 sleep。

端到端冒烟

前提是 server 已经在 8090 运行。编辑服务可达时冒烟会追加脚本编辑链路，不可达时自动跳过。

cd server && go run ./cmd/server &
./scripts/smoke.sh    # 成功以 smoke OK 结尾

覆盖内容：上传样例 IFC，轮询到 ready，检查 XKT、metadata 和下载接口；Issue 的创建、列表、截图、状态流转和删除；override 写入与生效值断言；change log 的旧值新值断言；脚本管线的暂存、沙箱运行、保存 v1 和版本记录断言；最后清理。

手工验证清单

1. 打开 http://localhost:5173，新建项目并选类型，在 AI 对话栏让 agent 生成模型。
2. 模型列表状态从 converting 变 ready，2 秒轮询；failed 有错误提示且可重试。
3. 进查看器：IFC 模型能渲染，可切 web-ifc 引擎，轨道旋转、缩放、NavCube 正常；DXF 模型 Canvas 渲染正常。
4. 模型树默认展开一层，搜索和类型过滤可用，节点能显隐，点击节点相机飞行并高亮。
5. 属性面板折叠、搜索、复制正常；script-backed 模型点定位脚本能跳到编辑器对应行。
6. 可见性工具、剖切滑杆、距离测量都可用。
7. Issue 全流程：选中构件新建，自动截图，3D 钉显示并可点击，状态流转，删除。
8. Diff：选 base 和 target，绿红黄着色，展开看字段明细，清除后复位。

故障排查

现象	排查
模型一直 converting	看 server 日志里的 converter stderr；手动跑 convert.js 复现；检查 nodeBin 和 converterScript 配置
转换 failed	调 POST /api/v1/models/{id}/retry
编辑 404 model not found	VIEWER_DATA_DIR 与 dataDir 不是同一目录
脚本编辑 422	契约校验或沙箱构建失败，请求零副作用，按 detail 修正重发
脚本编辑 503	沙箱不可用：缺 bwrap 或缺 uv，见沙箱执行环境
改了脚本前端没刷新	直连编辑服务的 run/save 不触发重转，改走 Go 代理
AI 对话没有智能回复	LLM 三参没配，处于离线 mock；配 VIEWER_LLM_API_KEY 等
PG 连不上	清空 pgDSN 回退文件存储

文档与提交纪律

• 公开文档源在 docs/site/，是唯一信息源。改动后必须跑 cd docs && npm run docs:build，死链会让构建失败。改了 API 文档要跑 npm run gen:api && npm run check:api，漂移检测会拦 PR。
• 文档涉及未交付能力时必须标注为规划，不得写不可执行的步骤。移动或删除文档后，全仓的相对链接要同步更新。
• commit 用中文前缀：feat:、fix:、docs:、ci:、chore:。PR 合入 main 需要 CI 全绿。
• 不要提交本机路径、密钥和运行时数据 data/。