fix(intake): use configured vision model for reference cost estimates

75adc3f7 imported QueryValues from mysql2/promise, which only exists in newer mysql2 typings than the package-lock version (3.15.3), breaking tsc on a clean install. Restore the previous equivalent call form (options object + values argument), preserving runtime behavior exactly.

.gitignore

@@ -21,6 +21,16 @@ _logs/
 # Temp
 temp/
 *.tmp
+/.tmp-*/
+/tmp-*/
+/tmp-*.html
+/tmp-*.png
+/tmp-*.env
+/tmp-*.service
+/tmp-*.timer
+/tmp-*.err
+/tmp-*.out
+/.gemini/
 
 # Build artifacts (C# / .NET)
 **/bin/

AGENTS.md

@@ -1,80 +1,167 @@
 # AGENTS.md
 
-适用范围：`D:\AI Code\3danzhuang` 全仓库。
+适用范围：`D:\AI Code\3danzhuang-wuyongjie-mainline` 全仓库。
+未单独说明时，先遵循当前 agent 自己的全局规则（ZCode：`C:\Users\54972\.zcode\v2\AGENTS.md`；Codex：`C:\Users\54972\.codex\AGENTS.md`）。
+这份文件只记录本仓库当前有效的补充规则和核查入口，不保存密码、密钥、数据库连接串或对象存储密钥。
 
-## 1. 默认方式
+重要边界：`D:\AI Code\3danzhuang` 是历史旧现场；当前正式工作目录以 `D:\AI Code\3danzhuang-wuyongjie-mainline` 为准。除非用户明确要求，不要混用旧目录、旧服务器别名、旧部署脚本或旧截图结论。
 
-- 默认中文沟通，面向非程序员表达。
-- 默认回复尽量简短、直白、好理解，非必要不展开。
-- 默认先说“现在你要做什么 / 结论是什么”；技术细节、文件路径、命令和长解释只在用户要求时展开。
-- 默认按当前会话直接开发。
-- 没有“规范审查结论”，任务不算完成。
+## 1. 当前项目真相
 
-## 2. 三条硬规则
+- 外层目录 `D:\AI Code\3danzhuang-wuyongjie-mainline` 是 Git 仓库根目录。
+- 主应用目录是 `furniture-3d-system/`；用户未指定目录时，默认在这里执行代码、测试、构建和脚本。
+- 技术栈以当前 `furniture-3d-system/package.json` 为准（核心：Next.js App Router + React + TypeScript + Prisma/PostgreSQL + Jest + Playwright + Tailwind CSS + Three.js/R3F；另有 ioredis、puppeteer、exceljs/xlsx、zod、zustand 等）。package.json 变动后文档不自动同步，以实时核查为准。
+- `CLAUDE.md`、旧 README、`docs/历史归档/` 和早期部署文档里可能仍有旧苹果风格、MinIO、旧 Docker 部署、旧模型数量、旧 Product/SKU 口径等信息；只能当历史参考，不能覆盖当前代码、workflow 文档和实时命令结果。
+- 工作树可能有用户或其他协作者留下的未跟踪文件、日志、贴图和本地产物。只处理本次任务明确相关的文件，不要顺手清理或回退无关现场。
 
-- 必须符合企业级架构标准。
-- 必须符合统一视觉标准。
-- 必须优先做根因修复，不能拿补丁冒充完成。
+## 2. 开工前固定入口
 
-## 3. 固定流程
-
-1. 开始前先用 1-2 句说明：目标、验收标准、根因判断。  
-2. 开发时优先复用现有实现，不顺手改无关问题。  
-3. 改完先做最小必要验证。  
-4. 交付前必须单独做一次规范审查。  
-5. 最终默认只交代：现在你要做什么、是否完成、有没有风险；技术细节只在用户要求时展开。
-
-### 团队协作固定入口
-
-当任务发生在 `furniture-3d-system/` 时，人和 AI 都必须先读取下面这些协作文档，再开始改代码：
+当任务发生在 `furniture-3d-system/` 时，改代码前必须先读这 3 份当前协作入口：
 
 - `furniture-3d-system/docs/workflow/团队协作模式.md`
 - `furniture-3d-system/docs/workflow/模块边界说明.md`
 - `furniture-3d-system/docs/workflow/主线同步操作手册.md`
 
-这 3 份文档就是进入 `furniture-3d-system/` 的固定协作入口，不再额外约定第二套平级入口，也不再靠聊天记录补口头规则。
+按任务类型额外读取：
 
-如果任务和包装协作有关，再额外读取：
+- 生产、部署、线上排障：`furniture-3d-system/docs/workflow/生产部署入口说明.md`，并核对 `scripts/deploy-yydd-prod-from-git.ps1` 与其调用的 `scripts/create-yydd-prod-deploy.ps1` 当前默认参数。
+- 前端、视觉、交互：`furniture-3d-system/docs/设计规范/白曜石工坊统一视觉标准.md` 和 `furniture-3d-system/docs/workflow/规范审查清单.md`。
+- 包装、仓库、轻仓库协作：再读包装/仓库相关交接文档和 `src/app/warehouse`、`src/app/api/warehouse`、`src/app/api/pre-skus/[id]/packaging/route.ts` 的当前实现。
+- 数据库、主数据、迁移：优先读 `docs/架构设计/内部主数据巡检基线-20260529.md`、`docs/架构设计/数据库混乱点治理台账.md` 和相关 `db:foundation:*` 脚本说明。
 
-- `furniture-3d-system/docs/workflow/同事交接模板.md`
-- `furniture-3d-system/docs/workflow/同事本地AGENTS模板.md`
-- `furniture-3d-system/docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md`
+如果文档和代码冲突，按这个顺序判断：当前代码和脚本、当前线上/命令返回、当前 workflow 文档、历史文档或旧记忆。
 
-固定协作口径：
+## 3. Git 与主线协作
 
-- `main` 只作为 `WuYongJie` 的主线收口分支，其他协作者默认不能直接推主线
-- `xuxiake` 的长期包装分支固定为 `codex/xuxiake-packaging`
-- `xuxiake` 的临时任务分支固定为 `codex/xuxiake-packaging-<任务简称>`
-- 新分支统一使用 `codex/<负责人>-<工作域>` 或 `codex/<负责人>-<工作域>-<任务简称>`
-- 不再使用 `feature/packaging`、`packaging/...`、`codex/xuxiake-dev` 这类泛分支名
-- 长期包装分支同步 `main` 时固定使用 `merge main`
-- 临时个人任务分支同步 `main` 时才使用 `rebase main`
+- `main` 是最终发布主线，由 `WuYongJie` 收口；不要直接把半成品推到 `main`。
+- `origin/codex/xuxiake-mainline` 是日常共享开发主线和默认同步基线。
+- 新功能、优化和修复默认从最新 `origin/codex/xuxiake-mainline` 开任务分支，再按协作流程回流。
+- 新分支统一使用 `codex/<负责人>-<工作域>` 或 `codex/<负责人>-<工作域>-<任务简称>`，不要再新建 `feature/...`、`packaging/...`、`dev`、`codex/xuxiake-dev` 这类泛分支名。
+- 长期共享分支同步共享开发主线时固定使用 `merge origin/codex/xuxiake-mainline`；只有确认无人共用的临时个人任务分支才使用 `rebase origin/codex/xuxiake-mainline`。
+- 每次开工或接续旧任务时，先看 `git status --short --branch`；涉及主线同步时再看 `git rev-list --left-right --count HEAD...origin/codex/xuxiake-mainline`，不要把“当前所在分支”误当成“已同步共享主线”。
+- 用户问“xuxiake 主线有没有新提交”时，必须先 `git fetch origin`，再基于最新远端状态回答。
+- 不要在脏工作树上直接 merge/rebase。先看 `git status --short`，分清本次改动、用户改动、本地产物和无关未跟踪文件。
+- 常规任务完成必要验证后，可以按协作流程推进 `commit / push`；`main`、生产发布、破坏性操作、删除数据、改远端历史等高风险动作必须有用户明确授权。
 
-## 4. 规范审查
+### 主线部署标准流程（每次"主线部署"都走这一套）
 
-规范审查固定只查三件事：
-- 架构有没有被破坏
-- 视觉有没有跑偏
-- 这次是不是根因修复
+本仓库有两根主线，都不直接提交：`main` 是生产部署唯一来源（由 `WuYongJie` 收口），`origin/codex/xuxiake-mainline` 是共享开发次主线（日常回流基线）。
 
-结论只能是：
-- `passed`
-- `passed with warnings`
-- `rejected`
+每次用户要求"主线部署"，严格按以下顺序，不跳步、不直接支线 → main：
 
-只要架构违规、视觉违规，或明显是补丁式修复，就必须 `rejected`。  
-如果这次不是独立复审，必须明确写出“这是自审，不是独立复审”。
+1. **在支线开发** → 提交到任务分支（如 `codex/wuyongjie-xxx`），不碰两根主线。
+2. **fetch xuxiake** → 必须先 `git fetch origin`，看 `origin/codex/xuxiake-mainline` 有没有新提交。
+3. **有新提交** → `merge origin/codex/xuxiake-mainline` 拉下来处理冲突（长期共享分支用 merge，不 rebase）；只处理冲突文件，不扩范围。
+4. **合并到 xuxiake** → 把支线合进 `origin/codex/xuxiake-mainline`，并 `push` 更新次主线。
+5. **合并到 main** → 把 xuxiake 合进 `main`，并 `push origin main`（本步需用户授权）。
+6. **用 main 部署** → 走 `scripts/deploy-yydd-prod-from-git.ps1`（默认源 `origin/main`），部署后核对 commit / 进程 / 端口 / 日志 / 关键页面（本步需用户授权）。
 
-统一清单：`docs/workflow/规范审查清单.md`
+发布前必须确认 `git ls-remote origin refs/heads/main`、本地 `origin/main`、目标部署 commit 三者一致。
 
-## 5. 标准来源
+## 4. 生产与部署
 
-- `furniture-3d-system/.cursor/rules/*.mdc`
-- `furniture-3d-system/docs/设计规范/苹果风格视觉标准.md`
-- `docs/workflow/规范审查清单.md`
+- 当前正式网址：`https://cp.jiansun.vip/`。
+- 当前权威生产 SSH 入口：`root@ltai5tdb2ogyj59fquyedh.yydd.ai`，端口 `60022`。
+- 当前生产部署目录：`/opt/furniture-3d-system-prod`。
+- 当前 PM2 进程名：`furniture-3d-system-prod`。
+- 当前应用本机端口：`3001`。
+- 默认生产部署来源：`origin/main`。
+- 当前主部署入口是外层 `scripts/deploy-yydd-prod-from-git.ps1`；它默认部署 `origin/main`，并调用 `scripts/create-yydd-prod-deploy.ps1` 生成发布包/远端发布脚本。不要把下层打包脚本单独当成唯一部署入口。
+- 发布前必须确认 `git ls-remote origin refs/heads/main`、本地 `origin/main`、目标部署 commit 三者一致；本地 `main` 是否领先或落后远端不能替代 `origin/main` 的真实发布来源。
+- 旧 `192.168.58.20`、本机泛别名 `prod`、旧 `gongxiangp2 / youyidian-3d-material` 生产信息都不能套用到本项目。
+- 生产动作前至少实时确认：目标主机、远端目录、PM2 进程、`current` 软链接、监听端口和 `https://cp.jiansun.vip/api/health`。
+- 生产数据库、迁移、主数据地基相关动作先只读核查；需要写入时必须有备份、目标库身份、确认口令和可回滚路径。
+- 对象存储当前要按 `src/lib/storage.ts`、`storage:*` 脚本、七牛迁移/GC 文档和生产环境变量实时核对；不要把历史 MinIO/S3 备份脚本当成当前生产存储真相。
 
-## 6. 边界
+## 5. 当前主链与模块边界
 
-- 用户未指定目录时，默认在 `furniture-3d-system/` 执行。
-- 未经用户明确要求，不主动 `commit / push`。
-- 禁止破坏性操作，除非用户明确授权。
+当前新平台数据主链按这条线理解：
+
+`资产中心 -> 辅助装配 -> 草稿组 -> 产品资料/正式入库 -> 仓库管理/轻仓库`
+
+当前全局工作台导航还包含首页、OA 新品流程看板、仓库质检、AI 出图工作台等运营入口。导航入口不等于数据主链，不要把页面入口和主数据归属混成一件事。
+
+主链默认入口和目录：
+
+- 首页与全局壳：`src/app/page.tsx`、`src/components/layout`
+- 资产中心：`src/app/asset-center`、`src/app/api/asset-center`
+- 辅助装配：`src/app/assisted-assembly`、`src/app/api/assisted-assembly`
+- 草稿组：`src/app/draft-groups`、`src/app/api/draft-groups`
+- 产品资料/正式入库：`src/app/intake`、`src/app/api/intake`
+- 仓库管理/轻仓库：`src/app/warehouse`、`src/app/api/warehouse`
+- 仓库质检：`src/app/warehouse-quality`、`src/app/api/warehouse-quality`
+- AI 出图工作台：`src/app/ai-render-workbench`
+- 审批工作流：`src/app/approval-workflows`
+- 素材库：`src/app/materials`
+- 移动端：`src/app/mobile`
+- 平台组件库：`src/components/platform`
+- 主链规则与类型：`src/lib/open-product`、`src/lib/planning`
+
+业务真相：
+
+- 资产族：`AssetFamily`
+- 规格款：`AssetVariant`
+- 草稿组：`DraftGroup`
+- 准 SKU：`PreSku`
+- 入库结果：正式 `Product / ProductSKU`（`SKU` 是业务概念，Prisma 模型名是 `ProductSKU`）
+- 产品资料侧非集成开品：`IntakeNonIntegratedProduct / IntakeNonIntegratedSkuItem`
+
+旧 CAD 兼容链继续存在，但不是新平台主数据源：
+
+- 页面：`src/app/products`、`src/app/products/[id]`、`src/app/products/[id]/assembly`、`src/app/products/[id]/skus/[skuId]`
+- 旧链模型和服务包括 `Product / ProductSKU / Panel / Hole / ProductHardware`、`assembly.service`、`panel.service`、`hole.service` 等。
+- 旧链可以继续服务历史产品、CAD 导入、装配步骤和兼容发布后能力，但不要反向主导资产中心、草稿组或产品资料主链。
+
+共享接缝默认谨慎处理：
+
+- `prisma/schema.prisma`
+- `prisma/migrations`
+- `src/app/layout.tsx`
+- `src/app/intake`
+- `src/app/draft-groups/[id]`
+- `src/app/api/platform/schemas.ts`
+- `src/server/services/draft-group.service.ts`
+- `src/server/services/intake.service.ts`
+- `src/server/repositories/draft-group.repository.ts`
+
+改这些地方前先说明原因、影响范围和验证计划；不要为了局部 UI 或临时兼容绕过模块边界。
+
+## 6. 架构硬规则
+
+- API Route 负责收参、鉴权和返回，不直接堆业务规则或 Prisma 查询。
+- Service 负责业务规则、权限校验、事务编排、缓存和跨模块协调。
+- Repository 负责数据访问。
+- 任何新接口必须有明确输入输出 DTO/校验口径。
+- 不是必须的话，不要使用兜底逻辑；原生主逻辑能做好，就先把主逻辑、状态契约和数据来源修正确。兜底只能用于明确的兼容、降级或应急场景，不能用来掩盖本应修好的业务规则、接口契约或前端状态问题。
+- 任何 Prisma 模型调整必须带迁移，并补齐主数据/迁移核查；生产/准生产禁止用 `prisma db push` 替代迁移。
+- 影响命名、BOM、包装、安装步骤、SKU、barcode、批次、入库承接的数据问题，优先从数据源和业务规则修，不在页面上压报错或绕校验。
+- SPU、SKU、barcode、批次不能混用：SPU 是父级产品款，SKU 是 SPU 下的具体子项（Prisma 模型名 `ProductSKU`），barcode 是绑定到最终 SKU 的业务定位值；基于某 SKU 派生的新 SKU 必须仍属于同一 SPU，并按业务要求继承或明确指定批次。
+
+## 7. 前端与视觉硬规则
+
+- 白曜石工坊统一视觉标准是本项目新平台第一视觉标准；默认是浅色工作台，不再提供深浅色主题切换入口。
+- 本项目有自己的组件库与 `Meta Component（元组件）` 体系；前端实现必须优先复用 `src/components/platform`、资产中心已沉淀的工作台表达和现有元组件，不允许绕开组件库另起一套孤立 UI。
+- 当用户指定 Stitch 设计稿或已有 Stitch 设计稿可参考时，Stitch 是当前功能的视觉规范与验收标准；实现方式是在本项目组件库/元组件体系内对齐 Stitch 的密度、层级、控件形态、留白、字号、圆角、阴影和低噪音表达，而不是无视组件库硬抄静态稿。
+- 资产中心页面是当前项目内的优先参考样板；涉及资产、图片、SKU、AI 白底图、3D 预览、工作区和检视器时，默认参考资产中心的工作台感、元组件表达、低噪音操作面板和重点图片区。
+- `Inspector（检视器）`、数据列表、表格、长文本和表单密集区必须优先保证可读性；毛玻璃只允许用于顶栏、HUD、浮动工具条和轻量状态浮层，不承载正文。
+- 板材、五金、组件、包装等资产必须按元组件表达，不能退回普通图片卡片或营销式大卡片布局。
+- 现有 `apple-*` token、深色 `ObsidianControlShell`、历史主题 CSS 只能作为兼容遗留；新功能不得以它们作为视觉方向。
+- 前端改造不得把现有后台习惯、普通 SaaS 审美或共享组件默认皮肤当成最终依据；如果组件库默认视觉和 Stitch/资产中心标准冲突，应在组件库体系内做专用变体、重写皮肤或局部重构。
+- 没有出现在设计稿、组件规范或业务必要路径里的说明文案、辅助卡片、重复统计块、解释区，不要为了“更易懂”自行添加；工作区必须抓重点，图片类功能要让图片和关键动作成为第一层级。
+- 涉及前端动画、入退场、滚动联动、时间线、拖拽、SVG 或动效性能时，先判断是否有助于理解和操作；需要时优先按技术栈调用对应 GSAP Skill，并继续遵守 Impeccable。React 必须使用 `useGSAP` 或带 `gsap.context().revert()` 的完整清理，滚动相关实例必须销毁并在布局变化时正确刷新；优先动画 `transform/opacity`，尊重 `prefers-reduced-motion`，不得为装饰滥用动效。
+- 前端修改后优先用真实页面、截图、1920×1080 视口和必要的移动端视口验证，不只看代码。
+
+## 8. 验证、收口与规范审查
+
+- 修改后必须做最小但有效的验证；不能验证就明确说明未验证原因和风险。
+- 常用验证命令以当前 `package.json` 为准，优先选和改动范围匹配的最小集合：`npm run type-check`、`npm run build`、`npm test -- <相关测试>`、`npm run lint`；对象存储用 `npm run storage:gc:audit` / `npm run storage:gc:apply`，主数据用 `npm run db:foundation:*` 相关只读或授权脚本。
+- 前端体验类改动要结合浏览器实际操作和截图验证；涉及 3D/canvas 时要确认画面非空、尺寸正确、交互可用。
+- 生产验证必须包含真实健康检查和日志/PM2/端口等现场证据，不能只说"本地构建通过"。
+- 规范审查固定只查三件事：架构有没有被破坏、视觉有没有跑偏、这次是不是根因修复。结论只能是 `passed` / `passed with warnings` / `rejected`；只要架构违规、视觉违规或明显补丁式修复，就必须 `rejected`。非独立复审时必须写明"这是自审，不是独立复审"。统一清单：`furniture-3d-system/docs/workflow/规范审查清单.md`。没有规范审查结论，任务不算完成。
+
+## 9. 敏感信息和交接
+
+- 账号密码、访问密钥、数据库连接串、对象存储密钥等敏感信息只能放在本地安全材料里，不写入 Git、共享文档、普通交接文本或长期记忆；生产域名、PM2 名称、部署目录这类非密钥运行入口可以写进仓库文档，但必须保持最新。
+- 仓库内协作文档只写非敏感入口、流程和职责；凭据类信息必须用 `[REDACTED_SECRET]` 或本地路径说明替代。
+- 发现摘要、日志或交接文件混有明文凭据时，先提示风险，再决定是否拆成本地敏感版和仓库协作版。
+- 给下一个 agent 或同事交接时，写清：本次只改了什么、没改什么、验证跑了什么、风险是什么、下一步要看哪些文件。

README.md

@@ -1,4 +1,4 @@
-# 3D 家具开品平台工作区
+# 由壹点「产品开发平台」工作区
 
 > 最后更新：2026-04-07  
 > 当前主线：`资产中心 -> 自动组合 -> 草稿组 -> 包装方案 -> 正式入库 -> 轻仓库`

autocad-plugin/FurnitureExporter/Commands.cs

@@ -20,7 +20,7 @@ namespace FurnitureExporter;
 /// </summary>
 public class FurnitureExporterApp : IExtensionApplication
 {
-    private const string PluginVersion = "2.5.0";
+    private const string PluginVersion = "2.6.0";
 
     public void Initialize()
     {
@@ -30,12 +30,13 @@ public class FurnitureExporterApp : IExtensionApplication
         doc?.Editor.WriteMessage($"║    家具导出插件 v{PluginVersion} 已加载             ║\n");
         doc?.Editor.WriteMessage("║                                            ║\n");
         doc?.Editor.WriteMessage("║  命令:                                     ║\n");
-        doc?.Editor.WriteMessage("║    FEXPORT      - 整套家具兼容导出         ║\n");
-        doc?.Editor.WriteMessage("║    FEXPORTASSET - 单资产导出到资产中心     ║\n");
+        doc?.Editor.WriteMessage("║    FEXPORT      - 单资产导出到资产中心     ║\n");
+        doc?.Editor.WriteMessage("║    FEXPORTASSET - 单资产导出别名           ║\n");
+        doc?.Editor.WriteMessage("║    FEXPORTPRODUCT - 整套家具兼容导出       ║\n");
         doc?.Editor.WriteMessage("║    FINFO        - 查看选中实体信息         ║\n");
         doc?.Editor.WriteMessage("║                                            ║\n");
         doc?.Editor.WriteMessage($"║  v{PluginVersion} 新功能:                           ║\n");
-        doc?.Editor.WriteMessage("║    · 新增资产中心单资产导出模式            ║\n");
+        doc?.Editor.WriteMessage("║    · 默认进入资产中心单资产导出            ║\n");
         doc?.Editor.WriteMessage("║    · 新增 assembly 装配语义导出层          ║\n");
         doc?.Editor.WriteMessage("║    · 语义优先用孔位/五金/配合面推导        ║\n");
         doc?.Editor.WriteMessage("║    · 安装顺序仍保留给 Web 端人工设定       ║\n");
@@ -54,7 +55,7 @@ public class FurnitureExporterApp : IExtensionApplication
 /// </summary>
 public class Commands
 {
-    private const string PluginVersion = "2.5.0";
+    private const string PluginVersion = "2.6.0";
 
     private sealed class SingleAssetExportMode
     {
@@ -71,6 +72,9 @@ public class Commands
         public List<PanelInfo> Panels { get; } = new();
         public List<HoleInfo> Holes { get; } = new();
         public List<HoleGroupInfo> HoleGroups { get; } = new();
+        public List<MountPatternInfo> MountPatterns { get; } = new();
+        public List<MountPatternInfo> SnapPatterns { get; } = new();
+        public List<SnapSurfaceInfo> SnapSurfaces { get; } = new();
         public int LogicalHoleCount { get; set; }
         public List<EdgeFeatureInfo> EdgeFeatures { get; } = new();
         public List<ExcludedHoleInfo> ExcludedHoles { get; } = new();
@@ -336,6 +340,9 @@ public class Commands
 
         var holeGroups = HoleGrouping.BuildEccentricScrewGroups(allHoles);
         HoleGrouping.AttachGroupsToPanels(panels, holeGroups);
+        var mountPatterns = MountPatternAnalyzer.BuildMountPatterns(panels, allHoles, holeGroups);
+        MountPatternAnalyzer.AttachPatternsToPanels(panels, mountPatterns);
+        var snapSurfaces = SnapSurfaceBuilder.BuildSnapSurfaces(panels);
         var logicalHoleCount = HoleGrouping.ComputeLogicalHoleCount(allHoles);
 
         foreach (var hole in allHoles)
@@ -353,6 +360,9 @@ public class Commands
 
         result.Holes.AddRange(allHoles);
         result.HoleGroups.AddRange(holeGroups);
+        result.MountPatterns.AddRange(mountPatterns);
+        result.SnapPatterns.AddRange(mountPatterns);
+        result.SnapSurfaces.AddRange(snapSurfaces);
         result.LogicalHoleCount = logicalHoleCount;
         result.EdgeFeatures.AddRange(allEdgeFeatures);
         result.ExcludedHoles.AddRange(panelAnalyzer.ExcludedHoles);
@@ -363,7 +373,7 @@ public class Commands
     /// <summary>
     /// 主导出命令 - 导出板材 GLB + 五金件位置 JSON
     /// </summary>
-    [CommandMethod("FEXPORT")]
+    [CommandMethod("FEXPORTPRODUCT")]
     public void ExportFurniture()
     {
         var doc = AcApp.DocumentManager.MdiActiveDocument;
@@ -405,7 +415,7 @@ public class Commands
                 ed.WriteMessage("    1. 输入命令 UNITS 打开单位设置\n");
                 ed.WriteMessage("    2. 将 '插入时的缩放单位' 改为 '毫米'\n");
                 ed.WriteMessage("    3. 点击确定\n");
-                ed.WriteMessage("    4. 重新运行 FEXPORT 命令\n");
+                ed.WriteMessage("    4. 重新运行 FEXPORTPRODUCT 命令\n");
                 ed.WriteMessage("\n");
                 
                 // 询问是否继续（仅供高级用户）
@@ -445,7 +455,7 @@ public class Commands
                 panelIds = FilterSolids(panelIds, db);
                 if (panelIds.Length == 0)
                 {
-                    ed.WriteMessage("  ⚠️ 无法恢复板材（可能图纸已变更/实体被删除）。已清除会话，请重新运行 FEXPORT。\n");
+                    ed.WriteMessage("  ⚠️ 无法恢复板材（可能图纸已变更/实体被删除）。已清除会话，请重新运行 FEXPORTPRODUCT。\n");
                     ExportSessionManager.Clear(docKey);
                     return;
                 }
@@ -546,7 +556,7 @@ public class Commands
 
                     ed.WriteMessage($"  ✓ 已记录 {panelIds.Length} 个板材\n");
                     ed.WriteMessage("\n  你现在可以自由调整图层显示/冻结/隔离等操作。\n");
-                    ed.WriteMessage("  调整完成后，再次运行 FEXPORT 继续第 2 步（选五金并导出）。\n");
+                    ed.WriteMessage("  调整完成后，再次运行 FEXPORTPRODUCT 继续第 2 步（选五金并导出）。\n");
 
                     var proceedOpt = new PromptKeywordOptions(
                         "\n是否现在直接继续第 2 步？ [继续(C)/稍后(R)]",
@@ -558,7 +568,7 @@ public class Commands
 
                     if (proceedResult.Status != PromptStatus.OK || proceedResult.StringResult != "Continue")
                     {
-                        ed.WriteMessage("\n已暂停导出。提示：再次运行 FEXPORT 继续；运行 FEXPORTRESET 可清除暂存。\n");
+                        ed.WriteMessage("\n已暂停导出。提示：再次运行 FEXPORTPRODUCT 继续；运行 FEXPORTRESET 可清除暂存。\n");
                         return;
                     }
                 }
@@ -683,6 +693,9 @@ public class Commands
                 // 2) 偏心孔位分组：把“主孔+侧孔”合并为 1 个逻辑孔位（不改变 holes 的几何数据，仅提供分组与逻辑计数）
                 var holeGroups = HoleGrouping.BuildEccentricScrewGroups(allHoles);
                 HoleGrouping.AttachGroupsToPanels(panels, holeGroups);
+                var mountPatterns = MountPatternAnalyzer.BuildMountPatterns(panels, allHoles, holeGroups);
+                MountPatternAnalyzer.AttachPatternsToPanels(panels, mountPatterns);
+                var snapSurfaces = SnapSurfaceBuilder.BuildSnapSurfaces(panels);
 
                 var logicalHoleCount = HoleGrouping.ComputeLogicalHoleCount(allHoles);
 
@@ -729,6 +742,9 @@ public class Commands
                 exportData.Panels = panels;
                 exportData.Holes = allHoles;
                 exportData.HoleGroups = holeGroups;
+                exportData.MountPatterns = mountPatterns;
+                exportData.SnapPatterns = mountPatterns;
+                exportData.SnapSurfaces = snapSurfaces;
                 exportData.LogicalHoleCount = logicalHoleCount;
 
                 if (panelAnalyzer.ExcludedHoles.Count > 0)
@@ -842,8 +858,25 @@ public class Commands
         }
     }
 
+    [CommandMethod("FEXPORTBUNDLE")]
+    public void ExportFurnitureBundle()
+    {
+        ExportFurniture();
+    }
+
+    [CommandMethod("FEXPORT")]
+    public void ExportAssetDefault()
+    {
+        ExportSingleAssetCore();
+    }
+
     [CommandMethod("FEXPORTASSET")]
     public void ExportSingleAsset()
+    {
+        ExportSingleAssetCore();
+    }
+
+    private void ExportSingleAssetCore()
     {
         var doc = AcApp.DocumentManager.MdiActiveDocument;
         if (doc == null)
@@ -985,6 +1018,9 @@ public class Commands
                     exportData.Panels = panelAnalysis.Panels;
                     exportData.Holes = panelAnalysis.Holes;
                     exportData.HoleGroups = panelAnalysis.HoleGroups;
+                    exportData.MountPatterns = panelAnalysis.MountPatterns;
+                    exportData.SnapPatterns = panelAnalysis.SnapPatterns;
+                    exportData.SnapSurfaces = panelAnalysis.SnapSurfaces;
                     exportData.LogicalHoleCount = panelAnalysis.LogicalHoleCount;
                     exportData.EdgeFeatures = panelAnalysis.EdgeFeatures;
                     exportData.PanelCount = panelAnalysis.Panels.Count;
@@ -1024,21 +1060,11 @@ public class Commands
 
                 if (mode.AnalyzePanels && panelAnalysis.Panels.Count > 0)
                 {
-                    ed.WriteMessage("  [4/5] 生成装配语义...");
-                    var assemblyAnalyzer = new AssemblySemanticAnalyzer();
-                    exportData.Assembly = assemblyAnalyzer.Analyze(
-                        panelAnalysis.Panels,
-                        panelAnalysis.Holes,
-                        panelAnalysis.HoleGroups,
-                        exportData.HardwareTypes);
-                    var highConfidenceCount = exportData.Assembly.PanelAssemblies.Count(item =>
-                        item.Confidence >= 0.75 &&
-                        !string.Equals(item.MountMode, "unknown", StringComparison.OrdinalIgnoreCase));
-                    ed.WriteMessage($" ✓ ({exportData.Assembly.PanelAssemblies.Count} 个板件语义, {highConfidenceCount} 个高置信)\n");
+                    ed.WriteMessage("  [4/5] 跳过旧装配语义... ✓ (single_asset 使用 snapPatterns/snapSurfaces)\n");
                 }
                 else
                 {
-                    ed.WriteMessage("  [4/5] 生成装配语义... ✓ (当前模式无需生成)\n");
+                    ed.WriteMessage("  [4/5] 跳过旧装配语义... ✓ (当前模式无需生成)\n");
                 }
 
                 ed.WriteMessage("  [5/5] 打包文件...");
@@ -1108,7 +1134,7 @@ public class Commands
         var ed = doc.Editor;
         var docKey = string.IsNullOrWhiteSpace(doc.Name) ? "Untitled" : doc.Name;
         ExportSessionManager.Clear(docKey);
-        ed.WriteMessage("\n已清除 FEXPORT 暂存会话。请重新运行 FEXPORT。\n");
+        ed.WriteMessage("\n已清除整套兼容导出暂存会话。请重新运行 FEXPORTPRODUCT。\n");
     }
 
     private static List<string> GetEntityHandles(Database db, ObjectId[] ids)

autocad-plugin/FurnitureExporter/FurnitureExporter.Tests/AssemblySemanticAnalyzerTests.cs

@@ -1,229 +1,236 @@
+using System;
 using System.Collections.Generic;
 using System.Linq;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
 using Newtonsoft.Json.Serialization;
-using Xunit;
 
-namespace FurnitureExporter.Tests;
-
-public class AssemblySemanticAnalyzerTests
+namespace FurnitureExporter.Tests
 {
-    [Fact]
-    public void Analyze_BuildsAssemblySection_AndDoesNotEmitInstallOrderFields()
+    public class AssemblySemanticAnalyzerTests
     {
-        var exportData = new ExportData
+        [Fact]
+        public void Analyze_BuildsAssemblySection_AndDoesNotEmitInstallOrderFields()
         {
-            Panels = new List<PanelInfo>
+            var exportData = new ExportData
+            {
+                Panels = new List<PanelInfo>
+                {
+                    CreatePanel(
+                        "panel_001",
+                        "side_panel",
+                        new[] { 9.0, 280.0, 360.0 },
+                        new[] { 1.0, 0.0, 0.0 },
+                        new[] { 0.0, 0.0, 0.0 },
+                        new[] { 18.0, 560.0, 720.0 }),
+                    CreatePanel(
+                        "panel_002",
+                        "shelf",
+                        new[] { 200.0, 280.0, 359.0 },
+                        new[] { 0.0, 0.0, 1.0 },
+                        new[] { 18.0, 0.0, 350.0 },
+                        new[] { 382.0, 560.0, 368.0 }),
+                },
+            };
+
+            exportData.Assembly = new AssemblySemanticAnalyzer().Analyze(
+                exportData.Panels,
+                exportData.Holes,
+                exportData.HoleGroups,
+                exportData.HardwareTypes);
+
+            var json = JsonConvert.SerializeObject(
+                exportData,
+                new JsonSerializerSettings
+                {
+                    ContractResolver = new CamelCasePropertyNamesContractResolver(),
+                    NullValueHandling = NullValueHandling.Ignore,
+                });
+
+            var root = JObject.Parse(json);
+            Assert.Equal("1.0", root["assembly"]?["version"]?.Value<string>());
+            Assert.NotNull(root["assembly"]?["panelAssemblies"]);
+            Assert.NotNull(root["assembly"]?["connections"]);
+            Assert.DoesNotContain("installOrder", json, StringComparison.OrdinalIgnoreCase);
+        }
+
+        [Fact]
+        public void Analyze_PrefersHardwareRelation_ForConnectedPanel()
+        {
+            var panels = new List<PanelInfo>
             {
                 CreatePanel(
                     "panel_001",
                     "side_panel",
-                    position: new[] { 9.0, 280.0, 360.0 },
-                    normal: new[] { 1.0, 0.0, 0.0 },
-                    boundingBoxMin: new[] { 0.0, 0.0, 0.0 },
-                    boundingBoxMax: new[] { 18.0, 560.0, 720.0 }),
+                    new[] { 9.0, 280.0, 360.0 },
+                    new[] { 1.0, 0.0, 0.0 },
+                    new[] { 0.0, 0.0, 0.0 },
+                    new[] { 18.0, 560.0, 720.0 }),
                 CreatePanel(
                     "panel_002",
                     "shelf",
-                    position: new[] { 200.0, 280.0, 359.0 },
-                    normal: new[] { 0.0, 0.0, 1.0 },
-                    boundingBoxMin: new[] { 18.0, 0.0, 350.0 },
-                    boundingBoxMax: new[] { 382.0, 560.0, 368.0 }),
-            },
-        };
+                    new[] { 200.0, 280.0, 359.0 },
+                    new[] { 0.0, 0.0, 1.0 },
+                    new[] { 18.0, 0.0, 350.0 },
+                    new[] { 382.0, 560.0, 368.0 }),
+            };
 
-        exportData.Assembly = AssemblySemanticAnalyzer.Analyze(
-            exportData.Panels,
-            exportData.Holes,
-            exportData.HoleGroups,
-            exportData.HardwareTypes);
-
-        var json = JsonConvert.SerializeObject(
-            exportData,
-            new JsonSerializerSettings
+            var holes = new List<HoleInfo>
             {
-                ContractResolver = new CamelCasePropertyNamesContractResolver(),
-                NullValueHandling = NullValueHandling.Ignore,
-            });
-
-        var root = JObject.Parse(json);
-        Assert.Equal("1.0", root["assembly"]?["version"]?.Value<string>());
-        Assert.NotNull(root["assembly"]?["panelAssemblies"]);
-        Assert.NotNull(root["assembly"]?["connections"]);
-        Assert.DoesNotContain("installOrder", json, System.StringComparison.OrdinalIgnoreCase);
-    }
-
-    [Fact]
-    public void Analyze_PrefersHoleGroupAndHardwareEvidence_OverPanelTypeFallback()
-    {
-        var panels = new List<PanelInfo>
-        {
-            CreatePanel(
-                "panel_001",
-                "side_panel",
-                position: new[] { 9.0, 280.0, 360.0 },
-                normal: new[] { 1.0, 0.0, 0.0 },
-                boundingBoxMin: new[] { 0.0, 0.0, 0.0 },
-                boundingBoxMax: new[] { 18.0, 560.0, 720.0 }),
-            CreatePanel(
-                "panel_002",
-                "shelf",
-                position: new[] { 200.0, 280.0, 359.0 },
-                normal: new[] { 0.0, 0.0, 1.0 },
-                boundingBoxMin: new[] { 18.0, 0.0, 350.0 },
-                boundingBoxMax: new[] { 382.0, 560.0, 368.0 }),
-        };
-
-        var holes = new List<HoleInfo>
-        {
-            new()
-            {
-                Id = "panel_001_hole_001",
-                PanelId = "panel_001",
-                Position = new[] { 9.0, 260.0, 360.0 },
-                Normal = new[] { 1.0, 0.0, 0.0 },
-                Diameter = 15.0,
-                Radius = 7.5,
-                Depth = 12.0,
-                Type = "blind",
-            },
-            new()
-            {
-                Id = "panel_001_hole_002",
-                PanelId = "panel_001",
-                Position = new[] { 16.0, 260.0, 360.0 },
-                Normal = new[] { 0.0, 1.0, 0.0 },
-                Diameter = 8.0,
-                Radius = 4.0,
-                Depth = 10.0,
-                Type = "blind",
-            },
-        };
-
-        var holeGroups = new List<HoleGroupInfo>
-        {
-            new()
-            {
-                Id = "panel_001_group_000",
-                PanelId = "panel_001",
-                GroupType = "eccentric_screw",
-                HoleIds = new[] { "panel_001_hole_001", "panel_001_hole_002" },
-                Position = new[] { 9.0, 260.0, 360.0 },
-                Normal = new[] { 1.0, 0.0, 0.0 },
-                Confidence = 0.96,
-                Reason = "偏心件孔组",
-            },
-        };
-
-        panels[0].Holes = holes.ToList();
-        panels[0].HoleGroups = holeGroups.ToList();
-
-        var hardwareTypes = new List<HardwareType>
-        {
-            new()
-            {
-                TypeId = "type_000",
-                InferredHardwareType = "connector",
-                Instances = new List<HardwareInstance>
+                new HoleInfo
                 {
-                    new()
+                    Id = "panel_001_hole_001",
+                    PanelId = "panel_001",
+                    Position = new[] { 9.0, 260.0, 360.0 },
+                    Normal = new[] { 1.0, 0.0, 0.0 },
+                    Diameter = 15.0,
+                    Radius = 7.5,
+                    Depth = 12.0,
+                    Type = "blind",
+                },
+                new HoleInfo
+                {
+                    Id = "panel_001_hole_002",
+                    PanelId = "panel_001",
+                    Position = new[] { 16.0, 260.0, 360.0 },
+                    Normal = new[] { 0.0, 1.0, 0.0 },
+                    Diameter = 8.0,
+                    Radius = 4.0,
+                    Depth = 10.0,
+                    Type = "blind",
+                },
+            };
+
+            var holeGroups = new List<HoleGroupInfo>
+            {
+                new HoleGroupInfo
+                {
+                    Id = "panel_001_group_000",
+                    PanelId = "panel_001",
+                    GroupType = "eccentric_screw",
+                    HoleIds = new[] { "panel_001_hole_001", "panel_001_hole_002" },
+                    Position = new[] { 9.0, 260.0, 360.0 },
+                    Normal = new[] { 1.0, 0.0, 0.0 },
+                    Confidence = 0.96,
+                    Reason = "偏心件孔组",
+                },
+            };
+
+            panels[0].Holes = holes.ToList();
+            panels[0].HoleGroups = holeGroups.ToList();
+
+            var hardwareTypes = new List<HardwareType>
+            {
+                new HardwareType
+                {
+                    TypeId = "type_000",
+                    InferredHardwareType = "connector",
+                    Instances = new List<HardwareInstance>
                     {
-                        Position = new Position3D { X = 12.0, Y = 260.0, Z = 360.0 },
-                        PrimaryPanelId = "panel_001",
-                        SecondaryPanelId = "panel_002",
-                        BoundHoleGroupId = "panel_001_group_000",
-                        BoundHoleIds = new[] { "panel_001_hole_001", "panel_001_hole_002" },
-                        BindingMode = "hole_group",
-                        BindingConfidence = 0.97,
-                        BindingReason = "优先按孔组绑定",
-                        NearbyPanelIds = new[] { "panel_001", "panel_002" },
+                        new HardwareInstance
+                        {
+                            Position = new Position3D { X = 12.0, Y = 260.0, Z = 360.0 },
+                            PrimaryPanelId = "panel_001",
+                            SecondaryPanelId = "panel_002",
+                            BoundHoleGroupId = "panel_001_group_000",
+                            BoundHoleIds = new[] { "panel_001_hole_001", "panel_001_hole_002" },
+                            BindingMode = "hole_group",
+                            BindingConfidence = 0.97,
+                            BindingReason = "优先按孔组绑定",
+                            NearbyPanelIds = new[] { "panel_001", "panel_002" },
+                        },
                     },
                 },
-            },
-        };
+            };
 
-        var assembly = AssemblySemanticAnalyzer.Analyze(panels, holes, holeGroups, hardwareTypes);
-        var panelAssembly = Assert.Single(assembly.PanelAssemblies.Where(item => item.PanelId == "panel_001"));
+            var assembly = new AssemblySemanticAnalyzer().Analyze(panels, holes, holeGroups, hardwareTypes);
+            var connection = Assert.Single(
+                assembly.Connections.Where(item =>
+                    item.SourcePanelId == "panel_001" &&
+                    item.TargetPanelId == "panel_002"));
+            var panelAssembly = Assert.Single(assembly.PanelAssemblies.Where(item => item.PanelId == "panel_001"));
 
-        Assert.Equal("connector_lock", panelAssembly.MountMode);
-        Assert.Equal("panel_002", panelAssembly.PrimarySupportPanelId);
-        Assert.Contains("panel_002", panelAssembly.TargetPanelIds);
-        Assert.Contains("panel_002", panelAssembly.DependsOn);
-        Assert.Contains(panelAssembly.Mates, mate => mate.MateType == "hole_group_hardware" && mate.HoleGroupId == "panel_001_group_000");
-        Assert.True(panelAssembly.Confidence >= 0.9);
-        Assert.DoesNotContain(panelAssembly.Warnings, warning => warning.Contains("仅按 panelType", System.StringComparison.OrdinalIgnoreCase));
-    }
+            Assert.Equal("hole_group_hardware", connection.ConnectionType);
+            Assert.Equal("slide_in", panelAssembly.MountMode);
+            Assert.Equal("left", panelAssembly.AssemblyDirection);
+            Assert.Equal("panel_002", panelAssembly.PrimarySupportPanelId);
+            Assert.Contains("panel_002", panelAssembly.TargetPanelIds);
+            Assert.Contains("panel_002", panelAssembly.DependsOn);
+            Assert.Contains("panel_002", panelAssembly.Mates.Right ?? new List<string>());
+            Assert.True(panelAssembly.Confidence >= 0.75);
+        }
 
-    [Fact]
-    public void Analyze_FallsBackToFaceMate_WhenNoHardwareBindingExists()
-    {
-        var panels = new List<PanelInfo>
+        [Fact]
+        public void Analyze_FallsBackToShelfDirection_WhenNoHardwareBindingExists()
         {
-            CreatePanel(
-                "panel_left",
-                "side_panel",
-                position: new[] { 9.0, 280.0, 360.0 },
-                normal: new[] { 1.0, 0.0, 0.0 },
-                boundingBoxMin: new[] { 0.0, 0.0, 0.0 },
-                boundingBoxMax: new[] { 18.0, 560.0, 720.0 }),
-            CreatePanel(
-                "panel_right",
-                "side_panel",
-                position: new[] { 391.0, 280.0, 360.0 },
-                normal: new[] { 1.0, 0.0, 0.0 },
-                boundingBoxMin: new[] { 382.0, 0.0, 0.0 },
-                boundingBoxMax: new[] { 400.0, 560.0, 720.0 }),
-            CreatePanel(
-                "panel_shelf",
-                "shelf",
-                position: new[] { 200.0, 280.0, 359.0 },
-                normal: new[] { 0.0, 0.0, 1.0 },
-                boundingBoxMin: new[] { 18.0, 0.0, 350.0 },
-                boundingBoxMax: new[] { 382.0, 560.0, 368.0 }),
-        };
+            var panels = new List<PanelInfo>
+            {
+                CreatePanel(
+                    "panel_left",
+                    "side_panel",
+                    new[] { 9.0, 280.0, 360.0 },
+                    new[] { 1.0, 0.0, 0.0 },
+                    new[] { 0.0, 0.0, 0.0 },
+                    new[] { 18.0, 560.0, 720.0 }),
+                CreatePanel(
+                    "panel_right",
+                    "side_panel",
+                    new[] { 391.0, 280.0, 360.0 },
+                    new[] { 1.0, 0.0, 0.0 },
+                    new[] { 382.0, 0.0, 0.0 },
+                    new[] { 400.0, 560.0, 720.0 }),
+                CreatePanel(
+                    "panel_shelf",
+                    "shelf",
+                    new[] { 200.0, 280.0, 359.0 },
+                    new[] { 0.0, 0.0, 1.0 },
+                    new[] { 18.0, 0.0, 350.0 },
+                    new[] { 382.0, 560.0, 368.0 }),
+            };
 
-        var assembly = AssemblySemanticAnalyzer.Analyze(
-            panels,
-            new List<HoleInfo>(),
-            new List<HoleGroupInfo>(),
-            new List<HardwareType>());
+            var assembly = new AssemblySemanticAnalyzer().Analyze(
+                panels,
+                new List<HoleInfo>(),
+                new List<HoleGroupInfo>(),
+                new List<HardwareType>());
 
-        var shelf = Assert.Single(assembly.PanelAssemblies.Where(item => item.PanelId == "panel_shelf"));
+            var shelf = Assert.Single(assembly.PanelAssemblies.Where(item => item.PanelId == "panel_shelf"));
 
-        Assert.Equal("slot_insert", shelf.MountMode);
-        Assert.Contains("panel_left", shelf.TargetPanelIds);
-        Assert.Contains("panel_right", shelf.TargetPanelIds);
-        Assert.Contains(shelf.Mates, mate => mate.MateType == "face_contact");
-        Assert.True(shelf.TravelDistance > 0);
-        Assert.True(System.Math.Abs(shelf.AssemblyAxis[0]) > 0.9);
-    }
+            Assert.Equal("drop_in", shelf.MountMode);
+            Assert.Equal("top", shelf.AssemblyDirection);
+            Assert.Contains("panel_left", shelf.TargetPanelIds);
+            Assert.Contains("panel_right", shelf.TargetPanelIds);
+            Assert.Contains("panel_left", shelf.Mates.Left ?? new List<string>());
+            Assert.Contains("panel_right", shelf.Mates.Right ?? new List<string>());
+            Assert.True(shelf.TravelDistance > 0);
+        }
 
-    private static PanelInfo CreatePanel(
-        string id,
-        string panelType,
-        double[] position,
-        double[] normal,
-        double[] boundingBoxMin,
-        double[] boundingBoxMax)
-    {
-        return new PanelInfo
+        private static PanelInfo CreatePanel(
+            string id,
+            string panelType,
+            double[] position,
+            double[] normal,
+            double[] boundingBoxMin,
+            double[] boundingBoxMax)
         {
-            Id = id,
-            PanelType = panelType,
-            Position = position,
-            Normal = normal,
-            BoundingBox = new BoundingBox3D
+            return new PanelInfo
             {
-                Min = boundingBoxMin,
-                Max = boundingBoxMax,
-            },
-            Size = new[]
-            {
-                System.Math.Round(boundingBoxMax[0] - boundingBoxMin[0], 2),
-                System.Math.Round(boundingBoxMax[1] - boundingBoxMin[1], 2),
-                System.Math.Round(boundingBoxMax[2] - boundingBoxMin[2], 2),
-            },
-        };
+                Id = id,
+                PanelType = panelType,
+                Position = position,
+                Normal = normal,
+                BoundingBox = new BoundingBox3D
+                {
+                    Min = boundingBoxMin,
+                    Max = boundingBoxMax,
+                },
+                Size = new[]
+                {
+                    Math.Round(boundingBoxMax[0] - boundingBoxMin[0], 2),
+                    Math.Round(boundingBoxMax[1] - boundingBoxMin[1], 2),
+                    Math.Round(boundingBoxMax[2] - boundingBoxMin[2], 2),
+                },
+            };
+        }
     }
 }

autocad-plugin/FurnitureExporter/FurnitureExporter.Tests/CommandRegistrationTests.cs

@@ -0,0 +1,42 @@
+using System;
+using System.IO;
+using System.Text.RegularExpressions;
+
+namespace FurnitureExporter.Tests
+{
+    public class CommandRegistrationTests
+    {
+        [Fact]
+        public void Fexport_DefaultsToSingleAssetExport()
+        {
+            var source = ReadCommandsSource();
+
+            Assert.Matches(CommandMethodPattern("FEXPORT", "ExportAssetDefault"), source);
+            Assert.Matches(CommandMethodPattern("FEXPORTASSET", "ExportSingleAsset"), source);
+            Assert.DoesNotMatch(CommandMethodPattern("FEXPORT", "ExportFurniture"), source);
+        }
+
+        [Fact]
+        public void LegacyProductBundleExport_UsesExplicitCompatibilityCommands()
+        {
+            var source = ReadCommandsSource();
+
+            Assert.Matches(CommandMethodPattern("FEXPORTPRODUCT", "ExportFurniture"), source);
+            Assert.Matches(CommandMethodPattern("FEXPORTBUNDLE", "ExportFurnitureBundle"), source);
+        }
+
+        private static string ReadCommandsSource()
+        {
+            var path = Path.GetFullPath(
+                Path.Combine(AppContext.BaseDirectory, @"..\..\..\..\Commands.cs"));
+            return File.ReadAllText(path);
+        }
+
+        private static Regex CommandMethodPattern(string commandName, string methodName)
+        {
+            return new Regex(
+                $@"\[CommandMethod\(""{Regex.Escape(commandName)}""\)\]\s+public\s+void\s+{Regex.Escape(methodName)}\s*\(",
+                RegexOptions.Multiline);
+        }
+    }
+}

autocad-plugin/FurnitureExporter/FurnitureExporter.Tests/MountPatternAnalyzerTests.cs

@@ -0,0 +1,89 @@
+using System.Collections.Generic;
+using System.Linq;
+
+namespace FurnitureExporter.Tests
+{
+    public class MountPatternAnalyzerTests
+    {
+        [Fact]
+        public void BuildMountPatterns_ForTwoHoleLine_RequiresTwoHoles()
+        {
+            var panel = CreatePanel("panel_line");
+            var holes = new List<HoleInfo>
+            {
+                CreateHole("hole_a", "panel_line", new[] { -40.0, 0.0, 0.0 }, new[] { 0.0, -1.0, 0.0 }, new[] { "top" }),
+                CreateHole("hole_b", "panel_line", new[] { 40.0, 0.0, 0.0 }, new[] { 0.0, -1.0, 0.0 }, new[] { "top" }),
+            };
+
+            var patterns = MountPatternAnalyzer.BuildMountPatterns(
+                new[] { panel },
+                holes,
+                new List<HoleGroupInfo>());
+
+            var pattern = Assert.Single(patterns);
+            Assert.Equal("line_2", pattern.PatternType);
+            Assert.Equal(2, pattern.MinRequiredHoles);
+            Assert.Equal(2, pattern.PreferredHoleCount);
+            Assert.Single(panel.SnapPatterns);
+            Assert.Equal(panel.MountPatterns, panel.SnapPatterns);
+        }
+
+        [Fact]
+        public void BuildMountPatterns_ForSymmetricRectangle_DefaultsToTwoRequiredHoles()
+        {
+            var panel = CreatePanel("panel_rect");
+            var holes = new List<HoleInfo>
+            {
+                CreateHole("hole_a", "panel_rect", new[] { -40.0, 0.0, -20.0 }, new[] { 0.0, -1.0, 0.0 }, new[] { "top" }),
+                CreateHole("hole_b", "panel_rect", new[] { 40.0, 0.0, -20.0 }, new[] { 0.0, -1.0, 0.0 }, new[] { "top" }),
+                CreateHole("hole_c", "panel_rect", new[] { -40.0, 0.0, 20.0 }, new[] { 0.0, -1.0, 0.0 }, new[] { "top" }),
+                CreateHole("hole_d", "panel_rect", new[] { 40.0, 0.0, 20.0 }, new[] { 0.0, -1.0, 0.0 }, new[] { "top" }),
+            };
+
+            var patterns = MountPatternAnalyzer.BuildMountPatterns(
+                new[] { panel },
+                holes,
+                new List<HoleGroupInfo>());
+
+            var pattern = Assert.Single(patterns);
+            Assert.Equal("rectangle_4", pattern.PatternType);
+            Assert.Equal(2, pattern.MinRequiredHoles);
+            Assert.Equal(4, pattern.PreferredHoleCount);
+            Assert.True(pattern.Symmetry);
+            Assert.Empty(pattern.RequiredHoleIds);
+            Assert.Equal(4, pattern.OptionalHoleIds.Length);
+        }
+
+        private static PanelInfo CreatePanel(string id)
+        {
+            return new PanelInfo
+            {
+                Id = id,
+                Position = new[] { 0.0, 0.0, 0.0 },
+                Normal = new[] { 0.0, 1.0, 0.0 },
+                BoundingBox = new BoundingBox3D
+                {
+                    Min = new[] { -300.0, -9.0, -300.0 },
+                    Max = new[] { 300.0, 9.0, 300.0 },
+                },
+                Size = new[] { 600.0, 18.0, 600.0 },
+            };
+        }
+
+        private static HoleInfo CreateHole(string id, string panelId, double[] position, double[] normal, string[] surfaceFaces)
+        {
+            return new HoleInfo
+            {
+                Id = id,
+                PanelId = panelId,
+                Position = position,
+                Normal = normal,
+                Diameter = 8.0,
+                Radius = 4.0,
+                Depth = 12.0,
+                Type = "blind",
+                SurfaceFaces = surfaceFaces,
+            };
+        }
+    }
+}

autocad-plugin/FurnitureExporter/FurnitureExporter.Tests/PanelFaceSemanticResolverTests.cs

@@ -0,0 +1,73 @@
+namespace FurnitureExporter.Tests
+{
+    public class PanelFaceSemanticResolverTests
+    {
+        [Fact]
+        public void ResolveSurfaceFaces_ForThroughHole_ReturnsOppositeFaces()
+        {
+            var faces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                new BoundingBox3D
+                {
+                    Min = new[] { 0.0, 0.0, 0.0 },
+                    Max = new[] { 18.0, 560.0, 720.0 },
+                },
+                new[] { 9.0, 280.0, 360.0 },
+                new[] { 1.0, 0.0, 0.0 },
+                18.0);
+
+            Assert.Contains("left", faces);
+            Assert.Contains("right", faces);
+        }
+
+        [Fact]
+        public void ResolveSurfaceFaces_ForBlindHole_ReturnsSingleExteriorFace()
+        {
+            var faces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                new BoundingBox3D
+                {
+                    Min = new[] { 0.0, 0.0, 0.0 },
+                    Max = new[] { 18.0, 560.0, 720.0 },
+                },
+                new[] { 4.0, 280.0, 360.0 },
+                new[] { 1.0, 0.0, 0.0 },
+                8.0);
+
+            Assert.Single(faces);
+            Assert.Equal("left", faces[0]);
+        }
+
+        [Fact]
+        public void ResolveSurfaceFaces_ForTopBottomThroughHole_ReturnsTopAndBottom()
+        {
+            var faces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                new BoundingBox3D
+                {
+                    Min = new[] { 0.0, 0.0, 0.0 },
+                    Max = new[] { 600.0, 720.0, 18.0 },
+                },
+                new[] { 300.0, 360.0, 9.0 },
+                new[] { 0.0, 0.0, 1.0 },
+                18.0);
+
+            Assert.Contains("top", faces);
+            Assert.Contains("bottom", faces);
+        }
+
+        [Fact]
+        public void ResolveSurfaceFaces_ForSideBlindHole_PrefersSingleSideFace()
+        {
+            var faces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                new BoundingBox3D
+                {
+                    Min = new[] { 0.0, 0.0, 0.0 },
+                    Max = new[] { 600.0, 18.0, 720.0 },
+                },
+                new[] { 300.0, 4.0, 360.0 },
+                new[] { 0.0, 1.0, 0.0 },
+                8.0);
+
+            Assert.Single(faces);
+            Assert.Equal("front", faces[0]);
+        }
+    }
+}

autocad-plugin/FurnitureExporter/FurnitureExporter.Tests/SnapSurfaceBuilderTests.cs

@@ -0,0 +1,103 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using Newtonsoft.Json.Serialization;
+
+namespace FurnitureExporter.Tests
+{
+    public class SnapSurfaceBuilderTests
+    {
+        [Fact]
+        public void BuildSnapSurfaces_FromBoundingBox_CreatesSixAxisFaces()
+        {
+            var panel = CreatePanel("panel_001");
+
+            var surfaces = SnapSurfaceBuilder.BuildSnapSurfaces(new[] { panel });
+
+            Assert.Equal(6, surfaces.Count);
+            Assert.Equal(6, panel.SnapSurfaces.Count);
+
+            var top = Assert.Single(surfaces.Where(surface => surface.Face == "top"));
+            Assert.Equal("panel_001_snap_top", top.Id);
+            Assert.Equal("panel_001", top.PanelId);
+            Assert.Equal(new[] { 0.0, 0.0, 1.0 }, top.Normal);
+            Assert.Equal(new[] { 0.0, 0.0, 18.0 }, top.Center);
+            Assert.Equal(18.0, top.Bounds.Min[2]);
+            Assert.Equal(18.0, top.Bounds.Max[2]);
+            Assert.Equal(1.0, top.Confidence);
+
+            var front = Assert.Single(surfaces.Where(surface => surface.Face == "front"));
+            Assert.Equal(new[] { 0.0, -1.0, 0.0 }, front.Normal);
+            Assert.Equal(-280.0, front.Center[1]);
+            Assert.Equal(-280.0, front.Bounds.Min[1]);
+            Assert.Equal(-280.0, front.Bounds.Max[1]);
+        }
+
+        [Fact]
+        public void ExportData_ForSingleAsset_EmitsSnapFieldsAndOmitsAssembly()
+        {
+            var panel = CreatePanel("panel_001");
+            var pattern = new MountPatternInfo
+            {
+                Id = "panel_001_mount_top_000",
+                PanelId = "panel_001",
+                MountFace = "top",
+                PatternType = "line_2",
+                HoleIds = new[] { "hole_a", "hole_b" },
+                RequiredHoleIds = new[] { "hole_a", "hole_b" },
+                MinRequiredHoles = 2,
+                PreferredHoleCount = 2,
+                Normal = new[] { 0.0, 0.0, 1.0 },
+                Position = new[] { 0.0, 0.0, 18.0 },
+                Confidence = 0.95,
+            };
+            panel.MountPatterns = new List<MountPatternInfo> { pattern };
+            panel.SnapPatterns = panel.MountPatterns;
+
+            var exportData = new ExportData
+            {
+                ExportMode = "single_asset",
+                Panels = new List<PanelInfo> { panel },
+                MountPatterns = new List<MountPatternInfo> { pattern },
+                SnapPatterns = new List<MountPatternInfo> { pattern },
+                SnapSurfaces = SnapSurfaceBuilder.BuildSnapSurfaces(new[] { panel }),
+            };
+
+            var json = JsonConvert.SerializeObject(
+                exportData,
+                new JsonSerializerSettings
+                {
+                    ContractResolver = new CamelCasePropertyNamesContractResolver(),
+                    NullValueHandling = NullValueHandling.Ignore,
+                });
+            var root = JObject.Parse(json);
+
+            Assert.Null(root["assembly"]);
+            Assert.DoesNotContain("\"mates\"", json, StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain("\"connections\"", json, StringComparison.OrdinalIgnoreCase);
+            Assert.Single(Assert.IsType<JArray>(root["mountPatterns"]));
+            Assert.Single(Assert.IsType<JArray>(root["snapPatterns"]));
+            Assert.Equal(6, Assert.IsType<JArray>(root["snapSurfaces"]).Count);
+            var panels = Assert.IsType<JArray>(root["panels"]);
+            Assert.Equal(6, Assert.IsType<JArray>(panels[0]?["snapSurfaces"]).Count);
+        }
+
+        private static PanelInfo CreatePanel(string id)
+        {
+            return new PanelInfo
+            {
+                Id = id,
+                Position = new[] { 0.0, 0.0, 9.0 },
+                Normal = new[] { 0.0, 0.0, 1.0 },
+                BoundingBox = new BoundingBox3D
+                {
+                    Min = new[] { -300.0, -280.0, 0.0 },
+                    Max = new[] { 300.0, 280.0, 18.0 },
+                },
+                Size = new[] { 600.0, 560.0, 18.0 },
+            };
+        }
+    }
+}

autocad-plugin/FurnitureExporter/FurnitureExporter.csproj

@@ -11,7 +11,7 @@
     <!-- AutoCAD 2024 插件配置 -->
     <AssemblyName>FurnitureExporter</AssemblyName>
     <RootNamespace>FurnitureExporter</RootNamespace>
-    <Version>2.5.0</Version>
+    <Version>2.6.0</Version>
     <Authors>Furniture 3D System</Authors>
     <Description>家具 3D 模型导出插件 - 导出 GLB 模型和五金件位置数据</Description>
     

autocad-plugin/FurnitureExporter/HoleDetector.cs

@@ -162,6 +162,31 @@ public class HoleDetector
     {
         try
         {
+            BoundingBox3D? panelBoundingBox = null;
+            try
+            {
+                var ext = solid.GeometricExtents;
+                panelBoundingBox = new BoundingBox3D
+                {
+                    Min = new[]
+                    {
+                        Math.Round(ext.MinPoint.X + _originOffset.X, 2),
+                        Math.Round(ext.MinPoint.Y + _originOffset.Y, 2),
+                        Math.Round(ext.MinPoint.Z + _originOffset.Z, 2),
+                    },
+                    Max = new[]
+                    {
+                        Math.Round(ext.MaxPoint.X + _originOffset.X, 2),
+                        Math.Round(ext.MaxPoint.Y + _originOffset.Y, 2),
+                        Math.Round(ext.MaxPoint.Z + _originOffset.Z, 2),
+                    },
+                };
+            }
+            catch
+            {
+                panelBoundingBox = null;
+            }
+
             var radius = cylinder.Radius;
             var diameter = radius * 2;
 
@@ -203,7 +228,12 @@ public class HoleDetector
                 Depth = Math.Round(depth, 2),
                 PanelId = panelId,
                 Type = holeType,
-                Radius = Math.Round(radius, 2)
+                Radius = Math.Round(radius, 2),
+                SurfaceFaces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                    panelBoundingBox,
+                    new[] { offsetPosition.X, offsetPosition.Y, offsetPosition.Z },
+                    new[] { axis.X, axis.Y, axis.Z },
+                    depth)
             };
         }
         catch (System.Exception ex)

autocad-plugin/FurnitureExporter/HoleGrouping.cs

@@ -92,7 +92,13 @@ public static class HoleGrouping
                     Position = mainHole.Position,
                     Normal = mainHole.Normal,
                     Confidence = confidence,
-                    Reason = $"主孔直径 {mainHole.Diameter:0.#}mm + 侧孔直径 {best.Diameter:0.#}mm，距离 {dist:0.#}mm，法向点积 {dot:0.00}"
+                    Reason = $"主孔直径 {mainHole.Diameter:0.#}mm + 侧孔直径 {best.Diameter:0.#}mm，距离 {dist:0.#}mm，法向点积 {dot:0.00}",
+                    MountFace = mainHole.SurfaceFaces.FirstOrDefault(face => !string.IsNullOrWhiteSpace(face)) ?? "unknown",
+                    SurfaceFaces = mainHole.SurfaceFaces
+                        .Concat(best.SurfaceFaces ?? Array.Empty<string>())
+                        .Where(face => !string.IsNullOrWhiteSpace(face))
+                        .Distinct(StringComparer.OrdinalIgnoreCase)
+                        .ToArray(),
                 };
                 groups.Add(group);
 

autocad-plugin/FurnitureExporter/HoleMarkerDetector.cs

@@ -374,6 +374,11 @@ public sealed class HoleMarkerDetector
             BindingSource = binding.BindingSource,
             BindingConfidence = binding.Confidence,
             BindingReason = binding.BindingReason,
+            SurfaceFaces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                binding.PanelCandidate.Panel.BoundingBox,
+                new[] { p.X, p.Y, p.Z },
+                new[] { axis.X, axis.Y, axis.Z },
+                depth),
         });
     }
 
@@ -418,6 +423,11 @@ public sealed class HoleMarkerDetector
             BindingSource = binding.BindingSource,
             BindingConfidence = binding.Confidence,
             BindingReason = binding.BindingReason,
+            SurfaceFaces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                binding.PanelCandidate.Panel.BoundingBox,
+                new[] { p.X, p.Y, p.Z },
+                new[] { axis.X, axis.Y, axis.Z },
+                depth),
         });
     }
 

autocad-plugin/FurnitureExporter/Models.cs

@@ -10,7 +10,7 @@ public class ExportData
     /// <summary>
     /// 数据格式版本
     /// </summary>
-    public string Version { get; set; } = "2.4";
+    public string Version { get; set; } = "2.6";
     
     /// <summary>
     /// 导出时间 (ISO 8601)
@@ -46,6 +46,13 @@ public class ExportData
     /// 图纸单位（毫米/厘米/米等）
     /// </summary>
     public string Units { get; set; } = "毫米";
+
+    /// <summary>
+    /// CAD 世界坐标系标识。
+    /// 当前导出统一按 AutoCAD 世界坐标：X 向右，Y 向前，Z 向上。
+    /// Web 端后续做孔位吸附时，不再需要靠启发式猜测坐标系。
+    /// </summary>
+    public string CoordinateSystem { get; set; } = "AUTOCAD_WORLD_Z_UP";
     
     /// <summary>
     /// 原点偏移 [X, Y, Z] (mm)
@@ -103,6 +110,24 @@ public class ExportData
     /// </summary>
     public List<HoleGroupInfo> HoleGroups { get; set; } = new();
 
+    /// <summary>
+    /// 安装图样（v2.5 兼容字段）。
+    /// 新方案主字段是 SnapPatterns；这里继续保留给旧 Web 端兼容。
+    /// </summary>
+    public List<MountPatternInfo> MountPatterns { get; set; } = new();
+
+    /// <summary>
+    /// 吸附图样（v2.6 新主字段）。
+    /// 内容与 MountPatterns 保持一致，Web 端后续优先读取 snapPatterns。
+    /// </summary>
+    public List<MountPatternInfo> SnapPatterns { get; set; } = new();
+
+    /// <summary>
+    /// 吸附面（v2.6 新增）。
+    /// 每块板件至少提供 6 个轴向外表面，用于辅助装配阶段做面级吸附候选。
+    /// </summary>
+    public List<SnapSurfaceInfo> SnapSurfaces { get; set; } = new();
+
     /// <summary>
     /// 逻辑孔位数量（v2.2.4 新增）
     /// 计算方式：以 HoleGroupId 合并计数（HoleGroupId 为空则按 Hole.Id 计数）。
@@ -313,6 +338,21 @@ public class PanelInfo
     /// 该板件上的逻辑孔位分组（v2.2.4 新增）
     /// </summary>
     public List<HoleGroupInfo> HoleGroups { get; set; } = new();
+
+    /// <summary>
+    /// 该板件上的安装图样（v2.5 兼容字段）
+    /// </summary>
+    public List<MountPatternInfo> MountPatterns { get; set; } = new();
+
+    /// <summary>
+    /// 该板件上的吸附图样（v2.6 新主字段）
+    /// </summary>
+    public List<MountPatternInfo> SnapPatterns { get; set; } = new();
+
+    /// <summary>
+    /// 该板件的吸附面（v2.6 新增）
+    /// </summary>
+    public List<SnapSurfaceInfo> SnapSurfaces { get; set; } = new();
 }
 
 /// <summary>
@@ -391,6 +431,14 @@ public class HoleInfo
     /// </summary>
     public double BindingConfidence { get; set; } = 1.0;
 
+    /// <summary>
+    /// 孔位整体可用置信度（0-1）
+    /// 说明：
+    /// - BindingConfidence 只表示“孔位和板件绑定得稳不稳”；
+    /// - Confidence 表示“这个孔位几何与语义整体是否可信”。
+    /// </summary>
+    public double Confidence { get; set; } = 1.0;
+
     /// <summary>
     /// 绑定原因说明（调试/回放）
     /// </summary>
@@ -418,12 +466,24 @@ public class HoleInfo
     /// 例如：main（主孔）/ side（侧孔）
     /// </summary>
     public string? HoleGroupRole { get; set; }
+
+    /// <summary>
+    /// 当前孔实际打在板件外表面的面标签。
+    /// 盲孔通常只有 1 个面；通孔通常会有 2 个相对面。
+    /// 例如：top / bottom / left / right / front / back
+    /// </summary>
+    public string[] SurfaceFaces { get; set; } = System.Array.Empty<string>();
     
     /// <summary>
     /// 推断的用途（根据直径）
     /// </summary>
     public string? InferredUsage { get; set; }
 
+    /// <summary>
+    /// 低置信度或歧义提示
+    /// </summary>
+    public List<string> Warnings { get; set; } = new();
+
     /// <summary>
     /// 针对该孔位的紧固件建议（v2.3 新增）
     /// 说明：
@@ -511,6 +571,140 @@ public class HoleGroupInfo
     /// 可读原因（调试/回放）
     /// </summary>
     public string? Reason { get; set; }
+
+    /// <summary>
+    /// 当前孔组默认作用的安装面。
+    /// 例如：top / bottom / left / right / front / back / unknown
+    /// </summary>
+    public string MountFace { get; set; } = "unknown";
+
+    /// <summary>
+    /// 逻辑孔位实际落在哪些板件外表面上。
+    /// 默认按主孔 + 组内成员孔合并去重。
+    /// </summary>
+    public string[] SurfaceFaces { get; set; } = System.Array.Empty<string>();
+
+    /// <summary>
+    /// 低置信度或歧义提示
+    /// </summary>
+    public List<string> Warnings { get; set; } = new();
+}
+
+/// <summary>
+/// 安装图样（v2.5 新增）
+/// </summary>
+public class MountPatternInfo
+{
+    /// <summary>
+    /// 图样 ID（如 panel_001_mount_top_001）
+    /// </summary>
+    public string Id { get; set; } = "";
+
+    /// <summary>
+    /// 所属板件 ID
+    /// </summary>
+    public string PanelId { get; set; } = "";
+
+    /// <summary>
+    /// 默认安装面：top / bottom / left / right / front / back / unknown
+    /// </summary>
+    public string MountFace { get; set; } = "unknown";
+
+    /// <summary>
+    /// 图样类型：single / line_2 / triangle_3 / rectangle_4 / generic
+    /// </summary>
+    public string PatternType { get; set; } = "generic";
+
+    /// <summary>
+    /// 属于该图样的几何孔位 ID
+    /// </summary>
+    public string[] HoleIds { get; set; } = System.Array.Empty<string>();
+
+    /// <summary>
+    /// 必需命中的孔位 ID
+    /// </summary>
+    public string[] RequiredHoleIds { get; set; } = System.Array.Empty<string>();
+
+    /// <summary>
+    /// 可选命中的孔位 ID
+    /// </summary>
+    public string[] OptionalHoleIds { get; set; } = System.Array.Empty<string>();
+
+    /// <summary>
+    /// 吸附成立所需的最少命中孔数
+    /// </summary>
+    public int MinRequiredHoles { get; set; }
+
+    /// <summary>
+    /// 推荐命中孔数（越接近越稳）
+    /// </summary>
+    public int PreferredHoleCount { get; set; }
+
+    /// <summary>
+    /// 是否允许对称复用
+    /// </summary>
+    public bool Symmetry { get; set; }
+
+    /// <summary>
+    /// 图样参考点（默认取图样中心）
+    /// </summary>
+    public double[] Position { get; set; } = new double[3];
+
+    /// <summary>
+    /// 图样参考法向（默认取安装面法向）
+    /// </summary>
+    public double[] Normal { get; set; } = new double[3];
+
+    /// <summary>
+    /// 图样置信度（0-1）
+    /// </summary>
+    public double Confidence { get; set; }
+
+    /// <summary>
+    /// 低置信度或歧义提示
+    /// </summary>
+    public List<string> Warnings { get; set; } = new();
+}
+
+/// <summary>
+/// 吸附面信息（v2.6 新增）
+/// </summary>
+public class SnapSurfaceInfo
+{
+    /// <summary>
+    /// 吸附面 ID（如 panel_001_snap_top）
+    /// </summary>
+    public string Id { get; set; } = "";
+
+    /// <summary>
+    /// 面标签：left / right / front / back / bottom / top
+    /// </summary>
+    public string Face { get; set; } = "";
+
+    /// <summary>
+    /// 所属板件 ID
+    /// </summary>
+    public string PanelId { get; set; } = "";
+
+    /// <summary>
+    /// 外法向量 [X, Y, Z]
+    /// </summary>
+    public double[] Normal { get; set; } = new double[3];
+
+    /// <summary>
+    /// 面中心 [X, Y, Z] (mm)
+    /// </summary>
+    public double[] Center { get; set; } = new double[3];
+
+    /// <summary>
+    /// 面边界框。薄轴最小值和最大值相同，表示该外表面所在平面。
+    /// </summary>
+    public BoundingBox3D Bounds { get; set; } = new();
+
+    /// <summary>
+    /// 推导置信度（0-1）
+    /// </summary>
+    public double Confidence { get; set; }
 }
 
 /// <summary>

autocad-plugin/FurnitureExporter/MountPatternAnalyzer.cs

@@ -0,0 +1,445 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace FurnitureExporter;
+
+/// <summary>
+/// 安装图样识别器。
+///
+/// 设计口径：
+/// - 吸附面（mount face）先缩小候选范围；
+/// - HoleGroup 负责把几何孔组织成业务孔位；
+/// - MountPattern 负责定义“至少命中几个孔才允许吸附成立”。
+/// </summary>
+public static class MountPatternAnalyzer
+{
+    private const double DefaultClusterDistanceMm = 220.0;
+
+    public static List<MountPatternInfo> BuildMountPatterns(
+        IReadOnlyList<PanelInfo> panels,
+        IReadOnlyList<HoleInfo> holes,
+        IReadOnlyList<HoleGroupInfo> holeGroups)
+    {
+        var patterns = new List<MountPatternInfo>();
+        if (panels == null || panels.Count == 0)
+        {
+            return patterns;
+        }
+
+        var holesByPanel = holes
+            .Where(h => !string.IsNullOrWhiteSpace(h.PanelId))
+            .GroupBy(h => h.PanelId, StringComparer.OrdinalIgnoreCase)
+            .ToDictionary(group => group.Key, group => group.ToList(), StringComparer.OrdinalIgnoreCase);
+
+        var groupsByPanel = holeGroups
+            .Where(group => !string.IsNullOrWhiteSpace(group.PanelId))
+            .GroupBy(group => group.PanelId, StringComparer.OrdinalIgnoreCase)
+            .ToDictionary(group => group.Key, group => group.ToList(), StringComparer.OrdinalIgnoreCase);
+
+        foreach (var panel in panels)
+        {
+            var panelHoles = holesByPanel.TryGetValue(panel.Id, out var panelHoleList)
+                ? panelHoleList
+                : new List<HoleInfo>();
+            var panelGroups = groupsByPanel.TryGetValue(panel.Id, out var panelGroupList)
+                ? panelGroupList
+                : new List<HoleGroupInfo>();
+
+            var units = BuildUnits(panel.Id, panelHoles, panelGroups);
+            if (units.Count == 0)
+            {
+                panel.MountPatterns = new List<MountPatternInfo>();
+                panel.SnapPatterns = new List<MountPatternInfo>();
+                continue;
+            }
+
+            var panelPatterns = new List<MountPatternInfo>();
+            var unitsByFace = units
+                .SelectMany(unit =>
+                    unit.MountFaces.Select(face => new { Face = face, Unit = unit }))
+                .GroupBy(item => item.Face, StringComparer.OrdinalIgnoreCase);
+
+            foreach (var faceGroup in unitsByFace)
+            {
+                var clusters = BuildClusters(faceGroup.Select(item => item.Unit).Distinct().ToList());
+                var patternIndex = 0;
+                foreach (var cluster in clusters)
+                {
+                    var pattern = BuildPattern(panel.Id, faceGroup.Key, patternIndex++, cluster);
+                    panelPatterns.Add(pattern);
+                }
+            }
+
+            panel.MountPatterns = panelPatterns;
+            panel.SnapPatterns = panelPatterns;
+            patterns.AddRange(panelPatterns);
+        }
+
+        return patterns;
+    }
+
+    public static void AttachPatternsToPanels(IReadOnlyList<PanelInfo> panels, IReadOnlyList<MountPatternInfo> patterns)
+    {
+        var map = patterns
+            .GroupBy(pattern => pattern.PanelId, StringComparer.OrdinalIgnoreCase)
+            .ToDictionary(group => group.Key, group => group.ToList(), StringComparer.OrdinalIgnoreCase);
+
+        foreach (var panel in panels)
+        {
+            var panelPatterns = map.TryGetValue(panel.Id, out var items)
+                ? items
+                : new List<MountPatternInfo>();
+            panel.MountPatterns = panelPatterns;
+            panel.SnapPatterns = panelPatterns;
+        }
+    }
+
+    private static List<MountPatternUnit> BuildUnits(
+        string panelId,
+        IReadOnlyList<HoleInfo> holes,
+        IReadOnlyList<HoleGroupInfo> holeGroups)
+    {
+        var units = new List<MountPatternUnit>();
+        var groupedHoleIds = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var group in holeGroups)
+        {
+            foreach (var holeId in group.HoleIds ?? Array.Empty<string>())
+            {
+                groupedHoleIds.Add(holeId);
+            }
+
+            var mountFaces = NormalizeMountFaces(group.SurfaceFaces, group.MountFace);
+            group.MountFace = mountFaces.FirstOrDefault() ?? "unknown";
+            units.Add(new MountPatternUnit
+            {
+                Id = group.Id,
+                PanelId = panelId,
+                HoleIds = group.HoleIds ?? Array.Empty<string>(),
+                Position = group.Position,
+                Normal = group.Normal,
+                GroupType = group.GroupType,
+                MountFaces = mountFaces,
+                Confidence = Clamp01(group.Confidence <= 0 ? 0.72 : group.Confidence),
+                Warnings = group.Warnings?.ToList() ?? new List<string>(),
+                Source = "hole-group",
+            });
+        }
+
+        foreach (var hole in holes)
+        {
+            if (groupedHoleIds.Contains(hole.Id))
+            {
+                continue;
+            }
+
+            units.Add(new MountPatternUnit
+            {
+                Id = hole.Id,
+                PanelId = panelId,
+                HoleIds = new[] { hole.Id },
+                Position = hole.Position,
+                Normal = hole.Normal,
+                GroupType = hole.HoleGroupType,
+                MountFaces = NormalizeMountFaces(hole.SurfaceFaces),
+                Confidence = Clamp01(hole.Confidence <= 0 ? 0.76 : hole.Confidence),
+                Warnings = hole.Warnings?.ToList() ?? new List<string>(),
+                Source = "single-hole",
+            });
+        }
+
+        return units;
+    }
+
+    private static List<List<MountPatternUnit>> BuildClusters(IReadOnlyList<MountPatternUnit> units)
+    {
+        var clusters = new List<List<MountPatternUnit>>();
+        var visited = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var unit in units)
+        {
+            if (!visited.Add(unit.Id))
+            {
+                continue;
+            }
+
+            var cluster = new List<MountPatternUnit>();
+            var queue = new Queue<MountPatternUnit>();
+            queue.Enqueue(unit);
+
+            while (queue.Count > 0)
+            {
+                var current = queue.Dequeue();
+                cluster.Add(current);
+
+                foreach (var candidate in units)
+                {
+                    if (visited.Contains(candidate.Id))
+                    {
+                        continue;
+                    }
+
+                    if (Distance(current.Position, candidate.Position) > DefaultClusterDistanceMm)
+                    {
+                        continue;
+                    }
+
+                    visited.Add(candidate.Id);
+                    queue.Enqueue(candidate);
+                }
+            }
+
+            clusters.Add(cluster.OrderBy(item => item.Position[0]).ThenBy(item => item.Position[1]).ThenBy(item => item.Position[2]).ToList());
+        }
+
+        return clusters;
+    }
+
+    private static MountPatternInfo BuildPattern(
+        string panelId,
+        string mountFace,
+        int patternIndex,
+        IReadOnlyList<MountPatternUnit> cluster)
+    {
+        var holeIds = cluster
+            .SelectMany(unit => unit.HoleIds)
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+
+        var warnings = cluster
+            .SelectMany(unit => unit.Warnings)
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .ToList();
+
+        var pointCount = cluster.Count;
+        var patternType = ResolvePatternType(cluster);
+        var isSymmetricRectangle = string.Equals(patternType, "rectangle_4", StringComparison.OrdinalIgnoreCase);
+        var minRequiredHoles = ResolveMinRequiredHoleCount(patternType, pointCount, isSymmetricRectangle);
+        var preferredHoleCount = pointCount;
+
+        var requiredHoleIds = Array.Empty<string>();
+        var optionalHoleIds = Array.Empty<string>();
+
+        if (pointCount <= 3 || !isSymmetricRectangle)
+        {
+            requiredHoleIds = holeIds;
+        }
+        else
+        {
+            optionalHoleIds = holeIds;
+            warnings.Add("四孔对称图样默认按 2 孔完成初始定位，剩余孔位作为增强固定。");
+        }
+
+        if (string.Equals(patternType, "generic", StringComparison.OrdinalIgnoreCase))
+        {
+            warnings.Add("当前图样由几何聚类自动生成，建议后续在资产录入阶段人工复核。");
+        }
+
+        return new MountPatternInfo
+        {
+            Id = $"{panelId}_mount_{mountFace}_{patternIndex:D3}",
+            PanelId = panelId,
+            MountFace = mountFace,
+            PatternType = patternType,
+            HoleIds = holeIds,
+            RequiredHoleIds = requiredHoleIds,
+            OptionalHoleIds = optionalHoleIds,
+            MinRequiredHoles = minRequiredHoles,
+            PreferredHoleCount = preferredHoleCount,
+            Symmetry = isSymmetricRectangle,
+            Position = AveragePosition(cluster),
+            Normal = ResolveMountFaceNormal(mountFace),
+            Confidence = ComputePatternConfidence(cluster, patternType, warnings.Count),
+            Warnings = warnings,
+        };
+    }
+
+    private static string ResolvePatternType(IReadOnlyList<MountPatternUnit> cluster)
+    {
+        return cluster.Count switch
+        {
+            1 => "single",
+            2 => "line_2",
+            3 => "triangle_3",
+            4 when IsRectangle(cluster) => "rectangle_4",
+            _ => "generic",
+        };
+    }
+
+    private static int ResolveMinRequiredHoleCount(string patternType, int pointCount, bool isSymmetricRectangle)
+    {
+        if (string.Equals(patternType, "single", StringComparison.OrdinalIgnoreCase))
+        {
+            return 1;
+        }
+
+        if (string.Equals(patternType, "line_2", StringComparison.OrdinalIgnoreCase))
+        {
+            return 2;
+        }
+
+        if (string.Equals(patternType, "triangle_3", StringComparison.OrdinalIgnoreCase))
+        {
+            return 3;
+        }
+
+        if (isSymmetricRectangle)
+        {
+            return 2;
+        }
+
+        if (pointCount <= 0)
+        {
+            return 1;
+        }
+
+        return pointCount <= 4 ? pointCount : Math.Min(pointCount, 4);
+    }
+
+    private static bool IsRectangle(IReadOnlyList<MountPatternUnit> cluster)
+    {
+        if (cluster.Count != 4)
+        {
+            return false;
+        }
+
+        var distances = new List<double>();
+        for (var i = 0; i < cluster.Count; i++)
+        {
+            for (var j = i + 1; j < cluster.Count; j++)
+            {
+                distances.Add(Distance(cluster[i].Position, cluster[j].Position));
+            }
+        }
+
+        distances.Sort();
+        if (distances.Count != 6)
+        {
+            return false;
+        }
+
+        var sideA = distances[0];
+        var sideB = distances[2];
+        var diagonalA = distances[4];
+        var diagonalB = distances[5];
+
+        return AreClose(sideA, distances[1], 0.12) &&
+               AreClose(sideB, distances[3], 0.12) &&
+               AreClose(diagonalA, diagonalB, 0.08);
+    }
+
+    private static double[] AveragePosition(IReadOnlyList<MountPatternUnit> cluster)
+    {
+        if (cluster.Count == 0)
+        {
+            return new[] { 0.0, 0.0, 0.0 };
+        }
+
+        return new[]
+        {
+            Math.Round(cluster.Average(item => item.Position[0]), 2),
+            Math.Round(cluster.Average(item => item.Position[1]), 2),
+            Math.Round(cluster.Average(item => item.Position[2]), 2),
+        };
+    }
+
+    private static double[] ResolveMountFaceNormal(string mountFace)
+    {
+        return mountFace.ToLowerInvariant() switch
+        {
+            "left" => new[] { -1.0, 0.0, 0.0 },
+            "right" => new[] { 1.0, 0.0, 0.0 },
+            "front" => new[] { 0.0, -1.0, 0.0 },
+            "back" => new[] { 0.0, 1.0, 0.0 },
+            "bottom" => new[] { 0.0, 0.0, -1.0 },
+            "top" => new[] { 0.0, 0.0, 1.0 },
+            _ => new[] { 0.0, 0.0, 1.0 },
+        };
+    }
+
+    private static double ComputePatternConfidence(
+        IReadOnlyList<MountPatternUnit> cluster,
+        string patternType,
+        int warningCount)
+    {
+        if (cluster.Count == 0)
+        {
+            return 0;
+        }
+
+        var baseConfidence = cluster.Average(item => item.Confidence);
+        if (string.Equals(patternType, "generic", StringComparison.OrdinalIgnoreCase))
+        {
+            baseConfidence = Math.Min(baseConfidence, 0.68);
+        }
+
+        if (warningCount > 0)
+        {
+            baseConfidence -= Math.Min(0.14, warningCount * 0.04);
+        }
+
+        return Math.Round(Clamp01(baseConfidence), 4);
+    }
+
+    private static string[] NormalizeMountFaces(IEnumerable<string>? faces, string? fallbackFace = null)
+    {
+        var normalized = (faces ?? Array.Empty<string>())
+            .Where(face => !string.IsNullOrWhiteSpace(face))
+            .Select(face => face.Trim().ToLowerInvariant())
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .ToList();
+
+        if (normalized.Count > 0)
+        {
+            return normalized.ToArray();
+        }
+
+        if (!string.IsNullOrWhiteSpace(fallbackFace))
+        {
+            return new[] { fallbackFace!.Trim().ToLowerInvariant() };
+        }
+
+        return new[] { "unknown" };
+    }
+
+    private static double Distance(IReadOnlyList<double> left, IReadOnlyList<double> right)
+    {
+        var dx = left[0] - right[0];
+        var dy = left[1] - right[1];
+        var dz = left[2] - right[2];
+        return Math.Sqrt(dx * dx + dy * dy + dz * dz);
+    }
+
+    private static bool AreClose(double left, double right, double toleranceRatio)
+    {
+        var baseValue = Math.Max(Math.Abs(left), Math.Abs(right));
+        if (baseValue <= 1e-6)
+        {
+            return true;
+        }
+
+        return Math.Abs(left - right) / baseValue <= toleranceRatio;
+    }
+
+    private static double Clamp01(double value)
+    {
+        if (value < 0) return 0;
+        if (value > 1) return 1;
+        return value;
+    }
+
+    private sealed class MountPatternUnit
+    {
+        public string Id { get; set; } = "";
+        public string PanelId { get; set; } = "";
+        public string[] HoleIds { get; set; } = Array.Empty<string>();
+        public double[] Position { get; set; } = new double[3];
+        public double[] Normal { get; set; } = new double[3];
+        public string? GroupType { get; set; }
+        public string[] MountFaces { get; set; } = Array.Empty<string>();
+        public double Confidence { get; set; }
+        public List<string> Warnings { get; set; } = new();
+        public string Source { get; set; } = "single-hole";
+    }
+}

autocad-plugin/FurnitureExporter/PanelAnalyzer.cs

@@ -210,8 +210,24 @@ public class PanelAnalyzer
             // 判断板材方向（法向量）
             var normal = DeterminePanelNormal(dims, size);
 
+            var panelBoundingBox = new BoundingBox3D
+            {
+                Min = new double[]
+                {
+                    Math.Round(ext.MinPoint.X + _originOffset.X, 2),
+                    Math.Round(ext.MinPoint.Y + _originOffset.Y, 2),
+                    Math.Round(ext.MinPoint.Z + _originOffset.Z, 2)
+                },
+                Max = new double[]
+                {
+                    Math.Round(ext.MaxPoint.X + _originOffset.X, 2),
+                    Math.Round(ext.MaxPoint.Y + _originOffset.Y, 2),
+                    Math.Round(ext.MaxPoint.Z + _originOffset.Z, 2)
+                }
+            };
+
             // 提取孔位
-            var holes = ExtractHoles(solid, $"panel_{index:D3}", thickness);
+            var holes = ExtractHoles(solid, $"panel_{index:D3}", thickness, panelBoundingBox);
 
             // v2.2.5：孔位过滤（与设计师“孔位口径”对齐）
             // - 极小薄件（如脚垫/垫片）不作为板件孔位统计对象，避免误把“几何细节”当孔
@@ -253,21 +269,7 @@ public class PanelAnalyzer
                     Math.Round(dims[2], 2)   // 厚
                 },
                 Normal = normal,
-                BoundingBox = new BoundingBox3D
-                {
-                    Min = new double[] 
-                    { 
-                        Math.Round(ext.MinPoint.X + _originOffset.X, 2),
-                        Math.Round(ext.MinPoint.Y + _originOffset.Y, 2),
-                        Math.Round(ext.MinPoint.Z + _originOffset.Z, 2)
-                    },
-                    Max = new double[] 
-                    { 
-                        Math.Round(ext.MaxPoint.X + _originOffset.X, 2),
-                        Math.Round(ext.MaxPoint.Y + _originOffset.Y, 2),
-                        Math.Round(ext.MaxPoint.Z + _originOffset.Z, 2)
-                    }
-                },
+                BoundingBox = panelBoundingBox,
                 Holes = holes
             };
         }
@@ -299,7 +301,11 @@ public class PanelAnalyzer
     /// <summary>
     /// 从板材实体中提取孔位信息
     /// </summary>
-    private List<HoleInfo> ExtractHoles(Solid3d solid, string panelId, double panelThickness)
+    private List<HoleInfo> ExtractHoles(
+        Solid3d solid,
+        string panelId,
+        double panelThickness,
+        BoundingBox3D panelBoundingBox)
     {
         var holes = new List<HoleInfo>();
         
@@ -315,7 +321,7 @@ public class PanelAnalyzer
                 var surface = BrepSurfaceUtils.Unwrap(face.Surface);
                 if (surface is Cylinder cylinder)
                 {
-                    var hole = ExtractHoleFromCylinder(cylinder, face, panelId, holeIndex, panelThickness);
+                    var hole = ExtractHoleFromCylinder(cylinder, face, panelId, holeIndex, panelThickness, panelBoundingBox);
                     if (hole != null)
                     {
                         holes.Add(hole);
@@ -326,7 +332,7 @@ public class PanelAnalyzer
                 {
                     // 柜脚/三角铁等五金件上常见“沉头孔/倒角孔”，其孔壁在 Brep 中可能表现为锥面（Cone），
                     // 仅识别 Cylinder 会漏掉这类孔位。
-                    var hole = ExtractHoleFromCone(cone, face, panelId, holeIndex, panelThickness);
+                    var hole = ExtractHoleFromCone(cone, face, panelId, holeIndex, panelThickness, panelBoundingBox);
                     if (hole != null)
                     {
                         holes.Add(hole);
@@ -344,7 +350,7 @@ public class PanelAnalyzer
                     // 某些孔位（尤其是五金件的沉头孔/复杂倒角）在 AutoCAD Brep 中，孔壁面可能被表达为 NurbSurface/其它曲面，
                     // 导致 surface is Cylinder/Cone 判断失败。
                     // 这里用“闭合圆边界 + 相邻端面平面法向推断孔轴”的方式做一次兜底，尽量补齐漏孔。
-                    var hole = ExtractHoleFromFallbackFace(face, panelId, holeIndex, panelThickness);
+                    var hole = ExtractHoleFromFallbackFace(face, panelId, holeIndex, panelThickness, panelBoundingBox);
                     if (hole != null)
                     {
                         holes.Add(hole);
@@ -374,7 +380,8 @@ public class PanelAnalyzer
         Autodesk.AutoCAD.BoundaryRepresentation.Face face,
         string panelId,
         int index,
-        double panelThickness)
+        double panelThickness,
+        BoundingBox3D panelBoundingBox)
     {
         try
         {
@@ -458,7 +465,12 @@ public class PanelAnalyzer
                 DetectionSource = "brep",
                 BindingSource = "panel_brep",
                 BindingConfidence = 1.0,
-                BindingReason = "从当前板件实体 Brep 直接提取"
+                BindingReason = "从当前板件实体 Brep 直接提取",
+                SurfaceFaces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                    panelBoundingBox,
+                    new[] { offsetPosition.X, offsetPosition.Y, offsetPosition.Z },
+                    new[] { axis.X, axis.Y, axis.Z },
+                    depth)
             };
         }
         catch
@@ -475,7 +487,8 @@ public class PanelAnalyzer
         Autodesk.AutoCAD.BoundaryRepresentation.Face face,
         string panelId,
         int index,
-        double panelThickness)
+        double panelThickness,
+        BoundingBox3D panelBoundingBox)
     {
         try
         {
@@ -560,7 +573,12 @@ public class PanelAnalyzer
                 DetectionSource = "brep",
                 BindingSource = "panel_brep",
                 BindingConfidence = 1.0,
-                BindingReason = "从当前板件实体 Brep 直接提取"
+                BindingReason = "从当前板件实体 Brep 直接提取",
+                SurfaceFaces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                    panelBoundingBox,
+                    new[] { offsetPosition.X, offsetPosition.Y, offsetPosition.Z },
+                    new[] { axis.X, axis.Y, axis.Z },
+                    depth)
             };
         }
         catch
@@ -577,7 +595,8 @@ public class PanelAnalyzer
         BrepFace face,
         string panelId,
         int index,
-        double panelThickness)
+        double panelThickness,
+        BoundingBox3D panelBoundingBox)
     {
         try
         {
@@ -651,7 +670,12 @@ public class PanelAnalyzer
                 DetectionSource = "brep",
                 BindingSource = "panel_brep",
                 BindingConfidence = 1.0,
-                BindingReason = "从当前板件实体 Brep 兜底面直接提取"
+                BindingReason = "从当前板件实体 Brep 兜底面直接提取",
+                SurfaceFaces = PanelFaceSemanticResolver.ResolveSurfaceFaces(
+                    panelBoundingBox,
+                    new[] { offsetPosition.X, offsetPosition.Y, offsetPosition.Z },
+                    new[] { axis.X, axis.Y, axis.Z },
+                    depth)
             };
         }
         catch

autocad-plugin/FurnitureExporter/PanelFaceSemanticResolver.cs

@@ -0,0 +1,226 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace FurnitureExporter;
+
+public static class PanelFaceSemanticResolver
+{
+    private const double SurfaceFaceToleranceMm = 3.0;
+    private const double InteriorFaceToleranceMm = 0.8;
+
+    public static string[] ResolveSurfaceFaces(
+        BoundingBox3D? boundingBox,
+        IReadOnlyList<double>? position,
+        IReadOnlyList<double>? normal,
+        double depth)
+    {
+        if (boundingBox?.Min?.Length != 3 || boundingBox.Max?.Length != 3)
+        {
+            return Array.Empty<string>();
+        }
+
+        var center = ToVector3(position);
+        var axis = Normalize(ToVector3(normal));
+        if (center == null || axis == null)
+        {
+            return Array.Empty<string>();
+        }
+
+        var faces = new List<string>();
+        var halfDepth = Math.Max(0, depth) / 2.0;
+        var dominantFaces = ResolveDominantAxisFaces(axis);
+
+        if (halfDepth > 0.01)
+        {
+            AddFace(
+                faces,
+                ResolveNearestSurfaceFace(
+                    boundingBox,
+                    Offset(center, axis, halfDepth),
+                    dominantFaces.Positive,
+                    dominantFaces.Negative,
+                    SurfaceFaceToleranceMm));
+            AddFace(
+                faces,
+                ResolveNearestSurfaceFace(
+                    boundingBox,
+                    Offset(center, axis, -halfDepth),
+                    dominantFaces.Negative,
+                    dominantFaces.Positive,
+                    SurfaceFaceToleranceMm));
+        }
+
+        if (faces.Count == 0)
+        {
+            AddFace(
+                faces,
+                ResolveNearestSurfaceFace(
+                    boundingBox,
+                    center,
+                    dominantFaces.Positive,
+                    dominantFaces.Negative,
+                    SurfaceFaceToleranceMm + InteriorFaceToleranceMm));
+        }
+
+        return faces
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+    }
+
+    public static string OppositeFace(string? face)
+    {
+        return face?.Trim().ToLowerInvariant() switch
+        {
+            "left" => "right",
+            "right" => "left",
+            "front" => "back",
+            "back" => "front",
+            "top" => "bottom",
+            "bottom" => "top",
+            _ => "unknown",
+        };
+    }
+
+    private static void AddFace(ICollection<string> faces, string? face)
+    {
+        if (string.IsNullOrWhiteSpace(face))
+        {
+            return;
+        }
+
+        faces.Add(face!.Trim().ToLowerInvariant());
+    }
+
+    private static double[]? ToVector3(IReadOnlyList<double>? value)
+    {
+        if (value == null || value.Count < 3)
+        {
+            return null;
+        }
+
+        return new[] { value[0], value[1], value[2] };
+    }
+
+    private static double[]? Normalize(double[]? value)
+    {
+        if (value == null)
+        {
+            return null;
+        }
+
+        var length = Math.Sqrt(value[0] * value[0] + value[1] * value[1] + value[2] * value[2]);
+        if (length < 1e-9)
+        {
+            return null;
+        }
+
+        return new[]
+        {
+            value[0] / length,
+            value[1] / length,
+            value[2] / length,
+        };
+    }
+
+    private static double[] Offset(double[] origin, double[] direction, double distance)
+    {
+        return new[]
+        {
+            origin[0] + direction[0] * distance,
+            origin[1] + direction[1] * distance,
+            origin[2] + direction[2] * distance,
+        };
+    }
+
+    private static string? ResolveNearestSurfaceFace(BoundingBox3D box, IReadOnlyList<double> point)
+    {
+        return ResolveNearestSurfaceFace(box, point, null, null, SurfaceFaceToleranceMm);
+    }
+
+    private static string? ResolveNearestSurfaceFace(
+        BoundingBox3D box,
+        IReadOnlyList<double> point,
+        string? preferredFace,
+        string? secondaryFace,
+        double tolerance)
+    {
+        var candidates = new List<(string Face, double Distance)>();
+
+        if (IsWithinRange(point[1], box.Min[1], box.Max[1], tolerance) &&
+            IsWithinRange(point[2], box.Min[2], box.Max[2], tolerance))
+        {
+            candidates.Add(("left", Math.Abs(point[0] - box.Min[0])));
+            candidates.Add(("right", Math.Abs(point[0] - box.Max[0])));
+        }
+
+        if (IsWithinRange(point[0], box.Min[0], box.Max[0], tolerance) &&
+            IsWithinRange(point[2], box.Min[2], box.Max[2], tolerance))
+        {
+            candidates.Add(("front", Math.Abs(point[1] - box.Min[1])));
+            candidates.Add(("back", Math.Abs(point[1] - box.Max[1])));
+        }
+
+        if (IsWithinRange(point[0], box.Min[0], box.Max[0], tolerance) &&
+            IsWithinRange(point[1], box.Min[1], box.Max[1], tolerance))
+        {
+            candidates.Add(("bottom", Math.Abs(point[2] - box.Min[2])));
+            candidates.Add(("top", Math.Abs(point[2] - box.Max[2])));
+        }
+
+        var best = candidates
+            .Where(item => item.Distance <= tolerance)
+            .OrderBy(item => GetFacePriority(item.Face, preferredFace, secondaryFace))
+            .ThenBy(item => item.Distance)
+            .FirstOrDefault();
+
+        return string.IsNullOrWhiteSpace(best.Face) ? null : best.Face;
+    }
+
+    private static (string Positive, string Negative) ResolveDominantAxisFaces(IReadOnlyList<double> axis)
+    {
+        var absX = Math.Abs(axis[0]);
+        var absY = Math.Abs(axis[1]);
+        var absZ = Math.Abs(axis[2]);
+
+        if (absX >= absY && absX >= absZ)
+        {
+            return axis[0] >= 0
+                ? ("right", "left")
+                : ("left", "right");
+        }
+
+        if (absY >= absX && absY >= absZ)
+        {
+            return axis[1] >= 0
+                ? ("back", "front")
+                : ("front", "back");
+        }
+
+        return axis[2] >= 0
+            ? ("top", "bottom")
+            : ("bottom", "top");
+    }
+
+    private static int GetFacePriority(string face, string? preferredFace, string? secondaryFace)
+    {
+        if (!string.IsNullOrWhiteSpace(preferredFace) &&
+            string.Equals(face, preferredFace, StringComparison.OrdinalIgnoreCase))
+        {
+            return 0;
+        }
+
+        if (!string.IsNullOrWhiteSpace(secondaryFace) &&
+            string.Equals(face, secondaryFace, StringComparison.OrdinalIgnoreCase))
+        {
+            return 1;
+        }
+
+        return 2;
+    }
+
+    private static bool IsWithinRange(double value, double min, double max, double tolerance)
+    {
+        return value >= min - tolerance && value <= max + tolerance;
+    }
+}

autocad-plugin/FurnitureExporter/SnapSurfaceBuilder.cs

@@ -0,0 +1,135 @@
+using System;
+using System.Collections.Generic;
+
+namespace FurnitureExporter;
+
+/// <summary>
+/// 从板件包围盒推导辅助装配吸附面。
+/// </summary>
+public static class SnapSurfaceBuilder
+{
+    private static readonly FaceDefinition[] Faces =
+    {
+        new("left", 0, false, new[] { -1.0, 0.0, 0.0 }),
+        new("right", 0, true, new[] { 1.0, 0.0, 0.0 }),
+        new("front", 1, false, new[] { 0.0, -1.0, 0.0 }),
+        new("back", 1, true, new[] { 0.0, 1.0, 0.0 }),
+        new("bottom", 2, false, new[] { 0.0, 0.0, -1.0 }),
+        new("top", 2, true, new[] { 0.0, 0.0, 1.0 }),
+    };
+
+    public static List<SnapSurfaceInfo> BuildSnapSurfaces(IReadOnlyList<PanelInfo> panels)
+    {
+        var allSurfaces = new List<SnapSurfaceInfo>();
+
+        foreach (var panel in panels)
+        {
+            var panelSurfaces = BuildPanelSurfaces(panel);
+            panel.SnapSurfaces = panelSurfaces;
+            allSurfaces.AddRange(panelSurfaces);
+        }
+
+        return allSurfaces;
+    }
+
+    private static List<SnapSurfaceInfo> BuildPanelSurfaces(PanelInfo panel)
+    {
+        var (min, max, confidence) = ResolveBounds(panel);
+        var surfaces = new List<SnapSurfaceInfo>(Faces.Length);
+
+        foreach (var face in Faces)
+        {
+            var center = new[]
+            {
+                Round((min[0] + max[0]) / 2.0),
+                Round((min[1] + max[1]) / 2.0),
+                Round((min[2] + max[2]) / 2.0),
+            };
+
+            var boundsMin = new[] { min[0], min[1], min[2] };
+            var boundsMax = new[] { max[0], max[1], max[2] };
+            var planeValue = face.UseMax ? max[face.Axis] : min[face.Axis];
+            center[face.Axis] = planeValue;
+            boundsMin[face.Axis] = planeValue;
+            boundsMax[face.Axis] = planeValue;
+
+            surfaces.Add(new SnapSurfaceInfo
+            {
+                Id = $"{panel.Id}_snap_{face.Name}",
+                Face = face.Name,
+                PanelId = panel.Id,
+                Normal = face.Normal,
+                Center = center,
+                Bounds = new BoundingBox3D
+                {
+                    Min = RoundAll(boundsMin),
+                    Max = RoundAll(boundsMax),
+                },
+                Confidence = confidence,
+            });
+        }
+
+        return surfaces;
+    }
+
+    private static (double[] Min, double[] Max, double Confidence) ResolveBounds(PanelInfo panel)
+    {
+        if (panel.BoundingBox?.Min?.Length == 3 && panel.BoundingBox.Max?.Length == 3)
+        {
+            return (RoundAll(panel.BoundingBox.Min), RoundAll(panel.BoundingBox.Max), 1.0);
+        }
+
+        var center = panel.Position?.Length == 3
+            ? panel.Position
+            : new[] { 0.0, 0.0, 0.0 };
+        var size = panel.Size?.Length == 3
+            ? panel.Size
+            : new[] { 0.0, 0.0, 0.0 };
+
+        var min = new[]
+        {
+            center[0] - Math.Abs(size[0]) / 2.0,
+            center[1] - Math.Abs(size[1]) / 2.0,
+            center[2] - Math.Abs(size[2]) / 2.0,
+        };
+        var max = new[]
+        {
+            center[0] + Math.Abs(size[0]) / 2.0,
+            center[1] + Math.Abs(size[1]) / 2.0,
+            center[2] + Math.Abs(size[2]) / 2.0,
+        };
+
+        return (RoundAll(min), RoundAll(max), 0.6);
+    }
+
+    private static double[] RoundAll(IReadOnlyList<double> values)
+    {
+        return new[]
+        {
+            Round(values[0]),
+            Round(values[1]),
+            Round(values[2]),
+        };
+    }
+
+    private static double Round(double value)
+    {
+        return Math.Round(value, 2);
+    }
+
+    private sealed class FaceDefinition
+    {
+        public FaceDefinition(string name, int axis, bool useMax, double[] normal)
+        {
+            Name = name;
+            Axis = axis;
+            UseMax = useMax;
+            Normal = normal;
+        }
+
+        public string Name { get; }
+        public int Axis { get; }
+        public bool UseMax { get; }
+        public double[] Normal { get; }
+    }
+}

autocad-plugin/README.md

@@ -1,13 +1,13 @@
 # AutoCAD 家具导出插件
 
-用于 AutoCAD 2024 的家具 3D 模型导出插件。导出板材模型和五金件安装位置，用于 Web 端 3D 展示和安装视频生成。
+用于 AutoCAD 2024 的家具 3D 模型导出插件。当前主流程是按资产中心口径导出单板材、单组件或单五金件，用于后续辅助装配和规格款入库。
 
 ## 功能特点
 
-- **只导出板材模型** - 五金件使用位置引用，文件体积小（1-3MB vs 30-50MB）
-- **自动分组五金件** - 按几何特征自动识别相同类型的五金件
-- **精确位置记录** - 记录每个五金件的安装位置和旋转角度
-- **服务端自动匹配** - 上传后自动匹配五金件库
+- **单资产导出** - `FEXPORT` 默认导出单板材、单组件或单五金件
+- **板材语义保留** - 导出孔位、孔组、吸附图样和吸附面，供辅助装配使用
+- **五金规格提取** - 单五金模式保留几何签名、图层类型和实例信息
+- **整套兼容保留** - 旧整套家具导出迁移到 `FEXPORTPRODUCT`
 
 ## 系统要求
 
@@ -20,7 +20,7 @@
 ### 方法 1：手动安装发版包（推荐给产品/实施）
 
 1. 完全关闭 AutoCAD 2024
-2. 解压 `dist/家具导出插件-v2.3.1-一键安装版.zip`
+2. 解压 `dist/家具导出插件-v2.6.0-一键安装版.zip`
 3. 将整个 `FurnitureExporter.bundle` 文件夹复制到：
 
 ```text
@@ -39,7 +39,7 @@
 
 ### 方法 2：一键安装
 
-双击 `dist/家具导出插件-v2.3.1-一键安装版/安装.bat`
+双击 `dist/家具导出插件-v2.6.0-一键安装版/安装.bat`
 
 脚本会自动：
 1. 复制插件到 `%AppData%\Autodesk\ApplicationPlugins\FurnitureExporter.bundle`
@@ -90,7 +90,7 @@ dotnet build -c Release
 
 ## 使用方法
 
-### FEXPORT - 导出家具模型
+### FEXPORT - 导出单资产到资产中心
 
 ```
 命令: FEXPORT
@@ -98,13 +98,21 @@ dotnet build -c Release
 
 **操作步骤：**
 
-1. **选择板材** - 框选所有板材实体，按 Enter 确认
-2. **选择五金件** - 框选所有五金件，按 Enter 确认（可跳过）
-3. **保存文件** - 选择保存位置
+1. **选择资产类型** - 板材 / 组件 / 五金
+2. **选择实体** - 框选该单资产包含的 3D Solid 或图块，按 Enter 确认
+3. **保存文件** - 选择 ZIP 保存位置
 
-**输出文件：** `xxx_export.zip`，包含：
-- `model.glb` - 板材 3D 模型
-- `hardware.json` - 五金件位置数据
+**输出文件：** `xxx_board_asset.zip` / `xxx_component_asset.zip` / `xxx_hardware_asset.zip`，包含：
+- `model.obj` - 单资产模型
+- `hardware.json` - 单资产结构化数据，包含 `exportMode: "single_asset"` 与 `assetTypeHint`
+
+### FEXPORTPRODUCT - 整套家具兼容导出
+
+```
+命令: FEXPORTPRODUCT
+```
+
+仅用于旧产品链路兼容。新资产中心和辅助装配测试请优先使用 `FEXPORT`。
 
 ### FINFO - 查看实体信息
 
@@ -120,36 +128,19 @@ dotnet build -c Release
 
 ```json
 {
-  "version": "1.0",
-  "exportedAt": "2024-01-15T10:30:00Z",
-  "sourceFile": "衣柜.dwg",
+  "version": "2.6",
+  "exportedAt": "2026-05-11T10:30:00Z",
+  "sourceFile": "桌腿.dwg",
   "software": "AutoCAD 2024",
-  "pluginVersion": "1.0.0",
-  "modelFile": "model.glb",
-  "panelCount": 12,
-  "hardwareTypes": [
-    {
-      "typeId": "type_000",
-      "signature": {
-        "width": 35.0,
-        "height": 12.0,
-        "depth": 12.0,
-        "volume": 4032.5
-      },
-      "instances": [
-        {
-          "position": { "x": 100.0, "y": 50.0, "z": 18.0 },
-          "rotation": { "x": 0, "y": 0, "z": 1.5708 },
-          "sourceLayer": "五金件"
-        },
-        {
-          "position": { "x": 100.0, "y": 150.0, "z": 18.0 },
-          "rotation": { "x": 0, "y": 0, "z": 1.5708 },
-          "sourceLayer": "五金件"
-        }
-      ]
-    }
-  ]
+  "pluginVersion": "2.6.0",
+  "modelFile": "model.obj",
+  "exportMode": "single_asset",
+  "assetTypeHint": "COMPONENT",
+  "sourceEntityCount": 1,
+  "panelCount": 1,
+  "snapPatterns": [],
+  "snapSurfaces": [],
+  "hardwareTypes": []
 }
 ```
 
@@ -160,17 +151,17 @@ dotnet build -c Release
 ───────                        ──────
 1. 打开 DWG 文件
 2. FEXPORT
-3. 框选板材 ────────────────→
-4. 框选五金件 ──────────────→
-5. 保存 ZIP ────────────────→ 上传 ZIP
+3. 选择资产类型（板材/组件/五金）
+4. 框选单个资产实体 ───────→
+5. 保存 ZIP ────────────────→ 上传到资产中心
                               ↓
                            自动解析
                               ↓
-                           匹配五金件库
+                           创建/更新资产族规格款
                               ↓
                            保存到数据库
                               ↓
-                           3D 预览 ✓
+                           辅助装配可用 ✓
 ```
 
 ## 开发

autocad-plugin/build-installer.ps1

@@ -49,7 +49,7 @@ Write-Host ""
 
 # 路径设置
 $PluginName = "FurnitureExporter"
-$Version = "2.5.0"
+$Version = "2.6.0"
 $SourceDir = Join-Path $PSScriptRoot "FurnitureExporter"
 $InstallerDir = Join-Path $PSScriptRoot "installer"
 $OutputDir = Join-Path $PSScriptRoot "dist"
@@ -90,7 +90,7 @@ $PackageXml = @"
     SchemaVersion="1.0" 
     AutodeskProduct="AutoCAD"
     Name="$PluginName"
-    Description="家具导出插件 v$Version - 支持整套兼容导出与资产中心单资产导出"
+    Description="家具导出插件 v$Version - 默认资产中心单资产导出，保留整套兼容导出"
     Author="Furniture 3D System"
     AppVersion="$Version"
     FriendlyVersion="$Version"
@@ -119,7 +119,7 @@ $PackageXml = @"
         AppName="$PluginName"
         Version="$Version"
         ModuleName="./Contents/$PluginName.dll"
-        AppDescription="家具导出插件 - 支持整套兼容导出与资产中心单资产导出"
+        AppDescription="家具导出插件 - 默认资产中心单资产导出，保留整套兼容导出"
         LoadOnAutoCADStartup="True"
         AppType="Net" />
   </Components>
@@ -306,7 +306,7 @@ New-ItemProperty -Path $appKey -Name "DESCRIPTION" -PropertyType String -Value "
 Write-Step "[3/3] 完成"
 Write-Host ""
 Write-Host "安装完成。请完全关闭 AutoCAD 后重新启动。" -ForegroundColor Green
-Write-Host "启动后命令行输入：FEXPORTASSET（单资产）或 FEXPORT（整套兼容）" -ForegroundColor Green
+Write-Host "启动后命令行输入：FEXPORT（单资产）或 FEXPORTPRODUCT（整套兼容）" -ForegroundColor Green
 Write-Host ""
 '@
 Write-TextFileUtf8Bom -Path (Join-Path $InstallerDir "install.ps1") -Content $InstallPs1
@@ -480,8 +480,10 @@ $Readme = @"
 使用方法
 ───────────────────────────────────────────────────────────────────────
 打开 AutoCAD 后，命令行输入：
-  FEXPORTASSET -> 单资产导出到资产中心（板材 / 组件 / 五金）
-  FEXPORT      -> 整套家具兼容导出
+  FEXPORT        -> 单资产导出到资产中心（板材 / 组件 / 五金）
+  FEXPORTASSET   -> 单资产导出别名
+  FEXPORTPRODUCT -> 整套家具兼容导出
+  FEXPORTBUNDLE  -> 整套家具兼容导出别名
   FINFO        -> 查看实体信息
 
 安装脚本做了什么（便于 IT/排查）
@@ -495,7 +497,7 @@ $Readme = @"
 
 常见问题
 ───────────────────────────────────────────────────────────────────────
-Q: 提示“未知命令 FEXPORTASSET / FEXPORT”
+Q: 提示“未知命令 FEXPORT / FEXPORTPRODUCT”
 A: 1) 确认已重启 AutoCAD（关闭再打开）
    2) 确认插件目录存在：
       %AppData%\Autodesk\ApplicationPlugins\FurnitureExporter.bundle\Contents\FurnitureExporter.dll

autocad-plugin/build.cmd

@@ -75,7 +75,8 @@ if %ERRORLEVEL% EQU 0 (
     echo   1. 打开 AutoCAD 2024
     echo   2. 输入命令: NETLOAD
     echo   3. 选择上述 DLL 文件
-    echo   4. 使用命令: FEXPORT 导出模型
+    echo   4. 使用命令: FEXPORT 导出单资产模型
+    echo      旧整套兼容导出: FEXPORTPRODUCT
     echo.
 ) else (
     echo.

autocad-plugin/build.ps1

@@ -84,7 +84,8 @@ try {
         Write-Host "  1. 打开 AutoCAD 2024"
         Write-Host "  2. 输入命令: NETLOAD"
         Write-Host "  3. 选择上述 DLL 文件"
-        Write-Host "  4. 使用命令: FEXPORT 导出模型"
+        Write-Host "  4. 使用命令: FEXPORT 导出单资产模型"
+        Write-Host "     旧整套兼容导出: FEXPORTPRODUCT"
         Write-Host ""
     }
     else {

autocad-plugin/installer/FurnitureExporter.bundle/PackageContents.xml

@@ -3,12 +3,12 @@
     SchemaVersion="1.0" 
     AutodeskProduct="AutoCAD"
     Name="FurnitureExporter"
-    Description="家具导出插件 v2.5.0 - 支持整套兼容导出与资产中心单资产导出"
+    Description="家具导出插件 v2.6.0 - 默认资产中心单资产导出，保留整套兼容导出"
     Author="Furniture 3D System"
-    AppVersion="2.5.0"
-    FriendlyVersion="2.5.0"
+    AppVersion="2.6.0"
+    FriendlyVersion="2.6.0"
     ProductType="Application"
-    Version="2.5.0"
+    Version="2.6.0"
     ProductCode="{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}">
     
   <CompanyDetails 
@@ -30,9 +30,9 @@
         
     <ComponentEntry 
         AppName="FurnitureExporter"
-        Version="2.5.0"
+        Version="2.6.0"
         ModuleName="./Contents/FurnitureExporter.dll"
-        AppDescription="家具导出插件 - 支持整套兼容导出与资产中心单资产导出"
+        AppDescription="家具导出插件 - 默认资产中心单资产导出，保留整套兼容导出"
         LoadOnAutoCADStartup="True"
         AppType="Net" />
   </Components>

autocad-plugin/installer/install.ps1

@@ -174,5 +174,5 @@ New-ItemProperty -Path $appKey -Name "DESCRIPTION" -PropertyType String -Value "
 Write-Step "[3/3] 完成"
 Write-Host ""
 Write-Host "安装完成。请完全关闭 AutoCAD 后重新启动。" -ForegroundColor Green
-Write-Host "启动后命令行输入：FEXPORTASSET（单资产）或 FEXPORT（整套兼容）" -ForegroundColor Green
+Write-Host "启动后命令行输入：FEXPORT（单资产）或 FEXPORTPRODUCT（整套兼容）" -ForegroundColor Green
 Write-Host ""

autocad-plugin/installer/使用说明.txt

@@ -1,5 +1,5 @@
 ═══════════════════════════════════════════════════════════════════════
-                    家具导出插件 v2.5.0 - 安装指南
+                    家具导出插件 v2.6.0 - 安装指南
 ═══════════════════════════════════════════════════════════════════════
 
 安装步骤（只需30秒）
@@ -16,8 +16,10 @@
 使用方法
 ───────────────────────────────────────────────────────────────────────
 打开 AutoCAD 后，命令行输入：
-  FEXPORTASSET -> 单资产导出到资产中心（板材 / 组件 / 五金）
-  FEXPORT      -> 整套家具兼容导出
+  FEXPORT        -> 单资产导出到资产中心（板材 / 组件 / 五金）
+  FEXPORTASSET   -> 单资产导出别名
+  FEXPORTPRODUCT -> 整套家具兼容导出
+  FEXPORTBUNDLE  -> 整套家具兼容导出别名
   FINFO        -> 查看实体信息
 
 安装脚本做了什么（便于 IT/排查）
@@ -31,10 +33,10 @@
 
 常见问题
 ───────────────────────────────────────────────────────────────────────
-Q: 提示“未知命令 FEXPORTASSET / FEXPORT”
+Q: 提示“未知命令 FEXPORT / FEXPORTPRODUCT”
 A: 1) 确认已重启 AutoCAD（关闭再打开）
    2) 确认插件目录存在：
       %AppData%\Autodesk\ApplicationPlugins\FurnitureExporter.bundle\Contents\FurnitureExporter.dll
    3) 如果 SECURELOAD=2，脚本会将其降到 1；如仍无效请截图安装日志给开发排查
 
-版本: v2.5.0
+版本: v2.6.0

docs/Precision-Atelier设计系统改造记录.md

@@ -212,3 +212,69 @@
 | `src/app/warehouse/WarehouseClient.tsx` | 移除 headerTools/eyebrow |
 | `src/app/HomeClient.workspace.tsx` | 移除 topTools 传参 |
 | ~20 个业务文件 | 硬编码颜色替换 |
+
+---
+
+## 第三阶段：管理基础设施视觉升级 (2026-04-16)
+
+### 10. 管理端专属视觉模式 (Management UI Patterns)
+
+在重构 `/admin` 和 `/users` 页面时，引入了针对“高密度控制类页面”的增强视觉模式，以平衡“工业精密感”与“视觉通透度”。
+
+**1. 沉浸式页头 (Immersive Page Header)**
+- **视觉特征**：
+  - 采用 `bg-white/60` + `backdrop-blur-2xl`。
+  - 强化左侧 Icon 视觉，使用 `rounded-[2rem] bg-black` 黑色底座，并叠加状态徽章（如 `ShieldCheck`）。
+  - **排版建议**：Manrope 3XL 标题 + 紧跟其后的 `text-apple-blue` 高亮关键词。
+  - **副标题**：使用 `text-[10px] tracking-[0.4em] uppercase` 的精密说明文字。
+
+**2. 精密控制条 (Precision Control Bar)**
+- **定义**：将原本分散的“搜索框”与“筛选器”整合进一个逻辑整体。
+- **视觉实现**：
+  - 容器：`rounded-[2rem]` 极圆圆角，`border-white/80` 微光边框，`bg-white/40` 背景。
+  - 搜索框：沉浸式设计，背景为 `bg-white/80`，聚焦时通过 `ring-apple-blue/5` 产生柔和晕染。
+  - 筛选器：图标 (Lucide Icon) + Select 组件的紧凑组合，图标作为装饰前缀。
+
+**3. 玻璃态卡片增强 (Enhanced Glass Cards)**
+- **改动**：在 `rounded-[2rem]` 的基础上，引入了“装饰线”动效。
+- **动效逻辑**：`group-hover:w-full` 的底部 1.5px 强调线，颜色与模块 Icon 色调一致。
+- **背景文字装饰**：绝对定位的 `text-[80px]` 背景大字（如模块 path），设置 `opacity-[0.03]` 极低透明度，增加“空间感”。
+
+**4. 状态指标看板 (System Health Dashboard)**
+- 应用场景：`/admin` 首页。
+- 组成：Icon 容器 + 上下两行文本（上行为微缩标签，下行为状态值）。
+- 配色：动态使用 `emerald-500` (正常), `blue-500` (活动), `amber-500` (注意)。
+
+**5. 三栏工作区 (Three-Column Workspace)**
+- 应用场景：`/asset-center/material-library`。
+- 定义：左侧极简分类 (Navigation) + 中间响应式网格 (Grid) + 右侧实时定义面板 (Inspector)。
+- 优势：极大降低页面跳转成本，实现“即时反馈”。
+
+**6. 精密滑块交互 (Precision Sliders)**
+- 视觉表现：细条轨道 + 圆形 Thumb + 右侧数值百分比徽章。
+- 应用场景：物理参数调节 (Metallic/Roughness/Opacity)。
+- 规范：取代原有的输入框，滑动步长固定为 0.01 (1%)。
+
+**7. 悬浮坞系统 (Floating Dock System)**
+- 应用场景：`/assisted-assembly`。
+- 定义：左侧布局的交互式入口，采用 `bg-black/60` + `backdrop-blur-3xl`。
+- 动效：点击后向右水平展开列表。
+- 逻辑：通过视觉发光 (Glow) 和计数徽标反馈当前分类的选择状态。
+
+**8. 环境 HUD (Ambient HUD)**
+- 定义：底部的非侵入式信息条。
+- 样式：极圆胶囊型，`backdrop-blur-xl`。
+- 作用：提供当前操作环境的实时状态（如“捕捉已就绪”）。
+
+### 11. 改动文件清单
+
+| 文件 | 改动类型 | 备注 |
+|------|----------|------|
+| `src/app/admin/page.tsx` | 重构 | 系统总控制台首页视觉重载 |
+| `src/app/users/page.tsx` | 重构 | 身份控制中心 (用户管理) 三栏重写 |
+| `src/app/asset-center/material-library/MaterialLibraryClient.tsx` | 重构 | 材质库首页视觉重写 (草稿图 12.png) |
+| `src/app/assisted-assembly/AssistedAssemblyClient.tsx` | 重构 | 拼装工作台沉浸式重写 & 引入 Floating Dock |
+| `src/components/platform/PlatformSplitLayout.tsx` | 基础重构 | 统一加装 backHref 导航标准 |
+
+
+

docs/前端UI改动清单.md

@@ -1,28 +1,47 @@
-# 前端 UI 改动清单
+# 协作任务板
 
-> 这份文档只保留"正在进行 / 未完成 / 待联调"的前端交接项。
-> 已完成且已确认正确的内容，直接删除，不保留历史记录。
-> 前端 UI agent 只按本文档执行；如果联调后确认是接口、数据、保存链路、状态口径问题，再回传后端 agent。
+## 已完成任务 (Completed)
+
+- **管理基础设施视觉升级 (Management Infrastructure UI Refactor)**
+  - **重构页面**：
+    - `系统总控制台 (/admin)`：引入“中枢枢纽”布局，增加系统状态看板 (Mock)，优化卡片视觉张力。
+    - `身份控制中心 (/users)`：引入“沉浸式页头”与“精密控制条”，整合搜索与筛选器。
+  - **负责人**：Gemini UI Engineer
+  - **完成日期**：2026-04-16
+
+- **基础资料库重构 (Material Library Pro Refactor)**
+  - **参考稿**：基于用户草稿 (12.png) 与 Precision Atelier 规范。
+  - **核心改动**：
+    - **三栏架构**：左侧分类 - 中间网格 - 右侧实时工作区。
+    - **实时预览 (Real-time Preview)**：面板顶部集成大面积材质物理表现预览。
+    - **精密滑块 (Precision Sliders)**：金属度、粗糙度、透明度全部由 Input 切换为 Slider 交互。
+    - **网格升级**：优化了花色卡片的视觉尺寸与 Metadata（元数据）展示。
+  - **负责人**：Gemini UI Engineer
+  - **完成日期**：2026-04-16
+
+- **辅助装配工作台沉浸式重构 (Assisted Assembly Workbench Immersive Refactor)**
+  - **重构页面**：`辅助装配工作台 (/assisted-assembly)`。
+  - **核心改动**：
+    - **沉浸式 3D 画布**：移除所有边框，采用 `#0c0e10` 深邃背景，占据 100% 中心区域。
+    - **悬浮 Dock 系统 (Floating Dock)**：左侧零件选择改为三个磨砂玻璃质感的悬浮坞（板件/支撑/连接件），支持平滑展开与计数反馈。
+    - **实时装配报告 (Inspector)**：右侧面板重塑为技术报告风格，展示拓扑节点、已连接对数及结构稳固性指标。
+    - **环境提示条 (Ambient HUD)**：底部增加半透明环境信息条，提示“孔位捕捉已就绪”。
+    - **导航标准化**：加装“资产中心 / 拼装”精密返回按钮。
+  - **负责人**：Gemini UI Engineer
+  - **完成日期**：2026-04-17
 
-## 处理归属说明
 
-- `前端负责`：视觉、布局、交互、动效、前端展示层接线。
-- `联调确认`：先按当前实现点流程；若发现根因在接口、数据、保存失败、状态不一致，再转后端。
-- **重要边界**：
-  - 前端 `agent` 只负责前端层，不负责拍板业务真相，不负责改接口，不负责改数据库，不负责处理保存链路真相。
-  - 只要问题已经超出“展示层接线 / 复用现有前端能力”的边界，就停止继续扩写，并回传后端 `agent`。
 
 ---
 
-## 当前未完成项
+## 进行中任务 (In Progress)
 
-- 当前无未完成前端交接项。
-- 2026-03-26 已完成交互重构：
-  - 背景改为淡灰底色+40px网格线（匹配图2资产中心）
-  - 物料区交互：预览图列表 + hover显示Tooltip + 拖拽到3D区后弹出规格款选择
-  - 类型检查通过，测试通过
-- 2026-04-10 已确认：
-  - `type-check（类型检查）` 通过
-  - 辅助装配相关单元测试通过
-  - 测试环境已完成部署
-  - 真实页面已完成最小联调：登录后进入 `辅助装配（assisted assembly）`，勾选资产族后左侧物料区可正常出现 `加入工作台`
+- assisted-assembly（辅助装配）：真实样本联调与验收
+  - 负责人：Codex
+  - 当前进展：
+    - 已补回孔位吸附的真实距离闸门，避免组件离目标过远时仍被误判为可吸附。
+    - 已移除缺少孔位 / 安装图样语义时回退到旧中心点假吸附的旧逻辑。
+    - 已将右侧提示收口为状态反馈卡，可区分“已进入吸附范围 / 缺少安装图样语义 / 缺少孔位语义”等状态。
+    - 已补齐辅助装配工作台与装配规则层回归测试，并通过 `jest（测试）` 与 `type-check（类型检查）`。
+  - 待完成：
+    - 用真实样本在浏览器里完成最终点验，确认拖拽、预吸附、松手吸附与右侧提示在真实模型下都一致。

furniture-3d-system/.dockerignore

@@ -75,7 +75,6 @@ dist
 
 # Gatsby文件
 .cache/
-public
 
 # Vuepress构建输出
 .vuepress/dist
@@ -225,4 +224,4 @@ PROJECT_SETUP_COMPLETE.md
 产品安装展示系统-*.md
 开发部署计划.md
 项目*.md
-架构*.md
+架构*.md

furniture-3d-system/.env.example

@@ -0,0 +1,220 @@
+# 本地运行
+NODE_ENV=development
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# 数据库
+DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB_NAME?schema=public
+
+# 员工工时花名只读人员配置来源（可选；开发环境配置后会合并正式人员配置）
+SUPPLY_CHAIN_PRODUCT_ARCHIVE_READ_DATABASE_URL=postgresql://READ_USER:READ_PASSWORD@READ_HOST:5432/READ_DB
+SUPPLY_CHAIN_PRODUCT_ARCHIVE_READ_DATABASE_SSL_REJECT_UNAUTHORIZED=true
+
+# 产品全量档案的聚水潭 SQL Server 只读来源
+JST_REPORT_DB_HOST=
+JST_REPORT_DB_PORT=1433
+JST_REPORT_DB_NAME=
+JST_REPORT_DB_SCHEMA=rpt
+JST_REPORT_DB_USER=
+JST_REPORT_DB_PASSWORD=
+JST_REPORT_DB_ENCRYPT=true
+JST_REPORT_DB_TRUST_SERVER_CERTIFICATE=true
+# 换货规则表 app.jst_sku_replace_rule 与 rpt 视图使用独立授权；留空时复用上面的主机、库和账号。
+JST_SKU_REPLACE_RULE_SCHEMA=app
+JST_SKU_REPLACE_RULE_DB_USER=
+JST_SKU_REPLACE_RULE_DB_PASSWORD=
+# 停产下架链接日快照最大导入延迟（小时）；超时保留已有链接。
+JST_DISCONTINUATION_LINK_MAX_AGE_HOURS=26
+# 数据库链接快照仅用于诊断；低于已有链接该比例时拒绝覆盖。
+JST_DM_MIN_EXISTING_COVERAGE_RATIO=0.5
+
+# 停产下架服务器 Chrome / RPA。
+JST_RPA_BROWSER_URL=http://127.0.0.1:9222
+JST_RPA_PROFILE_DIR=
+JST_RPA_CHROME_EXECUTABLE=
+JST_RPA_HEADLESS=true
+JST_RPA_DEBUG_PORT=9222
+JST_RPA_PYTHON=/usr/bin/python3
+# 聚水潭账号密码登录，仅配置在服务器私有环境文件，禁止提交真实值。
+JST_RPA_LOGIN_ID=
+JST_RPA_LOGIN_PASSWORD=
+JST_RPA_ATTEMPTS=3
+JST_RPA_FALLBACK_BATCH_SIZE=10000
+# 限价流程历史快照首次构建的追溯起点；后续只按更新时间增量同步。
+LIMIT_PRICE_HISTORY_SOURCE_START=2026-01-01T00:00:00
+# 产品限价页面已确认记录来源库（限价历史抽屉展示来源记录时使用）。
+PROD_ARCHIVE_DB_HOST=
+PROD_ARCHIVE_DB_PORT=5432
+PROD_ARCHIVE_DB_NAME=
+PROD_ARCHIVE_DB_USER=
+PROD_ARCHIVE_DB_PASSWORD=
+PROD_ARCHIVE_DB_SSL=true
+
+# OA 新品流程看板数据源。默认 mysql；切换到 JSReportReplica 时设为 mssql。
+OA_BOARD_SOURCE_DRIVER=mysql
+# MySQL 来源兼容配置。
+OA_BOARD_SOURCE_DB_HOST=
+OA_BOARD_SOURCE_DB_PORT=3306
+OA_BOARD_SOURCE_DB_NAME=
+OA_BOARD_SOURCE_DB_USER=
+OA_BOARD_SOURCE_DB_PASSWORD=
+OA_BOARD_SOURCE_DB_CHARSET=utf8mb4
+OA_BOARD_SOURCE_DB_SSL=false
+
+# SQL Server 来源：JSReportReplica.rpt 的 ding_Workflow、ding_WorkflowScheme、ding_WorkflowTask 只读视图。
+# 使用 mssql 来源时，快照仍写入下方配置的企划 MySQL 库。
+OA_BOARD_MSSQL_HOST=
+OA_BOARD_MSSQL_PORT=1433
+OA_BOARD_MSSQL_DATABASE=JSReportReplica
+OA_BOARD_MSSQL_SCHEMA=rpt
+OA_BOARD_MSSQL_USERNAME=
+OA_BOARD_MSSQL_PASSWORD=
+OA_BOARD_MSSQL_ENCRYPT=false
+OA_BOARD_MSSQL_TRUST_SERVER_CERTIFICATE=true
+OA_BOARD_MSSQL_CONNECTION_TIMEOUT_MS=15000
+OA_BOARD_MSSQL_REQUEST_TIMEOUT_MS=120000
+
+# OA 看板快照目标（MySQL）。留空时兼容复用 PLANNING_DATABASE_URL / PLANNING_DB_*。
+# 配置此组变量后，可保证切换 SQL Server 来源时所有快照、超时跟进和日报数据仍保存在企划库。
+OA_BOARD_SNAPSHOT_DATABASE_URL=
+OA_BOARD_SNAPSHOT_DB_HOST=
+OA_BOARD_SNAPSHOT_DB_PORT=3306
+OA_BOARD_SNAPSHOT_DB_NAME=
+OA_BOARD_SNAPSHOT_DB_USER=
+OA_BOARD_SNAPSHOT_DB_PASSWORD=
+OA_BOARD_SNAPSHOT_DB_CHARSET=utf8mb4
+OA_BOARD_SNAPSHOT_DB_SSL=false
+
+# HR 员工目录（SQL Server）。OA 快照仅在本地员工目录无法匹配时使用，
+# 用于将 ding_WorkflowTask.userId 解析成当前负责人的姓名。
+HR_SQLSERVER_HOST=
+HR_SQLSERVER_PORT=1433
+HR_SQLSERVER_DATABASE=
+HR_SQLSERVER_USERNAME=
+HR_SQLSERVER_PASSWORD=
+HR_SQLSERVER_ENCRYPT=false
+HR_SQLSERVER_TRUST_SERVER_CERTIFICATE=true
+
+# 产品资料供应商与仓库目录（SQL Server 报表库，只读）
+JST_PLANNING_SQLSERVER_HOST=
+JST_PLANNING_SQLSERVER_PORT=1433
+JST_PLANNING_SQLSERVER_DATABASE=
+JST_PLANNING_SQLSERVER_USERNAME=
+JST_PLANNING_SQLSERVER_PASSWORD=
+JST_PLANNING_SQLSERVER_SCHEMA=rpt
+JST_PLANNING_SQLSERVER_ENCRYPT=false
+JST_PLANNING_SQLSERVER_TRUST_SERVER_CERTIFICATE=true
+
+# 登录和令牌
+JWT_SECRET=replace-with-random-secret
+JWT_EXPIRES_IN=7d
+
+# 钉钉登录（OAuth 应用；只用于登录授权和用户信息获取）
+DINGTALK_LOGIN_CLIENT_ID=
+DINGTALK_LOGIN_CLIENT_SECRET=
+DINGTALK_CALLBACK_ORIGIN=
+
+# 钉钉开放平台 API（通讯录、待办、审批等服务端调用）
+DINGTALK_API_CLIENT_ID=
+DINGTALK_API_CLIENT_SECRET=
+
+# 钉钉待办：OA 阶段超时预警，以及预计出货日前 15 天的品牌策划主管提醒。
+DINGTALK_TODO_ENABLED=false
+DINGTALK_TODO_DETAIL_BASE_URL=
+DINGTALK_TODO_SOURCE_APP=oa-board
+DINGTALK_TODO_ESCALATION_ENABLED=false
+DINGTALK_TODO_ESCALATION_DAYS=3
+# DINGTALK_AGENT_ID=
+
+# 清货池多包标记钉钉通知：填写在职员工目录中的姓名，默认推送卷帘大将。
+SUPPLY_CHAIN_CLEARANCE_COMBO_NOTIFICATION_RECIPIENT=卷帘大将
+
+# 由壹点通知中心（仅服务端使用，项目密钥禁止提交或暴露给浏览器）
+YYD_NOTIFICATION_CENTER_URL=https://sc.jiansun.vip/notification-center
+YYD_NOTIFICATION_PROJECT_CODE=furniture_platform
+YYD_NOTIFICATION_PROJECT_SECRET=
+YYD_NOTIFICATION_TIMEOUT_MS=10000
+
+# 店铺账号新增时，梦汐/扬灵群使用的钉钉“由壹点”群机器人。
+# webhook 地址和签名密钥只配置在本地/正式站运行环境，不要提交真实值。
+DINGTALK_STORE_ACCOUNT_GROUP_WEBHOOK_URL=
+DINGTALK_STORE_ACCOUNT_GROUP_WEBHOOK_SECRET=
+DINGTALK_STORE_ACCOUNT_GROUP_WEBHOOK_TIMEOUT_MS=10000
+STORE_ACCOUNT_NOTIFICATION_RETRY_SECRET=
+
+# 产品开发待办定时任务（仅服务端/部署 cron 使用，须与其他任务密钥分开）
+PRODUCT_DEVELOPMENT_TODO_CRON_SECRET=
+
+# 对象存储
+# 必填，不能留空。当前生产桶使用 qiniu；只有明确切换适配器时才改为 s3/minio。
+STORAGE_PROVIDER=qiniu
+OBJECT_STORAGE_FILE_PATH=dev
+STORAGE_FILE_PATH=dev
+
+# 七牛云 Kodo
+QINIU_ACCESS_KEY=replace-with-qiniu-access-key
+QINIU_SECRET_KEY=replace-with-qiniu-secret-key
+QINIU_BUCKET=sucaiku-js
+QINIU_PUBLIC_DOMAIN=https://qny.jiansun.vip
+QINIU_FILE_PATH=dev
+QINIU_USE_HTTPS=true
+QINIU_PRIVATE_BUCKET=true
+QINIU_PRIVATE_URL_EXPIRES_SECONDS=7200
+
+# S3/MinIO 兼容适配器
+# STORAGE_PROVIDER=s3
+S3_ENDPOINT=http://127.0.0.1:9000
+S3_PUBLIC_ENDPOINT=http://127.0.0.1:9000
+S3_ACCESS_KEY=replace-with-s3-access-key
+S3_SECRET_KEY=replace-with-s3-secret-key
+S3_BUCKET=replace-with-s3-bucket
+S3_FILE_PATH=dev
+S3_REGION=us-east-1
+S3_ENABLE_PATH_STYLE=true
+
+# 外部 AI 生图
+EXTERNAL_IMAGE_GENERATE_TIMEOUT_MS=180000
+
+# BOM 核算竞品分析
+# 留空表示分析服务尚未接入；本地开发可显式填 fixture 验证完整工作台。
+# 生产环境禁止使用 fixture。
+BOM_COSTING_ANALYSIS_PROVIDER=
+# 真实竞品分析使用 market-detail-multimodal；Key 只放本地/生产环境变量。
+BOM_COSTING_MARKET_API_BASE_URL=https://qh.yydd.ai
+BOM_COSTING_MARKET_API_KEY=replace-with-market-open-api-key
+# 复用 AI 服务配置面板中已激活的多模态模型连接。
+BOM_COSTING_AI_SERVICE_TYPE=prompt-optimizer
+BOM_COSTING_MARKET_TIMEOUT_MS=60000
+# 最终结构与 BOM 汇总默认最多等待 110 秒；GPT-5 兼容网关会强制收紧到该上限，避免上游两分钟截断造成任务假死。
+BOM_COSTING_AI_TIMEOUT_MS=110000
+BOM_COSTING_AI_MAX_IMAGES=20
+# GPT-5 兼容网关的最终 BOM 汇总最多使用 12000 个输出额度，避免冗长回复拖垮整项任务。
+BOM_COSTING_AI_MAX_TOKENS=12000
+BOM_COSTING_AI_REASONING_EFFORT=low
+BOM_COSTING_MODELING_PROVIDER=
+
+# BOM 核算实时同款采购预估（1688 官方图搜）。
+# 网关固定为 https://skills-gateway.1688.com/api/find_product/1.0.0。
+# AK 只放服务器私密环境变量，服务端会按 x-csk-* 协议签名；实时同款价固定 × 90%
+# 是整件采购预估，历史 BOM 仅保留为结构参考。不要把 AK 写入 Git 或 NEXT_PUBLIC_* 变量。
+ALIBABA_1688_IMAGE_SEARCH_AK=replace-with-1688-image-search-ak
+# 仅在官方网关地址调整时设置；系统会拒绝非官方 HTTPS 地址。
+ALIBABA_1688_IMAGE_SEARCH_ENDPOINT_URL=https://skills-gateway.1688.com/api/find_product/1.0.0
+ALIBABA_1688_IMAGE_SEARCH_TIMEOUT_MS=45000
+ALIBABA_1688_IMAGE_SEARCH_MIN_SIMILARITY=0.78
+ALIBABA_1688_IMAGE_SEARCH_PAGE_SIZE=10
+ALIBABA_1688_IMAGE_SEARCH_PURCHASE_AMOUNT=1
+ALIBABA_1688_IMAGE_SEARCH_TAGS=4306497
+
+# 素材库白底图回传
+MATERIAL_LIBRARY_WHITE_BACKGROUND_API_ENABLED=false
+MATERIAL_LIBRARY_WHITE_BACKGROUND_API_BASE_URL=https://example.com
+MATERIAL_LIBRARY_WHITE_BACKGROUND_API_KEY=replace-with-material-library-api-key
+# 检测报告查询（不填则复用上面素材平台的 BaseUrl / API Key；都没有时「是否有检测报告」显示为空）
+MATERIAL_LIBRARY_CERTIFICATE_REPORT_API_BASE_URL=
+MATERIAL_LIBRARY_CERTIFICATE_REPORT_API_KEY=
+
+# 产品全量档案以图搜图（模型文件放在仓库外，不提交到 Git）
+IMAGE_SEARCH_MODEL_PATH=
+IMAGE_SEARCH_MODEL_SOURCE_BASE_URL=https://www.modelscope.cn/models/Xenova/dinov2-small/resolve/master
+IMAGE_SEARCH_MIN_SHAPE_COSINE=0.78
+IMAGE_SEARCH_MIN_SHAPE_MARGIN=0.08

furniture-3d-system/.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

furniture-3d-system/.gitignore

@@ -2,6 +2,7 @@
 
 # dependencies
 /node_modules
+/node_modules.pnpm-mixed
 /.pnp
 .pnp.*
 .yarn/*
@@ -15,7 +16,11 @@
 
 # next.js
 /.next/
+/.next-*/
+/.next-oa-preview*/
+/.next-oa-webpack/
 /out/
+/.data/
 
 # production
 /build
@@ -32,6 +37,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel
@@ -41,8 +47,14 @@ yarn-error.log*
 next-env.d.ts
 
 /src/generated/prisma
+.database-backups/
+.master-data-audits/
+.storage-migration-audits/
+.storage-gc-audits/
+.master-data-cleanup/
 
 # local workspace artifacts
+.codex-runtime/
 .codex-logs/
 _logs/
 output/
@@ -58,4 +70,12 @@ nul
 dev-server.log
 trace-deprecation-build.log
 typecheck-latest.log
+.local-test-*.log
+tsconfig.typecheck.generated.json
 local-packages/npm-cache/cache/_logs/
+
+# 脚本监控 Agent 本机凭据
+agents/script-monitor/config.json
+
+# 下载中心本地运行时产物
+.download-center/

furniture-3d-system/.planning/PROJECT.md

@@ -1,92 +0,0 @@
-# 家具 3D 新平台
-
-## What This Is
-
-这是一个面向家具开品与入库流程的 3D 平台，目标是把“资产中心、辅助装配（手动拼装）、草稿组、包装、正式入库、轻仓库”串成一条可持续维护的新平台主链。  
-项目同时保留旧的 `CAD -> 板件/孔位/五金/装配步骤` 兼容链，用来承接历史产品和旧编辑能力，但它不再作为新平台的业务主入口。
-
-## Core Value
-
-让新平台主链能够稳定地从资产与组合规则出发，生成可入库、可追踪、可协作的正式产品数据，而不是继续依赖旧 CAD 链条拼装业务真相。
-
-## Scope Baseline
-
-### Established Baseline
-
-- 资产中心、辅助装配（手动拼装）、草稿组、入库、轻仓库已经具备基础页面、接口和服务骨架。
-- 基础资料库（基材 / 花色）已并入主线，并支持基材多花色关联、自动编码和过渡期缩略图上传。
-- 旧 CAD 兼容链仍可维护板件、孔位、五金、装配步骤等历史能力。
-- 项目已经建立服务层、仓储层、Prisma 模型和 App Router 的基本架构。
-
-### Out of Scope
-
-- 把旧 `Product / SKU` 页面重新做成新平台首页。
-- 让包装流程绕过草稿组直接生成正式产品。
-- 在当前阶段里大改前端视觉实现。
-
-## Operating Context
-
-- 当前仓库的推荐主链是：`资产中心 -> 辅助装配（手动拼装） -> 草稿组 -> 包装方案 -> 正式入库 -> 轻仓库`
-- 包装和包装方案由同事 `xuxiake` 负责，长期分支固定为 `codex/xuxiake-packaging`
-- 主线由 `WuYongJie` 收口，`main` 只作为主线收口分支
-- 当前已存在两套测试环境：
-  - 同事包装测试环境：`192.168.42.134:3100`
-  - `WuYongJie` 主线独立测试环境：`192.168.42.134:3200`
-- 现有架构是 Next.js App Router 单体仓库，后端采用 `Route -> Service -> Repository -> Prisma`
-- 当前已经完成对 `draft-group.service.ts`、`assembly.service.ts`、`planning.service.ts`、`panel.service.ts` 的主线式拆分收口，并已把包装支线中的资料库与基材规则并回主线
-- 前端 UI 不由当前工作流直接实现，如需前端配合，只记录到 `D:\AI Code\3danzhuang\docs\前端UI改动清单.md`
-
-## Constraints
-
-- **协作**: `main` 仅由 `WuYongJie` 收口，其他协作者走各自职责分支。
-- **模块边界**: 包装负责人默认不直接改草稿组/入库共享接缝。
-- **技术栈**: 现有项目基于 Next.js 16、React 19、Prisma 7、PostgreSQL、S3/Redis 可选缓存。
-- **交付方式**: 默认不主动 commit / push。
-- **前端职责**: UI 改动交给独立前端 agent，当前主线工作流聚焦后端与项目结构。
-
-## Requirements
-
-- 当前业务真相以 `资产中心 -> 辅助装配（手动拼装） -> 草稿组 -> 包装 -> 正式入库 -> 轻仓库` 为准。
-- `自动组合` 属于历史阶段主线产物，不再作为当前用户主操作入口；旧文档里的相关描述按历史背景理解。
-- 基础资料库当前已纳入主线：`substrate（基材）` 支持多 `finish（花色）` 关联、`surfaceOptionId（贴面类型）` 可空、自动 `BC-XXXX（基材编码）` 与 `HS-XXXX（花色编码）`。
-- `weightKg（整板重量）` 当前指整板重量，不等于切割后单块板件重量；实际板件重量后续继续按切割规则或材质系统换算。
-- `5 字段唯一约束` 的最终业务规则仍是外部专题，当前主线已先完成包装支线并线与资料库落地，但该规则后续仍需同事单独拍板。
-
-## Project Memory Model
-
-- `STATE.md`：唯一快速恢复入口，只放当前阶段、下一步、风险和恢复路径。
-- `ROADMAP.md`：放阶段目标、依赖、成功标准和计划清单。
-- `REQUIREMENTS.md`：放需求本体、阶段映射和计划覆盖关系。
-- `PROJECT.md`：只保留长期项目定义、长期约束和关键决策，不复制运行态状态。
-
-## Key Decisions
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| 新平台主链和旧 CAD 兼容链明确分开维护 | 避免旧数据模型反向主导新平台业务 | Good |
-| 包装协作固定使用 `codex/xuxiake-packaging` 及其任务分支 | 降低团队协作中的分支歧义和并线混乱 | Good |
-| 主线优先做服务层职责拆分，而不是继续叠加补丁 | 当前主要风险是结构失控，不是单点功能缺失 | Good |
-| GSD 作为项目外置记忆和阶段工作流补充层接入 | 便于跨会话、跨 AI 延续项目上下文 | Good |
-| 真实业务测试必须使用与同事分离的独立测试环境 | 避免包装测试数据和主线真实业务测试互相污染 | Good |
-| 当前主链入口已从早期 `自动组合` 迁移为 `辅助装配（手动拼装）` | 避免 GSD 项目记忆继续把旧入口当成现行真相 | Good |
-| 包装支线资料库规则允许先以过渡能力落主线 | 先收业务真相与资料库主链，再把完整材质系统作为后续专题推进 | Good |
-
-## Evolution
-
-This document evolves at phase transitions and milestone boundaries.
-
-**After each phase transition**:
-1. Requirements invalidated? -> Move to Out of Scope with reason
-2. Requirements validated? -> Move to Validated with phase reference
-3. New requirements emerged? -> Add to roadmap or requirements, not to running state
-4. Decisions to log? -> Add to Key Decisions
-5. "What This Is" still accurate? -> Update if drifted
-
-**After each milestone**:
-1. Full review of all sections
-2. Core Value check -> still the right priority?
-3. Audit Out of Scope -> reasons still valid?
-4. Confirm Project Memory Model still has a single quick recovery入口
-
----
-*Last updated: 2026-04-11 after packaging branch material-library merge and GSD memory sync*

furniture-3d-system/.planning/REQUIREMENTS.md

@@ -1,87 +0,0 @@
-# Requirements: 家具 3D 新平台
-
-**Defined:** 2026-04-02
-**Core Value:** 让新平台主链能够稳定地从资产与组合规则出发，生成可入库、可追踪、可协作的正式产品数据
-
-## v1 Requirements
-
-> 当前业务入口已演进为 `辅助装配（手动拼装）` 主链。下面保留阶段编号不变，但凡旧文档里出现 `自动组合`，默认按“历史阶段方案”理解，不再视为当前唯一入口。
-
-### Mainline Platform
-
-- [ ] **MAIN-01**: 平台负责人可以在资产中心维护资产族与资产规格，并供新平台后续流程直接使用
-- [ ] **MAIN-02**: 平台负责人可以基于资产中心与系列模板完成辅助装配（手动拼装），并进入草稿组流程，而不是直接落到正式产品
-- [ ] **MAIN-03**: 系统可以在草稿组中保存每个预 SKU 的装配结果、显示摘要和后续接缝状态
-- [ ] **MAIN-04**: 预 SKU 可以保存包装方案结果，并把包装结果稳定传递给正式入库流程
-- [ ] **MAIN-05**: 正式入库流程可以把草稿组/预 SKU 结果转为正式 `Product / SKU`
-- [ ] **MAIN-06**: 轻仓库可以查看正式产品与 SKU 的基础结果，形成入库后的轻量管理闭环
-
-### Collaboration Workflow
-
-- [ ] **COLL-01**: 主线负责人和包装负责人拥有固定、明确、不歧义的分支命名规则
-- [ ] **COLL-02**: 协作入口文档足够清晰，新的 AI 会话进入项目后能先读到正确规则
-- [ ] **COLL-03**: 包装线默认不直接修改主线共享接缝文件，必须通过约定流程对齐后再改
-- [ ] **COLL-04**: 主线收口人可以在同事提交分支后完成检查、收口并决定 merge / cherry-pick / 手工整合
-
-### Mainline Maintainability
-
-- [ ] **ARCH-01**: 新平台主链的核心服务需要逐步拆分为更清晰的编排层、校验层、映射层和规则层
-- [ ] **ARCH-02**: 旧 CAD 兼容链需要继续保留，但不能继续侵入新平台主链的数据真相
-- [ ] **ARCH-03**: 新增主线后端能力时，需要延续统一的 `Route -> Service -> Repository -> Prisma` 结构
-- [ ] **ARCH-04**: GSD 需要能基于 `.planning` 文件在跨对话场景下恢复项目上下文
-
-## Phase 1 Coverage
-
-| Requirement | Phase | Plan Coverage | Notes |
-|-------------|-------|---------------|-------|
-| COLL-01 | Phase 1 | 01-01-PLAN.md | 固化分支命名、主线收口和同步口径 |
-| COLL-02 | Phase 1 | 01-01-PLAN.md, 01-02-PLAN.md | 一半来自协作文档入口，一半来自 `.planning` 恢复链 |
-| ARCH-04 | Phase 1 | 01-02-PLAN.md | `STATE -> ROADMAP / REQUIREMENTS / PROJECT` 恢复链已在 `.planning` 内闭环 |
-
-## v2 Requirements
-
-### Packaging Expansion
-
-- **PACK-01**: 包装方案结果支持更完整的成本、体积、材料、工艺扩展
-- **PACK-02**: 新平台包装结果和正式产品包装链进一步对齐，减少重复维护
-
-### Governance
-
-- **GOV-01**: 为主要阶段建立更细的 UAT 和交付检查闭环
-- **GOV-02**: 引入更完整的阶段化 roadmap 与 milestone 管理
-
-## Out of Scope
-
-| Feature | Reason |
-|---------|--------|
-| 大规模重做前端视觉设计 | 当前前端 UI 由独立 agent 负责，不是当前主工作流范围 |
-| 把旧 CAD 装配链改造成新平台主链 | 会继续混淆新旧业务边界 |
-| 绕过草稿组直接做包装或入库 | 会破坏新平台主线的数据收口 |
-
-## Traceability
-
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| MAIN-01 | Phase 2 | Completed by 02-01 |
-| MAIN-02 | Phase 2 | Completed by 02-01, 02-02; current mainline has since evolved from historical auto-combination wording to assisted assembly/manual assembly |
-| MAIN-03 | Phase 2 | Completed by 02-02 |
-| MAIN-04 | Phase 3 | Completed by 03-01 |
-| MAIN-05 | Phase 4 | Completed by 04-01 |
-| MAIN-06 | Phase 4 | Completed by 04-02 |
-| COLL-01 | Phase 1 | Completed by 01-01 |
-| COLL-02 | Phase 1 | Completed by 01-01, 01-02 |
-| COLL-03 | Phase 3 | Completed by 03-02 |
-| COLL-04 | Phase 4 | Completed by 04-03 |
-| ARCH-01 | Phase 5 | Pending |
-| ARCH-02 | Phase 5 | Pending |
-| ARCH-03 | Phase 5 | Pending |
-| ARCH-04 | Phase 1 | Completed by 01-02 |
-
-**Coverage:**
-- v1 requirements: 14 total
-- Mapped to phases: 14
-- Unmapped: 0
-
----
-*Requirements defined: 2026-04-02*
-*Last updated: 2026-04-11 after mainline shift to assisted assembly/manual assembly*

furniture-3d-system/.planning/ROADMAP.md

@@ -1,115 +0,0 @@
-# Roadmap: 家具 3D 新平台
-
-## Overview
-
-这是一个 brownfield 路线图，不把已存在的资产中心、辅助装配（手动拼装）、草稿组、入库、轻仓库和旧 CAD 兼容链重新当成“从零建设”。本轮路线图只围绕三件事推进：把新平台主链继续收口成稳定闭环，把主线负责人和包装负责人之间的协作规则固定下来，并用 GSD 的 `.planning` 记忆把阶段、风险和后续执行路径沉淀成可恢复的项目上下文。
-
-## Phases
-
-**Phase Numbering:**
-- Integer phases (1, 2, 3): Planned milestone work
-- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
-
-Decimal phases appear between their surrounding integers in numeric order.
-
-- [x] **Phase 1: 协作入口与项目记忆稳定化** - 先把分支规则、协作文档入口和 GSD 项目记忆固定下来。
-- [x] **Phase 2: 资产到草稿组主链收口** - 让资产中心、装配入口、草稿组继续按新平台主链稳定衔接。
-- [x] **Phase 3: 包装接缝稳定化** - 让预 SKU 的包装结果可保存、可交接，同时守住共享接缝边界。
-- [x] **Phase 4: 正式入库与轻仓库闭环** - 把草稿组结果稳定转成正式产品，并形成入库后的轻量管理闭环。
-- [x] **Phase 5: 主链可维护性收口** - 把核心服务拆分和新旧链边界继续收紧，避免主线重新膨胀。
-
-## Phase Details
-
-### Phase 1: 协作入口与项目记忆稳定化
-**Goal**: 新会话和协作者进入项目时，能按同一套规则接入主链，不再靠口头传递恢复上下文
-**Depends on**: Nothing (first phase)
-**Requirements**: COLL-01, COLL-02, ARCH-04
-**Success Criteria** (what must be TRUE):
-  1. 协作者可以按固定、明确的分支命名规则开始工作，不再出现职责不清的泛分支名。
-  2. 新的 AI 会话进入仓库后，只读 `.planning` 和记忆入口文档，就能知道主链、包装线和禁止直改区。
-  3. 主线当前阶段、下一步和已知风险可以从 `.planning/STATE.md` 直接恢复，不依赖上一轮聊天记录。
-**Status**: Complete
-**Plans**: 2 plans
-Plans:
-- [x] 01-01-PLAN.md — 固化仓库级协作入口、分支命名和同步口径
-- [x] 01-02-PLAN.md — 固化 `.planning` 项目记忆恢复层与需求追踪闭环
-**Execution note**: `01-01` 与 `01-02` 已全部完成；Phase 1 的协作入口、分支规则和 `.planning` 恢复链已经收口完成，下一步转入 Phase 2。
-
-### Phase 2: 资产到草稿组主链收口
-**Goal**: 平台负责人可以从资产与组合规则稳定走到草稿组结果，且这段主链继续沿用统一后端分层
-**Depends on**: Phase 1
-**Requirements**: MAIN-01, MAIN-02, MAIN-03
-**Success Criteria** (what must be TRUE):
-  1. 平台负责人可以在资产中心维护资产族与资产规格，并直接供新平台后续流程使用。
-  2. 平台负责人可以基于资产、模板和装配规则稳定进入草稿组，而不是直接落到正式产品。
-  3. 草稿组可以保存每个预 SKU 的候选结果、显示摘要，并看见后续接缝状态。
-**Status**: Complete
-**Plans**: 2 plans
-Plans:
-- [x] 02-01-PLAN.md — 把历史自动组合候选收口成可确认、可预览的阶段基线
-- [x] 02-02-PLAN.md — 把候选到草稿组的保存口径与前端交接要求统一收口
-**UI hint**: yes
-**Execution note**: `02-01`、`02-02` 已完成历史阶段基线收口；当前主线后来已从早期 `自动组合` 演进为 `辅助装配（手动拼装）` 入口，因此 Phase 2 相关文件按历史阶段理解，不再直接代表今天的页面入口。
-
-### Phase 3: 包装接缝稳定化
-**Goal**: 预 SKU 的包装结果可以稳定保存并交给后续流程，同时包装线和主线的共享接缝保持可控
-**Depends on**: Phase 2
-**Requirements**: MAIN-04, COLL-03
-**Success Criteria** (what must be TRUE):
-  1. 预 SKU 可以保存包装方案结果，并在后续流程中被稳定读取。
-  2. 草稿组到包装的共享接缝有清晰边界，包装线默认不会直接修改主线共享文件。
-  3. 当包装任务确实必须碰共享接缝时，主线负责人可以根据约定流程先对齐原因和影响范围再放行。
-**Status**: Complete
-**Plans**: 2 plans
-Plans:
-- [x] 03-01-PLAN.md — 锁定包装结果保存、试算与正式入库承接只认一套新结构
-- [x] 03-02-PLAN.md — 固定共享接缝协作规则、包装占位入口口径与前端联调边界
-**UI hint**: yes
-**Execution note**: `03-01` 已用测试守住包装结果保存、试算与正式入库承接；`03-02` 已固定共享接缝、占位入口和联调边界。下一步进入 Phase 4 的正式入库与轻仓库闭环。
-
-### Phase 4: 正式入库与轻仓库闭环
-**Goal**: 主线负责人可以把草稿组结果转成正式产品，并在入库后用轻仓库完成基础验收和收口
-**Depends on**: Phase 3
-**Requirements**: MAIN-05, MAIN-06, COLL-04
-**Success Criteria** (what must be TRUE):
-  1. 正式入库流程可以把草稿组或预 SKU 结果转成正式 `Product / SKU`。
-  2. 轻仓库可以查看正式产品与 SKU 的基础结果，形成入库后的轻量管理闭环。
-  3. 主线收口人收到协作者分支后，可以按约定完成检查，并决定 `merge`、`cherry-pick` 或手工整合。
-**Plans**: 3 plans
-Plans:
-- [x] 04-01-PLAN.md — 把草稿组/准 SKU 到正式 Product/SKU 的入库主链收口成稳定能力
-- [x] 04-02-PLAN.md — 把轻仓库收口成正式入库后的基础验收与查看闭环
-- [x] 04-03-PLAN.md — 固定主线收口检查单、merge/cherry-pick/手工整合决策与交接模板
-**UI hint**: yes
-**Execution note**: `04-01` 已补正式入库关键失败场景与 schema 契约；`04-02` 已补轻仓库 overview 与包装成品关联 SKU 编码；`04-03` 已固定主线收口检查单、决策规则与交接模板。Phase 4 已完成，下一步可进入 Phase 5。
-
-### Phase 5: 主链可维护性收口
-**Goal**: 新平台主链在继续演进时不再靠堆补丁前进，旧 CAD 兼容链也不会重新侵入新平台业务真相
-**Depends on**: Phase 4
-**Requirements**: ARCH-01, ARCH-02, ARCH-03
-**Success Criteria** (what must be TRUE):
-  1. 新平台主链的核心服务按编排、校验、映射、规则等职责继续拆分，新需求不会再堆进单个膨胀服务。
-  2. 旧 CAD 兼容链继续可用，但不会反向成为新平台资产、草稿组和入库链路的数据真相。
-  3. 新增主线后端能力时，代码位置和职责保持可预测，继续遵守 `Route -> Service -> Repository -> Prisma` 结构。
-**Plans**: 3 plans
-Plans:
-- [x] 05-01-PLAN.md — 继续压缩已拆但未拆透的热点 service，建立更稳定的职责边界
-- [ ] 05-02-PLAN.md — 继续收紧新旧链边界与主链分层，压住结构残留风险
-- [x] 05-03-PLAN.md — 收包装支线资料库并线，并把 GSD 项目记忆校正到当前真实主线
-**Execution note**: `05-01`、`05-02`、`05-03` 已全部完成；当前主线的服务分层、资料库迁移、GSD 项目记忆已经回到同一套真实口径。`5 字段唯一约束` 仍是外部专题，后续待包装同事单独定稿后再按新阶段或插入计划处理。
-
-## Progress
-
-**Execution Order:**
-Phases execute in numeric order: 1 -> 2 -> 2.1 -> 3 -> 3.1 -> 4 -> 5
-
-| Phase | Plans Complete | Status | Completed |
-|-------|----------------|--------|-----------|
-| 1. 协作入口与项目记忆稳定化 | 2/2 | Complete | 01-01, 01-02 |
-| 2. 资产到草稿组主链收口 | 2/2 | Complete | 02-01, 02-02 |
-| 3. 包装接缝稳定化 | 2/2 | Complete | 03-01, 03-02 |
-| 4. 正式入库与轻仓库闭环 | 3/3 | Complete | 04-01, 04-02, 04-03 |
-| 5. 主链可维护性收口 | 3/3 | Complete | 05-01, 05-02, 05-03 |
-
----
-*Last updated: 2026-04-11 after 05-02 structure closure and full Phase 5 completion*

furniture-3d-system/.planning/STATE.md

@@ -1,49 +0,0 @@
-# Project State
-
-## Quick Recovery
-
-**Current focus:** Roadmap complete - 等待新任务或外部专题（5 字段唯一约束）回流
-**Current phase:** Phase 5 of 5
-**Latest completed plan:** 05-02-PLAN.md - intake 分层残留、新旧链边界文档与主仓库 Prisma 模型已重新对齐，Phase 5 已完成
-**Phase status:** Phase 5 complete - `05-01`、`05-02`、`05-03` 全部完成
-**Last activity:** 2026-04-11 - 已补齐主仓库 `schema.prisma（数据库模型）` 与缺失迁移，重新跑通类型检查和关键测试，并把 GSD 记忆收口到当前真实主线
-
-## Next Step
-
-1. 如果包装同事回传 `5 字段唯一约束` 最终方案，先新开插入计划或新阶段，不要直接口头改主线。
-2. 若继续联调资料库，优先核对：多花色关联、自动编码、临时新建分类/花色、整板重量口径。
-3. 新会话先读本文件，再按需下钻 `ROADMAP.md`、`REQUIREMENTS.md`、`PROJECT.md`、`phases/05-主链可维护性收口/05-CONTEXT.md`、`phases/05-主链可维护性收口/05-02-SUMMARY.md`、`phases/05-主链可维护性收口/05-03-SUMMARY.md`。
-
-## Risks
-
-- 正式入库与轻仓库现在会直接承接 `PreSku` 与包装结果，Phase 4 要避免把这条链重新拉回旧兼容模型。
-- `COLL-04` 已落成第一轮规则，但包装支线后续如果继续回传资料库专题，仍要继续按协作边界执行。
-- `assembly / panel / planning / intake / warehouse` 等主链服务如果后续再次自然膨胀，会直接破坏 Phase 5 已收好的结构。
-- 当前 `.planning` 已开始回到真实主线，但早期 Phase 2 历史文档仍保留 `自动组合` 话术；阅读时必须按“历史阶段记录”理解，不能再把它当当前入口。
-- 基础资料库里的 `5 字段唯一约束` 最终规则仍未拍板；当前主线只是先完成并线与可运行落地，不等于最终业务真相已定稿。
-- `192.168.42.134:3200` 虽然已独立隔离，但数据库初始数据来自同事测试库快照，不是完全空白环境。
-
-## Recovery Path
-
-- `STATE.md`：先看当前阶段、下一步、风险。
-- `ROADMAP.md`：确认 Phase 5 的目标和成功标准。
-- `REQUIREMENTS.md`：确认主线当前聚焦 `ARCH-01`、`ARCH-02`、`ARCH-03`。
-- `PROJECT.md`：查看长期项目定义、约束和关键决策。
-- `phases/05-主链可维护性收口/05-CONTEXT.md`：恢复 Phase 5 已锁定的结构目标、边界与关键热点。
-- `phases/05-主链可维护性收口/05-02-SUMMARY.md`：恢复主仓库 schema / intake 分层 / 文档边界收口的最新结果。
-- `phases/05-主链可维护性收口/05-03-SUMMARY.md`：恢复包装支线资料库并线、测试环境部署和 GSD 项目记忆校正的最新结果。
-- `docs/会话交接-20260411-包装支线并线与资料库收口.md`：查看这轮包装支线并线到底收了什么、留了什么。
-- `phases/04-正式入库与轻仓库闭环/04-01-SUMMARY.md`：快速恢复正式入库已收口到什么程度。
-- `phases/04-正式入库与轻仓库闭环/04-02-SUMMARY.md`：快速恢复轻仓库已收口到什么程度。
-- `phases/04-正式入库与轻仓库闭环/04-03-SUMMARY.md`：快速恢复协作收口规则已固定到什么程度。
-
-## Collaboration Guardrails
-
-- `main` 只由 `WuYongJie` 收口。
-- `codex/xuxiake-packaging` 是包装长期分支；临时任务分支固定为 `codex/xuxiake-packaging-<任务简称>`。
-- 长期协作分支同步 `main` 用 `merge main`；临时个人任务分支同步 `main` 才用 `rebase main`。
-- 同事测试环境：`192.168.42.134:3100`
-- `WuYongJie` 独立测试环境：`192.168.42.134:3200`
-
----
-*Last updated: 2026-04-11 after 05-02 closure and Phase 5 completion*

furniture-3d-system/.planning/codebase/ARCHITECTURE.md

@@ -1,137 +0,0 @@
-# Architecture
-
-**Analysis Date:** 2026-04-02
-
-## Pattern Overview
-
-**Overall:** Next.js App Router monolith with domain-oriented server modules.
-
-**Key Characteristics:**
-- Use `src/app` for both SSR pages and API routes; page loaders often call services directly, while browser clients call `/api/*`.
-- Keep backend layers split as `Route -> Service -> Repository -> Prisma`, with shared error/response wrappers in `src/server/core`.
-- Separate new platform mainline rules from legacy CAD compatibility rules through dedicated domain libraries in `src/lib/open-product` and `src/lib/planning`.
-
-## Layers
-
-**Application Entry Layer:**
-- Purpose: render pages, guard navigation, and host API routes.
-- Location: `src/app`, `src/app/api`, `src/app/layout.tsx`, `src/proxy.ts`
-- Contains: App Router pages such as `src/app/page.tsx`, platform pages like `src/app/asset-center/page.tsx`, legacy pages like `src/app/products/[id]/assembly/page.tsx`, and route handlers like `src/app/api/draft-groups/route.ts`.
-- Depends on: `src/lib/server-session.ts`, `src/server/services`, `src/server/core/response.ts`, Zod schemas in `src/app/api/platform/schemas.ts`.
-- Used by: browser requests and Next.js runtime.
-
-**UI Composition Layer:**
-- Purpose: hold reusable page shells and feature clients.
-- Location: `src/components`, especially `src/components/platform`, `src/components/assembly`, `src/components/3d`, plus feature clients under `src/app/*/*Client.tsx`.
-- Contains: shared frame components like `src/components/platform/PlatformPageFrame.tsx`, navigation in `src/components/platform/PlatformFlowNav.tsx`, 3D/editor clients in `src/app/products/[id]/assembly/AssemblyEditorWorkspace.tsx`.
-- Depends on: typed helpers from `src/lib/*`, API helper wrappers such as `src/lib/open-product/platform-api.ts`, and server-returned DTOs.
-- Used by: page files in `src/app`.
-
-**Domain Service Layer:**
-- Purpose: enforce permissions, workflow rules, state transitions, DTO mapping, and orchestration across repositories.
-- Location: `src/server/services`
-- Contains: domain services for mainline (`src/server/services/asset-center.service.ts`, `src/server/services/combination.service.ts`, `src/server/services/draft-group.service.ts`, `src/server/services/intake.service.ts`, `src/server/services/warehouse.service.ts`), planning (`src/server/services/planning.service.ts`), and legacy compatibility (`src/server/services/product.service.ts`, `src/server/services/assembly.service.ts`, `src/server/services/panel.service.ts`, `src/server/services/hole.service.ts`).
-- Depends on: repositories from `src/server/repositories`, core errors in `src/server/core/errors.ts`, cache in `src/server/cache`, and pure rules from `src/lib/open-product` / `src/lib/planning`.
-- Used by: App Router pages and route handlers.
-
-**Persistence Layer:**
-- Purpose: isolate Prisma queries, relation loading, batching, and transactions.
-- Location: `src/server/repositories`
-- Contains: generic base in `src/server/repositories/base.repository.ts`, domain repositories like `src/server/repositories/asset-center.repository.ts`, `src/server/repositories/draft-group.repository.ts`, `src/server/repositories/product.repository.ts`, `src/server/repositories/assembly.repository.ts`.
-- Depends on: Prisma singleton in `src/lib/prisma.ts` and Prisma schema in `prisma/schema.prisma`.
-- Used by: service classes only; route handlers do not query Prisma directly in the mainline path.
-
-**Rule / Contract Layer:**
-- Purpose: keep deterministic business rules and parsing separate from transport and persistence.
-- Location: `src/lib/open-product`, `src/lib/planning`, plus selected legacy helpers like `src/lib/assembly-generator.ts`
-- Contains: open-platform asset validation and review rules in `src/lib/open-product/asset-validation.ts` and `src/lib/open-product/asset-review.ts`, candidate generation in `src/lib/open-product/single-board-desk.ts`, planning parsers/generator in `src/lib/planning/parsers.ts` and `src/lib/planning/candidate-generator.ts`.
-- Depends on: TypeScript types and lightweight utility code only.
-- Used by: services, selected clients, and tests.
-
-## Data Flow
-
-**New Platform Mainline Flow:**
-
-1. Server pages such as `src/app/asset-center/page.tsx`, `src/app/auto-combinations/page.tsx`, `src/app/draft-groups/page.tsx`, and `src/app/intake/page.tsx` load authenticated data through `src/lib/server-session.ts` and call services from `src/server/services`.
-2. Browser actions submit to API routes like `src/app/api/asset-center/families/route.ts`, `src/app/api/auto-combinations/generate/route.ts`, `src/app/api/draft-groups/route.ts`, `src/app/api/pre-skus/[id]/packaging/route.ts`, and `src/app/api/intake/formalize/route.ts`.
-3. Route handlers validate input with schemas in `src/app/api/platform/schemas.ts`, then services orchestrate repositories and pure rule modules, finally persisting workflow state in Prisma models such as `AssetFamily`, `AssetVariant`, `DraftGroup`, `PreSku`, `PreSkuPackagingPlan`, `Product`, and `ProductSKU` in `prisma/schema.prisma`.
-
-**Legacy CAD Compatibility Flow:**
-
-1. Legacy pages under `src/app/products/*` and `src/app/products/[id]/assembly/*` fetch product-centric data from Prisma or services, for example `src/app/products/[id]/assembly/page.tsx`.
-2. Editors and detail clients call APIs such as `src/app/api/products/[id]/assembly/route.ts`, `src/app/api/products/[id]/assembly/generate/route.ts`, `src/app/api/products/[id]/panels/route.ts`, `src/app/api/products/[id]/holes/route.ts`, and `src/app/api/products/[id]/import-hardware/route.ts`.
-3. Legacy services use repositories plus rule helpers like `src/lib/assembly-generator.ts`, `src/lib/panel-assembly-semantic.ts`, `src/lib/sku-cad-data.ts`, and `src/lib/3d/engine.ts` to maintain `Product`, `ProductSKU`, `Panel`, `Hole`, `ProductHardware`, and `AssemblyStep` data.
-
-**Planning Workspace Flow:**
-
-1. Planning APIs in `src/app/api/planning/templates/*` and `src/app/api/planning/workspaces/*` accept template and workspace definitions.
-2. `src/server/services/planning.service.ts` validates structure with `src/lib/planning/parsers.ts`, scopes visibility through `src/server/services/planning-scope.service.ts`, and generates candidates through `src/server/services/planning-generation.service.ts`.
-3. Generated candidates and saved drafts are stored in `PlanningTemplate`, `PlanningWorkspace`, and `PlanningDraft` models in `prisma/schema.prisma`.
-
-**State Management:**
-- Use server-first data loading for page entry (`src/app/page.tsx`, `src/app/asset-center/page.tsx`, `src/app/intake/page.tsx`).
-- Use local React state inside feature clients and shared Zustand stores in `src/stores` for UI/session state such as `src/stores/ui.store.ts`, `src/stores/auth.store.ts`, and `src/stores/product.store.ts`.
-- Use cache abstractions in `src/server/cache/cache.service.ts` for selective backend caching, especially product list and assembly results.
-
-## Key Abstractions
-
-**Mainline Domain Entities:**
-- Purpose: represent the new platform business truth before formal product creation.
-- Examples: `prisma/schema.prisma`, `src/lib/open-product/types.ts`, `src/server/services/draft-group.service.ts`, `src/server/services/intake.service.ts`
-- Pattern: asset family and variant data stay independent from formal `Product / ProductSKU` until intake.
-
-**Service Facade Index:**
-- Purpose: provide stable import entrypoints for pages and routes.
-- Examples: `src/server/services/index.ts`, `src/server/repositories/index.ts`
-- Pattern: explicit named exports instead of wildcard barrels to reduce conflicts while still centralizing access.
-
-**Scoped Assembly Model:**
-- Purpose: let legacy assembly logic work at product scope and optional SKU scope.
-- Examples: `src/server/services/assembly.service.ts`, `src/server/services/assembly-scope.service.ts`, `src/server/repositories/assembly.repository.ts`, `prisma/schema.prisma`
-- Pattern: normalize optional `skuId`, then branch cache keys, queries, and versioning rules by scope.
-
-**Platform Rule Libraries:**
-- Purpose: keep combinatorics and validation deterministic and testable.
-- Examples: `src/lib/open-product/single-board-desk.ts`, `src/lib/open-product/asset-validation.ts`, `src/lib/planning/candidate-generator.ts`
-- Pattern: pure function modules return candidates, warnings, and contracts; services own repository lookups and permission checks.
-
-## Entry Points
-
-**Root Application Shell:**
-- Location: `src/app/layout.tsx`
-- Triggers: every App Router request
-- Responsibilities: register global CSS, initialize theme script, wrap the app with `PreferencesProvider`, and set shared metadata.
-
-**Authentication Gate:**
-- Location: `src/proxy.ts` and `src/lib/server-session.ts`
-- Triggers: page navigation and server-side page loaders
-- Responsibilities: redirect unauthenticated users, validate auth cookie, and provide normalized `AuthUser` context.
-
-**Platform Home:**
-- Location: `src/app/page.tsx`
-- Triggers: visit `/`
-- Responsibilities: combine legacy product list from `productService` with current draft groups from `draftGroupService`, then hand off to `src/app/HomeClient.tsx`.
-
-**API Surface:**
-- Location: `src/app/api/**/route.ts`
-- Triggers: client-side fetch and external HTTP requests
-- Responsibilities: parse request data, call `handleRequest` from `src/server/core/response.ts`, enforce auth, and translate `AppError` results to JSON envelopes.
-
-## Error Handling
-
-**Strategy:** centralized application errors with JSON response helpers and service-thrown `AppError`.
-
-**Patterns:**
-- Service and route code throw or catch `AppError` from `src/server/core/errors.ts`; routes convert them through `jsonError` / `jsonErrorFromAppError` in `src/server/core/response.ts`.
-- `handleRequest` in `src/server/core/response.ts` assigns `requestId`, resolves auth, checks roles, and standardizes unknown errors into `SYSTEM_INTERNAL`.
-- Server pages still use Next.js control flow (`redirect`, `notFound`) directly in files such as `src/app/products/[id]/assembly/page.tsx` and `src/lib/server-session.ts`.
-
-## Cross-Cutting Concerns
-
-**Logging:** request-level and operational logging is centralized under `src/server/services/log.service.ts`, `src/server/repositories/log.repository.ts`, `src/server/middleware/request-logger.ts`, and `src/lib/logger.ts`.
-**Validation:** API inputs use Zod schemas in `src/app/api/platform/schemas.ts` and route-local schemas; deeper domain checks live in service or rule modules such as `src/lib/open-product/asset-validation.ts`.
-**Authentication:** page access uses `src/proxy.ts` and `src/lib/server-session.ts`; API auth is resolved inside `src/server/core/response.ts` through `src/lib/auth-middleware.ts`.
-
----
-
-*Architecture analysis: 2026-04-02*

furniture-3d-system/.planning/codebase/CONCERNS.md

@@ -1,123 +0,0 @@
-# Codebase Concerns
-
-**Analysis Date:** 2026-04-02
-
-## Tech Debt
-
-**Route / Page 越层直接访问 Prisma，业务规则分散在入口层:**
-- Issue: 多个页面和 API Route 直接 `import { prisma } from '@/lib/prisma'` 并自行查询产品、SKU、板件、孔位或活动日志，绕过 `Service` / `Repository` 统一边界。
-- Files: `src/app/api/products/[id]/packaging/route.ts`, `src/app/api/trash/products/[id]/route.ts`, `src/app/api/trash/skus/[id]/route.ts`, `src/app/products/[id]/page.tsx`, `src/app/products/[id]/assembly/page.tsx`, `src/app/products/[id]/skus/[skuId]/page.tsx`, `src/app/products/[id]/skus/[skuId]/assembly/page.tsx`
-- Impact: 权限校验、软删除判断、日志写入和字段裁剪会在多个入口重复实现；后续改产品权限或主链字段时，容易出现“有的入口修了，有的入口没修”的回归。
-- Fix approach: 把产品读取、包装权限前置校验、回收站操作日志写入统一收回到 `src/server/services/*.ts` 与 `src/server/repositories/*.ts`；Route 只保留收参、鉴权、响应格式。
-
-**包装旧链仍是“双真相”实现，服务层自身也夹带数据库访问:**
-- Issue: `src/server/services/packaging.service.ts` 既直接查 `prisma.product.findUnique`，又调用 `src/server/repositories/packaging.repository.ts`；同时新主链包装能力已经落在 `src/server/services/pre-sku-packaging.service.ts` 与 `src/server/services/draft-group.service.ts`，形成两套包装规则入口。
-- Files: `src/server/services/packaging.service.ts`, `src/server/repositories/packaging.repository.ts`, `src/server/services/pre-sku-packaging.service.ts`, `src/server/services/draft-group.service.ts`, `src/app/api/products/[id]/packaging/route.ts`, `src/app/api/pre-skus/[id]/packaging/route.ts`
-- Impact: 后续一旦包装结构、默认箱规、成本汇总口径变化，旧产品链和新主链很容易继续分叉，正式产品包装与 `PreSku` 包装结果可能长期不一致。
-- Fix approach: 明确“正式产品包装”与“PreSku 包装”的唯一真相和映射时机；把旧链权限/存在性校验下沉到仓储或服务内部，避免服务层继续混用 Prisma 与 Repository。
-
-**演示种子与初始化逻辑和正式业务混在主服务目录:**
-- Issue: `src/server/services/open-platform-demo-seed.service.ts` 在一个超大服务里同时做账号创建、资产族审批、组合生成、包装写入、正式入库和清理旧演示数据；`src/server/services/system-init.service.ts` 同时负责连接重试、默认管理员创建、降级模式和数据完整性检查。
-- Files: `src/server/services/open-platform-demo-seed.service.ts`, `src/server/services/system-init.service.ts`, `src/lib/init.ts`
-- Impact: 这些脚本既能改真实数据，又承载启动行为，维护者很难判断“这是开发辅助逻辑”还是“生产运行逻辑”；一处改动可能同时影响启动、种子数据和正式链路。
-- Fix approach: 把启动初始化、开发种子、演示数据清理拆成独立模块或脚本入口；保留服务层只负责可复用业务动作，避免“一个文件串完整主链流程”。
-
-## Known Bugs
-
-**包装接口测试只覆盖 GET，写操作回归容易漏掉:**
-- Symptoms: `src/app/api/products/[id]/packaging/route.test.ts` 只有一个 GET 用例，POST / PUT / DELETE 的权限、默认方案切换、错误分支和参数校验没有自动兜底。
-- Files: `src/app/api/products/[id]/packaging/route.ts`, `src/app/api/products/[id]/packaging/route.test.ts`, `src/server/services/packaging.service.ts`
-- Trigger: 修改包装方案默认值逻辑、删除逻辑、协作者权限或请求体结构后，很容易在无感情况下破坏写接口。
-- Workaround: 变更该链路时至少手测四个接口；更稳妥的做法是先补 POST / PUT / DELETE 路由测试与 `PackagingService` 单测。
-
-**回收站产品 / SKU 路由缺少独立测试，恢复与硬删除日志链路脆弱:**
-- Symptoms: `src/app/api/trash/products/[id]/route.ts` 和 `src/app/api/trash/skus/[id]/route.ts` 直接写 `activityLog`，但仓库内未检测到对应路由测试。
-- Files: `src/app/api/trash/products/[id]/route.ts`, `src/app/api/trash/skus/[id]/route.ts`, `src/server/middleware/request-logger.ts`
-- Trigger: 调整 `productService.deleteProduct`、`skuService`、活动日志结构或认证上下文后，路由很可能出现“业务成功但日志失败”或“日志成功但响应异常”的割裂。
-- Workaround: 变更回收站逻辑时手动验证恢复、彻底删除、活动日志三条链路；后续应补针对 `POST` / `DELETE` 的 API 测试。
-
-## Security Considerations
-
-**仓库内存在硬编码默认管理员账号与密码:**
-- Risk: `src/server/services/system-init.service.ts` 直接声明 `admin@system.local` 与 `Admin@123456`，并在启动时自动创建默认超级管理员。
-- Files: `src/server/services/system-init.service.ts`, `src/lib/init.ts`
-- Current mitigation: 创建后标记 `isFirstLogin: true`，并提示首次登录修改信息。
-- Recommendations: 改为仅在显式初始化命令下创建；邮箱和密码由环境变量或一次性 bootstrap token 注入；生产环境默认禁用自动超级管理员创建。
-
-**演示种子服务写死演示账号和统一密码:**
-- Risk: `src/server/services/open-platform-demo-seed.service.ts` 固定使用 `open-platform-planner@example.com`、`open-platform-reviewer@example.com` 和 `Seed123456!`，并通过 `seed()` 返回登录信息。
-- Files: `src/server/services/open-platform-demo-seed.service.ts`
-- Current mitigation: 密码入库前会做哈希；服务内用 marker 区分演示数据。
-- Recommendations: 将演示种子限定在开发环境脚本；禁止在生产构建或公共接口中暴露演示登录信息；密码改为一次性生成并只在本地终端输出。
-
-## Performance Bottlenecks
-
-**3D 选中与高亮链路大量遍历场景树，模型变大时会卡顿:**
-- Problem: `src/lib/3d/engine.ts` 在命中解析、对象查找、批量高亮、取所有 mesh 等路径上反复调用 `scene.traverse`、`modelRoot.traverse`、`getAllMeshes()` 和 `getObjectByName()`。
-- Files: `src/lib/3d/engine.ts`
-- Cause: 运行时按名字做多轮模糊匹配，没有稳定的节点索引缓存；调试日志也散落在模型加载和选择过程中。
-- Improvement path: 建立模型加载后的节点索引与 alias cache，把查找从“整树遍历”收敛到字典读取；把调试日志严格收束到显式 debug 开关。
-
-**孔位 2D 覆盖层会在映射和投影阶段多次遍历模型:**
-- Problem: `src/components/3d/HoleOverlay2D.tsx` 在板件对象解析、严格孔位映射、leader 生成等阶段多次 `modelRoot.traverse`，同时大量做世界坐标到屏幕坐标转换。
-- Files: `src/components/3d/HoleOverlay2D.tsx`
-- Cause: 叠加层同时承担“查对象、容错匹配、投影、去重、绘制准备”多种职责，缺少预计算缓存。
-- Improvement path: 拆出一次性计算的板件映射索引与包围盒缓存；把实时 render 依赖限制在必要的相机变化和 transform 变化。
-
-## Fragile Areas
-
-**旧装配编辑器工作区文件过大，状态和 UI 耦合严重:**
-- Files: `src/app/products/[id]/assembly/AssemblyEditorWorkspace.tsx`
-- Why fragile: 单文件约 3600 行，混合了安装顺序、上下文菜单、材质、孔位高亮、组件装配、播放控制和移动端 UI 状态；轻微改动就可能引发跨功能回归。
-- Safe modification: 先在现有 hook 与纯函数层补测试，再按子域拆分为安装顺序、材质、预览、菜单几个独立模块；避免直接在工作区文件里继续叠加新分支。
-- Test coverage: 未检测到 `src/app/products/[id]/assembly/AssemblyEditorWorkspace.test.tsx`；当前只有 `src/app/products/[id]/assembly/hooks/__tests__/useAssemblyEditorApi.test.tsx` 和部分 3D / lib 层测试，无法直接覆盖整页状态机。
-
-**开放平台演示种子服务一次串完整主链，任何一个子步骤变更都可能牵一发动全身:**
-- Files: `src/server/services/open-platform-demo-seed.service.ts`
-- Why fragile: 同时依赖资产中心、自动组合、草稿组、包装、正式入库、轻仓库六条链路，并在执行前删除旧演示数据。
-- Safe modification: 只在需要联调演示时触碰；拆为“账号准备”“资产准备”“草稿组生成”“包装注入”“正式入库”几个明确步骤，并用幂等标记分别验证。
-- Test coverage: 有 `src/server/services/__tests__/open-platform-demo-seed.service.test.ts`，但主要覆盖候选选择、包装输入拼装和 happy path；对异常清理、并发执行、部分失败回滚覆盖不足。
-
-## Scaling Limits
-
-**请求日志只保存在进程内存，无法支撑多实例和长周期排障:**
-- Current capacity: `src/server/middleware/request-logger.ts` 只保留最多 `1000` 条 `requestLogs`，进程重启即丢失。
-- Limit: 多实例部署、Serverless 冷启动或高并发下，请求统计和慢请求分析没有全局一致性，也不能追溯历史。
-- Scaling path: 将请求日志接入集中式日志系统或数据库表；保留本地内存日志仅作为开发态调试缓冲。
-
-## Dependencies at Risk
-
-**React 19 + Next 16 + Three 生态组合依赖版本锁定较紧:**
-- Risk: `package.json` 通过 `overrides` 强制 `@react-three/drei`、`@react-three/fiber`、`@react-spring/*` 适配 React `19.2.4`，说明当前 3D 栈对上游版本兼容性比较脆弱。
-- Impact: 升级 React、Next 或 3D 相关依赖时，`src/lib/3d/*`、`src/components/3d/*`、`src/app/products/[id]/assembly/*` 很可能先出问题。
-- Migration plan: 后续升级前先单独跑 3D/装配测试集，优先验证 `src/lib/3d/__tests__/*`、`src/components/3d/__tests__/*`、`src/app/products/[id]/assembly/hooks/__tests__/*`。
-
-## Missing Critical Features
-
-**缺少对旧链包装与新主链包装的一致性治理:**
-- Problem: 正式产品包装仍走 `PackagingPlan`，新主链包装走 `PreSkuPackagingPlan`，当前只在正式入库时做一次复制，没有统一的差异检测或同步规则。
-- Blocks: 后续如果要做包装版本追踪、重新入库、包装成本对账或“草稿组变更回刷正式 SKU”，现有结构难以保证一致性。
-
-## Test Coverage Gaps
-
-**系统初始化与降级模式未检测到自动化测试:**
-- What's not tested: 默认管理员创建、数据库重试、降级模式进入/恢复、`throwOnFailure` 分支。
-- Files: `src/server/services/system-init.service.ts`, `src/lib/init.ts`
-- Risk: 启动期问题会直接影响整站可用性，但当前改动没有自动回归护栏。
-- Priority: High
-
-**请求日志中间件未检测到自动化测试:**
-- What's not tested: 请求 ID、慢请求统计、错误日志筛选、内存上限裁剪、开发态打印分支。
-- Files: `src/server/middleware/request-logger.ts`
-- Risk: 监控与排障数据出错时，开发阶段不容易第一时间发现。
-- Priority: Medium
-
-**旧产品详情 / SKU 详情页直接查库，但未检测到对应页面测试:**
-- What's not tested: 权限校验后的详情装载、敏感字段裁剪、SKU 级板件 / 孔位 / 五金范围隔离。
-- Files: `src/app/products/[id]/page.tsx`, `src/app/products/[id]/skus/[skuId]/page.tsx`, `src/app/products/[id]/skus/[skuId]/assembly/page.tsx`
-- Risk: 详情页容易在权限、软删除、兼容链字段变化时静默回归。
-- Priority: High
-
----
-
-*Concerns audit: 2026-04-02*

furniture-3d-system/.planning/codebase/CONVENTIONS.md

@@ -1,145 +0,0 @@
-# Coding Conventions
-
-**Analysis Date:** 2026-04-02
-
-## Naming Patterns
-
-**Files:**
-- Use kebab-case for most source files under `src/server/services`, `src/server/repositories`, `src/lib`, and route segments such as `src/server/services/planning.service.ts`, `src/server/repositories/planning.repository.ts`, `src/lib/panel-selection-resolution.ts`, `src/app/api/warehouse/route.ts`.
-- Use PascalCase for React component files under `src/components` and page clients such as `src/components/platform/PlatformPageFrame.tsx`, `src/components/ui/Button.tsx`, `src/app/warehouse/WarehouseClient.tsx`.
-- Use suffix-based names to encode responsibility. Common suffixes already used in code:
-  - `*.service.ts` for business logic in `src/server/services`
-  - `*.repository.ts` for data access in `src/server/repositories`
-  - `*.mapper.ts` for DTO/entity mapping in `src/server/services/planning.mapper.ts`, `src/server/services/draft-group.mapper.ts`
-  - `*.types.ts` for module-local types in `src/server/services/planning.service.types.ts`, `src/app/home/home-client.types.ts`
-  - `*.container.tsx` and `*.workspace.tsx` for wrapper/composition variants in `src/app/products/[id]/ProductDetailClient.container.tsx`, `src/app/products/[id]/ProductDetailClient.workspace.tsx`
-  - `route.ts` and `route.test.ts` for API handlers and colocated API tests in `src/app/api/auth/login/route.ts`, `src/app/api/auth/login/route.test.ts`
-
-**Functions:**
-- Use camelCase for functions and methods. Examples: `parsePlanningSlotSelections` in `src/lib/planning/parsers.ts`, `getWorkspaceDetail` in `src/server/services/planning.service.ts`, `calculatePagination` in `src/server/core/response.ts`.
-- Use verb-led names for actions and booleans that read like capabilities. Examples: `assertCanWritePlanning` in `src/server/services/planning-scope.service.ts`, `canReadWorkspace` in `src/server/services/planning-scope.service.ts`, `useCreateUser` in `src/hooks/api/useUsers.ts`.
-- Use `toXxxDTO` naming for mappers. Examples: `toTemplateDTO`, `toWorkspaceDTO`, `toDraftDTO` in `src/server/services/planning.mapper.ts`.
-
-**Variables:**
-- Use camelCase for local variables and object keys. Examples: `requestId`, `generationContext`, `slotAssetOptions`, `pendingRequestRef`.
-- Use ALL_CAPS only for true constants and config maps. Examples: `USER_STORAGE_KEY` in `src/hooks/useAuth.ts`, `MODAL_IDS` in `src/stores/ui.store.ts`, `CACHE_TTL` in `src/server/core/constants.ts`.
-- Prefix intentionally unused parameters with `_` to satisfy lint configuration. Examples appear in `src/server/services/base.service.ts` (`_ctx`) and `src/server/services/draft-group.service.ts`.
-
-**Types:**
-- Use PascalCase for interfaces, classes, DTOs, and aliases. Examples: `PlanningWorkspaceDTO`, `PlanningTemplateWithRelations`, `RequestContext`, `ButtonProps`.
-- Use explicit `Props` suffix for component props and `Result`/`DTO` suffix for return models. Examples: `PlatformPageFrameProps` in `src/components/platform/PlatformPageFrame.tsx`, `ListResult` in `src/server/services/base.service.ts`, `WarehouseOverviewDTO` in `src/server/services/warehouse.service.types.ts`.
-
-## Code Style
-
-**Formatting:**
-- No Prettier or Biome config is detected at repo root. Formatting is effectively governed by existing file style plus ESLint in `eslint.config.mjs`.
-- The codebase is not fully normalized. Both semicolon-heavy and semicolon-free styles coexist:
-  - Semicolon-light style: `src/server/services/planning.service.ts`, `src/components/platform/PlatformPageFrame.tsx`
-  - Semicolon-heavy legacy style: `src/hooks/useAuth.ts`, `src/components/ui/Button.tsx`
-- Keep edits consistent with the file you touch instead of trying to reformat unrelated lines.
-- TypeScript strict mode is enabled in `tsconfig.json`, but `noImplicitAny` is explicitly disabled. Prefer real types for new code even though existing code allows gradual typing.
-
-**Linting:**
-- ESLint is configured through `eslint.config.mjs` with `eslint-config-next/core-web-vitals` and `eslint-config-next/typescript`.
-- Treat lint warnings as standards debt, not as permission to add more debt. The current config downgrades several rules to `warn`, including:
-  - `@typescript-eslint/no-explicit-any`
-  - `@typescript-eslint/no-unused-vars` with `_` ignore patterns
-  - `@typescript-eslint/ban-ts-comment`
-  - `react-hooks/exhaustive-deps`
-  - `react-hooks/set-state-in-effect`
-  - `react-hooks/immutability`
-- Tests under `tests/**` and `**/*.test.ts(x)` are excluded from lint in `eslint.config.mjs`, so do not rely on lint alone to keep tests clean.
-
-## Import Organization
-
-**Order:**
-1. Framework and third-party packages first. Examples: `next/server`, `react`, `@prisma/client`, `lucide-react`.
-2. Alias imports from `@/` second. Examples in `src/app/api/warehouse/route.ts` and `src/components/platform/PlatformPageFrame.tsx`.
-3. Relative imports last for same-folder modules. Examples: `./planning.mapper`, `./PlatformFlowNav`, `../repositories`.
-
-**Path Aliases:**
-- Use the `@/*` alias from `tsconfig.json` for cross-folder imports.
-- Prefer alias imports for anything outside the current feature folder. Examples:
-  - `@/server/core/response`
-  - `@/components/ui/Button`
-  - `@/lib/planning/parsers`
-- Use relative imports only for near-neighbor modules inside the same slice. Examples:
-  - `./planning.service.types`
-  - `./route`
-  - `../repositories`
-
-## Error Handling
-
-**Patterns:**
-- API routes should wrap logic with `handleRequest` from `src/server/core/response.ts`. Example: `src/app/api/warehouse/route.ts`.
-- Domain failures should use `AppError` and `ErrorCode` from `src/server/core/errors.ts`. Example usage is visible throughout `src/server/services/planning.service.ts`.
-- Route handlers may catch `AppError` only to convert to `jsonError`; unknown errors should be rethrown so `handleRequest` can produce a standard 500 response. Example: `src/app/api/warehouse/route.ts`.
-- Service-layer validation is performed before repository writes and should fail fast with readable Chinese messages. Example messages in `src/server/services/planning.service.ts` include `'规划模板不存在'` and `'模板编码和名称不能为空'`.
-- Client-side code currently uses `console.error` for recoverable UI/network failures in places like `src/hooks/useAuth.ts`. Preserve user-facing recovery behavior if touching those paths.
-
-## Logging
-
-**Framework:** `console` plus thin service wrappers.
-
-**Patterns:**
-- Core request logging and error output currently rely on `console.error` inside `src/server/core/response.ts`.
-- Additional logging helpers exist in `src/lib/logger.ts`, `src/server/services/logger.service.ts`, and `src/server/middleware/request-logger.ts`, but direct `console` usage is still common.
-- Use request-scoped IDs when logging server request failures; `handleRequest` already generates `requestId` in `src/server/core/response.ts`.
-
-## Comments
-
-**When to Comment:**
-- Prefer brief comments before non-obvious behavior, polyfills, compatibility workarounds, or architecture boundaries.
-- Existing examples:
-  - Jest environment/polyfill rationale in `jest.setup.js`
-  - accessibility and focus behavior notes in `src/components/ui/Button.tsx`
-  - cache behavior notes in `src/server/services/base.service.ts`
-- Avoid restating obvious code. Most newer files such as `src/components/platform/PlatformPageFrame.tsx` and `src/server/services/planning.service.ts` are readable without heavy comments.
-
-**JSDoc/TSDoc:**
-- JSDoc is used inconsistently.
-  - Heavy JSDoc in older foundational files: `src/components/ui/Button.tsx`, `src/server/services/base.service.ts`, `src/server/repositories/base.repository.ts`
-  - Minimal or no JSDoc in newer platform files: `src/server/services/planning.service.ts`, `src/components/platform/PlatformPageFrame.tsx`
-- For new work, add JSDoc only for shared utilities, base classes, or APIs whose contracts are not obvious from names and types.
-
-## Function Design
-
-**Size:** Keep route handlers small and orchestration-focused. Business logic belongs in services, not in `src/app/api/**/route.ts`.
-
-**Parameters:**
-- Prefer typed input objects for service methods when there are multiple related inputs. Examples: `createTemplate(input, user)` and `createWorkspace(input, user)` in `src/server/services/planning.service.ts`.
-- Prefer explicit `Props` interfaces for React components. Example: `PlatformPageFrameProps` in `src/components/platform/PlatformPageFrame.tsx`.
-- In hooks, return structured objects rather than tuples when more than one value is exposed. Example: `useAuth` and `usePermissions` in `src/hooks/useAuth.ts`.
-
-**Return Values:**
-- API routes should return `jsonSuccess(...)` / `jsonError(...)` from `src/server/core/response.ts`.
-- Services usually return DTOs directly in newer modules such as `src/server/services/planning.service.ts`; generic base services may still use `ServiceResult<T>` in `src/server/services/base.service.ts`.
-- Repository methods should return raw persistence models or relation-enriched records, not DTOs. Example: `PlanningWorkspaceWithRelations` from `src/server/repositories/planning.repository.ts`.
-
-## Module Design
-
-**Exports:**
-- Prefer named exports for reusable functions, hooks, DTO helpers, services, and most components. Examples: `PlatformPageFrame`, `planningService`, `calculatePagination`, `useUsers`.
-- Default exports are common for page-level components and some legacy UI primitives. Examples: `src/app/warehouse/WarehouseClient.tsx`, `src/app/asset-center/page.tsx`, `src/components/ui/Button.tsx`.
-- Keep both the class and singleton export when a service/repository is meant to be mocked or instantiated in tests. Examples:
-  - `export const planningService = new PlanningService()`
-  - `export { PlanningService }`
-  - similar pattern in `src/server/repositories/planning.repository.ts`
-
-**Barrel Files:**
-- Barrel files are used selectively, not universally.
-  - Present for grouped APIs: `src/server/services/index.ts`, `src/server/repositories/index.ts`, `src/hooks/api/index.ts`, `src/components/upload/index.ts`, `src/components/packaging/index.ts`
-  - Many feature folders still import concrete files directly.
-- When adding a new module to an existing barrel-managed folder, update that folder's `index.ts`. Otherwise import the file directly and do not create a new barrel just for one file.
-
-## Prescriptive Patterns To Follow
-
-- For new backend work under `src/app/api`, keep the route as input/auth/response glue only, and push rules into `src/server/services`.
-- For new server business logic, colocate DTO types in `*.service.types.ts` and mapping helpers in `*.mapper.ts` when transformation logic grows.
-- For new frontend pages on the new platform path, reuse `src/components/platform` and `src/components/ui` primitives before introducing page-specific primitives.
-- For imports, keep third-party first, `@/` aliases second, and same-folder relative imports last.
-- For touched files with legacy semicolon style, match local style. Do not mass-reformat to enforce a repo-wide style that the repo does not currently enforce.
-
----
-
-*Convention analysis: 2026-04-02*

furniture-3d-system/.planning/codebase/INTEGRATIONS.md

@@ -1,107 +0,0 @@
-# External Integrations
-
-**Analysis Date:** 2026-04-02
-
-## APIs & External Services
-
-**Database & ORM:**
-- PostgreSQL - primary transactional database for all business domains
-  - SDK/Client: `@prisma/client`, `@prisma/adapter-pg`, `pg`
-  - Auth: `DATABASE_URL`
-  - Evidence: `prisma/schema.prisma`, `prisma.config.ts`, `src/lib/prisma.ts`
-
-**Object Storage:**
-- MinIO or another S3-compatible object store - stores uploaded models, thumbnails, and generated asset files
-  - SDK/Client: `@aws-sdk/client-s3`
-  - Auth: `S3_ENDPOINT`, `S3_PUBLIC_ENDPOINT`, `S3_PUBLIC_URL`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_REGION`, `S3_BUCKET`
-  - Evidence: `src/lib/storage.ts`, `src/app/api/upload/model/route.ts`, `src/server/services/product-upload.service.ts`, `src/server/services/product-cad-upload.service.ts`
-
-**Caching:**
-- Redis (optional) - L2 cache when available, with in-memory fallback when `REDIS_URL` is absent or unavailable
-  - SDK/Client: `ioredis`
-  - Auth: `REDIS_URL`
-  - Evidence: `src/server/cache/cache.service.ts`
-
-**CAD / Conversion Services:**
-- DWG conversion HTTP service - converts DWG files through `/health`, `/convert`, `/status/:taskId`, and `/download/:taskId`
-  - SDK/Client: native `fetch`
-  - Auth: `DWG_CONVERTER_URL`
-  - Evidence: `src/lib/storage.ts`, `src/server/services/sku-upload.service.ts`, `src/server/services/product-upload.service.ts`
-- ODA File Converter - local/native DWG conversion executable fallback for CAD processing
-  - SDK/Client: child process wrapper around local binary
-  - Auth: `ODA_FILE_CONVERTER`
-  - Evidence: `src/lib/dwg/oda-wrapper.ts`, `src/lib/dwg/converter.ts`
-
-## Data Storage
-
-**Databases:**
-- PostgreSQL
-  - Connection: `DATABASE_URL`
-  - Client: Prisma with `PrismaPg` adapter and `pg` connection pool in `src/lib/prisma.ts`
-
-**File Storage:**
-- S3-compatible object storage
-  - Upload API entry: `src/app/api/upload/model/route.ts`
-  - Service-layer usage: `src/server/services/product-upload.service.ts`, `src/server/services/product-cad-upload.service.ts`
-
-**Caching:**
-- Redis when configured; otherwise in-process memory cache
-  - Implementation: `src/server/cache/cache.service.ts`
-
-## Authentication & Identity
-
-**Auth Provider:**
-- Custom JWT auth backed by Prisma `User` records
-  - Implementation: `src/server/services/auth.service.ts`, `src/lib/jwt.ts`, `src/lib/token-validator.ts`, `src/proxy.ts`
-  - Session transport: `auth-token` HTTP-only cookie set by `src/app/api/auth/login/route.ts`
-  - Password hashing: `bcryptjs` via `src/lib/password.ts`
-
-## Monitoring & Observability
-
-**Error Tracking:**
-- None detected for external SaaS error tracking; no Sentry/Datadog/New Relic SDK usage was found in `src/`
-
-**Logs:**
-- Console-based application/runtime logging in files such as `src/lib/storage.ts`, `src/lib/jwt.ts`, and `src/server/cache/cache.service.ts`
-- In-memory request log buffer for API diagnostics in `src/server/middleware/request-logger.ts`
-- Persistent business audit logs in PostgreSQL `ActivityLog` via `src/server/services/logger.service.ts`
-- Health endpoint for container and ops checks: `src/app/api/health/route.ts` and `src/server/services/health.service.ts`
-
-## CI/CD & Deployment
-
-**Hosting:**
-- Dockerized Next.js standalone app is the main deployment shape
-  - Build/runtime: `Dockerfile`
-  - Compose manifests present: `docker-compose.yml`, `docker-compose.dev.yml`, `docker-compose.prod.yml`, `docker-compose.standard.yml`, `docker-compose.lightweight.yml`, `docker-compose.test.yml`
-
-**CI Pipeline:**
-- Not detected
-- Deployment is script-driven through `scripts/deploy.ps1`, `scripts/deploy.sh`, and `scripts/remote-deploy.sh`
-
-## Environment Configuration
-
-**Required env vars:**
-- Core runtime: `DATABASE_URL`, `JWT_SECRET`
-- Auth/session support: `JWT_EXPIRES_IN`, `NEXT_PUBLIC_APP_URL`
-- Storage: `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`
-- Common optional/runtime extensions: `S3_PUBLIC_ENDPOINT`, `S3_PUBLIC_URL`, `S3_REGION`, `S3_BUCKET`, `REDIS_URL`, `DWG_CONVERTER_URL`, `ODA_FILE_CONVERTER`, `DWG_TEMP_DIR`, `DWG_OUTPUT_DIR`, `PRISMA_LOG_QUERIES`, `NEXTAUTH_SECRET`, `NEXTAUTH_URL`
-
-**Secrets location:**
-- Repo root `.env` and `.env.test` are present; `.env.example` exists as the template source
-- Prisma bootstrapping reads `.env` in `prisma.config.ts`
-- Remote deployment generates a target `.env` from `.env.example` in `scripts/remote-deploy.sh`
-
-## Webhooks & Callbacks
-
-**Incoming:**
-- None detected under `src/app/api/` for webhook-style integrations
-
-**Outgoing:**
-- DWG conversion HTTP calls to the service behind `DWG_CONVERTER_URL` from `src/lib/storage.ts`
-- S3 API calls to the configured object store from `src/lib/storage.ts`
-- PostgreSQL and Redis network connections from `src/lib/prisma.ts` and `src/server/cache/cache.service.ts`
-- Remote SSH deployment calls from `scripts/remote-deploy.sh`
-
----
-
-*Integration audit: 2026-04-02*

furniture-3d-system/.planning/codebase/STACK.md

@@ -1,89 +0,0 @@
-# Technology Stack
-
-**Analysis Date:** 2026-04-02
-
-## Languages
-
-**Primary:**
-- TypeScript 5 - application code in `src/`, `tests/`, `scripts/`, and Prisma seed/config files such as `prisma/seed.ts` and `prisma.config.ts`
-
-**Secondary:**
-- JavaScript - Node/Next config and helper scripts in `package.json`, `next.config.js`, `jest.config.js`, and `scripts/*.js`
-- SQL via Prisma schema - relational data model in `prisma/schema.prisma`
-- Shell/PowerShell - deployment, backup, restore, and environment validation in `scripts/*.sh`, `scripts/*.ps1`, and `scripts/remote-deploy.sh`
-
-## Runtime
-
-**Environment:**
-- Node.js 18+ for local development, stated in `README.md`
-- Node.js 18 Alpine container runtime in `Dockerfile`
-
-**Package Manager:**
-- npm - driven by `package.json`
-- Lockfile: present in `package-lock.json`
-
-## Frameworks
-
-**Core:**
-- Next.js 16.1.6 - App Router web application and API routes in `package.json` and `src/app/`
-- React 19.2.4 - UI runtime for pages, components, and hooks in `package.json` and `src/components/`
-- Prisma 7.3.0 - ORM/data access layer configured by `prisma.config.ts`, `prisma/schema.prisma`, and `src/lib/prisma.ts`
-
-**Testing:**
-- Jest 30.2.0 - test runner configured in `jest.config.js`
-- React Testing Library 16.3.2 - component and UI assertions from `package.json`
-- Supertest 7.2.2 - API test client from `package.json`
-- Fast-check 4.5.3 - property-based testing dependency from `package.json`
-
-**Build/Dev:**
-- TypeScript 5 - static typing via `tsconfig.json`
-- ESLint 9 + `eslint-config-next` 16.1.6 - linting from `package.json` and `eslint.config.mjs`
-- Tailwind CSS 4.1.18 + PostCSS - styling pipeline from `package.json` and `postcss.config.mjs`
-- `tsx` 4.21.0 - TypeScript runtime for seeds and scripts in `package.json`
-- Docker multi-stage build - production packaging in `Dockerfile`
-
-## Key Dependencies
-
-**Critical:**
-- `@prisma/client` 7.3.0 - generated DB client used throughout repositories and services such as `src/server/repositories/*.ts`
-- `@prisma/adapter-pg` 7.3.0 + `pg` 8.17.2 - Prisma 7 PostgreSQL adapter/pool setup in `src/lib/prisma.ts` and `prisma/seed.ts`
-- `jsonwebtoken` 9.0.3 + `bcryptjs` 3.0.3 - custom auth stack in `src/lib/jwt.ts`, `src/server/services/auth.service.ts`, and `src/server/services/system-init.service.ts`
-- `@aws-sdk/client-s3` 3.948.0 - S3-compatible object storage client in `src/lib/storage.ts`
-- `ioredis` 5.9.2 - optional cache backend with memory fallback in `src/server/cache/cache.service.ts`
-
-**Infrastructure:**
-- `three` 0.182.0, `@react-three/fiber` 9.5.0, `@react-three/drei` 10.7.7 - 3D rendering and scene tooling in `src/lib/3d/` and `src/components/3d/`
-- `gsap` 3.12.5 and `framer-motion` 12.29.2 - animation systems used in interactive UI and playback code
-- `react-hook-form` 7.54.2 + `@hookform/resolvers` 5.2.2 + `zod` 4.3.6 - form state and validation across API/UI boundaries
-- `zustand` 5.0.2 - client state store in `src/stores/`
-- `obj2gltf` 3.2.0 - DWG/OBJ to glTF conversion pipeline support in `src/lib/dwg/converter.ts`
-
-## Configuration
-
-**Environment:**
-- Runtime configuration is env-driven; code references `DATABASE_URL`, `JWT_SECRET`, `JWT_EXPIRES_IN`, `REDIS_URL`, `S3_ENDPOINT`, `S3_PUBLIC_ENDPOINT`, `S3_PUBLIC_URL`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_REGION`, `S3_BUCKET`, `NEXT_PUBLIC_APP_URL`, `NEXTAUTH_SECRET`, `NEXTAUTH_URL`, `DWG_CONVERTER_URL`, `ODA_FILE_CONVERTER`, `DWG_TEMP_DIR`, `DWG_OUTPUT_DIR`, and `PRISMA_LOG_QUERIES`
-- `.env`, `.env.example`, and `.env.test` exist at repo root; `prisma.config.ts` explicitly loads `DATABASE_URL` from `.env` when needed
-- Auth and storage fail fast on missing secrets in `src/lib/jwt.ts` and `src/lib/storage.ts`
-
-**Build:**
-- TypeScript path alias `@/*` is defined in `tsconfig.json`
-- Next standalone output, headers, redirects, image remote patterns, and bundling rules are defined in `next.config.js`
-- Prisma schema and migrations are configured in `prisma.config.ts`
-- Docker build and runtime packaging are defined in `Dockerfile`
-- Compose variants exist for local/dev/prod/lightweight/test deployment: `docker-compose.yml`, `docker-compose.dev.yml`, `docker-compose.prod.yml`, `docker-compose.lightweight.yml`, `docker-compose.standard.yml`, and `docker-compose.test.yml`
-
-## Platform Requirements
-
-**Development:**
-- Install Node.js 18+, PostgreSQL 14+, MinIO or another S3-compatible object store, and optionally Redis, per `README.md`
-- Docker is used for local dependency orchestration and optional DWG conversion service, per `README.md`
-- ODA File Converter can be installed locally for native DWG conversion, with path discovery in `src/lib/dwg/oda-wrapper.ts`
-
-**Production:**
-- Primary target is a Dockerized Next.js standalone deployment produced by `Dockerfile`
-- Health-check and ops scripts assume containerized services plus shell/PowerShell tooling in `scripts/validate-config.*`, `scripts/deploy.*`, `scripts/backup-*.sh`, and `scripts/backup-*.ps1`
-- Remote deployment over SSH is supported by `scripts/remote-deploy.sh`
-
----
-
-*Stack analysis: 2026-04-02*

furniture-3d-system/.planning/codebase/STRUCTURE.md

@@ -1,160 +0,0 @@
-# Codebase Structure
-
-**Analysis Date:** 2026-04-02
-
-## Directory Layout
-
-```text
-furniture-3d-system/
-├── prisma/                 # Prisma schema, migrations, seed data
-├── public/                 # Static assets and uploaded/runtime-served files
-├── scripts/                # Local maintenance, seed, sync, and type-check scripts
-├── src/
-│   ├── app/                # Next.js App Router pages and API routes
-│   ├── components/         # Shared UI, 3D viewers, assembly editors, platform shells
-│   ├── hooks/              # Client hooks and API hooks
-│   ├── lib/                # Shared utilities, rule engines, auth/session helpers
-│   ├── providers/          # React providers
-│   ├── server/             # Core server abstractions, services, repositories, cache
-│   ├── stores/             # Zustand state stores
-│   └── types/              # Cross-feature TS types
-├── tests/                  # Cross-cutting integration/security/performance tests
-├── docs/                   # Workflow, standards, architecture, and feature docs
-└── .planning/codebase/     # GSD-generated codebase mapping docs
-```
-
-## Directory Purposes
-
-**`src/app`:**
-- Purpose: hold all routeable UI pages and HTTP API handlers.
-- Contains: root pages (`src/app/page.tsx`), new platform pages (`src/app/asset-center`, `src/app/auto-combinations`, `src/app/draft-groups`, `src/app/intake`, `src/app/warehouse`), legacy pages (`src/app/products`, `src/app/share`), and App Router APIs (`src/app/api`).
-- Key files: `src/app/layout.tsx`, `src/app/page.tsx`, `src/app/api/platform/schemas.ts`, `src/app/api/asset-center/families/route.ts`, `src/app/api/products/[id]/assembly/generate/route.ts`
-
-**`src/components`:**
-- Purpose: keep reusable UI and rich client widgets out of route files.
-- Contains: platform shell components in `src/components/platform`, 3D/assembly widgets in `src/components/3d` and `src/components/assembly`, generic UI atoms in `src/components/ui`, and domain widgets such as `src/components/packaging`.
-- Key files: `src/components/platform/PlatformPageFrame.tsx`, `src/components/platform/platform-navigation.ts`, `src/components/3d/ModelViewer.tsx`, `src/components/assembly/AssemblyEditorClient.tsx`
-
-**`src/lib`:**
-- Purpose: shared non-DB logic used by both server and client.
-- Contains: auth/session helpers (`src/lib/auth-middleware.ts`, `src/lib/server-session.ts`), Prisma singleton (`src/lib/prisma.ts`), open-platform rules (`src/lib/open-product/*`), planning rules (`src/lib/planning/*`), legacy CAD/3D helpers (`src/lib/assembly-generator.ts`, `src/lib/3d/*`).
-- Key files: `src/lib/prisma.ts`, `src/lib/open-product/single-board-desk.ts`, `src/lib/open-product/platform-api.ts`, `src/lib/planning/candidate-generator.ts`
-
-**`src/server`:**
-- Purpose: central backend module tree.
-- Contains: `core` request/response/error types, `services` business orchestration, `repositories` data access, `cache`, `validators`, `middleware`, and `monitoring`.
-- Key files: `src/server/core/response.ts`, `src/server/services/index.ts`, `src/server/services/draft-group.service.ts`, `src/server/repositories/base.repository.ts`, `src/server/repositories/draft-group.repository.ts`
-
-**`src/stores`:**
-- Purpose: client-side Zustand stores for shared UI state.
-- Contains: auth, product, and UI stores.
-- Key files: `src/stores/auth.store.ts`, `src/stores/product.store.ts`, `src/stores/ui.store.ts`
-
-**`prisma`:**
-- Purpose: define persistence schema and DB evolution history.
-- Contains: `schema.prisma`, seed file, config, and migration SQL folders.
-- Key files: `prisma/schema.prisma`, `prisma/seed.ts`, `prisma/migrations/20260330193000_add_open_product_platform/migration.sql`, `prisma/migrations/20260331193000_upgrade_pre_sku_packaging_plan/migration.sql`
-
-**`tests`:**
-- Purpose: hold repo-level tests that are not colocated with a single source folder.
-- Contains: API tests, security tests, performance checks, shared mocks, and library tests.
-- Key files: `tests/api/assembly-generate-from-order.route.test.ts`, `tests/security/authorization.test.ts`, `tests/services/product-list-cache-version.test.ts`
-
-## Key File Locations
-
-**Entry Points:**
-- `src/app/layout.tsx`: global App Router shell and metadata.
-- `src/app/page.tsx`: authenticated home/dashboard entry.
-- `src/proxy.ts`: page-level auth gate for Next.js requests.
-
-**Configuration:**
-- `package.json`: scripts and runtime dependencies.
-- `prisma/schema.prisma`: application data model.
-- `prisma/prisma.config.ts`: Prisma configuration.
-
-**Core Logic:**
-- `src/server/services`: business logic layer.
-- `src/server/repositories`: persistence abstraction layer.
-- `src/lib/open-product`: new platform combination, validation, and view contracts.
-- `src/lib/planning`: planning template parsing and candidate generation.
-
-**Testing:**
-- `src/app/__tests__`: page-level tests.
-- `src/server/services/__tests__`: service-layer tests.
-- `src/components/*/__tests__`: component tests.
-- `tests/`: broader API, security, performance, and library tests.
-
-## Naming Conventions
-
-**Files:**
-- Route files use Next.js conventions: `src/app/**/page.tsx`, `src/app/api/**/route.ts`.
-- Service and repository files use dot-suffixed domain names: `src/server/services/draft-group.service.ts`, `src/server/repositories/draft-group.repository.ts`.
-- Client-heavy page companions use `*Client.tsx`, `*.container.tsx`, and `*.workspace.tsx`, for example `src/app/HomeClient.tsx` and `src/app/products/[id]/ProductDetailClient.workspace.tsx`.
-
-**Directories:**
-- Feature directories use kebab-case route names in `src/app`, such as `src/app/asset-center`, `src/app/auto-combinations`, `src/app/draft-groups`.
-- Shared backend directories are pluralized by role, such as `src/server/services`, `src/server/repositories`, `src/server/validators`.
-
-## Where to Add New Code
-
-**New Feature:**
-- Primary code: put route entrypoints under the closest feature path in `src/app`; for new mainline steps, prefer `src/app/<feature>` plus matching APIs in `src/app/api/<feature>`.
-- Tests: colocate page/client tests beside the feature in `src/app/<feature>/__tests__` or `src/components/<feature>/__tests__`; add cross-feature API/security coverage under `tests/` when it spans modules.
-
-**New Component/Module:**
-- Implementation: reusable platform-shell UI belongs in `src/components/platform`; legacy CAD or 3D viewer widgets belong in `src/components/assembly` or `src/components/3d`; generic atoms belong in `src/components/ui`.
-
-**Utilities:**
-- Shared helpers: place deterministic domain rules in `src/lib/open-product` for mainline asset/PreSku logic, in `src/lib/planning` for planning workspaces, and in broader `src/lib` only when the helper is not specific to one domain.
-
-## Special Directories
-
-**`src/app/api/platform`:**
-- Purpose: shared Zod transport schemas for new platform APIs.
-- Generated: No
-- Committed: Yes
-
-**`src/components/platform`:**
-- Purpose: the approved visual shell for new platform mainline pages.
-- Generated: No
-- Committed: Yes
-
-**`src/server/cache`:**
-- Purpose: backend cache helpers and cache key policy.
-- Generated: No
-- Committed: Yes
-
-**`.planning/codebase`:**
-- Purpose: persistent codebase maps consumed by later GSD planning and execution commands.
-- Generated: Yes
-- Committed: Yes
-
-**`.next`:**
-- Purpose: Next.js build output and dev runtime artifacts.
-- Generated: Yes
-- Committed: No
-
-## Placement Guidance By Domain
-
-**New Platform Mainline:**
-- Put page shells under `src/app/asset-center`, `src/app/auto-combinations`, `src/app/draft-groups`, `src/app/intake`, or `src/app/warehouse` when extending the existing chain.
-- Put APIs under matching folders like `src/app/api/asset-center`, `src/app/api/draft-groups`, `src/app/api/intake`, and `src/app/api/warehouse`.
-- Put business rules in `src/server/services/asset-center.service.ts`, `src/server/services/combination.service.ts`, `src/server/services/draft-group.service.ts`, `src/server/services/intake.service.ts`, or sibling services rather than inside route files.
-
-**Legacy Product / CAD Compatibility:**
-- Put product-detail and assembly UI under `src/app/products/[id]`, `src/app/products/[id]/assembly`, or `src/app/products/[id]/skus/[skuId]`.
-- Put backend handlers under `src/app/api/products/[id]/**`, `src/app/api/holes/**`, and `src/app/api/hardware/**`.
-- Put data transformations in legacy helper modules such as `src/lib/assembly-generator.ts`, `src/lib/panel-assembly-semantic.ts`, and `src/server/services/sku-cad-import.helper.ts`.
-
-**Planning Workspace Domain:**
-- Put APIs under `src/app/api/planning/templates` and `src/app/api/planning/workspaces`.
-- Put parsing/generation logic in `src/lib/planning` and orchestration in `src/server/services/planning.service.ts` and `src/server/services/planning-generation.service.ts`.
-
-**Packaging Bridge:**
-- Put PreSku-side packaging endpoints under `src/app/api/pre-skus/[id]/packaging`.
-- Put legacy product packaging endpoints under `src/app/api/products/[id]/packaging`.
-- Put persistence and calculations in `src/server/services/pre-sku-packaging.service.ts`, `src/server/services/packaging.service.ts`, and `src/server/repositories/packaging.repository.ts` instead of route handlers.
-
----
-
-*Structure analysis: 2026-04-02*

furniture-3d-system/.planning/codebase/TESTING.md

@@ -1,247 +0,0 @@
-# Testing Patterns
-
-**Analysis Date:** 2026-04-02
-
-## Test Framework
-
-**Runner:**
-- Jest 30 via `jest` in `package.json`
-- Config: `jest.config.js`
-
-**Assertion Library:**
-- Jest built-in assertions plus `@testing-library/jest-dom` from `jest.setup.js`
-
-**Run Commands:**
-```bash
-npm test              # Run all tests
-npm run test:watch    # Watch mode
-npm run test:coverage # Coverage
-```
-
-## Test File Organization
-
-**Location:**
-- Both colocated and centralized tests are used.
-- Colocated tests sit beside the source under `src/**/__tests__` and `src/**/route.test.ts`. Examples:
-  - `src/server/services/__tests__/planning.service.test.ts`
-  - `src/components/platform/__tests__/PlatformPageFrame.test.tsx`
-  - `src/app/api/auth/login/route.test.ts`
-- Centralized suites live under the root `tests/` tree for broader concerns. Examples:
-  - `tests/api/auth.test.ts`
-  - `tests/security/authorization.test.ts`
-  - `tests/performance/rendering.test.tsx`
-  - `tests/services/trash.service.test.ts`
-
-**Naming:**
-- Use `*.test.ts` or `*.test.tsx`.
-- API route tests usually mirror the handler path with `route.test.ts`.
-- Unit tests under colocated folders normally mirror the source file name, such as `src/lib/__tests__/panel-selection-resolution.test.ts` for `src/lib/panel-selection-resolution.ts`.
-
-**Structure:**
-```text
-src/
-  app/**/route.test.ts
-  */__tests__/*.test.ts(x)
-tests/
-  api/*.test.ts
-  security/*.test.ts(x)
-  performance/*.test.tsx
-  services/*.test.ts
-  mocks/*.ts
-```
-
-## Test Structure
-
-**Suite Organization:**
-```typescript
-describe('planningService', () => {
-  beforeEach(() => {
-    jest.clearAllMocks()
-  })
-
-  it('读取工作台详情时返回候选、草稿和已解析的资产挂载点', async () => {
-    const result = await planningService.getWorkspaceDetail('workspace-1', user)
-
-    expect(result.slotAssetOptions).toHaveLength(1)
-    expect(result.candidates[0].key).toBe('candidate-1')
-  })
-})
-```
-- This pattern is taken directly from `src/server/services/__tests__/planning.service.test.ts`.
-
-**Patterns:**
-- Group tests by module, then by scenario using nested `describe(...)`. Examples: `tests/security/authorization.test.ts`, `tests/pages/login.test.tsx`.
-- Reset mocks in `beforeEach` or `afterEach`. Examples:
-  - `jest.clearAllMocks()` in `src/server/services/__tests__/planning.service.test.ts`
-  - `jest.resetAllMocks()` in `src/hooks/__tests__/useAuth.test.tsx`
-- Use Chinese test names extensively. Keep new test descriptions behavior-focused and readable for reviewers.
-- For async expectations, use `await expect(...).rejects...` or `waitFor(...)` instead of arbitrary timers. Examples:
-  - `src/server/services/__tests__/planning.service.test.ts`
-  - `src/hooks/__tests__/useAuth.test.tsx`
-
-## Mocking
-
-**Framework:** Jest mocks via `jest.mock`, `jest.fn`, `jest.mocked`, and occasional `require('./route')` for route modules.
-
-**Patterns:**
-```typescript
-jest.mock('../../repositories', () => ({
-  planningTemplateRepository: {
-    findByIdWithRelations: jest.fn(),
-    create: jest.fn(),
-  },
-}))
-
-const mockedPlanningTemplateRepository = jest.mocked(planningTemplateRepository)
-mockedPlanningTemplateRepository.findByIdWithRelations.mockResolvedValue(...)
-```
-- This repository-mocking pattern is used in `src/server/services/__tests__/planning.service.test.ts`.
-
-```typescript
-jest.mock('@/server/core/response', () => ({
-  handleRequest: (...args: unknown[]) => mockHandleRequest(...args),
-  jsonError: (...args: unknown[]) => mockJsonError(...args),
-  jsonSuccess: (...args: unknown[]) => mockJsonSuccess(...args),
-}))
-
-const { GET, PUT } = require('./route')
-```
-- This route-level mock pattern is used in `src/app/api/pre-skus/[id]/packaging/route.test.ts`.
-
-```typescript
-global.fetch = jest.fn().mockResolvedValue({
-  ok: true,
-  json: async () => ({ success: true, data: { authenticated: true, user: ... } }),
-} as Response)
-```
-- This browser/network mock pattern is used in `src/hooks/__tests__/useAuth.test.tsx`.
-
-**What to Mock:**
-- Mock repositories when testing services in `src/server/services/__tests__`.
-- Mock `@/server/core/response` and `@/server/services` when testing route handlers in `src/app/api/**/route.test.ts`.
-- Mock browser APIs and `global.fetch` for hooks/components using network or router behavior. Examples: `src/hooks/__tests__/useAuth.test.tsx`, `tests/pages/login.test.tsx`.
-- Use `tests/mocks/nanoid.ts` through `moduleNameMapper` when deterministic IDs matter.
-
-**What NOT to Mock:**
-- Do not mock pure algorithmic helpers unless the test is explicitly isolating a higher-level orchestrator. Pure logic in `src/lib`, `src/lib/3d`, `src/lib/open-product`, and `src/lib/planning` is commonly tested directly.
-- Do not mock DOM rendering helpers when the goal is UI output verification. Component tests like `src/components/platform/__tests__/PlatformPageFrame.test.tsx` render the actual component and assert on visible output.
-
-## Fixtures and Factories
-
-**Test Data:**
-```typescript
-const user = {
-  id: 'user-1',
-  email: 'planner@example.com',
-  name: '规划员',
-  role: 'DESIGNER' as const,
-  status: 'ACTIVE' as const,
-  departmentId: 'dept-1',
-  teamId: 'team-1',
-}
-```
-- Inline object fixtures are the dominant style. This pattern appears in `src/server/services/__tests__/planning.service.test.ts`, `tests/security/authorization.test.ts`, and many root-level API tests.
-
-**Location:**
-- Most fixtures are declared inline inside each spec file.
-- Shared mock modules are minimal and currently limited to helpers like `tests/mocks/nanoid.ts`.
-- Global environment setup lives in `jest.setup.js`, not in per-suite helpers.
-
-## Coverage
-
-**Requirements:** Global threshold enforced in `jest.config.js`
-- branches: 70
-- functions: 70
-- lines: 70
-- statements: 70
-
-**View Coverage:**
-```bash
-npm run test:coverage
-```
-
-## Test Types
-
-**Unit Tests:**
-- Heavy coverage exists for pure logic and feature helpers under `src/lib/**/__tests__`, `src/lib/3d/__tests__`, `src/lib/open-product/__tests__`, and `src/lib/planning/__tests__`.
-- Service unit tests mock repositories and assert business rules. Examples:
-  - `src/server/services/__tests__/planning.service.test.ts`
-  - `src/server/services/__tests__/draft-group.service.test.ts`
-  - `src/server/services/__tests__/intake.service.test.ts`
-
-**Integration Tests:**
-- Root `tests/api/*.test.ts` and some route tests exercise route/service contracts more broadly.
-- Security-oriented integration-style checks live under `tests/security/`.
-- Some API tests likely depend on test environment configuration because `.env.test` exists at repo root. Do not read secret values; only rely on the file's presence when setting up environment expectations.
-
-**E2E Tests:**
-- Playwright and Cypress config files are not detected at repo root.
-- Browser E2E framework: Not used in the current repo snapshot.
-
-## Common Patterns
-
-**Async Testing:**
-```typescript
-await waitFor(() => {
-  expect(screen.getByTestId('user-name')).toHaveTextContent('管理员')
-})
-
-await expect(
-  planningService.createDraft('workspace-1', input, user),
-).rejects.toMatchObject({
-  code: ErrorCode.VALIDATION_FAILED,
-})
-```
-- These patterns come from `src/hooks/__tests__/useAuth.test.tsx` and `src/server/services/__tests__/planning.service.test.ts`.
-
-**Error Testing:**
-```typescript
-const response = await PUT(
-  {
-    json: async () => ({
-      resultSummary: { estimatedCost: 12 },
-      items: [],
-    }),
-  } as any,
-  { params: Promise.resolve({ id: 'pre-sku-1' }) },
-)
-
-expect(mockSavePackagingPlan).not.toHaveBeenCalled()
-expect(response).toEqual(
-  expect.objectContaining({
-    success: false,
-    status: 400,
-  }),
-)
-```
-- This route-validation pattern comes from `src/app/api/pre-skus/[id]/packaging/route.test.ts`.
-
-## Environment and Setup
-
-**Jest Environment:**
-- `testEnvironment` is `jsdom` in `jest.config.js`, even for many server-focused tests.
-- `setupFilesAfterEnv` points to `jest.setup.js`.
-
-**Global Setup in `jest.setup.js`:**
-- Loads `@testing-library/jest-dom`
-- Polyfills `TextEncoder` and `TextDecoder`
-- Polyfills `setImmediate` for Prisma-related code
-- Defines fallback `Request` and `Response` implementations for Next.js server code
-- Mocks `IntersectionObserver`, `ResizeObserver`, `window.matchMedia`, `CSS.supports`, and `performance.now`
-
-**Ignored Paths:**
-- Jest ignores `.next`, `output`, and `temp` via `modulePathIgnorePatterns` and `watchPathIgnorePatterns` in `jest.config.js`.
-- ESLint ignores test files, so rely on test review and actual execution rather than lint for test quality.
-
-## Prescriptive Patterns To Follow
-
-- Put narrow unit tests next to the code in `__tests__` when the module is owned by a specific slice under `src`.
-- Put cross-cutting, regression, security, or workflow tests under the root `tests/` tree.
-- For a new service test, mock repositories and other downstream collaborators; assert the business rule and returned DTO shape.
-- For a new route test, mock `handleRequest`, response helpers, and the service entrypoint instead of booting the entire app.
-- For a new component or hook test, use React Testing Library with `render`, `screen`, and `waitFor`; prefer behavior assertions over snapshot tests. Snapshot usage is not detected in the current repo.
-- Keep test names in Chinese and aligned with actual user-observable behavior or explicit business rule outcomes.
-
----
-
-*Testing analysis: 2026-04-02*

furniture-3d-system/.planning/config.json

@@ -1,28 +0,0 @@
-{
-  "mode": "yolo",
-  "granularity": "standard",
-  "parallelization": {
-    "enabled": true
-  },
-  "planning": {
-    "commit_docs": true,
-    "search_gitignored": false
-  },
-  "model_profile": "balanced",
-  "workflow": {
-    "research": true,
-    "plan_check": true,
-    "verifier": true,
-    "nyquist_validation": true,
-    "auto_advance": false,
-    "research_before_questions": false,
-    "discuss_mode": "assumptions",
-    "skip_discuss": false,
-    "text_mode": false
-  },
-  "git": {
-    "branching_strategy": "none",
-    "phase_branch_template": "gsd/phase-{phase}-{slug}",
-    "milestone_branch_template": "gsd/{milestone}-{slug}"
-  }
-}

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-01-PLAN.md

@@ -1,139 +0,0 @@
----
-phase: 01-协作入口与项目记忆稳定化
-plan: 01
-type: execute
-wave: 1
-depends_on: []
-files_modified:
-  - AGENTS.md
-  - docs/workflow/团队协作模式.md
-  - docs/workflow/模块边界说明.md
-  - docs/workflow/主线同步操作手册.md
-autonomous: true
-requirements:
-  - COLL-01
-  - COLL-02
-must_haves:
-  truths:
-    - "新协作者进入 furniture-3d-system 后，能从固定入口读到统一的分支命名与同步规则。"
-    - "AI 会话不会再把协作规则散读成多个互相矛盾的口径。"
-    - "包装长期分支和临时任务分支的 merge/rebase 规则可以直接从文档验证。"
-  artifacts:
-    - path: "AGENTS.md"
-      provides: "仓库级固定入口与强制阅读说明"
-      contains: "团队协作固定入口"
-    - path: "docs/workflow/团队协作模式.md"
-      provides: "角色分工、分支命名、收口规则"
-      contains: "codex/xuxiake-packaging"
-    - path: "docs/workflow/模块边界说明.md"
-      provides: "主链、包装线、兼容链和共享接缝边界"
-      contains: "共享层边界"
-    - path: "docs/workflow/主线同步操作手册.md"
-      provides: "长期分支 merge 与临时分支 rebase 的同步口径"
-      contains: "git merge main"
-  key_links:
-    - from: "AGENTS.md"
-      to: "docs/workflow/团队协作模式.md"
-      via: "进入 furniture-3d-system 前置阅读"
-      pattern: "团队协作模式"
-    - from: "docs/workflow/团队协作模式.md"
-      to: "docs/workflow/主线同步操作手册.md"
-      via: "同步规则引用"
-      pattern: "主线同步操作手册"
-    - from: "docs/workflow/模块边界说明.md"
-      to: "docs/workflow/团队协作模式.md"
-      via: "角色边界与工作域映射"
-      pattern: "团队协作模式"
----
-
-<objective>
-固化 `furniture-3d-system` 的协作入口与分支口径，让新协作者和新 AI 会话都从同一组文档进入项目。
-
-Purpose: 落地 D-01、D-02、D-03、D-04，消除“入口分散、口径不一致、分支职责含糊”的协作恢复成本。
-Output: 对齐后的仓库级入口说明与三份协作文档。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-@AGENTS.md
-@docs/workflow/团队协作模式.md
-@docs/workflow/模块边界说明.md
-@docs/workflow/主线同步操作手册.md
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: 对齐仓库级入口与协作主文档</name>
-  <files>AGENTS.md, docs/workflow/团队协作模式.md</files>
-  <read_first>
-    AGENTS.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-    .planning/ROADMAP.md
-    docs/workflow/团队协作模式.md
-    docs/workflow/模块边界说明.md
-    docs/workflow/主线同步操作手册.md
-  </read_first>
-  <acceptance_criteria>
-    - `AGENTS.md` 明确把 `docs/workflow/团队协作模式.md`、`docs/workflow/模块边界说明.md`、`docs/workflow/主线同步操作手册.md` 作为进入 `furniture-3d-system/` 的固定入口，符合 D-01、D-02。
-    - `docs/workflow/团队协作模式.md` 保留并强化 `codex/&lt;负责人&gt;-&lt;工作域&gt;` 和 `codex/&lt;负责人&gt;-&lt;工作域&gt;-&lt;任务简称&gt;` 规则，符合 D-03。
-    - 文档中明确 `main` 只由 `WuYongJie` 收口、`codex/xuxiake-packaging` 为包装长期分支，符合 D-04。
-  </acceptance_criteria>
-  <action>按 D-01 至 D-04 统一仓库级入口和主协作文档文案：去掉容易让人误解成“还有第二套入口”的表述；把固定入口、固定分支命名、主线收口责任、包装长期分支命名写成可以直接复制执行的规则；不要新增平级入口文档，也不要把业务主链规划塞进本任务。</action>
-  <verify>
-    <automated>rg -n "团队协作模式|模块边界说明|主线同步操作手册|codex/<负责人>-<工作域>|codex/xuxiake-packaging|WuYongJie" AGENTS.md docs/workflow/团队协作模式.md</automated>
-  </verify>
-  <done>仓库级入口与主协作文档没有互相打架的口径，新协作者只读这两层就能知道从哪里开始、谁收口、分支怎么命名。</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 补齐边界文档与同步手册的可执行约束</name>
-  <files>docs/workflow/模块边界说明.md, docs/workflow/主线同步操作手册.md</files>
-  <read_first>
-    docs/workflow/模块边界说明.md
-    docs/workflow/主线同步操作手册.md
-    docs/workflow/团队协作模式.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-    AGENTS.md
-  </read_first>
-  <acceptance_criteria>
-    - `docs/workflow/模块边界说明.md` 能直接看出新平台主链、包装线、旧兼容链、共享接缝和禁止直改区。
-    - `docs/workflow/主线同步操作手册.md` 明确长期共享分支使用 `merge main`、临时个人任务分支使用 `rebase main`，并与 `团队协作模式.md` 保持一致。
-    - 两份文档都不引入新的职责划分或新的协作入口，符合 D-07、D-08。
-  </acceptance_criteria>
-  <action>把边界文档和同步手册修整成执行型约束：让协作者可以直接判断哪些目录可改、哪些共享接缝必须先对齐；让长期分支与临时分支的同步方式不再靠口头解释；禁止顺手扩写到 `draft-group`、`intake`、`schema.prisma` 等敏感接缝的实现改动，符合 D-07、D-08。</action>
-  <verify>
-    <automated>rg -n "共享接缝|不要乱碰|merge main|rebase main|codex/xuxiake-packaging" docs/workflow/模块边界说明.md docs/workflow/主线同步操作手册.md docs/workflow/团队协作模式.md</automated>
-  </verify>
-  <done>模块边界和主线同步口径可直接执行，包装线和主线负责人不会再因为“能不能改、该怎么同步”去补口头说明。</done>
-</task>
-
-</tasks>
-
-<verification>
-执行后运行文档关键词校验，确认固定入口、分支命名、长期分支 merge、临时分支 rebase、共享接缝边界都能被命令直接检出。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`COLL-01` 与 `COLL-02` 的协作入口部分可从 `AGENTS.md` 和三份 workflow 文档直接恢复；新会话不看聊天记录，也能找到入口、边界和同步规则。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/01-协作入口与项目记忆稳定化/01-01-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-01-SUMMARY.md

@@ -1,49 +0,0 @@
-# Phase 01 Plan 01 Summary
-
-## 结果
-
-本次执行把 `furniture-3d-system` 的第一层协作入口收口到同一组文档：`AGENTS.md` 负责声明固定入口，`团队协作模式.md` 负责固定分工和分支命名，`模块边界说明.md` 负责固定主链/包装线/兼容链与共享接缝边界，`主线同步操作手册.md` 负责固定长期分支 `merge main`、临时任务分支 `rebase main` 的同步口径。
-
-这次没有新增第二套入口，也没有把阶段范围扩到业务实现。重点是把新会话和新协作者进入项目时最容易散掉的规则，改成可以直接读、直接照做、彼此不打架的文案。
-
-## 改动文件
-
-- `D:\AI Code\3danzhuang\AGENTS.md`
-- `D:\AI Code\3danzhuang\furniture-3d-system\docs\workflow\团队协作模式.md`
-- `D:\AI Code\3danzhuang\furniture-3d-system\docs\workflow\模块边界说明.md`
-- `D:\AI Code\3danzhuang\furniture-3d-system\docs\workflow\主线同步操作手册.md`
-
-## 验证
-
-已执行：
-
-```powershell
-rg -n "团队协作模式|模块边界说明|主线同步操作手册|codex/<负责人>-<工作域>|codex/xuxiake-packaging|WuYongJie" "D:\AI Code\3danzhuang\AGENTS.md" "D:\AI Code\3danzhuang\furniture-3d-system\docs\workflow\团队协作模式.md"
-```
-
-结果：命中固定入口、统一分支命名、`WuYongJie` 主线收口、`codex/xuxiake-packaging` 长期包装分支等关键词。
-
-已执行：
-
-```powershell
-rg -n "共享接缝|不要乱碰|merge main|rebase main|codex/xuxiake-packaging" "D:\AI Code\3danzhuang\furniture-3d-system\docs\workflow\模块边界说明.md" "D:\AI Code\3danzhuang\furniture-3d-system\docs\workflow\主线同步操作手册.md" "D:\AI Code\3danzhuang\furniture-3d-system\docs\workflow\团队协作模式.md"
-```
-
-结果：命中共享接缝边界、长期分支 `merge main`、临时任务分支 `rebase main`、固定包装分支等关键词。
-
-## 规范审查
-
-- 结论：`passed`
-- 审查范围：架构、视觉、根因修复
-- 标注：这是自审，不是独立复审
-
-说明：
-
-- 架构：本次仅调整协作文档入口和执行口径，没有引入新的架构分层冲突，也没有扩写到业务实现层。
-- 视觉：本次未修改 UI 或视觉实现，不存在偏离统一视觉标准的问题。
-- 根因修复：本次针对“入口分散、口径不一致、同步方式靠口头解释”这个根因做收口，不是靠临时说明或聊天补丁维持。
-
-## 风险
-
-- 本次只完成 Phase 01 Plan 01 的文档收口，没有覆盖 `.planning` 恢复层的后续计划内容。
-- 按用户要求未执行 `commit`，因此本次结果只体现在工作区文件变更中。

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-02-PLAN.md

@@ -1,143 +0,0 @@
----
-phase: 01-协作入口与项目记忆稳定化
-plan: 02
-type: execute
-wave: 1
-depends_on: []
-files_modified:
-  - .planning/PROJECT.md
-  - .planning/REQUIREMENTS.md
-  - .planning/ROADMAP.md
-  - .planning/STATE.md
-autonomous: true
-requirements:
-  - COLL-02
-  - ARCH-04
-must_haves:
-  truths:
-    - "新 AI 会话只读 `.planning` 就能恢复当前阶段、下一步和主要风险。"
-    - "Phase 1 的目标、需求、成功标准和当前状态在 `.planning` 内部没有相互矛盾。"
-    - "项目记忆不会再分散到零散说明文档里，`STATE.md` 保持唯一快速恢复入口。"
-  artifacts:
-    - path: ".planning/STATE.md"
-      provides: "当前阶段、下一步、风险的快速恢复入口"
-      contains: "Current focus"
-    - path: ".planning/ROADMAP.md"
-      provides: "Phase 目标、依赖、成功标准和计划清单"
-      contains: "Phase 1: 协作入口与项目记忆稳定化"
-    - path: ".planning/REQUIREMENTS.md"
-      provides: "需求追踪与阶段映射"
-      contains: "ARCH-04"
-    - path: ".planning/PROJECT.md"
-      provides: "项目核心价值、上下文和关键决策"
-      contains: "GSD 作为项目外置记忆"
-  key_links:
-    - from: ".planning/STATE.md"
-      to: ".planning/ROADMAP.md"
-      via: "当前阶段与下一步映射"
-      pattern: "Phase 1 - 协作入口与项目记忆稳定化"
-    - from: ".planning/ROADMAP.md"
-      to: ".planning/REQUIREMENTS.md"
-      via: "Requirement ID 覆盖"
-      pattern: "COLL-01, COLL-02, ARCH-04"
-    - from: ".planning/PROJECT.md"
-      to: ".planning/STATE.md"
-      via: "项目核心价值与当前焦点对齐"
-      pattern: "Current focus"
----
-
-<objective>
-把 `.planning` 固化成 Phase 1 的唯一项目记忆恢复层，让新会话可以不依赖聊天记录恢复上下文。
-
-Purpose: 落地 D-05、D-06，并把 `COLL-02` 与 `ARCH-04` 需要的恢复链条固定到 `.planning` 内部。
-Output: 对齐后的 `PROJECT / REQUIREMENTS / ROADMAP / STATE` 四层项目记忆。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/REQUIREMENTS.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-@AGENTS.md
-@docs/workflow/团队协作模式.md
-@docs/workflow/模块边界说明.md
-@docs/workflow/主线同步操作手册.md
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: 收紧 STATE 快速恢复入口并清理重复状态</name>
-  <files>.planning/STATE.md, .planning/PROJECT.md</files>
-  <read_first>
-    .planning/STATE.md
-    .planning/PROJECT.md
-    .planning/ROADMAP.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-    AGENTS.md
-    docs/workflow/团队协作模式.md
-    docs/workflow/模块边界说明.md
-    docs/workflow/主线同步操作手册.md
-  </read_first>
-  <acceptance_criteria>
-    - `.planning/STATE.md` 明确保留当前阶段、当前 focus、下一步和风险，符合 D-05。
-    - `.planning/PROJECT.md` 只保留项目级长期背景与关键决策，不复制 `STATE.md` 的运行态状态，符合 D-06。
-    - 两个文件都不新增 `.planning` 之外的状态入口。
-  </acceptance_criteria>
-  <action>按 D-05、D-06 重新梳理 `STATE.md` 和 `PROJECT.md` 的职责：`STATE.md` 只做快速恢复入口，写清当前阶段、下一步、风险和恢复文件；`PROJECT.md` 只保留长期项目定义、约束和关键决策。删除会导致状态分散的重复段落，但不要引入新的记忆文档或把 Phase 2 之后的内容提前塞进来。</action>
-  <verify>
-    <automated>rg -n "Current focus|Phase: 1 of 5|Blockers/Concerns|GSD 作为项目外置记忆|Key Decisions" .planning/STATE.md .planning/PROJECT.md</automated>
-  </verify>
-  <done>新会话先打开 `STATE.md` 就能知道现在在哪一阶段、接下来做什么、有哪些风险；`PROJECT.md` 不再和 `STATE.md` 抢角色。</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 对齐路线图与需求追踪的 Phase 1 记忆闭环</name>
-  <files>.planning/ROADMAP.md, .planning/REQUIREMENTS.md</files>
-  <read_first>
-    .planning/ROADMAP.md
-    .planning/REQUIREMENTS.md
-    .planning/STATE.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-    docs/workflow/团队协作模式.md
-    docs/workflow/模块边界说明.md
-    docs/workflow/主线同步操作手册.md
-  </read_first>
-  <acceptance_criteria>
-    - `.planning/ROADMAP.md` 中 Phase 1 的目标、成功标准、计划数量和计划清单与实际 `PLAN.md` 文件一致。
-    - `.planning/REQUIREMENTS.md` 里 `COLL-01`、`COLL-02`、`ARCH-04` 仍明确映射到 Phase 1，且没有漏映射。
-    - 两个文件能让后续执行器直接判断“Phase 1 做什么、为什么、做到什么算完成”。
-  </acceptance_criteria>
-  <action>把 `ROADMAP.md` 和 `REQUIREMENTS.md` 调整成可执行追踪面板：保持 Phase 1 goal、requirements、success criteria、plans list 同步；确保 `COLL-01 / COLL-02 / ARCH-04` 的映射与计划文件一致；不要新增额外阶段，也不要把未开始的业务主链任务混入 Phase 1。</action>
-  <verify>
-    <automated>rg -n "COLL-01|COLL-02|ARCH-04|Phase 1: 协作入口与项目记忆稳定化|01-01-PLAN.md|01-02-PLAN.md" .planning/ROADMAP.md .planning/REQUIREMENTS.md</automated>
-  </verify>
-  <done>`.planning` 内部对 Phase 1 的目标、需求、成功标准、计划清单和当前状态形成单一闭环，执行阶段不需要再靠聊天记录补全上下文。</done>
-</task>
-
-</tasks>
-
-<verification>
-执行后分别用关键词校验 `STATE / PROJECT / ROADMAP / REQUIREMENTS`，确认快速恢复入口、需求映射、Phase 1 成功标准和计划清单一致。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`ARCH-04` 达成：新 AI 会话只读 `.planning/STATE.md` 再按需下钻 `PROJECT / ROADMAP / REQUIREMENTS`，即可恢复项目上下文；`COLL-02` 的 `.planning` 部分同步达成。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/01-协作入口与项目记忆稳定化/01-02-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-02-SUMMARY.md

@@ -1,38 +0,0 @@
-# Phase 01 Plan 02: 项目记忆恢复层与需求追踪闭环 Summary
-
-## Outcome
-
-把 `.planning` 收紧成 Phase 1 的单一恢复链：`STATE.md` 只保留当前阶段、下一步、风险与恢复路径；`PROJECT.md` 只保留长期项目定义、约束和关键决策；`ROADMAP.md` 与 `REQUIREMENTS.md` 对齐 Phase 1 的计划清单、需求映射和执行状态。
-
-## Files Updated
-
-- `.planning/STATE.md`
-- `.planning/PROJECT.md`
-- `.planning/ROADMAP.md`
-- `.planning/REQUIREMENTS.md`
-
-## Verification
-
-- `rg -n "Current focus|Phase 1 of 5|Risks|Recovery Path|GSD 作为项目外置记忆|Key Decisions" .planning/STATE.md .planning/PROJECT.md`
-- `rg -n "COLL-01|COLL-02|ARCH-04|Phase 1: 协作入口与项目记忆稳定化|01-01-PLAN.md|01-02-PLAN.md" .planning/ROADMAP.md .planning/REQUIREMENTS.md`
-- 人工核对：`STATE -> ROADMAP / REQUIREMENTS / PROJECT` 的引用职责没有重复、没有把运行态状态散落回其他文档
-
-## Deviations from Plan
-
-None - 本次只在计划允许的 `.planning` 文件范围内收口，没有扩写到代码或协作文档正文。
-
-## Risks
-
-- Phase 1 还没整体结束，`01-01-PLAN.md` 仍需完成，协作入口规则才能与 `.planning` 记忆层一起闭环。
-- 当前结论基于你限定的写入范围，没有去改动其他 executor 正在负责的文件。
-
-## 规范审查结论
-
-- 结论：`passed`
-- 审查范围：架构、视觉、根因修复
-- 说明：本次只调整 `.planning` 记忆层职责，没有破坏代码架构，也没有引入视觉改动；根因修复点是“项目状态分散、恢复入口不唯一”，不是做表面补丁。
-- 标注：这是自审，不是独立复审
-
-## Self-Check
-
-PASSED

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-03-PLAN.md

@@ -1,140 +0,0 @@
----
-phase: 01-协作入口与项目记忆稳定化
-plan: 03
-type: execute
-wave: 2
-depends_on:
-  - 01-01
-  - 01-02
-files_modified:
-  - .planning/ROADMAP.md
-  - .planning/STATE.md
-  - .planning/REQUIREMENTS.md
-autonomous: true
-gap_closure: true
-requirements:
-  - COLL-01
-  - COLL-02
-  - ARCH-04
-must_haves:
-  truths:
-    - "`.planning` 内部对 Phase 1 的完成状态只有一个结论：01-01 和 01-02 已完成，Phase 1 已闭环。"
-    - "新会话打开 `STATE.md` 时，能直接看到 Phase 1 已完成以及下一步应转入 Phase 2。"
-    - "`COLL-01`、`COLL-02`、`ARCH-04` 的追踪状态与 Phase 1 实际产物一致，不再停留在过期状态。"
-  artifacts:
-    - path: ".planning/ROADMAP.md"
-      provides: "Phase 1 计划清单、进度表和阶段完成状态"
-      contains: "01-01-PLAN.md"
-    - path: ".planning/STATE.md"
-      provides: "最新完成计划、阶段状态和下一步"
-      contains: "Latest completed plan"
-    - path: ".planning/REQUIREMENTS.md"
-      provides: "Phase 1 requirement traceability status"
-      contains: "COLL-01"
-  key_links:
-    - from: ".planning/phases/01-协作入口与项目记忆稳定化/01-01-SUMMARY.md"
-      to: ".planning/ROADMAP.md"
-      via: "完成产物回写计划状态"
-      pattern: "01-01-PLAN.md"
-    - from: ".planning/phases/01-协作入口与项目记忆稳定化/01-02-SUMMARY.md"
-      to: ".planning/STATE.md"
-      via: "最新完成计划与阶段状态同步"
-      pattern: "01-02-PLAN.md"
-    - from: ".planning/ROADMAP.md"
-      to: ".planning/REQUIREMENTS.md"
-      via: "Phase 1 完成状态驱动 requirement status"
-      pattern: "COLL-01|COLL-02|ARCH-04"
----
-
-<objective>
-只修复 Phase 1 在 `.planning` 内部的状态冲突，把已完成的 01-01、01-02 结果同步回路线图、状态页和需求追踪。
-
-Purpose: 解决 `01-VERIFICATION.md` 指出的唯一 blocker，让 `.planning` 再次成为可信的项目恢复入口，符合 D-05、D-06，并收口 COLL-01、COLL-02、ARCH-04。
-Output: 同步后的 `.planning/ROADMAP.md`、`.planning/STATE.md`、`.planning/REQUIREMENTS.md`，以及本次 gap closure 的执行总结预期。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/STATE.md
-@.planning/ROADMAP.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-@.planning/phases/01-协作入口与项目记忆稳定化/01-VERIFICATION.md
-@.planning/phases/01-协作入口与项目记忆稳定化/01-01-SUMMARY.md
-@.planning/phases/01-协作入口与项目记忆稳定化/01-02-SUMMARY.md
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: 回写 Phase 1 计划与状态页的真实完成状态</name>
-  <files>.planning/ROADMAP.md, .planning/STATE.md</files>
-  <read_first>
-    .planning/phases/01-协作入口与项目记忆稳定化/01-VERIFICATION.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-01-SUMMARY.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-02-SUMMARY.md
-    .planning/ROADMAP.md
-    .planning/STATE.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-  </read_first>
-  <acceptance_criteria>
-    - `.planning/ROADMAP.md` 把 `01-01-PLAN.md`、`01-02-PLAN.md` 都标记为已完成，`Plans` 数量与实际一致，Phase 1 和进度表状态同步收口。
-    - `.planning/STATE.md` 的 `Latest completed plan`、`Phase status`、`Last activity`、`Next Step` 与“Phase 1 已完成、下一步进入 Phase 2”一致。
-    - 文案只做状态同步，不补写 Phase 2 业务内容，不改 `.planning` 之外任何文件，符合 D-07。
-  </acceptance_criteria>
-  <action>依据 `01-VERIFICATION.md` 的 gap 和 `01-01/01-02-SUMMARY.md` 的真实完成结果，统一回写 `ROADMAP.md` 与 `STATE.md`。明确 01-01、01-02 已完成；如果 Phase 1 的所有计划都已完成，就把 Phase 1 标记为 complete，并把进度表、完成记录、下一步一起改成 Phase 2 启动前的状态。不要新造计划，不要保留“仍需等待 01-01”的旧结论。</action>
-  <verify>
-    <automated>rg -n "01-01-PLAN.md|01-02-PLAN.md|Phase 1: 协作入口与项目记忆稳定化|Phase status|Latest completed plan|Next Step|Phase 2" .planning/ROADMAP.md .planning/STATE.md</automated>
-  </verify>
-  <done>路线图和状态页不再把 Phase 1 同时写成“已完成”和“进行中”，新会话从 `STATE.md` 出发会得到正确的下一步。</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 对齐 Phase 1 需求追踪并定义本次 gap closure 总结输出</name>
-  <files>.planning/REQUIREMENTS.md</files>
-  <read_first>
-    .planning/REQUIREMENTS.md
-    .planning/ROADMAP.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-VERIFICATION.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-01-SUMMARY.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-02-SUMMARY.md
-    .planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md
-  </read_first>
-  <acceptance_criteria>
-    - `COLL-01`、`COLL-02`、`ARCH-04` 的 `Traceability` 状态与 Phase 1 完成状态一致，不再出现 Pending / In progress 的过期状态。
-    - `Phase 1 Coverage` 与 `Traceability` 对 01-01、01-02 的描述一致，能解释每个 requirement 是由哪些已完成计划收口。
-    - 执行总结要求明确：本次 gap closure 完成后生成 `01-03-SUMMARY.md`，说明同步了哪些状态和为什么能关闭 verification gap。
-  </acceptance_criteria>
-  <action>把 `REQUIREMENTS.md` 回写成已完成后的真实状态：`COLL-01` 对应 01-01，`COLL-02` 由 01-01 和 01-02 共同完成，`ARCH-04` 由 01-02 完成，并让状态与 Task 1 回写后的 Phase 1 结论保持一致。只同步 Phase 1 这三个 requirement，不顺手改其他阶段需求。执行完成后的总结里要专门记录“本次只做 `.planning` 状态同步，已关闭 01-VERIFICATION 的唯一 gap”。</action>
-  <verify>
-    <automated>rg -n "COLL-01|COLL-02|ARCH-04|Implemented|Completed|01-01-PLAN.md|01-02-PLAN.md|Phase 1" .planning/REQUIREMENTS.md</automated>
-  </verify>
-  <done>需求追踪不再滞后于真实执行结果，执行器也知道需要用 `01-03-SUMMARY.md` 记录本次 gap closure 的关闭依据。</done>
-</task>
-
-</tasks>
-
-<verification>
-先对照 `01-VERIFICATION.md` 的 gap 列表逐项核对，再运行两条 `rg` 命令确认：
-1. `ROADMAP.md`、`STATE.md` 已统一反映 Phase 1 完成和 Phase 2 为下一步。
-2. `REQUIREMENTS.md` 已把 `COLL-01`、`COLL-02`、`ARCH-04` 更新到与 Phase 1 一致的状态。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`01-VERIFICATION.md` 中关于 “Phase 1 的目标、需求、成功标准和当前状态在 .planning 内部没有相互矛盾” 的失败项可以被关闭；新会话只看 `.planning` 就会得到一致结论：Phase 1 已完成，下一步进入 Phase 2。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/01-协作入口与项目记忆稳定化/01-03-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-03-SUMMARY.md

@@ -1,41 +0,0 @@
-# Phase 01 Plan 03: `.planning` 状态同步与 verification gap closure Summary
-
-## Outcome
-
-本次执行只做 `.planning` 内部状态同步，没有扩到业务代码或协作文档正文。核心结果是把 `ROADMAP.md`、`STATE.md`、`REQUIREMENTS.md` 全部回写到同一个结论：`01-01` 和 `01-02` 已完成，Phase 1 已闭环，下一步进入 Phase 2。
-
-这次修掉的是 `01-VERIFICATION.md` 指出的唯一 blocker，也就是 `.planning` 内部还保留了“Phase 1 进行中”和“01-01 未完成”的过期状态，导致新会话无法从 `.planning` 得到唯一可信的恢复结论。
-
-## Files Updated
-
-- `.planning/ROADMAP.md`
-- `.planning/STATE.md`
-- `.planning/REQUIREMENTS.md`
-
-## Verification
-
-- `rg -n "01-01-PLAN.md|01-02-PLAN.md|Status|Complete|2/2|Phase 1" .planning/ROADMAP.md`
-- `rg -n "Current focus|Current phase|Latest completed plan|Phase status|Next Step|Phase 2" .planning/STATE.md`
-- `rg -n "COLL-01|COLL-02|ARCH-04|Completed by" .planning/REQUIREMENTS.md`
-
-结果：Phase 1 的计划完成状态、恢复入口和 requirement traceability 已统一，不再出现 `Pending`、`In progress` 与已存在 Summary 冲突的情况。
-
-## Deviations from Plan
-
-None - 本次严格只同步 `.planning` 三个状态文件，并按计划补写执行总结，没有扩大范围。
-
-## Risks
-
-- 本次只关闭了 Phase 1 的状态矛盾，不等于 Phase 2 已经开始实现。
-- 当前结论依赖 `.planning` 继续被当成唯一恢复入口；如果后续又把运行态结论写回其他零散文档，会再次造成记忆分叉。
-
-## 规范审查结论
-
-- 结论：`passed`
-- 审查范围：架构、视觉、根因修复
-- 说明：本次只同步 `.planning` 状态，不涉及业务架构和 UI；修的是状态真相不一致这个根因，不是补丁式遮盖。
-- 标注：这是自审，不是独立复审
-
-## Self-Check
-
-PASSED

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-CONTEXT.md

@@ -1,104 +0,0 @@
-# Phase 1: 协作入口与项目记忆稳定化 - Context
-
-**Gathered:** 2026-04-02 (assumptions mode)
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-固定当前项目的协作入口、分支与收口规则、以及 GSD 项目级记忆恢复入口，让新会话和协作者进入项目时可以按同一套规则接入主链，而不是继续依赖口头说明恢复上下文。本阶段不重做业务主链，也不扩展包装或入库能力。
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### 协作入口
-- **D-01:** 新会话和协作者的统一入口固定为 `.planning`、`docs/workflow` 和外层 `AGENTS.md`，不新增第二套并行入口。
-- **D-02:** `docs/workflow/团队协作模式.md`、`docs/workflow/模块边界说明.md`、`docs/workflow/主线同步操作手册.md` 作为进入 `furniture-3d-system/` 的第一层协作文档入口。
-
-### 分支与收口规则
-- **D-03:** 分支命名和主线收口规则视为锁定约束，继续沿用 `codex/<负责人>-<工作域>` 与 `codex/<负责人>-<工作域>-<任务简称>`。
-- **D-04:** `main` 只由 `WuYongJie` 收口，`codex/xuxiake-packaging` 作为包装长期分支保留，长期共享分支同步 `main` 用 `merge`，临时个人任务分支才用 `rebase`。
-
-### 项目记忆恢复
-- **D-05:** `.planning/STATE.md` 作为“当前阶段、下一步、风险”的唯一快速恢复入口，`PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 作为补充层。
-- **D-06:** GSD 项目记忆更新以阶段文件和 `.planning` 结构为主，不把状态分散到零散说明文档里。
-
-### 阶段边界
-- **D-07:** Phase 1 只固定协作边界和记忆边界，不趁机重做业务主链结构。
-- **D-08:** 现有主链和共享接缝在本阶段只做明确标注、引用和恢复入口固化，不提前改 `draft-group`、`intake`、`schema.prisma` 等敏感接缝。
-
-### the agent's Discretion
-本阶段中 GSD 文件的具体组织方式、说明文案细化顺序、以及后续 plan 的任务切分粒度，由 agent 在不突破以上边界的前提下决定。
-
-</decisions>
-
-<canonical_refs>
-## Canonical References
-
-**Downstream agents MUST read these before planning or implementing.**
-
-### 项目级记忆与路线
-- `.planning/PROJECT.md` — 项目目标、核心价值、约束、关键决策
-- `.planning/REQUIREMENTS.md` — Phase 1 对应的 `COLL-01`、`COLL-02`、`ARCH-04`
-- `.planning/ROADMAP.md` — Phase 1 的目标、依赖和成功标准
-- `.planning/STATE.md` — 当前项目状态恢复入口
-
-### 协作文档
-- `docs/workflow/团队协作模式.md` — 固定分工、分支规则、同步与收口流程
-- `docs/workflow/模块边界说明.md` — 新平台主链、包装线、旧兼容链、共享接缝边界
-- `docs/workflow/主线同步操作手册.md` — 长期分支 merge / 临时分支 rebase 的执行口径
-
-### 全局规则
-- `../AGENTS.md` — 全仓库级协作规则和进入项目的默认入口要求
-
-### 代码库结构参考
-- `.planning/codebase/STRUCTURE.md` — 目录组织和关键文件位置
-- `.planning/codebase/CONVENTIONS.md` — 约定、命名和结构模式
-- `.planning/codebase/STACK.md` — 当前技术栈和环境边界
-
-</canonical_refs>
-
-<code_context>
-## Existing Code Insights
-
-### Reusable Assets
-- `.planning/PROJECT.md`、`.planning/REQUIREMENTS.md`、`.planning/ROADMAP.md`、`.planning/STATE.md` 已经形成 GSD 的第一层项目记忆，可直接作为后续 plan 和 execute 的输入。
-- `docs/workflow/团队协作模式.md`、`docs/workflow/模块边界说明.md`、`docs/workflow/主线同步操作手册.md` 已经覆盖协作规则、模块边界和同步口径，不需要从头再造。
-- 根目录 `AGENTS.md` 已经把“进入 `furniture-3d-system/` 先读哪些文档”的规则写成全局入口。
-
-### Established Patterns
-- 当前项目已经形成“主线负责人收口、包装线协作、旧 CAD 兼容链保留”的组织模式。
-- 当前仓库的工程结构仍以 `Route -> Service -> Repository -> Prisma` 为后端主模式，本阶段不需要动到这条结构线。
-- 当前 GSD 配置是 `yolo + assumptions + parallelization enabled`，适合在少打断的前提下继续往下推进。
-
-### Integration Points
-- 后续 plan 需要围绕 `.planning`、`docs/workflow`、根级 `AGENTS.md` 三层入口做固化和必要修订。
-- 如果后续需要把项目恢复入口暴露给新会话，关键接点就在 `.planning/STATE.md` 与 `AGENTS.md` 的引用关系。
-- Phase 2 之后的业务推进，需要继承本阶段确认的协作规则和记忆入口，而不是重新定义。
-
-</code_context>
-
-<specifics>
-## Specific Ideas
-
-- 这个项目要“完全按 GSD-first 走”，不是继续用原生 Codex 的直推式节奏再顺便兼容 `.planning`。
-- 当前体验目标不是重做业务，而是先让 GSD 真正成为项目推进的主工作流。
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-- 资产中心到草稿组的业务继续收口 —— 属于 Phase 2
-- 包装方案与共享接缝的稳定化 —— 属于 Phase 3
-- 正式入库与轻仓库闭环 —— 属于 Phase 4
-- 核心服务继续拆分收口 —— 属于 Phase 5
-
-</deferred>
-
----
-
-*Phase: 01-协作入口与项目记忆稳定化*
-*Context gathered: 2026-04-02*

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-DISCUSSION-LOG.md

@@ -1,36 +0,0 @@
-# Phase 1: 协作入口与项目记忆稳定化 - Discussion Log (Assumptions Mode)
-
-> **Audit trail only.** Do not use as input to planning, research, or execution agents.
-> Decisions captured in CONTEXT.md — this log preserves the analysis.
-
-**Date:** 2026-04-02
-**Phase:** 01-协作入口与项目记忆稳定化
-**Mode:** assumptions
-**Areas analyzed:** 协作入口形态, 分支与收口规则, 项目记忆的唯一恢复源, Phase 1 的边界重点
-
-## Assumptions Presented
-
-### 协作入口形态
-| Assumption | Confidence | Evidence |
-|------------|-----------|----------|
-| Phase 1 应该把统一入口固定为 `.planning` + `docs/workflow` + 外层 `AGENTS.md`，而不是再新增一套分散入口或依赖代码内注释。 | Confident | `D:\AI Code\3danzhuang\AGENTS.md`, `.planning/ROADMAP.md`, `.planning/STATE.md`, `.planning/PROJECT.md` |
-
-### 分支与收口规则
-| Assumption | Confidence | Evidence |
-|------------|-----------|----------|
-| Phase 1 需要把分支命名和主线收口规则视为锁定约束，不再把泛分支名或“谁都能直接并 main”当可选做法。 | Confident | `docs/workflow/团队协作模式.md`, `docs/workflow/主线同步操作手册.md`, `.planning/PROJECT.md` |
-
-### 项目记忆的唯一恢复源
-| Assumption | Confidence | Evidence |
-|------------|-----------|----------|
-| `.planning/STATE.md` 应作为“当前阶段、下一步、风险”的唯一快速恢复入口，`PROJECT.md` / `REQUIREMENTS.md` / `ROADMAP.md` 作为补充层。 | Confident | `.planning/ROADMAP.md`, `.planning/STATE.md`, `.planning/PROJECT.md` |
-
-### Phase 1 的边界重点
-| Assumption | Confidence | Evidence |
-|------------|-----------|----------|
-| Phase 1 的重点是固定协作边界和记忆边界，不是趁机重做主链结构；现有主链和共享接缝只需要被明确标注和引用。 | Likely | `.planning/PROJECT.md`, `docs/workflow/模块边界说明.md`, `src/components/platform/platform-navigation.ts`, `src/server/services/draft-group.service.ts`, `src/server/services/intake.service.ts`, `prisma/schema.prisma` |
-
-## Corrections Made
-
-No corrections — all assumptions confirmed by direct GSD-first推进决策。
-

furniture-3d-system/.planning/phases/01-协作入口与项目记忆稳定化/01-VERIFICATION.md

@@ -1,108 +0,0 @@
----
-phase: 01-协作入口与项目记忆稳定化
-verified: 2026-04-02T11:59:45.1660327Z
-status: passed
-score: 6/6 must-haves verified
-re_verification:
-  previous_status: gaps_found
-  previous_score: 5/6
-  gaps_closed:
-    - "Phase 1 的目标、需求、成功标准和当前状态在 `.planning` 内部没有相互矛盾。"
-  gaps_remaining: []
-  regressions: []
----
-
-# Phase 1: 协作入口与项目记忆稳定化 Verification Report
-
-**Phase Goal:** 新会话和协作者进入项目时，能按同一套规则接入主链，不再靠口头传递恢复上下文
-**Verified:** 2026-04-02T11:59:45.1660327Z
-**Status:** passed
-**Re-verification:** Yes - after gap closure
-
-## Goal Achievement
-
-### Observable Truths
-
-| # | Truth | Status | Evidence |
-| --- | --- | --- | --- |
-| 1 | 新协作者进入 `furniture-3d-system` 后，能从固定入口读到统一的分支命名与同步规则。 | ✓ VERIFIED | 根级 `AGENTS.md` 强制先读 3 份 workflow 文档；`团队协作模式.md` 和 `主线同步操作手册.md` 明确给出分支命名、`main` 收口人和同步命令。 |
-| 2 | AI 会话不会再把协作规则读成多套互相矛盾的口径。 | ✓ VERIFIED | `AGENTS.md`、`团队协作模式.md`、`模块边界说明.md`、`主线同步操作手册.md` 对 `WuYongJie`、`codex/xuxiake-packaging`、`merge main` / `rebase main` 的表述一致。 |
-| 3 | 包装长期分支和临时任务分支的 `merge` / `rebase` 规则可以直接从文档验证。 | ✓ VERIFIED | 两份 workflow 文档都明确“长期分支 `merge main`、临时任务分支 `rebase main`”，并给出可执行命令。 |
-| 4 | 新 AI 会话只读 `.planning` 就能恢复当前阶段、下一步和主要风险。 | ✓ VERIFIED | `.planning/STATE.md` 直接给出 `Current focus`、`Current phase`、`Next Step`、`Risks`、`Recovery Path`。 |
-| 5 | Phase 1 的目标、需求、成功标准和当前状态在 `.planning` 内部没有相互矛盾。 | ✓ VERIFIED | `ROADMAP.md` 已把 Phase 1 标为 `Complete`、计划清单为 `2/2`；`STATE.md` 已写明 Phase 1 complete 并转入 Phase 2；`REQUIREMENTS.md` Traceability 已同步为 `Completed by 01-01/01-02`。 |
-| 6 | 项目记忆不会再分散到零散说明文档里，`STATE.md` 保持唯一快速恢复入口。 | ✓ VERIFIED | `PROJECT.md` 的 `Project Memory Model` 明确 `STATE.md` 是唯一快速恢复入口；`STATE.md` 的恢复路径只回链到 `ROADMAP.md`、`REQUIREMENTS.md`、`PROJECT.md`。 |
-
-**Score:** 6/6 truths verified
-
-### Required Artifacts
-
-| Artifact | Expected | Status | Details |
-| --- | --- | --- | --- |
-| `D:\AI Code\3danzhuang\AGENTS.md` | 仓库级固定入口与强制阅读说明 | ✓ VERIFIED | 明确要求进入 `furniture-3d-system/` 前先读 3 份 workflow 文档。 |
-| `docs/workflow/团队协作模式.md` | 角色分工、分支命名、收口规则 | ✓ VERIFIED | 明确角色边界、分支命名、主线收口与同步节奏。 |
-| `docs/workflow/模块边界说明.md` | 主链、包装线、兼容链和共享接缝边界 | ✓ VERIFIED | 明确敏感接缝、禁止直改区和开工前入口。 |
-| `docs/workflow/主线同步操作手册.md` | 长期分支 `merge` 与临时分支 `rebase` 口径 | ✓ VERIFIED | 明确命令、适用场景和禁用动作。 |
-| `.planning/STATE.md` | 当前阶段、下一步、风险的快速恢复入口 | ✓ VERIFIED | 结构完整，且内容已回写到 Phase 2 准备态。 |
-| `.planning/ROADMAP.md` | Phase 目标、依赖、成功标准和计划清单 | ✓ VERIFIED | Phase 1 完成状态、计划清单、执行说明与阶段目录 Summary 一致。 |
-| `.planning/REQUIREMENTS.md` | 需求追踪与阶段映射 | ✓ VERIFIED | Phase 1 coverage 和 Traceability 已与 `01-01`、`01-02`、`01-03` 的状态同步。 |
-| `.planning/PROJECT.md` | 项目核心价值、长期约束和记忆模型 | ✓ VERIFIED | 长期定义与运行态职责分离，没有重新抢 `STATE.md` 的入口职责。 |
-
-### Key Link Verification
-
-| From | To | Via | Status | Details |
-| --- | --- | --- | --- | --- |
-| `D:\AI Code\3danzhuang\AGENTS.md` | `docs/workflow/团队协作模式.md` | 进入项目前置阅读 | ✓ WIRED | 根级入口明确列出 3 份 workflow 文档。 |
-| `docs/workflow/团队协作模式.md` | `docs/workflow/主线同步操作手册.md` | 同步规则引用 | ✓ WIRED | 文档正文直接回链并展开 `merge` / `rebase` 口径。 |
-| `docs/workflow/模块边界说明.md` | `docs/workflow/团队协作模式.md` | 工作域与分支规则映射 | ✓ WIRED | 开头与“开工前最少要看什么”都要求先读团队协作模式。 |
-| `.planning/STATE.md` | `.planning/ROADMAP.md` | 当前阶段与下一步恢复路径 | ✓ WIRED | `Recovery Path` 明确要求从 `STATE.md` 下钻 `ROADMAP.md`。 |
-| `.planning/ROADMAP.md` | `.planning/REQUIREMENTS.md` | Requirement ID 覆盖 | ✓ WIRED | Phase 1 引用 `COLL-01`、`COLL-02`、`ARCH-04`，Requirements 中已有对应映射和完成状态。 |
-| `.planning/PROJECT.md` | `.planning/STATE.md` | 项目记忆模型对齐 | ✓ WIRED | `PROJECT.md` 明确声明 `STATE.md` 是唯一快速恢复入口。 |
-
-### Data-Flow Trace (Level 4)
-
-| Artifact | Data Variable | Source | Produces Real Data | Status |
-| --- | --- | --- | --- | --- |
-| Documentation phase artifacts | N/A | Static markdown | N/A | SKIPPED - 本阶段是文档与项目记忆核验，不涉及运行时数据流。 |
-
-### Behavioral Spot-Checks
-
-| Behavior | Command | Result | Status |
-| --- | --- | --- | --- |
-| 协作入口规则可被直接检出 | `rg -n "团队协作模式|模块边界说明|主线同步操作手册|codex/<负责人>-<工作域>|codex/xuxiake-packaging|WuYongJie|merge main|rebase main"` | 关键命中全部存在，入口与口径一致 | ✓ PASS |
-| `.planning` 恢复入口可被直接检出 | `rg -n "Current focus|Current phase|Latest completed plan|Phase status|Next Step|Recovery Path|COLL-01|COLL-02|ARCH-04"` | 当前阶段、风险、下一步和需求映射都能直接恢复 | ✓ PASS |
-| 旧 blocker 是否关闭 | 对比 `01-01-SUMMARY.md`、`01-02-SUMMARY.md`、`01-03-SUMMARY.md` 与 `ROADMAP.md` / `STATE.md` / `REQUIREMENTS.md` | 已不存在“Summary 说完成，但 `.planning` 说未完成”的冲突 | ✓ PASS |
-
-### Requirements Coverage
-
-| Requirement | Source Plan | Description | Status | Evidence |
-| --- | --- | --- | --- | --- |
-| `COLL-01` | `01-01-PLAN.md` | 主线负责人和包装负责人拥有固定、明确、不歧义的分支命名规则 | ✓ SATISFIED | `AGENTS.md`、`团队协作模式.md`、`主线同步操作手册.md` 已统一分支命名和主线收口规则。 |
-| `COLL-02` | `01-01-PLAN.md`, `01-02-PLAN.md` | 协作入口文档足够清晰，新的 AI 会话进入项目后能先读到正确规则 | ✓ SATISFIED | 外层入口文档和 `.planning` 恢复链已形成同一套接入路径，且状态不再冲突。 |
-| `ARCH-04` | `01-02-PLAN.md` | GSD 需要能基于 `.planning` 文件在跨对话场景下恢复项目上下文 | ✓ SATISFIED | `STATE -> ROADMAP / REQUIREMENTS / PROJECT` 恢复链存在且状态一致。 |
-
-### Anti-Patterns Found
-
-| File | Line | Pattern | Severity | Impact |
-| --- | --- | --- | --- | --- |
-| None | - | 未发现 TODO、占位文案、空实现或新的状态分叉 | - | 本次复核范围内无 blocker / warning 级反模式。 |
-
-### Human Verification Required
-
-None. 本阶段目标是文档与 `.planning` 恢复链一致性，已可通过静态检查确认。
-
-## 规范审查
-
-- 结论：`passed`
-- 标注：这是自审，不是独立复审
-- 架构：本次核验确认协作入口、模块边界和 `.planning` 记忆模型没有互相打穿，也没有新增第二套并行入口。
-- 视觉：本阶段没有 UI 改动，本次复核未发现视觉标准风险。
-- 根因修复：之前的 blocker 是 `.planning` 真相不一致；现在 `ROADMAP.md`、`STATE.md`、`REQUIREMENTS.md` 已同步到同一完成结论，属于根因收口，不是表面补丁。
-
-## Gaps Summary
-
-旧 blocker 已关闭。Phase 1 现在同时满足两件事：协作者能从固定文档入口拿到同一套主链接入规则，新会话也能只靠 `.planning` 恢复当前阶段、下一步和风险，而且这两条链路已经没有内部状态冲突。因此本阶段目标已达成，可以判定 Phase 1 complete。
-
----
-
-_Verified: 2026-04-02T11:59:45.1660327Z_
-_Verifier: Claude (gsd-verifier)_

furniture-3d-system/.planning/phases/02-资产到草稿组主链收口/02-01-PLAN.md

@@ -1,241 +0,0 @@
----
-phase: 02-资产到草稿组主链收口
-plan: 01
-type: execute
-wave: 1
-depends_on: []
-files_modified:
-  - src/lib/open-product/platform-api.ts
-  - src/server/services/asset-center.service.ts
-  - src/server/services/asset-center.service.types.ts
-  - src/server/services/__tests__/asset-center.service.test.ts
-  - src/lib/open-product/single-board-desk.ts
-  - src/server/services/combination.service.ts
-  - src/server/services/combination.service.types.ts
-  - src/app/api/platform/schemas.ts
-  - src/server/services/__tests__/combination.service.test.ts
-  - src/lib/open-product/__tests__/single-board-desk.test.ts
-autonomous: true
-requirements:
-  - MAIN-01
-  - MAIN-02
-must_haves:
-  truths:
-    - "平台负责人在资产中心可以稳定维护资产族与资产规格，并且自动组合直接消费这套维护结果。"
-    - "平台负责人在自动组合阶段看到的候选不再只是资产族摘要，而是可直接确认的实际组合关系。"
-    - "自动组合候选直接带出可驱动 3D 预览和摘要展示的数据，不必先进草稿组才第一次得到真实拼装结果。"
-    - "候选生成仍然以资产中心维护的 `AssetFamily / AssetVariant` 为数据真相，不回退到旧 `Product / SKU`。"
-  artifacts:
-    - path: "src/server/services/asset-center.service.ts"
-      provides: "资产族与规格款维护及审核后的主链服务"
-      contains: "listFamilies"
-    - path: "src/lib/open-product/platform-api.ts"
-      provides: "资产中心维护接口与自动组合消费接口"
-      contains: "createAssetFamily"
-    - path: "src/server/services/combination.service.types.ts"
-      provides: "预览就绪的自动组合候选 DTO 契约"
-      contains: "CombinationCandidateDTO"
-    - path: "src/server/services/combination.service.ts"
-      provides: "资产中心到候选列表的主链编排"
-      contains: "generateCandidates"
-    - path: "src/lib/open-product/single-board-desk.ts"
-      provides: "单板桌候选粒度与候选物化规则"
-      contains: "materializeSingleBoardDeskPreSku"
-    - path: "src/app/api/platform/schemas.ts"
-      provides: "自动组合接口输入输出所依赖的 schema 约束"
-      contains: "generateCombinationSchema"
-  key_links:
-    - from: "src/server/services/asset-center.service.ts"
-      to: "src/server/services/combination.service.ts"
-      via: "资产中心可维护结果直接供自动组合消费"
-      pattern: "AVAILABLE"
-    - from: "src/server/services/combination.service.ts"
-      to: "src/lib/open-product/single-board-desk.ts"
-      via: "候选生成后立即物化预览和摘要"
-      pattern: "materializeSingleBoardDeskPreSku"
-    - from: "src/server/services/combination.service.ts"
-      to: "src/server/repositories/asset-center.repository.ts"
-      via: "读取资产族与规格款"
-      pattern: "asset(Family|Variant)Repository"
-    - from: "src/app/api/platform/schemas.ts"
-      to: "src/server/services/combination.service.types.ts"
-      via: "接口契约与服务 DTO 对齐"
-      pattern: "generateCombinationSchema"
----
-
-<objective>
-把 `/auto-combinations` 的候选结果从“摘要列表”收口成“可直接确认的成品组合 + 预览数据”契约。
-
-Purpose: 按 D-04、D-05、D-06、D-08、D-09、D-11 修根因，让候选阶段就携带足够的组合细节和预览能力，同时继续以资产中心数据为主链真相。
-Output: 预览就绪的候选 DTO、单板桌候选规则收口，以及覆盖候选生成的自动化测试。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/02-资产到草稿组主链收口/02-CONTEXT.md
-@docs/workflow/团队协作模式.md
-@docs/workflow/模块边界说明.md
-@src/app/api/auto-combinations/generate/route.ts
-@src/server/services/combination.service.ts
-@src/server/services/combination.service.types.ts
-@src/lib/open-product/single-board-desk.ts
-@src/lib/open-product/platform-view.ts
-@src/server/services/pre-sku-materialization.service.ts
-@src/lib/open-product/__tests__/single-board-desk.test.ts
-
-<interfaces>
-From `src/server/services/combination.service.types.ts`:
-
-```ts
-export interface GenerateCombinationInput {
-  seriesTemplateId: string
-  desktopFamilyIds: string[]
-  legFamilyIds?: string[]
-  connectorFamilyIds?: string[]
-}
-
-export interface CombinationCandidateDTO extends SingleBoardDeskCandidate {}
-```
-
-From `src/lib/open-product/single-board-desk.ts`:
-
-```ts
-export interface SingleBoardDeskCandidate {
-  key: string
-  defaultName: string
-  previewMode: 'summary-only'
-  slotSummary: Array<{ label: string; value: string }>
-  familySelection: {
-    desktopFamilyId: string
-    legGroupFamilyId: string | null
-    legRoles: Record<'frontLeft' | 'frontRight' | 'rearLeft' | 'rearRight', string | null>
-    connectorFamilyIds: string[]
-  }
-  estimatedCost: number | null
-  statusTag: '待确认'
-}
-
-export function materializeSingleBoardDeskPreSku(input: {
-  template: SingleBoardDeskTemplate
-  candidate: SingleBoardDeskCandidate
-  variants: OpenProductAssetVariant[]
-}): MaterializedSingleBoardDeskPreSku
-```
-</interfaces>
-</context>
-
-<tasks>
-
-<task type="auto" tdd="true">
-  <name>Task 1: 收口资产中心维护链路与可消费验证</name>
-  <files>src/lib/open-product/platform-api.ts, src/server/services/asset-center.service.ts, src/server/services/asset-center.service.types.ts, src/server/services/__tests__/asset-center.service.test.ts</files>
-  <read_first>
-    .planning/phases/02-资产到草稿组主链收口/02-CONTEXT.md
-    src/lib/open-product/platform-api.ts
-    src/server/services/asset-center.service.ts
-    src/server/services/asset-center.service.types.ts
-    src/server/services/__tests__/asset-center.service.test.ts
-    src/app/auto-combinations/page.tsx
-    src/server/services/combination.service.ts
-  </read_first>
-  <acceptance_criteria>
-    - 资产中心现有“资产族 / 规格款维护”链路有明确可执行验证，能证明主线负责人可以维护并产出可被自动组合直接消费的 `AVAILABLE` 数据，符合 `MAIN-01`。
-    - 如果现有维护链路存在阻断主链消费的问题，本任务要把修复范围收敛在资产中心服务/API/DTO，不把包装、草稿组、正式入库混进来。
-    - 自动化测试至少覆盖“资产族/规格款可列出、可创建或更新、状态可进入自动组合消费范围”中的关键主链行为，不允许只在计划里口头认定“已经稳定”。 
-  </acceptance_criteria>
-  <behavior>
-    - Test 1: 资产中心服务返回的资产族/规格款在状态满足条件时可被自动组合页面筛选进可用集合。
-    - Test 2: 维护后的资产族/规格款字段口径与自动组合使用的字段一致，例如类型、状态、connectionRoles、modelUrl 等。
-    - Test 3: 如果某类资产缺少主链必需字段，服务层会给出明确错误或不可用状态，而不是让自动组合阶段再兜底。
-  </behavior>
-  <action>先验证并收口 `MAIN-01`：把资产中心维护链路和自动组合消费链路明确连起来。优先复用现有 `asset-center.service.ts` 与 `platform-api.ts`，补足必要的服务层测试和 DTO 对齐，让“资产可维护、且能被后续主链直接使用”成为可验证事实。如果当前代码已经大体稳定，则任务重点放在补验证和去掉隐含前提；如果存在阻断点，则只修资产中心主链消费相关根因，不顺手扩到页面交互或其他模块。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath src/server/services/__tests__/asset-center.service.test.ts</automated>
-  </verify>
-  <done>Phase 2 的 `MAIN-01` 不再只是前提假设，而是有明确验证和必要收口动作支撑的可执行任务。</done>
-</task>
-
-<task type="auto" tdd="true">
-  <name>Task 2: 定义预览就绪的候选契约与失败测试</name>
-  <files>src/server/services/combination.service.types.ts, src/lib/open-product/__tests__/single-board-desk.test.ts, src/server/services/__tests__/combination.service.test.ts</files>
-  <read_first>
-    .planning/phases/02-资产到草稿组主链收口/02-CONTEXT.md
-    src/server/services/combination.service.types.ts
-    src/lib/open-product/single-board-desk.ts
-    src/server/services/pre-sku-materialization.service.ts
-    src/lib/open-product/__tests__/single-board-desk.test.ts
-    src/server/services/__tests__/draft-group.service.test.ts
-  </read_first>
-  <acceptance_criteria>
-    - 候选 DTO 按 D-05、D-11 明确表达“实际组合关系 + 预览所需快照”，至少覆盖组合明细、`previewNodes`、状态/警告、摘要字段，而不是只保留 `summary-only`。
-    - 新增或改造的测试先表达失败预期：候选生成结果必须直接包含预览数据，并且数据来源仍然是资产中心的 `AssetFamily / AssetVariant`，符合 D-03、D-08。
-    - 测试命名和断言能直接说明单板桌候选的桌面、腿位、连接件关系，不把“腿组”继续当成唯一粒度，符合 D-09。
-  </acceptance_criteria>
-  <behavior>
-    - Test 1: `combinationService.generateCandidates()` 返回的每条候选都包含可供 3D 预览复用的 `previewNodes` 和组合摘要。
-    - Test 2: 单板桌候选会把桌面和四个腿位拆成实际组合关系，而不是只返回“桌腿组”粗粒度描述。
-    - Test 3: 当资产中心缺少唯一可用规格款时，候选仍返回可解释的状态/警告，而不是默默丢失预览信息。
-  </behavior>
-  <action>先把候选契约写清楚，再补测试约束。围绕 D-05、D-08、D-09、D-11 扩展 `CombinationCandidateDTO`，让执行者在实现前就知道候选必须直接携带预览所需数据。测试要覆盖服务层与纯规则层两侧：规则层证明粒度提升到真实组合关系，服务层证明资产中心数据可直接产出预览就绪候选。不要在这一任务里改页面代码，也不要把正式入库或包装字段塞进候选契约。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath src/lib/open-product/__tests__/single-board-desk.test.ts src/server/services/__tests__/combination.service.test.ts</automated>
-  </verify>
-  <done>候选契约和测试都已明确表达“候选即预览”的目标，且失败时能准确指出是候选粒度、预览快照还是资产规格款解析出了问题。</done>
-</task>
-
-<task type="auto" tdd="true">
-  <name>Task 3: 实现候选粒度升级与自动组合服务收口</name>
-  <files>src/lib/open-product/single-board-desk.ts, src/server/services/combination.service.ts, src/server/services/combination.service.types.ts, src/app/api/platform/schemas.ts, src/server/services/__tests__/combination.service.test.ts, src/lib/open-product/__tests__/single-board-desk.test.ts</files>
-  <read_first>
-    src/lib/open-product/single-board-desk.ts
-    src/server/services/combination.service.ts
-    src/app/api/auto-combinations/generate/route.ts
-    src/app/api/platform/schemas.ts
-    src/server/services/pre-sku-materialization.service.ts
-    src/lib/open-product/platform-view.ts
-  </read_first>
-  <acceptance_criteria>
-    - `combinationService.generateCandidates()` 按 D-04、D-06、D-11 返回可直接驱动左侧预览的候选数据，且字段口径和 `materializeSingleBoardDeskPreSku()` 一致。
-    - 单板桌候选不再固定为 `previewMode: 'summary-only'` 的摘要结果，而是显式带出组合明细、摘要、预览节点、状态和警告，符合 D-05、D-09。
-    - 路由 schema 仍只接收主链需要的输入；不把包装、正式产品或旧 CAD 真相混进来，符合 D-01、D-03、D-14。
-  </acceptance_criteria>
-  <behavior>
-    - Test 1: 使用资产中心中的桌面族、桌腿族、连接件族生成候选时，返回值包含 `previewNodes`、组合摘要和状态字段。
-    - Test 2: 某个腿位或连接件缺少唯一规格款时，候选结果带出 warning/status，而不是直接崩溃。
-    - Test 3: 接口 schema 仍然只接受 `seriesTemplateId`、资产族选择等主链参数，不接受包装或正式入库字段。
-  </behavior>
-  <action>基于 Task 1 的契约，把单板桌候选从“列表摘要”升级成“可直接确认的组合快照”。优先复用 `materializeSingleBoardDeskPreSku()` 和现有资产规格款解析逻辑，而不是再造第二套预览拼装机制，符合 D-08。必要时允许在 `single-board-desk.ts` 内抽公共 helper，但要保持纯规则层纯净；`combination.service.ts` 负责读资产中心数据、调用规则层并返回 DTO；`schemas.ts` 只维护接口输入约束，不做业务拼装判断。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath src/lib/open-product/__tests__/single-board-desk.test.ts src/server/services/__tests__/combination.service.test.ts</automated>
-  </verify>
-  <done>自动组合接口已经能稳定返回“可直接确认、可直接预览”的候选结果，后续前端 agent 只需消费 DTO，不需要再反推组合规则或自己拼预览数据。</done>
-</task>
-
-</tasks>
-
-<verification>
-执行后至少跑通单板桌规则测试和组合服务测试，确认候选粒度、预览快照、资产规格款来源三件事同时成立。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`MAIN-01` 与 `MAIN-02` 在自动组合侧达成：资产中心数据可直接生成可确认的组合候选，候选本身就带出主链预览所需数据，不再让草稿组成为第一次看到真实拼装效果的唯一入口。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/02-资产到草稿组主链收口/02-01-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/02-资产到草稿组主链收口/02-01-SUMMARY.md

@@ -1,44 +0,0 @@
----
-phase: 02-资产到草稿组主链收口
-plan: 01
-subsystem: combination
-tags: [asset-center, auto-combinations, preview, testing]
-requires:
-  - phase: 01-协作入口与项目记忆稳定化
-    provides: 协作入口与项目记忆稳定
-provides:
-  - 资产中心维护结果可被历史自动组合主链消费
-  - 单板桌候选预览契约基线
-  - 组合服务与规则层的自动化验证
-affects: [phase-02, asset-center, historical-auto-combinations]
-requirements-completed: [MAIN-01, MAIN-02]
-completed: 2026-04-02
----
-
-# Phase 2 Plan 01 Summary
-
-**这轮先把“资产中心可维护”与“候选可预览”连成一条历史阶段基线，让 Phase 2 的主链不再只是摘要列表。**
-
-## Accomplishments
-
-- 补齐并验证了 `asset-center（资产中心）` 维护结果可直接被历史 `auto-combinations（自动组合）` 链消费的口径。
-- 收口了单板桌候选的预览与摘要契约，让候选结果不再只是粗粒度摘要。
-- 为 `combination.service（组合服务）`、`single-board-desk（单板桌规则）` 和 `asset-center（资产中心）` 相关服务补了关键自动化测试。
-
-## Verification
-
-- 已执行：`npm test -- --runTestsByPath src/server/services/__tests__/asset-center.service.test.ts`
-- 已执行：`npm test -- --runTestsByPath src/server/services/__tests__/combination.service.test.ts`
-- 已执行：`npm test -- --runTestsByPath src/lib/open-product/__tests__/single-board-desk.test.ts`
-- 结果：通过
-
-## Risks
-
-- 本总结对应的是 Phase 2 当时的历史主链基线，当前现行入口已演进为 `assisted-assembly（辅助装配） / manual assembly（手动拼装）`，不要再把这里的 `auto-combinations（自动组合）` 直接当成今天的页面入口。
-
-## Review
-
-- 结论：`passed`
-- 审查范围：架构、视觉、根因修复
-- 标注：这是自审，不是独立复审
-

furniture-3d-system/.planning/phases/02-资产到草稿组主链收口/02-02-PLAN.md

@@ -1,195 +0,0 @@
----
-phase: 02-资产到草稿组主链收口
-plan: 02
-type: execute
-wave: 2
-depends_on:
-  - 02-01
-files_modified:
-  - src/server/services/draft-group.service.types.ts
-  - src/server/services/pre-sku-materialization.service.ts
-  - src/server/services/draft-group.service.ts
-  - src/app/api/platform/schemas.ts
-  - src/server/services/__tests__/draft-group.service.test.ts
-  - ../docs/前端UI改动清单.md
-autonomous: true
-requirements:
-  - MAIN-02
-  - MAIN-03
-must_haves:
-  truths:
-    - "平台负责人把候选送入草稿组后，草稿组里保存的 `PreSku` 结果与候选阶段看到的组合/预览口径一致。"
-    - "草稿组里的每个预 SKU 都能保存候选摘要、预览快照和后续接缝状态，不会在主链交接时丢字段。"
-    - "前端 agent 拿到明确交接要求后，可以按固定契约完成“点候选即预览”的页面改动，而不是自行猜后端数据。"
-  artifacts:
-    - path: "src/server/services/pre-sku-materialization.service.ts"
-      provides: "候选到 PreSku 的一致性物化逻辑"
-      contains: "buildPreparedPreSkus"
-    - path: "src/server/services/draft-group.service.ts"
-      provides: "自动组合结果进入草稿组的主链编排"
-      contains: "createFromAutoCombination"
-    - path: "src/server/services/draft-group.service.types.ts"
-      provides: "草稿组明细、PreSku 摘要与接缝状态 DTO"
-      contains: "DraftGroupPreSkuDTO"
-    - path: "../docs/前端UI改动清单.md"
-      provides: "自动组合页候选预览联动的前端交接要求"
-      contains: "自动组合候选即预览"
-  key_links:
-    - from: "src/server/services/draft-group.service.ts"
-      to: "src/server/services/pre-sku-materialization.service.ts"
-      via: "候选入草稿组时复用同一物化口径"
-      pattern: "buildPreparedPreSkus"
-    - from: "src/server/services/pre-sku-materialization.service.ts"
-      to: "src/lib/open-product/single-board-desk.ts"
-      via: "候选物化与预览节点生成"
-      pattern: "materializeSingleBoardDeskPreSku"
-    - from: "../docs/前端UI改动清单.md"
-      to: "src/server/services/draft-group.service.types.ts"
-      via: "前端按 DTO 消费候选预览与草稿组摘要"
-      pattern: "previewNodes|displaySummary|assemblyResultStatus"
----
-
-<objective>
-把“候选 -> 草稿组 -> PreSku”这段主链收口成同一口径，并把自动组合页的前端联动需求明确交接给前端 workflow。
-
-Purpose: 按 D-06、D-10、D-11、D-12、D-13 修复主链交接不一致问题，避免候选阶段和草稿组阶段各说各话。
-Output: 一致的候选入草稿组物化逻辑、草稿组 DTO 收口，以及更新后的前端 UI 交接清单。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/02-资产到草稿组主链收口/02-CONTEXT.md
-@.planning/phases/02-资产到草稿组主链收口/02-01-PLAN.md
-@src/server/services/draft-group.service.ts
-@src/server/services/draft-group.service.types.ts
-@src/server/services/pre-sku-materialization.service.ts
-@src/app/api/platform/schemas.ts
-@src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
-@src/components/platform/ModelPreviewPanel.tsx
-@src/components/platform/CompositeAssetPreview.tsx
-@../docs/前端UI改动清单.md
-
-<interfaces>
-From `src/server/services/draft-group.service.types.ts`:
-
-```ts
-export interface DraftGroupCandidateInput {
-  key: string
-  defaultName: string
-  familySelection: {
-    desktopFamilyId: string
-    legGroupFamilyId?: string | null
-    legRoles: Partial<
-      Record<'frontLeft' | 'frontRight' | 'rearLeft' | 'rearRight', string | null | undefined>
-    >
-    connectorFamilyIds: string[]
-  }
-}
-
-export interface DraftGroupPreSkuDTO {
-  id: string
-  sourceCandidateKey: string
-  previewNodes: unknown[]
-  displaySummary: Record<string, unknown> | null
-  assemblyResultStatus: AssemblyResultStatus | null
-  assemblyWarnings: string[]
-}
-```
-
-From `src/server/services/pre-sku-materialization.service.ts`:
-
-```ts
-class PreSkuMaterializationService {
-  async buildPreparedPreSkus(
-    input: CreateDraftGroupFromAutoCombinationInput,
-    draftGroupId: string,
-  ): Promise<{
-    seriesTemplateCode: string
-    preparedPreSkus: Prisma.PreSkuUncheckedCreateInput[]
-  }>
-}
-```
-</interfaces>
-</context>
-
-<tasks>
-
-<task type="auto" tdd="true">
-  <name>Task 1: 统一候选入草稿组的物化口径与测试</name>
-  <files>src/server/services/draft-group.service.types.ts, src/server/services/pre-sku-materialization.service.ts, src/server/services/draft-group.service.ts, src/app/api/platform/schemas.ts, src/server/services/__tests__/draft-group.service.test.ts</files>
-  <read_first>
-    .planning/phases/02-资产到草稿组主链收口/02-01-PLAN.md
-    src/server/services/draft-group.service.ts
-    src/server/services/draft-group.service.types.ts
-    src/server/services/pre-sku-materialization.service.ts
-    src/server/services/__tests__/draft-group.service.test.ts
-    src/app/api/platform/schemas.ts
-  </read_first>
-  <acceptance_criteria>
-    - 草稿组接收的候选输入和 Plan `02-01` 输出契约一致，入草稿组后保存的 `previewNodes`、摘要、状态、警告不再和候选阶段脱节，符合 D-10、D-11、D-12。
-    - `createFromAutoCombination()` 继续只落 `DraftGroup -> PreSku`，不引入正式产品或包装方案直存逻辑，符合 D-01、D-10、D-14。
-    - 测试覆盖多候选保存、四个腿位拆分、摘要/预览口径一致和异常提示，不让“候选能看、草稿组丢字段”再次回归，符合 D-05、D-12。
-  </acceptance_criteria>
-  <behavior>
-    - Test 1: 选择多个候选创建草稿组后，每个 `PreSku` 保存的 `previewNodes`、摘要和状态与候选阶段一致。
-    - Test 2: 混搭腿位候选写入草稿组时，四个腿位仍分别保留，不会回退成单一腿组摘要。
-    - Test 3: 缺少可用规格款时，草稿组明细保留 warning/status，后续接缝状态可见。
-  </behavior>
-  <action>基于 Plan `02-01` 的候选契约，把候选入草稿组的物化过程收口到同一套口径。优先复用或下沉公共物化 helper，避免 `combination.service.ts` 与 `pre-sku-materialization.service.ts` 各自维护一套组合解释。必要时扩展 `DraftGroupCandidateInput` 和 `createDraftGroupSchema` 以承接预览就绪候选，但服务端仍要自行校验关键字段，不信任前端拼装结果。不要在本任务里把包装字段做成必填，也不要越界改草稿组详情 UI。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath src/server/services/__tests__/draft-group.service.test.ts src/server/services/__tests__/combination.service.test.ts</automated>
-  </verify>
-  <done>候选进入草稿组后，`PreSku` 保存结果与候选阶段同源同口径，主链在自动组合和草稿组之间不再出现“重新解释一次候选”的断层。</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 把自动组合页联动需求写入前端交接清单</name>
-  <files>../docs/前端UI改动清单.md</files>
-  <read_first>
-    ../docs/前端UI改动清单.md
-    .planning/phases/02-资产到草稿组主链收口/02-CONTEXT.md
-    .planning/phases/02-资产到草稿组主链收口/02-01-PLAN.md
-    src/app/auto-combinations/AutoCombinationsClient.tsx
-    src/components/platform/ModelPreviewPanel.tsx
-    src/components/platform/CompositeAssetPreview.tsx
-  </read_first>
-  <acceptance_criteria>
-    - 按 D-13 把前端要做的事写成清晰交接项，而不是直接在当前 plan 里实现 UI。
-    - 清单明确写出“候选即预览”的交互目标、候选卡片需要展示的成品组合粒度、左侧预览消费的后端字段，以及联调时如何判断是前端问题还是后端问题，符合 D-06、D-13。
-    - 文档明确标注：实际页面改动需走前端 workflow / 前端 agent，不在本阶段主链计划里直接写 UI 代码。
-  </acceptance_criteria>
-  <action>更新 `../docs/前端UI改动清单.md`，新增一段只针对 `/auto-combinations` 的交接要求：候选列表必须展示实际组合关系；点击候选时左侧复用现有 `ModelPreviewPanel` / `CompositeAssetPreview` 消费后端返回的 `previewNodes`；创建草稿组时提交的候选字段必须和 Plan `02-01`、本计划 Task 1 对齐；如果联调失败，要按“接口字段缺失/口径不一致归后端，展示结构和交互归前端”分流。只写需求和联调边界，不直接改页面代码。</action>
-  <verify>
-    <automated>rg -n "自动组合候选即预览|实际组合关系|previewNodes|前端 workflow|联调失败" ../docs/前端UI改动清单.md</automated>
-  </verify>
-  <done>前端 agent 已有清晰、可执行的交接清单，后续 UI 落地不需要再回头猜候选字段、预览字段和责任边界。</done>
-</task>
-
-</tasks>
-
-<verification>
-执行后至少跑通草稿组服务测试，并用文档关键字校验确认前端交接要求已落盘且责任边界明确。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`MAIN-02` 与 `MAIN-03` 在主链交接侧达成：候选结果能稳定收口到草稿组并保存为一致的 `PreSku` 摘要/预览数据，前端改动也已被清楚移交给前端 workflow，而不是混在后端计划里含糊处理。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/02-资产到草稿组主链收口/02-02-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/02-资产到草稿组主链收口/02-02-SUMMARY.md

@@ -1,93 +0,0 @@
----
-phase: 02-资产到草稿组主链收口
-plan: 02
-subsystem: api
-tags: [draft-group, auto-combinations, pre-sku, preview, testing]
-requires:
-  - phase: 02-资产到草稿组主链收口
-    provides: 自动组合候选预览契约
-provides:
-  - 候选到草稿组的统一物化逻辑
-  - 缺规格款与多规格款场景下可持续流转的 PreSku 摘要
-  - 自动组合页前端联调交接清单
-affects: [phase-03, packaging, auto-combinations-ui]
-tech-stack:
-  added: []
-  patterns:
-    - 单板桌候选和草稿组共享同一套物化 helper
-    - 用 warning/status 保留异常场景，而不是在主链中途直接拦截
-key-files:
-  created:
-    - src/server/services/single-board-desk-materialization.ts
-    - .planning/phases/02-资产到草稿组主链收口/02-02-SUMMARY.md
-  modified:
-    - src/server/services/combination.service.ts
-    - src/server/services/pre-sku-materialization.service.ts
-    - src/server/services/__tests__/draft-group.service.test.ts
-    - docs/前端UI改动清单.md
-key-decisions:
-  - "候选阶段和草稿组阶段不再各自解释单板桌候选，统一复用 single-board-desk-materialization helper。"
-  - "缺规格款和多规格款不再阻断草稿组创建，而是保留装配状态与 warnings 继续进入 PreSku。"
-patterns-established:
-  - "候选主链模式：generateCandidates 与 buildPreparedPreSkus 共用一套物化与诊断逻辑。"
-  - "交接模式：前端只消费后端契约，不自己补口径；联调失败按字段/展示边界分流。"
-requirements-completed: [MAIN-02, MAIN-03]
-duration: 45min
-completed: 2026-04-02
----
-
-# Phase 2 Plan 02 Summary
-
-**自动组合候选和草稿组 PreSku 现在共用一套物化真相，异常候选也能带着状态与警告继续进入主链。**
-
-## Performance
-
-- **Duration:** 45 min
-- **Started:** 2026-04-02T20:40:00+08:00
-- **Completed:** 2026-04-02T21:23:50+08:00
-- **Tasks:** 2
-- **Files modified:** 5
-
-## Accomplishments
-
-- 抽出 `single-board-desk-materialization.ts`，让自动组合和草稿组都复用同一套模板构建、规格款映射和 warning 诊断逻辑。
-- 草稿组创建不再因为“缺规格款 / 多规格款”直接失败，而是把 `assemblyResultStatus`、`assemblyWarnings`、`previewNodes`、`displaySummary` 一起保存进 `PreSku`。
-- 更新了 `docs/前端UI改动清单.md`，把“候选即预览”的字段契约、页面目标和联调责任边界固定下来。
-
-## Task Commits
-
-未创建提交。当前仓库仍保持本地未提交工作状态。
-
-## Files Created/Modified
-
-- `src/server/services/single-board-desk-materialization.ts` - 单板桌候选共享物化 helper
-- `src/server/services/combination.service.ts` - 自动组合候选改为复用共享 helper
-- `src/server/services/pre-sku-materialization.service.ts` - 草稿组 PreSku 物化改为复用共享 helper
-- `src/server/services/__tests__/draft-group.service.test.ts` - 覆盖缺规格款/多规格款继续收口场景
-- `docs/前端UI改动清单.md` - 固定自动组合候选即预览交接清单
-
-## Decisions Made
-
-- 用统一 helper 解决根因，避免 `combination.service` 和 `pre-sku-materialization.service` 再次分叉。
-- 保留“双层 warning”：既保留装配层 warning，也保留更可读的业务提示，前端直接展示即可。
-
-## Deviations from Plan
-
-None - plan executed exactly as written.
-
-## Issues Encountered
-
-- 草稿组旧测试假设“异常候选必须拦截”，与当前主链目标冲突；已改成验证 warning/status 持续保留。
-
-## User Setup Required
-
-None - no external service configuration required.
-
-## Next Phase Readiness
-
-- Phase 2 的两个 plan 已执行完成，主链已经能从候选稳定收口到草稿组。
-- 下一步可以进入 Phase 3，专注包装接缝稳定化，不再回头补候选和草稿组之间的口径问题。
-
----
-*Phase: 02-资产到草稿组主链收口*
-*Completed: 2026-04-02*

furniture-3d-system/.planning/phases/02-资产到草稿组主链收口/02-CONTEXT.md

@@ -1,138 +0,0 @@
-# Phase 2: 资产到草稿组主链收口 - Context
-
-**Gathered:** 2026-04-02
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-把新平台主链中“资产中心 -> 自动组合 -> 草稿组”这一段收口到符合真实业务目标的状态：资产族与规格款能作为组合输入，自动拼装能按系列规则生成合法候选，用户可以围绕候选结果确认组合并进入草稿组。当前阶段聚焦主线，不负责包材窗和包装方案实现，也不直接推进正式入库。
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### 主线范围与协作边界
-- **D-01:** Phase 2 只做主线的资产中心、自动组合、草稿组链路收口，不把 `包材窗`、`包装方案` 纳入当前实现范围。
-- **D-02:** 包材窗和包装方案明确属于同事 `xuxiake` 的包装域；主线只保留后续对接所需的数据接缝，不代做包装功能。
-- **D-03:** 本阶段继续遵守新平台主链与旧 CAD 兼容链分离原则；自动拼装可复用旧 3D 预览能力，但不能让旧 `Product / SKU / Panel` 反向变成新主链数据真相。
-
-### 自动拼装的业务目标
-- **D-04:** 自动拼装的目标不是“生成摘要候选后再慢慢确认”，而是：用户选择某个系列，再选择一个或多个板材/组件，系统按该系列规则生成合法组合列表。
-- **D-05:** 合法组合列表必须显式表达实际组合关系，例如“桌面A + 桌腿B*4”，而不是只停留在“桌面板资产族 + 桌腿组资产族”的粗粒度摘要。
-- **D-06:** 用户点击某一条合法组合后，左侧 3D 预览区应立即按该组合自动拼装并正确展示对应模型结果；这属于主线自动拼装体验的一部分，不应延后到草稿组才首次出现。
-
-### 当前代码真相与收口方向
-- **D-07:** 当前 `/auto-combinations` 已具备“系列模板 + 资产族选择 + 候选列表生成”的基础，但左侧仍是配置摘要，不是候选驱动的 3D 预览。
-- **D-08:** 当前系统已具备组合预览底座：`PreSku.previewNodes`、`ModelPreviewPanel`、`CompositeAssetPreview` 已能渲染多模型拼装预览，应优先复用，不重造第二套 3D 预览机制。
-- **D-09:** 当前候选生成规则只锁定 `single-board-desk`，且主要是“桌面板 x 桌腿组”的资产族展开；Phase 2 需要围绕真实业务目标，把候选粒度、规则表达和预览联动往“可直接确认的成品组合”推进。
-
-### 数据与对象流转
-- **D-10:** 新平台主链的对象流转继续保持为：`AssetFamily / AssetVariant -> 自动组合候选 -> DraftGroup -> PreSku`，不能跳过草稿组直接落正式 `Product / SKU`。
-- **D-11:** 候选阶段应尽早产出足够驱动预览的数据，避免出现“候选能看列表但不能看真实拼装，必须先进草稿组才能首次预览”的断层。
-- **D-12:** 草稿组继续作为多条候选结果的收口容器，但不再承担“第一次看到真实拼装效果”的唯一入口职责。
-
-### 阶段边界
-- **D-13:** 本阶段优先做根因收口，不做 UI 美化型任务；如果需要前端落地改动，只把需求写入 `D:\AI Code\3danzhuang\docs\前端UI改动清单.md`，由前端 agent 实现。
-- **D-14:** 本阶段不趁机扩写正式入库、轻仓库或包装增强内容；这些分别属于后续 Phase 3 / 4。
-
-### the agent's Discretion
-- 自动拼装在实现上先从“单板桌”模板收口，还是先补通通用候选预览协议，由 agent 根据现有代码复用度决定。
-- 组合规则是先在 service 层细化，还是先在 `open-product` 规则层细化，由 agent 在不破坏分层的前提下决定。
-- 为了让前端 agent 接手 UI，哪些交互差异只记录需求、不在当前阶段直接实现，由 agent 判断。
-
-</decisions>
-
-<specifics>
-## Specific Ideas
-
-- 用户期望的自动拼装行为是：
-  - 选择系列，例如 `单板桌系列`
-  - 选择部件，例如 `桌面A`
-  - 系统按系列规则生成合法列表，例如：
-    - `桌面A + 桌腿A*4`
-    - `桌面A + 桌腿B*4`
-    - `桌面A + 桌腿C*4`
-  - 点击其中一条后，左侧 3D 自动拼好并正确展示该组合
-- 图里的 `包材窗` 和 `包装方案` 不归主线负责，Phase 2 不把这两个模块纳入执行范围。
-- 当前项目真实现状是“自动组合页先出候选，草稿组详情页才看 3D”，而目标是“自动组合页点候选即看 3D”。
-
-</specifics>
-
-<canonical_refs>
-## Canonical References
-
-**Downstream agents MUST read these before planning or implementing.**
-
-### 项目级约束
-- `.planning/PROJECT.md` — 项目目标、长期约束、主线与兼容链分离原则
-- `.planning/ROADMAP.md` — Phase 2 的目标、依赖、成功标准
-- `.planning/REQUIREMENTS.md` — `MAIN-01`、`MAIN-02`、`MAIN-03` 的需求定义
-- `.planning/STATE.md` — 当前阶段、下一步、风险恢复入口
-
-### 协作与边界
-- `../AGENTS.md` — 外层仓库全局规则、协作入口、前端/UI 交接规则
-- `docs/workflow/团队协作模式.md` — 主线、包装线、兼容链的协作口径
-- `docs/workflow/模块边界说明.md` — 新平台主链、包装协作、旧 CAD 兼容链和共享接缝边界
-
-### 自动组合主链现状
-- `src/app/auto-combinations/page.tsx` — 自动组合页主入口
-- `src/app/auto-combinations/AutoCombinationsClient.tsx` — 当前候选生成页面与左侧区域现状
-- `src/app/api/auto-combinations/generate/route.ts` — 自动组合生成接口入口
-- `src/server/services/combination.service.ts` — 当前候选生成编排服务
-- `src/server/services/combination.service.types.ts` — 当前候选 DTO 结构
-- `src/lib/open-product/single-board-desk.ts` — 单板桌模板的候选生成与预览节点物化规则
-- `src/lib/open-product/assembly-contract.ts` — 单板桌槽位与角色约束
-- `src/server/services/series-template.service.ts` — 当前模板初始化和模板规则来源
-- `src/server/repositories/series-template.repository.ts` — 模板持久化读取方式
-
-### 草稿组与预览现状
-- `src/server/services/draft-group.service.ts` — 自动组合结果进入草稿组的主链服务
-- `src/server/services/pre-sku-materialization.service.ts` — 候选物化为 `PreSku` 与 `previewNodes` 的关键逻辑
-- `src/server/services/draft-group.service.types.ts` — `PreSku` 预览与包装输入结构
-- `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx` — 当前“点击条目切换左侧 3D”的已实现页面
-- `src/components/platform/ModelPreviewPanel.tsx` — 平台侧预览容器
-- `src/components/platform/CompositeAssetPreview.tsx` — 组合资产预览组件
-- `src/components/platform/CompositeAssetPreviewCanvas.tsx` — 组合 3D 画布实现
-- `src/lib/open-product/platform-view.ts` — `previewNodes` / BOM / 安装预览读取逻辑
-
-### 数据模型
-- `prisma/schema.prisma` — `AssetFamily`、`AssetVariant`、`SeriesTemplate`、`DraftGroup`、`PreSku` 数据模型边界
-
-</canonical_refs>
-
-<code_context>
-## Existing Code Insights
-
-### Reusable Assets
-- `combinationService.generateCandidates()` 已经把模板、资产族和候选生成串起来，可作为 Phase 2 的候选规则主入口。
-- `materializeSingleBoardDeskPreSku()` 已经能基于唯一规格款生成 `previewNodes`、BOM、安装步骤预览，这套物化逻辑可复用到“候选即预览”链路。
-- `ModelPreviewPanel` + `CompositeAssetPreview` 已经具备多模型装配预览能力，不需要为自动组合页再造新的 3D 预览组件。
-
-### Established Patterns
-- 新平台主链沿用 `Route -> Service -> Repository -> Prisma`，候选规则与物化逻辑应继续留在 service/lib 规则层，不把业务判断塞回页面。
-- 当前模板体系以 `SeriesTemplate` 为规则源，`previewRule`、`slotSchema`、`recommendationRule` 已是现有扩展点。
-- 当前草稿组链路已经证明“候选结果 -> PreSku -> 3D 预览”可跑通，说明系统不是缺 3D 能力，而是缺自动组合页的联动收口。
-
-### Integration Points
-- `/api/auto-combinations/generate` 是候选生成的后端接入点，后续若要让候选直接驱动预览，这里或其下游 DTO 是关键接缝。
-- `DraftGroupService.createFromAutoCombination()` 与 `PreSkuMaterializationService` 是候选落草稿组的主接缝，后续要保证候选预览数据和草稿组预览数据口径一致。
-- 前端如果要实现“点候选即看 3D”，最直接的页面接点是 `AutoCombinationsClient.tsx` 左侧区域。
-
-</code_context>
-
-<deferred>
-## Deferred Ideas
-
-- 包材窗、包装方案和包装成本/体积/材料扩展 —— 属于 Phase 3
-- 正式入库、成品落库、轻仓库收口 —— 属于 Phase 4
-- 旧 CAD 兼容链的装配编辑器增强 —— 只作为复用参考，不在本阶段单独推进
-- 自动拼装的更通用系列模板扩展 —— 先收口 `single-board-desk`，其余模板后续再扩
-
-</deferred>
-
----
-
-*Phase: 02-资产到草稿组主链收口*
-*Context gathered: 2026-04-02*

furniture-3d-system/.planning/phases/02-资产到草稿组主链收口/02-DISCUSSION-LOG.md

@@ -1,64 +0,0 @@
-# Phase 2: 资产到草稿组主链收口 - Discussion Log
-
-> **Audit trail only.** Do not use as input to planning, research, or execution agents.
-> Decisions captured in CONTEXT.md — this log preserves the source discussion and code reconnaissance.
-
-**Date:** 2026-04-02
-**Phase:** 02-资产到草稿组主链收口
-**Mode:** direct capture from user clarification + code reconnaissance
-**Areas analyzed:** 自动拼装业务目标, 主线与包装域边界, 自动组合当前实现, 草稿组与 3D 预览现状
-
-## User Clarifications Captured
-
-### 包装域边界
-| Clarification | Confidence | Source |
-|------------|-----------|----------|
-| 图里的 `包材窗` 和 `包装方案` 由同事负责，主线不用操心这两块实现。 | Confirmed | User explicit instruction on 2026-04-02 |
-
-### 自动拼装目标
-| Clarification | Confidence | Source |
-|------------|-----------|----------|
-| 用户希望先选系列，再选板材/组件，系统按系列规则生成合法组合列表。 | Confirmed | User explicit instruction on 2026-04-02 |
-| 合法组合应显示成真实可理解的组合项，例如 `桌面A + 桌腿B*4`。 | Confirmed | User example on 2026-04-02 |
-| 点击某一条组合后，左侧 3D 预览区要立即自动拼好并正确展示该组合。 | Confirmed | User explicit instruction on 2026-04-02 |
-
-## Code Reconnaissance Findings
-
-### 自动组合入口
-| Finding | Confidence | Evidence |
-|------------|-----------|----------|
-| 当前主入口是 `/auto-combinations`，用户选择的是系列模板和资产族，不是直接选择具体规格款。 | Confident | `src/app/auto-combinations/page.tsx`, `src/app/auto-combinations/AutoCombinationsClient.tsx` |
-
-### 候选生成现状
-| Finding | Confidence | Evidence |
-|------------|-----------|----------|
-| 当前后端只锁定 `single-board-desk` 模板，候选由“桌面板资产族 x 桌腿组资产族”生成。 | Confident | `src/server/services/combination.service.ts`, `src/lib/open-product/single-board-desk.ts` |
-| 当前候选更偏“摘要候选”，还不是用户想要的“点一条就看真实拼装”的候选体验。 | Confident | `AutoCombinationsClient.tsx`, `single-board-desk.ts` |
-
-### 3D 预览现状
-| Finding | Confidence | Evidence |
-|------------|-----------|----------|
-| 当前系统已经具备组合 3D 预览能力，底座在 `previewNodes` + `ModelPreviewPanel` + `CompositeAssetPreview`。 | Confident | `pre-sku-materialization.service.ts`, `ModelPreviewPanel.tsx`, `CompositeAssetPreview.tsx` |
-| 现有“点击条目切换左侧 3D”发生在草稿组详情页，而不是自动组合页。 | Confident | `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx` |
-
-### 对象流转
-| Finding | Confidence | Evidence |
-|------------|-----------|----------|
-| 当前主线对象流转是 `自动组合候选 -> DraftGroup -> PreSku -> 后续入库`。 | Confident | `draft-group.service.ts`, `pre-sku-materialization.service.ts`, `prisma/schema.prisma` |
-
-## Corrections Made
-
-- 修正了“自动拼装还没有 3D 底子”的粗判断。真实情况是 3D 预览底子已经有，只是放在草稿组阶段，不在自动组合页。
-- 修正了“包装可能要一起考虑”的范围判断。根据用户明确说明，`包材窗` 和 `包装方案` 在 Phase 2 不属于主线执行范围。
-
-## Open Technical Gaps Identified
-
-- 候选 DTO 目前是否足够直接驱动自动组合页的左侧 3D 预览，还需要在规划阶段具体拆任务。
-- 现有 `single-board-desk` 规则还比较粗，如何把“桌腿组”细化成用户理解的“桌腿A/B/C*4”显示与规则输出，需要在计划中明确。
-- 自动组合页如果要实现点候选即看 3D，会涉及前端联动；当前工作流只负责把需求和后端/数据结构口径定清楚。
-
-## Scope Reminder
-
-- 本阶段不实现包材窗和包装方案。
-- 本阶段不直接推进正式入库和轻仓库。
-- 本阶段优先收口自动组合到草稿组的主链真相。

furniture-3d-system/.planning/phases/03-包装接缝稳定化/03-01-PLAN.md

@@ -1,163 +0,0 @@
----
-phase: 03-包装接缝稳定化
-plan: 01
-type: execute
-wave: 1
-depends_on: []
-files_modified:
-  - src/server/services/pre-sku-packaging.service.ts
-  - src/server/services/packaging-plan-calculator.ts
-  - src/server/services/intake.service.ts
-  - src/server/services/__tests__/draft-group.service.test.ts
-  - src/server/services/__tests__/intake.service.test.ts
-  - src/app/api/pre-skus/[id]/packaging/route.test.ts
-autonomous: true
-requirements:
-  - MAIN-04
-must_haves:
-  truths:
-    - "PreSku 的包装结果保存后，读取、试算、正式入库承接的是同一套 `boxes / costSummary / processDraft` 真相结构。"
-    - "主线不会再同时维护旧 `items / resultSummary` 和新 `boxes[]` 两套包装入口口径。"
-    - "正式入库继续以“存在有效包装箱”作为准入前提，前端页面或包装线任务不能绕开这条规则。"
-  artifacts:
-    - path: "src/server/services/pre-sku-packaging.service.ts"
-      provides: "PreSku 包装上下文、试算、保存的主编排"
-      contains: "savePackagingPlan|previewPackagingPlan|getPackagingContext"
-    - path: "src/server/services/packaging-plan-calculator.ts"
-      provides: "包装箱、材料、成本、重量、体积统一计算"
-      contains: "materializePackagingPlanForPersistence"
-    - path: "src/server/services/intake.service.ts"
-      provides: "正式入库对包装结果的承接"
-      contains: "formalizeDraftGroup"
-  key_links:
-    - from: "src/server/services/pre-sku-packaging.service.ts"
-      to: "src/server/services/packaging-plan-calculator.ts"
-      via: "保存与试算统一走同一套包装物化逻辑"
-      pattern: "materializePackagingPlanForPersistence"
-    - from: "src/server/services/intake.service.ts"
-      to: "prisma/schema.prisma"
-      via: "PreSkuPackagingPlan -> PackagedItem 正式承接"
-      pattern: "PackagedItem|PreSkuPackagingPlan"
-    - from: "src/app/api/pre-skus/[id]/packaging/route.ts"
-      to: "src/app/api/platform/schemas.ts"
-      via: "包装接口输入必须继续锁定为 boxes / costSummary / processDraft / notes"
-      pattern: "savePreSkuPackagingPlanSchema"
----
-
-<objective>
-把 `PreSku` 包装结果的保存、试算和正式入库承接彻底收口成同一条主线真相，并用测试守住回归。
-
-Purpose: 按 `MAIN-04` 修根因，避免包装结果“能保存但不能稳定承接”、或者后续又被旧结构和页面占位逻辑带偏。
-Output: 更稳的包装保存/试算/入库承接测试闭环，以及明确只认新结构的主线口径。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/03-包装接缝稳定化/03-CONTEXT.md
-@src/server/services/pre-sku-packaging.service.ts
-@src/server/services/packaging-plan-calculator.ts
-@src/server/services/intake.service.ts
-@src/app/api/pre-skus/[id]/packaging/route.ts
-@src/app/api/platform/schemas.ts
-@src/server/services/__tests__/draft-group.service.test.ts
-@src/server/services/__tests__/intake.service.test.ts
-
-<interfaces>
-From `src/server/services/draft-group.service.types.ts`:
-
-```ts
-export interface SavePreSkuPackagingPlanInput {
-  sourceType?: 'PRODUCT' | 'PRE_SKU' | 'DRAFT_GROUP'
-  sourceRefId?: string | null
-  status?: string
-  boxes: SavePreSkuPackagingPlanBoxInput[]
-  costSummary?: Partial<PreSkuPackagingCostSummaryDTO> | null
-  processDraft?: Record<string, unknown> | null
-  notes?: string | null
-}
-```
-
-From `src/server/services/intake.service.ts`:
-
-```ts
-function ensurePreSkuReadyForFormalization(preSku, draftGroupId: string)
-function normalizePackagingBoxes(value: unknown)
-function normalizePackagingSummary(value: unknown, boxCount: number)
-```
-</interfaces>
-</context>
-
-<tasks>
-
-<task type="auto" tdd="true">
-  <name>Task 1: 锁定包装保存、试算与读取只认新结构</name>
-  <files>src/server/services/pre-sku-packaging.service.ts, src/server/services/packaging-plan-calculator.ts, src/app/api/pre-skus/[id]/packaging/route.test.ts, src/server/services/__tests__/draft-group.service.test.ts</files>
-  <read_first>
-    src/server/services/pre-sku-packaging.service.ts
-    src/server/services/packaging-plan-calculator.ts
-    src/app/api/pre-skus/[id]/packaging/route.ts
-    src/app/api/platform/schemas.ts
-    src/server/services/__tests__/draft-group.service.test.ts
-    src/app/api/pre-skus/[id]/packaging/route.test.ts
-  </read_first>
-  <acceptance_criteria>
-    - `src/server/services/__tests__/draft-group.service.test.ts` 包含“包装试算 / 保存 / 读取”围绕 `boxes`、`costSummary`、`processDraft` 的断言，不再依赖旧 `items / resultSummary` 入口。
-    - `src/app/api/pre-skus/[id]/packaging/route.test.ts` 能证明 `PUT` 非法旧结构会被 schema 拦截，合法新结构返回 `200`。
-    - `src/server/services/pre-sku-packaging.service.ts` 中保存与试算继续共用 `materializePackagingPlanForPersistence(`，没有出现第二套手工汇总逻辑。
-  </acceptance_criteria>
-  <action>补齐并收紧包装接口与服务测试：明确 `PUT /api/pre-skus/[id]/packaging` 只接受 `boxes / costSummary / processDraft / notes`，旧 `items / resultSummary` 形态必须校验失败；确认 `previewPackagingPlan()` 和 `savePackagingPlan()` 都继续复用 `materializePackagingPlanForPersistence()`，并在测试里固定断言返回与持久化结果中的 `boxes[0].materials`、`estimatedWeightKg`、`estimatedCost`、`costSummary.totalCost`、`costSummary.totalWeightKg`。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath src/app/api/pre-skus/[id]/packaging/route.test.ts src/server/services/__tests__/draft-group.service.test.ts</automated>
-  </verify>
-  <done>包装保存、试算、读取这三段都固定在新结构上，后续包装 UI 再接入时不会把旧结构重新带回来。</done>
-</task>
-
-<task type="auto" tdd="true">
-  <name>Task 2: 锁定正式入库对包装结果的准入和承接</name>
-  <files>src/server/services/intake.service.ts, src/server/services/__tests__/intake.service.test.ts</files>
-  <read_first>
-    src/server/services/intake.service.ts
-    src/server/services/__tests__/intake.service.test.ts
-    prisma/schema.prisma
-    src/server/services/draft-group.service.ts
-  </read_first>
-  <acceptance_criteria>
-    - `src/server/services/__tests__/intake.service.test.ts` 包含“无有效包装箱不能入库”和“有 `boxes[]` 时会生成 `PackagedItem`”的断言。
-    - `src/server/services/intake.service.ts` 仍通过 `hasValidPackagingBoxes` 或等价显式逻辑判断准 SKU 是否可正式入库，没有新增页面兜底绕过。
-    - `src/server/services/intake.service.ts` 创建 `PackagedItem` 时 payload 内包含 `boxNumber`、`outerSizeMm`、`materials`、`costSummary`。
-  </acceptance_criteria>
-  <action>收紧正式入库测试和承接口径：明确 `ensurePreSkuReadyForFormalization()` 必须继续以“存在有效包装箱”为准入条件；在 `intake.service.test.ts` 固定断言 `formalizeDraftGroup()` 对没有 `boxes[]` 的 `PreSkuPackagingPlan` 直接报错，对有 `boxes[]` 的 `PreSkuPackagingPlan` 会创建 `PackagedItem`，并把 `boxNumber`、`outerSizeMm`、`materials`、`costSummary` 写入 payload。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath src/server/services/__tests__/intake.service.test.ts</automated>
-  </verify>
-  <done>包装结果到正式入库的承接链被测试守住，后续即使包装线继续开发，也不容易把主线准入规则改坏。</done>
-</task>
-
-</tasks>
-
-<verification>
-至少跑通包装路由测试、草稿组包装服务测试和正式入库测试，确认包装结果在保存、试算、入库三段中的结构一致。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`MAIN-04` 在主线侧被收口为：`PreSku` 的包装结果能稳定保存、稳定试算、稳定承接到正式入库，而且这条链只认一套新结构。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/03-包装接缝稳定化/03-01-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/03-包装接缝稳定化/03-01-SUMMARY.md

@@ -1,80 +0,0 @@
----
-phase: 03-包装接缝稳定化
-plan: 01
-subsystem: api
-tags: [packaging, pre-sku, intake, tests, boxes]
-requires:
-  - phase: 02-资产到草稿组主链收口
-    provides: 候选到 PreSku 的稳定主链
-provides:
-  - 包装保存/试算/入库承接测试闭环
-  - 正式入库对包装结果的准入保护
-affects: [phase-04, packaging-ui, intake]
-tech-stack:
-  added: []
-  patterns:
-    - 包装新结构只认 boxes/costSummary/processDraft
-    - 正式入库以有效包装箱为唯一准入前提
-key-files:
-  created:
-    - .planning/phases/03-包装接缝稳定化/03-01-SUMMARY.md
-  modified:
-    - src/server/services/__tests__/intake.service.test.ts
-key-decisions:
-  - "修测试而不是重改主线逻辑，因为当前真实问题是测试底座落后于已存在的入库承接实现。"
-patterns-established:
-  - "包装链守护模式：路由、草稿组包装服务、正式入库三段一起跑回归测试。"
-requirements-completed: [MAIN-04]
-duration: 20min
-completed: 2026-04-02
----
-
-# Phase 3 Plan 01 Summary
-
-**包装保存、试算和正式入库承接现在由同一组测试守住，主线继续只认 `boxes / costSummary / processDraft` 新结构。**
-
-## Performance
-
-- **Duration:** 20 min
-- **Started:** 2026-04-02T21:50:00+08:00
-- **Completed:** 2026-04-02T22:10:00+08:00
-- **Tasks:** 2
-- **Files modified:** 1
-
-## Accomplishments
-
-- 补齐了 `intake.service.test.ts` 的事务 mock，使其覆盖当前真实的板件、孔位、五金、包装方案与包装成品承接流程。
-- 跑通包装路由、草稿组包装服务、正式入库三组关键测试，确认主线仍只认新包装结构。
-- 固定了正式入库承接断言：`PackagedItem` payload 必须带 `boxNumber / outerSizeMm / materials / costSummary`。
-
-## Task Commits
-
-未创建提交。当前仓库仍保持本地未提交工作状态。
-
-## Files Created/Modified
-
-- `src/server/services/__tests__/intake.service.test.ts` - 补齐正式入库事务 mock 和包装承接断言
-
-## Decisions Made
-
-- 继续保留现有主线实现，不为了“让测试过”去回退已存在的 `panel / productHardware / packagingPlan / packagedItem` 承接逻辑。
-
-## Deviations from Plan
-
-None - plan executed exactly as written.
-
-## Issues Encountered
-
-- `intake.service.test.ts` 的 mock 没有覆盖新增的事务写入点，导致测试先于业务逻辑报错；已修正为与当前实现对齐。
-
-## User Setup Required
-
-None - no external service configuration required.
-
-## Next Phase Readiness
-
-- 包装结果主线承接已经被测试守住，可以继续做协作边界和占位入口口径收口。
-
----
-*Phase: 03-包装接缝稳定化*
-*Completed: 2026-04-02*

furniture-3d-system/.planning/phases/03-包装接缝稳定化/03-02-PLAN.md

@@ -1,145 +0,0 @@
----
-phase: 03-包装接缝稳定化
-plan: 02
-type: execute
-wave: 1
-depends_on:
-  - 03-01
-files_modified:
-  - docs/workflow/模块边界说明.md
-  - docs/workflow/团队协作模式.md
-  - docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md
-  - ../docs/前端UI改动清单.md
-  - src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
-autonomous: true
-requirements:
-  - COLL-03
-must_haves:
-  truths:
-    - "包装线默认能读共享接缝，但不能把 `draft-group / intake / schema.prisma` 当作自己的自由改动区。"
-    - "当前草稿组详情页里的包装区只是主线占位入口，不冒充最终包装工作区。"
-    - "前端 agent 和包装 agent 拿到的交接口径一致，不会一边按旧结构做，一边按新结构收口。"
-  artifacts:
-    - path: "docs/workflow/模块边界说明.md"
-      provides: "共享接缝与禁止越界边界"
-      contains: "包装协作边界"
-    - path: "docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md"
-      provides: "给同事 AI 的固定对接口径"
-      contains: "不要碰什么"
-    - path: "../docs/前端UI改动清单.md"
-      provides: "前端对草稿组包装区和自动组合联调的固定说明"
-      contains: "包装占位|真正包装工作区"
-  key_links:
-    - from: "src/app/draft-groups/[id]/DraftGroupDetailClient.tsx"
-      to: "../docs/前端UI改动清单.md"
-      via: "主线占位入口与最终包装工作区职责分离"
-      pattern: "包装方案|占位"
-    - from: "docs/workflow/团队协作模式.md"
-      to: "docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md"
-      via: "团队协作规则与同事 AI 固定口径一致"
-      pattern: "codex/xuxiake-packaging"
----
-
-<objective>
-把包装线和主线的共享接缝规则、占位入口口径和前端联调边界固定下来，避免后续协作再次混乱。
-
-Purpose: 按 `COLL-03` 修根因，避免共享文件被误改、草稿组占位页被误当正式包装工作区、以及前端/包装 agent 围绕旧结构继续开发。
-Output: 更新后的协作文档、对同事 AI 的固定说明，以及必要时更明确的主线占位文案。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/03-包装接缝稳定化/03-CONTEXT.md
-@docs/workflow/团队协作模式.md
-@docs/workflow/模块边界说明.md
-@docs/workflow/同事交接模板.md
-@docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md
-@../docs/前端UI改动清单.md
-@src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
-
-<interfaces>
-From `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx`:
-
-```tsx
-<AccordionSection
-  title="包装方案"
-  description="按准 SKU 保存包装占位，后续包装模块可继续增强。"
->
-```
-```
-</interfaces>
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: 固定共享接缝协作文档口径</name>
-  <files>docs/workflow/团队协作模式.md, docs/workflow/模块边界说明.md, docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md</files>
-  <read_first>
-    docs/workflow/团队协作模式.md
-    docs/workflow/模块边界说明.md
-    docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md
-    .planning/phases/03-包装接缝稳定化/03-CONTEXT.md
-    src/server/services/pre-sku-packaging.service.ts
-    src/server/services/intake.service.ts
-  </read_first>
-  <acceptance_criteria>
-    - `docs/workflow/模块边界说明.md` 明确写出 `draft-group.service.ts`、`draft-group.repository.ts`、`intake.service.ts`、`prisma/schema.prisma`、`src/app/draft-groups/[id]` 是包装线“可读但不默认直改”的共享接缝。
-    - `docs/workflow/团队协作模式.md` 明确写出主线当前包装区只是承接口，不是包装线独立顶层系统。
-    - `docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md` 明确写出当前草稿组包装区是最小联通版占位，包装线不要把它当最终工作区重写主线契约。
-  </acceptance_criteria>
-  <action>统一三份文档口径：明确包装线默认工作域是 `src/app/api/pre-skus/[id]/packaging`、`src/server/services/packaging.service.ts`、`src/server/repositories/packaging.repository.ts` 及包装文档目录；共享接缝固定列出 `draft-group.service.ts`、`draft-group.repository.ts`、`intake.service.ts`、`prisma/schema.prisma`、`src/app/draft-groups/[id]`；文档中直接写明草稿组详情页包装区只是“主线最小联通版占位入口”，最终包装工作区由包装线独立增强，但不能改坏 `PreSkuPackagingPlan`、`boxes[]`、`costSummary`、`processDraft` 现有契约。</action>
-  <verify>
-    <automated>rg -n "最小联通版占位|共享接缝|可读但不默认直改|boxes\\[\\]|processDraft" docs/workflow/团队协作模式.md docs/workflow/模块边界说明.md docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md</automated>
-  </verify>
-  <done>团队文档、同事 AI 说明和主线当前实现口径一致，后续协作不会再因为“这个页面是不是最终包装工作区”而跑偏。</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 固定前端占位与联调边界说明</name>
-  <files>../docs/前端UI改动清单.md, src/app/draft-groups/[id]/DraftGroupDetailClient.tsx</files>
-  <read_first>
-    ../docs/前端UI改动清单.md
-    src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
-    docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md
-  </read_first>
-  <acceptance_criteria>
-    - `../docs/前端UI改动清单.md` 包含“草稿组详情包装区只是占位入口，不是真正包装工作区”的明确交接说明。
-    - 如果修改 `DraftGroupDetailClient.tsx`，其文案必须直接出现“占位”或等价明确表达，避免前端误解为最终包装模块。
-    - 文档中明确区分：结构契约问题归后端 / 主线，视觉和交互落地归前端或包装 agent。
-  </acceptance_criteria>
-  <action>在 `../docs/前端UI改动清单.md` 追加草稿组详情页包装区说明：当前页面只负责按 `PreSku` 保存最小包装占位并验证主线能读写 `PreSkuPackagingPlan`，不是最终包装子工作区；联调时如果发现 `boxes[] / costSummary / processDraft / packagingInput` 缺失或与正式入库承接不一致，归后端主线；如果只是布局、动效、表单体验、材料选择器界面问题，归前端或包装 agent。视现有文案是否足够，再决定是否在 `DraftGroupDetailClient.tsx` 的包装区描述里补一句“后续包装模块继续增强，此处仅为主线占位入口”。</action>
-  <verify>
-    <automated>rg -n "占位入口|真正包装工作区|boxes\\[\\]|costSummary|processDraft|packagingInput" ../docs/前端UI改动清单.md src/app/draft-groups/[id]/DraftGroupDetailClient.tsx</automated>
-  </verify>
-  <done>前端和包装线后续接手时会先知道当前页面只是占位入口，避免直接在主线页面里堆出完整包装系统。</done>
-</task>
-
-</tasks>
-
-<verification>
-通过文档关键字校验和必要的页面文案检查，确认共享接缝口径、占位入口口径和联调边界都已落盘。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`COLL-03` 在主线侧被收口为：包装线可以继续开发，但不会默认直改共享接缝，也不会把主线占位页误当成最终包装系统。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/03-包装接缝稳定化/03-02-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/03-包装接缝稳定化/03-02-SUMMARY.md

@@ -1,91 +0,0 @@
----
-phase: 03-包装接缝稳定化
-plan: 02
-subsystem: api
-tags: [collaboration, packaging, docs, boundaries, ui-handoff]
-requires:
-  - phase: 03-包装接缝稳定化
-    provides: 包装新结构已稳定承接
-provides:
-  - 包装线共享接缝协作口径
-  - 草稿组包装区占位入口说明
-  - 前端/包装 agent 联调分流规则
-affects: [phase-04, packaging-collab, frontend-handoff]
-tech-stack:
-  added: []
-  patterns:
-    - 共享接缝先对齐再改
-    - 主线占位入口不冒充最终包装工作区
-key-files:
-  created:
-    - .planning/phases/03-包装接缝稳定化/03-02-SUMMARY.md
-  modified:
-    - docs/workflow/团队协作模式.md
-    - docs/workflow/模块边界说明.md
-    - docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md
-    - ../docs/前端UI改动清单.md
-    - src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
-key-decisions:
-  - "草稿组详情页包装区明确定义为主线占位入口，不再允许被误解为最终包装工作区。"
-  - "包装线补 UI/材料选择/最低成本方案时，不默认落在 draft-group/intake/schema 这些共享接缝里实现。"
-patterns-established:
-  - "协作分流模式：结构契约问题归主线后端，视觉与交互问题归前端或包装 agent。"
-requirements-completed: [COLL-03]
-duration: 20min
-completed: 2026-04-02
----
-
-# Phase 3 Plan 02 Summary
-
-**包装线和主线的共享接缝规则、占位入口口径和联调边界现在已经固定到文档和页面文案里。**
-
-## Performance
-
-- **Duration:** 20 min
-- **Started:** 2026-04-02T22:10:00+08:00
-- **Completed:** 2026-04-02T22:30:00+08:00
-- **Tasks:** 2
-- **Files modified:** 5
-
-## Accomplishments
-
-- 在团队协作文档里明确了包装线默认边界，以及草稿组详情页包装区只是主线最小联通版占位入口。
-- 在给同事 AI 的包装底座说明里明确了：不要把主线占位区当成最终包装工作区去重写共享契约。
-- 在前端交接清单里补了草稿组包装区的固定口径和联调分流规则。
-
-## Task Commits
-
-未创建提交。当前仓库仍保持本地未提交工作状态。
-
-## Files Created/Modified
-
-- `docs/workflow/团队协作模式.md` - 固定包装线与主线协作边界
-- `docs/workflow/模块边界说明.md` - 固定共享接缝和占位入口说明
-- `docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md` - 固定给同事 AI 的接缝口径
-- `../docs/前端UI改动清单.md` - 固定前端联调分流规则
-- `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx` - 页面文案明确为主线包装占位
-
-## Decisions Made
-
-- 页面文案只做最小必要修改，不直接把草稿组详情页改造成完整包装工作区。
-
-## Deviations from Plan
-
-None - plan executed exactly as written.
-
-## Issues Encountered
-
-- 无代码级阻塞；主要工作是把已经确认的边界从口头/会话规则落盘到正式协作文档。
-
-## User Setup Required
-
-None - no external service configuration required.
-
-## Next Phase Readiness
-
-- Phase 3 已完成，包装接缝和协作边界已经稳定。
-- 下一步可以进入 Phase 4，专注正式入库与轻仓库闭环，而不是再回头解释包装接缝规则。
-
----
-*Phase: 03-包装接缝稳定化*
-*Completed: 2026-04-02*

furniture-3d-system/.planning/phases/03-包装接缝稳定化/03-CONTEXT.md

@@ -1,137 +0,0 @@
-# Phase 3: 包装接缝稳定化 - Context
-
-**Gathered:** 2026-04-02
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-本阶段只做“包装线与主线共享接缝”的稳定化，不直接代做同事负责的包装方案业务本体。目标是让 `PreSku` 的包装结果能够稳定保存、稳定传递到正式入库，同时把共享文件的改动边界和协作规则固定住，避免后面主线和包装线互相打架。
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### 范围与职责
-- **D-01:** Phase 3 聚焦 `MAIN-04` 与 `COLL-03`，只收口包装接缝、保存链路、入库承接和协作边界。
-- **D-02:** 包装方案 UI、包装材料选择、最低成本方案、工艺图组合占位仍由同事 `xuxiake` 负责；主线当前不代做这些业务层实现。
-- **D-03:** 本阶段不回头扩写自动组合规则、资产中心规则或旧 CAD 兼容链。
-
-### 当前后端真相
-- **D-04:** `PreSkuPackagingPlan` 已经是新平台包装结果真相对象，主结构锁定为 `sourceType / sourceRefId / status / boxes / costSummary / processDraft / notes`。
-- **D-05:** `GET /api/pre-skus/[id]/packaging` 返回 `packagingPlan + packagingInput`，前端不应自己重拼包装输入。
-- **D-06:** `PUT /api/pre-skus/[id]/packaging` 只接受新结构；旧的 `items / resultSummary` 不能再作为新平台入口契约。
-- **D-07:** 正式入库已经按 `boxes[]` 生成 `PackagedItem`，说明包装结果到入库承接链已存在，不需要再发明第二条包装落库路径。
-
-### 共享接缝与敏感区
-- **D-08:** 当前最敏感的共享接缝固定是：`draft-group.service.ts`、`draft-group.repository.ts`、`intake.service.ts`、`prisma/schema.prisma`、`src/app/draft-groups/[id]`。
-- **D-09:** 这些接缝文件后续如果要被包装线修改，必须先在任务里写清“为什么非改不可”，不能因为包装 UI 要求就直接重写主线对象结构。
-- **D-10:** Phase 3 如果要做主线改动，优先做“边界稳定”和“契约补齐”，不做包装线本体的体验优化。
-
-### 状态推进规则
-- **D-11:** `PreSku` 保存包装结果后，草稿组状态通过 `draftGroupStateService` 在 `PACKAGING / READY_FOR_INTAKE / FORMALIZED` 之间推进；这条状态链必须继续保持单一真相。
-- **D-12:** 正式入库前的准入规则继续依赖“是否存在有效包装箱”，不能被包装线 UI 绕开。
-
-### 协作规则
-- **D-13:** `xuxiake` 长期包装分支固定为 `codex/xuxiake-packaging`，同步 `main` 固定用 `merge main`；这不是建议，是固定协作口径。
-- **D-14:** 包装线默认可以读共享接缝，但不默认拥有这些文件的自由修改权。
-- **D-15:** 主线负责人后续收口包装改动时，优先按小任务合并或手工收口，不一次吞并长期积压改动。
-
-### the agent's Discretion
-- Phase 3 先做“文档和计划收口”，还是先补主线侧接缝防护测试，由 agent 根据现有代码脆弱点决定。
-- 如果发现共享接缝已经有明显架构风险，是否先插一个小 plan 做守护性重构，由 agent 在不越过包装业务本体的前提下决定。
-
-</decisions>
-
-<specifics>
-## Specific Ideas
-
-- 包装底座当前已经具备：
-  - `packagingInput` 自动派生
-  - `boxes[]` 保存与试算
-  - 从资产中心读取 `PACKAGING` 资产族与规格款
-  - 正式入库按 `boxes[]` 生成 `PackagedItem`
-- 当前草稿组详情页只是“最小联通版包装占位”，不是最终包装工作区。
-- 当前真正容易反复打架的，不是接口有没有，而是：
-  - 包装线会不会反向改 `DraftGroup / PreSku / Intake` 契约
-  - 主线会不会在未对齐情况下继续扩共享模型
-  - 前端会不会为了联调顺手兜底旧结构
-
-</specifics>
-
-<canonical_refs>
-## Canonical References
-
-**Downstream agents MUST read these before planning or implementing.**
-
-### 项目级约束
-- `.planning/PROJECT.md`
-- `.planning/ROADMAP.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/STATE.md`
-
-### 协作与边界
-- `../AGENTS.md`
-- `docs/workflow/团队协作模式.md`
-- `docs/workflow/模块边界说明.md`
-- `docs/workflow/主线同步操作手册.md`
-- `docs/workflow/同事交接模板.md`
-- `docs/workflow/同事本地AGENTS模板.md`
-- `docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md`
-
-### 主线侧包装接缝
-- `src/server/services/draft-group.service.ts`
-- `src/server/services/draft-group.service.types.ts`
-- `src/server/services/pre-sku-packaging.service.ts`
-- `src/server/services/packaging-plan-calculator.ts`
-- `src/server/services/draft-group-state.service.ts`
-- `src/server/services/intake.service.ts`
-- `src/server/repositories/draft-group.repository.ts`
-- `src/app/api/pre-skus/[id]/packaging/route.ts`
-- `src/app/api/pre-skus/[id]/packaging/preview/route.ts`
-- `src/app/api/pre-skus/[id]/packaging/material-options/route.ts`
-- `src/app/api/platform/schemas.ts`
-- `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx`
-- `src/lib/open-product/platform-api.ts`
-
-### 数据模型
-- `prisma/schema.prisma`
-
-</canonical_refs>
-
-<code_context>
-## Existing Code Insights
-
-### Reusable Assets
-- `preSkuPackagingService` 已经把包装上下文读取、材料资产读取、保存、试算串起来。
-- `materializePackagingPlanForPersistence()` 已经把箱内项、包装材料、重量、体积、成本汇总逻辑收口成单独计算层。
-- `intakeService.formalizeDraftGroup()` 已经消费 `packagingPlan.boxes` 并生成正式 `PackagingPlan + PackagedItem`。
-
-### Established Patterns
-- 新平台主链继续遵守 `Route -> Service -> Repository -> Prisma`。
-- 包装结果在 `PreSkuPackagingPlan` 落真相，正式入库再承接，不允许直接绕过 `PreSku` 去创建正式包装成品。
-- 包装状态推进由主线状态服务统一处理，不靠前端页面自己判断。
-
-### Integration Points
-- `draft-group.service.ts` 是包装线和主线之间最核心的服务接缝。
-- `DraftGroupDetailClient.tsx` 是当前最小联通前端接点，但不是最终包装工作区。
-- `schema.prisma` 中的 `PreSku / PreSkuPackagingPlan / PackagedItem / ProductSKU` 是一组联动模型，任一处字段调整都会影响上下游。
-
-</code_context>
-
-<deferred>
-## Deferred Ideas
-
-- 包装子工作区最终 UI 设计与交互实现
-- 最低成本方案生成算法
-- 工艺图组合真正实现
-- 正式产品级 `PackagingPlan` 进一步重构
-- 包装域的更完整成本、体积、材料扩展（作为 v2 的 `PACK-01 / PACK-02`）
-
-</deferred>
-
----
-
-*Phase: 03-包装接缝稳定化*
-*Context gathered: 2026-04-02*

furniture-3d-system/.planning/phases/03-包装接缝稳定化/03-DISCUSSION-LOG.md

@@ -1,57 +0,0 @@
-# Phase 3: 包装接缝稳定化 - Discussion Log
-
-> **Audit trail only.** Do not use as input to planning, research, or execution agents.
-> Decisions captured in CONTEXT.md — this log preserves the source discussion and code reconnaissance.
-
-**Date:** 2026-04-02
-**Phase:** 03-包装接缝稳定化
-**Mode:** direct capture from code reconnaissance + existing workflow docs
-**Areas analyzed:** 包装协作边界, 共享接缝, 包装保存链路, 正式入库承接
-
-## User Clarifications Captured
-
-### 职责边界
-| Clarification | Confidence | Source |
-|------------|-----------|----------|
-| 包装和包装方案由同事负责，主线当前不用代做。 | Confirmed | User explicit instruction on 2026-04-02 |
-| 主线后续如果需要动前端，不由当前 agent 直接做，而是写到前端交接文档。 | Confirmed | User explicit instruction on 2026-04-02 |
-
-## Code Reconnaissance Findings
-
-### 包装底座现状
-| Finding | Confidence | Evidence |
-|------------|-----------|----------|
-| `preSkuPackagingService` 已经提供包装上下文读取、材料规格读取、保存和试算能力。 | Confident | `src/server/services/pre-sku-packaging.service.ts` |
-| 包装成本、重量、体积计算已经独立收口到 `materializePackagingPlanForPersistence()`。 | Confident | `src/server/services/packaging-plan-calculator.ts` |
-| 包装接口当前走 `GET/PUT /api/pre-skus/[id]/packaging`，并复用 `savePreSkuPackagingPlanSchema`。 | Confident | `src/app/api/pre-skus/[id]/packaging/route.ts`, `src/app/api/platform/schemas.ts` |
-
-### 主线共享接缝
-| Finding | Confidence | Evidence |
-|------------|-----------|----------|
-| 草稿组详情页当前已经能保存包装占位，但这是最小联通版，不是最终包装工作区。 | Confident | `src/app/draft-groups/[id]/DraftGroupDetailClient.tsx` |
-| 入库服务当前直接消费 `PreSku.packagingPlan.boxes` 并生成 `PackagedItem`。 | Confident | `src/server/services/intake.service.ts` |
-| `schema.prisma` 里 `PreSku`、`PreSkuPackagingPlan`、`PackagedItem`、`ProductSKU` 已形成联动模型。 | Confident | `prisma/schema.prisma` |
-
-### 协作风险
-| Finding | Confidence | Evidence |
-|------------|-----------|----------|
-| 当前最大的协作风险不是“包装底座缺失”，而是包装线误改 `draft-group / intake / schema.prisma` 这些共享接缝。 | Confident | workflow docs + current code topology |
-| 当前文档已经明确这些文件不是包装线默认自由修改区，但 `.planning` 里还缺少 Phase 3 的正式上下文。 | Confident | `docs/workflow/模块边界说明.md`, `.planning/STATE.md` |
-
-## Corrections Made
-
-- 修正了“Phase 3 可能要继续搭包装底座”的判断。真实情况是底座已存在，下一步重点应是接缝稳定化和协作边界固化。
-- 修正了“包装问题主要在 UI 层”的判断。真实更敏感的是共享模型、状态推进与正式入库承接链。
-
-## Open Technical Gaps Identified
-
-- 共享接缝是否还缺守护性测试，特别是包装保存后草稿组状态推进与正式入库承接之间的回归保护。
-- 草稿组详情页当前的最小包装占位是否需要进一步标注“仅占位，不是真正包装工作区”，避免包装线误把它当最终入口。
-- `REQUIREMENTS.md` 中 Phase 2 已完成项还需要回写状态，避免后续规划误判主链进度。
-
-## Scope Reminder
-
-- 本阶段不直接做包装方案业务 UI。
-- 本阶段不直接做最低成本算法。
-- 本阶段不扩写自动组合和资产中心。
-- 本阶段优先收口共享接缝、状态链和协作边界。

furniture-3d-system/.planning/phases/04-正式入库与轻仓库闭环/04-01-PLAN.md

@@ -1,164 +0,0 @@
----
-phase: 04-正式入库与轻仓库闭环
-plan: 01
-type: execute
-wave: 1
-depends_on: []
-files_modified:
-  - src/server/services/intake.service.ts
-  - src/server/services/intake.service.types.ts
-  - src/server/services/__tests__/intake.service.test.ts
-  - src/app/api/platform/schemas.ts
-  - src/app/intake/IntakeClient.tsx
-  - ../docs/前端UI改动清单.md
-autonomous: true
-requirements:
-  - MAIN-05
-must_haves:
-  truths:
-    - "正式入库继续只从 `DraftGroup / PreSku` 进入，不允许绕过草稿组直接造正式 `Product / SKU`。"
-    - "`formalizeDraftGroup()` 是 Phase 4 的正式入库唯一主链入口，补强应围绕现有实现收口，而不是另起第二套流程。"
-    - "正式入库结果必须稳定落成 `Product / ProductSKU / PackagingPlan / PackagedItem`，并且对失败场景给出明确可测试的校验。"
-  artifacts:
-    - path: "src/server/services/intake.service.ts"
-      provides: "正式入库编排、校验、正式对象创建"
-      contains: "formalizeDraftGroup|ensurePreSkuReadyForFormalization"
-    - path: "src/server/services/__tests__/intake.service.test.ts"
-      provides: "正式入库主链回归保护"
-      contains: "formalizeDraftGroup"
-    - path: "src/app/api/platform/schemas.ts"
-      provides: "正式入库输入 DTO 校验"
-      contains: "formalizeDraftGroupSchema"
-  key_links:
-    - from: "src/app/intake/IntakeClient.tsx"
-      to: "src/server/services/intake.service.ts"
-      via: "正式入库页提交的字段必须与服务层契约一致"
-      pattern: "formalizeDraftGroup"
-    - from: "src/server/services/intake.service.ts"
-      to: "prisma/schema.prisma"
-      via: "正式入库承接到 Product / ProductSKU / PackagingPlan / PackagedItem"
-      pattern: "productSKU|packagingPlan|packagedItem"
----
-
-<objective>
-把草稿组/准 SKU 到正式 `Product / SKU` 的入库链收口成稳定、可验证、可回归的主线能力。
-
-Purpose: 按 `MAIN-05` 修根因，避免正式入库虽然“能跑通”，但在多准 SKU、挂已有 SPU、包装承接、失败校验这些关键场景下仍不稳定。
-Output: 更稳的正式入库服务契约、关键测试覆盖，以及必要的前端联调说明。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/04-正式入库与轻仓库闭环/04-CONTEXT.md
-@.planning/phases/03-包装接缝稳定化/03-CONTEXT.md
-@src/app/intake/page.tsx
-@src/app/intake/IntakeClient.tsx
-@src/app/api/intake/formalize/route.ts
-@src/app/api/platform/schemas.ts
-@src/lib/open-product/platform-api.ts
-@src/server/services/intake.service.ts
-@src/server/services/intake.service.types.ts
-@src/server/services/__tests__/intake.service.test.ts
-@prisma/schema.prisma
-
-<interfaces>
-From `src/server/services/intake.service.types.ts`:
-
-```ts
-export interface FormalizeDraftGroupInput {
-  draftGroupId: string
-  targetMode: 'CREATE_PRODUCT' | 'ATTACH_PRODUCT'
-  productId?: string
-  modelNumber?: string
-  productName?: string
-  skuItems: Array<{
-    preSkuId: string
-    skuCode?: string
-    skuName?: string
-    initialStock?: number
-    warehouseLocationId?: string | null
-  }>
-}
-```
-
-From `src/server/services/intake.service.ts`:
-
-```ts
-async formalizeDraftGroup(input: FormalizeDraftGroupInput, user: AuthUser)
-function ensurePreSkuReadyForFormalization(preSku, draftGroupId: string)
-```
-</interfaces>
-</context>
-
-<tasks>
-
-<task type="auto" tdd="true">
-  <name>Task 1: 收紧正式入库校验与服务回归测试</name>
-  <files>src/server/services/intake.service.ts, src/server/services/intake.service.types.ts, src/server/services/__tests__/intake.service.test.ts</files>
-  <read_first>
-    src/server/services/intake.service.ts
-    src/server/services/intake.service.types.ts
-    src/server/services/__tests__/intake.service.test.ts
-    prisma/schema.prisma
-  </read_first>
-  <acceptance_criteria>
-    - `intake.service.test.ts` 覆盖“新建 SPU”“挂已有 SPU”“同一次入库重复选择同一 preSku”“已 FORMALIZED / ARCHIVED preSku 不可重复入库”“无有效包装箱不可入库”等关键场景。
-    - `intake.service.ts` 中正式入库失败原因继续在 service 层显式校验，而不是让 route 或页面兜底。
-    - 成功入库时，测试能证明会创建正式 `ProductSKU`，并承接包装成品与状态推进结果。
-  </acceptance_criteria>
-  <action>补齐并收紧 `formalizeDraftGroup()` 的回归测试，优先围绕 Phase 4 真正影响主链稳定性的场景：单次多准 SKU 正式入库、挂已有 SPU 时的合法性、重复选择同一 `preSkuId` 的拦截、已经 `FORMALIZED` 或 `ARCHIVED` 的准 SKU 拦截、无有效包装箱拦截，以及成功后 `draftGroup` 状态的推进。必要时小幅重构 `intake.service.ts` 的局部逻辑，让校验和对象创建更可测试，但不改变“从 `PreSku` 承接正式对象”的主真相。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath src/server/services/__tests__/intake.service.test.ts</automated>
-  </verify>
-  <done>正式入库主链具备稳定可回归的失败/成功断言，后续执行 Phase 4 其他计划时不会反复担心基础入库逻辑漂移。</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 固定正式入库前端联调契约</name>
-  <files>src/app/api/platform/schemas.ts, src/app/intake/IntakeClient.tsx, ../docs/前端UI改动清单.md</files>
-  <read_first>
-    src/app/api/platform/schemas.ts
-    src/app/intake/IntakeClient.tsx
-    src/lib/open-product/platform-api.ts
-    ../docs/前端UI改动清单.md
-  </read_first>
-  <acceptance_criteria>
-    - `formalizeDraftGroupSchema` 与 `IntakeClient` 实际提交字段保持一致，不出现“页面可填但接口不认”或“接口要求但页面没传”的漂移。
-    - 如果发现需要前端 UI 配合，只追加到 `../docs/前端UI改动清单.md`，不在本计划里直接大改前端实现。
-    - 入库页当前文案或交互若会误导用户绕过主链，应在最小范围内修正或明确记录给前端 agent。
-  </acceptance_criteria>
-  <action>核对 `IntakeClient`、`platform-api.ts`、`formalizeDraftGroupSchema` 三处正式入库契约是否完全一致；如果存在缺口，只做主链所需的最小修正。任何需要独立前端 agent 处理的体验问题，统一写进 `../docs/前端UI改动清单.md`，例如：多准 SKU 预览切换、成功态跳转反馈、挂已有 SPU 时的推荐选择体验等。</action>
-  <verify>
-    <automated>rg -n "formalizeDraftGroup|targetMode|warehouseLocationId|initialStock|skuItems" src/app/intake/IntakeClient.tsx src/app/api/platform/schemas.ts src/lib/open-product/platform-api.ts ../docs/前端UI改动清单.md</automated>
-  </verify>
-  <done>正式入库页和后端契约一致，前端需要继续做的内容也被明确分流给 UI agent。</done>
-</task>
-
-</tasks>
-
-<verification>
-至少跑通正式入库服务测试，并用关键字校验确认前端联调契约一致。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`MAIN-05` 在主线侧被收口为：草稿组/准 SKU 能稳定转成正式 `Product / SKU`，并且这条链有足够测试与契约保护。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/04-正式入库与轻仓库闭环/04-01-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/04-正式入库与轻仓库闭环/04-01-SUMMARY.md

@@ -1,87 +0,0 @@
----
-phase: 04-正式入库与轻仓库闭环
-plan: 01
-subsystem: api
-tags: [intake, formalization, validation, tests, ui-handoff]
-requires:
-  - phase: 03-包装接缝稳定化
-    provides: 包装结果新结构与正式入库承接已稳定
-provides:
-  - 正式入库关键失败场景回归保护
-  - 正式入库前后端契约收紧
-  - 前端正式入库联调口径补充
-affects: [phase-04, intake, warehouse, frontend-handoff]
-tech-stack:
-  added: []
-  patterns:
-    - 正式入库前置校验继续留在 service 层
-    - ATTACH_PRODUCT / CREATE_PRODUCT 契约前移到 schema
-key-files:
-  created:
-    - .planning/phases/04-正式入库与轻仓库闭环/04-01-SUMMARY.md
-  modified:
-    - src/app/api/platform/schemas.ts
-    - src/server/services/__tests__/intake.service.test.ts
-    - ../docs/前端UI改动清单.md
-key-decisions:
-  - "不重写 intake 主链，而是补齐正式入库关键失败场景测试与 schema 契约。"
-  - "前端 UI 继续交给独立 agent，主线只补正式入库联调口径。"
-patterns-established:
-  - "正式入库守护模式：service 回归测试 + schema 契约校验 + 前端联调清单三段一起收口。"
-requirements-completed: [MAIN-05]
-duration: 20min
-completed: 2026-04-02
----
-
-# Phase 4 Plan 01 Summary
-
-**正式入库主链现在补上了更关键的失败场景保护，并把挂已有 SPU / 新建 SPU 的契约前移到了 schema。**
-
-## Performance
-
-- **Duration:** 20 min
-- **Started:** 2026-04-02T23:10:00+08:00
-- **Completed:** 2026-04-02T23:30:00+08:00
-- **Tasks:** 2
-- **Files modified:** 3
-
-## Accomplishments
-
-- 补齐了正式入库关键失败场景测试，覆盖目标产品不存在、库位不存在、新建 SPU 模式等主链风险点。
-- 收紧了 `formalizeDraftGroupSchema`，明确 `ATTACH_PRODUCT` 必须传 `productId`，`CREATE_PRODUCT` 不允许混传 `productId`。
-- 在前端交接清单里补了正式入库联调口径，明确两种入库模式要分开确认，且多准 SKU 首入库要按一次提交的主链口径联调。
-
-## Task Commits
-
-未创建提交。当前仓库仍保持本地未提交工作状态。
-
-## Files Created/Modified
-
-- `src/app/api/platform/schemas.ts` - 收紧正式入库 schema 契约
-- `src/server/services/__tests__/intake.service.test.ts` - 补齐正式入库关键回归测试
-- `../docs/前端UI改动清单.md` - 补正式入库的前端联调说明
-
-## Decisions Made
-
-- 继续保留 `intakeService.formalizeDraftGroup()` 作为正式入库唯一主链入口，不为 Phase 4 另起第二套正式入库流程。
-
-## Deviations from Plan
-
-None - plan executed exactly as written.
-
-## Issues Encountered
-
-- 无阻塞性问题；现有 intake 主链本身可用，主要缺口在关键测试覆盖和 schema 契约没有前移。
-
-## User Setup Required
-
-None - no external service configuration required.
-
-## Next Phase Readiness
-
-- `MAIN-05` 已做第一轮正式收口，正式入库主链更稳定。
-- 下一步可以进入 `04-02`，收口轻仓库 overview 和入库后结果可见性闭环。
-
----
-*Phase: 04-正式入库与轻仓库闭环*
-*Completed: 2026-04-02*

furniture-3d-system/.planning/phases/04-正式入库与轻仓库闭环/04-02-PLAN.md

@@ -1,137 +0,0 @@
----
-phase: 04-正式入库与轻仓库闭环
-plan: 02
-type: execute
-wave: 1
-depends_on:
-  - 04-01
-files_modified:
-  - src/server/services/warehouse.service.ts
-  - src/server/services/warehouse.service.types.ts
-  - src/server/repositories/warehouse.repository.ts
-  - src/app/api/warehouse/route.ts
-  - src/app/warehouse/WarehouseClient.tsx
-  - ../docs/前端UI改动清单.md
-autonomous: true
-requirements:
-  - MAIN-06
-must_haves:
-  truths:
-    - "轻仓库仍是正式入库后的轻量闭环页，不是完整 WMS。"
-    - "轻仓库必须能直接看见正式入库产出的正式 SKU、包装成品和基础库位结果。"
-    - "任何轻仓库补强都应优先复用现有 overview 聚合链，而不是另外再造一套仓库读取入口。"
-  artifacts:
-    - path: "src/server/services/warehouse.service.ts"
-      provides: "轻仓库概览聚合与库位能力"
-      contains: "getOverview|createLocation"
-    - path: "src/app/warehouse/WarehouseClient.tsx"
-      provides: "轻仓库概览页骨架"
-      contains: "正式 SKU 库存|包装成品库存|库位管理"
-    - path: "src/server/services/warehouse.service.types.ts"
-      provides: "轻仓库 overview DTO"
-      contains: "WarehouseOverviewDTO"
-  key_links:
-    - from: "src/server/services/intake.service.ts"
-      to: "src/server/services/warehouse.service.ts"
-      via: "正式入库产物必须在轻仓库 overview 中可见"
-      pattern: "productSKU|packagedItem"
-    - from: "src/app/warehouse/page.tsx"
-      to: "src/server/services/warehouse.service.ts"
-      via: "轻仓库页面直接消费 overview 聚合结果"
-      pattern: "getOverview"
----
-
-<objective>
-把轻仓库收口成“正式入库后马上能检查结果”的稳定闭环，而不是只剩一个概念页。
-
-Purpose: 按 `MAIN-06` 修根因，避免正式入库虽然生成了正式对象，但轻仓库里信息不全、字段不稳、无法真正承担验收入口。
-Output: 更完整的轻仓库 overview 契约、必要的数据补强，以及前端联调说明。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/04-正式入库与轻仓库闭环/04-CONTEXT.md
-@src/app/warehouse/page.tsx
-@src/app/warehouse/WarehouseClient.tsx
-@src/app/api/warehouse/route.ts
-@src/app/api/warehouse/locations/route.ts
-@src/server/services/warehouse.service.ts
-@src/server/services/warehouse.service.types.ts
-@src/server/repositories/warehouse.repository.ts
-@src/server/services/intake.service.ts
-@../docs/前端UI改动清单.md
-</context>
-
-<tasks>
-
-<task type="auto" tdd="true">
-  <name>Task 1: 收紧轻仓库 overview 契约</name>
-  <files>src/server/services/warehouse.service.ts, src/server/services/warehouse.service.types.ts, src/server/repositories/warehouse.repository.ts</files>
-  <read_first>
-    src/server/services/warehouse.service.ts
-    src/server/services/warehouse.service.types.ts
-    src/server/repositories/warehouse.repository.ts
-    src/server/services/intake.service.ts
-    prisma/schema.prisma
-  </read_first>
-  <acceptance_criteria>
-    - `WarehouseOverviewDTO` 能稳定表达库位、正式 SKU、包装成品三组核心结果，不靠前端猜字段。
-    - `warehouse.service.ts` 返回的正式 SKU 和包装成品信息足够支撑“入库后检查结果”这一目标，例如正式对象名、型号/编码、库存、库位、基础尺寸/重量等。
-    - 如果发现仓库读取层存在明显空洞，补在 service/repository 层，不把业务拼装塞回页面组件。
-  </acceptance_criteria>
-  <action>审视 `getOverview()` 当前聚合出来的字段是否足够支撑轻仓库闭环。优先修复“正式入库后结果可见但信息不完整”的根因，例如包装成品缺少关联编码、正式 SKU/包装成品的展示字段不统一、读取链在 service 层混杂页面兜底假设等。若需要新增测试，可就地补到合适的 service/repository 测试文件，保证 overview 契约稳定。</action>
-  <verify>
-    <automated>rg -n "getOverview|skuStock|packagedItems|warehouseLocation" src/server/services/warehouse.service.ts src/server/services/warehouse.service.types.ts src/server/repositories/warehouse.repository.ts</automated>
-  </verify>
-  <done>轻仓库后端 overview 契约更完整，正式入库后的关键结果可以稳定读取并继续被页面消费。</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 固定轻仓库页面与前端分工边界</name>
-  <files>src/app/api/warehouse/route.ts, src/app/warehouse/WarehouseClient.tsx, ../docs/前端UI改动清单.md</files>
-  <read_first>
-    src/app/api/warehouse/route.ts
-    src/app/warehouse/WarehouseClient.tsx
-    ../docs/前端UI改动清单.md
-    src/server/services/warehouse.service.types.ts
-  </read_first>
-  <acceptance_criteria>
-    - `/warehouse` 当前页面不会再暗示“完整 WMS 已完成”，而是明确属于轻仓库闭环页。
-    - 若需要前端继续增强检索、切换、布局、动效等体验，只记录到 `../docs/前端UI改动清单.md`。
-    - 页面如果存在明显与后端 overview 契约不一致的展示问题，只做主链所需的最小修正。
-  </acceptance_criteria>
-  <action>核对 `WarehouseClient` 与 `warehouseService.getOverview()` 的字段契约和页面口径，确保轻仓库始终表达“正式结果查看与基础验收”而不是完整仓储系统。任何独立前端增强项，例如更强检索、筛选、卡片样式、移动端交互、成功回流引导等，只写入 `../docs/前端UI改动清单.md`，让 UI agent 继续处理。</action>
-  <verify>
-    <automated>rg -n "轻仓库|正式 SKU|包装成品|WMS|库位" src/app/warehouse/WarehouseClient.tsx ../docs/前端UI改动清单.md</automated>
-  </verify>
-  <done>轻仓库页面与服务契约口径一致，同时把需要 UI agent 继续处理的前端需求从主线逻辑里分流出去。</done>
-</task>
-
-</tasks>
-
-<verification>
-至少完成轻仓库 overview 契约检查，并用关键字验证页面和前端交接文档口径一致。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`MAIN-06` 在主线侧被收口为：正式产品与 SKU 的基础结果可以在轻仓库稳定查看，并形成入库后的轻量管理闭环。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/04-正式入库与轻仓库闭环/04-02-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/04-正式入库与轻仓库闭环/04-02-SUMMARY.md

@@ -1,92 +0,0 @@
----
-phase: 04-正式入库与轻仓库闭环
-plan: 02
-subsystem: api
-tags: [warehouse, overview, sku, packaged-item, tests, ui-handoff]
-requires:
-  - phase: 04-正式入库与轻仓库闭环
-    provides: 正式入库主链关键契约已收紧
-provides:
-  - 轻仓库 overview 读取链补强
-  - 包装成品关联 SKU 编码可见
-  - 轻仓库服务测试底座
-affects: [phase-04, warehouse, frontend-handoff]
-tech-stack:
-  added: []
-  patterns:
-    - 轻仓库读取优先走 repository
-    - overview 契约由测试守住
-key-files:
-  created:
-    - .planning/phases/04-正式入库与轻仓库闭环/04-02-SUMMARY.md
-    - src/server/services/__tests__/warehouse.service.test.ts
-  modified:
-    - src/server/repositories/sku.repository.ts
-    - src/server/repositories/draft-group.repository.ts
-    - src/server/services/warehouse.service.ts
-    - ../docs/前端UI改动清单.md
-key-decisions:
-  - "先补正式入库后最直接可见的仓库闭环缺口：包装成品必须能显示关联 SKU 编码。"
-  - "轻仓库 overview 的正式 SKU 读取改为走 repository，不继续在 service 层直接查 Prisma。"
-patterns-established:
-  - "轻仓库守护模式：repository 聚合 + service 映射 + overview 测试 + 前端联调清单。"
-requirements-completed: [MAIN-06]
-duration: 20min
-completed: 2026-04-02
----
-
-# Phase 4 Plan 02 Summary
-
-**轻仓库现在能把包装成品和正式 SKU 对得上了，并且 overview 读取链补上了测试。**
-
-## Performance
-
-- **Duration:** 20 min
-- **Started:** 2026-04-02T23:30:00+08:00
-- **Completed:** 2026-04-02T23:50:00+08:00
-- **Tasks:** 2
-- **Files modified:** 5
-
-## Accomplishments
-
-- 给轻仓库补了 `warehouse.service.test.ts`，用测试固定正式 SKU 与包装成品 overview 的核心映射结果。
-- 补强了包装成品读取关系，轻仓库现在会返回包装成品对应的正式 `skuCode`，方便入库后核对。
-- 把正式 SKU 仓库总览读取从 service 内直查 Prisma 调整为走 `skuRepository`，让分层更稳。
-- 在前端交接清单里补了“包装成品列表要能看见关联正式 SKU 编码”的联调要求。
-
-## Task Commits
-
-未创建提交。当前仓库仍保持本地未提交工作状态。
-
-## Files Created/Modified
-
-- `src/server/repositories/sku.repository.ts` - 新增轻仓库正式 SKU overview 读取方法
-- `src/server/repositories/draft-group.repository.ts` - 包装成品读取补上关联 SKU
-- `src/server/services/warehouse.service.ts` - 轻仓库 overview 映射补全 `skuCode`
-- `src/server/services/__tests__/warehouse.service.test.ts` - 新增轻仓库服务测试
-- `../docs/前端UI改动清单.md` - 补轻仓库联调说明
-
-## Decisions Made
-
-- 先修“入库后核对信息不完整”这个根因，而不是扩写更重的仓储动作。
-
-## Deviations from Plan
-
-None - plan executed exactly as written.
-
-## Issues Encountered
-
-- 无阻塞性问题；当前最直接的闭环缺口是包装成品 DTO 里 `skuCode` 一直为 `null`，已修正。
-
-## User Setup Required
-
-None - no external service configuration required.
-
-## Next Phase Readiness
-
-- `MAIN-06` 已完成第一轮正式收口，轻仓库现在更适合作为正式入库后的基础验收页。
-- 下一步可以进入 `04-03`，固定主线收口检查单和 `merge / cherry-pick / 手工整合` 决策规则。
-
----
-*Phase: 04-正式入库与轻仓库闭环*
-*Completed: 2026-04-02*

furniture-3d-system/.planning/phases/04-正式入库与轻仓库闭环/04-03-PLAN.md

@@ -1,129 +0,0 @@
----
-phase: 04-正式入库与轻仓库闭环
-plan: 03
-type: execute
-wave: 1
-depends_on:
-  - 04-01
-files_modified:
-  - docs/workflow/团队协作模式.md
-  - docs/workflow/主线同步操作手册.md
-  - docs/workflow/同事交接模板.md
-  - docs/workflow/模块边界说明.md
-autonomous: true
-requirements:
-  - COLL-04
-must_haves:
-  truths:
-    - "主线收口人收到同事分支后，必须能按固定检查单完成检查，而不是继续靠临场判断。"
-    - "对协作者分支的决策必须能明确落到 `merge / cherry-pick / 手工整合` 三种口径之一。"
-    - "收口规则必须继续服务当前主线和包装协作边界，不产生第二套平级入口文档。"
-  artifacts:
-    - path: "docs/workflow/团队协作模式.md"
-      provides: "团队协作总规则"
-      contains: "merge / cherry-pick / 手工整合"
-    - path: "docs/workflow/主线同步操作手册.md"
-      provides: "分支同步与收口执行口径"
-      contains: "冲突|merge main|rebase main"
-    - path: "docs/workflow/同事交接模板.md"
-      provides: "协作者提交分支时的固定交接材料"
-      contains: "本次只改了什么|验证|风险"
-  key_links:
-    - from: "docs/workflow/团队协作模式.md"
-      to: "docs/workflow/模块边界说明.md"
-      via: "检查分支是否越过模块边界或改了共享接缝"
-      pattern: "共享接缝|包装协作边界"
-    - from: "docs/workflow/同事交接模板.md"
-      to: "docs/workflow/主线同步操作手册.md"
-      via: "交接材料与同步/并线动作要能对上"
-      pattern: "merge|rebase|冲突"
----
-
-<objective>
-把主线负责人收同事分支的流程收口成固定、可复用、AI 也能照着执行的规则。
-
-Purpose: 按 `COLL-04` 修根因，避免包装同事后续继续提交分支时，主线收口仍然因为“怎么检查、什么时候 merge、什么时候 cherry-pick”不固定而反复混乱。
-Output: 更新后的协作文档、主线收口检查单、三选一决策口径，以及更明确的交接模板。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
-@.planning/REQUIREMENTS.md
-@.planning/phases/04-正式入库与轻仓库闭环/04-CONTEXT.md
-@docs/workflow/团队协作模式.md
-@docs/workflow/主线同步操作手册.md
-@docs/workflow/模块边界说明.md
-@docs/workflow/同事交接模板.md
-@docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: 固定主线收口检查单与三选一决策表</name>
-  <files>docs/workflow/团队协作模式.md, docs/workflow/主线同步操作手册.md, docs/workflow/模块边界说明.md</files>
-  <read_first>
-    docs/workflow/团队协作模式.md
-    docs/workflow/主线同步操作手册.md
-    docs/workflow/模块边界说明.md
-    .planning/phases/04-正式入库与轻仓库闭环/04-CONTEXT.md
-  </read_first>
-  <acceptance_criteria>
-    - 文档里明确列出主线收口前最少检查项：是否同步最新 `main`、是否超出任务范围、是否碰共享接缝、是否有最小验证、是否带交接说明。
-    - 文档里明确写出什么情况直接 `merge`、什么情况 `cherry-pick`、什么情况手工整合、什么情况暂不收口。
-    - 文档里明确把 Phase 4 的主线风险写出来：不能把包装逻辑误带进正式入库主链，不能把旧兼容链重新当作主链真相。
-  </acceptance_criteria>
-  <action>在现有协作文档入口内补一套主线收口检查规则，不新增第二套入口。重点补充：主负责人收同事分支时必须先看任务范围、共享接缝、验证记录、交接说明；当改动集中且无敏感接缝时可直接 `merge`，当改动里混有敏感接缝或非目标提交时优先 `cherry-pick`，当提交质量一般但目标功能仍要收口时采用手工整合；如果缺验证、范围失控、碰敏感接缝但未说明原因，则暂不收口。</action>
-  <verify>
-    <automated>rg -n "cherry-pick|手工整合|检查单|共享接缝|暂不收口|merge" docs/workflow/团队协作模式.md docs/workflow/主线同步操作手册.md docs/workflow/模块边界说明.md</automated>
-  </verify>
-  <done>主线收口不再依赖口头经验，后续人和 AI 都能按同一套规则判断如何收同事分支。</done>
-</task>
-
-<task type="auto">
-  <name>Task 2: 收紧同事交接模板，让 AI 可直接读懂</name>
-  <files>docs/workflow/同事交接模板.md</files>
-  <read_first>
-    docs/workflow/同事交接模板.md
-    docs/workflow/团队协作模式.md
-    docs/workflow/模块边界说明.md
-  </read_first>
-  <acceptance_criteria>
-    - `同事交接模板.md` 至少要求同事说明：本次只改什么、明确没改什么、是否碰共享接缝、验证跑了什么、风险/待主线继续什么。
-    - 模板语言足够让 AI 直接提取信息，不依赖大量上下文猜测。
-    - 模板口径与当前固定分支名、共享接缝规则一致，不再出现 `feature/packaging` 等旧口径。
-  </acceptance_criteria>
-  <action>把 `docs/workflow/同事交接模板.md` 收紧成 AI 也能直接解析的固定交接格式，显式要求协作者在提交分支时同步写明：目标分支名、任务范围、未做范围、共享接缝是否触达、最小验证结果、风险和需要主线负责人决定的事项。确保模板与 `codex/xuxiake-packaging` 及其任务分支口径一致。</action>
-  <verify>
-    <automated>rg -n "codex/xuxiake-packaging|共享接缝|验证|没改|风险|目标分支" docs/workflow/同事交接模板.md</automated>
-  </verify>
-  <done>同事后续给主线的交接材料更标准，主线收口和 AI 辅助检查都会更稳定。</done>
-</task>
-
-</tasks>
-
-<verification>
-通过文档关键字校验，确认主线收口检查单、三选一决策规则和交接模板都已落盘且口径一致。
-</verification>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`COLL-04` 在主线侧被收口为：主线负责人可以在同事提交分支后按固定规则完成检查，并决定 `merge / cherry-pick / 手工整合`。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/04-正式入库与轻仓库闭环/04-03-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/04-正式入库与轻仓库闭环/04-03-SUMMARY.md

@@ -1,90 +0,0 @@
----
-phase: 04-正式入库与轻仓库闭环
-plan: 03
-subsystem: docs
-tags: [collaboration, merge, cherry-pick, handoff, intake, warehouse]
-requires:
-  - phase: 04-正式入库与轻仓库闭环
-    provides: 正式入库与轻仓库闭环边界已固定
-provides:
-  - 主线收口检查单
-  - merge/cherry-pick/手工整合 决策口径
-  - AI 可读的交接模板增强
-affects: [phase-04, collaboration, packaging-collab]
-tech-stack:
-  added: []
-  patterns:
-    - 协作者分支收口规则并入现有 workflow 入口
-    - 交接模板显式要求写清范围、共享接缝、验证与建议收口方式
-key-files:
-  created:
-    - .planning/phases/04-正式入库与轻仓库闭环/04-03-SUMMARY.md
-  modified:
-    - docs/workflow/团队协作模式.md
-    - docs/workflow/主线同步操作手册.md
-    - docs/workflow/模块边界说明.md
-    - docs/workflow/同事交接模板.md
-key-decisions:
-  - "不新建第二套平级协作文档入口，而是在既有 workflow 文档里补主线收口规则。"
-  - "主线收口默认按检查单决定 merge / cherry-pick / 手工整合，不再继续靠临场判断。"
-patterns-established:
-  - "协作收口守护模式：交接模板 -> 收口检查单 -> 决策规则 三段闭环。"
-requirements-completed: [COLL-04]
-duration: 20min
-completed: 2026-04-02
----
-
-# Phase 4 Plan 03 Summary
-
-**主线收同事分支的流程现在已经写成固定规则了，后面人和 AI 都能按同一套口径判断怎么收。**
-
-## Performance
-
-- **Duration:** 20 min
-- **Started:** 2026-04-02T23:50:00+08:00
-- **Completed:** 2026-04-03T00:10:00+08:00
-- **Tasks:** 2
-- **Files modified:** 4
-
-## Accomplishments
-
-- 在团队协作总文档里补了主线收口检查单，以及 `merge / cherry-pick / 手工整合 / 暂不收口` 的固定判断口径。
-- 在主线同步操作手册里补了“主线负责人怎么收同事分支”的执行说明。
-- 在模块边界说明里补了共享接缝被改动时的收口提醒，避免直接整支 `merge`。
-- 在同事交接模板里补了 AI 更容易读懂的固定字段，包括目标分支、本次只改/没改、是否碰共享接缝、风险和建议主线怎么收。
-
-## Task Commits
-
-未创建提交。当前仓库仍保持本地未提交工作状态。
-
-## Files Created/Modified
-
-- `docs/workflow/团队协作模式.md` - 固定主线收口检查单和三选一决策规则
-- `docs/workflow/主线同步操作手册.md` - 补主线负责人收同事分支的操作口径
-- `docs/workflow/模块边界说明.md` - 补共享接缝改动时的收口提醒
-- `docs/workflow/同事交接模板.md` - 补 AI 可读的固定交接字段
-
-## Decisions Made
-
-- 把 `COLL-04` 落在现有 workflow 入口里，而不是再发明一份新的并线说明文档。
-
-## Deviations from Plan
-
-None - plan executed exactly as written.
-
-## Issues Encountered
-
-- 无阻塞性问题；主要工作是把已明确的协作原则落成可执行规则。
-
-## User Setup Required
-
-None - no external service configuration required.
-
-## Next Phase Readiness
-
-- `COLL-04` 已完成第一轮正式收口，后续同事提交包装分支时，主线有固定收口口径可依。
-- Phase 4 的三条计划已全部完成第一轮收口，后续可转向 Phase 5，或按需要补 Phase 4 的更细化验证。
-
----
-*Phase: 04-正式入库与轻仓库闭环*
-*Completed: 2026-04-02*

furniture-3d-system/.planning/phases/04-正式入库与轻仓库闭环/04-CONTEXT.md

@@ -1,137 +0,0 @@
-# Phase 4: 正式入库与轻仓库闭环 - Context
-
-**Gathered:** 2026-04-02
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-本阶段只收口新平台主链的最后一段：把草稿组中的 `PreSku` 结果稳定转成正式 `Product / SKU`，并在入库后通过轻仓库完成基础查看与验收闭环。同时补齐主线负责人检查协作者分支并决定 `merge / cherry-pick / 手工整合` 的固定收口口径。本阶段不代做包装方案本体，不扩成完整 WMS，也不把旧 CAD 兼容链重新拉回新主链真相。
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### 正式入库主链
-- **D-01:** Phase 4 继续以 `DraftGroup / PreSku` 为正式入库唯一前置，不允许跳过草稿组，也不允许让旧 `Product / SKU` 反向主导新平台组合阶段。
-- **D-02:** 正式入库沿用现有 `formalizeDraftGroup()` 主链收口，核心方向是补稳定性、可检查性和测试覆盖，不重起第二套入库流程。
-- **D-03:** `PreSku` 正式入库前仍必须满足“属于当前草稿组、未正式入库、未归档、且存在有效包装箱”这组准入规则；包装结果继续只认 Phase 3 已锁定的新结构。
-- **D-04:** 入库后的正式结果以 `Product / ProductSKU / PackagingPlan / PackagedItem` 为正式承接对象，但这些正式对象只承接来自 `PreSku` 的已确认结果，不作为前置规划阶段的数据真相。
-
-### 轻仓库闭环
-- **D-05:** 轻仓库定位继续保持“基础验收与查看闭环”，只管理正式 SKU、包装成品、库存数量和基础库位，不在本阶段扩写完整出入库流水、调拨或盘点能力。
-- **D-06:** 轻仓库页面和接口优先复用现有 `warehouseService.getOverview()` 与库位创建能力，重点收口正式入库后的可见性、字段完整性和主链闭环体验。
-- **D-07:** 轻仓库展示应直接反映正式入库产物，包括正式 SKU、包装成品和库位挂接结果，避免用户入库后还要再录一遍仓库基础数据。
-
-### 协作者分支收口
-- **D-08:** Phase 4 必须把 `COLL-04` 从“原则”提升为“可执行规则”，让主线负责人收到同事分支后，能按固定检查单决定 `merge / cherry-pick / 手工整合`。
-- **D-09:** 收口规则至少要覆盖：是否基于最新 `main`、是否超出任务范围、是否碰共享接缝、是否附带最小验证、是否带交接说明、是否影响正式入库/轻仓库主链。
-- **D-10:** 对包装同事分支的收口，继续坚持“小任务收口优先”，默认不一次吞并长期积压改动；如果改动落入敏感接缝，优先 `cherry-pick` 或手工整合，而不是直接整支合并。
-
-### 范围边界
-- **D-11:** 包装方案本体、包装材料选择、最低成本方案、工艺图组合仍属于同事 `xuxiake` 的工作域；主线本阶段只承接包装结果，不代做包装业务实现。
-- **D-12:** 前端/UI 不由当前工作流直接实现；如果 Phase 4 需要前端配合，只把需求写到 `D:\AI Code\3danzhuang\docs\前端UI改动清单.md`。
-- **D-13:** 本阶段优先修根因和闭环缺口，不顺手扩写旧 CAD 兼容链，也不把路由层变成业务实现层。
-
-### the agent's Discretion
-- 是否先补正式入库链的测试和数据收口，再补轻仓库展示细节，由 agent 根据当前缺口排序决定。
-- `COLL-04` 的收口规则最终落在单独文档、现有协作文档补章，还是两者组合，由 agent 在不增加第二套入口的前提下决定。
-
-</decisions>
-
-<canonical_refs>
-## Canonical References
-
-**Downstream agents MUST read these before planning or implementing.**
-
-### 项目级约束
-- `.planning/PROJECT.md` — 项目目标、主链定义、前端边界、协作约束
-- `.planning/ROADMAP.md` — Phase 4 的目标、依赖、成功标准
-- `.planning/REQUIREMENTS.md` — `MAIN-05`、`MAIN-06`、`COLL-04` 的需求定义
-- `.planning/STATE.md` — 当前阶段恢复入口与风险
-
-### 既有阶段上下文
-- `.planning/phases/02-资产到草稿组主链收口/02-CONTEXT.md` — `AssetFamily / AssetVariant -> DraftGroup / PreSku` 主链边界
-- `.planning/phases/03-包装接缝稳定化/03-CONTEXT.md` — 包装新结构、共享接缝和协作边界
-- `.planning/phases/03-包装接缝稳定化/03-01-SUMMARY.md` — 包装结果保存/试算/入库承接已被测试守住
-- `.planning/phases/03-包装接缝稳定化/03-02-SUMMARY.md` — 包装占位入口与协作边界已固定
-
-### 协作与收口规则
-- `../AGENTS.md` — 全仓库协作入口、规范审查和团队协作固定口径
-- `docs/workflow/团队协作模式.md` — 主线/包装线职责、分支规则、并线原则
-- `docs/workflow/模块边界说明.md` — 主线、包装、旧兼容链与共享接缝边界
-- `docs/workflow/主线同步操作手册.md` — 长期分支 `merge main` 与临时任务分支 `rebase main` 的固定口径
-- `docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md` — 包装线对接主线时必须遵守的结构和接缝说明
-
-### 正式入库现状
-- `src/app/intake/page.tsx` — 正式入库页面入口与数据装配
-- `src/app/intake/IntakeClient.tsx` — 正式入库编辑流程、选草稿组/选准 SKU/入库去向
-- `src/app/api/intake/formalize/route.ts` — 正式入库接口入口
-- `src/app/api/platform/schemas.ts` — 正式入库与库位 DTO 校验结构
-- `src/lib/open-product/platform-api.ts` — 前端调用正式入库与库位接口的统一入口
-- `src/server/services/intake.service.ts` — 正式入库编排、准入校验、正式对象创建
-- `src/server/services/intake.service.types.ts` — 正式入库输入输出 DTO
-- `src/server/services/__tests__/intake.service.test.ts` — 正式入库与包装承接现有测试底座
-
-### 轻仓库现状
-- `src/app/warehouse/page.tsx` — 轻仓库页面入口
-- `src/app/warehouse/WarehouseClient.tsx` — 轻仓库概览、库位创建、正式 SKU/包装成品展示
-- `src/app/api/warehouse/route.ts` — 轻仓库概览接口
-- `src/app/api/warehouse/locations/route.ts` — 库位接口
-- `src/server/services/warehouse.service.ts` — 轻仓库概览与库位服务
-- `src/server/services/warehouse.service.types.ts` — 轻仓库 DTO
-- `src/server/repositories/warehouse.repository.ts` — 基础库位仓储
-
-### 数据模型与共享对象
-- `prisma/schema.prisma` — `DraftGroup`、`PreSku`、`Product`、`ProductSKU`、`PackagingPlan`、`PackagedItem`、`WarehouseLocation` 数据边界
-- `src/server/repositories/draft-group.repository.ts` — 草稿组与准 SKU 读取接缝
-- `src/server/repositories/product.repository.ts` — 正式产品推荐与承接对象读取
-- `src/server/repositories/sku.repository.ts` — 正式 SKU 结构与查询接缝
-
-</canonical_refs>
-
-<code_context>
-## Existing Code Insights
-
-### Reusable Assets
-- `intakeService.formalizeDraftGroup()` 已经具备从 `PreSku` 创建正式 `Product / ProductSKU / PackagingPlan / PackagedItem` 的主链能力，可直接作为 Phase 4 主入口继续收口。
-- `WarehouseService.getOverview()` 已经把库位、正式 SKU、包装成品聚合成一个总览 DTO，适合作为轻仓库最小闭环底座。
-- `IntakeClient` 和 `WarehouseClient` 已有基础页面骨架，说明 Phase 4 不是从零搭页面，而是补闭环、补字段、补检查规则。
-
-### Established Patterns
-- 主线后端继续遵守 `Route -> Service -> Repository -> Prisma`，Phase 4 不应把入库或仓库规则塞回 Route 或页面。
-- 包装结果入库承接继续以 `boxes[]` 为唯一有效输入，不能为了兼容旧口径重新放开旧结构。
-- 轻仓库现在是“轻量管理页”，不是完整 WMS；这是本阶段已明确的产品边界，不应被计划误扩。
-
-### Integration Points
-- `draftGroupService.getById()` 提供正式入库页所需的 `DraftGroupDetailDTO`，是 `PreSku -> 正式入库` 的前置读取接缝。
-- `intake.service.ts` 是 `PreSku -> Product / SKU / 包装成品` 的核心编排层，任何正式入库补强都应围绕这里分层推进。
-- `warehouse.service.ts` 和 `/warehouse` 页面是入库后结果可见性的主接点；Phase 4 若发现闭环缺口，应优先在这里收口。
-- `docs/workflow/*.md` 是 `COLL-04` 固定口径的正式入口，新的收口规则应并入现有入口，而不是再造第二套平级文档入口。
-
-</code_context>
-
-<specifics>
-## Specific Ideas
-
-- 用户已明确：包装和包装方案由同事负责，本阶段不要回头代做包装本体。
-- 用户已明确：前端/UI 由独立 agent 处理；主线如果需要 UI 配合，只记录需求到 `D:\AI Code\3danzhuang\docs\前端UI改动清单.md`。
-- 当前真正需要补的是“正式入库完成后是否真的形成可检查闭环”和“同事分支来了以后主线怎么稳定收口”，而不是重新定义业务主链。
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-- 包装方案本体增强、最低成本方案、工艺图组合 — 继续留在包装域
-- 完整 WMS 能力（出入库流水、调拨、盘点）— 后续阶段或新需求
-- 旧 CAD 兼容链增强 — 保持可用，但不属于本阶段闭环
-- 主链核心服务进一步大拆分 — 留到 Phase 5 继续做可维护性收口
-
-</deferred>
-
----
-
-*Phase: 04-正式入库与轻仓库闭环*
-*Context gathered: 2026-04-02*

furniture-3d-system/.planning/phases/04-正式入库与轻仓库闭环/04-DISCUSSION-LOG.md

@@ -1,61 +0,0 @@
-# Phase 4: 正式入库与轻仓库闭环 - Discussion Log
-
-> **Audit trail only.** Do not use as input to planning, research, or execution agents.
-> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
-
-**Date:** 2026-04-02
-**Phase:** 04-正式入库与轻仓库闭环
-**Areas discussed:** 正式入库主链、轻仓库闭环、协作者分支收口
-
----
-
-## 正式入库主链
-
-| Option | Description | Selected |
-|--------|-------------|----------|
-| 沿用现有正式入库主链补稳定性 | 复用 `formalizeDraftGroup()`、补校验和测试，不重起第二套流程 | ✓ |
-| 新起独立正式入库流程 | 绕开现有主链重新设计一套正式入库实现 | |
-| 先扩旧产品链再回接新主链 | 让旧 `Product / SKU` 兼容链重新承担主链前置职责 | |
-
-**User's choice:** 自动模式采用推荐项，继续沿用现有正式入库主链补稳定性。
-**Notes:** 已从当前代码确认 `intake.service.ts` 能把 `PreSku` 承接为正式 `Product / ProductSKU / PackagingPlan / PackagedItem`，因此 Phase 4 重点是闭环收口，不是重写主链。
-
----
-
-## 轻仓库闭环
-
-| Option | Description | Selected |
-|--------|-------------|----------|
-| 维持轻仓库定位，只补正式结果可见性 | 继续只做库位、正式 SKU、包装成品和基础库存查看 | ✓ |
-| 直接扩成完整 WMS | 本阶段加入复杂出入库、调拨、盘点等能力 | |
-| 把轻仓库并回正式入库页 | 不单独保留轻仓库概览页 | |
-
-**User's choice:** 自动模式采用推荐项，维持轻仓库定位，只补正式结果可见性。
-**Notes:** 当前 `/warehouse` 已经具备概览和库位创建底座，符合“轻仓库”定位；扩成完整 WMS 属于明显 scope creep。
-
----
-
-## 协作者分支收口
-
-| Option | Description | Selected |
-|--------|-------------|----------|
-| 固定主线收口检查单和三选一决策规则 | 明确 `merge / cherry-pick / 手工整合` 的判断标准 | ✓ |
-| 继续沿用口头原则 | 只保留文档里的抽象原则，收口时临场判断 | |
-| 让协作者自己决定如何并入主线 | 放弃主线收口人的固定检查职责 | |
-
-**User's choice:** 自动模式采用推荐项，固定主线收口检查单和三选一决策规则。
-**Notes:** 文档侦察确认 `COLL-04` 目前只有原则，没有可执行检查单；Phase 4 需要把这部分补成稳定流程。
-
----
-
-## the agent's Discretion
-
-- 计划阶段可决定先补正式入库测试闭环还是先补轻仓库字段闭环，但都必须服务 `MAIN-05 / MAIN-06`。
-- `COLL-04` 最终落在单独操作手册还是并入现有协作文档章节，可在不增加第二入口的前提下决定。
-
-## Deferred Ideas
-
-- 包装方案本体增强与包装工作区 UI
-- 完整 WMS 能力
-- 旧 CAD 兼容链增强
-

furniture-3d-system/.planning/phases/05-主链可维护性收口/05-01-PLAN.md

@@ -1,104 +0,0 @@
----
-phase: 05-主链可维护性收口
-plan: 01
-type: execute
-wave: 1
-depends_on: []
-files_modified:
-  - src/server/services/assembly.service.ts
-  - src/server/services/panel.service.ts
-  - src/server/services/planning.service.ts
-  - src/server/services/*.types.ts
-  - src/server/services/__tests__/*
-autonomous: true
-requirements:
-  - ARCH-01
-must_haves:
-  truths:
-    - "主链核心服务继续按编排、校验、映射、规则等职责拆分，新逻辑不能重新堆回单个膨胀 service。"
-    - "拆分优先围绕已有热点和现有拆分模式继续推进，不做一次性全仓库大重构。"
-  artifacts:
-    - path: "src/server/services/assembly.service.ts"
-      provides: "旧兼容链装配主服务"
-      contains: "findByProductId|bulkUpdateSteps|generate"
-    - path: "src/server/services/panel.service.ts"
-      provides: "板件主服务"
-      contains: "findByProductId|bulkSaveAssemblySemantics|create|update"
-    - path: "src/server/services/planning.service.ts"
-      provides: "规划主服务"
-      contains: "createTemplate|updateTemplate|createWorkspace|generateCandidates"
-  key_links:
-    - from: "src/server/services/assembly.service.ts"
-      to: "src/server/services/assembly-generation.service.ts"
-      via: "继续抽离生成与编排职责"
-      pattern: "generate"
-    - from: "src/server/services/panel.service.ts"
-      to: "src/server/services/panel-scope.service.ts"
-      via: "继续压缩权限与范围判断到 scope/validation 层"
-      pattern: "scope"
----
-
-<objective>
-继续把主链热点 service 拆到职责更清楚的状态，避免后续需求再次堆回大文件。
-
-Purpose: 按 `ARCH-01` 修根因，建立“新增逻辑该放哪”的可预测结构。
-Output: 一轮继续拆分后的主链 service 结构和必要测试。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/phases/05-主链可维护性收口/05-CONTEXT.md
-@src/server/services/assembly.service.ts
-@src/server/services/assembly-generation.service.ts
-@src/server/services/assembly-scope.service.ts
-@src/server/services/panel.service.ts
-@src/server/services/panel-scope.service.ts
-@src/server/services/panel-validation.service.ts
-@src/server/services/planning.service.ts
-@src/server/services/planning-generation.service.ts
-@src/server/services/planning-scope.service.ts
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: 继续压缩已拆但未拆透的热点 service</name>
-  <files>src/server/services/assembly.service.ts, src/server/services/panel.service.ts, src/server/services/planning.service.ts</files>
-  <read_first>
-    src/server/services/assembly.service.ts
-    src/server/services/panel.service.ts
-    src/server/services/planning.service.ts
-    对应的 *.scope/*.validation/*.mapper/*.generation 文件
-  </read_first>
-  <acceptance_criteria>
-    - 继续从主服务里抽出明确职责，不把新逻辑反向塞回去。
-    - 拆分后主服务只保留高层编排、少量胶水逻辑和对外入口。
-    - 至少补或更新一组相关测试，证明拆分没有改变外部行为。
-  </acceptance_criteria>
-  <action>从当前仍偏大的 `assembly.service.ts`、`panel.service.ts`、`planning.service.ts` 里找最明显的一段职责块继续下沉到已有的 scope / validation / mapper / generation / internal 文件，保持 API 不变，重点让“新增逻辑该放哪”更明确。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath <补实际测试文件></automated>
-  </verify>
-  <done>热点 service 继续瘦身，结构样板更清楚。</done>
-</task>
-
-</tasks>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`ARCH-01` 在当前热点主链 service 上继续落地，后续新增逻辑位置更可预测。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/05-主链可维护性收口/05-01-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/05-主链可维护性收口/05-01-SUMMARY.md

@@ -1,63 +0,0 @@
----
-phase: 05-主链可维护性收口
-plan: 01
-subsystem: service
-tags: [planning, service-layer, validation, draft-snapshot, tests]
-requires:
-  - phase: 04-正式入库与轻仓库闭环
-    provides: 主链功能闭环已先稳定
-provides:
-  - planning.service 继续瘦身
-  - 规划模板/分类校验职责下沉
-  - 草稿选中资产最小快照口径固定
-affects: [phase-05, planning, architecture]
-tech-stack:
-  added: []
-  patterns:
-    - planning 主服务只保留编排
-    - validation 负责模板定义与分类存在性校验
-    - internal helper 负责草稿快照裁剪
-key-files:
-  created:
-    - .planning/phases/05-主链可维护性收口/05-01-SUMMARY.md
-    - src/server/services/planning-validation.service.ts
-  modified:
-    - src/server/services/planning.service.ts
-    - src/server/services/planning.service.internal.ts
-    - src/server/services/__tests__/planning.service.test.ts
-key-decisions:
-  - "先继续收 planning.service，而不是同时扩到 assembly/panel，避免这轮 Phase 5 扩范围。"
-  - "把模板定义校验和分类存在性校验下沉到 planning-validation.service。"
-  - "把草稿 selectedAssets 的最小持久化快照提成 internal helper，避免主服务重复拼装。"
-patterns-established:
-  - "planning 收口模式：scope 控权限，generation 管候选生成，validation 管模板/分类校验，internal 管 JSON/快照胶水。"
-requirements-progressed: [ARCH-01]
-completed: 2026-04-03
----
-
-# Phase 5 Plan 01 Summary
-
-**这一轮先把 `planning.service` 再瘦一层，让主服务更像编排层，而不是继续混着做输入校验和快照拼装。**
-
-## Accomplishments
-
-- 新增 `planning-validation.service.ts`，把模板定义解析校验和分类存在性校验从 `planning.service.ts` 下沉出去。
-- 在 `planning.service.internal.ts` 增加草稿 `selectedAssets` 最小快照 helper，统一只保留 `id / assetType / code / name`。
-- `planning.service.ts` 现在主要保留模板、工作台、草稿的高层编排，职责边界更清楚。
-- 补了 `planning.service.test.ts`，验证模板创建时的分类校验/字段修剪，以及草稿保存时的最小快照持久化口径。
-
-## Verification
-
-- 已执行：`npm test -- --runTestsByPath src/server/services/__tests__/planning.service.test.ts`
-- 结果：通过（4/4）
-
-## Risks
-
-- 这轮只继续收口了 `planning.service.ts`，`assembly.service.ts` 和 `panel.service.ts` 仍属于 Phase 5 后续可继续瘦身的热点。
-- 未跑全量 `type-check` 和全量测试；本轮验证只覆盖了规划服务相关路径。
-
-## Review
-
-- 结论：`passed`
-- 审查范围：`planning.service` 分层、最小测试、是否属于根因修复
-- 标注：这是自审，不是独立复审

furniture-3d-system/.planning/phases/05-主链可维护性收口/05-02-PLAN.md

@@ -1,93 +0,0 @@
----
-phase: 05-主链可维护性收口
-plan: 02
-type: execute
-wave: 1
-depends_on:
-  - 05-01
-files_modified:
-  - src/server/services/intake.service.ts
-  - src/server/services/warehouse.service.ts
-  - src/server/repositories/*.ts
-  - src/app/api/**/*.ts
-  - docs/workflow/模块边界说明.md
-autonomous: true
-requirements:
-  - ARCH-02
-  - ARCH-03
-must_haves:
-  truths:
-    - "旧 CAD 兼容链继续可用，但不会反向成为新平台主链的数据真相。"
-    - "新增主线后端能力继续遵守 Route -> Service -> Repository -> Prisma。"
-  artifacts:
-    - path: "src/server/services/intake.service.ts"
-      provides: "正式入库主链"
-      contains: "formalizeDraftGroup"
-    - path: "src/server/services/warehouse.service.ts"
-      provides: "轻仓库主链"
-      contains: "getOverview"
-    - path: "docs/workflow/模块边界说明.md"
-      provides: "新旧链边界约束"
-      contains: "不混主链和兼容链"
----
-
-<objective>
-继续把新旧链边界和分层约束收紧，避免 Phase 4 收好的主链又被旧链和直查逻辑侵入。
-
-Purpose: 按 `ARCH-02`、`ARCH-03` 修根因，守住主链数据真相和统一分层。
-Output: 一轮边界/分层收口后的代码与必要说明。
-</objective>
-
-<execution_context>
-@D:/AI Code/3danzhuang/.codex/get-shit-done/workflows/execute-plan.md
-@D:/AI Code/3danzhuang/.codex/get-shit-done/templates/summary.md
-</execution_context>
-
-<context>
-@.planning/phases/05-主链可维护性收口/05-CONTEXT.md
-@src/server/services/intake.service.ts
-@src/server/services/warehouse.service.ts
-@src/app/api/intake/formalize/route.ts
-@src/app/api/warehouse/route.ts
-@src/app/api/warehouse/locations/route.ts
-@docs/workflow/模块边界说明.md
-</context>
-
-<tasks>
-
-<task type="auto">
-  <name>Task 1: 收掉主链里的分层残留点和边界风险</name>
-  <files>src/server/services/intake.service.ts, src/server/services/warehouse.service.ts, src/server/repositories/*.ts, src/app/api/**/*.ts</files>
-  <read_first>
-    src/server/services/intake.service.ts
-    src/server/services/warehouse.service.ts
-    相关 route 和 repository
-  </read_first>
-  <acceptance_criteria>
-    - 能回收到 repository 的直接数据访问尽量回收，不继续散落在 service / route。
-    - 正式入库、轻仓库等新平台主链不反向依赖旧兼容链真相。
-    - 若发现边界口径需要补，补到现有边界文档，不另开平级入口。
-  </acceptance_criteria>
-  <action>检查并继续收掉 `intake / warehouse` 以及相关 route/repository 中仍然不够干净的分层残留点；如果发现旧兼容链对象正在反向影响新主链决策，优先做最小结构收口，并把必要的边界提醒补到现有文档。</action>
-  <verify>
-    <automated>npm test -- --runTestsByPath <补实际测试文件></automated>
-  </verify>
-  <done>主链的分层和边界更稳，Phase 4 收好的能力不容易再被结构漂移带坏。</done>
-</task>
-
-</tasks>
-
-<review>
-执行完成后必须单独输出一次规范审查结论，参考 `docs/workflow/规范审查清单.md`，固定包含：
-- 结论：`passed` / `passed with warnings` / `rejected`
-- 审查范围：架构、视觉、根因修复
-- 标注：`这是自审，不是独立复审`
-</review>
-
-<success_criteria>
-`ARCH-02`、`ARCH-03` 在主链关键接点上继续落地，新旧链边界和统一分层保持可预测。
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/05-主链可维护性收口/05-02-SUMMARY.md`
-</output>

furniture-3d-system/.planning/phases/05-主链可维护性收口/05-02-SUMMARY.md

@@ -1,59 +0,0 @@
----
-phase: 05-主链可维护性收口
-plan: 02
-subsystem: boundary-and-layering
-tags: [intake, warehouse, prisma, material-library, assisted-assembly, gsd-memory]
-requires:
-  - phase: 05-主链可维护性收口
-    provides: 05-01 已完成第一轮 service 拆分
-  - phase: 05-主链可维护性收口
-    provides: 05-03 已把包装支线资料库规则并回主线
-provides:
-  - intake 主链继续回收到 repository 分层
-  - 主仓库 prisma schema 与当前代码口径重新对齐
-  - 新旧链边界文档回到当前手动拼装主链
-affects: [phase-05, intake, warehouse, prisma-schema, planning-memory]
-requirements-progressed: [ARCH-02, ARCH-03]
-completed: 2026-04-11
----
-
-# Phase 5 Plan 02 Summary
-
-**这轮把 `05-03（包装支线资料库并线）` 留下的结构尾巴收掉：一边把 `intake（正式入库）` 的分层残留继续回收到 `repository（仓储层）`，一边把主仓库里落后的 `schema.prisma（数据库模型）` 补回到当前真实代码口径。**
-
-## Accomplishments
-
-- `intake.service.ts（正式入库服务）` 不再继续直接查 `prisma（数据库）` 里的 `Product / SKU`，已回收到 `productRepository（产品仓储）` 与 `skuRepository（SKU 仓储）`。
-- 新增 `skuRepository.findByProductIdAndSkuCode(...)`，让正式入库唯一编码生成继续遵守 `Route -> Service -> Repository -> Prisma` 分层。
-- `docs/workflow/模块边界说明.md` 已改回当前真实主线：
-  - 当前入口是 `assisted-assembly（辅助装配）`
-  - 当前装配主链是 `manual assembly（手动拼装）`
-  - 旧 `auto-combinations（自动组合）` 只按历史兼容链理解
-- 主仓库 `prisma/schema.prisma（数据库模型）` 已补齐到与当前代码一致：
-  - `surfaceOptionId（贴面类型）` 可空
-  - `weightKg（整板重量）`
-  - `SubstrateFinish（基材-花色关联）`
-  - `Material.code（花色编码）`
-- 主仓库已补回缺失迁移：
-  - `20260411143000_merge_packaging_branch_material_library（包装支线资料库并线迁移）`
-- `material.service.ts（花色服务）`、`asset-center.service.ts（资产中心服务）`、`open-platform-demo-seed.service.ts（演示数据服务）` 等配套代码与测试已和新口径对齐。
-- `platform-navigation（平台导航）`、`draft-groups（草稿组）`、`intake（正式入库）` 页面里的旧“生成候选”话术已回收到当前“完成手动拼装”口径。
-
-## Verification
-
-- `npx prisma validate`
-- `npm run type-check`
-- `npm test -- --runInBand --runTestsByPath src/server/services/__tests__/intake.service.test.ts src/server/services/__tests__/warehouse.service.test.ts src/server/services/__tests__/open-platform-demo-seed.service.test.ts src/lib/open-product/__tests__/assembly-workspace.test.ts src/app/assisted-assembly/AssistedAssemblyClient.test.tsx src/app/__tests__/assisted-assembly-page.test.tsx`
-
-结果：全部通过。
-
-## Risks
-
-- `5 字段唯一约束` 的最终业务规则仍未定稿；本轮只把当前主线收回到“代码、迁移、文档一致”，没有擅自拍板最终重复判定真相。
-- 当前工作区仍然是混合现场，包含前端重写相关改动和未跟踪目录；本总结只代表 `05-02` 这轮结构收口已完成，不代表整仓库已经干净可直接发布。
-
-## Review
-
-- 结论：`passed with warnings`
-- 审查范围：架构、视觉、根因修复
-- 标注：这是自审，不是独立复审

furniture-3d-system/.planning/phases/05-主链可维护性收口/05-03-PLAN.md

@@ -1,47 +0,0 @@
----
-phase: 05-主链可维护性收口
-plan: 03
-type: execute
-wave: inserted
-depends_on:
-  - 05-01
-files_modified:
-  - prisma/schema.prisma
-  - src/server/services/asset-center.service.ts
-  - src/server/services/material.service.ts
-  - src/app/asset-center/material-library/**
-  - src/lib/open-product/platform-api.ts
-  - .planning/PROJECT.md
-  - .planning/ROADMAP.md
-  - .planning/REQUIREMENTS.md
-  - .planning/STATE.md
-autonomous: true
-requirements:
-  - ARCH-01
-  - COLL-04
-must_haves:
-  truths:
-    - "包装支线里的资料库业务真相先并回主线，但不把未拍板的 5 字段唯一约束冒充已定稿。"
-    - "GSD 项目记忆必须回到当前真实主线，不能继续把旧自动组合入口当现行入口。"
-  artifacts:
-    - path: "docs/会话交接-20260411-包装支线并线与资料库收口.md"
-      provides: "这轮并线收了什么、留了什么"
-      contains: "5 字段唯一约束后续专题"
-    - path: ".planning/STATE.md"
-      provides: "当前真实恢复入口"
-      contains: "05-03"
----
-
-<objective>
-把包装支线里的基础资料库规则和迁移安全地并回主线，并顺手把 GSD 项目记忆校正到当前真实业务主线。
-
-Purpose: 收掉当前主线和包装支线之间已经拍板的资料库真相，同时修复 `.planning` 记忆滞后问题。
-Output: 可运行的主线代码、测试环境部署结果、可恢复的 GSD 项目记忆。
-</objective>
-
-<success_criteria>
-- 包装支线资料库规则并回主线后，主线仍可验证、可部署。
-- 测试环境完成部署并确认基础资料库与辅助装配主链没有回退。
-- `.planning` 的核心文件重新描述当前真实主线，而不是继续停在旧的自动组合话术。
-</success_criteria>
-

furniture-3d-system/.planning/phases/05-主链可维护性收口/05-03-SUMMARY.md

@@ -1,54 +0,0 @@
----
-phase: 05-主链可维护性收口
-plan: 03
-subsystem: material-library
-tags: [packaging-merge, material-library, prisma, deploy, gsd-memory]
-requires:
-  - phase: 05-主链可维护性收口
-    provides: 05-01 已完成第一轮服务拆分收口
-provides:
-  - 包装支线资料库规则并回主线
-  - 基材 / 花色迁移脚本与测试
-  - GSD 项目记忆刷新到当前真实主线
-affects: [phase-05, material-library, packaging-merge, planning-memory]
-requirements-progressed: [ARCH-01, COLL-04]
-completed: 2026-04-11
----
-
-# Phase 5 Plan 03 Summary
-
-**这轮先把包装支线中已经拍板的资料库真相并回主线，再把 GSD 项目记忆刷新到当前真实主线。**
-
-## Accomplishments
-
-- 已把包装支线里的 `material-library（基础资料库）` 规则并回主线，包括：
-  - `surfaceOptionId（贴面类型）` 可空
-  - `weightKg（整板重量）`
-  - `SubstrateFinish（基材-花色关联）`
-  - `BC-XXXX（基材编码）` / `HS-XXXX（花色编码）` 自动生成
-  - 花色同名仅按 `isActive（启用）` 判重
-  - 右侧详情驱动面板、临时新建花色 / 分类、缩略图上传过渡能力
-- 已新增 `Prisma（数据库）` 迁移，并在测试环境手工落库，确认数据库结构与主线代码一致。
-- 已补资料库、资产中心、辅助装配、旧订单生成装配的关键测试，并重新跑通。
-- 已把 `.planning` 的核心记忆从旧 `auto-combinations（自动组合）` 主线，校正到当前 `assisted-assembly（辅助装配） / manual assembly（手动拼装）` 主线。
-
-## Verification
-
-- `npm run type-check`
-- `npm test -- --runInBand --runTestsByPath src/app/asset-center/material-library/MaterialLibraryClient.test.tsx src/server/repositories/__tests__/material.repository.test.ts src/server/services/__tests__/material.service.test.ts src/server/services/__tests__/asset-center.substrate.service.test.ts src/server/services/__tests__/asset-center.service.test.ts`
-- `npm test -- --runInBand --runTestsByPath src/app/assisted-assembly/AssistedAssemblyClient.test.tsx src/app/__tests__/assisted-assembly-page.test.tsx src/components/platform/__tests__/AssemblyWorkbench.test.tsx src/lib/open-product/__tests__/assembly-workspace.test.ts`
-- `npm test -- --runInBand --runTestsByPath src/app/api/products/[id]/assembly/generate-from-order/__tests__/route.test.ts`
-- 测试环境部署成功，`PM2（进程管理）` 进程 `furniture-3d-system-wyj-test` 在线
-- 真实页面最小冒烟通过：资料库页可打开、辅助装配页未回退到旧自动组合文案
-
-## Risks
-
-- `5 字段唯一约束` 的最终业务规则仍未定稿，本轮只做了可运行的并线收口，不等于这项真相已经拍板完成。
-- 测试环境数据库来自旧库快照，本轮迁移采用手工执行 `migration.sql（迁移脚本）` 的方式落库，后续如需长期治理，应补一条更正式的基线说明。
-
-## Review
-
-- 结论：`passed with warnings`
-- 审查范围：架构、视觉、根因修复
-- 标注：这是自审，不是独立复审
-

furniture-3d-system/.planning/phases/05-主链可维护性收口/05-CONTEXT.md

@@ -1,127 +0,0 @@
-# Phase 5: 主链可维护性收口 - Context
-
-**Gathered:** 2026-04-03
-**Status:** Ready for planning
-
-<domain>
-## Phase Boundary
-
-本阶段只处理“主链以后还能不能继续稳着长”的结构问题：继续把核心服务按编排、校验、映射、规则拆开，继续压住旧 CAD 兼容链对新平台主链的反向侵入，并把新增主线能力继续收在 `Route -> Service -> Repository -> Prisma` 结构里。本阶段不再重做 Phase 4 功能闭环，不扩新业务范围，也不代做前端改版。
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### 服务拆分方向
-- **D-01:** Phase 5 继续沿用“从膨胀服务里抽出 scope / validation / mapper / generation / materialization”的拆分路线，而不是一次性大重构全仓库。
-- **D-02:** 已经开始拆分的主链服务优先继续收口，包括 `assembly.service.ts`、`panel.service.ts`、`planning.service.ts`，以及仍可能继续膨胀的 `intake.service.ts`、`warehouse.service.ts`。
-- **D-03:** 新拆分应优先服务“职责可预测”，让后续新增逻辑知道该放哪，而不是仅仅为了文件变多。
-
-### 新旧链边界
-- **D-04:** 新平台主链的数据真相继续锁在 `AssetFamily / AssetVariant / DraftGroup / PreSku -> Product / SKU` 这条链上，旧 `CAD / Panel / Hole / ProductHardware / AssemblyStep` 只负责兼容维护和承接，不回头主导新平台规划阶段。
-- **D-05:** 如果正式入库或轻仓库需要复用旧链对象，只允许作为“正式承接结果”或“兼容展示结果”使用，不允许反向把旧对象当成新平台前置真相。
-- **D-06:** 与旧链相关的 service 如果继续扩写，必须明确是兼容链能力，不能伪装成新平台主链 service。
-
-### 分层约束
-- **D-07:** Phase 5 要继续把 service 内直接查 Prisma 的残留点收回 repository，或者至少集中到已有 repository 能力里。
-- **D-08:** Route 继续只做收参、鉴权、返回；如果发现 Route 或页面开始兜底主业务规则，要优先回收。
-- **D-09:** 本阶段优先做“结构收口”，不为追求表面整洁去回退已经跑通的主链能力。
-
-### the agent's Discretion
-- 先拆哪一个主链 service，由 agent 按当前膨胀度和风险排序决定。
-- 是否把 Phase 5 拆成“服务继续拆分”和“边界/分层收口”两条 plan，由 agent 决定。
-
-</decisions>
-
-<canonical_refs>
-## Canonical References
-
-**Downstream agents MUST read these before planning or implementing.**
-
-### 项目级约束
-- `.planning/PROJECT.md` — 项目目标、主链与旧链并存约束
-- `.planning/ROADMAP.md` — Phase 5 的目标、依赖、成功标准
-- `.planning/REQUIREMENTS.md` — `ARCH-01`、`ARCH-02`、`ARCH-03` 的需求定义
-- `.planning/STATE.md` — 当前阶段恢复入口
-
-### 前序阶段结果
-- `.planning/phases/04-正式入库与轻仓库闭环/04-01-SUMMARY.md` — 正式入库主链已收口到什么程度
-- `.planning/phases/04-正式入库与轻仓库闭环/04-02-SUMMARY.md` — 轻仓库 overview 已收口到什么程度
-- `.planning/phases/04-正式入库与轻仓库闭环/04-03-SUMMARY.md` — 协作收口规则已固定
-
-### 协作与边界
-- `../AGENTS.md` — 全仓库标准与固定流程
-- `docs/workflow/模块边界说明.md` — 新平台主链、包装线、旧 CAD 兼容链边界
-- `docs/workflow/团队协作模式.md` — 主线职责、协作分流和收口规则
-
-### 当前服务拆分现状
-- `src/server/services/assembly.service.ts`
-- `src/server/services/assembly-generation.service.ts`
-- `src/server/services/assembly-scope.service.ts`
-- `src/server/services/assembly.mapper.ts`
-- `src/server/services/panel.service.ts`
-- `src/server/services/panel-scope.service.ts`
-- `src/server/services/panel-validation.service.ts`
-- `src/server/services/panel.mapper.ts`
-- `src/server/services/planning.service.ts`
-- `src/server/services/planning-generation.service.ts`
-- `src/server/services/planning-scope.service.ts`
-- `src/server/services/planning.mapper.ts`
-- `src/server/services/planning.service.internal.ts`
-- `src/server/services/intake.service.ts`
-- `src/server/services/warehouse.service.ts`
-
-### 相关仓储与边界接点
-- `src/server/repositories/sku.repository.ts`
-- `src/server/repositories/draft-group.repository.ts`
-- `src/server/repositories/warehouse.repository.ts`
-- `src/app/api/intake/formalize/route.ts`
-- `src/app/api/warehouse/route.ts`
-- `src/app/api/warehouse/locations/route.ts`
-- `prisma/schema.prisma`
-
-</canonical_refs>
-
-<code_context>
-## Existing Code Insights
-
-### Reusable Assets
-- `assembly.service.ts` 已经开始把生成、scope、mapper 分出去，说明 Phase 5 不需要从零定义拆分模式。
-- `panel.service.ts` 已经开始复用 `panelScopeService`、`panelValidationService`、`panel.mapper.ts`。
-- `planning.service.ts` 已经开始复用 `planningGenerationService`、`planningScopeService`、`planning.mapper.ts` 与 `planning.service.internal.ts`。
-
-### Established Patterns
-- 当前仓库已经形成“主服务 + scope/validation/mapper/helper”的拆分样式，Phase 5 应继续沿这条线推进。
-- `draft-group.service.ts` 与 `combination.service.ts` 已经比前面更轻，说明“先拆膨胀热点，再稳接口”这条路径是可行的。
-- Phase 4 已证明：如果不主动收口，`intake / warehouse` 这种主链服务会继续自然膨胀。
-
-### Integration Points
-- `intake.service.ts` 是 `PreSku -> Product / SKU / PackagingPlan / PackagedItem` 的正式承接中心，是主链结构风险高点。
-- `warehouse.service.ts` 现在已比之前更干净，但仍是 Phase 5 里要继续盯的主链读模型服务。
-- `assembly.service.ts`、`panel.service.ts`、`planning.service.ts` 是“已拆但未完全拆透”的典型点，适合继续作为 Phase 5 的结构样板。
-
-</code_context>
-
-<specifics>
-## Specific Ideas
-
-- 用户一直要求“地基打好”，Phase 5 对应的就是继续打地基，而不是再开新功能。
-- 当前最该避免的不是功能缺失，而是 Phase 4 完成功能后，主链又慢慢回到“大文件继续堆逻辑”的状态。
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-- 新功能扩展
-- 大规模前端视觉改版
-- 包装方案本体增强
-- 完整 WMS 能力
-
-</deferred>
-
----
-
-*Phase: 05-主链可维护性收口*
-*Context gathered: 2026-04-03*

furniture-3d-system/.planning/phases/05-主链可维护性收口/05-DISCUSSION-LOG.md

@@ -1,59 +0,0 @@
-# Phase 5: 主链可维护性收口 - Discussion Log
-
-> **Audit trail only.** Do not use as input to planning, research, or execution agents.
-> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
-
-**Date:** 2026-04-03
-**Phase:** 05-主链可维护性收口
-**Areas discussed:** 服务拆分方向、新旧链边界、分层约束
-
----
-
-## 服务拆分方向
-
-| Option | Description | Selected |
-|--------|-------------|----------|
-| 延续已有拆分路线，继续从膨胀服务抽 scope/validation/mapper/generation | 小步稳定收口，降低对现有主链的冲击 | ✓ |
-| 一次性大重构整个 service 层 | 风险高，容易把 Phase 4 刚收稳的主链打散 | |
-| 先不拆服务，只靠文档约束 | 结构风险仍会继续累积 | |
-
-**User's choice:** 自动模式采用推荐项，继续沿已有拆分路线推进。
-**Notes:** 当前仓库已经出现 `assembly-generation.service.ts`、`panel-scope.service.ts`、`planning.mapper.ts` 这类拆分产物，说明这条路已被验证。
-
----
-
-## 新旧链边界
-
-| Option | Description | Selected |
-|--------|-------------|----------|
-| 继续压住旧 CAD 兼容链，只允许作为兼容承接层存在 | 保持新平台主链数据真相清晰 | ✓ |
-| 让旧链对象重新参与新平台前置规划 | 会重新混淆主链真相 | |
-| 暂时不管边界，只先拆代码文件 | 容易拆完后仍然业务真相混乱 | |
-
-**User's choice:** 自动模式采用推荐项，继续压住旧链边界。
-**Notes:** ROADMAP 和模块边界文档都已经把这点写成长期约束。
-
----
-
-## 分层约束
-
-| Option | Description | Selected |
-|--------|-------------|----------|
-| 继续把 service 内直查 Prisma 的残留点回收到 repository | 让后续新增逻辑位置可预测 | ✓ |
-| 接受 service 里零散直查 Prisma | 会持续削弱分层稳定性 | |
-| 只在 Route 层补注释说明 | 不能解决结构漂移 | |
-
-**User's choice:** 自动模式采用推荐项，继续把残留直查 Prisma 收回 repository。
-**Notes:** Phase 4 的 warehouse 已经证明这种回收方式是低风险且有效的。
-
----
-
-## the agent's Discretion
-
-- Phase 5 先从哪一个主链热点 service 下手，由执行阶段再按风险排序。
-
-## Deferred Ideas
-
-- 新业务能力扩展
-- 大规模前端改版
-

furniture-3d-system/Dockerfile

@@ -7,10 +7,9 @@
 # ============================================
 # 阶段 1: 基础镜像
 # ============================================
-FROM node:18-alpine AS base
+FROM node:24-alpine AS base
 
-# 使用阿里云镜像源加速（中国网络优化）
-RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories
+# 保留官方 Alpine 源，避免镜像站同步滞后导致 apk 包 404。
 
 # ============================================
 # 阶段 2: 依赖安装 (deps)
@@ -71,6 +70,11 @@ FROM base AS builder
 ARG DATABASE_URL="postgresql://user:password@localhost:5432/placeholder_db?schema=public"
 ARG NEXTAUTH_URL=""
 ARG NEXT_PUBLIC_APP_URL=""
+ARG S3_ENDPOINT="http://localhost:9000"
+ARG S3_PUBLIC_DOMAIN="http://localhost:9000/furniture-3d-models"
+ARG S3_BUCKET="furniture-3d-models"
+ARG S3_ACCESS_KEY="build-only"
+ARG S3_SECRET_KEY="build-only"
 
 # Prisma 引擎缓存配置
 ARG PRISMA_ENGINE_CACHE_FILE_NAME="libquery_engine-linux-musl-openssl-3.0.x.so.node"
@@ -82,6 +86,12 @@ ENV PRISMA_SCHEMA_ENGINE_CACHE_FILE_NAME=${PRISMA_SCHEMA_ENGINE_CACHE_FILE_NAME}
 ENV DATABASE_URL=${DATABASE_URL}
 ENV NEXTAUTH_URL=${NEXTAUTH_URL}
 ENV NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL}
+ENV S3_ENDPOINT=${S3_ENDPOINT}
+ENV S3_PUBLIC_DOMAIN=${S3_PUBLIC_DOMAIN}
+ENV S3_BUCKET=${S3_BUCKET}
+ENV S3_ACCESS_KEY=${S3_ACCESS_KEY}
+ENV S3_SECRET_KEY=${S3_SECRET_KEY}
+ENV PUPPETEER_SKIP_DOWNLOAD=true
 ENV NEXT_TELEMETRY_DISABLED=1
 ENV NODE_ENV=production
 ENV PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING=1
@@ -237,4 +247,4 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:3000/api/health || exit 1
 
 # 启动应用
-CMD ["node", "server.js"]
+CMD ["node", "server.js"]

furniture-3d-system/README.md

@@ -1,10 +1,11 @@
-# 家具开品平台
+# 由壹点「产品开发平台」
 
-> 最后更新：2026-04-07  
-> 当前默认主线：`资产中心 -> 自动组合 -> 草稿组 -> 包装方案 -> 正式入库 -> 轻仓库`
+> 最后更新：2026-04-15  
+> 当前默认主线：`资产中心 -> 辅助装配 -> 草稿组 -> 正式入库 -> 轻仓库`
 
 这是当前正在持续开发的主项目。
 旧 `CAD -> 装配编辑 -> 装配步骤 -> 3D 回放` 链继续保留，但它属于兼容链，不再代表当前业务主线。
+包装结果当前挂在草稿组、`PreSku` 和轻仓库承接口里，不作为独立顶层页面阶段。
 
 ## 开始前先读
 
@@ -16,8 +17,8 @@
 ## 当前项目目标
 
 - 用资产族和规格款作为开品基础数据
-- 按系列规则生成自动组合候选
-- 让用户在草稿组里确认组合、预览、包装承接
+- 在辅助装配工作台完成组合、吸附、3D 预览和保存前校验
+- 让用户在草稿组里确认组合、预览，并承接包装相关信息
 - 再进入正式入库和轻仓库
 - 保留旧 CAD 链服务历史数据、兼容导入、装配编辑和回放
 
@@ -50,7 +51,7 @@ npm test
 ### 新平台主链
 
 - `/asset-center`
-- `/auto-combinations`
+- `/assisted-assembly`
 - `/draft-groups`
 - `/intake`
 - `/warehouse`
@@ -74,11 +75,11 @@ npm test
 
 - `docs/项目总览.md`
 - `docs/README.md`
-- `docs/agent-memory/README.md`
 - `docs/部署指南.md`
 - `docs/运维指南.md`
 
 ## 说明
 
 - 一次性阶段报告、测试报告和旧设计稿已清理，不再占用项目入口。
-- 前端交接单以工作区根目录 `docs/前端UI改动清单.md` 为准，不看仓库内旧副本。
+- 项目内不再维护前端交接单、会话交接或 `agent-memory` 这类台账入口。
+- 历史文档里如果还出现 `auto-combinations`、`自动组合`、`自动拼装`，统一按旧称呼理解，不再代表当前主线入口。

furniture-3d-system/agents/script-monitor/README.md

@@ -0,0 +1,30 @@
+# 供应链脚本监控 Agent
+
+每台运行脚本的机器部署一份 Agent。Agent 只主动向产品平台发起 HTTP 请求，不需要为被监控机器开放入站端口。
+
+## 接入
+
+1. 在供应链中心的“脚本监控”页面点击“接入机器”，生成独立的 `agentId` 和 `agentToken`。
+2. 复制本目录到目标机器，把 `config.example.json` 复制为 `config.json`，填入凭据、内外网地址和脚本任务说明。
+3. 先运行 `node agent.mjs` 确认上报，再使用 `pm2 start ecosystem.config.cjs` 常驻。
+
+需要在平台点击“立即运行”的脚本，必须在 `config.json` 对应任务中显式配置
+`"allowManualRun": true`。平台只会下发脚本 `key`，Agent 始终执行本机配置里预存的
+`command`，不会接收平台传来的任意命令。Agent 默认每 5 秒主动领取一次执行请求，
+因此内网机器不需要开放入站端口。
+
+`connectionMode` 支持：
+
+- `intranet`：只走内网地址。
+- `internet`：只走公网地址，生产必须使用 HTTPS。
+- `auto`：优先内网，失败后自动尝试公网。
+
+## 记录真实运行结果
+
+对于需要记录开始时间、耗时、退出码和输出的任务，用包装器代替原命令：
+
+```bash
+node /opt/furniture-script-monitor/run-script.mjs supply-chain-archive-sync
+```
+
+包装器执行 `config.json` 中同一 `key` 的 `command`，并在开始与结束时上报。Agent Token 只保存在目标机器的 `config.json`，该文件已被仓库忽略。

furniture-3d-system/agents/script-monitor/agent.mjs

@@ -0,0 +1,410 @@
+import { createHash } from 'node:crypto'
+import { execFileSync, spawn } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { hostname, platform, release } from 'node:os'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+export const AGENT_VERSION = '1.0.0'
+const AGENT_DIR = dirname(fileURLToPath(import.meta.url))
+
+function requiredText(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`缺少 ${label}`)
+  return value.trim()
+}
+
+export function loadConfig(configPath = process.env.SCRIPT_MONITOR_CONFIG || resolve(AGENT_DIR, 'config.json')) {
+  if (!existsSync(configPath)) {
+    throw new Error(`配置文件不存在：${configPath}，请复制 config.example.json 为 config.json`)
+  }
+  const config = JSON.parse(readFileSync(configPath, 'utf8'))
+  config.agentId = requiredText(config.agentId, 'agentId')
+  config.agentToken = requiredText(config.agentToken, 'agentToken')
+  config.connectionMode = String(config.connectionMode || 'auto').toLowerCase()
+  if (!['intranet', 'internet', 'auto'].includes(config.connectionMode)) {
+    throw new Error('connectionMode 必须是 intranet、internet 或 auto')
+  }
+  config.reportIntervalSec = Math.max(15, Number(config.reportIntervalSec) || 60)
+  config.requestTimeoutMs = Math.max(1000, Number(config.requestTimeoutMs) || 10000)
+  config.commandPollIntervalSec = Math.min(60, Math.max(2, Number(config.commandPollIntervalSec) || 5))
+  config.scripts = Array.isArray(config.scripts) ? config.scripts : []
+  return config
+}
+
+function normalizeCenterUrl(value) {
+  if (typeof value !== 'string' || !value.trim()) return null
+  const url = new URL(value.trim())
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error(`不支持的中心地址协议：${url.protocol}`)
+  return url.toString().replace(/\/$/, '')
+}
+
+export function resolveCenterEndpoints(config) {
+  const intranet = normalizeCenterUrl(config.centerUrls?.intranet)
+  const internet = normalizeCenterUrl(config.centerUrls?.internet)
+  const endpoints = []
+  if (config.connectionMode !== 'internet' && intranet) endpoints.push({ kind: 'INTRANET', url: intranet })
+  if (config.connectionMode !== 'intranet' && internet) endpoints.push({ kind: 'INTERNET', url: internet })
+  if (endpoints.length === 0) throw new Error('当前连接模式没有可用的 centerUrls 地址')
+  return endpoints
+}
+
+export async function postToCenter(config, route, payload) {
+  let lastError = null
+  for (const endpoint of resolveCenterEndpoints(config)) {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), config.requestTimeoutMs)
+    try {
+      const response = await fetch(`${endpoint.url}${route}`, {
+        method: 'POST',
+        signal: controller.signal,
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${config.agentToken}`,
+          'x-script-monitor-agent-id': config.agentId,
+        },
+        body: JSON.stringify({
+          ...payload,
+          ...(route.endsWith('/report')
+            ? { connectionKind: payload.connectionKind ?? endpoint.kind }
+            : {}),
+        }),
+      })
+      if (!response.ok) {
+        const message = await response.text().catch(() => '')
+        throw new Error(`HTTP ${response.status}${message ? `：${message.slice(0, 240)}` : ''}`)
+      }
+      return { endpoint, body: await response.json().catch(() => null) }
+    } catch (error) {
+      lastError = error
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+  throw lastError ?? new Error('没有可用的中心地址')
+}
+
+function hashKey(value) {
+  return createHash('sha256').update(value).digest('hex').slice(0, 20)
+}
+
+function redactCommand(command) {
+  return String(command || '')
+    .replace(/([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY)[A-Z0-9_]*=)([^\s]+)/gi, '$1[REDACTED]')
+    .replace(/(https?:\/\/[^:/\s]+:)[^@/\s]+@/gi, '$1[REDACTED]@')
+    .slice(0, 2000)
+}
+
+function readPm2() {
+  try {
+    const raw = execFileSync('pm2', ['jlist'], { encoding: 'utf8', timeout: 5000 })
+    return JSON.parse(raw)
+  } catch {
+    return []
+  }
+}
+
+function scanPm2() {
+  return readPm2().map((processInfo) => {
+    const name = String(processInfo.name || '未命名 PM2 进程')
+    const status = processInfo.pm2_env?.status === 'online'
+      ? 'RUNNING'
+      : processInfo.pm2_env?.status === 'stopped'
+        ? 'DISABLED'
+        : processInfo.pm2_env?.status === 'errored'
+          ? 'FAILED'
+          : 'UNKNOWN'
+    return {
+      key: `pm2:${name}`,
+      name,
+      taskDescription: '',
+      jobType: 'PM2',
+      schedule: null,
+      commandPreview: redactCommand(processInfo.pm2_env?.pm_exec_path || ''),
+      expectedIntervalSec: null,
+    status,
+    isEnabled: status !== 'DISABLED',
+    canManualRun: false,
+      lastStartedAt: processInfo.pm2_env?.pm_uptime
+        ? new Date(processInfo.pm2_env.pm_uptime).toISOString()
+        : null,
+      lastResultSummary: status === 'RUNNING'
+        ? `PM2 在线，PID ${processInfo.pid || '-'}`
+        : `PM2 状态：${processInfo.pm2_env?.status || 'unknown'}`,
+    }
+  })
+}
+
+function parseCronLine(line) {
+  const value = line.trim()
+  if (!value || value.startsWith('#')) return null
+  const special = value.match(/^@(reboot|yearly|annually|monthly|weekly|daily|hourly)\s+(.+)$/)
+  const regular = value.match(/^(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+(.+)$/)
+  const schedule = special ? `@${special[1]}` : regular?.[1]
+  const command = special?.[2] ?? regular?.[2]
+  if (!schedule || !command) return null
+  const tag = command.match(/#\s*([\w.-]{3,})\s*$/)?.[1]
+  const name = tag || command.split(/\s+/).filter(Boolean).slice(-1)[0] || 'cron task'
+  return {
+    key: `cron:${hashKey(`${schedule}\n${command}`)}`,
+    name,
+    taskDescription: '',
+    jobType: 'CRON',
+    schedule,
+    commandPreview: redactCommand(command.replace(/\s+#.*$/, '')),
+    expectedIntervalSec: null,
+    status: 'UNKNOWN',
+    isEnabled: true,
+    canManualRun: false,
+  }
+}
+
+function scanCron() {
+  if (platform() === 'win32') return []
+  try {
+    const raw = execFileSync('crontab', ['-l'], { encoding: 'utf8', timeout: 5000 })
+    return raw.split(/\r?\n/).map(parseCronLine).filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+function checkProcess(name) {
+  try {
+    if (platform() === 'win32') {
+      const output = execFileSync('tasklist', ['/FI', `IMAGENAME eq ${name}`], { encoding: 'utf8', timeout: 4000 })
+      return output.toLowerCase().includes(String(name).toLowerCase())
+    }
+    execFileSync('pgrep', ['-f', '--', name], { stdio: 'ignore', timeout: 4000 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function checkConfiguredScript(script) {
+  if (script.enabled === false) return { status: 'DISABLED', summary: '监控已停用' }
+  const check = script.resultCheck
+  if (!check) return { status: 'UNKNOWN', summary: null }
+
+  if (check.type === 'file') {
+    try {
+      const stat = statSync(requiredText(check.path, 'resultCheck.path'))
+      const ageSec = Math.max(0, Math.round((Date.now() - stat.mtimeMs) / 1000))
+      const fresh = !check.maxAgeSec || ageSec <= Number(check.maxAgeSec)
+      const largeEnough = check.minBytes == null || stat.size >= Number(check.minBytes)
+      return {
+        status: fresh && largeEnough ? 'SUCCESS' : 'FAILED',
+        summary: `文件 ${stat.size} B，${ageSec} 秒前更新`,
+      }
+    } catch (error) {
+      return { status: 'FAILED', summary: `文件检查失败：${error.message}` }
+    }
+  }
+
+  if (check.type === 'systemd') {
+    try {
+      const service = requiredText(check.service, 'resultCheck.service')
+      const state = execFileSync('systemctl', ['is-active', service], { encoding: 'utf8', timeout: 4000 }).trim()
+      return { status: state === 'active' ? 'RUNNING' : 'FAILED', summary: `systemd：${state}` }
+    } catch {
+      return { status: 'FAILED', summary: 'systemd 服务未运行' }
+    }
+  }
+
+  if (check.type === 'process') {
+    const running = checkProcess(requiredText(check.name, 'resultCheck.name'))
+    return { status: running ? 'RUNNING' : 'FAILED', summary: running ? '进程正在运行' : '未找到目标进程' }
+  }
+
+  return { status: 'UNKNOWN', summary: '未识别的结果检查类型' }
+}
+
+function normalizeConfiguredScript(script) {
+  const key = requiredText(script.key, 'scripts[].key')
+  const result = checkConfiguredScript(script)
+  return {
+    key,
+    name: requiredText(script.name, `scripts[${key}].name`),
+    taskDescription: String(script.taskDescription || '').slice(0, 2000),
+    jobType: String(script.jobType || 'OTHER').toUpperCase(),
+    schedule: script.schedule ? String(script.schedule).slice(0, 240) : null,
+    commandPreview: redactCommand(script.commandPreview || script.command || ''),
+    expectedIntervalSec: script.expectedIntervalSec ? Number(script.expectedIntervalSec) : null,
+    status: result.status,
+    isEnabled: script.enabled !== false,
+    canManualRun: script.allowManualRun === true && Boolean(script.command),
+    lastResultSummary: result.summary,
+  }
+}
+
+export function collectScripts(config) {
+  const byKey = new Map()
+  if (config.autoDiscover?.cron !== false) {
+    for (const script of scanCron()) byKey.set(script.key, script)
+  }
+  if (config.autoDiscover?.pm2 !== false) {
+    for (const script of scanPm2()) byKey.set(script.key, script)
+  }
+  for (const script of config.scripts) {
+    const normalized = normalizeConfiguredScript(script)
+    byKey.set(normalized.key, { ...(byKey.get(normalized.key) || {}), ...normalized })
+  }
+  return [...byKey.values()]
+}
+
+export async function reportSnapshot(config) {
+  const scripts = collectScripts(config)
+  const result = await postToCenter(config, '/api/internal/script-monitor/report', {
+    hostname: hostname(),
+    os: `${platform()} ${release()}`,
+    agentVersion: AGENT_VERSION,
+    reportIntervalSec: config.reportIntervalSec,
+    scripts,
+  })
+  console.log(`[script-monitor] 已通过${result.endpoint.kind === 'INTRANET' ? '内网' : '公网'}上报 ${scripts.length} 个脚本`)
+}
+
+function keepTail(current, chunk, limit = 12000) {
+  const next = current + chunk.toString()
+  return next.length > limit ? next.slice(-limit) : next
+}
+
+async function reportManualRun(config, command, input) {
+  return postToCenter(config, '/api/internal/script-monitor/run', {
+    commandId: command.id,
+    scriptKey: command.scriptKey,
+    scriptName: command.scriptName,
+    taskDescription: command.taskDescription || '',
+    jobType: String(command.jobType || 'OTHER').toUpperCase(),
+    ...input,
+  })
+}
+
+export async function executeManualCommand(config, command) {
+  const script = config.scripts.find((item) => item.key === command.scriptKey)
+  const startedAt = new Date()
+  const externalRunId = `manual:${command.id}`
+  if (!script?.command || script.allowManualRun !== true) {
+    const message = 'Agent 配置未开放该脚本的手动运行权限'
+    await reportManualRun(config, command, {
+      externalRunId,
+      status: 'FAILED',
+      trigger: 'manual',
+      startedAt: startedAt.toISOString(),
+      finishedAt: new Date().toISOString(),
+      durationMs: 0,
+      exitCode: 1,
+      resultSummary: message,
+      errorTail: message,
+    })
+    return
+  }
+
+  await reportManualRun(config, command, {
+    externalRunId,
+    status: 'RUNNING',
+    trigger: 'manual',
+    startedAt: startedAt.toISOString(),
+  })
+  let outputTail = ''
+  let errorTail = ''
+  try {
+    const child = spawn(script.command, {
+      cwd: script.cwd ? resolve(script.cwd) : process.cwd(),
+      env: process.env,
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    child.stdout.on('data', (chunk) => {
+      outputTail = keepTail(outputTail, chunk)
+      process.stdout.write(chunk)
+    })
+    child.stderr.on('data', (chunk) => {
+      errorTail = keepTail(errorTail, chunk)
+      process.stderr.write(chunk)
+    })
+    const exitCode = await new Promise((resolveExit, reject) => {
+      child.once('error', reject)
+      child.once('close', (code) => resolveExit(code ?? 1))
+    })
+    const finishedAt = new Date()
+    await reportManualRun(config, command, {
+      externalRunId,
+      status: exitCode === 0 ? 'SUCCESS' : 'FAILED',
+      trigger: 'manual',
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      durationMs: finishedAt.getTime() - startedAt.getTime(),
+      exitCode,
+      resultSummary: exitCode === 0 ? '手动运行成功' : `手动运行失败，退出码 ${exitCode}`,
+      outputTail,
+      errorTail,
+    })
+  } catch (error) {
+    const finishedAt = new Date()
+    await reportManualRun(config, command, {
+      externalRunId,
+      status: 'FAILED',
+      trigger: 'manual',
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      durationMs: finishedAt.getTime() - startedAt.getTime(),
+      exitCode: 1,
+      resultSummary: `手动运行启动失败：${error.message}`,
+      errorTail: error.message,
+    })
+  }
+}
+
+export async function pollManualCommand(config) {
+  const result = await postToCenter(
+    config,
+    '/api/internal/script-monitor/commands/claim',
+    {},
+  )
+  const command = result.body?.data?.command
+  if (!command) return false
+  await executeManualCommand(config, command)
+  return true
+}
+
+async function main() {
+  const config = loadConfig()
+  const run = async () => {
+    try {
+      await reportSnapshot(config)
+    } catch (error) {
+      console.error('[script-monitor] 上报失败：', error.message)
+    }
+  }
+  let commandBusy = false
+  const poll = async () => {
+    if (commandBusy) return
+    commandBusy = true
+    try {
+      await pollManualCommand(config)
+    } catch (error) {
+      console.error('[script-monitor] 手动任务轮询失败：', error.message)
+    } finally {
+      commandBusy = false
+    }
+  }
+  await run()
+  await poll()
+  const timer = setInterval(run, config.reportIntervalSec * 1000)
+  const commandTimer = setInterval(poll, config.commandPollIntervalSec * 1000)
+  const stop = () => {
+    clearInterval(timer)
+    clearInterval(commandTimer)
+    process.exit(0)
+  }
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main().catch((error) => {
+    console.error('[script-monitor] 启动失败：', error.message)
+    process.exit(1)
+  })
+}

furniture-3d-system/agents/script-monitor/agent.test.mjs

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { executeManualCommand } from './agent.mjs'
+
+function config(overrides = {}) {
+  return {
+    agentId: 'agent-1',
+    agentToken: 'secret-token',
+    connectionMode: 'internet',
+    centerUrls: { internet: 'https://monitor.example.test' },
+    requestTimeoutMs: 5000,
+    scripts: [{
+      key: 'local-check',
+      name: '本机检查',
+      taskDescription: '验证手动触发',
+      jobType: 'MANUAL',
+      allowManualRun: true,
+      command: `${JSON.stringify(process.execPath)} -e "console.log('manual-ok')"`,
+    }],
+    ...overrides,
+  }
+}
+
+function command() {
+  return {
+    id: 'command-1',
+    scriptKey: 'local-check',
+    scriptName: '本机检查',
+    taskDescription: '验证手动触发',
+    jobType: 'MANUAL',
+  }
+}
+
+test('manual command executes only the local configured command and reports its result', async () => {
+  const previousFetch = globalThis.fetch
+  const reports = []
+  globalThis.fetch = async (_url, init) => {
+    reports.push(JSON.parse(init.body))
+    return new Response(JSON.stringify({ success: true, data: { ok: true } }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })
+  }
+  try {
+    await executeManualCommand(config(), command())
+  } finally {
+    globalThis.fetch = previousFetch
+  }
+
+  assert.equal(reports.length, 2)
+  assert.equal(reports[0].status, 'RUNNING')
+  assert.equal(reports[1].status, 'SUCCESS')
+  assert.equal(reports[1].exitCode, 0)
+  assert.match(reports[1].outputTail, /manual-ok/)
+  assert.equal(reports[1].commandId, 'command-1')
+})
+
+test('manual command is rejected when allowManualRun is not explicitly enabled', async () => {
+  const previousFetch = globalThis.fetch
+  const reports = []
+  globalThis.fetch = async (_url, init) => {
+    reports.push(JSON.parse(init.body))
+    return new Response(JSON.stringify({ success: true, data: { ok: true } }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })
+  }
+  const blockedConfig = config()
+  blockedConfig.scripts[0].allowManualRun = false
+  try {
+    await executeManualCommand(blockedConfig, command())
+  } finally {
+    globalThis.fetch = previousFetch
+  }
+
+  assert.equal(reports.length, 1)
+  assert.equal(reports[0].status, 'FAILED')
+  assert.match(reports[0].resultSummary, /未开放/)
+})

furniture-3d-system/agents/script-monitor/config.example.json

@@ -0,0 +1,36 @@
+{
+  "agentId": "PASTE_AGENT_ID_HERE",
+  "agentToken": "PASTE_AGENT_TOKEN_HERE",
+  "agentName": "仓库服务器 01",
+  "connectionMode": "auto",
+  "centerUrls": {
+    "intranet": "http://10.0.0.20:3001",
+    "internet": "https://cp.jiansun.vip"
+  },
+  "reportIntervalSec": 60,
+  "commandPollIntervalSec": 5,
+  "requestTimeoutMs": 10000,
+  "autoDiscover": {
+    "cron": true,
+    "pm2": true
+  },
+  "scripts": [
+    {
+      "key": "supply-chain-archive-sync",
+      "name": "供应链产品档案同步",
+      "taskDescription": "同步聚水潭商品档案、仓库和供应商扩展字段",
+      "jobType": "CRON",
+      "schedule": "*/15 * * * *",
+      "expectedIntervalSec": 900,
+      "allowManualRun": true,
+      "command": "npm run sync:supply-chain-product-archive",
+      "cwd": "/opt/furniture-3d-system-prod/current",
+      "resultCheck": {
+        "type": "file",
+        "path": "/opt/furniture-3d-system-prod/shared/logs/product-archive-sync.log",
+        "maxAgeSec": 1800,
+        "minBytes": 1
+      }
+    }
+  ]
+}

furniture-3d-system/agents/script-monitor/ecosystem.config.cjs

@@ -0,0 +1,15 @@
+module.exports = {
+  apps: [{
+    name: 'furniture-script-monitor-agent',
+    script: 'agent.mjs',
+    cwd: __dirname,
+    instances: 1,
+    exec_mode: 'fork',
+    autorestart: true,
+    watch: false,
+    env: {
+      NODE_ENV: 'production',
+      SCRIPT_MONITOR_CONFIG: `${__dirname}/config.json`,
+    },
+  }],
+}

furniture-3d-system/agents/script-monitor/run-script.mjs

@@ -0,0 +1,82 @@
+import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { resolve } from 'node:path'
+import { loadConfig, postToCenter } from './agent.mjs'
+
+function keepTail(current, chunk, limit = 12000) {
+  const next = current + chunk.toString()
+  return next.length > limit ? next.slice(-limit) : next
+}
+
+async function sendRun(config, script, input) {
+  return postToCenter(config, '/api/internal/script-monitor/run', {
+    scriptKey: script.key,
+    scriptName: script.name,
+    taskDescription: script.taskDescription || '',
+    jobType: String(script.jobType || 'OTHER').toUpperCase(),
+    ...input,
+  })
+}
+
+async function main() {
+  const scriptKey = process.argv[2]
+  if (!scriptKey) throw new Error('用法：node run-script.mjs <script-key>')
+  const config = loadConfig()
+  const script = config.scripts.find((item) => item.key === scriptKey)
+  if (!script) throw new Error(`配置中不存在脚本：${scriptKey}`)
+  if (!script.command) throw new Error(`脚本 ${scriptKey} 未配置 command`)
+
+  const externalRunId = `${scriptKey}:${randomUUID()}`
+  const startedAt = new Date()
+  await sendRun(config, script, {
+    externalRunId,
+    status: 'RUNNING',
+    trigger: 'wrapper',
+    startedAt: startedAt.toISOString(),
+  }).catch((error) => {
+    console.warn('[script-monitor-run] 开始状态上报失败，不阻断原脚本：', error.message)
+  })
+
+  let outputTail = ''
+  let errorTail = ''
+  const child = spawn(script.command, {
+    cwd: script.cwd ? resolve(script.cwd) : process.cwd(),
+    env: process.env,
+    shell: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  child.stdout.on('data', (chunk) => {
+    outputTail = keepTail(outputTail, chunk)
+    process.stdout.write(chunk)
+  })
+  child.stderr.on('data', (chunk) => {
+    errorTail = keepTail(errorTail, chunk)
+    process.stderr.write(chunk)
+  })
+
+  const exitCode = await new Promise((resolveExit, reject) => {
+    child.once('error', reject)
+    child.once('close', (code) => resolveExit(code ?? 1))
+  })
+  const finishedAt = new Date()
+  await sendRun(config, script, {
+    externalRunId,
+    status: exitCode === 0 ? 'SUCCESS' : 'FAILED',
+    trigger: 'wrapper',
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    durationMs: finishedAt.getTime() - startedAt.getTime(),
+    exitCode,
+    resultSummary: exitCode === 0 ? '脚本执行成功' : `脚本退出码 ${exitCode}`,
+    outputTail,
+    errorTail,
+  }).catch((error) => {
+    console.warn('[script-monitor-run] 运行结果上报失败，保留原退出码：', error.message)
+  })
+  process.exitCode = exitCode
+}
+
+main().catch((error) => {
+  console.error('[script-monitor-run] 执行失败：', error.message)
+  process.exitCode = 1
+})

furniture-3d-system/data/freight-config/province-shipment-share.json

@@ -0,0 +1,257 @@
+{
+  "version": 1,
+  "generatedAt": "2026-10-26T08:52:26.453Z",
+  "sourceFile": "各省发货占比.xlsx",
+  "totalShipment": 10983200,
+  "rowCount": 31,
+  "rows": [
+    {
+      "province": "安徽",
+      "shipmentCount": 426181,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.038803,
+      "region": "一区",
+      "regionShare": 0.214
+    },
+    {
+      "province": "江苏",
+      "shipmentCount": 800646,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.072897,
+      "region": "一区",
+      "regionShare": 0.214
+    },
+    {
+      "province": "上海",
+      "shipmentCount": 325564,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.029642,
+      "region": "一区",
+      "regionShare": 0.214
+    },
+    {
+      "province": "浙江",
+      "shipmentCount": 797004,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.072566,
+      "region": "一区",
+      "regionShare": 0.214
+    },
+    {
+      "province": "北京",
+      "shipmentCount": 290861,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.026482,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "福建",
+      "shipmentCount": 467880,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.0426,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "广东",
+      "shipmentCount": 1820992,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.165798,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "河北",
+      "shipmentCount": 424406,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.038641,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "河南",
+      "shipmentCount": 546529,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.04976,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "湖北",
+      "shipmentCount": 378469,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.034459,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "湖南",
+      "shipmentCount": 386336,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.035175,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "江西",
+      "shipmentCount": 271676,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.024736,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "山东",
+      "shipmentCount": 626419,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.057034,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "天津",
+      "shipmentCount": 115475,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.010514,
+      "region": "二区",
+      "regionShare": 0.485
+    },
+    {
+      "province": "广西",
+      "shipmentCount": 397325,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.036176,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "贵州",
+      "shipmentCount": 242963,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.022121,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "黑龙",
+      "shipmentCount": 166557,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.015165,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "吉林",
+      "shipmentCount": 135735,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.012358,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "辽宁",
+      "shipmentCount": 257754,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.023468,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "山西",
+      "shipmentCount": 177480,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.016159,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "陕西",
+      "shipmentCount": 281956,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.025672,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "四川",
+      "shipmentCount": 532179,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.048454,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "云南",
+      "shipmentCount": 341852,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.031125,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "重庆",
+      "shipmentCount": 222288,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.020239,
+      "region": "三区",
+      "regionShare": 0.251
+    },
+    {
+      "province": "甘肃",
+      "shipmentCount": 144419,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.013149,
+      "region": "四区",
+      "regionShare": 0.05
+    },
+    {
+      "province": "海南",
+      "shipmentCount": 148380,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.01351,
+      "region": "四区",
+      "regionShare": 0.05
+    },
+    {
+      "province": "内蒙",
+      "shipmentCount": 166636,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.015172,
+      "region": "四区",
+      "regionShare": 0.05
+    },
+    {
+      "province": "宁夏",
+      "shipmentCount": 47493,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.004324,
+      "region": "四区",
+      "regionShare": 0.05
+    },
+    {
+      "province": "青海",
+      "shipmentCount": 39031,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.003554,
+      "region": "四区",
+      "regionShare": 0.05
+    },
+    {
+      "province": "西藏",
+      "shipmentCount": 441,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.00004,
+      "region": "未分区",
+      "regionShare": 0.0002471046689489402
+    },
+    {
+      "province": "新疆",
+      "shipmentCount": 2273,
+      "totalShipment": 10983200,
+      "shipmentShare": 0.000207,
+      "region": "未分区",
+      "regionShare": 0.0002471046689489402
+    }
+  ]
+}

furniture-3d-system/docs/DEPLOYMENT.md

@@ -59,10 +59,13 @@ docker-compose -f docker-compose.lightweight.yml up -d
 ### 4. 初始化数据库
 ```bash
 # 进入应用容器执行迁移
-docker exec -it furniture3d-app npx prisma db push
+docker exec -it furniture3d-app npx prisma migrate deploy
 
 # 或在本地执行（需要数据库可访问）
-npx prisma db push
+npx prisma migrate deploy
+
+# 迁移后验证主数据地基
+npm run db:verify-master-data:all:strict
 ```
 
 ### 5. 访问系统
@@ -134,19 +137,22 @@ JWT_EXPIRES_IN=7d
 
 ### 首次部署
 ```bash
-# 推送 schema 到数据库
-npx prisma db push
+# 应用 Prisma migration，保留 _prisma_migrations 历史
+npx prisma migrate deploy
 
 # 生成 Prisma Client
 npx prisma generate
+
+# 验证主数据迁移、视图、约束和 JSON 边界
+npm run db:verify-master-data:all:strict
 ```
 
 ### 后续更新（Schema 变更）
 ```bash
-# 开发环境：直接推送
-npx prisma db push
+# 仅本地临时开发环境可用；脚本会拒绝 production、非本机库和疑似生产库名
+npm run prisma:push
 
-# 生产环境：使用迁移（推荐）
+# 生产环境：必须使用迁移
 npx prisma migrate deploy
 ```
 
@@ -272,10 +278,13 @@ docker-compose -f docker-compose.prod.yml build app
 docker-compose -f docker-compose.prod.yml up -d app
 
 # 执行数据库迁移（如有）
-docker exec -it furniture3d-app npx prisma db push
+docker exec -it furniture3d-app npx prisma migrate deploy
+docker exec -it furniture3d-app npm run db:verify-master-data:all:strict
 ```
 
 ### 重要提示
 - 更新前请先备份数据库
 - 测试环境验证后再更新生产环境
 - 保留旧版本镜像以便回滚
+- 生产/准生产禁止用 `prisma db push` 替代迁移；否则会绕过 `_prisma_migrations`，后续无法证明数据库结构来源。
+- 仓库内 `npm run prisma:push` 只作为本地开发保护入口：默认只允许 `localhost / 127.0.0.1 / ::1`，拒绝 `NODE_ENV=production`、`VERCEL_ENV=production` 和疑似生产库名。

furniture-3d-system/docs/README.md

@@ -1,7 +1,7 @@
-# 家具开品平台文档导航
+# 由壹点「产品开发平台」文档导航
 
-> 最后更新：2026-04-07  
-> 这份导航只突出当前有效入口，历史阶段文档不再和现行入口混排。
+> 最后更新：2026-04-15  
+> 当前主线入口：`/asset-center -> /assisted-assembly -> /draft-groups -> /intake -> /warehouse`
 
 ## 当前必读入口
 
@@ -16,15 +16,12 @@
 ### 项目现状
 
 - [项目总览](./项目总览.md)
-- [长期记忆导航](./agent-memory/README.md)
-- [长期决策日志](./agent-memory/decision-log.md)
-- [长期待办与阻塞](./agent-memory/open-issues.md)
 
 ### 业务与架构
 
 - [认证系统设计](./架构设计/auth-system-design.md)
 - [权限系统设计](./架构设计/permission-design-v2.md)
-- [新平台一期实施计划](./架构设计/新平台一期-资产中心与自动拼装实施计划-20260331.md)
+- [新平台一期实施计划（历史文件名保留“自动拼装”字样）](./架构设计/新平台一期-资产中心与自动拼装实施计划-20260331.md)
 
 ### 开发与运维
 
@@ -53,4 +50,9 @@
 2. [团队协作模式](./workflow/团队协作模式.md)
 3. [模块边界说明](./workflow/模块边界说明.md)
 4. [主线同步操作手册](./workflow/主线同步操作手册.md)
-5. [agent-memory/README](./agent-memory/README.md)
+
+## 当前说明
+
+- 部分历史文档或文件名仍保留“自动拼装 / 自动组合 / auto-combinations”等旧称呼；当前一律按“辅助装配（assisted-assembly）”理解。
+- 这份导航只保留有效入口；具体任务边界以当前任务单、交接摘要、已确认协作信息和实际代码现状为准。
+- `main` 继续由 `WuYongJie` 负责收口。

furniture-3d-system/docs/agent-memory/README.md

@@ -18,8 +18,9 @@
 
 ## 当前主线口径
 
-- 默认主线：`资产中心 -> 自动组合 -> 草稿组 -> 包装方案 -> 正式入库 -> 轻仓库`
+- 默认主线：`资产中心 -> 辅助装配 -> 草稿组 -> 正式入库 -> 轻仓库`
 - 旧 CAD 装配链：兼容链，不是默认主线
+- 历史文档或文件名里的 `自动组合`、`自动拼装`、`auto-combinations` 只按旧称呼理解，不再代表当前页面入口或系列资料口径。
 
 ## 文件分工
 

furniture-3d-system/docs/agent-memory/decision-log.md

@@ -2,8 +2,9 @@
 
 | 日期 | 决策 | 原因 | 影响范围 | 状态 |
 |---|---|---|---|---|
+| 2026-05-18 | 旧“自动组合 / 自动拼装 / 固定模板”口径降级为历史兼容称呼，当前主线统一为“资产中心 -> 辅助装配 -> 草稿组 -> 正式入库 -> 轻仓库” | 系列资料和长期记忆里残留旧模板描述，会误导资产中心和后续 AI 把已取消的自动拼装当成当前入口 | `AssetSeries` 资料、`docs/agent-memory/*`、后续 AI 会话上下文 | 已生效 |
 | 2026-04-07 | 文档入口收口到“当前主线入口 + 历史参考分层”，删除重复副本和明显过时文档 | 旧入口混有过时阶段总结、旧 UI 方案和重复清单，容易把人和 AI 带回旧主线 | 根 README、仓库 README、docs 导航、agent-memory、重复旧文档 | 已生效 |
-| 2026-04-07 | 项目长期记忆主目标从“CAD 装配编辑”切回“资产中心 -> 自动组合 -> 草稿组 -> 包装方案 -> 正式入库 -> 轻仓库” | 当前业务主线已经变化，如果不先修正 agent-memory，后续 AI 会持续沿用错误目标 | `docs/agent-memory/*` 与后续所有 AI 会话上下文 | 已生效 |
+| 2026-04-07 | 项目长期记忆主目标从“CAD 装配编辑”切回当时的新平台开品链 | 当时业务主线已经变化，如果不先修正 agent-memory，后续 AI 会持续沿用更早的 CAD 目标 | `docs/agent-memory/*` 与后续所有 AI 会话上下文 | 已被 2026-05-18 决策替代 |
 | 2026-03-13 | 协作流程收敛为“直接开发 + 规范审查闸门” | 避免运行时协作策略干扰主线开发，把硬规则稳定落到每次交付的固定步骤里 | 全项目默认协作方式、交付口径、审查流程 | 已生效 |
 | 2026-03-05 | SKU详情页/装配编辑器节点解析统一到“模型真实节点映射 + canonical 别名解析”，并将 3D 拾取容差改为“中心命中优先 + 最近命中优先” | 修复 SKU 详情与装配编辑器点选规则不一致、折角线锚点错位，以及点选漂移导致的误选/漏选 | `SKUDetailClient.workspace`、`install-order-node-resolution`、`model-viewer-pick-tolerance` | 已生效 |
 | 2026-02-27 | 装配编辑器本轮收口：修复可见乱码文案、步骤编辑器响应式布局、孔位高亮坐标解算改为“panel/modelRoot 双坐标根候选择优” | 解决页面可用性问题并降低孔位错绑/爆炸状态漂移 | `AssemblyEditorWorkspace`、`AssemblyStepEditor`、`HoleOverlay2D` | 已生效 |

furniture-3d-system/docs/agent-memory/open-issues.md

@@ -1,6 +1,6 @@
 # 待办与阻塞（长期）
 
-最后更新：2026-04-07
+最后更新：2026-05-18
 
 ## P0
 
@@ -10,10 +10,10 @@
   - 证据：`src/app/asset-center/AssetCenterClient.tsx`、工作区根目录 `docs/前端UI改动清单.md`
   - 状态：处理中
 
-- 问题：自动组合、草稿组、包装承接这条主线还在持续联调。
+- 问题：辅助装配、草稿组、正式入库这条主线还在持续联调。
   - 责任角色：主线负责人 / 前端 / 包装负责人
-  - 下一步：继续验证候选预览、草稿组承接、包装占位和正式入库之间的真实业务闭环
-  - 证据：`src/app/auto-combinations`、`src/app/draft-groups`、`src/app/intake`
+  - 下一步：继续验证辅助装配保存、草稿组承接、包装占位和正式入库之间的真实业务闭环
+  - 证据：`src/app/assisted-assembly`、`src/app/draft-groups`、`src/app/intake`
   - 状态：处理中
 
 - 问题：文档和 AI 记忆已经做过一次清理，但后续如果不持续维护，仍会再次回到多口径状态。

furniture-3d-system/docs/agent-memory/project-context.md

@@ -1,12 +1,13 @@
 # 项目上下文（长期）
 
-最后更新：2026-04-07
+最后更新：2026-05-18
 
 ## 项目目标
 
-- 当前主线目标：用资产中心沉淀资产数据，再通过自动组合、草稿组、包装承接、正式入库和轻仓库形成开品闭环。
-- 当前默认主线：`资产中心 -> 自动组合 -> 草稿组 -> 包装方案 -> 正式入库 -> 轻仓库`
+- 当前主线目标：用资产中心沉淀资产数据，再通过辅助装配、草稿组、正式入库和轻仓库形成开品闭环。
+- 当前默认主线：`资产中心 -> 辅助装配 -> 草稿组 -> 正式入库 -> 轻仓库`
 - 旧 `CAD -> 装配编辑 -> 装配步骤 -> 回放` 链继续保留，但属于兼容链。
+- 历史 `自动组合 / 自动拼装 / auto-combinations` 只作为旧称呼或兼容资料理解，不再代表当前主链入口。
 
 ## 当前硬约束
 
@@ -19,7 +20,7 @@
 ## 当前项目最容易出问题的地方
 
 - 资产命名、连接角色、系列规则继续出现自由输入，导致脏数据进入主线
-- 自动组合候选与 3D 预览结果不一致
+- 辅助装配保存、草稿组承接与正式入库资料同步不一致
 - 包装承接口和主线真相混层
 - 旧兼容链的历史逻辑反向污染新平台主线
 

furniture-3d-system/docs/integrations/dropship-return-address-push-api.md

@@ -0,0 +1,109 @@
+# 1688代发异常事项：退货地址推送接口
+
+## 交付与启用
+
+本接口供外部系统按 SPU 推送退货地址。正式站发布包含该接口的版本并配置独立密钥后，对方即可按本文调用。
+
+部署人员在生产运行环境配置 `DROPSHIP_RETURN_ADDRESS_API_KEY`，使用独立随机密钥（建议至少32个随机字节），由双方通过安全渠道交接；密钥不进入 Git、对接文档、URL 或普通日志。未配置时接口返回503。无需提供数据库账号，无需平台用户登录。
+
+## 请求
+
+- 方法：`POST`
+- 正式地址：`https://cp.jiansun.vip/api/external/supply-chain/dropship-return-addresses`
+- 本地联调：`http://localhost:3001/api/external/supply-chain/dropship-return-addresses`
+- 请求头：`Content-Type: application/json`、`x-api-key: <对接密钥>`
+- 每批1–100条；单条推送也使用 `items` 数组。
+
+```json
+{
+  "items": [
+    {
+      "spu": "DF-C1YMJ0009",
+      "returnAddress": "收件人：张三；电话：138xxxxxxxx；地址：江苏省……"
+    }
+  ]
+}
+```
+
+| 字段 | 必填 | 规则 |
+| --- | --- | --- |
+| `spu` | 是 | 1–120位字母、数字、下划线或连字符；自动去除首尾空格并转为大写 |
+| `returnAddress` | 是 | 去除首尾空格后1–500字；收件人、电话、详细地址合并为一段文字 |
+
+仅接收上述字段。额外传入发票类型、安装方式等字段，该条会失败，不会改动这些字段。
+
+调用示例（密钥由调用方运行环境注入）：
+
+```bash
+curl --request POST \
+  'https://cp.jiansun.vip/api/external/supply-chain/dropship-return-addresses' \
+  --header 'Content-Type: application/json' \
+  --header "x-api-key: ${DROPSHIP_RETURN_ADDRESS_API_KEY}" \
+  --data '{"items":[{"spu":"DF-C1YMJ0009","returnAddress":"收件人：张三；电话：138xxxxxxxx；地址：江苏省……"}]}'
+```
+
+## 写入规则
+
+1. 一SPU一退货地址，同SPU下所有SKU共用；按档案中的DF代发范围核验，不受当月业绩筛选影响。
+2. SPU必须已存在于产品档案。没有维护记录时自动创建维护记录；不会创建产品档案。
+3. 新地址覆盖该SPU原有地址（包括人工填写的地址），以数据库实际处理顺序为准。
+4. 只更新退货地址和维护人/时间，保留发票类型、整装/拆装；新增维护记录时其他字段使用原有空值默认值。
+5. 空地址拒绝，不能通过这个接口清空地址。重复推送同一地址返回 `UNCHANGED`，不重复写入或变更时间。
+6. 同批重复SPU（含大小写/首尾空格差异）的重复项全部失败，其余条目继续处理；每批按输入顺序返回结果。
+7. 每条独立保存，某条失败不撤销已经成功的条目。实际地址变化写入1688代发异常事项操作日志，标记“外部退货地址同步”，包含前后值与请求编号。
+8. 当前页面默认只显示有业绩SPU；无业绩产品推送成功后，切换“全部SPU”查看。
+
+## 响应
+
+HTTP200表示批次已处理，**仍须检查 `data.failedCount` 和每条 `status`**。
+
+```json
+{
+  "success": true,
+  "data": {
+    "total": 2,
+    "successCount": 1,
+    "failedCount": 1,
+    "updatedCount": 1,
+    "unchangedCount": 0,
+    "results": [
+      {
+        "index": 1,
+        "spu": "DF-C1YMJ0009",
+        "status": "UPDATED",
+        "updatedAt": "2026-10-24T04:00:00.000Z"
+      },
+      {
+        "index": 2,
+        "spu": "DF-MISSING",
+        "status": "FAILED",
+        "code": "SPU_NOT_FOUND",
+        "message": "产品档案中不存在该代发 SPU"
+      }
+    ]
+  },
+  "meta": {
+    "requestId": "服务端请求编号",
+    "timestamp": "2026-10-24T04:00:00.000Z"
+  }
+}
+```
+
+`index` 从1开始，对应请求数组顺序；`UPDATED` 表示新增或更新成功，`UNCHANGED` 表示地址已一致。两种均计入 `successCount`。时间使用UTC ISO8601格式。
+
+| 每条失败码 | 含义与处理 |
+| --- | --- |
+| `INVALID_ITEM` | 字段格式、地址为空/过长或包含额外字段；修正数据后重推 |
+| `DUPLICATE_SPU` | 同批存在重复SPU；去重后重推 |
+| `SPU_NOT_FOUND` | 不存在对应DF代发档案；核对SPU或等待档案同步后重推 |
+| `WRITE_FAILED` | 保存失败；重试该条，持续失败时附 `meta.requestId` 联系管理员 |
+
+| HTTP状态 | 含义 |
+| --- | --- |
+| 200 | 批次已处理，检查逐条结果 |
+| 400 | 非法JSON、缺少items、空批次、超过100条或多余顶层字段；整批不写入 |
+| 401 | 缺少密钥或密钥错误；整批不写入 |
+| 503 | 服务端未配置对接密钥；整批不写入 |
+| 500 | 系统错误；提供请求编号排查 |
+
+网络超时或500时可能已有部分条目保存。可重推相同地址；如果期间出现更新，应重新取得上游最新地址再推送，避免旧批次覆盖新地址。调用方不应并发推送同一SPU。

furniture-3d-system/docs/integrations/finance-store-account-password-reveal.md

@@ -0,0 +1,153 @@
+# 财务系统店铺密码直接显示契约
+
+状态：生产接口已上线；2026-09-09 按当前明文存储规则修正 `passwordConfigured`。
+
+## 存储事实与授权边界
+
+- 密码真相源是 `public."StoreAccount"."passwordCiphertext"`。字段名是历史遗留；当前规则将新值以明文保存，读取链路对历史 `v1:` AES-256-GCM 值保留兼容。
+- 存量 `v1:` 值已由 `scripts/migrate-store-account-plaintext-20260908.js` 迁移。`STORE_ACCOUNT_ENCRYPTION_KEY` 仅用于可能残留或恢复出的历史 `v1:` 值，不参与当前明文值读取。
+- `passwordConfigured` 只表示存储值是否非空，不校验字符集或密码强度；因此包含 `+`、`/`、`=` 等字符的密码也会正确返回 true。它不返回密码本身。
+- 普通 `store_account_reader` 可读视图、不能读取基表或密码列。此次迁移不增加其基表权限。
+- 本接口只信任专用服务身份 `finance-store-accounts`。财务系统必须在自身后端校验用户登录态、查看/复制权限及店铺范围，然后从可信会话中取 `requesterId`。不得把客户端传入的任意人员 ID 当成操作者。服务凭据仅保存在财务后端，禁止交给浏览器。
+- 不提供密码列表或批量导出。财务页面可在已通过自身页面权限校验后，自动读取当前可见页最多 50 个账号；CSV 和共享镜像仍只读取 `passwordConfigured`。复制操作继续走单账号接口。上游审计记录的用户 ID 是专用财务服务的身份断言，未授权请求中的 ID 不可信，`serviceId=null`。
+
+## HTTP 契约
+
+生产配置完成后的地址：
+
+`POST https://cp.jiansun.vip/internal/store-accounts/{id}/password/reveal`
+
+`POST https://cp.jiansun.vip/internal/store-accounts/visible-page/password/reveal`
+
+`id` 为 `accounts_v1.id`，仅接受单个 1–128 位字母、数字、下划线或连字符。无查询参数；禁止在 URL、请求体、请求头中传待读取密码。
+
+请求头：
+
+```http
+Authorization: Bearer <专用服务令牌>
+Content-Type: application/json
+```
+
+请求体（严格拒绝额外字段，最大 1024 字节，1 秒内读取完毕）：
+
+```json
+{ "requesterId": "finance-user-123", "purpose": "view" }
+```
+
+`purpose` 仅允许 `view` 或 `copy`。`requesterId` 是财务会话中的稳定人员标识，1–128 位 `[A-Za-z0-9_.:@-]`。不接受批量 ID、查询参数、普通登录 Cookie/JWT、普通数据库凭据或其他内部任务密钥。
+
+当前页批量请求严格只接受以下字段，正文最大 8192 字节；`accountIds` 为 1 至 50 个互不重复且符合单账号 ID 规则的值：
+
+```json
+{ "requesterId": "finance-user-123", "purpose": "view", "accountIds": ["account-1", "account-2"] }
+```
+
+成功 `200`：
+
+```json
+{ "requestId": "<服务端生成的 UUID>", "password": "<仅本次响应体中的密码>" }
+```
+
+当前页批量成功的 HTTP 状态为 `200`，每个账号分别返回 `200/404/429/503`。每项都有独立 UUID；只有状态 `200` 的项包含密码，并按请求顺序完整返回：
+
+```json
+{
+  "requestId": "<批次 UUID>",
+  "items": [
+    { "accountId": "account-1", "requestId": "<项目 UUID>", "status": 200, "password": "<密码>" },
+    { "accountId": "account-2", "requestId": "<项目 UUID>", "status": 404 }
+  ]
+}
+```
+
+所有状态均返回 `Cache-Control: no-store`、`Pragma: no-cache`、`X-Content-Type-Options: nosniff`。`X-Request-Id` 与响应体、审计的追踪 ID 相同。不会在响应头中放密码。
+
+错误体：
+
+```json
+{ "requestId": "<UUID>", "error": { "code": "FORBIDDEN", "message": "请求被拒绝" } }
+```
+
+| HTTP | code | 含义 |
+|---|---|---|
+| 403 | FORBIDDEN | 服务认证失败、非 HTTPS、非法 ID/JSON/用途、额外参数或非 POST |
+| 404 | PASSWORD_NOT_FOUND | 账号不存在或没有可用密码，两者不区分 |
+| 429 | RATE_LIMITED | 任一限流窗口超限 |
+| 503 | UNAVAILABLE | 密钥/解密、数据库、限流或审计不可用；不返回内部异常 |
+
+审计或数据库故障优先返回 503，绝不在无法持久化成功审计时返回密码。数据库完全不可用时无法保存该次失败审计，由网关仅记录追踪 ID、状态与时间供运维关联。成功审计表示服务器已授权并生成响应，不等同于浏览器已经复制成功。
+
+## 限流和超时
+
+- 单账号数据库滚动窗口：服务全部账号 30 次/分钟、300 次/24 小时；同一人员 10 次/分钟；同一账号 5 次/分钟。公网 TLS 网关保留 1 KiB 敏感请求正文上限，财务端把 50 行当前页拆成两个最多 25 个账号的批次；批次标记因此按服务 20 次/分钟、1000 次/24 小时、同一人员 10 次/分钟限流，等价于原每页额度。批次中的每个账号仍受同一账号 5 次/分钟限制。查看和复制共享账号额度，轮换令牌不重置服务身份或额度。
+- 已认证的成功、404、参数拒绝和解密失败均占额度；429 不延长窗口。额度检查与审计在同一数据库事务中用事务级锁串行化，跨进程/重启共享状态。
+- 429 不携带剩余数量或精确窗口，避免推测其他用户行为。客户端不得自动重试密码读取；提示用户稍后再试，持续超限联系管理员。
+- 财务客户端设置总超时 10 秒、禁用自动重定向和重试。后端池上限 4、连接获取 1 秒、SQL 执行 1.5 秒/客户端查询 2 秒、锁等待 1 秒，路由运行预算 10 秒。网关必须配置请求体 1 秒和总请求截止，防止慢请求占用。
+- 入口网关还需按来源 IP 对全部请求（包括未授权请求）限制为 60 次/分钟，返回 429 JSON 和 `no-store`；这项入口防滥用配置属于上线门禁。应用层数据库限流负责已认证的敏感读取。
+
+## 环境变量（仅名称及要求）
+
+| 名称 | 所在系统与要求 |
+|---|---|
+| STORE_ACCOUNT_ENCRYPTION_KEY | 仅用于兼容历史 `v1:` 密文，至少 32 字符；生产不回退到 JWT_SECRET |
+| STORE_ACCOUNT_FINANCE_TOKEN | 上游专用服务令牌，密码学随机至少 32 字节，base64url 编码，43–128 字符；缺失时拒绝全部调用 |
+| STORE_ACCOUNT_FINANCE_TOKEN_PREVIOUS | 上游可选旧令牌，仅用于短时轮换；主令牌缺失时旧令牌也不生效 |
+| STORE_ACCOUNT_REVEAL_EDGE_TOKEN | 上游与可信 TLS 网关之间的独立随机凭据，base64url 43–128 字符；与财务令牌完全分离，不提供给财务系统；缺失时拒绝全部调用 |
+| DATABASE_URL | 上游现有数据库连接；仅专用不输出查询/异常的连接池读取密文、写审计 |
+| STORE_ACCOUNT_REVEAL_URL | 财务后端配置完整 HTTPS 地址模板 |
+| STORE_ACCOUNT_REVEAL_VISIBLE_PAGE_URL | 财务后端配置当前页批量 HTTPS 地址；必须使用精确 `visible-page` 路径 |
+| STORE_ACCOUNT_REVEAL_TOKEN | 财务后端保存与上游专用令牌对应的值 |
+| STORE_REVEAL_TEST_ADMIN_URL | 仅本地集成测试；必须指向回环地址、有建测试库/角色权限的 PostgreSQL |
+| STORE_REVEAL_TEST_POSTGRES_CONTAINER | 仅本地日志验收，指定本地 PostgreSQL 容器以只读扫描测试期间日志 |
+
+## HTTPS、日志和缓存上线门禁
+
+1. 财务后端至公开入口及跨主机的所有代理链路必须使用验证证书的 HTTPS，禁止 HTTP 跳转、跳过证书验证、明文 FRP/跨主机上游。当前 PR 不修改生产 TLS 拓扑；上线前逐跳核实，不满足即不启用令牌。
+2. 应用不以 URL 或未经认证的转发头证明 TLS。必须由受控网关在实际 HTTPS 入口覆盖 `X-Forwarded-Proto: https` 及 `X-Store-Reveal-Edge-Token`（值来自独立 `STORE_ACCOUNT_REVEAL_EDGE_TOKEN`），剥除客户端原有同名头；HTTP 入口直接拒绝，不能注入上述凭据。应用对网关凭据做定时安全比较，缺失/错误或协议不是 https 时拒绝。凭据仅上游和网关持有，不提供给财务系统；配置文件 0600，不通过 `nginx -T` 等诊断输出展示。仍需封闭应用直连并逐跳验证 TLS，独立凭据不代替网络加密。
+3. 对精确路径 `/internal/store-accounts/*/password/reveal` 禁止网关缓存、响应落盘缓冲、CDN缓存、请求/响应体及 Authorization 采集；包括 APM、WAF、异常上报、链路追踪和调试抓包。网关日志只允许时间、方法、路径（不带参数）、状态、耗时、追踪 ID。不要采集响应对象。
+4. 网关自己的 403/404/429/503 也使用脱敏 JSON、`Cache-Control: no-store` 和追踪 ID；不得返回上游诊断页。禁止将该路由接入通用 `withApi`/request logger；目前路由直接返回白名单响应，不记录异常对象。
+5. 数据库查询结果包含当前明文密码；严禁记录 SQL 结果、绑定参数或异常对象，不要启用该连接池的参数/结果追踪。密码写入及历史格式迁移期间同样关闭 PostgreSQL/pgAudit 的绑定参数和错误参数记录。
+6. 财务后端同样禁用正文采集、缓存及异常对象打印。浏览器在进入已授权页面后只读取当前可见页，避免 localStorage/sessionStorage/Service Worker 持久化；页面隐藏或离开时清除页面密码，不把密码放入通知、埋点或消息队列。
+
+## 视图与审计迁移
+
+初始迁移：`prisma/migrations/20260908120000_store_account_password_reveal/migration.sql`。明文状态修复：`prisma/migrations/20260909100000_fix_store_account_password_configured_plaintext/migration.sql`。
+
+- 新增 `StoreAccountPasswordAccessAudit`，固定字段为请求追踪 ID、人员标识、服务身份、账号 ID、用途、HTTP状态、数据库时间；不关联用户/店铺外键，以保留未授权、不存在和删除账号的失败审计。状态 200 表示成功，其他状态表示失败。
+- 只在原视图存在时，以原视图查询作为子查询，在末尾追加 `passwordConfigured boolean`，保留原字段、筛选、每行内容、ID、所有者与 ACL；`EXISTS` 不会产生重复行。未配置外部视图的环境不擅自创建外部读入口。
+- `passwordConfigured` 的当前定义为 `passwordCiphertext <> ''`。修复迁移仅替换这个布尔表达式，并在事务内核对原字段逐行内容、视图所有者和 ACL 未变；不读取或输出密码。
+- 明文迁移已由独立脚本完成。本状态修复不改任何密码或银行账号数据，也不增加普通只读账号权限。审计数据至少保留 365 天。
+
+迁移前由 DBA 只读确认目标库、视图定义/所有者/ACL、字段顺序、行数与唯一性、密码聚合、普通读取账号和其成员角色权限。若生产仍以本次基线验收，COUNT 与 DISTINCT id 必须均为 958；若业务新增/删除则暂停并重新确认基线，不改数据凑数。
+
+备份与执行顺序（生产必须在明确批准后执行）：
+
+1. 备份当前 `main`/部署 SHA、现有视图 DDL/ACL/所有者及 `_prisma_migrations` 状态。生成目标库 `pg_dump -Fc` 备份并验证可读取；备份进入生产主机权限 0700 目录，文件 0600，不进入 Git 或共享日志。备份可能含密文，按敏感材料管理。
+2. 本次不修改任何密码、银行卡号或服务令牌；备份不得进入 Git 或普通日志。
+3. 执行明文状态修复迁移，视图短时获得 DDL 锁（最多等 5 秒，执行预算 30 秒）；不回放未审查的其他迁移。
+4. 在同一只读快照比较迁移前后原字段行集、顺序/类型、行数/唯一性和权限；运行 `scripts/sql/check-store-account-password-reveal.sql`，确认最后字段 boolean，报告 true/false/null 聚合。预计当前数据为 957/1/0，但必须执行后实测。
+5. 按项目主线发布流程部署，完成逐跳 TLS、网关日志/限流/缓存检查后再配令牌。生产虚构账号的创建、调用与删除属于额外生产写入，需单独批准；不要调用真实账号作为测试。
+
+回滚：先移除财务令牌阻止新调用并回退应用 SHA。新增状态列与审计表可安全保留以避免丢失审计；旧应用不依赖它们。需要完整结构回退时，经 DBA 检查依赖后，在事务中以备份 DDL 重建旧视图并恢复原所有者/ACL（PostgreSQL 不允许 `CREATE OR REPLACE VIEW` 删除尾列，禁止随意 `DROP ... CASCADE`）。审计记录保留，不直接删表；按项目规则处理已应用迁移历史，禁止直接删除 `_prisma_migrations` 记录或用 `db push`。任何完整结构回退先在隔离库演练。
+
+## 密钥轮换
+
+服务令牌：在受限凭据系统生成新随机令牌；旧值暂放 `STORE_ACCOUNT_FINANCE_TOKEN_PREVIOUS`，新值放主变量，重启上游；更新财务后端，使用虚构账号验收；移除旧值并重启。两值对应同一服务身份，审计/额度不变。怀疑泄露时立即撤销旧值，宁可短暂拒绝请求。
+
+网关凭据：暂停此接口，在网关及上游同时更新 `STORE_ACCOUNT_REVEAL_EDGE_TOKEN` 后验收并恢复；不支持旧值并行。不得将网关凭据与服务令牌设成相同值。
+
+历史兼容密钥：当前明文规则不需要为新值轮换数据密钥。若确认数据库中不存在 `v1:` 值并且备份保留策略允许，可另行评估退役历史解密密钥；退役前必须检查备份恢复场景，不能直接删除。
+
+## 本次验证记录
+
+- 当前页批量扩展的服务、HTTP 路由和代理边界共 3 个测试套件、41 项测试通过；`npm run type-check` 通过。测试覆盖 1–50 个账号、重复账号拒绝、部分 404/429/503、批次与每账号审计，以及失败时不返回明文。
+- 单元/HTTP/代理路由测试：34 项通过，含伪造 HTTPS URL/转发头和错误网关凭据拒绝。
+- 追加现有代理路由的 7 项回归，与 10 项集成测试合计 6 套件、51 项全部通过。
+- 隔离本地 PostgreSQL 集成测试：10 项通过，覆盖完整加解密与 HTTP handler、已提交审计、403/404/429/no-store、并发/跨实例限流、分钟/24小时配额、审计失败拒绝泄露、原字段及筛选保留、958/958 与 boolean 957/1/0、普通只读角色拒绝基表/密码/审计读取。
+- 开启本地测试连接的 PostgreSQL statement 日志，只在内存扫描 `docker logs`；应用日志、审计行、SQL请求与真实数据库日志均未检出随机测试密码。测试无需打印测试密码，断言只输出布尔结果。
+- Type-check 通过；范围内 ESLint 通过。全仓库主数据边界巡检有 6 项已有违规，均位于本次未修改模块；不得据此声称全仓库通过。
+- 2026-09-09 生产只读复核确认：958 行、958 个唯一 ID、957 条非空密码、1 条空密码；旧正则导致状态误报为全 false。本迁移用于恢复预期聚合 true/false/null = 957/1/0。
+
+运行：`npx jest --runInBand --runTestsByPath src/server/services/store-account-password-reveal.service.test.ts src/proxy-store-account-reveal.test.ts "src/app/internal/store-accounts/[id]/password/reveal/route.test.ts" tests/integration/store-account-password-reveal.test.ts`。未配置本地测试库变量时，集成套件明确 skip，不能算真实数据库验收通过。
+
+收口：**passed with warnings**。这是自审，不是独立复审。Route → Service → Repository 边界保持；未修改 UI；状态字段与当前明文存储规则对齐，专用认证、审计和限流边界不变。

furniture-3d-system/docs/mockups/intake-archive-workspace-layout.html

@@ -0,0 +1,689 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>安装方式 / 工厂质检归档布局草图</title>
+    <style>
+      :root {
+        --page: #eef2f5;
+        --panel: #f7f9fb;
+        --surface: #ffffff;
+        --soft: #edf2f5;
+        --line: #dce5ea;
+        --text: #14212a;
+        --muted: #687885;
+        --faint: #9aa8b3;
+        --ink: #263b45;
+        --ink-2: #4d6672;
+        --accent: #365a66;
+        --active: #23313a;
+        --green: #2d7c57;
+        --orange: #d99142;
+        --shadow: 0 24px 70px rgba(24, 37, 46, 0.12);
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background:
+          radial-gradient(circle at 18% 12%, rgba(54, 90, 102, 0.12), transparent 25%),
+          linear-gradient(180deg, #fbfcfd 0%, var(--page) 100%);
+        color: var(--text);
+        font-family:
+          "Microsoft YaHei",
+          "PingFang SC",
+          "Noto Sans CJK SC",
+          sans-serif;
+      }
+
+      .topbar {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        height: 72px;
+        padding: 0 28px;
+        background: rgba(255, 255, 255, 0.82);
+        border-bottom: 1px solid var(--line);
+        backdrop-filter: blur(18px);
+      }
+
+      .brand {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        font-weight: 800;
+      }
+
+      .brand-mark {
+        display: grid;
+        width: 34px;
+        height: 34px;
+        place-items: center;
+        border-radius: 12px;
+        background: var(--text);
+        color: #fff;
+        font-size: 18px;
+      }
+
+      .top-actions {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+      }
+
+      .search {
+        width: 260px;
+        border-radius: 16px;
+        background: var(--soft);
+        color: var(--faint);
+        padding: 12px 16px;
+        font-size: 14px;
+      }
+
+      .avatar {
+        display: grid;
+        width: 40px;
+        height: 40px;
+        place-items: center;
+        border-radius: 999px;
+        background: #fff;
+        border: 1px solid var(--line);
+        color: var(--muted);
+        font-weight: 700;
+      }
+
+      .shell {
+        display: grid;
+        grid-template-columns: 196px minmax(0, 1fr) 236px;
+        gap: 18px;
+        min-height: calc(100vh - 72px);
+        padding: 20px 18px 24px;
+      }
+
+      .left-nav,
+      .right-nav {
+        border-radius: 26px;
+        background: rgba(255, 255, 255, 0.72);
+        border: 1px solid rgba(220, 229, 234, 0.86);
+        box-shadow: 0 18px 48px rgba(31, 47, 56, 0.08);
+      }
+
+      .left-nav {
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+        padding: 22px 14px;
+      }
+
+      .nav-item {
+        border-radius: 15px;
+        color: #40515b;
+        padding: 13px 14px;
+        font-size: 14px;
+      }
+
+      .nav-item.active {
+        background: #fff;
+        color: var(--active);
+        font-weight: 800;
+        box-shadow: 0 14px 32px rgba(24, 37, 46, 0.08);
+      }
+
+      .workspace {
+        min-width: 0;
+        border-radius: 30px;
+        padding: 14px;
+        background: rgba(235, 240, 244, 0.78);
+        border: 1px solid rgba(214, 224, 230, 0.92);
+      }
+
+      .workspace-card {
+        overflow: hidden;
+        min-height: calc(100vh - 132px);
+        border-radius: 26px;
+        background: var(--surface);
+        box-shadow: var(--shadow);
+      }
+
+      .workspace-head {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 20px;
+        min-height: 94px;
+        padding: 22px 26px;
+        border-bottom: 1px solid var(--line);
+      }
+
+      .workspace-head h1 {
+        margin: 0 0 8px;
+        font-size: 22px;
+        letter-spacing: -0.02em;
+      }
+
+      .workspace-head p {
+        margin: 0;
+        color: var(--muted);
+        font-size: 14px;
+      }
+
+      .toolbar {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+      }
+
+      .button {
+        border-radius: 15px;
+        padding: 13px 18px;
+        background: var(--accent);
+        color: #fff;
+        font-weight: 800;
+        font-size: 14px;
+        box-shadow: 0 16px 34px rgba(54, 90, 102, 0.2);
+      }
+
+      .button.ghost {
+        background: transparent;
+        color: var(--faint);
+        box-shadow: none;
+      }
+
+      .archive-layout {
+        display: grid;
+        grid-template-columns: 224px minmax(430px, 1fr) 382px;
+        min-height: calc(100vh - 226px);
+      }
+
+      .style-panel {
+        border-right: 1px solid var(--line);
+        padding: 22px 18px;
+        background: #fbfcfd;
+      }
+
+      .eyebrow {
+        margin: 0 0 12px;
+        color: var(--faint);
+        font-size: 11px;
+        font-weight: 800;
+        letter-spacing: 0.2em;
+        text-transform: uppercase;
+      }
+
+      .style-card {
+        margin-bottom: 12px;
+        border-radius: 18px;
+        padding: 15px;
+        background: #fff;
+        border: 1px solid var(--line);
+      }
+
+      .style-card.active {
+        border-color: var(--active);
+        background: #eef3f5;
+      }
+
+      .style-title {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 8px;
+        margin-bottom: 8px;
+        font-size: 16px;
+        font-weight: 800;
+      }
+
+      .pill {
+        border-radius: 999px;
+        background: var(--ink-2);
+        color: #fff;
+        padding: 4px 10px;
+        font-size: 12px;
+      }
+
+      .style-card p {
+        margin: 0;
+        color: var(--muted);
+        font-size: 13px;
+        line-height: 1.6;
+      }
+
+      .memo {
+        margin-top: 18px;
+        border-radius: 20px;
+        padding: 16px;
+        background: var(--panel);
+        color: var(--muted);
+        font-size: 13px;
+        line-height: 1.65;
+      }
+
+      .media-panel {
+        display: flex;
+        min-width: 0;
+        flex-direction: column;
+        background: #eef3f6;
+      }
+
+      .media-head {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 14px;
+        padding: 18px 20px;
+        border-bottom: 1px solid var(--line);
+      }
+
+      .media-search {
+        flex: 1;
+        border-radius: 16px;
+        background: #fff;
+        color: var(--faint);
+        padding: 13px 16px;
+        font-size: 14px;
+      }
+
+      .type-tabs {
+        display: flex;
+        gap: 8px;
+      }
+
+      .type-tab {
+        border-radius: 999px;
+        padding: 10px 14px;
+        background: #fff;
+        color: var(--muted);
+        font-size: 13px;
+        font-weight: 800;
+        border: 1px solid var(--line);
+      }
+
+      .type-tab.active {
+        background: var(--active);
+        color: #fff;
+        border-color: var(--active);
+      }
+
+      .media-scroll {
+        min-height: 0;
+        overflow-y: auto;
+        padding: 20px;
+      }
+
+      .media-grid {
+        display: grid;
+        grid-template-columns: repeat(3, minmax(140px, 1fr));
+        gap: 14px;
+      }
+
+      .media-card {
+        overflow: hidden;
+        min-height: 176px;
+        border-radius: 22px;
+        background: #fff;
+        border: 1px solid rgba(220, 229, 234, 0.9);
+        box-shadow: 0 14px 34px rgba(31, 47, 56, 0.08);
+      }
+
+      .media-card.active {
+        border-color: var(--active);
+        box-shadow: 0 20px 46px rgba(31, 47, 56, 0.16);
+      }
+
+      .thumb {
+        height: 112px;
+        background:
+          linear-gradient(135deg, rgba(255, 255, 255, 0.35), transparent 42%),
+          linear-gradient(135deg, #d3dbe0, #bfcbd1);
+      }
+
+      .media-card:nth-child(2) .thumb {
+        background: linear-gradient(135deg, #cfc2b4, #856d57);
+      }
+
+      .media-card:nth-child(3) .thumb {
+        background: linear-gradient(135deg, #d4e3e5, #78949d);
+      }
+
+      .media-card:nth-child(4) .thumb {
+        background: linear-gradient(135deg, #ded5cd, #aa8466);
+      }
+
+      .media-card:nth-child(5) .thumb {
+        background: linear-gradient(135deg, #dfe2e6, #939fa8);
+      }
+
+      .media-card:nth-child(6) .thumb {
+        background: linear-gradient(135deg, #e7ded6, #b9855b);
+      }
+
+      .media-info {
+        padding: 12px 13px 14px;
+      }
+
+      .media-info strong {
+        display: block;
+        overflow: hidden;
+        margin-bottom: 6px;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        font-size: 14px;
+      }
+
+      .media-info span {
+        color: var(--muted);
+        font-size: 12px;
+      }
+
+      .detail-panel {
+        display: flex;
+        min-width: 0;
+        flex-direction: column;
+        border-left: 1px solid var(--line);
+        background: #fff;
+      }
+
+      .detail-head {
+        padding: 24px 26px 16px;
+      }
+
+      .detail-head .eyebrow {
+        margin-bottom: 10px;
+      }
+
+      .detail-head h2 {
+        margin: 0;
+        font-size: 24px;
+        line-height: 1.25;
+      }
+
+      .preview {
+        margin: 0 26px;
+        overflow: hidden;
+        border-radius: 24px;
+        background:
+          linear-gradient(145deg, rgba(255, 255, 255, 0.24), transparent 42%),
+          linear-gradient(135deg, #cfc2b4, #7b624f);
+        min-height: 330px;
+        box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.45);
+      }
+
+      .detail-meta {
+        margin: 18px 26px 0;
+        border-radius: 22px;
+        background: var(--panel);
+        padding: 18px;
+      }
+
+      .meta-row {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 18px;
+        padding: 9px 0;
+        color: var(--muted);
+        font-size: 13px;
+      }
+
+      .meta-row strong {
+        color: var(--text);
+      }
+
+      .detail-actions {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        gap: 10px;
+        margin: 18px 26px 26px;
+      }
+
+      .small-action {
+        border-radius: 15px;
+        background: #fff;
+        border: 1px solid var(--line);
+        color: var(--ink);
+        padding: 12px;
+        text-align: center;
+        font-size: 13px;
+        font-weight: 800;
+      }
+
+      .right-nav {
+        align-self: start;
+        padding: 16px;
+      }
+
+      .right-title {
+        padding: 12px 12px 16px;
+        border-bottom: 1px solid var(--line);
+      }
+
+      .right-title h3 {
+        margin: 0 0 6px;
+        font-size: 18px;
+      }
+
+      .right-title p {
+        margin: 0;
+        color: var(--muted);
+        font-size: 12px;
+      }
+
+      .doc-list {
+        display: flex;
+        flex-direction: column;
+        gap: 10px;
+        padding-top: 14px;
+      }
+
+      .doc-item {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        border-radius: 15px;
+        padding: 12px 14px;
+        background: #fff;
+        border: 1px solid var(--line);
+        color: #243641;
+        font-weight: 700;
+      }
+
+      .doc-item.active {
+        background: #dfe8ee;
+        border-color: #c8d5dd;
+      }
+
+      .doc-count {
+        border-radius: 999px;
+        background: #fff;
+        color: var(--muted);
+        min-width: 28px;
+        padding: 4px 9px;
+        text-align: center;
+        font-size: 12px;
+      }
+
+      @media (max-width: 1440px) {
+        .shell {
+          grid-template-columns: 170px minmax(0, 1fr) 212px;
+        }
+
+        .archive-layout {
+          grid-template-columns: 206px minmax(360px, 1fr) 340px;
+        }
+
+        .media-grid {
+          grid-template-columns: repeat(2, minmax(150px, 1fr));
+        }
+      }
+
+      @media (max-width: 1100px) {
+        .shell,
+        .archive-layout {
+          grid-template-columns: 1fr;
+        }
+
+        .left-nav,
+        .right-nav {
+          display: none;
+        }
+
+        .style-panel,
+        .detail-panel {
+          border: 0;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <header class="topbar">
+      <div class="brand">
+        <div class="brand-mark">J</div>
+        <span>由壹点「产品开发平台」</span>
+      </div>
+      <div class="top-actions">
+        <div class="search">搜索组件...</div>
+        <div class="avatar">L</div>
+      </div>
+    </header>
+
+    <main class="shell">
+      <aside class="left-nav">
+        <div class="nav-item">首页概览</div>
+        <div class="nav-item">资产中心</div>
+        <div class="nav-item">辅助装配</div>
+        <div class="nav-item">草稿组</div>
+        <div class="nav-item active">正式产品</div>
+        <div class="nav-item">仓库管理</div>
+      </aside>
+
+      <section class="workspace">
+        <div class="workspace-card">
+          <div class="workspace-head">
+            <div>
+              <h1>归档型工作区布局草图</h1>
+              <p>安装方式、工厂质检可以共用这套结构：左边选款式，中间看素材，右边看当前详情。</p>
+            </div>
+            <div class="toolbar">
+              <div class="button">上传到当前栏</div>
+              <div class="button ghost">下载当前</div>
+            </div>
+          </div>
+
+          <div class="archive-layout">
+            <aside class="style-panel">
+              <p class="eyebrow">Style</p>
+              <div class="style-card active">
+                <div class="style-title">款式一 <span class="pill">26</span></div>
+                <p>摔包图片 18 份<br />摔包视频 8 份</p>
+              </div>
+              <div class="style-card">
+                <div class="style-title">款式二 <span class="pill">0</span></div>
+                <p>当前还没有工厂质检资料</p>
+              </div>
+              <div class="style-card">
+                <div class="style-title">款式三 <span class="pill">0</span></div>
+                <p>跟随 SKU 型号自动出现</p>
+              </div>
+              <div class="memo">
+                这里不再堆太多说明，只保留款式和数量。后续图片再多，也只在中间素材墙滚动。
+              </div>
+            </aside>
+
+            <section class="media-panel">
+              <div class="media-head">
+                <div class="media-search">搜索文件名、日期、备注...</div>
+                <div class="type-tabs">
+                  <div class="type-tab active">摔包图片 18</div>
+                  <div class="type-tab">摔包视频 8</div>
+                </div>
+              </div>
+
+              <div class="media-scroll">
+                <div class="media-grid">
+                  <article class="media-card active">
+                    <div class="thumb"></div>
+                    <div class="media-info">
+                      <strong>正面摔包-01.jpg</strong>
+                      <span>今天 14:20 · 已归档</span>
+                    </div>
+                  </article>
+                  <article class="media-card">
+                    <div class="thumb"></div>
+                    <div class="media-info">
+                      <strong>侧面摔包-02.jpg</strong>
+                      <span>今天 14:19 · 已归档</span>
+                    </div>
+                  </article>
+                  <article class="media-card">
+                    <div class="thumb"></div>
+                    <div class="media-info">
+                      <strong>箱角状态-03.jpg</strong>
+                      <span>昨天 18:06 · 已归档</span>
+                    </div>
+                  </article>
+                  <article class="media-card">
+                    <div class="thumb"></div>
+                    <div class="media-info">
+                      <strong>包装封口-04.jpg</strong>
+                      <span>昨天 17:55 · 已归档</span>
+                    </div>
+                  </article>
+                  <article class="media-card">
+                    <div class="thumb"></div>
+                    <div class="media-info">
+                      <strong>复检记录-05.jpg</strong>
+                      <span>04/25 · 已归档</span>
+                    </div>
+                  </article>
+                  <article class="media-card">
+                    <div class="thumb"></div>
+                    <div class="media-info">
+                      <strong>外箱状态-06.jpg</strong>
+                      <span>04/25 · 已归档</span>
+                    </div>
+                  </article>
+                </div>
+              </div>
+            </section>
+
+            <aside class="detail-panel">
+              <div class="detail-head">
+                <p class="eyebrow">Preview</p>
+                <h2>正面摔包-01.jpg</h2>
+              </div>
+              <div class="preview"></div>
+              <div class="detail-meta">
+                <div class="meta-row"><span>所属款式</span><strong>款式一</strong></div>
+                <div class="meta-row"><span>资料类型</span><strong>摔包图片</strong></div>
+                <div class="meta-row"><span>当前数量</span><strong>18 份</strong></div>
+                <div class="meta-row"><span>上传时间</span><strong>今天 14:20</strong></div>
+              </div>
+              <div class="detail-actions">
+                <div class="small-action">放大预览</div>
+                <div class="small-action">删除当前</div>
+              </div>
+            </aside>
+          </div>
+        </div>
+      </section>
+
+      <aside class="right-nav">
+        <div class="right-title">
+          <h3>图片与文档</h3>
+          <p>这里只负责切换工作区，不再挤进主内容里。</p>
+        </div>
+        <div class="doc-list">
+          <div class="doc-item">产品实拍 <span class="doc-count">9</span></div>
+          <div class="doc-item">安装方式 <span class="doc-count">0</span></div>
+          <div class="doc-item active">工厂质检 <span class="doc-count">26</span></div>
+          <div class="doc-item">仓库抽检 <span class="doc-count">0</span></div>
+        </div>
+      </aside>
+    </main>
+  </body>
+</html>

furniture-3d-system/docs/mockups/non-integrated-create-opening-reference-preview.html

@@ -0,0 +1,778 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>开品参考填写预览</title>
+    <style>
+      :root {
+        --page: #f8f9fa;
+        --shell: #eef3f7;
+        --card: #ffffff;
+        --soft: #f7f9fb;
+        --line: #dce3ea;
+        --text: #111c27;
+        --muted: #617182;
+        --faint: #8c98a5;
+        --dark: #405766;
+        --active: #202a33;
+        --blue-soft: #e9f3ff;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        min-width: 1360px;
+        height: 100vh;
+        overflow: hidden;
+        background: var(--page);
+        color: var(--text);
+        font-family:
+          Manrope,
+          Inter,
+          "PingFang SC",
+          "Microsoft YaHei",
+          Arial,
+          sans-serif;
+        font-size: 13px;
+      }
+
+      button,
+      input,
+      textarea {
+        font: inherit;
+      }
+
+      .top-nav {
+        position: fixed;
+        inset: 0 0 auto 0;
+        z-index: 20;
+        height: 64px;
+        display: flex;
+        align-items: center;
+        padding: 0 32px;
+        border-bottom: 1px solid rgba(0, 0, 0, 0.04);
+        background: rgba(255, 255, 255, 0.92);
+        backdrop-filter: blur(24px);
+      }
+
+      .brand {
+        display: flex;
+        min-width: 172px;
+        align-items: center;
+        gap: 10px;
+        color: #2d3335;
+        text-decoration: none;
+      }
+
+      .brand-mark {
+        width: 36px;
+        height: 36px;
+        border-radius: 6px;
+        display: grid;
+        place-items: center;
+        background: #0d1520;
+        color: #fff;
+        font-size: 18px;
+        font-weight: 900;
+      }
+
+      .brand strong {
+        display: block;
+        font-size: 13px;
+        font-weight: 900;
+        line-height: 1;
+      }
+
+      .brand span {
+        display: block;
+        margin-top: 5px;
+        font-size: 10px;
+        font-weight: 700;
+        color: rgba(90, 96, 98, 0.55);
+      }
+
+      .divider {
+        width: 1px;
+        height: 32px;
+        margin: 0 28px;
+        background: rgba(0, 0, 0, 0.05);
+      }
+
+      .nav-links {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+      }
+
+      .nav-link {
+        height: 40px;
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        border-radius: 6px;
+        padding: 0 12px;
+        color: rgba(90, 96, 98, 0.72);
+        font-size: 13px;
+        font-weight: 700;
+        text-decoration: none;
+      }
+
+      .nav-link.active {
+        background: rgba(0, 0, 0, 0.04);
+        color: #2d3335;
+        box-shadow: 0 1px 2px rgba(15, 23, 42, 0.06);
+      }
+
+      .nav-icon {
+        width: 15px;
+        height: 15px;
+        border: 1.7px solid currentColor;
+        border-radius: 4px;
+        opacity: 0.75;
+      }
+
+      .top-tools {
+        margin-left: auto;
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        border-left: 1px solid rgba(0, 0, 0, 0.04);
+        padding-left: 24px;
+      }
+
+      .round,
+      .user {
+        height: 38px;
+        border: 1px solid rgba(15, 23, 42, 0.08);
+        background: #fff;
+        color: #5a6062;
+      }
+
+      .round {
+        width: 38px;
+        border-radius: 50%;
+      }
+
+      .user {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        border-radius: 999px;
+        padding: 0 14px 0 10px;
+      }
+
+      .avatar {
+        width: 28px;
+        height: 28px;
+        border-radius: 50%;
+        display: grid;
+        place-items: center;
+        background: #eef1f4;
+        color: #7b858f;
+        font-weight: 800;
+      }
+
+      .main {
+        height: calc(100vh - 64px);
+        margin-top: 64px;
+        overflow: hidden;
+        padding: 0 0 16px 16px;
+        background: var(--page);
+      }
+
+      .split {
+        height: 100%;
+        display: flex;
+        overflow: hidden;
+        border: 1px solid rgba(255, 255, 255, 0.72);
+        border-radius: 32px;
+        background: var(--shell);
+        box-shadow: 0 18px 44px rgba(27, 45, 58, 0.08);
+      }
+
+      .content {
+        min-width: 0;
+        flex: 1;
+        overflow-y: auto;
+        padding: 12px;
+      }
+
+      .content-inner {
+        min-height: 100%;
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        background: var(--card);
+        padding: 12px;
+      }
+
+      .info-card {
+        border: 1px solid var(--line);
+        border-radius: 12px;
+        background: #fff;
+        padding: 12px;
+      }
+
+      .section-title {
+        margin: 0 0 12px;
+        font-size: 15px;
+        font-weight: 900;
+      }
+
+      .top-summary {
+        display: grid;
+        grid-template-columns: 220px minmax(0, 1fr);
+        gap: 16px;
+      }
+
+      .image-box {
+        height: 174px;
+        border: 1px solid var(--line);
+        border-radius: 12px;
+        background:
+          linear-gradient(180deg, rgba(255, 255, 255, 0.45), rgba(222, 229, 235, 0.18)),
+          #f3f6f9;
+        display: grid;
+        place-items: center;
+        overflow: hidden;
+      }
+
+      .desk {
+        position: relative;
+        width: 154px;
+        height: 86px;
+      }
+
+      .desk::before {
+        content: "";
+        position: absolute;
+        left: 5px;
+        right: 5px;
+        top: 14px;
+        height: 28px;
+        border-radius: 6px;
+        transform: perspective(120px) rotateX(6deg);
+        background: #6a452e;
+        box-shadow: inset 0 -9px 0 rgba(0, 0, 0, 0.2);
+      }
+
+      .leg {
+        position: absolute;
+        top: 40px;
+        width: 8px;
+        height: 50px;
+        background: #3b281e;
+      }
+
+      .leg.one {
+        left: 24px;
+      }
+
+      .leg.two {
+        left: 62px;
+      }
+
+      .leg.three {
+        right: 62px;
+      }
+
+      .leg.four {
+        right: 24px;
+      }
+
+      .field-grid {
+        display: grid;
+        grid-template-columns: repeat(5, minmax(0, 1fr));
+        gap: 22px 36px;
+        align-content: start;
+      }
+
+      .field span,
+      .line-field span {
+        display: block;
+        margin-bottom: 6px;
+        color: var(--muted);
+        font-size: 12px;
+      }
+
+      .field input,
+      .field textarea,
+      .line-field input,
+      .line-field textarea {
+        width: 100%;
+        border: 0;
+        background: transparent;
+        color: #071522;
+        outline: none;
+        padding: 0;
+        font-weight: 700;
+      }
+
+      .field input::placeholder,
+      .field textarea::placeholder {
+        color: #a2acb7;
+        font-weight: 500;
+      }
+
+      .soft-input {
+        min-height: 30px;
+        display: flex;
+        align-items: center;
+        border: 1px solid var(--line);
+        border-radius: 10px;
+        background: #f8fafc;
+        padding: 0 10px;
+      }
+
+      .soft-input input {
+        height: 28px;
+      }
+
+      .select-pill {
+        height: 32px;
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        border: 1px solid var(--line);
+        border-radius: 12px;
+        background: #f3f6f9;
+        padding: 0 10px;
+        font-weight: 800;
+      }
+
+      .badge {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-width: 24px;
+        height: 18px;
+        border-radius: 999px;
+        background: #425966;
+        color: #fff;
+        font-size: 11px;
+        font-weight: 900;
+      }
+
+      .divider-line {
+        margin: 16px 0 12px;
+        height: 1px;
+        background: var(--line);
+      }
+
+      .line-grid {
+        display: grid;
+        grid-template-columns: repeat(6, minmax(0, 1fr));
+        gap: 18px 34px;
+      }
+
+      .line-field.wide-2 {
+        grid-column: span 2;
+      }
+
+      .line-field.wide-3 {
+        grid-column: span 3;
+      }
+
+      .textarea-box {
+        min-height: 54px;
+        border: 1px solid var(--line);
+        border-radius: 10px;
+        background: #f8fafc;
+        padding: 9px 10px;
+      }
+
+      .textarea-box textarea {
+        min-height: 36px;
+        resize: vertical;
+        line-height: 1.5;
+      }
+
+      .sub-card {
+        margin-top: 14px;
+        border: 1px solid var(--line);
+        border-radius: 12px;
+        background: #fff;
+        overflow: hidden;
+      }
+
+      .sub-head {
+        padding: 12px;
+        border-bottom: 1px solid var(--line);
+      }
+
+      .sub-head h2 {
+        margin: 0;
+        font-size: 15px;
+        font-weight: 900;
+      }
+
+      .sub-head p {
+        margin: 5px 0 0;
+        color: var(--muted);
+        font-size: 12px;
+      }
+
+      .reference-table {
+        width: 100%;
+        border-collapse: collapse;
+        font-size: 12px;
+      }
+
+      .reference-table th,
+      .reference-table td {
+        border-bottom: 1px solid var(--line);
+        padding: 10px 12px;
+        text-align: left;
+        vertical-align: top;
+      }
+
+      .reference-table th {
+        color: var(--muted);
+        font-weight: 800;
+        background: #f8fafc;
+      }
+
+      .mini-actions {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+        white-space: nowrap;
+      }
+
+      .mini-btn {
+        height: 26px;
+        border: 1px solid var(--line);
+        border-radius: 7px;
+        background: #f7f9fb;
+        color: #334b5f;
+        padding: 0 9px;
+        font-size: 11px;
+        font-weight: 800;
+      }
+
+      .mini-btn.primary {
+        border-color: var(--dark);
+        background: var(--dark);
+        color: #fff;
+      }
+
+      .mini-btn.danger {
+        color: #c73646;
+      }
+
+      .bottom-actions {
+        display: flex;
+        justify-content: flex-end;
+        gap: 10px;
+        padding: 12px;
+      }
+
+      .btn {
+        height: 38px;
+        border: 1px solid var(--line);
+        border-radius: 10px;
+        background: #f7f9fb;
+        color: var(--text);
+        padding: 0 18px;
+        font-weight: 800;
+      }
+
+      .btn.primary {
+        border-color: var(--dark);
+        background: var(--dark);
+        color: #fff;
+      }
+
+      .right-panel {
+        width: 224px;
+        min-width: 224px;
+        max-width: 224px;
+        overflow-y: auto;
+        border-left: 1px solid var(--line);
+        background: #fff;
+        padding: 12px;
+      }
+
+      .side-card {
+        min-height: 100%;
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        background: #fff;
+        overflow: hidden;
+      }
+
+      .side-head {
+        padding: 14px 12px;
+        border-bottom: 1px solid var(--line);
+      }
+
+      .side-head h2 {
+        margin: 0;
+        font-size: 16px;
+        font-weight: 900;
+      }
+
+      .side-head p {
+        margin: 7px 0 0;
+        color: var(--muted);
+        font-size: 11px;
+      }
+
+      .node-list {
+        display: grid;
+        gap: 8px;
+        padding: 10px;
+      }
+
+      .node {
+        height: 38px;
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        border: 1px solid var(--line);
+        border-radius: 10px;
+        background: #fff;
+        color: #334b5f;
+        padding: 0 10px;
+      }
+
+      .node.active {
+        background: #e6eef5;
+        color: #27495f;
+      }
+
+      .node.dark {
+        border-color: var(--active);
+        background: var(--active);
+        color: #fff;
+      }
+
+      .count {
+        min-width: 24px;
+        height: 24px;
+        display: grid;
+        place-items: center;
+        border-radius: 999px;
+        background: #f6f8fa;
+        color: var(--muted);
+        font-weight: 900;
+        font-size: 12px;
+      }
+
+      .dark .count {
+        background: #40515f;
+        color: #fff;
+      }
+    </style>
+  </head>
+  <body>
+    <header class="top-nav">
+      <a class="brand" href="#">
+        <div class="brand-mark">J</div>
+        <div>
+          <strong>壹点产品开发平台</strong>
+          <span>正式产品</span>
+        </div>
+      </a>
+      <div class="divider"></div>
+      <nav class="nav-links">
+        <a class="nav-link" href="#"><i class="nav-icon"></i>首页概览</a>
+        <a class="nav-link" href="#"><i class="nav-icon"></i>资产中心</a>
+        <a class="nav-link" href="#"><i class="nav-icon"></i>辅助装配</a>
+        <a class="nav-link" href="#"><i class="nav-icon"></i>草稿组</a>
+        <a class="nav-link active" href="#"><i class="nav-icon"></i>正式产品</a>
+        <a class="nav-link" href="#"><i class="nav-icon"></i>仓库管理</a>
+      </nav>
+      <div class="top-tools">
+        <button class="round" aria-label="通知"></button>
+        <button class="round" aria-label="切换主题"></button>
+        <button class="user"><span class="avatar">L</span>LocalAdmin⌄</button>
+      </div>
+    </header>
+
+    <main class="main">
+      <section class="split">
+        <div class="content">
+          <div class="content-inner">
+            <section class="info-card">
+              <h1 class="section-title">开品参考填写</h1>
+              <div class="top-summary">
+                <div class="image-box">
+                  <div class="desk">
+                    <span class="leg one"></span>
+                    <span class="leg two"></span>
+                    <span class="leg three"></span>
+                    <span class="leg four"></span>
+                  </div>
+                </div>
+                <div class="field-grid">
+                  <div class="field">
+                    <span>开品名称</span>
+                    <div class="soft-input"><input value="胡桃木色窄边书桌" /></div>
+                  </div>
+                  <div class="field">
+                    <span>临时编号</span>
+                    <div class="soft-input"><input value="KP20260428-001" /></div>
+                  </div>
+                  <div class="field">
+                    <span>品牌</span>
+                    <input value="基本盘" />
+                  </div>
+                  <div class="field">
+                    <span>适配品牌</span>
+                    <div class="select-pill">基本盘 <i class="badge">+3</i> ▼</div>
+                  </div>
+                  <div class="field">
+                    <span>当前阶段</span>
+                    <input value="立项前" />
+                  </div>
+
+                  <div class="field">
+                    <span>商品类目</span>
+                    <input value="书桌" />
+                  </div>
+                  <div class="field">
+                    <span>销售类目</span>
+                    <input value="书桌" />
+                  </div>
+                  <div class="field">
+                    <span>设计师</span>
+                    <input value="徐霞客" />
+                  </div>
+                  <div class="field">
+                    <span>企划负责人</span>
+                    <input value="徐霞客" />
+                  </div>
+                  <div class="field">
+                    <span>年份</span>
+                    <input value="2026" />
+                  </div>
+                </div>
+              </div>
+
+              <div class="divider-line"></div>
+
+              <div class="line-grid">
+                <div class="line-field wide-2">
+                  <span>竞品链接 / 参考链接</span>
+                  <div class="soft-input"><input value="https://example.com/reference-desk" /></div>
+                </div>
+                <div class="line-field">
+                  <span>目标价格带</span>
+                  <input value="待评审确认" />
+                </div>
+                <div class="line-field">
+                  <span>尺寸</span>
+                  <input value="140/60/78" />
+                </div>
+                <div class="line-field">
+                  <span>材质</span>
+                  <input value="胡桃木色 / 橡胶木方向" />
+                </div>
+                <div class="line-field">
+                  <span>是否急开</span>
+                  <input value="否" />
+                </div>
+
+                <div class="line-field wide-3">
+                  <span>开品理由</span>
+                  <div class="textarea-box">
+                    <textarea>看中竞品窄边桌面比例和轻量化视觉，适合基础盘补一个中低价位书桌款。</textarea>
+                  </div>
+                </div>
+              </div>
+            </section>
+
+            <section class="sub-card">
+              <div class="sub-head">
+                <div style="display: flex; align-items: center; justify-content: space-between; gap: 12px">
+                  <div>
+                    <h2>参考资料</h2>
+                    <p>这里上传前期参考文档、截图整理和竞品资料，不放 SKU，也不放完整基础信息。</p>
+                  </div>
+                  <button class="mini-btn primary">上传文档</button>
+                </div>
+              </div>
+              <table class="reference-table">
+                <thead>
+                  <tr>
+                    <th style="width: 80px">序号</th>
+                    <th style="width: 220px">文档名称</th>
+                    <th style="width: 150px">类型</th>
+                    <th>备注</th>
+                    <th style="width: 150px">操作</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td>1</td>
+                    <td>竞品截图整理.pdf</td>
+                    <td>参考文档</td>
+                    <td>主图、侧面图、结构截图，供产品资料和立项评审参考。</td>
+                    <td>
+                      <div class="mini-actions">
+                        <button class="mini-btn">下载</button>
+                        <button class="mini-btn danger">删除</button>
+                      </div>
+                    </td>
+                  </tr>
+                  <tr>
+                    <td>2</td>
+                    <td>目标价格带.xlsx</td>
+                    <td>价格资料</td>
+                    <td>竞品价格、尺寸、卖点和链接初步整理。</td>
+                    <td>
+                      <div class="mini-actions">
+                        <button class="mini-btn">下载</button>
+                        <button class="mini-btn danger">删除</button>
+                      </div>
+                    </td>
+                  </tr>
+                  <tr>
+                    <td>3</td>
+                    <td>参考外观图.zip</td>
+                    <td>图片资料</td>
+                    <td>外观图片、局部结构图、材质参考图。</td>
+                    <td>
+                      <div class="mini-actions">
+                        <button class="mini-btn">下载</button>
+                        <button class="mini-btn danger">删除</button>
+                      </div>
+                    </td>
+                  </tr>
+                </tbody>
+              </table>
+              <div class="bottom-actions">
+                <button class="btn">保存草稿</button>
+                <button class="btn primary">保存开品参考</button>
+              </div>
+            </section>
+          </div>
+        </div>
+
+        <aside class="right-panel">
+          <div class="side-card">
+            <div class="side-head">
+              <h2>图片与文档</h2>
+              <p>右侧按分类切换工作区</p>
+            </div>
+            <div class="node-list">
+              <button class="node active"><span>开品参考</span><i class="count">0</i></button>
+              <button class="node"><span>产品资料</span><i class="count">1</i></button>
+              <button class="node"><span>设计卖点</span><i class="count">1</i></button>
+              <button class="node"><span>立项评审</span><i class="count">0</i></button>
+              <button class="node dark"><span>基础信息</span><i class="count">锁</i></button>
+              <button class="node"><span>样品评审</span><i class="count">锁</i></button>
+              <button class="node"><span>产品实拍</span><i class="count">锁</i></button>
+              <button class="node"><span>安装方式</span><i class="count">锁</i></button>
+              <button class="node"><span>包装细节</span><i class="count">锁</i></button>
+            </div>
+          </div>
+        </aside>
+      </section>
+    </main>
+  </body>
+</html>