# 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：

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 / 进程 / 端口 / 日志 / 关键页面（本步需用户授权）。

发布前必须确认 `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 或同事交接时，写清：本次只改了什么、没改什么、验证跑了什么、风险是什么、下一步要看哪些文件。