方案设计 · 新人使用手册
从 0 到交付，一份方案该走的路都写在这里。按顺序读、按顺序点。截图是真实后台界面，按钮文案照抄，认字就行。
给谁看的
这份手册是给刚上手的新人/设计师/销售看的，目标是：照着 8 步走完一遍，能独立产出一份可报价、可交付的方案。
如果你是 admin / 维护者，要看「功能是怎么实现的、数据表怎么建、接口怎么调」——请看 功能文档 /docs/（技术视角）。这份是使用视角。
我能做什么（按角色看）
登录后右上角会显示你的角色。新人最常问的就是「为什么我点删除没反应」—— 答：你大概是只读账号。
| 角色 | 能做什么（方案设计模块） |
|---|---|
| admin 管理员 | 全权限；可改报价模板库、批量归档、人员管理。 |
| manager 项目经理 | 全权限（除报价模板库）；可批量归档、删归档。 |
| designer 设计师 | 全权限（除报价模板库、人员、审计）；日常就是这套 8 步。 |
| sales 销售 | 同 designer 权限；可独立出方案给客户做预算。 |
| viewer 只读 | 只能查看、导出、分享；所有写操作按钮不报错页但会提示「只读账号无法执行」，找管理员开权限。 |
术语表（先扫一遍）
- 方案
- 一个客户/一套户型的智能家居设备配置总单，含房间、设备、点位、报价。一个方案对应一份合同/报价/方案册。
- 等级 L1–L4
- 智能化程度分级：L1 基础智能 / L2 联动智能（默认）/ L3 全屋智能 / L4 AI 智能。后端只存代码，前端展示中文名。
- 物理房间
- 户型里真实存在的空间（客厅/主卧/厨房…），是设备能挂的地方，也是造价统计范围。
- 系统配置
- 全屋唯一类目的子系统（中控/照明/安防/暖通），也算造价。
- 方案元信息
- 选配向导写入的「网络方案 / 目标场景」汇总行，不参与造价——别把设备放这里，不然报价里看不到。
- 设备 / 设备项
- 挂到某个房间的某个具体产品（小米水浸卫士 ×1、领普三键开关 ×1）。
- 点位
- 户型图上某个位置标注的设备（用百分比坐标，拖拽移动）。一个设备可标多个点位。
- 点位的类型 point_kind
- 决定它在图上画成什么：switch 开关（蓝方块）/ light 灯（金五角星）/ curtain 窗帘（紫三角）/ sensor 传感器（青圆）/ ap 网络（灰方）。
- 控制关系
- 「开关的哪个键在哪个动作下控制哪个灯/触发哪个模式」。分物理线（要布线）和虚拟线（无线/场景）。
- 灯光模式
- 一组灯的目标态（开/关 + 可选亮度%）。可被某个键的某个动作触发（一键启动整屋场景）。
- 光晕
- 灯在图上显示的照射范围（半径根据瓦数+方案面积计算），方案面积 = 0 时不显示——是功能不是坏了。
- BOM / 报价
- BOM = 物料清单，按分类聚合，采购成本价；报价 = 含设计费/施工费的最终给客户价。
- COS 归档
- 导出的合同/报价单/方案册自动备份到腾讯云对象存储，每次导出覆盖同名文件，不留历史版本。
- 分享链接
- 一方案一条只读链接给客户预览。不勾「重新生成」时点保存不会换链。
步骤 1 · 进方案设计
1从左侧栏进「方案设计」
目的：找到入口、看清你有哪些方案。
登录后点左侧栏的「方案设计」（在「项目交付」分组下，排在「项目管理」之后）。
页面顶部会显示 6 个摘要卡：方案总数 / 启用中 / 停用·草稿 / 总房间 / 总设备项 / 已绑定客户；下面有搜索框、状态/等级筛选、排序下拉。
右上角是「+ 新建方案」—— 下一步用它。
提示：列表里只看到一个方案？正常——系统刚搭好就一个演示方案。新人练习时直接用这个方案点「设计」进下一步。
步骤 2 · 新建方案
2填表 → 保存方案
目的：创建一份方案的「壳」——编号自动、名字你定、等级和面积定基线。
点「+ 新建方案」进入表单页。只有「方案名称」是必填，其它都有合理默认值。
| 方案名称 * | 推荐格式：张先生·三室两厅·L2（客户 + 户型 + 等级） |
|---|---|
| 智能化等级 | 下拉选 L1–L4，默认 L2 联动智能 |
| 建筑面积（㎡） | 填实际数字。光晕/单价/报价都依赖这个值，为 0 会导致光晕不显示。 |
| 归属客户 | 下拉选已有客户，或选「-（手动填写客户名称）」直接在「客户名称」输入 |
| 设计/施工费率 | 默认 8% / 5%。报价自动按 设备小计 × 费率 计算设计服务费/安装施工费。 |
| 备注 | 可写客户偏好、特殊要求；导出方案册会带上 |
| 状态 | 默认「启用」；做废稿就改「停用·草稿」 |
点「保存方案」。系统会自动分配一个编号：QLZ-YYYYMMDD-NNN（如 QLZ-20260903-005），同一天递增。跳到方案详情页 = 第 3 步开始。
步骤 3 · 加房间与设备
3在详情页配房间 + 挂设备
目的：告诉系统这方案里有几个房间、每个房间要装什么、装几个。
3.1 加房间：在「房间与设备分布」卡顶部，「新增房间，如 书房」输入框里填名字（点输入框会弹出预设：玄关 / 客厅 / 餐厅 / 厨房 / 主卧 / 次卧 / 儿童房 / 书房 / 主卫 / 次卫 / 衣帽间 / 阳台 / 储物间 / 车库 / 影音室 / 茶室 / 健身房 / 其他），点「+ 房间」新增。
3.2 加设备：卡片顶部有一整排表单，从左到右依次填，最后点「+ 添加设备」：
- 选择房间（下拉，只列真实房间；「系统配置」「方案元信息」不可在此添加）
- 全部类型（下拉，如：智能开关 / 安防守护 / 传感感知）
- 选择设备（可搜索 combobox，30+ 设备库必备：键入「指纹」「Aqara」「TP」「灯」等任一段即可过滤；点选 → 下方自动填）
- 按标签过滤，如 指纹（可选，按产品的 tags 子串过滤，与「选择设备」文本输入是 AND 关系）
- 数量（默认 1）+ 备注（可选）
顺序别乱：先选房间，再选类型，设备下拉才会出东西。新人最常见的卡壳就是直接去点设备下拉，发现只有一句「请先选择类型」。切类型/改标签都会清空当前选择，避免「切了类型还是老设备」漏改。
3.3 套用报价模板（推荐，省时）：如果设备库里已有报价模板（在「报价模板库」里维护，仅 admin 可改），可在顶部「套用报价模板（快速出单）」卡选模板 →「套用到本方案」，会按模板房间/设备批量写入本方案。
① 套用非幂等：按房间名匹配，不同名就新建房间，重复套用会叠加设备。想覆盖请先手动清空方案。
② 元信息房间不计数：选配向导写入的「方案元信息」组（含「网络方案」「目标场景」汇总行）不参与造价统计——别把真设备放这里，否则报价里看不到。
③ 「复制」按钮 = 编辑页：列表行「📋 复制」跳到
/scheme/form?id=<id>，但点保存会 UPDATE 原方案 而非新建。复制的正确做法是手动新建方案再套用模板。
步骤 4 · 上传户型图
4进户型图页 · 上传图
目的：把客户家的 CAD/手画/拍摄图放进来，作为点位标注的底图。
点方案详情页顶部「户型图」按钮，进 /app/scheme/<id>/plan。
设计 · 户型图 · 数字孪生 · BOM · 报价 · 施工图不管你在哪一页，右上角都有这 6 个按钮，当前所在的那个会带蓝框。比如在户型图页想看立体效果，直接点「数字孪生」就行，不用先退回方案详情。
后面跟着的按钮（导出 SVG / 导出 CSV / 导出Word / 米家配置清单…）才是当前页自己的操作，跟着页面变。
「数字孪生」(/app/scheme/<id>/twin) 把同一张户型图做成 2.5D 等轴测，灯光按瓦数渲染光晕、点场景按钮一键切换「会客/观影/起夜/全亮/全关」、拖动可换视角。只读可视化，不动点位数据；点场景按钮不会真的下发到米家，纯演示。
- 「户型图名称」：如「一层平面」「主卧区域」
- 「选择文件」→ 「上传户型图」（仅图片，
image/*，上限 8MB）
cad/ 下的 DXF/DWG 解析模块 尚未接入 Web 层，所以传 DXF/DWG 没反应。如客户给了 CAD 图，先导出为 PNG 再上传。
上传后图会显示在下方画布。下一步开始标点位。
步骤 5 · 标注设备点位
5把设备点到图上
目的：告诉系统「这盏灯在客厅东南角、这开关在门口」——后续 BOM / 报价 / 控制图都依赖这个数据。
5.1 选设备（右侧「标注设备」卡）：「选择方案内设备」是可搜索的 combobox（不是普通下拉）：直接键入「灯」「小米」「客厅」等任一段即可过滤；用 ↑/↓ 浏览、回车确认、Esc 收起。选一项 → 下方出现「灯光渲染参数」（仅灯类需要填）。再次点击已选设备 → 自动定位并全选文本，直接键入即替换。切到「虚拟灯位」tab 会自动清空。
| 灯光渲染参数 | 必填 · 决定光晕半径 |
|---|---|
| 灯型 | 吸顶灯 / 筒灯 / 射灯 / 导轨灯 / 灯带 / 吊灯 |
| 瓦数 | 数字（如 8 / 24），影响光晕范围（瓦数越大光晕越大） |
| 方向 | 横向 / 竖向 / 全向，影响灯带类设备的光带渲染 |
5.2 在图上点：参数填好后去左侧图面，点要标注的位置。图上出现一个色点（蓝方=开关/金★=灯/紫三角=窗帘/青圆=传感器/灰方=AP），下方已标注点位列表多一行。
同一设备可标多个位置（每个位置算一个点位）。拖动色点可微调。
点「一键生成全部点位」按 5 列网格自动铺点（只能跑一次：图上已有任何点位即被拒；想重铺得手动清空或逐个删）。
· 真实设备：照方案「数量」落点，布满提示。
· 虚拟灯位：不占设备清单 / 不进 BOM 报价，但能画控制关系 + 配灯光模式，专给「不卖灯、只设计智能化逻辑」的场景用，无限添加。
「光线照不到」坑：图上看不到光晕？99% 是方案建筑面积 = 0。回步骤 2 填上面积。光晕算法是按 √(瓦数/参考值) × 方案面积 缩放，面积 0 → 缩放 0 → 不显示。
步骤 6 · 建控制关系（控制图）
6让开关「管」上灯
目的：把开关的物理按键和它控制的灯/窗帘/传感器连起来，给施工方一份清晰的布线清单，给客户一张「哪个键管哪个」的动作表。
6.1 切到控制模式：右侧「控制关系（控制图）」卡点「控制模式」按钮（高亮蓝底即生效）。
6.2 选键位 / 动作 / 线型：控制盒出现三个下拉
- 键位：键 1 / 键 2 / 键 3（三键开关就是这三个按键）
- 动作：单击 / 双击 / 长按（同一键可挂不同动作触发不同目标）
- 线型：物理线（红实线，要布线）/ 虚拟线（黄虚线，无线/场景）
6.3 点开关：左侧图上点一个 蓝色方块（switch 类型）的点位。控制盒里出现「已选开关：xxx」+「再点一个受控点位即可建立关系」。
6.4 点受控点位：再点一个非开关点位（灯/窗帘/传感器），立刻在它俩之间画一条线（红实线或黄虚线，按你的线型选），并入「按键动作表」+ 一行记录。
6.5 查看 / 删 / 聚焦：
- 右侧「按键动作表」按 键位→动作顺序排好；模式目标用 ⚡金底标记
- 点行尾「×」删关系
- 图上点一条线 → 加粗 + 显示气泡「键N·动作 → 受控点」+ 把受控点高亮，其他变暗
- 再点同一条线 → 取消聚焦
「控制关系」「灯光模式」两块都独立到户型图下方跨整行卡片里（参考「已标注点位」的样式），列宽更宽松、组头文字不再换行——右侧 300px 窄列只放「标注设备」+ 图例。
6.6 把键位绑到「灯光模式」（可选）：想让某个键触发场景（比如「双击 → 观影模式」），在控制盒下方有「绑定到模式…」下拉，选模式 → 点「绑定」。图上开关旁边会出现 ⚡金底「键N·动作」徽标，模式 link 画成自环（区别于普通线）。
步骤 7 · 配灯光模式（场景联动）
7把常用场景做成「一键」
目的：把「回家」「观影」「夜灯」这种「一组灯按某种状态开」做成一个模式，让某个键一键触发。
7.1 新建模式：右侧「灯光模式（场景联动）」卡点「+ 新建模式」弹模态。
7.2 命名：建议「观影模式 / 夜灯模式 / 全屋关灯 / 回家」之类。最多 60 字；同方案内不可重名。
7.3 勾选灯 + 设状态：模态里按房间分组列出方案内所有灯类点位。每行：
- 勾选框：纳入此模式（不勾 = 不受影响）
- 开/关：下拉选「开」或「关」
- 亮度%：可选，调光设备填 1–100；不填 = 保持原状
点「保存模式」落库。
7.4 预览效果：点新生成的金底 chip 图上立刻显示「目标态」——
- 状态 = 开：图上点变金色实心 + 4px 光晕
- 状态 = 关：图上点变半透灰（不显示光晕）
下方提示行：「正在预览模式「xxx」—— N 灯开，M 灯关。再点该模式或画布空白处退出。」预览不落库，随时切回「浏览」就消失。
7.5 绑定到键：见步骤 6.6 · 控制盒下方「绑定到模式…」下拉选这个模式 + 选键位/动作 + 点「绑定」。
mode_id 会被清零（也就是触发器没了，连线还在）。要彻底拆掉再手动去按键动作表删那一行。
步骤 8 · 导报价 · 发客户
8出 BOM → 报价 → 方案册 → 客户链接
目的：把数据变成可交付的文件：物料清单 / 报价单 / 方案册 / 合同 Word+PDF，再发给客户只读预览。
8.1 出 BOM（采购内部用）：方案详情页顶部「BOM」→ 进 /app/bom?scheme=<id>。按分类聚合、采购成本价、底部「采购总成本」。可「导出 CSV」。
8.2 出报价（给客户看）：方案详情页顶部「报价」→ 进 /app/quote?scheme=<id>。含设备小计、设计服务费(8%)、安装施工费(5%)、采购成本、设备毛利、合计。「导出 Word」「导出 PDF」一键拿。
8.3 出方案册 + 合同：回到方案详情页，顶部右侧「导出方案册」「导出合同」。每次导出 Word + PDF 共 6 个文件，自动归档到对象存储（页面下方「交付物归档」卡可看到/下载/删除）。
导出命名规范：<方案名>_<类型>_<方案编号>.<ext>，例：Rio.的智能方案_方案册_QLZ-20260815-002.pdf。
8.4 出水电交底图（给水电师傅 / 木工看）：列表行「水电」或详情页顶部「水电交底图」，进 /app/drawing?scheme=<id>。页面是四个页签，师傅要哪张就切哪张：
| 水电预留 | 各设备对强电 / 弱电 / 网络的预留要求，水电与硬装阶段提前预埋用——这是给师傅最重要的一张 |
|---|---|
| 网络布线 | 核心 / 路由 / AP / 网口的点位与数量汇总 |
| 开关面板 | 开关与插座类设备的面板类型清单 |
| 木作灯光 | 灯带 / 线性灯 / 射灯等需要在木工阶段留槽、留孔的灯光项 |
这三个产出页（BOM / 报价 / 水电交底图）顶部都有「返回设计」，随时回方案详情，不用点浏览器后退。
8.4.bis 户型图自身导出（点位数大的方案用）：进户型图页 /app/scheme/<id>/plan 后，顶部「导出 SVG」一键下载矢量户型图（点位 + 控制关系全在一张 SVG 里），可以直接给设计师归档或在 Illustrator 里继续美化。「米家配置清单」则按房间汇总米家网关 / 传感器 / 灯类设备的清单 HTML（含品牌型号），给到对接小米工程师用。
8.5 发客户链接：方案详情页「方案分享」卡选有效期（永久 / 7 天 / 30 天 / 90 天）、勾选「显示品牌 / 型号」（默认勾 = 给客户看产品细节；不勾 = 客户只看到类型和数量）→「生成分享链接」→ 点「复制」发给客户。
链接已经生成过之后，同一个按钮会变成「保存分享设置」——改有效期或显示项用它；不勾「重新生成」的话链接不会变，客户手里的旧链接继续有效。
客户点开是 /share/<token> 的只读页面：能看到方案/房间/设备/点位，不能改。每方案一条链接。
• 方案册：给客户看的图文册（封面 + 方案概览 + 房间与设备 + 控制图）
• 报价单：给客户的价目表（含费率和合计）
• 合同/服务协议：给客户签的协议（个人模式是「服务协议」口径，不是法务腔）
按钮速查表
新人最常问「那个按钮在哪」—— 把它贴墙上：
| 新建方案 | 方案列表页 右上角 + 新建方案 |
|---|---|
| 进方案详情 | 列表行 📝 设计 或点方案名 |
| 编辑方案 | 详情页 顶部 编辑方案 |
| 加房间 | 详情页「房间与设备分布」卡 顶部 输入框填名字（有预设下拉）→ + 房间 |
| 加设备 | 同卡 顶部表单：选房间 → 选类型 → 选设备 → 数量 → + 添加设备 |
| 删房间 | 房间卡 右上角 删除房间（红字，会连带删掉该房间下所有设备，有二次确认） |
| 删子系统 | 「系统配置」分组里 删除子系统 |
| 进户型图 | 详情页 顶部 户型图 |
| 看数字孪生 | 详情页 顶部 数字孪生（2.5D 等轴测，演示用，不改数据） |
| 上传户型图 | 户型图页 第一个卡 → 选择文件 → 上传户型图 |
| 标点位 | 右侧「标注设备」选设备+参数 → 左侧图面点位置 |
| 改点位类型 | 点位行 末列 设置 |
| 建控制关系 | 右侧「控制关系（控制图）」控制模式 → 选键/动作/线型 → 点开关 → 点灯 |
| 绑键到模式 | 控制盒 绑定到模式… 选模式 → 绑定 |
| 建灯光模式 | 右侧「灯光模式」+ 新建模式 → 命名 → 勾灯 → 保存模式 |
| 预览模式 | 模式 chip 上点一下；再点或点画布空白处退出 |
| 出 BOM | 详情页 顶部 BOM → 列表页 导出 CSV |
| 出报价 | 详情页 顶部 报价 → 导出Word / 导出PDF |
| 出方案册 / 合同 | 详情页 顶部 导出方案册 / 导出合同 |
| 生成分享链接 | 详情页「方案分享」卡 → 选有效期 → 生成分享链接 → 复制 |
| 改分享设置 | 已经生成过的方案，同一个按钮会变成 保存分享设置（不勾「重新生成」就不换链） |
| 出水电交底图 | 列表行 水电 或详情页顶部 水电交底图，内含四个页签：水电预留 / 网络布线 / 开关面板 / 木作灯光 |
| 从产出页回方案 | BOM / 报价 / 水电交底图 三个页的顶部都有 返回设计，一键回方案详情 |
| 删方案 | 列表行 删除（红字，admin/manager/designer/sales 可） |
新人踩过的坑（按发生频次排序）
- 顺序反了：没加设备就去标点位 → 选不到；没标点位就建控制关系 → 选不到；没标灯类点位就建模式 → 保存按钮置灰。回到 1→2→3→4→5→6→7 顺序。
- 方案面积 = 0：光晕完全不显示，以为功能坏了。回步骤 2 填面积。
- 重复套用模板：会叠加设备，不会幂等替换。想换模板先手动清。
- 「复制」按钮 = 编辑页：列表行「📋 复制」点了之后改完点保存，会 UPDATE 原方案不会新建。要复制请手动「+ 新建方案」+ 套用模板。
- 设备放进「方案元信息」：报价里看不到（元信息不参与造价）。移动到物理房间或系统配置下。
- 删方案/房间/点位都是不可逆的，无回收站，删之前先确认（前端的 confirm 弹窗是最后一道防线）。
- 导出的 DXF/DWG 不收：当前版本户型图只收图片，CAD 文件先转 PNG 再传。
- 导出文件被覆盖：同 (方案,类型,格式) 重复导出 → 覆盖。版本管理线下做。
- 只读账号点啥都「权限不足」：不报错页，只 flash 提示「只读账号无法执行该操作」。找管理员开权限。
- 模式名重了：保存时报数据库唯一键错误（前端会弹提示「保存失败」），换个名。
- 删模式后 line 还在：删模式只把引用此模式的 link 行
mode_id清零，连线行不删。要彻底拆掉去按键动作表删那一行。 - 跨图控制关系：控制关系是图级的（两端必须同图），模式是方案级的（可跨图）。想跨图触发场景就建模式 link。
常见问题
Q: 我是 sales（销售），能出方案吗？
能。sales 在方案设计模块的权限与 designer 一样，可以独立建方案、加房间、标点位、出报价。报价模板库（/app/quote-templates）仅 admin 可改；其他都能做。
Q: 选配向导生成的方案里有一些「待选设备」行，报价里看不到
这些行 product_id=0，BOM/报价都按 JOIN products 过滤会丢。要么在后台把它们换成设备库真实产品，要么删掉重新按客户需求选真实产品。
Q: 「设备毛利」显示为 0 或没出现
「设备毛利 = 设备售价小计 − 采购成本」。需设备库的产品都填了「采购价」（在「产品表单」最下面一栏），毛利才会显示。售价 × 数量 = 售价小计，采购价 × 数量 = 采购成本，毛利 = 售价小计 − 采购成本。
Q: 客户看不到分享链接
检查有效期（永久 / 7 / 30 / 90 天）有没有过期；URL 完整复制（包括 http://...）；客户在不同网络/地区时链接仍能访问（链接用的是公网地址）。
Q: 怎么让某个键一键关全屋？
建一个「全屋关灯」模式 → 在控制盒选好键/动作（一般是「长按」）→ 「绑定到模式…」下拉选「全屋关灯」→ 绑定。模式里把所有灯的状态设成「关」即可。
Q: 我把户型图传错了，能换吗？
当前版本没有「替换户型图」按钮。只能删除已标点位（点位会跟着图走）再传新图——但点位行不会自动恢复，需要重新标。建议传之前先确认图清晰、有尺寸。
Q: 这份文档哪一节跟实际对不上？
功能在迭代、UI 会变。如果你发现按钮文案变了、字段改了、或者有新的坑—— 告诉管理员去改这份文档。改完一行版本号自动往前推，链接永久不变。
给维护者：功能改了，怎么同步这份手册
原则：改了「方案设计」相关的界面，就必须动这份手册。别靠记性，靠下面这条命令。
- 改完代码，先跑自检：
python3 docs/guide/check_sync.py
它会扫 7 个模板里的真实按钮文案，跟手册比对，报三类问题：
· [缺失] 界面有、手册没写 —— 新人会找不到
· [失效] 手册写了、界面已经没了 —— 新人会对着空气点
· [可能过期] 模板比手册新 —— 提醒你确认改动是否影响手册 - 按报告改手册：新按钮补进「按钮速查表」，改了名字的就替换旧文案，新坑补进「新人踩过的坑」。
- 界面变化大时，重新截一张图替掉
docs/guide/shots/里对应的那张（文件名别改）。 - 一键发布：
sh .deploy/sync_guide.sh—— 它会先跑自检，通过才上传，然后改属主、逐条验证线上 200。 - 技术口径（路由 / 数据表 / 接口）另有一份：改
功能文档.md→python3 gen_docs.py→ 部署到/docs/。
新增页面时：把模板加进 docs/guide/check_sync.py 的 SCAN_PAGES，否则那个页面脱离监控。只有「取消 / 关闭 / 纯筛选」这类才加进 IGNORE，宁可手册多写一行。
这份手册由 全屋智能 · 管理平台 维护，地址永久不变：/guide/。
技术视角文档见 /docs/（仅管理员可见）；同步检查脚本：docs/guide/check_sync.py。