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 <cursoragent@cursor.com>

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<ColumnStatMethod, string> = {
+  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<Record<string, ColumnStatMethod>>
+
+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<string, unknown>
+    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<ColumnStatConfigMap>(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<string, unknown>)[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: 在模板中于 `</ListTable>` 与分页之间插入统计行**
+
+紧接 `</ListTable>` 之后、`<div class="pagination list-pager-bar">` 之前插入：
+
+```vue
+        <div class="quote-list-stats-row" aria-label="列表列统计">
+          <div class="quote-list-stats-row__fixed">
+            <div class="quote-list-stats-row__cell is-fixed" style="width: 55px" />
+            <div class="quote-list-stats-row__cell is-fixed" style="width: 55px" />
+          </div>
+          <div class="quote-list-stats-row__scroll">
+            <div
+              v-for="col in statsBusinessColumns"
+              :key="col.prop"
+              class="quote-list-stats-row__cell is-stat"
+            >
+              <el-dropdown trigger="click" @command="(cmd: string) => onSelectColumnStat(col.prop, cmd as any)">
+                <span class="quote-list-stats-row__trigger" :class="{ 'is-empty': !statsCellText(col.prop, col.money) }">
+                  {{ statsCellText(col.prop, col.money) || '统计' }}
+                </span>
+                <template #dropdown>
+                  <el-dropdown-menu>
+                    <el-dropdown-item
+                      v-for="opt in COLUMN_STAT_METHOD_OPTIONS"
+                      :key="opt.label"
+                      :command="opt.value"
+                    >
+                      {{ opt.label }}
+                    </el-dropdown-item>
+                  </el-dropdown-menu>
+                </template>
+              </el-dropdown>
+            </div>
+          </div>
+        </div>
+```
+
+空态占位文案用浅色「统计」（或「—」），选中后替换为 `求和 …`。若产品更希望空态完全空白但可点，将 `|| '统计'` 改为 `\u00a0` 并保留 `min-height`。
+
+**推荐空态：** 显示淡色「选择统计」，避免完全空白不好点。与 spec「默认空」兼容做法：空态用 `opacity` 较低的「统计」占位，已选则正常色显示结果。上面模板已用 `is-empty` class 区分。
+
+- [ ] **Step 3: 增加 scoped 样式（对齐 Fresh Mint 合计行）**
+
+在该文件既有 `<style>` 中追加：
+
+```scss
+.quote-list-stats-row {
+  display: flex;
+  align-items: stretch;
+  border-top: 2px solid var(--el-color-primary, #10b981);
+  background: var(--mint-primary-bg, #ecfdf5);
+  font-weight: 600;
+  color: var(--mint-text, #1e293b);
+  min-height: 44px;
+  overflow-x: auto;
+}
+
+.quote-list-stats-row__fixed {
+  display: flex;
+  flex-shrink: 0;
+}
+
+.quote-list-stats-row__scroll {
+  display: flex;
+  flex: 1;
+  min-width: 0;
+}
+
+.quote-list-stats-row__cell {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 8px 10px;
+  box-sizing: border-box;
+  border-right: 1px solid var(--mint-border, #e2e8f0);
+}
+
+.quote-list-stats-row__cell.is-stat {
+  flex: 1 1 120px;
+  min-width: 120px;
+  justify-content: flex-start;
+}
+
+.quote-list-stats-row__trigger {
+  cursor: pointer;
+  width: 100%;
+  text-align: left;
+  line-height: 1.4;
+  font-size: 13px;
+  outline: none;
+}
+
+.quote-list-stats-row__trigger.is-empty {
+  color: var(--mint-text-muted, #64748b);
+  font-weight: 500;
+}
+```
+
+- [ ] **Step 4: 手动验收（dev）**
+
+```bash
+cd web-admin && pnpm dev
+```
+
+打开 `http://localhost:3006/#/crm/quote`，按 spec §7 逐条核对：
+
+1. 合计行存在，默认业务格为空态占位  
+2. 金额列「求和」数值正确  
+3. 客户名称「求和」为 `求和 -`，「最大值」有字符串结果  
+4. 换页方式保留、数值重算  
+5. 刷新后 localStorage 恢复  
+6. 隐藏列后统计格消失  
+7. 展开/勾选对应固定格无下拉  
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web-admin/src/views/crm/quote/QuoteListPage.vue
+git commit -m "$(cat <<'EOF'
+feat(crm): add interactive column stats row on quote list
+
+Let users pick sum/avg/max/min per column on the current page,
+with localStorage persistence for the quote management list.
+EOF
+)"
+```
+
+---
+
+### Task 3: 列宽/横滚对齐加固（若 Step 4 发现错位）
+
+**Files:**
+- Modify: `web-admin/src/views/crm/quote/QuoteListPage.vue`（仅当手动验收发现统计行与表头明显错位时执行）
+
+- [ ] **Step 1: 用主表 DOM 同步 cell 宽度（可选加固）**
+
+若 flex 均分导致与 `el-table` 列宽不一致，在 `onMounted` + `watch(statsBusinessColumns)` 中：
+
+```ts
+const quoteTableWrapRef = ref<HTMLElement | null>(null)
+
+function syncStatsColumnWidths() {
+  const table = quoteTableWrapRef.value?.querySelector('.el-table')
+  if (!table) return
+  const headerCells = table.querySelectorAll('.el-table__header-wrapper th')
+  // headerCells[0]=expand, [1]=selection, 之后与 statsBusinessColumns 对齐
+  const cells = quoteTableWrapRef.value?.querySelectorAll(
+    '.quote-list-stats-row__scroll .quote-list-stats-row__cell'
+  )
+  if (!cells) return
+  const offset = 2
+  cells.forEach((el, i) => {
+    const th = headerCells[i + offset] as HTMLElement | undefined
+    if (!th) return
+    ;(el as HTMLElement).style.flex = 'none'
+    ;(el as HTMLElement).style.width = `${th.offsetWidth}px`
+    ;(el as HTMLElement).style.minWidth = `${th.offsetWidth}px`
+  })
+}
+```
+
+给包住 `ListTable` + 统计行的容器加 `ref="quoteTableWrapRef"`，并在 `nextTick` 调用 `syncStatsColumnWidths`；监听 window resize。
+
+若 Task 2 验收对齐已可接受，本 Task 可整项勾选为跳过并在 PR 说明中注明。
+
+- [ ] **Step 2: Commit（仅当有改动）**
+
+```bash
+git add web-admin/src/views/crm/quote/QuoteListPage.vue
+git commit -m "$(cat <<'EOF'
+fix(crm): sync quote list stats row widths to table headers
+
+Keep the interactive summary cells aligned when columns resize.
+EOF
+)"
+```
+
+---
+
+## Spec coverage check
+
+| Spec 要求 | Task |
+|-----------|------|
+| 当前页统计 | Task 2 `getStatCellValues` ← `quoteList` |
+| 点选下拉 + 前缀文案 | Task 2 模板 + Task 1 `formatColumnStatDisplay` |
+| 全业务列可配 | Task 2 `statsBusinessColumns` |
+| 算不出显示 `-` | Task 1 单测 + `formatColumnStatDisplay` |
+| localStorage `crm-quote-column-stats` | Task 1 load/save |
+| 展开/勾选不可配 | Task 2 固定空 cell |
+| 不改 ListTable/后端 | 文件 map 已限制 |
+| Fresh Mint 合计行视觉 | Task 2 样式 |
+| `finalAmount` 用同一取值 | Task 2 `getQuoteFinalAmount` |
+
+## 执行方式
+
+Plan complete and saved to `docs/superpowers/plans/2026-08-16-quote-list-column-stats.md`. Two execution options:
+
+**1. Subagent-Driven (recommended)** — 每个 Task 派发新子代理，Task 间复核  
+
+**2. Inline Execution** — 本会话按 executing-plans 连续执行并设检查点  
+
+Which approach?