furniture-3d-system-Wu/AGENTS.md

AGENTS.md

适用范围：D:\AI Code\3danzhuang-wuyongjie-mainline 全仓库。 未单独说明时，先遵循全局规则：C:\Users\54972\.codex\AGENTS.md。 这份文件只记录本仓库当前有效的补充规则和核查入口，不保存密码、密钥、数据库连接串或对象存储密钥。

重要边界：D:\AI Code\3danzhuang 是历史旧现场；当前正式工作目录以 D:\AI Code\3danzhuang-wuyongjie-mainline 为准。除非用户明确要求，不要混用旧目录、旧服务器别名、旧部署脚本或旧截图结论。

1. 当前项目真相

• 外层目录 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、Three.js/R3F、七牛/对象存储相关脚本等。
• CLAUDE.md、旧 README、docs/历史归档/ 和早期部署文档里可能仍有旧苹果风格、MinIO、旧 Docker 部署、旧模型数量、旧 Product/SKU 口径等信息；只能当历史参考，不能覆盖当前代码、workflow 文档和实时命令结果。
• 工作树可能有用户或其他协作者留下的未跟踪文件、日志、贴图和本地产物。只处理本次任务明确相关的文件，不要顺手清理或回退无关现场。

2. 开工前固定入口

当任务发生在 furniture-3d-system/ 时，改代码前必须先读这 3 份当前协作入口：

• furniture-3d-system/docs/workflow/团队协作模式.md
• furniture-3d-system/docs/workflow/模块边界说明.md
• furniture-3d-system/docs/workflow/主线同步操作手册.md

按任务类型额外读取：

• 生产、部署、线上排障：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:* 脚本说明。

如果文档和代码冲突，按这个顺序判断：当前代码和脚本、当前线上/命令返回、当前 workflow 文档、历史文档或旧记忆。

3. Git 与主线协作

• 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. 生产与部署

• 当前正式网址：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、storage:* 脚本、七牛迁移/GC 文档和生产环境变量实时核对；不要把历史 MinIO/S3 备份脚本当成当前生产存储真相。

5. 当前主链与模块边界

当前新平台数据主链按这条线理解：

资产中心 -> 辅助装配 -> 草稿组 -> 产品资料/正式入库 -> 仓库管理/轻仓库

当前全局工作台导航还包含首页、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/components/platform
• 主链规则与类型：src/lib/open-product、src/lib/planning

业务真相：

• 资产族：AssetFamily
• 规格款：AssetVariant
• 草稿组：DraftGroup
• 准 SKU：PreSku
• 入库结果：正式 Product / SKU
• 产品资料侧非集成开品：IntakeNonIntegratedProduct / IntakeNonIntegratedSkuItem

旧 CAD 兼容链继续存在，但不是新平台主数据源：

• 页面：src/app/products、src/app/products/[id]、src/app/products/[id]/assembly、src/app/products/[id]/skus/[skuId]
• 旧链模型和服务包括 Product / SKU / 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 下的具体子项，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/资产中心标准冲突，应在组件库体系内做专用变体、重写皮肤或局部重构。
• 没有出现在设计稿、组件规范或业务必要路径里的说明文案、辅助卡片、重复统计块、解释区，不要为了“更易懂”自行添加；工作区必须抓重点，图片类功能要让图片和关键动作成为第一层级。
• 前端修改后优先用真实页面、截图、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 -- --plan <file> --confirm-delete
  • npm run db:foundation:* 相关只读或授权脚本
• 前端体验类改动要结合浏览器实际操作和截图验证；涉及 3D/canvas 时要确认画面非空、尺寸正确、交互可用。
• 生产验证必须包含真实健康检查和日志/PM2/端口等现场证据，不能只说“本地构建通过”。
• 没有“规范审查结论”，任务不算完成。

9. 规范审查

规范审查固定只查三件事：

• 架构有没有被破坏。
• 视觉有没有跑偏。
• 这次是不是根因修复。

结论只能是：

• passed
• passed with warnings
• rejected

只要架构违规、视觉违规，或明显是补丁式修复，就必须 rejected。 如果这次不是独立复审，必须明确写出“这是自审，不是独立复审”。

统一清单：furniture-3d-system/docs/workflow/规范审查清单.md

10. 敏感信息和交接

• 账号密码、访问密钥、数据库连接串、对象存储密钥等敏感信息只能放在本地安全材料里，不写入 Git、共享文档、普通交接文本或长期记忆；生产域名、PM2 名称、部署目录这类非密钥运行入口可以写进仓库文档，但必须保持最新。
• 仓库内协作文档只写非敏感入口、流程和职责；凭据类信息必须用 [REDACTED_SECRET] 或本地路径说明替代。
• 发现摘要、日志或交接文件混有明文凭据时，先提示风险，再决定是否拆成本地敏感版和仓库协作版。
• 给下一个 agent 或同事交接时，写清：本次只改了什么、没改什么、验证跑了什么、风险是什么、下一步要看哪些文件。