Files
2026-10-15 10:35:55 +08:00

64 lines
5.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CAD World Client
独立的前台工作台。需求解析、图片上传和零件匹配均请求业务后端,前台不再调用模型服务,也不发送系统提示词或模型密钥。请同时保留仓库根目录的 `shared/`,其中包含构建所需的公共模块。
## 运行
```sh
npm ci
npm run dev
```
默认访问 http://127.0.0.1:8091/,监听 0.0.0.0,支持同一局域网访问。Node.js 要求 >= 22.12.0。
前台与管理后台共用 `../shared/api-origin.ts`:本机/局域网访问通过开发代理请求开发 API;`dev-cadworld.robotquan.com`、`dev-cadworld-admin.robotquan.com` 直连 `https://dev-cadworld-api.robotquan.com`;`cadworld.robotquan.com`、`cadworld-admin.robotquan.com` 直连 `https://cadworld-api.robotquan.com`。本地代理可在 `.env.local` 用 `ROBOT_API_TARGET` 覆盖,线上地址由域名规则决定。需求请求携带 `credentials: include`,不读取 HttpOnly Cookie。
生产构建:`npm run build`,上传 `dist` 到静态网站。线上浏览器直接访问 API 域名,无需在网页站点配置 API 反向代理;服务器保留 SPA 路由回退。后端需允许实际网站来源跨域。详见 [部署与联调说明](docs/ai-deployment.md)。
## 当前功能
- 会话创建、单图上传(PNG/JPEG/WebP,8 MiB,最多 4 张)、POST SSE 阶段事件。
- 后端保存多轮上下文,前端只发送新消息。用户补充或修改需求时继续使用同一会话。
- 收到解析结果后自动调用匹配接口,发送 `{revision, confirmed:true}`,用户不需要二次确认;后端如果拒绝匹配,界面显示实际错误,详见 [后端匹配说明](docs/backend-direct-matching.md)。
- `components` 返回后直接加载到主画布,同时更新真实模型结构、属性和数量。没有默认示例模型。
- 不因 `partial`、`blocked`、缺件或未接受降级阻止返回零件的显示;不主动接受后端降级,也不将业务状态伪装为完成。
- 装配从实际 URDF 累积 link/joint 变换,使用 `urdfInfo.frames.interfaceType` 或现有 LINK 命名规则匹配接口。后端可标识配对节点,但额外装配矩阵不覆盖文件接口计算。
- 仅将两端安装节点的完整坐标系同向重合:`父接口变换 × 子接口变换的逆`。不额外翻转 180°、猜测正面或按零件名称纠正方向;`pairingConvention` 字符串不触发隐含旋转。文件原始坐标和网格不改写,URDF 使用加载时的初始关节姿态。
- 对齐只施加刚体变换,不缩放、镜像或剪切。没有明确的子安装节点时不猜用根节点,零件仍单独展示并说明原因。
- 无法唯一确定连接的零件单独展示并给出具体原因;文件加载失败仅影响该零件,其他已加载零件继续显示。
- 支持 STL/OBJ/DAE 和 URDF 基本几何体,保留资源相对目录。
- 组件带有效 `rotationAxis` 时,在安装点增加沿该局部轴旋转的装配关节;保留原 URDF 内部关节,支持角度调节、归零和本地版本恢复。
- 停止调用 DELETE;断线查询状态;重试复用消息编号。组件版本冲突可重新匹配。
项目保存仍为本地查看状态,未接入服务端项目保存或动力学仿真。
## 联调记录(2026-10-13)
早期实际后端 `POST https://dev-cadworld-api.robotquan.com/api/robot-conversations` 返回 HTTP 503:
```json
{"code":"DATABASE_UNAVAILABLE","message":"数据库暂不可用,请检查数据库连接配置后重试","data":null,"requestId":"cb6f00d32b0a4c21a47c49ae164fd489"}
```
该 503 为早期历史问题,后续已收到成功的解析和匹配结果。实际可用性以当前接口请求为准。
自动化测试覆盖接口请求、SSE 分块、Cookie 转发、重试、错误处理、接口节点对齐、多层连接、后端矩阵优先、部分零件显示与资源路径。历史截图 `backend-assembly-fixture.png` 使用模拟几何体;`real-urdf-node-alignment-flipped.png` 使用真实 URDF 资源但属于已移除的手动试装流程。当前入口为主画布自动装配。
```sh
npm test
npm run check
npm run build
```
`node tests/demand-preview.mjs` 可启动隔离模拟环境(前台8096,模拟后端8997),不影响实际运行入口。完成测试后 Ctrl+C 关闭。
旧 `server/app.mjs`、`shared/requirements.mjs` 和 `ai-rules/` 仅保留为先前规则交接参考与回归测试,不属于当前 dev/start 调用链;旧 `/api/ai/responses` 已不可访问。规则、文档、测试和密钥不会作为前台静态资源发布。
## 零件库与 Excel 物料清单(2026-10-14)
零件库按匹配结果的 components 实例展示,名称与编码来自 component,每个实例一张卡片;不将内部 Link 或 STL 资源数量当作零件数量。点击组件定位它在当前模型中的根节点,内部 Link 继续在模型结构中查看。
物料清单读取 components[].component.bomList,按来源零件分组展示后台 Excel 保存的部件名称、部位、DOF、材质、功能、形状、大小、扭矩,保留数值 0 和额外字段。缺失字段与空清单分别提示;非表格 JSON 原样展示,不转换为模型节点。CSV 导出相同 BOM 行并记录来源实例,不合并不同实例的重复物料。模型节点清单独立在导出菜单提供。
真实后台详情 /admin-api/components/7 和 /8 已只读核对,均返回 2 条 Excel BOM。截图中的旧 match 无法匿名读取,未据此推断其字段缺失。66 项测试、生产构建以及隔离模拟接口的浏览器显示、零件定位和 CSV 导出验证通过;截图为模拟接口验证,不代表线上新版已部署。