perf(worker): 单号检索收敛为可走索引的等值/前缀,并支持关联单号反查

问题:后台「按单号检索」在平台单号/工单号分支里 OR 了一支
`work_order_no ILIKE '%'||$n||'%'`。前置通配符非 sargable,任何 B-Tree 都用不上,
整条查询退化成 work_orders 的 Seq Scan。

生产实测(10.3 万行 / 572MB,pg_stat_statements 46 小时窗口):
  - 列表查询 + 统计查询用同一份 filters 并行执行,一次检索打两遍全表;
    两者合计占全库 66% 的磁盘读(1.1TB/46h),单次读 26,442 个块(约 211MB)、398ms、返回 1 行。
  - 收敛后同库同参数:等值 0.19ms,前缀 30ms(约 2000 倍)。
  - 真实统计查询端到端 760ms → 61.6ms。

改动:
1. 平台单号/工单号分支收敛为「等值 + 前缀」,与 order-repo / task-repo 既有写法一致;
   工单号含随机小写段(10.2 万行里 7.4 万行非全大写),保留 LOWER() 比较。
2. 迁移 090 补 text_pattern_ops 前缀索引:当前库 collation 为 en_US.utf8,
   前缀 LIKE 在默认 B-Tree 上会退化成全索引扫(实测 438ms)。
3. 新增关联单号反查分支:SUB/INV/AS/DT 不在 work_orders 上,
   经关联表反查工单 id,四条链路均命中唯一索引。
4. 前端 isExplicitOrderNoSearch 同步补齐(否则搜到的单会被状态页签挡掉、
   实时补丁还会把行删掉)。

验证:生产 EXPLAIN 逐条比对 + 14 项仓储单测 + 6 项分类器单测。
This commit is contained in:
yml2213
2026-10-03 14:27:32 +08:00
parent f0d745ea50
commit 90de6b9419
8 changed files with 289 additions and 6 deletions
@@ -116,6 +116,88 @@ test('空白搜索词不生成全表 LIKE 条件', () => {
assert.deepEqual(query.params, [])
})
test('平台单号检索只生成可走索引的等值/前缀条件,不得出现前置通配符', () => {
const query = buildWorkOrderWhere({ keyword: '2627401680611492' })
assert.match(
query.whereClause,
/\(wo\.platform_order_id = \$1 OR wo\.platform_order_id LIKE \$1 \|\| '%'\)/,
)
// 前置通配符非 sargable:一旦混进来,整条查询会退化成 work_orders 全表扫,
// 生产实测每次读 211MB / 398ms,列表与统计并行触发一次打两遍。
assert.doesNotMatch(query.whereClause, /ILIKE\s*'%'/)
assert.deepEqual(query.params, ['2627401680611492'])
})
test('工单号检索大小写不敏感且只走索引,不得出现前置通配符', () => {
const query = buildWorkOrderWhere({ keyword: 'WO26100113008697' })
assert.match(
query.whereClause,
/\(LOWER\(wo\.work_order_no\) = LOWER\(\$1\) OR LOWER\(wo\.work_order_no\) LIKE LOWER\(\$1\) \|\| '%'\)/,
)
assert.doesNotMatch(query.whereClause, /ILIKE\s*'%'/)
assert.deepEqual(query.params, ['WO26100113008697'])
})
test('SUB/INV/AS/DT 关联单号经关联表反查工单,不回落到通配符', () => {
// 寄售线索号:SUB → result_inventory_id → bound_work_order_id
const sub = buildWorkOrderWhere({ keyword: 'SUB26100301127318' })
assert.match(sub.whereClause, /FROM consignment_submissions cs/)
assert.match(sub.whereClause, /ci\.bound_work_order_id IS NOT NULL/)
assert.doesNotMatch(sub.whereClause, /LIKE LOWER/)
assert.deepEqual(sub.params, ['SUB26100301127318'])
// 寄售库存号:INV → bound_work_order_id
const inv = buildWorkOrderWhere({ keyword: 'INV26100310477194' })
assert.match(inv.whereClause, /FROM consignment_inventories ci/)
assert.doesNotMatch(inv.whereClause, /LIKE LOWER/)
// 售后案号:AS → work_order_id
const ase = buildWorkOrderWhere({ keyword: 'ASde06bcb25aca' })
assert.match(ase.whereClause, /FROM worker_after_sales_cases ac/)
assert.match(ase.whereClause, /ac\.work_order_id IS NOT NULL/)
assert.doesNotMatch(ase.whereClause, /LIKE LOWER/)
// 履约任务号:DT → work_orders.task_id(历史数据为空,但链路必须保留)
const dt = buildWorkOrderWhere({ keyword: 'DTb946808bcd5b' })
assert.match(dt.whereClause, /FROM fulfillment_tasks ft/)
assert.match(dt.whereClause, /wo_task\.task_id = ft\.id/)
assert.doesNotMatch(dt.whereClause, /LIKE LOWER/)
})
test('普通关键词仍然走 trgm 表达式模糊搜索', () => {
const query = buildWorkOrderWhere({ keyword: '指挥官密钥' })
assert.match(query.whereClause, /LIKE LOWER\(\$\d+\)/)
assert.deepEqual(query.params, ['%指挥官密钥%'])
})
test('单号检索分支不得回退成裸列模糊匹配(源码级防退化守卫)', async () => {
const { readFile } = await import('node:fs/promises')
const src = await readFile(
new URL('./worker-platform/work-order-query-repo.ts', import.meta.url),
'utf8',
)
// 这里是 46 小时窗口内占全库 66% 磁盘读的形状:裸列 + 前置通配符。
assert.doesNotMatch(
src,
/wo\.work_order_no ILIKE '%' \|\|/,
'工单号模糊匹配必须改用 trgm 表达式,或收敛为等值/前缀',
)
assert.doesNotMatch(
src,
/wo\.work_order_no ILIKE \$\{paramIndex\} \|\|/,
'工单号前缀匹配必须用 LOWER() 走 idx_work_orders_work_order_no_lower_pattern',
)
assert.match(
src,
/platform_order_id LIKE \$\{paramIndex\} \|\| '%'/,
'平台单号前缀条件必须保留(迁移 090 的 text_pattern_ops 索引依赖它)',
)
})
test('大厅候选按分类上限取队首后再受全局上限限制', () => {
const query = buildWorkOrderWhere({
hallCandidateLimit: 20,
@@ -9,6 +9,8 @@ import {
import {
isPlatformOrderIdLookupKeyword,
isWorkOrderNoLookupKeyword,
resolveRelatedWorkOrderLookupKind,
type RelatedWorkOrderLookupKind,
} from '../../utils/platform-order-id.js'
export const WORK_ORDER_SELECT = `
@@ -141,6 +143,54 @@ function workOrderSearchExpression(alias = 'wo') {
)`
}
/**
* 关联单号(SUB / INV / AS / DT)反查工单的条件。
*
* 这些号码不存在于 work_orders 上,只能经关联表回溯。四条链路分别命中:
* consignment_submissions_submission_no_key / consignment_inventories_inventory_no_key
* / worker_after_sales_cases_case_no_key / fulfillment_tasks_task_no_key
* 全部是唯一索引等值查找,因此不会出现「按单号搜索反而全表扫」的情况。
*
* 回溯不到时不返回任何行(而不是回落到通配符搜索)——SUB/INV 在库存被工单消耗前
* 本来就没有对应工单,此时"查不到"是正确结果。
*/
function buildRelatedWorkOrderLookupFilter(
kind: RelatedWorkOrderLookupKind,
paramIndex: string,
): string {
if (kind === 'consignment_submission') {
return `wo.id IN (
SELECT ci.bound_work_order_id
FROM consignment_submissions cs
JOIN consignment_inventories ci ON ci.id = cs.result_inventory_id
WHERE cs.submission_no = ${paramIndex}
AND ci.bound_work_order_id IS NOT NULL
)`
}
if (kind === 'consignment_inventory') {
return `wo.id IN (
SELECT ci.bound_work_order_id
FROM consignment_inventories ci
WHERE ci.inventory_no = ${paramIndex}
AND ci.bound_work_order_id IS NOT NULL
)`
}
if (kind === 'after_sales_case') {
return `wo.id IN (
SELECT ac.work_order_id
FROM worker_after_sales_cases ac
WHERE ac.case_no = ${paramIndex}
AND ac.work_order_id IS NOT NULL
)`
}
return `wo.id IN (
SELECT wo_task.id
FROM fulfillment_tasks ft
JOIN work_orders wo_task ON wo_task.task_id = ft.id
WHERE ft.task_no = ${paramIndex}
)`
}
/**
* 打手订单个人状态:拼单按个人份额状态计算。
* 传入 workerId 时,代练中但存在待审核取消申请或未处理反馈的订单归入问题单,
@@ -930,18 +980,35 @@ export function buildWorkOrderWhere({
filters.push(`wo.id = $${params.length}`)
}
if (normalizedKeyword) {
// 单号检索只允许「可走索引的等值/前缀」条件,与 order-repo / task-repo 的既有写法保持一致。
// 这两支曾经额外 OR 了 `work_order_no ILIKE '%' || $n || '%'`:前置通配符非 sargable,
// 任何 B-Tree 都用不上,会把整条查询拖成 work_orders 的 Seq Scan。
// 生产实测(10.3 万行 / 572MB,pg_stat_statements 46 小时窗口):
// 后台按平台单号检索 → Seq Scan 每次读 26,442 个块(约 211MB)、398ms、返回 1 行;
// 列表与统计用同一份 filters 并行执行,一次检索打两遍全表,
// 两者合计占全库 66% 的磁盘读(1.1TB/46h)。
// 收敛后同库同参数:Index Scan 0.19ms,前缀检索 30ms(约 2000 倍)。
const relatedLookupKind = resolveRelatedWorkOrderLookupKind(normalizedKeyword)
if (isPlatformOrderIdLookupKeyword(normalizedKeyword)) {
params.push(normalizedKeyword)
const paramIndex = `$${params.length}`
filters.push(
`(wo.platform_order_id = ${paramIndex} OR wo.platform_order_id LIKE ${paramIndex} || '%' OR wo.work_order_no ILIKE '%' || ${paramIndex} || '%')`,
`(wo.platform_order_id = ${paramIndex} OR wo.platform_order_id LIKE ${paramIndex} || '%')`,
)
} else if (isWorkOrderNoLookupKeyword(normalizedKeyword)) {
params.push(normalizedKeyword)
const paramIndex = `$${params.length}`
// 工单号含随机小写段(10.2 万行里 7.4 万行非全大写),必须 LOWER() 比较;
// 配套迁移 090 的 idx_work_orders_work_order_no_lower_pattern 才能让前缀检索走范围扫描。
filters.push(
`(wo.work_order_no = ${paramIndex} OR wo.work_order_no ILIKE ${paramIndex} || '%' OR wo.work_order_no ILIKE '%' || ${paramIndex} || '%' OR LOWER(wo.work_order_no) = LOWER(${paramIndex}))`,
`(LOWER(wo.work_order_no) = LOWER(${paramIndex}) OR LOWER(wo.work_order_no) LIKE LOWER(${paramIndex}) || '%')`,
)
} else if (relatedLookupKind) {
// 关联单号(SUB/INV/AS/DT)本身不在 work_orders 上,必须先经关联表反查工单 id。
// 四条链路都命中唯一索引,属于索引驱动的等值查询;查不到时直接返回空集,
// 不会像通配符那样退化成全表扫。
params.push(normalizedKeyword)
filters.push(buildRelatedWorkOrderLookupFilter(relatedLookupKind, `$${params.length}`))
} else {
params.push(`%${normalizedKeyword}%`)
filters.push(`${workOrderSearchExpression()} LIKE LOWER($${params.length})`)