核心亮点
- 一个客户一个项目:线索到售后一条主线推进,看板上拖拽即可过阶段
- 三级可见性:内部看成本与利润,对外只看脱敏案例 —— 公开页用白名单挑字段,将来加新字段最坏是不显示,而不是悄悄泄露
- 统计口径先定死再写代码:利润 = 合同额 −(设备成本 + 其他费用),口径随接口下发到界面,两边不会各说各话
- 供应商产品底价库:Excel / PDF / 在线表格的价格表都能入库,按类目 / 品牌 / 规格多维检索 —— 报价不用再翻聊天记录找历史价
- 建议零售价分三层来源(厂商给的 / 官方定价 / 按品类系数推算),界面上用角标分开 —— 推算值不会冒充供应商承诺
- 数据缺失宁可显性告警:宁可标出「这几条没有价 / 这个字段超长」,也不给一个漂亮的错数字
技术栈
产品界面
开发成果 31/34
- 领域模型与阶段状态机(含任意阶段旁路流失)
- FastAPI + SQLite 后端与 13 个路由模块
- Web 端界面:工作台 / 项目看板 / 项目详情
- 登录认证与账号管理 CLI(PBKDF2 + JWT)
- 三级可见性与公开页白名单脱敏
- 公开展厅页(免登录,桌面 + 移动端)
- 成本口径补齐:项目其他费用
- 经营统计看板(年度 / 趋势 / 维度 / 成本构成 / CSV 导出)
- 自动化测试 154 项断言全绿
- 代码入库(私有仓库)
- ★ 部署上线:crm.filebreeze.cn(Nginx + HTTPS,公网关闭接口文档)
- 行业调研模块:智能灯具市场价格与渠道情报
- 接入真实业务数据试运行(含重建管理员账号)
- 运维 · 今日待办(工作台首屏面板 + 独立页)
- 运维 · 项目施工工期(开工日 / 天数 / 完工日现算)
- 运维 · 行业动向 + 竞品分析 + 每日自动更新提示词
- 运维 · 项目类型可自维护(内置 + 自定义,新增「智能照明」)
- 运维 · 阶段变更操作人改为名册下拉
- 运维 · 产品查询 + 供应商两板块(价格表 → 产品库三段式流水线)
- 运维 · 产品底价库:7 家供应商 / 4283 条,含 703 张产品图
- 运维 · 建议零售价(厂商 / 官方 / 推算三层来源,覆盖 99%)
- 运维 · 报价 AI 自动化(客户需求 → 产品库 → 加价 → 报价单)
- 运维 · 收款 / 应收与现金流口径
- ★ 移动端 Android 首版:现场打卡(签到 / 收工双时点)+ 施工拍照 + 离线优先同步队列,release APK 已出
- ★ 售后记录独立成表 + 看板「售后」跨阶段汇总列;已交付后不再催跟进(ADR-015/016)
- 运维 · 利润双口径:现金 / 经济,自有安装按影子人工计价
- ★ 员工管理 + 项目派工:员工即账号,派工与打卡分两本账(ADR-017)
- ★ 官网产品中心:只读白名单接口 + 逐条标记上官网 200 条 + 703 张产品图上线(ADR-018)
- 运维 · 安全:修掉静态回退路径穿越(P0)+ 不下发定价倍率
- 运维 · 采购记录 / 库存台账 / 出库三用途(四表,数量永远由流水求和,ADR-021~025)
- 运维 · 产品详情长图:封面与详情分两组,官网详情页整宽可看(0.12.5)
- ★ 人工成本按人天记账 + 设备清单按供应商 / 品牌 / 类型筛选(ADR-026)
- ★ 员工薪资两制:日薪 / 月薪(按月折算日单价进项目成本,ADR-027)
- 运维 · 移动端 iOS 与小程序端(复用同一套后端 API)
项目简介
面向全屋智能 / 单品加装 / 旧房改造业务的经营与项目管理平台。
核心主线:一个客户 = 一个项目,项目沿阶段推进 —— 线索 → 勘察 → 方案设计 → 报价 → 谈判 → 签约 → 施工中 → 已交付 → 售后,任意阶段可旁路到「已流失」(须填原因)。
三级可见性:公开(案例展厅,免登录,白名单脱敏)/ 成员(客户资料、方案与售价)/ 管理员(成本、其他费用、利润)。
产品与报价:供应商产品底价库 —— 供应商给的价格表(Excel / PDF / 在线表格)解析入库,按「供应商 × 型号」各存一行、不做同款归并(同一款产品有几家能供就有几行,报价时能看到出处与差异);产品查询支持类目 / 品牌 / 规格 / 价格区间多维筛选,规格是结构化存的(搜「24V」能命中型号没写、规格写了的产品);建议零售价分三层来源(厂商给的 / 官方定价 / 按品类系数推算),界面上用角标分开 —— 推算值不会冒充供应商承诺;每款产品可逐条标记「上官网」,经一组只读白名单接口对外输出(官网 / 小程序共用这一份数据,不出进货价与供应商)。
利润:现金口径与经济口径两本账 —— 现金利润是银行里真进出的钱,经济利润还要减掉「自有安装的影子人工」,避免把老板自己的劳动当成利润。
模块:工作台(今日待办 + 今日待跟进 + 久未联系预警)/ 项目看板(按阶段分列、拖拽推进,售后为跨阶段汇总列)/ 客户主数据 / 项目详情(跟进时间线、售后记录、设备清单、报价多版本、阶段流转、施工工期、施工人员派工、附件、对外公开设置)/ 经营统计 / 产品查询 / 供应商 / 行业调研 / 行业动向 / 竞品分析 / 员工管理 / 公开展厅。
开发历程 34 条
重跑导入不再把产品详情长图冲成封面(0.12.6)
产品图片分「封面」与「详情长图」两组后,重跑一次导入就会把长图全冲成封面:导入对图片是「整组重建」,而分组标记通常只存在于数据库里(长图是事后手工标的,数据源 JSON 里没有这个字段)。后果是图片文件还在,但对外接口的长图分组空了、官网详情页整宽长图静默消失,而导入日志只显示「图片 N 张」。
修法:重建前先把同名旧记录的分组标记抄下来,优先级 = 数据源明写 > 同名旧记录 > 封面;另写一个校验脚本,在临时库上验证「重跑一次不退化」。
这类 bug 的共同点是:写的时候无感,读到才发现不对。同一批修掉的还有产品规格字段超长——导入时不管、列表接口直接 500。
发版前多了步 md5 对拍,救回 490 条产品规格
发版前把服务器上前后端每个文件的 md5 算成清单,跟本地逐一比对——而不是直接 rsync --delete。对出两个文件只存在于服务器、从未进过 Git:一份供应商价格表数据源(已补全过规格)、一张规格标签对照表(多 11 个键);旁边还躺着两个 .bak 和四个一次性修复脚本。
直接部署会怎样:用本地版覆盖后,490 条产品的结构化规格(显指 / 色温 / 尺寸 / 灯珠)静默退回旧版,官网规格区大面积空掉;65 条产品的「配件」标签全没;11 个标签消失、界面直接显示英文键名。而部署日志、健康检查、首页 200 全都会显示成功。
处置:线上版本取回入库(逐条确认仅线上多 490 条规格、少 9 条表格说明行);四个脚本原样存档并标「路径写死指向线上库,不要跑」,它们恰好解释了那批规格怎么补出来的。
两条教训:① 数据源与标签白名单只能改仓库,直接改线上会在下次部署时静默还原;② rsync --delete 前一步固定是 md5 对拍,不是可选项——健康检查只能告诉你「进程活着」,告诉不了你「数据还在」。
人工改按人天记账,员工薪资分「日薪 / 月薪」两制(0.13.2 上线)
项目费用原来只能记一个金额:「人工 5431」这样一行。能算进利润,但答不了三个每天都会被问的问题——这单用了几个人、干了几天、一天多少钱。
改成一人一条,金额 = 人数 × 天数 × 日单价:
- 金额由服务端算,前端只做预览。手改金额、复制旧条目、浏览器浮点误差,最后账都对不上。
- 缺项不猜:天数或单价只填了一个就拒收,不按 1 倍补齐——那会造出一个看着合理的错数。
- 「按派工带入人工」做成显式且幂等的动作,派工不自动写费用:自动写的话,每改一次派工就多加一条,一单下来人工翻三倍还没人发现。
同时补上月薪制:施工队按天议价,内勤 / 设计 / 项目经理拿月薪,两种人都要能算进项目。月薪不另立一套成本算法,只在出口折成日单价(默认按 21.75 天,界面给 21.75 / 26 / 30 三档)。同一个 8000 元月薪,按 21.75 天是 367.82/天、按 26 天是 307.69/天,差 20% —— 这是公司的会计口径,不该由代码拍定。
两个细节值得记:
1. 折算结果不落库,每次现算。写回日单价字段的话,一调薪就会出现「档案一个数、成本另一个数」,而且没有字段能证明哪个对。
2. 切换计薪方式时不清另一套数字:日薪改月薪、再改回日薪,原来的数值都还在,不用重输。
顺手把设备清单加了供应商 / 品牌 / 类型筛选,筛完直接显示「筛出 N 项 · 报价小计」——筛完最想知道的就是这个数。
踩坑:跨库搬产品图不能按 id 搬,要按「供应商+型号+名称」反查
跨库搬产品图时把
product_images.product_id直接搬过去,会把图挂到隔壁产品上。- 本地库与线上库的
products.id并不一一对应:同一批供应商在不同时间导入,id 段整体偏移(这次差 7 条),4283 条里有 3190 条的 id 对不上。 - 正确做法:按「供应商 + 型号 + 名称」的交集反查目标库的行;同名多行按产品 id 顺序一一配对。只按名称会命中重复,只按型号会命中同款四色,交集才唯一。
- 动手前先跑映射预演,并核对一件事:
原有覆盖是否被新覆盖完全包含。这次原有覆盖 369 个产品、新覆盖 668 个、原有而新缺失 0 个,才落库。 - 第二个坑:
product_images.created_at是 NOT NULL 且没有默认值,手写 INSERT 必须显式补时间戳 —— 否则抛 IntegrityError,而delete已经在同一事务里执行过,看着很像「数据已经没了」(实际会回滚)。 - 第三个坑:先传了图片文件、后补数据库记录,中间跑了一次审查脚本,被判成「233 条没有产品图」—— 审查脚本查的是
product_images表,不是文件系统。文件和记录要一起到位再跑审查。
- 本地库与线上库的
0.10.0 上线:售后记录、利润双口径、员工派工、官网产品中心
本版按工作流拆成 6 个提交推送,每块都带一份 ADR / 模块说明:
- 售后记录独立成表(ADR-015):交付之后客户回来的事(报修 / 补装 / 回访)不再塞进「跟进记录」。看板「售后」列改成跨阶段汇总列 —— 阶段在售后 ∪ 有未完成记录,所以同一张卡片可能同时出现在「已交付」和「售后」。这是刻意的:一列回答「走到哪一步」,另一列回答「还有谁在等我们」。
- 交付后不再催跟进(ADR-016):已交付 / 售后 / 已流失不再挂红色「未跟进」;但用户显式约的「待跟进」照旧保留。原则是「派生告警抑制,显式承诺保留」。
- 利润给两个口径:现金利润(银行里真进出的钱)与经济利润(再扣掉自有安装的影子人工,设备款 ×15%)。只报一个,必然有「看着很赚、其实在给自己打工」的单子被当成好生意。
- 员工管理 + 项目派工(ADR-017):员工就是账号(补工种与电话),不另立名册;派工表挂账号真外键。派工是计划、打卡是实际 —— 两本账才看得出「安排三个人只来了两个」。
- 官网产品中心(ADR-018):产品库逐条标记「上官网」(370 条审出 200 条),对外开一组只读白名单接口(列表 / 按 id 批量 / 详情 / 图片)。只出厂商建议零售价,不出进货价、不出供应商、不出规格原文里的内部备注;没有价就显示「询价」,不拿成本乘系数编价。CORS 单独一组,只对公开接口放开。
- 安全:修掉静态回退的路径穿越(P0,实测可读到签名密钥与整个数据库),定价倍率不再随产品接口下发(那是定价策略本身)。
- 线上数据:产品图 703 张 / 8.3MB 同步上线,200 条标记落库。公开接口实测:200 条、分页 100/页、未上架与不存在的 id 一律 404、响应体里扫不到进货价与供应商字段。
构建排障两例:一行「25.0.2」和它掩盖的错误;以及构建成功≠产物正确
- flutter build apk 1 秒失败只输出「25.0.2」:Flutter 优先用 Studio 自带 JDK 25,Gradle 8.14 不认;改 --jdk-dir 到 17.0.7。
- permission_handler_android 自带 AGP 9.0.1、硬编码 compileSdk 37,与 Gradle 8.14/36 代差;已摘掉。
- 构建成功不等于产物正确:图标脚本按自身目录拼路径,5 张图标写错位置,只有 API 24/25 真机暴露;签名缺配置时静默回退 debug。
移动端 Android 首版落地:现场打卡(签到 / 收工双时点)+ 施工拍照 + 离线优先同步
- Android 首版可装可用:签到 → 施工 → 拍照 → 收工,自动算时长。
- 离线优先:手机时间为权威,服务端另存字段核对;每动作带 client_uuid 只落一条;先落盘再提示成功。
- 队列由本地未同步记录反推,负数 id 区分;开工→收工依赖持久化的 id 映射。
- 失败三分类:5xx/超时停下等、401 不碰队列、其余 4xx 进失败箱不删。
- release apk 54.9MB、签名 CN=Yueju Intelligent 非 debug;队列 14 项、后端 51 项断言全绿。
0.7.0 上线:产品图与建议零售价进生产
- 上线 0.7.0:385 张产品图入产品库,建议零售价三层来源覆盖 99%。
- 按工作流拆两笔提交(数据+产品图 / 零售价),以相对基线、同组文件的完整差异逐字节自检两笔合并等于改动前工作区。
- 数据上线独立成步:同步数据源、服务器跑幂等导入、单独同步图片,导入前先拍回滚备份。
- 上线时发现线上库多一个客户一个项目,再次印证生产库只能增量导入。
- 验收 4283 条 / 7 家供应商 / 385 张图 / 孤儿图 0;令牌取图 200 且为 webp、无令牌 401、不存在 404。
周期
2026-10-08 → 未定





