trades-builder

贸易运营技能

此技能的作用

此技能定义了如何构建贸易运营工具——这是施工类行业和现场服务企业每天运行的估算到付款工作流。

这不是通用项目管理工具（Jira/Asana），也不是 CPQ 工具（不包含产品配置）。它专为以下企业打造，用于跟踪工作流：

• 根据测量的范围项目（平方英尺、线性英尺、单位）创建估算
• 为施工队或分包工种安排并分派现场工作
• 按范围项目和地点跟踪进度
• 根据已完成的测量工作向分包工种付款
• 向客户开具发票并收款

**常见行业：**石膏板、屋顶、HVAC、管道、电气、油漆、地板、混凝土、景观美化、总承包。

构建者会阅读此技能，阅读特定工种及其术语对应的 DOMAIN.md，并生成一个可用原型，其中使用客户实际的范围项目、定价和工作流阶段。

何时使用此技能

当记录或 DOMAIN.md 包含以下信号时，请使用此技能：

信号	示例
带有测量值的范围项目	平方英尺、线性英尺、板英尺、单位面积内的单位数量
现场排期	施工队分派、工作日历、现场工作规划
分包工种付款	向分包商付款、工种付款、按平方英尺计算的付款费率
估算到发票的工作流	估算 → 排期 → 施工 → 发票周期
工种特定范围	保温、石膏板、批嵌、屋顶、框架、管道粗装
基于地点的规格	每层、每个房间、每个区域的不同规格
双向开票	工种发票（向分包商付款）和客户发票（向客户收款）

请勿将此技能用于：

• 存在依赖关系的产品配置 → 使用 cpq-builder
• 库存和存货管理 → 使用 erp-builder（未来推出）
• 通用 CRM 或联系人管理 → 使用 crm-builder

---

模板约定

开始构建前，请了解模板提供了什么，以及此技能会添加什么。这就是约定：

模板（app/layouts/MainLayout.tsx）包含：

• SidebarProvider、Sidebar、SidebarContent、SidebarInset、SidebarTrigger — 已完成连接
• SidebarContent 为空 — 这是你的填充区域
• 页眉中有一个品牌位置（徽标占位符 + 公司名称）
• 页眉右侧区域中有 ModeToggle 和用户菜单

此技能会填充：

• SidebarContent — 加入垂直步骤导航和已保存的项目（见下文的布局模式）
• 页眉中的品牌位置 — 加入 DOMAIN.md 中的客户徽标和公司名称
• 页眉右侧区域 — 在现有用户菜单前加入角色切换器 DropdownMenu
• <main> 中的 <Outlet /> — 通过各个路由组件呈现五个部分

此技能不会：

• 添加第二个 Sidebar 组件。侧边栏只有一个。
• 在 SidebarContent 中放置品牌区块。品牌只放在页眉中。
• 重新连接 SidebarProvider 或替换可折叠行为。使用现有配置。
• 将步骤导航作为水平标签页放在主内容区域中。步骤导航应作为垂直列表放在 SidebarContent 中。

如果你发现自己想要重构 MainLayout.tsx，请停下来——几乎总是应该改为填充 SidebarContent。

---

部分定义

trades-builder 工具有五个部分。这些部分是固定的——它们来自此技能，而不是记录中描述的业务流程。

第 1 节：估价

功能： 记录项目详情，并根据工作范围生成估价。

项目详情（可内联编辑）：

• 项目名称 — 可内联编辑的文本（点击即可编辑，失焦时保存）
• 客户名称 — 可内联编辑的文本
• 地址 — 可内联编辑的文本
• 估价编号 — 自动生成，只读
• 客户来源 — 如果 DOMAIN.md 定义了来源，则使用 Select 下拉菜单；否则使用自由文本
• 估价人员备注 — Textarea，始终可编辑

工作范围项目表（本节的核心内容）： 此表是应用中最重要的元素。每一行代表一项已测量数量的工作范围。

列	类型	可编辑	备注
工作范围	Select 下拉菜单	是	选项来自 DOMAIN.md：保温、干墙、接缝处理、打磨、清洁、底漆施工等。
位置	文本输入框	是	例如“主层客厅”“地下室套间”
规格/类型	文本输入框或 Select	是	例如“X 型”“防潮”“R-20 棉毡”“4 级饰面”
平方英尺	数字输入框	是	此位置此项工作范围的面积
单价	数字输入框	是	每平方英尺的价格（CAD）
行总计	计算得出	否	平方英尺 × 单价，自动计算
操作	删除按钮	—	垃圾桶图标，用于移除此行

• 表格下方的 “添加行”按钮，用于添加更多工作范围项目
• 同一工作范围类型可有多行 — 例如，不同位置、类型不同的两行干墙项目
• 自动计算页脚： 小计、税费（GST 5%）、总计 — 每次单元格更改时更新
• 所有单元格均可直接编辑 — 点击单元格、输入内容，失焦时保存。内联编辑模式请参阅 frontend-design 技能。

需使用的 DOMAIN.md 数据：

• 实体注册表 → 工作规格子项用作“工作范围”下拉选项
• 业务规则 → 计量单位（sqft、lft）、税种和税率、付款条款
• 术语表 → 使用准确的工作范围名称（而非通用标签）

第 2 节：日程安排

功能： 规划现场工作的分配和顺序。

字段（可编辑）：

• 指派的角色/人员 — 使用 DOMAIN.md 利益相关者映射中的 Select 下拉菜单，不可使用自由文本
• 工作范围顺序 — 可重新排序的列表，显示各项工作范围的执行顺序
• 开始日期 — 日期选择器，可编辑
• 目标完成日期 — 日期选择器，可编辑
• 现场施工人员备注 — Textarea，可编辑

如果 DOMAIN.md 提及日程安排工具（例如“使用 Bold 安排日程”），则在本节说明中提及：“使用 Bold 安排现场施工人员。”

第 3 节：进行中

功能： 按工作范围项目和位置跟踪工作完成情况。

显示内容：

• 从估价中的工作范围项目填充表格 — 保留相同的行，用于跟踪完成情况

列	类型	可编辑	备注
工作范围	文本	否	来自估价
位置	文本	否	来自估价
平方英尺	数字	否	来自估价
状态	Select 下拉菜单	是	未开始 / 进行中 / 已完成

• 状态更改后立即保存到 localStorage
• “全部标记为已完成”按钮，用于批量更新
• 进度指示器：“已完成 5 项工作范围中的 3 项”

第 4 部分：结项

功能： 处理双重付款流程——向分包商付款，并向客户开具发票。

显示——两个并排的发票区域：

分包商发票区域：

• 分包商付款金额——根据已完成的范围项目自动计算（平方英尺 × 费率）
• 状态：Select 下拉菜单——待付款 / 已付款
• 付款日期——日期选择器，状态为已付款时可编辑
• 如果 DOMAIN.md 中提及 Bold，则在此引用

客户发票区域：

• 发票金额——Estimate 中的小计 + 税费

• 状态：Select 下拉菜单——待发送 / 已发送 / 已付款

• 发票日期——可编辑的日期选择器

• 如果 DOMAIN.md 中提及 Arvest，则在此引用

• “结项”操作按钮，将项目标记为已完成

• 两个发票状态都必须保存到 localStorage

如果 DOMAIN.md 中提及开票工具，请在区域标题中引用它们：“分包商发票（Bold）”和“客户发票（Arvest）”。

第 5 部分：工作摘要

功能： 以只读形式汇总已完成的项目——最终输出视图。

布局（从上到下）：

1. 公司页眉——来自 domain.md Brand Logos 部分的品牌 Logo（使用提供的 Logo URL 或路径）+ 公司名称 + 占位地址（“123 Main St, City, Province, Postal Code — update in settings”）
2. 项目信息——项目名称、客户、地址、估算编号、日期、负责人。标签/值对组成的两列网格。
3. 范围摘要表——所有范围项目，包含范围类型、位置、规格/类型、平方英尺、费率、行总计。使用简洁的 Table，数值列右对齐。
4. 总计区块——小计、税费（GST 5%）、总计。总计以大号粗体显示。
5. 付款状态——分包商发票状态徽章 + 客户发票状态徽章，并排显示。
6. 条款——付款条款（Net 30）、货币（CAD）。

此视图完全只读。 没有编辑控件、输入框或下拉菜单。用户需要在步骤导航中点击返回 Estimate 或 Schedule 来进行修改。工作摘要是输出结果，而不是工作区。

布局模式

trades-builder 工具采用三面板布局，包含五个部分（不是四个）。构建器必须遵循此布局。

左侧边栏（始终可见，可折叠）

模板已在 app/layouts/MainLayout.tsx 中配置好 SidebarProvider、Sidebar、SidebarContent 和 SidebarTrigger。SidebarContent 目前为空——此技能要填充的就是这个区域。不要重新配置侧边栏，不要添加第二个 Sidebar 组件，也不要在其中放置品牌标识块。品牌标识仅放在页眉中（参见上文的 Template Contract）。

侧边栏标题： 使用“工作流”或“项目工作流”等与上下文相关的标签——不要使用公司名称。标题应描述导航的用途。

组件	内容
步骤导航	在 SidebarContent 中垂直列出全部五个部分：(1) Estimate、(2) Schedule、(3) In Progress、(4) Close Out、(5) Job Summary。每个步骤显示：步骤编号、标签、部分描述中的副标题，以及完成状态。在侧边栏中使用垂直步骤导航——不要在主内容区域使用水平标签页。
已保存项目	列出存储在 localStorage 中的项目。每项显示名称 + 客户 + 状态徽章（已估算 / 已排期 / 进行中 / 已完成）。将此区域固定在侧边栏底部，确保无需滚动即可看到。双击项目名称可内联重命名。

重要：步骤导航标签来自本技能，而不是 DOMAIN.md。 DOMAIN.md 状态模型可能列出 estimated, scheduled, in progress, completed——这些是项目的状态值，用于状态徽章。步骤导航的标签是本技能定义的部分名称：Estimate、Schedule、In Progress、Close Out、Job Summary。 两者不同。步骤导航有 5 个步骤，领域模型有 4 个状态。不要将领域模型的状态列表用作步骤导航标签——否则会只有 4 个步骤，缺少 Close Out 和 Job Summary。

主内容区（居中——随所选部分变化）

仅渲染当前活动部分。不要将所有部分堆叠在同一个可滚动页面上。不要将多个部分合并到同一个面板中（例如，将“Schedule / In Progress / Close Out”作为一个部分是错误的——每个部分都应有各自的面板）。不要使用水平标签页。每个步骤条步骤都应在主内容区的完整宽度内显示对应面板。隐藏所有其他面板。

实现：使用 currentStep 状态变量（0–4）。仅渲染与 currentStep 匹配的面板。

// ALL FIVE panels, conditional rendering
{currentStep === 0 && <EstimatePanel />}
{currentStep === 1 && <SchedulePanel />}
{currentStep === 2 && <InProgressPanel />}
{currentStep === 3 && <CloseOutPanel />}
{currentStep === 4 && <JobSummaryPanel />}

部分	渲染内容
Estimate	项目详情表单 + 可添加/删除行、包含数量和费率并自动计算总额的范围项目表格。“Save estimate”和“Continue to Schedule”按钮。
Schedule	角色/施工队分配下拉菜单（来自 DOMAIN.md）、范围顺序、日期字段、现场备注。“Continue to In Progress”按钮。
In Progress	按位置划分的范围跟踪表，每行显示状态。“Mark completed”按钮。
Close Out	贸易发票部分 + 客户发票部分，并排显示。“Close out job”按钮。
Job Summary	只读格式化项目摘要，包含公司标题、范围表、总额和付款状态。

右侧边栏（始终显示）

组件	内容
Project summary	实时更新的边栏摘要：当前阶段、估算编号、付款条款、小计、税额、总额。范围项目变更时同步更新。
Workflow notes	将 DOMAIN.md 中的业务规则作为上下文指引显示。引用 BR-ID。
Actions	返回、继续和删除项目按钮。主要操作使用品牌强调色。

RBAC 行为

• 使用 DOMAIN.md 的 User Roles 或 Stakeholder Map 中的角色填充 localStorage。
• 角色切换器是标题栏中的单个 DropdownMenu 下拉菜单，不是多个独立按钮。显示当前活动角色名称和徽章。
• 审批限制：如果 DOMAIN.md 规定只有特定角色才能结项或审批，则对其他角色禁用这些按钮。
• 角色专属视图：如果不同角色负责不同阶段（例如，估算员负责 Estimate，项目经理负责 Schedule），则在该角色处于活动状态时显示相关上下文。

价格显示

• 在 Estimate 面板中显示价格——单价、行总额、小计、税额、总额。
• 在右侧边栏的 Project Summary 中显示累计总额。
• 使用 DOMAIN.md 中指定的货币、税种和税率。
• 价格需使用货币代码格式（例如，“$3,900.40 CAD”，或使用“$3,900.40”，并在摘要中显示“CAD”）。

shadcn/ui 组件映射

将卡片视为例外，而不是默认布局基元。尽可能将内容直接放入页面主体。只有确实需要强调、分隔、重复展示或呈现对话框／详情时，才使用卡片。不要构建卡片繁多的仪表板、卡片中嵌套卡片，或由悬浮面板组成的通用网格。

贸易运营元素	shadcn 组件	使用说明
项目详情表单	Input、Label、Select	项目名称、客户、地址。将标签置于输入框上方。
工作范围项目表格	Table、TableHeader、TableRow、TableCell	添加／移除行。数值列右对齐。
工作范围项目状态	Badge	未开始 = 轮廓样式，进行中 = 蓝色，已完成 = 绿色。
项目状态徽标	Badge	已估价 = 琥珀色，已排期 = 蓝色，进行中 = 蓝色，已完成 = 绿色。
角色徽标	Badge	员工 = 轮廓样式，审批人 = 默认样式。
任务分配下拉菜单	Select、SelectContent、SelectItem	使用 DOMAIN.md 中的利益相关方姓名填充。不得使用自由文本输入框。
发票状态分区	使用 Separator、Badge、Select、Input 的内联分区	贸易商发票与客户发票并排显示。只有在发票确实需要更明显的分隔时才使用卡片。
操作按钮	Button	主要按钮：品牌强调色，“继续”。次要按钮：轮廓样式，“返回”。危险操作：“删除项目”。
步骤导航	自定义垂直列表	放在 SidebarContent 中。步骤编号置于圆圈内，包含标签、副标题和完成勾选标记。使用 cn() 设置状态。
角色切换器	DropdownMenu	在页眉中放置单个下拉菜单触发器。
项目摘要侧边栏	内联堆叠的标签／值行	标签使用弱化色，值加粗。总计行字号较大并突出显示。
工作流备注	紧凑的弱化色备注块	引用带有 BR-ID 的参考资料。
日期字段	Input，并设置 type="date"	开始日期、目标完成日期。
备注／多行文本框	Textarea	估算员备注、现场施工人员备注。
确认对话框	AlertDialog	删除项目、结项。
Toast 通知	Sonner / toast()	保存、标记为已完成、结项后显示。

确定性映射规则

实体 → 工作范围项目映射

当 Knowledge Agent 从转录内容中提取实体时，将其映射到 trades-builder 结构：

DOMAIN.md 实体	映射到	所属分区
项目 / 工单	项目记录（顶层）	所有分区
估价	估价数据（价格、条款）	估价面板
工单规格 / 工作范围	工作范围项目表格行	估价 + 进行中
发票	客户发票分区	结项
贸易商发票	贸易商发票分区	结项
分包商付款	贸易商发票的付款状态	结项
现场计划	计划数据	计划面板

业务规则 → 验证映射

DOMAIN.md 规则模式	实现方式
“按平方英尺跟踪”	工作范围项目表格使用平方英尺作为数量列
“按平方英尺付费”	贸易商发票金额 = 已完成工作范围项目的（平方英尺数 × 单价）之和
“每个地点有不同的[类型]”	工作范围项目表格包含地点列，同一工作范围类型可有多行
“阶段：已估价、已排期、进行中、已完成”	步骤阶段必须完全一致
“手动输入”	项目创建表单，不提供导入流程
“GST/HST 为 X%”	在估价单和发票中添加税费行，并将税种作为标签
“Net 30/45”	在摘要和发票中显示付款条款
“只有[角色]可以[操作]”	对相关按钮实施 RBAC 权限门控

集成 → 参考资料映射

如果 DOMAIN.md 列出了集成点（例如 Bold、Arvest、QuickBooks），请在分区说明和工作流备注中提及，但不要构建集成界面。该原型仅使用 localStorage。集成功能将在完整版本中实现。

参考文件

此技能要求存在以下文件：

文件	用途
DOMAIN.md 或 .tasks/domain.md	业务术语、实体、规则、角色、品牌数据

编写任何代码之前，构建器应先读取 DOMAIN.md 或 .tasks/domain.md。