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>
16 KiB
指定品牌回填改为偏好提示 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: 标题与芯片区改为两种模式共用多选
模板改动要点:
- 标题固定为「选择品牌并填量」(去掉
required分支文案)。 - 芯片列表条件改为
v-if="brandMode === 'any' || brandMode === 'required'"(删除v-else-if="brandMode === 'required'"锁定芯片块)。 activeRows始终返回props.modelValue(删除required强制单行逻辑)。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 }])
}
requiredBrandLabel计算属性若已无模板引用可删除;requiredBrandIdprop 保留供父级语义/将来提示,组件内不再用于锁定。
- 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: 手工验收清单(打勾)
- 计划产品指定品牌 → 司机公开链接:默认预选该品牌,可取消、可加其他品牌,保存成功
- 同上现场公开链接
- 运输计划归档弹窗同上
- 管理端司机回传补录同上
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
- 数据库迁移
- 强制回填必须包含指定品牌