开发日记
按时间回看每个项目做了什么、踩了什么坑、做了哪些取舍。共 34 条记录。
2026-11-10
重跑导入不再把产品详情长图冲成封面(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 项 · 报价小计」——筛完最想知道的就是这个数。
2026-10-20
踩坑:跨库搬产品图不能按 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、响应体里扫不到进货价与供应商字段。
2026-10-10
构建排障两例:一行「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 项断言全绿。
2026-10-09
0.7.0 上线:产品图与建议零售价进生产
- 上线 0.7.0:385 张产品图入产品库,建议零售价三层来源覆盖 99%。
- 按工作流拆两笔提交(数据+产品图 / 零售价),以相对基线、同组文件的完整差异逐字节自检两笔合并等于改动前工作区。
- 数据上线独立成步:同步数据源、服务器跑幂等导入、单独同步图片,导入前先拍回滚备份。
- 上线时发现线上库多一个客户一个项目,再次印证生产库只能增量导入。
- 验收 4283 条 / 7 家供应商 / 385 张图 / 孤儿图 0;令牌取图 200 且为 webp、无令牌 401、不存在 404。
阶段变更的操作人:从手打文本框改成名册下拉
- 阶段变更「操作人」由自由文本改为名册下拉,候选从专门接口现取,新入职同事立即可选。
- 接口登录即可、不要求管理员;不复用账号管理接口,也不放进免登录公开元数据(姓名属内部信息)。
- 下拉下注明「留空则自动记为当前登录账号」。
- 用不落库方式验证三种情形:不填署当前、选人署所选、空串回落当前,全部通过。
项目类型可以自己加了:内置项与自定义项拼起来下发
- 项目类型支持自定义增删,其余字典保持只读。
- 下发为内置常量加自定义表拼接:内置恒排最前、顺序稳定,自定义追加在后。
- 接口挂在免登录公开路由(登录页渲染表单用),增删两个接口各自显式声明需管理员,不能靠挂载位置定权限。
- 字典值长度上限与项目表该列同宽,并去首尾空格,避免「智能照明 」另成一条分类。
- 删除时返回「有几个项目还在用」,项目存名字快照,删分类不动已有项目。
行业动向 + 竞品分析:机器批量写入,指纹去重
- 侧栏新增「行业动向」与「竞品分析」,均仅登录可见。
- 幂等键:动向为日期加公司加标题,不含摘要与来源,避免两家媒体同题重复入库;竞品为品牌加品类加产品加型号,不含价格,避免每次调价新增一行。
- 指纹认字面不认意思:改摘要算更新、改标题算新条目,已写进抓取提示词要求标题写死。
- 护栏:价格区间低大于高直接拒收;全屋整包与单品分开统计,某品牌均价从 ¥1,438 修正为 ¥892。
- 交付自包含每日抓取提示词加纯标准库推送脚本,交常开电脑每天跑一次。
派生金额不给编辑入口,但显示它的地方必须自带导航
- 反馈找不到设备清单小计的编辑入口;小计是数量乘报价单价实时算出,库里没有该字段。
- 界面误导:小计卡在首屏最上与只读指标同款,可编辑清单在下一屏且非默认页签,卡上无跳转。
- 定两条:派生金额继续不可直接编辑;显示该数的地方负责导航,整卡可聚焦回车跳页签并滚动到位,右上角常驻低干扰的「维护」。
- 空清单提示不再显示 ¥0,避免误读为已填;概览位(客户详情、看板卡片)不加编辑入口。
项目加施工工期:只存两个数,完工日现算
- 项目补开工日与施工天数,完工日不落库,由开工日加天数减 1 现算,避免存三个数出现两个真相。
- 加列走既有迁移清单,线上重启即生效,不需要单独导数据。
- 阶段流转:拖进施工中时显式给了按给的、已有值保留(误拖回不抹掉)、都没有才取当前时间。
- 看板卡片显示「10-07 · 3 天(10-09 完工)」。
- 16 项断言全过:0 天、1000 天、负数一律拒收;只填天数不给日期时完工日为空。
今日待办:工作台首屏 + 独立页,两个入口同一份计数
- 侧栏新增「今日待办」,可自加紧急事项并可选绑定项目。
- 待办不属于项目:绑定可选,删项目只解绑不删待办。
- 「今日」定义为未完成且期限不晚于今天,含未设期限,避免无限后拖。
- 工作台首屏面板支持回车添加、勾选、推迟到明天;独立页做分组、编辑、清空已完成;两处与侧栏角标取同一接口,计数一致。
- 逾期转红、紧急标橙;工作台为桌面布局,面板设最小宽度,移动端适配列为下一步。
建议零售价:厂商给的、官方的、我们推的,必须一眼分得开
- 需求:产品查询加建议零售价,厂商没提供则由系统推。
- 数据现状:库里约五分之一产品带厂商零售价,其余报价靠手感加价。
- 四层来源带角标区分:厂商零售价「厂」、官方定价「官」、采购价乘品类系数推算「估」、无采购价显示短横线。
- 系数取自库里五百多条采购价与零售价真实配对,按类目取中位数,1.07 至 2.9 倍、兜底 2.4;官方产品线只乘 1.1,展板样品不给建议价。
- 即时算不落库,避免成本改了建议价静默错位;覆盖 99%,三处先行规则挂出待核。
一条超长字段,能把整个页面打挂
- 现象:供应商列表页整页挂,产品库按价格排序也整页挂,看着像前端写坏,实为数据问题。
- 根因:SQLite 文本字段无长度上限,接口出参契约限 64 字,写入无感、查询才炸;一家 21 个品牌拼进「主营品类」达 80 多字。
- 修法三层:导入按上限截断并统计截断条数;上限值直接取自出参契约;冒烟测试加超长值断言,确保列表仍返回 200。
- 教训:数据侧超长会表现成前端崩溃,排查先拿一条真实数据过接口;此后导入前先跑字段长度体检。
解析「跑通了」不等于「解析对了」:三个静默错误
- 脚本一路打印成功、条数也对,但有三处静默错误,结果都看起来合理。
- ① 三张表被判无表头,19 条真产品没进:闸门要求表头含价格类词,默认词表缺「产品价格」,补入后解决。
- ② 插座凭空多出同价「单火」版:合并单元格使零火/单火两列读出同值;加闸「拆出版本与主价相同即不是两件货」,两表从 51+32 收敛到 35+25。
- ③ 分类被关键词抢走:床归成窗帘电机、中控屏归成音箱、音响线当成音箱,重排分类优先级修正。
- 教训:每次解析后必须回原表逐格核对,并看类目分布是否符合常识。
把「产品图」做成通用能力:385 张图随产品一起入库
- 第 7 家米家生态,表 50MB 出头,体积几乎全是内嵌产品图,要求图也一并入库。
- 抽图按锚点定位到行,宽高比 ≥2.5 判为页眉横幅剔除 28 张;透明通道先合成白底,否则压缩后发黑;同格多图只按内容去重。
- 51.6MB 原图压成 385 张 webp、2.9MB;新建图片表启动时自动建,与产品一对一,产品图不进幂等键。
- 取图接口要求登录,前端不能直写图片地址,须取二进制渲染并及时释放,否则翻几千条会攒几百兆内存。
- 该家共 371 条,米家生态与小米官方产品各成一块。
新增门禁安防品类:参数全塞在一个格子里
- 第 6 家做门禁,43 条,是产品库首个门禁安防品类,表头干净,难点在描述格。
- 十来个参数塞一格,键值换行、空格分隔、一半键不带冒号三种写法混用;描述解析器拆成结构化属性加归一化原文,拆不出原样保留不硬猜。
- 新脏数据:表尾页脚费用行(安装费/快递费/设备总计)有名无型号无价,原闸门拦不住;「设备总计」行因合并单元格读到「不含税运」,看着像有型号。改为按名称前缀拦。
- 一款支架三个型号在源表里型号、名称、描述完全相同只有价格不同,挂出等确认,不自己编。
价格表是 PDF 也能读:把矢量表格线还原成网格
- 首个 PDF 报价表:10 页带表格线与产品图,用矢量表格线还原网格,落入与 Excel 侧相同结构,导入代码零改动。
- 补系列前缀必须隔空格,否则「A6」加「16A插座」会拼出 A616A插座。
- 列宽折行只在中文与中文之间掐空格,保留中英文之间空格,以区分「M3 一开」与「M3一开」。
- 一格两价拆两条;两列材质是互补非主备(70 行只填前者、27 行只填后者、50 行都填),也拆两条。
- 147 个数据行拆成 203 条,全部有价。
一家渠道商 = 21 个品牌、11 张子表:第 5 类畸形表也拿下了
- 渠道商汇总表:一家 21 个品牌、11 张子表,列名各表自定,3 张表内分多段,1 张整表无表头。
- 引擎补按子表生效的配置:子表列映射、无表头直取列号、段内重算列号、子表默认品牌、价格词表按表设定。
- 品牌三级兜底(行内品牌列 → 子表默认 → 命令行),含数字或过长的品牌名一律回落默认。
- 结果 370 条全有价、覆盖 21 个品牌,全量回表逐格核对 370/370 一致。
- 抓出两个真问题:千分位价格被读成 1、供应商页因字段超长整页挂;第一家 723 条基线复跑一致。
把「导价格表」沉淀成可复用的流程:引擎通用、配置专用
- 把导价格表沉淀为「引擎通用、配置专用」:每家供应商一份配置(列名别名、子表列映射、分类与品牌规则、计价单位)。
- 脚本只做体检与解析,体检先跑,输出行列数、合并区、表头段数、记录数、有价数并自动告警。
- 留回归基线:第一家表重跑输出必须逐条完全一致,新特性先过基线,防「为 A 家加的功能改坏 B 家」。
- 已验证单一供应商表、渠道商汇总表、PDF 报价表三种形态,每次只加一份配置和一个钩子,前三家结果均可复现。
同一款产品被多家供应:不归并,按「供应商 × 型号」各存一行
- 结论:同一款产品被多家供应时不归并,按「供应商 × 型号」各存一行。
- 实测两家供应商品牌完全不相交,当前跨供应商重复为 0 组。
- 只按品牌 + 型号去重,光一家内部就误并 88 组:型号列笼统,一串名字下塞着 6 个不同功率的价。
- 同一通用件(200W 电源)一家内部 4 个价、差 60%;漏并只是多几行,误并就是报价报错。
- 扩展路径:只读的跨供应商比价视图,查询时聚类不落库,验证后再固化标准品层。
产品查询与供应商两个板块:从供应商价格表到可检索的产品库
- 三段流水线:供应商价格表解析成结构化数据源,幂等导入产品库,再由接口供查询页,换供应商只改第一步。
- 解析处理合并单元格、多段表头、整行标题、一格多配置价等畸形表。
- 导入按「来源表 + 行号」幂等 upsert,重复跑不产生重复行;不带清理参数时人工补录的产品保留。
- 查询一次返回结果、价格统计与筛选项,三者同源,筛完统计跟着收敛。
- 首批入库 723 条、4 个类目;采购底价不进公开展厅,挂在登录路由下;规格结构化存储(搜 24V 能命中)。
定名「悦居智能 CRM」:产品名带上公司名,并与业务描述区分开
- 产品名从「智能家居 CRM」定为「悦居智能 CRM」,加上公司名,一眼看出是谁家的系统。
- 三层命名有意区分:产品名悦居智能 CRM、业务领域智能家居、对外展厅智能家居案例展厅。
- 展厅是否挂公司名不在本次范围,属对外业务品牌承诺,需单独决策。
- 落地 11 个文件 12 处(README、接口文档标题、/health、页面 title、侧栏、登录页大标题),英文标识与前缀不动。
- 重新构建部署后从公网逐页核对,均为新名且控制台无报错。
部署脚本用 rsync --delete,把线上的启动脚本删了
- 现象:一次例行部署后站点直接 502。
- 根因:rsync --delete 全量同步把线上手工放置、未进仓库的启动脚本删掉,进程管理器重启找不到入口。
- 脚本最后一步打印「部署完成」,健康检查拿到 502 仍照常打印成功。
- 修法:启动脚本纳入版本库;健康检查改硬判据,返回内容必须含 ok,否则非零码退出并提示看日志。
- 结论:全量同步与服务器手工文件天生冲突;打印成功不等于真成功。
新增「行业调研」:把行情与价格变成一份能查的底稿
- 新增「行业调研」,首个主题智能灯具市场:17 章节、67 条型号价格记录,覆盖品牌格局、价格分档、成本结构、合规与采购报价建议。
- 数据独立种子文件、幂等写入,已存在主题默认不覆盖,需显式 --reset 才重灌且只清这一个主题。
- 可见性:读对全员开放、写仅管理员,避免同一条价格出现两个版本。
- 价格有出处、有数据日期、有口径说明,「这个价是什么时候的」能直接答。
项目改名:去掉错字,并简化到「智能家居 CRM」
- 原名「智能家具项目与客户管理平台」中「家具」为错字,且名字太长、各处缩写不统一。
- 统一为「智能家居 CRM」。
- 有意不动两处:对外展厅仍叫「智能家居案例展厅」;英文标识与配置项前缀保持原样,避免为改显示名牵出部署改动。
- 外部平台上的项目名一并同步,避免改名漏在客户先看到的地方。
正式上线:内部客户与项目管理平台投入使用(v0.1.0)
- 立项到上线历时 2 天,已按生产标准部署到自有域名并投入使用(v0.1.0)。
- 能力:客户加项目全生命周期九阶段可旁路流失;三级可见性;经营统计 KPI/年度对比/月度趋势/成本构成/CSV 导出;智能灯具价格库。
- 上线前收口:全站 HTTPS 自动续期、关闭 /docs 与 /openapi.json、应用端口只监听本机、未登录业务接口返回 401。
- 前端构建产物由后端一并吐出,线上只有一个进程。
- 真实浏览器从公网走完整流程均正常、控制台无报错;库内为演示数据,正式录入前需重建管理员账号。
2026-10-08
自动断言也可能是假断言:用 0 验证 0
- 断言「在谈项目金额合计等于 0」恒成立,实为验证 0 == 0,实现写错也会通过。
- 改为比对接口真实返回的「在谈金额」字段才有意义。
- 截图脚本以 URL 是否以 /dashboard 结尾判登录成功,而登录失败跳 /login?redirect=/dashboard 也命中,密码错误被静默当成功。
- 改为严格比对完整地址,并额外等一个仅登录后存在的元素。
- 结论:断言先问「实现写错时它会不会失败」,会失败的才叫断言。
公开页用白名单挑字段,不用黑名单删字段
- 落地三级可见性:公开免登录、成员(客户资料/方案/售价)、管理员(成本/其他费用/利润)。
- 公开页不复用内部对象删字段,单独定义模型逐字段挑选;黑名单的弱点是新增字段会自动上公网,白名单最坏只是忘了显示。
- 对外标题用独立字段不回退项目名;不显示内部阶段名,只给筹备中/施工中/已交付;附件对外重命名。
- 成本字段读写双向拦截,只裁剪输出可被改写后反推原值。
折线图看着挺正常,数据点却全飘在顶部
- 现象:月度趋势折线峰谷正确,但代表各月的圆点全落在图表顶部。
- 根因:折线用 SVG、数据点用 HTML 绝对定位,SVG 的 y 轴向下、CSS 的 bottom 向上,整条曲线被垂直翻转。
- 修法:bottom = 100 − (y / 高度) × 100。
- 另坑:SVG 呈现属性不解析 CSS 变量,stroke 写 var(--brand) 会静默失效,必须用 :style 绑定。
- 结论:跨两套渲染体系拼图形,坐标方向与颜色解析规则都要各验一遍。
还没签约的项目,被算成了「亏损 4.9 万」
- 现象:在谈项目的明细行显示合同额 ¥0、利润 ¥-49,173 且标红,看着像已经亏了。
- 根因:统一公式「合同额 − 总成本」只对已成交项目成立,代码漏了这个前提。
- 修法:仅已成交算利润,未签约的利润与利润率留空显示短横线,成本照常显示,表头注明未签约项目不计利润。
- 补一条断言专守此回归。
- 教训:同一公式在汇总与逐行两种用法下前提可能不同,汇总时全是成交项目所以看不出来。
统计口径先定死,再写代码
- 先写 ADR 钉死口径,再由一个模块统一算钱,详情页与统计页共用同一套算法。
- 业绩按签约时间归属,不按建档时间,避免「去年谈、今年签」的报表慢一拍。
- 利润 = 合同额 −(设备成本 + 其他费用);只减设备成本得到的是毛差,会系统性虚高。
- 成本按项目归集不分摊,历史年份利润随后续售后费用录入而变小,属预期行为且界面已说明。
- 未成交项目不计业绩,按在谈/流失/签约后流失单列;收入为 0 时利润率返回「算不出来」而非 0;口径随接口下发。