设计师

今天要做什么

按节拍跑图：每天推「评审中」的图纸和当日新图，每周盘未关联的「已通过」图与待收设计费，每月核已抵订单的设计费金额与项目齐套状态。

每日

1. 开班先扫 /dashboard/designs，按状态「评审中」（in_review）筛选，收昨日评审人批注；通过的切到「已通过」（approved）。
2. 接销售转来的 RFQ / 项目：在「新建设计」里选项目、上传图纸文件 DWG / DXF / AI / PSD / PDF（单文件 ≤ 50MB）。
3. 给「已通过」图纸做关联：详情点「关联」挂到「报价行」（quote_item）/「订单行」（order_item）/「产品档案」（product），下游采购与生产从此读图。
4. 去 /dashboard/designs/fees 核当日到账：给「待付」（pending）设计费记录收款；客户付清后系统自动推进到「已付款」（paid），随后点「开始设计」进入「设计中」（designing）。
5. 完工出图：已交付的设计费点「完成」进入「已完成」（completed）；锁定订单后做抵扣。

每周

• 盘「已通过」但没有关联记录的图纸（approved 却无 drawing_assignments 行）：未关联意味着下游没拿到图。
• 盘「已付款」但三天还没开工的设计费（status='paid' 却未进入 designing）：约客户再确认规格。
• 盘项目齐套：项目下「图纸齐套度」未达 100% 的跟进评审人。

每月

• 核「已抵订单」的设计费：状态为「已抵订单」（status='converted'）的记录，其 amount_applied_to_order（抵扣金额）要与目标订单的 paid_amount（已收金额）对得上。
• 清「已驳回」图纸：rejected 超一个月未修订的归档或删除。

权限红线（先看这 5 条）

• 图纸文件只接受 DWG / DXF / AI / PSD / PDF / PNG / JPG / GIF / SVG / WebP（这些是行业通用的设计源文件和图像格式，保留原英文缩写），单文件 ≤ 50MB——超限或扩展名不符直接被系统拒收。
• 状态为「已通过」（approved）的图纸不能改文件本体——要改必须重新上传新一条记录并自增版本，老版保留。
• 设计费处于「待付」（pending）状态不能直接转订单抵扣——必须先收齐款进入「已付款」（paid）/「已完成」（completed）后才允许「抵扣订单」。
• BOM（物料清单）编辑入口在产品模块（/dashboard/products/[id]），不在 /dashboard/designs——设计师跨模块维护变体 BOM，项目 BOM 在 /dashboard/projects/[id]。
• 已「抵订单」（converted）的设计费不能退——已抵订单的款项只能在订单侧冲销，不走设计费退款流程。

系统功能缺口（3 项，培训开场必讲）

以下是设计师日常高频想用、但当前系统尚未在 UI 暴露的功能。学员先知道"哪里不能点"，避免到处找入口。遇到这三类需求走替代方案，或联系 IT。

1. ECO / 工程变更单（design_change_orders）无专用表与入口。 行业通用的"已批准图纸改动要走 ECO 流程"在本系统没有独立单据。替代方案：重新走「新建设计」上传新版（版本号 version 由设计师手工自增），状态选「评审中」（in_review）做新一轮评审；旧版保留用于追溯；下游已关联的图纸要手动切到新版 drawing_id。
2. BOM 版本无法在界面回滚。 代码里有 revertBOMVersion 这个函数（意思是"回滚 BOM 版本"），但 UI 目前没有对应按钮——改错只能在产品详情的 BOM 管理器里删行重建；需要保留历史请让管理员从 DB 侧做快照。
3. 设计费"作废"（forfeited，即客户弃付没收的场景）UI 无触发入口。 数据库枚举已预留这个状态，但前端没暴露任何按钮；如需使用，联系 IT 走后台更新。日常不需要认识这个状态。

Quickstart — 日常核心任务

2.1 上传设计图纸

客户 / 销售确认设计需求，项目已落库；把 DWG / PDF / AI 等设计文件传入系统并关联项目，供下游评审。

1. 进 /dashboard/designs，右上点「新建设计」。（见图 ①）
2. 弹窗填图纸名（必填）；选所属项目（必填，图纸必须挂项目）。（见图 ②）
3. 选初始状态：默认「草稿」（draft）；已和客户当面确认可直接设「评审中」（in_review）。（见图 ③）
4. 拖拽文件或点上传区选文件——超过 50MB 或扩展名不在白名单会立即报错。（见图 ④）
5. 填备注（可空），点「提交」——系统存入存储桶 design-drawings 并落到图纸表。

何时不该做：未确认项目归属（projectId 未填）的图纸不要传——无项目归属会导致后续项目齐套度统计漏掉该图，下游采购 / 生产在 /dashboard/projects/[id]?tab=drawings 也看不到。文件 > 50MB 不要拆分后混传——走分块上传或先在外部压缩。

观测信号：

1. 画廊顶部出现新卡片，缩略图可见，状态徽标按所选初始状态显示。
2. 详情页「版本」= v1（新建记录）；「文件大小」与本地文件一致。
3. 项目详情「图纸」Tab 下该图出现在聚合视图里。

技术追溯：图纸表 design_drawings 新增行，file_url 指向 /object/public/design-drawings/；version=1；status 属于 (draft, in_review)。

系统动作：uploadDesignDrawing

2.2 图纸评审流转

草稿完成自检后送审；评审人在详情页做通过 / 驳回；驳回后修订可回退到草稿再上传新版。

1. 在画廊点图纸卡片进详情页。
2. 右下「操作」卡片点「提交评审」——状态由「草稿」（draft）推进到「评审中」（in_review）。（见图 ①）
3. 评审人打开详情，点「批准」或「驳回」——状态由「评审中」推进到「已通过」（approved）或「已驳回」（rejected）。（见图 ②、③）
4. 被驳回图纸点「回退草稿」回到「草稿」状态，然后重新上传新版（当前不支持在同一行替换文件本体）。（见图 ④）

何时不该做：已「已通过」（approved）的图纸不要再动状态——下游采购 / 生产可能已据此排料。确需改设计：新版上传后走新一轮评审，老版保留做追溯。已知缺口：当前系统没有独立的 ECO（工程变更单）表（代码里 design_change_orders 未实现），变更靠新版号 +「评审中」重走流程。

观测信号：

1. 详情页顶部状态徽标按 「草稿」→「评审中」→「已通过」/「已驳回」推进。
2. 画廊卡片的状态下拉同步变更。
3. 项目齐套度分子 +1（项目下所有图纸都「已通过」时触发下游开工闸）。

技术追溯：图纸状态列 design_drawings.status enum: draft | in_review | approved | rejected；合法 transition（流转）：draft↔in_review、in_review→approved|rejected、approved|rejected→draft；齐套检查函数 checkProjectDrawingsReady。

系统动作：updateDrawingStatusAction

2.3 关联图纸到业务实体

图纸「已通过」（approved）后必须挂到具体的报价行 / 订单行 / 产品档案，否则采购和生产读不到。

1. 在图纸详情右上点「关联」打开关联对话框。
2. 弹窗选关联实体类型：「报价行」（quote_item）/「订单行」（order_item）/「产品档案」（product，即产品变体层）。
3. 填目标实体 ID（从报价 / 订单 / 产品详情页复制 UUID）。（见图 ①）
4. 填备注（例如「对应卧室衣柜 3#」），便于下游识别。（见图 ②）
5. 点「关联」——数据落入「图纸关联表」（drawing_assignments），详情页右下关联卡片出现新行。

何时不该做：关联实体类型 entity_type 只允许三种值：quote_item / order_item / product——填其他值会被拒。未「已通过」的图就挂生产订单会让生产照草稿开料，出错只能返工。同一图纸挂多个实体要分别做一次关联（不是批量）。

观测信号：

1. 图纸详情的关联卡片出现新行，实体类型徽标 + 前 8 位实体 ID 可见。
2. 下游模块按实体 ID 反查：订单详情会显示图纸链接；产品详情图纸页面亦显示。

技术追溯：图纸关联表 drawing_assignments 新增行（drawing_id、entity_type、entity_id、notes、created_by）。

系统动作：assignDrawingToEntityAction、getDrawingAssignments

2.4 编辑图纸元数据

图纸名 / 描述录错或要补充说明，元数据可改；文件本体不能原地替换。

1. 图纸详情右上点「编辑」。（见图 ①）
2. 改名称 / 描述（注意：文件上传区在此弹窗无效——这是元数据编辑，不是新版上传）。（见图 ②）
3. 点「保存」——版本号（version）不变，也不触发评审重置。

何时不该做：要换文件内容不要在这里改——此入口只动名称（name）/ 描述（description）。换文件走「新建设计」传新版并自增版本号，老版保留用于追溯。

观测信号：

1. 详情页标题同步刷新为新名称。
2. 画廊卡片标题同步变更。
3. 版本号不变。

技术追溯：图纸表 design_drawings 的 name / description 更新；version 不变；updated_at（更新时间）刷新。

系统动作：updateDrawingMetadataAction

2.5 创建设计费单

客户确认设计委托后，在收款前落一张「设计费单」以便跟踪到账、开票和后期抵扣。

1. 进 /dashboard/designs/fees，右上点「新建设计费」。（见图 ①）
2. 填客户（必填，从客户列表复制客户 ID）。
3. 填金额（必填）；币种默认人民币（CNY），外币项目需改。（见图 ②、③）
4. 关联项目（可选）；填设计描述、交付期限、条款、备注。（见图 ④）
5. 点「提交」——系统自动生成设计费编号（格式 DF-YYYY-NNNN，例如 DF-2026-0007），初始状态为「待付」（pending）。

何时不该做：未经客户书面 / 邮件确认设计委托禁止建单——「待付」的单出现在财务应收预期列表里，无效单会污染回款预测。币种填错必须删单重建，不能直接改（影响下游汇率换算）。

观测信号：

1. 设计费列表顶部出现新行，编号 DF-YYYY-NNNN。
2. 状态徽标显示「待付」（pending）。
3. 详情页「已付金额」= 0、「可抵扣余额」= 0。

技术追溯：设计费单表 design_fees 的 design_fee_number 自增；status='pending'；amount（总额）写入、paid_amount（已收金额）= 0。

系统动作：createDesignFeeAction

2.6 记录设计费收款 + 状态流

客户转账到账，按实际到账金额累加「已收金额」；付清后流转状态到「设计中」再到「已完成」。

1. 设计费详情页核对金额与客户匹配。
2. 出纳 / 销售确认银行到账后，在设计费详情触发收款记录（累加已收金额 paid_amount）。
3. 付清后状态自动进入「已付款」（paid）；点「开始设计」进入「设计中」（designing）。
4. 设计交付后点「完成」进入「已完成」（completed）——此时可抵订单。
5. 全程未开工可点「退款」进入「已退款」（refunded）。

何时不该做：未收到银行回单禁止预录收款——错录需走删除回滚，且会误导「已付 / 未付」仪表盘。状态未到「已付款」前不要点「开始设计」——系统硬校验收款完成才允许进入「设计中」。处于「已抵订单」（converted）/「已退款」（refunded）状态下点任何动作都会被拒。

观测信号：

1. 详情页「已付金额」按收款额增长；付清后「剩余未付」= 0。
2. 状态徽标按「待付」→「已付款」→「设计中」→「已完成」推进。
3. 列表页徽标色变化（待付 灰、已付款 蓝、设计中 黄、已完成 绿）。

技术追溯：设计费表 design_fees 的 paid_amount 累加、paid_at（付款时间）落时间戳；status 枚举：pending | paid | designing | completed | converted | refunded | forfeited（forfeited = 作废，仅数据库预留，目前无 UI 入口）。

系统动作：recordPaymentAction、updateFeeStatusAction

2.7 设计费抵扣订单

客户由设计进入定做，销售已转订单（单号前缀 SO-）；把已完成的设计费作为订单预收款抵扣首付。

1. 确保设计费状态为「已完成」（completed）、客户与目标订单客户一致。
2. 设计费详情「操作」卡片填目标订单 ID（从 /dashboard/sales/orders 复制 UUID）。
3. 点「抵扣订单」——系统写入「抵扣目标订单 ID」（converted_to_order_id）和「抵扣金额」（amount_applied_to_order），目标订单的已收金额 paid_amount 自动加上。
4. 会计在预付款表 prepayments 里看到一条类型为「设计费」（type='design_fee'）的记录。

何时不该做：客户不一致的订单不能抵——系统会校验设计费与订单的客户 ID 是否相同。状态不是「已完成」（处于「设计中」/「已付款」时）不允许抵。已「已抵订单」（converted）的设计费不能再抵第二单——一笔设计费只能抵一单；要拆分抵给多单需事先在抵扣金额里控制。

观测信号：

1. 设计费状态变「已抵订单」（converted），详情页显示关联订单号与抵扣金额。
2. 目标订单「已收 / 合计」数字增长；付款 Tab 出现预收款记录。
3. 会计 AR（应收账款）看到对应订单应收减少。

技术追溯：设计费 design_fees.status='converted'、converted_to_order_id / amount_applied_to_order / converted_at（抵扣时间）填充；销售订单 sales_orders.paid_amount 经 recalculateOrderPaidAmount()（订单已收金额重算函数）刷新；预付款表 prepayments 新增一行，类型为『设计费』（type='design_fee'）。

系统动作：convertFeeToOrderAction

2.8 跨模块查看 / 维护产品 BOM

定制产品需要挂 BOM（物料清单）供采购下单、生产备料；BOM 编辑不在设计模块，切到产品详情。

1. 进 /dashboard/products，在列表找到目标产品点进详情。
2. 滚到 BOM 管理卡片。
3. 新增行：选物料、填数量、选单位（默认「件」pcs，可选「米」m / 「平方米」m2 / 「千克」kg）。（见图 ①、②）
4. 选用途类型：「柜体」（cabinet_body）/「门板」（door）/「台面」（countertop）/「五金」（hardware）/「其他」（other）。（见图 ③）
5. 点新增按钮保存。（见图 ④）项目 BOM 走 /dashboard/projects/[id]?tab=bom，是另一套入口。

何时不该做：不要把材料直接填到图纸描述里代替 BOM——采购看不到、成本核算也拿不到。产品 BOM 和项目 BOM 是两套表（产品 BOM 表 bom_items vs 项目 BOM 表 project_bom），不要混用；定制件一般先在项目 BOM 草拟，定稿后同步到产品 BOM。已知缺口：BOM 版本目前不在用户界面暴露回滚按钮（代码里有 revertBOMVersion 函数但未挂 UI）——改错只能删行重建。

观测信号：

1. BOM 表格出现新行，物料名 / 数量 / 用途徽标可见。
2. 产品详情的成本摘要按新 BOM 重算。
3. 采购端在采购订单创建时能读到 BOM 展开。

技术追溯：产品 BOM 表 bom_items 新增行（product_id、material_id、quantity、unit、usage_type、position）；成本重算函数 computeBomCostSummary。

系统动作：BOM 的增删改查在产品模块（非设计师 actions.ts 范围）。

上下游交接契约

设计师产出「图纸 + BOM + 设计费」三类成品，全部靠关联 / 状态流触达下游。契约缺失下游读不到图 / 排不了产 / 对不了账。

异常回滚

图纸 / 设计费 / 关联 / BOM 误操作走下表规则回滚。不要直接改 DB。

进阶功能

相关业务场景

设计师是场景 2（定制家具项目流）的主角；场景 1（标品）和场景 4（采购付款）不参与；场景 3 作为抵订单 / 退款的触发方参与尾段。

1. 标准成单流（询盘 → 报价 → 订单 → 发货 → 开票）： 标品流设计师不参与——若报价行含定制件，销售会把项目 / 图纸请求转给设计师走场景 2 分支。 → 场景（了解即可）
2. 定制家具项目流： 设计师主导：接项目 → 上传草图（「草稿」）→ 收设计费 → 推到「设计中」→ 多轮评审 → 所有图「已通过」→ 关联到「订单行」/「产品档案」→ 订单签约后把设计费抵扣订单首款。 → 场景详解
3. 回款流： 设计师在设计费抵扣入口触发抵扣，走预付款表（类型『设计费』）挂订单预收款；退款走设计费状态流转到「已退款」。 → 场景详解
4. 采购付款流：设计师不参与付款——只负责给采购交付图纸关联 + BOM，下单 / 付款由采购 / 出纳做。 → 场景（了解即可）
5. 月结流： 设计师有限参与——月初清「已驳回」图、核「已抵订单」设计费金额对得上订单已收金额；会计端结账不参与。 → 场景详解
6. 报销审批流：设计师作为申请人走 /dashboard/expenses（外勤 / 打样耗材报销），非核心动作——不在 Quickstart 范围。 → 场景（作为申请人）

外部协作入口

• /dashboard/projects — 项目视图，图纸聚合 / BOM 齐套 / 里程碑；定制项目起点。
• /dashboard/products — 产品与 BOM 维护入口；定制件建变体 + 挂 BOM 在此。
• /dashboard/inquiries — 询盘池，AI 文档解析的 RFQ 由销售复核后转项目。
• /dashboard/wecom — 企微消息（图纸送审 / 已批准 / 设计费到账通知）配置入口。
• /dashboard/settings/email — 外贸邮件网关（发 PDF 图纸给客户用）。
• /dashboard/manual — 系统内置使用手册（补充参考）。

权限与范围

看得到什么（行级安全边界）

• 当前组织（organization_id）下的所有图纸（design_drawings）/ 图纸关联（drawing_assignments）/ 设计费单（design_fees）。
• 产品 BOM（bom_items）与项目 BOM（project_bom）按组织隔离。
• 图纸存储对象落在 design-drawings 存储桶（公开桶 + 路径隔离）；URL 自带组织前缀。

核心概念

• organization_id（组织 ID）— 租户隔离键。设计师只看本组织图纸 / BOM / 设计费。
• book_id（账套 ID）— 账套隔离键，设计费属财务数据受账套隔离；切账套后看到的设计费集合变。
• 图纸关联表 drawing_assignments — 图纸到业务实体的多对多桥表，是下游读图的唯一正式入口。
• 工作流引擎（src/services/workflow-engine.ts）——图纸状态由代码硬编码流转规则（非 PostgreSQL enum），设计费状态同理。

术语表

设计图纸（图纸表）

design_drawings（name + version）

图纸状态枚举

draft 草稿 | in_review 评审中 | approved 已通过 | rejected 已驳回

图纸版本

design_drawings.version（整数，手工自增）

文件 URL

design_drawings.file_url（指向 /object/public/design-drawings/）

文件大小限制

50MB（uploadDesignDrawing 硬校验）

允许文件类型

png / jpg / gif / svg / webp / pdf / dwg / dxf / ai / psd（设计行业通用格式）

图纸关联（图纸关联表）

drawing_assignments（drawing_id × entity_type × entity_id）

关联实体类型枚举

quote_item 报价行 | order_item 订单行 | product 产品档案

项目齐套检查

checkProjectDrawingsReady(projectId)（全部图纸「已通过」才 ready）

设计费单（设计费表）

design_fees；编号 design_fee_number 格式 DF-YYYY-NNNN

设计费状态枚举

pending 待付 | paid 已付款 | designing 设计中 | completed 已完成 | converted 已抵订单 | refunded 已退款 | forfeited 作废（目前无 UI 入口）

设计费抵订单

design_fees.amount_applied_to_order（抵扣金额）+ converted_to_order_id（目标订单 ID）

预收款桥（预付款表）

prepayments（类型 type='design_fee' = 设计费）

产品 BOM（物料清单）

bom_items（product_id × material_id）

BOM 用途枚举

cabinet_body 柜体 | door 门板 | countertop 台面 | hardware 五金 | other 其他

BOM 单位

pcs 件 | m 米 | m2 平方米 | kg 千克（默认 pcs）

项目 BOM

project_bom（独立表，绑项目 ID）

图纸上传核心动作

uploadDesignDrawing

图纸关联核心动作

assignDrawingToEntityAction

设计费抵订单核心动作

convertFeeToOrderAction

常见问题