AGENTS.md

适用范围：D:\AI Code\3danzhuang-wuyongjie-mainline 全仓库。未单独说明时，先遵循当前 agent 自己的全局规则（ZCode：C:\Users\54972\.zcode\v2\AGENTS.md；Codex：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 + Tailwind CSS + Three.js/R3F；另有 ioredis、puppeteer、exceljs/xlsx、zod、zustand 等）。package.json 变动后文档不自动同步，以实时核查为准。
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、生产发布、破坏性操作、删除数据、改远端历史等高风险动作必须有用户明确授权。

主线部署标准流程（每次"主线部署"都走这一套）

本仓库有两根主线，都不直接提交：main 是生产部署唯一来源（由 WuYongJie 收口），origin/codex/xuxiake-mainline 是共享开发次主线（日常回流基线）。

每次用户要求"主线部署"，严格按以下顺序，不跳步、不直接支线 → main：

在支线开发 → 提交到任务分支（如 codex/wuyongjie-xxx），不碰两根主线。
fetch xuxiake → 必须先 git fetch origin，看 origin/codex/xuxiake-mainline 有没有新提交。
有新提交 → merge origin/codex/xuxiake-mainline 拉下来处理冲突（长期共享分支用 merge，不 rebase）；只处理冲突文件，不扩范围。
合并到 xuxiake → 把支线合进 origin/codex/xuxiake-mainline，并 push 更新次主线。
合并到 main → 把 xuxiake 合进 main，并 push origin main（本步需用户授权）。
用 main 部署 → 走 scripts/deploy-yydd-prod-from-git.ps1（默认源 origin/main），部署后核对 commit / 进程 / 端口 / 日志 / 关键页面（本步需用户授权）。

发布前必须确认 git ls-remote origin refs/heads/main、本地 origin/main、目标部署 commit 三者一致。

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.ts、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/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 或同事交接时，写清：本次只改了什么、没改什么、验证跑了什么、风险是什么、下一步要看哪些文件。

15 KiB Raw Blame History Unescape Escape