extension-slots

name	extension-slots
description	MallBase 扩展槽边界规范；涉及会员、积分、分销、余额、优惠等权益扩展接入订单、商品编辑或 UniApp 展示时使用。

扩展槽边界规范

适用场景

当需求涉及以下任一方向时，优先使用本规则：

• 订单金额计算新增权益项，例如会员优惠、积分抵扣、优惠券、余额权益、分销相关金额。
• 订单状态流转新增副作用，例如支付后冻结、完成后发放、关闭后回滚、退款后扣回。
• 后台商品编辑页新增营销字段或 SKU 级权益字段。
• UniApp 商品详情、规格弹窗、订单确认页新增权益展示。
• 现有会员、积分、分销、余额能力需要接入统一扩展点。

后端规则

1. 订单金额扩展优先实现 OrderPriceContributorInterface，通过 OrderPricePipeline 接入。
2. 订单状态副作用优先实现 OrderEventListenerInterface，通过 OrderEventDispatcher 接入。
3. 新扩展默认注册在 ExtensionRegistry，不要把新权益逻辑直接堆回 OrderService、OrderStatusMachine 或 RefundOrderStatusMachine。
4. 扩展实现必须保持 Service 无状态，不能依赖实例属性保存请求态。
5. 扩展中的落库副作用必须幂等，尤其是支付、完成、关闭、退款等可重复触发的事件。
6. 金额扩展必须以分为边界做精确分配，避免浮点误差；返回给前端的金额统一保留两位小数。
7. 多个扩展同时作用于订单金额时，必须明确优先级，避免互相覆盖或重复扣减。
8. 不要为了单次、局部、不会复用的逻辑强行新增扩展点；局部简单逻辑可以留在原模块内。

后台商品编辑规则

1. 商品营销字段、SKU 扩展字段优先集中在 frontend/admin/apps/web-antd/src/views/goods/goods/extension-slots.ts。
2. goods-edit.vue 和 useGoodsEdit.ts 只负责渲染、透传、批量应用、提交转换，不再散落具体权益字段判断。
3. 新增 SKU 字段必须同时覆盖默认值、编辑回填、批量设置、提交转换和列显隐。
4. 字段显隐必须由功能开关和当前表单模式共同决定，避免功能关闭后仍提交隐藏字段。

UniApp 规则

1. 商品详情、规格弹窗、订单确认页的权益展示优先集中在 frontend/uniapp/utils/extension-slots.js。
2. 展示层只消费扩展槽返回的展示项，避免每个页面重复判断会员价、积分赠送、成长值等细节。
3. 订单确认页的权益卡片、商品行提示、价格汇总行应从同一扩展状态构建，避免展示和提交金额不一致。
4. 新增可交互权益项时，必须明确默认状态、禁用条件、提交参数和接口预览结果的对应关系。

测试要求

1. 后端新增价格贡献器或事件监听器时，至少补充管线或监听器单测。
2. 影响订单主链路时，必须覆盖预览、创建、支付、完成、关闭或退款中的相关边界。
3. 影响前端展示时，至少执行对应前端构建；涉及真实用户链路时，用本地接口和浏览器抽样验证。
4. 如果只调整扩展槽结构但不改变行为，测试可以聚焦在原有合同不变和关键页面不报错。

反模式

• 在 OrderService::calculateAmounts() 中继续追加会员、积分、分销、优惠券等分支。
• 在状态机里直接调用具体业务 Service，绕过统一事件分发。
• 前端多个页面分别复制同一套会员价、积分赠送、成长值判断。
• 功能开关关闭后仍显示字段、提交字段或触发副作用。
• 为一次性页面排版创建新的扩展槽，增加不必要复杂度。