64 lines
5.6 KiB
Markdown
64 lines
5.6 KiB
Markdown
# 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 导出验证通过;截图为模拟接口验证,不代表线上新版已部署。
|