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