tms-erp-web/.workbuddy/memory/2026-10-14.md

2026-10-14

运单管理：草稿行「查看」改为与其它状态一致的「详情」

• 现象：/business/waybill-manage 列表操作列，草稿行显示「查看」→ 走 avue 自带 $refs.crud.rowView() 表单弹窗；其它状态显示「详情」→ openDetail() 跳独立详情页 /business/waybill-manage/detail?id=x（新标签「运单管理详情」）。同一列两种弹窗形态。
• 根因：waybill-manage-page.vue 的 showDetailButton(row) 显式 return status !== 'draft'，把草稿排除在详情按钮外，于是落到 #menu 里 !showDetailButton(row) 的「查看」分支。
• 修法：showDetailButton() 去掉草稿判断，仅保留 config.detailButton + _view 权限判断；「查看」分支保留，仅在 detailButton:false 时兜底。
• 备注：business-crud-page.vue:7043、transport-plan-page.vue:4111 有同款 status !== 'draft' 逻辑（运输计划另有 showViewButton）；两个 option 文件里的 detailButtonIgnoreDraftStatus 目前是死配置，组件未读取。

收付款管理模块：列表页右上角统一为 4 键工具组（最终方案 = 改 avue-crud）

• 现象：付款管理页右上角只有 1 个刷新按钮，与其它模块不一致；参考模块的 4 键工具组其实是 avue-crud 内置头部，不是可引用的公共组件。
• 方案演进：
  1. 过渡方案（已落地 7 页）：手写页引入标准件 src/components/table-header-tools/main.vue，改法为搜索区 v-if="searchVisible"、el-table 加 :size="tableSize"、列 v-for="column in visibleColumns"、data 加 searchVisible/tableSize/visibleColumnKeys；汇票两页表格在子组件，子组件透传 update:searchVisible + refresh。已接入 invoice-application.vue、invoice-receipt.vue、receipt-flow.vue、receipt-claim-record.vue、bill-ledger.vue+bill-ledger-table.vue、bill-payment.vue+bill-payment-table.vue。 但用户实测反馈：第 2 键（列设置）与第 4 键（表格尺寸）效果仍与参考模块不同 —— 参考模块第 2 键是 el-drawer 列设置抽屉（列名/隐藏/冻结/过滤/排序），第 4 键是「表格 ↔ 卡片」视图切换，两者都嵌在 avue 内部，无法脱离 avue-crud 复用。
  2. 最终方案（用户选定，先做样板）：列表页改写成 <avue-crud>，4 键 = 刷新 / 列显隐抽屉 / 搜索显隐 / 网格切换，与其它模块 100% 一致。
• 样板：src/views/payment/payment-application.vue + src/option/payment/paymentApplication.js（paymentApplicationOption() 工厂）。
  • 搜索项与表格列 label 不一致的（表格列「收款方」vs 搜索项「客户名称」）用 searchProp 映射；属搜索专用列用 searchOnlyColumn() 统一生成（hide + showColumn:false + add/edit/viewDisplay:false）。
  • ⚠️ avue 的 searchOrder 是降序（header-search2.js：(b.searchOrder||0)-(a.searchOrder||0)），值越大越靠前 —— 首次做反了，9 个搜索项 score 全部反转。
  • ⚠️ column 数组顺序即表格列顺序，搜索项夹在中间会把该列挤到表格前面（deptName 踩过），搜索专用列必须紧跟在同位置或用 hide 隔离。
  • on-load 在 created / currentChange / sizeChange 都会触发（table-page2.js），因此 currentChange/sizeChange 只改 page、不要再调 onLoad；onLoad(page) 也不能把 page 里的 total/pageSizes spread 进查询参数。
• 顺带加固：table-header-tools 加 deactivated() 关闭列设置弹窗（keep-alive 切页防 Teleport 弹窗残留）；清理 invoice-application / invoice-receipt 里失效的 __toolbar-right 样式规则。
• 验证：项目根建临时 html 挂真组件 + app.use(Avue)，agent-browser 实测 —— 4 个按钮均渲染图标、刷新触发、搜索区切换、表格尺寸 default→large、列设置弹窗勾选双向生效；avue-crud 样板另测：4 键数量=4、默认 4 项搜索 + 展开 9 项、18 列表格顺序与原页一致、列显隐抽屉表头 5 列 18 行、网格按钮切出卡片视图；临时文件用完即删。
• 踩坑：el-icon-* 字符串图标靠 Avue 的全局映射，验证页不装 Avue 时 4 个按钮是空圆（差点误判）。
• 待办：用户确认样板效果后，把其余 6 页（invoice-application / invoice-receipt / receipt-flow / receipt-claim-record / bill-ledger / bill-payment）也改成 avue-crud，并回退其 table-header-tools 改动。

正式结算单表单：结算明细区按钮/筛选行对齐预结算单

• 现象：formal-settlement-editor.vue 的「结算明细」区把 导出/选择结算明细 塞在筛选表单的 actions 里（grid-column:1/-1 换行右对齐，出现两个蓝实心），与 pre-settlement-editor.vue 不一致（后者把这两个按钮放 <section-card #extra>，筛选项与查询/重置同行）。
• 改法（只动 formal 一个文件，72+/17-）：
  1. 模板 section-card#extra 加 导出（v-if="hasPermission('formal_settlement_export')" type=primary plain）+ 选择结算明细（v-if="editable" type=primary plain），与「收起明细」并列；actions 里只留 查询/重置。
  2. el-form 去掉 inline、label-width 88px→auto，4 个输入补 placeholder="请输入"。
  3. 样式 grid-template-columns: repeat(4, minmax(0,1fr)) auto + align-items:center；actions 去掉 grid-column:1/-1 改 width:auto;margin-left:0;white-space:nowrap;justify-self:end；媒体查询 ≤1200px 同步补 auto 列。
  4. 补 hasPermission：...mapGetters(['permission','userInfo']) + isAdmin（isAdministrator from @/utils/auth）+ methods hasPermission(code){ return this.isAdmin || this.validData(this.permission?.[code], false) }（validData 是项目全局属性，main.js 未显式挂载但全站通用）。
• ⚠️ 关键坑：文件末尾 .formal-editor :deep(.el-form-item){margin-bottom:24px} 与筛选区 :deep(.el-form-item){margin-bottom:0} 特异性相同，靠源序决定胜负 → 覆盖规则必须写在文件尾部（@media 之前）。pre 用的也是同索引结构。
• 验证：agent-browser + mock 注入实测 —— grid 列 188.25×4 + 132、5 个 form-item 同一行 top 相同、form-item margin-bottom=0；正式单与预结算单同视口截图逐像素一致。

「变更运输路线」弹窗 · 变更记录列表：变更前/后地址分行展示

• 需求：变更内容原为单行 YD-xxx：发货地 A → B；到货地 C → D（多条以 ； 拼接），地址太长挤成一坨，要求「变更前地址 / 变更后地址」换行。
• 落地：新增 src/utils/route-change.js 导出 formatRouteChangeContent(content, emptyText='-') —— 仅展示层格式化（不动 taskInfoJson 里已存的 content，历史数据同样生效）：\r\n 归一 → ； 转 \n → → 转 →\n（箭头留上一行行尾）→ 压缩空行；空值返回 -。
• 接入 3 处同一弹窗（都在 methods 里以 ES6 简写挂载 formatRouteChangeContent，与 formatContractOptionLabel 同款）：
  • views/business/loading-manage.vue（表格列 record-content）
  • views/business/components/waybill-manage-page.vue
  • views/business/components/business-crud-page.vue
• ⚠️ 关键坑：white-space: pre-wrap 下模板里插值前后的换行+缩进空白会被渲染出来（内容前面凭空多一行缩进）。所以要么把 >{{ ... }}</div> 写成紧贴一行（loading-manage），要么改用 v-text="formatRouteChangeContent(row.content)" 多行写法（另两处）——文本节点不存在才安全。CSS 里 white-space:normal 需改 pre-wrap（loading-manage 原为 normal），另两处补 overflow-wrap:anywhere; word-break:break-word; line-height:22px。
• 效果：YD-20260904-0022：发货地 广西…公司 → / 换行 / 广东省…西瓜洲 / 到货地 山东…公司 → / 山东省…公司。
• 验证：node 直跑函数（多条 / 单条 / 路线顺序 / 空值）输出正确；dev localhost:2889 三个 .vue 与 scoped style 块均 200，编译产物各含 3 处 formatRouteChangeContent。
• 未做（如需再说）：存储格式与导出 Excel 仍是单行文本；vehicle/transport-change-record.vue 的 changeContent 是人工填写的自由文本，未改。

发货模板"选择常用地址"改图标（对齐运输计划）

• 需求：/business/shipping-template/form 收发货信息行，把文字「选择」按钮改成运输计划同款图标方式。
• 改动（src/views/business/components/shipping-template-page.vue）：
  1. import { Location, OfficeBuilding } from '@element-plus/icons-vue'，并把 OfficeBuilding 加进 data()；
  2. departure/arrival 两个 form 插槽里，把 <el-tooltip><el-button ...>选择</el-button></el-tooltip> 从行尾移到第二个地址输入框之后，改成 :icon="OfficeBuilding" + link 图标按钮（class shipping-template-page__address-pick-btn）；
  3. suffix 的 <el-icon> 补 class shipping-template-page__map-suffix（cursor/18px/#909399/hover #409eff），与运输计划同名同款；
  4. .shipping-template-page__route-row grid 第 3 列插入 40px 图标列（原末尾的 auto），并把 __address-pick-btn .el-icon { font-size: 22px } 写进该行容器内。
• 关键坑（差点误判成 bug）：Element Plus 图标两种用法机制不同 ——
  • 标签形式 <Location /> 靠 main.js 里 app.component(key, ...) 全局注册解析，与 data() 无关；
  • 表达式形式 :icon="OfficeBuilding" 编译成 _ctx.OfficeBuilding，必须把组件对象放进 data()（放 components 注册里模板取不到，会静默渲染不出图标）。 验证页漏了全局注册，曾误判 <Location /> 不渲染。
• 验证：临时验证页（项目根 html + 真 .vue，走 Vite + 真 element-plus + 全局图标注册）实测：地址框内 Location 18px、按钮 40px 内 svg 22px 居中、7 列 184/368/40/48/184/64/184 铺满 1120px；截图视觉与运输计划一致。用完已删临时文件。
• dev 自检：shipping-template-page.vue 与 scoped style 均 200。

多联总单：调度页顶部路线节点 / 详情页路线图 —— 省市区按「市 区县」分段展示

• 现象：/business/master-order?mode=dispatch&id=xxx 顶部 route-overview 的起/终节点直接绑定 route.departureName/arrivalName 原始值 → 显示成「上海市浦东新区」「广西壮族自治区南宁市邕宁区」挤成一坨（同页段1~段3 的表头早已是「上海市 浦东新区 → 上海市 静安区」，用户截图圈出顶部这行说"怎么还没改"）。
• 根因：顶部节点是唯一没走格式化方法的绑定（段头走 dispatchLocationName，详情页走 segmentLocationName），不是格式化逻辑有问题。
• 落地：新增 src/utils/region-address.js 导出 formatRegionAddress(value) + splitRegionTokens(value)（按行政区划后缀切分，州+市、县+区 连写特例合并；整串都是行政区划才重排，站点名「南宁站」「广州南站」和含街道门牌的详细地址原样返回）→「市 区县」的空格展示，省/自治区不重复（与全站既有 formatRoadLocation/formatRouteCityDistrict 规则一致，广西壮族自治区南宁市邕宁区 → 南宁市 邕宁区）。
• 接入 4 处：调度页 route-overview 起/终节点的强文本改用 dispatchLocationName(route, 'departure'|'arrival')、第二行地址改用 formatRegionAddress(...)，addressText() 名称+地址都格式化并去重（南宁市 邕宁区 不再重复两遍）；详情页 route-map 两处 <small> 地址改用 formatRegionAddress(...)。
• 验证：项目根临时验证页（真组件 + axios.defaults.adapter 全量 mock 后端，复刻截图数据 routes=[上海市静安区, 南宁站, 广西壮族自治区南宁市邕宁区]）+ agent-browser 读 DOM —— 调度页顶部 4 节点 =「上海市 浦东新区 / 上海市 静安区 / 南宁站 / 南宁市 邕宁区」，与段1~段3 表头、详情页路线图逐字一致；终节点宽 101px 未被省略号截断（改前原始串超宽被截）；两页 innerText 再扫 省|自治区 已无未加空格的残留。用完已删临时文件。

同事拉代码编译报错（漏提交新文件）→ 已修复

• 现象：同事 pull 后 [vite:load-fallback] Could not load .../src/utils/route-change (imported by src/views/business/loading-manage.vue): ENOENT。
• 根因：src/utils/route-change.js、src/utils/region-address.js 是新增文件且一直 untracked，本地能跑、远端没有。 提交时用了只带已跟踪文件的写法（git commit -am 之类），.vue 的引用被提交了、新 .js 没进去（12:44 的 6de87ed 就是这种情况）。region-address 是第二个雷：route-change 修好后会接着报它。
• 修复：git add src/utils/region-address.js src/utils/route-change.js → commit 749b314 :bug: 补充提交遗漏的 region-address 与 route-change 工具文件 → push（期间远端有同事新提交 74780b8，先 git pull --rebase 无冲突）。三处 tree（本地 HEAD / origin/master / 远端真实 SHA）核对一致。
• 复查：写脚本扫 src/** 所有 @/、相对路径引用（含 scss @use/@import），比对 git ls-files，无其它"文件存在但未跟踪"的引用目标，暂时不会再踩同类坑。
• 教训：本仓库提交前建议 git status 扫一眼 ??，新增文件必须显式 git add。

payment 模块 6 个手写列表页：搜索栏「展开/收起」统一（对齐 customer-archive / settlement）

• 起因：/payment/invoice-application、/payment/bill-payment 的展开收起控件与别的模块不一致。排查发现 payment 模块 6 个手写搜索栏各写各的：5 个是 el-tooltip+el-button text+纯箭头图标（文案「折叠」，tooltip 才显示），receipt-flow.vue 更离谱 —— 裸 el-button（带边框）且排在查询/重置左边。
• 统一标准（两处参照物写法完全一致）：
  • views/settlement/{formal-settlement,pre-settlement,transport-reconciliation,receivable-payable-detail,settlement-adjustment}.vue 已有写法：

    <el-button text :icon="searchExpanded ? ArrowUp : ArrowDown" @click="toggleSearch">
      {{ searchExpanded ? '收起' : '展开' }}
    </el-button>
    

    放在「查询 / 重置」之后（最右）。
  • views/vehicle/customer-archive.vue 是 avue-crud 内建，searchIcon: true + searchIndex: 4，渲染出的也是同一形态。
• avue 显示规则（node_modules/@smallwei/avue/lib/packages/element-plus/crud/menu/header-search3.js 的 isSearchIcon）： searchIcon === true && columnLen > searchIndex → 搜索项不超过 4 项时根本不渲染展开/收起按钮。故各页 data 加 searchIndex: 4 + searchItemCount: N，computed showSearchToggle = searchItemCount > searchIndex。
• 逐页落地：invoice-application(5项) / invoice-receipt(6项) / receipt-claim-record(11项) / receipt-flow(7项) / components/bill-ledger-search(6项) 均显示；components/bill-payment-search 仅 4 项（后端 BillPaymentServiceImpl.selectPage 也只支持 paymentNo/deptName/paymentDate 区间/approvalStatus 这 4 个条件）→ showSearchToggle=false，不渲染按钮，避免留一个"点了没反应"的假按钮。
• receipt-flow.vue：补 import { ArrowDown, ArrowUp }、按钮从最左移到最右、文案「折叠」→「收起」。
• gap 不动：business/、settlement/ 手写页的 __search-actions 都写了 gap: 8px（与本次统一无关，别顺手删）。
• 校验：6 个文件 curl localhost:2889/src/...vue 与 ?vue&type=style&index=0&scoped=true&lang.scss 全 200；grep 折叠|el-tooltip src/views/payment/ 已无残留。

15:55 路线变更「变更内容」列排布问题（待用户确认方案，未动代码）

• 位置：变更运输路线 弹窗 → 变更记录 tab → 表格 变更内容 列，共 3 处同款：views/business/loading-manage.vue:1688（__record-content）、views/business/components/waybill-manage-page.vue:3027、views/business/components/business-crud-page.vue:2998。
• 存储格式为单行文本：YD-xxx：发货地 A → B；到货地 C → D；YD-yyy：…，展示层由 src/utils/route-change.js 的 formatRouteChangeContent() 切行（；→换行、→→ →\n），再以 white-space: pre-wrap 平铺。
• 病因：： 不带换行 → 运单号与「发货地 原地址」挤同一行；前/后无标签；多条记录无分隔。一个单元格可堆 3 条运单 × 2 字段 × 2 行 ≈ 12+ 行。
• 已给 3 个方案（A 单元格内分组对齐：运单号独占行主色 + 字段标签列 + 前值/后值缩进对齐，改 formatter 返回结构 + 模板渲染；B 列只留「运单号 · N 项」摘要 + 查看详情弹窗，复用同类组件 src/components/change-record-detail-dialog/main.vue（变更字段/变更前/变更后三列 + 分页）；C 按「运单 × 字段」拆行 + span-method 合并时间/人）。推荐 A，B 备选。等用户确认后再改。

16:20 已按方案 A 落地（变更内容列分组渲染）

• src/utils/route-change.js 重写：删掉 formatRouteChangeContent，改为导出 parseRouteChangeContent(content)，返回分组数组 [{ type, title, text, fields:[{label,before,after,single,changed,unchanged}] }]。
  • ⚠️ 关键坑：存储格式里「到货地」前面只有 ；、没有冒号（真实格式 ${waybillNo}：发货地 A → B；到货地 C → D）。第一版按「冒号切 head/tail」写，导致「到货地」整段落进纯文本兜底 → 必须"先判断 segment 是否以字段名开头"，再把无标题字段行合并进上一条 waybill 分组。
  • 字段名正则的长标签必须排在短标签前（发货地址 早于 发货地），否则被前缀吃掉。字段白名单：发货地址/到货地址/发货地/到货地/装货地/卸货地/收货地。
  • 三种分组类型：waybill（运单号：发货地…）、field（；到货地…，合并进上一个非 text 分组）、group（路线顺序：X 调整为 Y，按「调整为」拆前后，不走箭头切分，因为路线文本本身含 →）、text（兜底原文）。
  • 箭头正则 /\s*(?:→|➔|➜|[\-–—]{1,2}\s*>)\s*/；空值归一为 -。
• 三处模板统一改为分组渲染（运单号主色标题 + 左侧 2px 主色竖条；字段 label 列 54px；changed 两行「旧值(灰) / → 新值(主色)」，unchanged 单行 + 灰字「未变更」）：loading-manage.vue（loading-route-change-dialog__change-*）、waybill-manage-page.vue、business-crud-page.vue。样式块也同步替换（__route-change-record-content 从 white-space: pre-wrap 改为 flex column；箭头 text-align: right，grid item 会被 blockify 所以 span 上生效）。
• 校验：node 跑 parseRouteChangeContent 7 组用例（真实截图数据 / 路线顺序 / 混合 / 半角箭头分号 / 无箭头单值 / 纯文本 / 空）全部符合预期；@vue/compiler-sfc 编译三个 .vue 的 template + scss 全过；SSR 渲染真实模板 + agent-browser 截图确认观感（临时文件已删）。
• 已知代价：窄列（360px）下地址被 54px 标签列占位，单元格比原来高约一倍；换来的是一条运单/一个字段的分组边界一目了然。

16:05 /base/measurement-unit 创建时间/更新时间列截断修复

• 现象：表格里「创建时…」「更新时…」列被挤到 ~80px，2026-0... 截断；用户猜测要固定操作列。
• 根因：option/base/measurement-unit.js 两列只写了 type/format/sortable，没有 width/minWidth → el-table 未设宽列按剩余空间均分，被压到低于内容宽度 → 省略号。与 menuFixed 无关。
• 修法：createTime/updateTime 加 width: 180（与同模块 option/base/common-address.js 完全一致），createUserName/updateUserName 加 minWidth: 110。
• 结论（重要经验）：操作列不需要额外"固定"，menuFixed: 'right' 早在 option 里（main.js 全局 crudOption.menuWidth: 180，avue 库默认 220）。不要为了"防截断"去加宽操作列，加宽只会增加横向滚动；时间列截断一律是缺 width。
• 验证方式（可复用）：项目根建临时 html __mu-check.html → Vite 直接服务；import { createOption } from '/src/option/base/measurement-unit.js' + app.use(Avue, { crudOption: { menuWidth: 180 } })，用 h(resolveComponent('avue-crud'), {...}, { menu: () => [...] }) 渲染（避免运行时模板编译）。 实测（容器 1200px）：td 宽 [50,70,150,150,130,200,100,110,110,180,180,180] 合计 1610 → 横向滚动 410px；scrollWidth > clientWidth 的单元格 0 个；操作 th 为 position: sticky，滚到最右后右边缘 = 容器右边缘 → fixed 生效。用完删文件 + agent-browser close。

16:25 变更内容列 hover 提示去除（分组改造的连带问题）

• 用户反馈：改完分组后，变更内容单元格 hover 出现提示浮层，要求去掉。
• 根因：main.js:84 app.use(ElementPlus, { table: { showOverflowTooltip: true } }) 全局开启 → EP 给每列 .cell 加 .el-tooltip 类（white-space: nowrap）。我上一次改造把内层 white-space: pre-wrap 换成了 flex column、忘了补 white-space → 继承 nowrap → 长地址横向溢出 → tooltip 激活。改动前靠 pre-wrap 自保所以没暴露。
• 修法（三处，列级豁免、不动全局配置）：① 变更内容列显式 :show-overflow-tooltip="false"；② __route-change-record-content 补 white-space: normal 兜底。
• ⚠️ 验证踩坑：用「项目根临时 html + node_modules/element-plus/dist/index.full.min.js 全局构建 + app.use(ElementPlus, { table: { showOverflowTooltip: true } })」复现时，el-table 表头/列宽渲染错乱（表头逐列堆叠、每行只渲染出 2 个 cell），该环境不可用于布局验证；但单元格内容渲染正常，足以确认分组结构无误。要验证真实表格布局还是得走 Vite 服务真实页面。 另：自定义组件接模板字符串时，切出的模板里 row.content 要替换成 content（插槽作用域不存在于独立组件里），否则报 Cannot read properties of undefined (reading 'content')。
• 校验：编译三个 .vue 的 template + scss 全过；临时验证页 __route-change-verify.html 与 8899 端口静态服务已删除/停止。
• 未处理（等用户确认）：备注列的 show-overflow-tooltip 保持原样（属全站约定），用户若要求连备注一起去掉再单独改。