Files
shanxia2.0/docs/superpowers/plans/2026-07-31-pl-required-brand-as-preference.md
T
zlwuandCursor 10c3c5470c chore: sync local PL/CRM/BX and migration work to new Gogs host
Bundle pending backend/web-admin feature updates, data-migration scripts,
and related docs so the V1.5 branch on the Tencent Cloud Gogs matches the
current workspace (excluding local secrets).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-01 09:19:21 +08:00

16 KiB
Raw Blame History

指定品牌回填改为偏好提示 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: 取消司机链接 / 现场链接 / 归档弹窗等回填路径上「指定品牌只能填该品牌」的硬锁,使 required 仅作计划偏好:默认预选、可取消、可多选其他品牌,校验与 any 一致(合计 = 实际数量)。

Architecture: 后端 validate_brand_qty_rows 将 required 与 any 共用合计校验;前端 BrandQtyChipsField 对两种模式统一多选芯片交互;各父级初始化为 required 加载产品全部启用品牌并预选偏好品牌,删除「实际数量强制写死唯一品牌行」逻辑。计划创建存库语义不变。

Tech Stack: FastAPI / pytest;Vue 3 + Element Plus(web-admin);公开页 Vant。

Spec: docs/superpowers/specs/2026-07-31-pl-required-brand-as-preference-design.md


File map

File Responsibility
backend/app/services/pl_brand_archive.py 权威校验:required 不再锁品牌
backend/tests/test_pl_brand_archive.py 替换/新增 required 用例
web-admin/src/components/business/brand-qty-chips-field/index.vue 统一多选交互与标题
web-admin/src/components/business/pl-plan-archive-dialog/index.vue required 加载全品牌 + 预选;去 sync
web-admin/src/components/business/pl-plan-driver-feedback-dialog/index.vue 同上
web-admin/src/components/business/pl-plan-view-tabs/index.vue 现场编辑初始化与 chips 一致
web-admin/src/views/public/pl/transport/index.vue 确认预选逻辑;依赖 chips 组件
web-admin/src/views/public/pl/_shared/PublicIoOrderPage.vue 同上
docs/demos/pl-site-driver-brand-qty-demo.html 文案修正

公开 API(public_transport / pl_io_order_service)已返回产品全部启用 brandOptions,一般无需改后端读接口。


Task 1: Backend — validate_brand_qty_rows 放宽 required

Files:

  • Modify: backend/app/services/pl_brand_archive.py

  • Modify: backend/tests/test_pl_brand_archive.py

  • Step 1: 改写失败用例为新期望,并新增通过用例

将 test_required_allows_only_that_brand 替换为下列测试(整文件相关用例如下;保留既有 any / no_brand / inventory 用例):

def test_required_allows_other_brand_when_sum_matches():
    validate_brand_qty_rows(
        brand_mode="required",
        required_brand_id="b1",
        actual_qty=Decimal("10"),
        rows=[{"brandId": "b2", "brandName": "红四方", "qty": Decimal("10")}],
    )


def test_required_allows_multi_brand_when_sum_matches():
    validate_brand_qty_rows(
        brand_mode="required",
        required_brand_id="b1",
        actual_qty=Decimal("10"),
        rows=[
            {"brandId": "b1", "brandName": "君正", "qty": Decimal("6")},
            {"brandId": "b2", "brandName": "红四方", "qty": Decimal("4")},
        ],
    )


def test_required_sum_must_match():
    with pytest.raises(ValueError, match="合计"):
        validate_brand_qty_rows(
            brand_mode="required",
            required_brand_id="b1",
            actual_qty=Decimal("10"),
            rows=[
                {"brandId": "b1", "brandName": "君正", "qty": Decimal("6")},
                {"brandId": "b2", "brandName": "红四方", "qty": Decimal("3")},
            ],
        )
  • Step 2: 运行测试确认旧实现失败

Run:

cd backend && source venv/bin/activate && pytest tests/test_pl_brand_archive.py::test_required_allows_other_brand_when_sum_matches tests/test_pl_brand_archive.py::test_required_allows_multi_brand_when_sum_matches tests/test_pl_brand_archive.py::test_required_sum_must_match -v

Expected: test_required_allows_other_brand_when_sum_matches 与 test_required_allows_multi_brand_when_sum_matches FAIL(仍抛「指定品牌时只能填写该品牌数量」);test_required_sum_must_match 可能 FAIL 或因先撞上旧错误而 match 失败。

  • Step 3: 实现最小校验改动

将 validate_brand_qty_rows 中 required / any 合并为合计校验(保留 required_brand_id 参数以免改签名,但不再使用):

def validate_brand_qty_rows(
    *,
    brand_mode: Optional[str],
    required_brand_id: Optional[str],
    actual_qty: Decimal,
    rows: list[dict],
) -> None:
    actual_qty = Decimal(str(actual_qty))
    if not brand_mode:
        return
    if brand_mode in ("required", "any"):
        total = sum((Decimal(str(r.get("qty") or 0)) for r in rows), Decimal("0"))
        if total != actual_qty:
            raise ValueError("各品牌数量合计必须等于归档实际数量")
        return
    raise ValueError("无效的 brand_mode")

Note: required_brand_id 可保留为未使用参数(加 # noqa: ARG001 或前缀 _ 若项目 lint 要求)。优先保留关键字名以免破坏调用方。

  • Step 4: 跑通品牌归档测试

Run:

cd backend && source venv/bin/activate && pytest tests/test_pl_brand_archive.py tests/test_pl_feedback_brand_qty.py -v

Expected: PASS

  • Step 5: Commit
git add backend/app/services/pl_brand_archive.py backend/tests/test_pl_brand_archive.py
git commit -m "$(cat <<'EOF'
fix(pl): treat required brand as preference in brand qty validation

Allow multi-brand feedback/archive rows when plan brandMode is required; only enforce sum equals actual qty.
EOF
)"

Task 2: Frontend — BrandQtyChipsField 统一多选

Files:

  • Modify: web-admin/src/components/business/brand-qty-chips-field/index.vue

  • Step 1: 标题与芯片区改为两种模式共用多选

模板改动要点:

  1. 标题固定为「选择品牌并填量」(去掉 required 分支文案)。
  2. 芯片列表条件改为 v-if="brandMode === 'any' || brandMode === 'required'"(删除 v-else-if="brandMode === 'required'" 锁定芯片块)。
  3. activeRows 始终返回 props.modelValue(删除 required 强制单行逻辑)。
  4. toggleChip 允许在 required 下切换:
function toggleChip(opt: BrandOption) {
  if (props.disabled || (props.brandMode !== 'any' && props.brandMode !== 'required')) return
  const selected = isSelected(opt.brandId)
  if (selected) {
    clearQtyDraft(opt.brandId)
    emitRows(props.modelValue.filter((r) => r.brandId !== opt.brandId))
    return
  }
  emitRows([...props.modelValue, { brandId: opt.brandId, brandName: opt.brandName, qty: 0 }])
}
  1. requiredBrandLabel 计算属性若已无模板引用可删除;requiredBrandId prop 保留供父级语义/将来提示,组件内不再用于锁定。
  • Step 2: 本地快速自检(无自动化组件测时)

确认文件内不存在:指定品牌填量、chip--locked 模板引用、brandMode === 'required' 专用锁定分支(样式类可留)。

  • Step 3: Commit
git add web-admin/src/components/business/brand-qty-chips-field/index.vue
git commit -m "$(cat <<'EOF'
fix(web-admin): allow multi-brand chips when plan brand is required

Treat required like any in BrandQtyChipsField so preference brand is not locked.
EOF
)"

Task 3: 归档弹窗 — required 加载全品牌并预选

Files:

  • Modify: web-admin/src/components/business/pl-plan-archive-dialog/index.vue

  • Step 1: 删除 syncRequiredBrandQty 及其 watch

删除函数 syncRequiredBrandQty、对 productRows 的 deep watch,以及 onArchiveBrandActualQty 中仅 any 才回写的限制。改为有品牌模式时合计均回写实际数量:

function onArchiveBrandActualQty(row: PlanFormProductRow, val: number) {
  if (row.brandMode === 'any' || row.brandMode === 'required') {
    row.actualQty = Number(val)
  }
}
  • Step 2: 改写 initBrandQtyRows

对 any 与 required 都拉取产品详情品牌列表;required 无已保存明细时预选偏好品牌:

async function initBrandQtyRows(rows: PlanFormProductRow[]) {
  const needDetailIds = [
    ...new Set(
      rows
        .filter(
          (row) =>
            (row.brandMode === 'any' || row.brandMode === 'required') && row.productId
        )
        .map((row) => row.productId)
    )
  ]
  const detailMap = new Map<string, ProductDetail>()
  await Promise.all(
    needDetailIds.map(async (productId) => {
      try {
        const res = await fetchProductDetail({ id: productId })
        const detail = pickBxData<ProductDetail>(res)
        if (detail?.id) detailMap.set(productId, detail)
      } catch {
        // 提交时由后端校验
      }
    })
  )

  rows.forEach((row) => {
    const actual = Number(row.actualQty ?? 0)
    if (row.brandMode !== 'any' && row.brandMode !== 'required') return

    const brands = (detailMap.get(row.productId)?.brands || []).filter(
      (b) => (b.status || 'on') === 'on'
    )
    row.brandOptions = brands.map((b) => ({
      brandId: b.id || '',
      brandName: b.brandName || ''
    }))

    if (row.brandMode === 'required' && row.brandId) {
      const name =
        row.brandName ||
        row.brandOptions.find((o) => o.brandId === row.brandId)?.brandName ||
        '指定品牌'
      // 确保偏好品牌在 options 中(停用品牌仍可预选展示)
      if (!row.brandOptions.some((o) => o.brandId === row.brandId)) {
        row.brandOptions = [
          { brandId: row.brandId, brandName: name },
          ...row.brandOptions
        ]
      }
      row.brandQtyRows = [{ brandId: row.brandId, brandName: name, qty: actual }]
      return
    }

    // any:仅单品牌时预填
    if (row.brandOptions.length === 1) {
      row.brandQtyRows = [
        {
          brandId: row.brandOptions[0].brandId,
          brandName: row.brandOptions[0].brandName,
          qty: actual
        }
      ]
      row.actualQty = actual
    } else {
      row.brandQtyRows = []
    }
  })
}

保留归档区「指定品牌」el-tag 提示(偏好说明),不要删除。

  • Step 3: Commit
git add web-admin/src/components/business/pl-plan-archive-dialog/index.vue
git commit -m "$(cat <<'EOF'
fix(web-admin): archive dialog loads all brands for required preference

Preselect preferred brand but allow multi-brand qty entry like any mode.
EOF
)"

Task 4: 管理端司机回传弹窗

Files:

  • Modify: web-admin/src/components/business/pl-plan-driver-feedback-dialog/index.vue

  • Step 1: 去掉实际数量改动时强制写死指定品牌行

删除或清空 onActualQtyChange 中 required 特殊分支(若模板仍绑定,改为空函数或直接绑定 syncRowActualQty 即可)。有品牌时实际数量应由 BrandQtyChipsField 的 update:actualQty 驱动。

  • Step 2: buildProductRows 为 required 也加载全品牌 options

将:

[...new Set(products.filter(p => p.brandMode === 'any' && p.productId).map(p => p.productId))]

改为同时包含 required:

;[
  ...new Set(
    products
      .filter(
        (p) => (p.brandMode === 'any' || p.brandMode === 'required') && p.productId
      )
      .map((p) => p.productId)
  )
]

并将:

const brandOptions =
  prod.brandMode === 'any'
    ? brandOptionMap.get(prod.productId) || []
    : prod.brandId
      ? [{ brandId: prod.brandId, brandName: prod.brandName || '指定品牌' }]
      : []

改为:

let brandOptions =
  prod.brandMode === 'any' || prod.brandMode === 'required'
    ? brandOptionMap.get(prod.productId) || []
    : []
if (
  prod.brandMode === 'required' &&
  prod.brandId &&
  !brandOptions.some((o) => o.brandId === prod.brandId)
) {
  brandOptions = [
    { brandId: prod.brandId, brandName: prod.brandName || '指定品牌' },
    ...brandOptions
  ]
}
  • Step 3: 改写 mapBrandQtyRows 的 required 分支

有已保存正数量明细时,直接回显全部(可多品牌);否则仅预选偏好品牌一行:

if (prod.brandMode === 'required') {
  if (savedPositive.length) return savedPositive
  const brandId = prod.brandId || ''
  if (!brandId) return []
  const brandName =
    prod.brandName ||
    brandOptions.find((o) => o.brandId === brandId)?.brandName ||
    '指定品牌'
  return [{ brandId, brandName, qty: seedActualQty }]
}

any 分支保持现有逻辑不变。

  • Step 4: Commit
git add web-admin/src/components/business/pl-plan-driver-feedback-dialog/index.vue
git commit -m "$(cat <<'EOF'
fix(web-admin): driver feedback dialog multi-brand for required preference

Load full brand options and preselect preferred brand without locking.
EOF
)"

Task 5: 计划详情现场编辑 + 公开页

Files:

  • Modify: web-admin/src/components/business/pl-plan-view-tabs/index.vue

  • Modify: web-admin/src/views/public/pl/transport/index.vue(若需)

  • Modify: web-admin/src/views/public/pl/_shared/PublicIoOrderPage.vue(若需)

  • Step 1: pl-plan-view-tabs — mapIoItemBrandQtyRows

现场 API 已返回全量 brandOptions。确保 required:

  • 有 brandQtys 正数量 → 回显多行
  • 否则 → 仅预选 brandId 一行(现有逻辑已接近,确认不要把 options 裁成单品牌)

若存在把 brandOptions 裁成单元素的代码,删除之。BrandQtyChipsField 已在 Task 2 放开多选。

  • Step 2: 公开页

transport/index.vue 与 PublicIoOrderPage.vue 的 mapBrandQtyRows 已在无保存数据时预选 required 品牌;brandOptions 来自公开 API 全量列表。确认:

  • 未再把 brandOptions 覆盖为单品牌
  • brandModeForField 仍可返回 'required'(组件内按多选处理)
  • 前端校验仍只检查「至少一正数量 + 合计=实际」,不检查必须含指定品牌

无需为公开页重复实现 options 拉取,除非实测 brandOptions 为空。

  • Step 3: Commit
git add web-admin/src/components/business/pl-plan-view-tabs/index.vue \
  web-admin/src/views/public/pl/transport/index.vue \
  web-admin/src/views/public/pl/_shared/PublicIoOrderPage.vue
git commit -m "$(cat <<'EOF'
fix(web-admin): align site/driver public brand qty with preference semantics

Ensure required mode keeps full brand options and multi-select entry.
EOF
)"

若某文件无实际 diff,勿强行 git add 空提交;可把有改动的文件单独提交。


Task 6: Demo 文案 + 回归

Files:

  • Modify: docs/demos/pl-site-driver-brand-qty-demo.html

  • Step 1: 修正规则预览文案

将:

③ 各品牌数量合计 = 该产品实际数量;不限品牌时可多选品牌,指定品牌时仅允许该品牌一行。

改为:

③ 各品牌数量合计 = 该产品实际数量;不限品牌与指定品牌(偏好)均可多选品牌,指定品牌默认预选且可取消。
  • Step 2: 后端全量相关测试

Run:

cd backend && source venv/bin/activate && pytest tests/test_pl_brand_archive.py tests/test_pl_feedback_brand_qty.py -v

Expected: PASS

  • Step 3: 手工验收清单(打勾)
  1. 计划产品指定品牌 → 司机公开链接:默认预选该品牌,可取消、可加其他品牌,保存成功
  2. 同上现场公开链接
  3. 运输计划归档弹窗同上
  4. 管理端司机回传补录同上
  5. any / 无品牌产品行为与改前一致
  • Step 4: Commit
git add docs/demos/pl-site-driver-brand-qty-demo.html
git commit -m "$(cat <<'EOF'
docs: update brand qty demo copy for required-as-preference

EOF
)"
  • Step 5: 更新 graphify(若本会话改了代码文件)
./scripts/update-graph.sh all

Spec coverage checklist

Spec 要求 Task
validate_brand_qty_rows required 与 any 合计校验 Task 1
required 多品牌 / 非指定品牌可通过 Task 1
BrandQtyChipsField 多选、去锁定 Task 2
标题「选择品牌并填量」 Task 2
归档加载全品牌 + 预选偏好 + 去 sync Task 3
保留「指定品牌」提示 tag Task 3
司机回传弹窗全品牌 + 预选 Task 4
现场编辑 / 公开页对齐 Task 5
Demo 文案 Task 6
不改计划创建存库语义 (无任务改 form/quote/contract)
不做必须包含指定品牌 Task 1/前端校验均未加此规则

Out of scope

  • 计划 / 报价 / 合同建单品牌字段语义与 UI
  • 数据库迁移
  • 强制回填必须包含指定品牌