From be55f23c21e926f22393b94e578d1cdbea52966e Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Sun, 16 Aug 2026 15:49:16 +0800 Subject: [PATCH] docs: add quote list column stats implementation plan Break the approved design into TDD-friendly tasks for the quote management list interactive summary row. Co-authored-by: Cursor --- .../2026-08-16-quote-list-column-stats.md | 550 ++++++++++++++++++ 1 file changed, 550 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-16-quote-list-column-stats.md diff --git a/docs/superpowers/plans/2026-08-16-quote-list-column-stats.md b/docs/superpowers/plans/2026-08-16-quote-list-column-stats.md new file mode 100644 index 000000000..18d61c158 --- /dev/null +++ b/docs/superpowers/plans/2026-08-16-quote-list-column-stats.md @@ -0,0 +1,550 @@ +# 报价单列表可配置列统计行 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 在【报价单管理】主列表底部增加可点选的列统计行:默认空;用户按列选择求和/平均/最大/最小后,对当前页数据即时展示,并写入本机 localStorage。 + +**Architecture:** 纯函数放在 `quoteListColumnStats.ts`(聚合 + 文案 + storage);`QuoteListPage.vue` 在主表与分页之间渲染自定义统计行(不用 `show-summary`)。不改 `ListTable`、不改后端;其它列表本轮不接入。 + +**Tech Stack:** Vue 3、Element Plus(`el-dropdown`)、TypeScript、localStorage、Node 内置 test + `tsx` + +**Spec:** `docs/superpowers/specs/2026-08-16-quote-list-column-stats-design.md` + +--- + +## File map + +| 文件 | 职责 | +|------|------| +| `web-admin/src/views/crm/quote/quoteListColumnStats.ts` | 类型、解析数字、聚合、展示文案、localStorage | +| `web-admin/src/views/crm/quote/quoteListColumnStats.test.ts` | 纯函数单测(`node:test` + `tsx`) | +| `web-admin/src/views/crm/quote/QuoteListPage.vue` | 统计行 UI、列显隐同步、取值适配(含 `finalAmount`) | + +--- + +### Task 1: 纯函数模块 + 失败单测骨架 + +**Files:** +- Create: `web-admin/src/views/crm/quote/quoteListColumnStats.ts` +- Create: `web-admin/src/views/crm/quote/quoteListColumnStats.test.ts` + +- [ ] **Step 1: 写入完整纯函数模块** + +```ts +// web-admin/src/views/crm/quote/quoteListColumnStats.ts + +export type ColumnStatMethod = 'sum' | 'avg' | 'max' | 'min' + +export const COLUMN_STAT_STORAGE_KEY = 'crm-quote-column-stats' + +export const COLUMN_STAT_METHOD_OPTIONS: { value: ColumnStatMethod | ''; label: string }[] = [ + { value: '', label: '无' }, + { value: 'sum', label: '求和' }, + { value: 'avg', label: '平均' }, + { value: 'max', label: '最大值' }, + { value: 'min', label: '最小值' } +] + +export const COLUMN_STAT_METHOD_LABEL: Record = { + sum: '求和', + avg: '平均', + max: '最大值', + min: '最小值' +} + +/** 列表中按金额格式展示的列 prop */ +export const QUOTE_MONEY_STAT_PROPS = new Set([ + 'discountAmount', + 'finalAmount', + 'totalAmount', + 'freight', + 'barrelDeposit' +]) + +export function parseStatNumber(raw: unknown): number | null { + if (raw == null || raw === '') return null + if (typeof raw === 'number') return Number.isFinite(raw) ? raw : null + let s = String(raw).trim() + if (!s) return null + s = s.replace(/^¥/, '').replace(/%$/, '').replace(/,/g, '') + const n = Number(s) + return Number.isFinite(n) ? n : null +} + +function nonEmptyString(raw: unknown): string | null { + if (raw == null) return null + const s = String(raw).trim() + return s ? s : null +} + +export function aggregateColumnValues( + values: unknown[], + method: ColumnStatMethod +): number | string | null { + const nums: number[] = [] + const strs: string[] = [] + for (const v of values) { + const n = parseStatNumber(v) + if (n != null) nums.push(n) + else { + const s = nonEmptyString(v) + if (s != null) strs.push(s) + } + } + + if (method === 'sum') { + if (!nums.length) return null + return nums.reduce((a, b) => a + b, 0) + } + if (method === 'avg') { + if (!nums.length) return null + return nums.reduce((a, b) => a + b, 0) / nums.length + } + if (method === 'max') { + if (nums.length) return Math.max(...nums) + if (strs.length) return strs.reduce((a, b) => (a >= b ? a : b)) + return null + } + // min + if (nums.length) return Math.min(...nums) + if (strs.length) return strs.reduce((a, b) => (a <= b ? a : b)) + return null +} + +export function formatStatNumberResult( + value: number, + opts: { money?: boolean } = {} +): string { + if (opts.money) { + return value.toLocaleString('zh-CN', { + minimumFractionDigits: 2, + maximumFractionDigits: 2 + }) + } + if (Number.isInteger(value)) return String(value) + return value.toLocaleString('zh-CN', { maximumFractionDigits: 4 }) +} + +/** + * 生成合计格展示文案。method 为空则返回 ''。 + * 聚合结果为 null →「{标签} -」 + */ +export function formatColumnStatDisplay( + method: ColumnStatMethod | '' | null | undefined, + values: unknown[], + opts: { money?: boolean } = {} +): string { + if (!method) return '' + const label = COLUMN_STAT_METHOD_LABEL[method] + const agg = aggregateColumnValues(values, method) + if (agg == null) return `${label} -` + if (typeof agg === 'number') { + return `${label} ${formatStatNumberResult(agg, opts)}` + } + return `${label} ${agg}` +} + +export type ColumnStatConfigMap = Partial> + +export function loadColumnStatConfig( + storageKey: string = COLUMN_STAT_STORAGE_KEY +): ColumnStatConfigMap { + try { + const raw = localStorage.getItem(storageKey) + if (!raw) return {} + const parsed = JSON.parse(raw) as Record + if (!parsed || typeof parsed !== 'object') return {} + const out: ColumnStatConfigMap = {} + for (const [k, v] of Object.entries(parsed)) { + if (v === 'sum' || v === 'avg' || v === 'max' || v === 'min') out[k] = v + } + return out + } catch { + return {} + } +} + +export function saveColumnStatConfig( + config: ColumnStatConfigMap, + storageKey: string = COLUMN_STAT_STORAGE_KEY +): void { + const cleaned: ColumnStatConfigMap = {} + for (const [k, v] of Object.entries(config)) { + if (v === 'sum' || v === 'avg' || v === 'max' || v === 'min') cleaned[k] = v + } + localStorage.setItem(storageKey, JSON.stringify(cleaned)) +} + +export function setColumnStatMethod( + config: ColumnStatConfigMap, + prop: string, + method: ColumnStatMethod | '' +): ColumnStatConfigMap { + const next = { ...config } + if (!method) delete next[prop] + else next[prop] = method + return next +} +``` + +- [ ] **Step 2: 写单测(先假设实现正确;若模块尚未导出齐会 FAIL)** + +```ts +// web-admin/src/views/crm/quote/quoteListColumnStats.test.ts +import assert from 'node:assert/strict' +import { describe, it } from 'node:test' +import { + aggregateColumnValues, + formatColumnStatDisplay, + parseStatNumber, + setColumnStatMethod +} from './quoteListColumnStats' + +describe('parseStatNumber', () => { + it('parses plain and money-like strings', () => { + assert.equal(parseStatNumber(12.5), 12.5) + assert.equal(parseStatNumber('¥1,234.50'), 1234.5) + assert.equal(parseStatNumber('10%'), 10) + assert.equal(parseStatNumber('abc'), null) + assert.equal(parseStatNumber(''), null) + }) +}) + +describe('aggregateColumnValues', () => { + it('sum and avg over numbers only', () => { + assert.equal(aggregateColumnValues([1, 2, 'x', null], 'sum'), 3) + assert.equal(aggregateColumnValues([1, 3], 'avg'), 2) + assert.equal(aggregateColumnValues(['a', 'b'], 'sum'), null) + }) + + it('max/min prefer numbers then lexicographic strings', () => { + assert.equal(aggregateColumnValues([1, 9, 3], 'max'), 9) + assert.equal(aggregateColumnValues([1, 9, 3], 'min'), 1) + assert.equal(aggregateColumnValues(['张三', '李四'], 'max'), '张三') + assert.equal(aggregateColumnValues(['张三', '李四'], 'min'), '李四') + assert.equal(aggregateColumnValues([null, ''], 'max'), null) + }) +}) + +describe('formatColumnStatDisplay', () => { + it('empty method yields empty string', () => { + assert.equal(formatColumnStatDisplay('', [1, 2]), '') + }) + + it('formats money sum and dash for non-numeric sum', () => { + assert.equal( + formatColumnStatDisplay('sum', [1000, 234.5], { money: true }), + '求和 1,234.50' + ) + assert.equal(formatColumnStatDisplay('sum', ['甲', '乙']), '求和 -') + assert.equal(formatColumnStatDisplay('max', ['甲', '乙']), '最大值 乙') + }) +}) + +describe('setColumnStatMethod', () => { + it('sets and clears props', () => { + const a = setColumnStatMethod({}, 'totalAmount', 'sum') + assert.deepEqual(a, { totalAmount: 'sum' }) + const b = setColumnStatMethod(a, 'totalAmount', '') + assert.deepEqual(b, {}) + }) +}) +``` + +- [ ] **Step 3: 跑单测,期望 PASS** + +```bash +cd web-admin && pnpm exec tsx --test src/views/crm/quote/quoteListColumnStats.test.ts +``` + +Expected: all tests pass. + +- [ ] **Step 4: Commit** + +```bash +git add web-admin/src/views/crm/quote/quoteListColumnStats.ts \ + web-admin/src/views/crm/quote/quoteListColumnStats.test.ts +git commit -m "$(cat <<'EOF' +feat(crm): add quote list column stats helpers + +Pure aggregation, display formatting, and localStorage helpers +for the quote list configurable summary row. +EOF +)" +``` + +--- + +### Task 2: QuoteListPage 接入统计行 UI + +**Files:** +- Modify: `web-admin/src/views/crm/quote/QuoteListPage.vue` + +- [ ] **Step 1: 在 script 中增加 import、状态与辅助逻辑** + +在现有 `script` 适当位置(imports 区与 `quoteList` / `isColumnVisible` 附近)加入: + +```ts +import { + COLUMN_STAT_METHOD_OPTIONS, + QUOTE_MONEY_STAT_PROPS, + formatColumnStatDisplay, + loadColumnStatConfig, + saveColumnStatConfig, + setColumnStatMethod, + type ColumnStatConfigMap, + type ColumnStatMethod +} from './quoteListColumnStats' +``` + +固定始终展示、且可统计的列(不在 `listColumnDefs` 的显隐里,但主表始终有): + +```ts +const ALWAYS_STAT_PROPS = ['quoteNo', 'quoteTitle'] as const +``` + +```ts +const columnStatConfig = ref(loadColumnStatConfig()) + +/** 统计行业务列:报价单号/主题 + 当前可见可选列,顺序与主表一致 */ +const statsBusinessColumns = computed(() => { + const cols: { prop: string; money: boolean }[] = [ + { prop: 'quoteNo', money: false }, + { prop: 'quoteTitle', money: false } + ] + for (const def of listColumnDefs) { + if (!isColumnVisible(def.prop)) continue + cols.push({ + prop: def.prop, + money: QUOTE_MONEY_STAT_PROPS.has(def.prop) + }) + } + return cols +}) + +function getStatCellValues(prop: string): unknown[] { + return quoteList.value.map((row) => { + if (prop === 'finalAmount') return getQuoteFinalAmount(row) + if (prop === 'productInfo') { + const lines = formatQuoteProductInfoLines(row) + return lines.length ? lines.join('\n') : null + } + return (row as Record)[prop] + }) +} + +function statsCellText(prop: string, money: boolean): string { + const method = columnStatConfig.value[prop] + return formatColumnStatDisplay(method, getStatCellValues(prop), { money }) +} + +function onSelectColumnStat(prop: string, method: ColumnStatMethod | '') { + columnStatConfig.value = setColumnStatMethod(columnStatConfig.value, prop, method) + saveColumnStatConfig(columnStatConfig.value) +} +``` + +注意:`getQuoteFinalAmount` / `formatQuoteProductInfoLines` 须在这些函数之前已定义,或把上述函数放到它们之后。 + +- [ ] **Step 2: 在模板中于 `` 与分页之间插入统计行** + +紧接 `` 之后、`