基于客户标签的商城分类与商品可见性过滤全链路总览 (Category & Product Visibility Filter)
对应开发 Issue：#24 P1-REQ-03 基于客户标签的商城分类与商品可见性过滤
核心定制模块：3will_website_sale_category_customer_filter
依赖模块：base,website_sale,3will_website_sale_base,3will_website_sale_on_behalf_order
适用角色：电商运营主管、商品主档管理员、销售业务经理、系统管理员
1. 业务背景与核心痛点
在大型综合性 B2B 批发与供应链贸易中，企业往往服务于多种完全异构的客户群体。例如：
- 餐饮连锁与中餐馆：采购 5KG 餐饮特制浓缩火锅底料、特大包装冷冻食材、专业后厨耗材；
- 西人主流超市与精品烘焙工坊：采购 250G 澳洲天然发酵黄油、西式冷冻面团、零售精装进口选品；
- 普通贸易商与日化零售店：采购通用粮油副食、日用百货。
在未启用客群分类过滤的原生 Odoo 环境中，存在以下突出的业务与运营痛点：
┌──────────────────────────────────────────┐
│ 原生 Odoo 统一商城商品展示的业务痛点 │
└────────────────────┬─────────────────────┘
│
┌────────────────────────────────────┼────────────────────────────────────┐
▼ ▼ ▼
┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐
│ 客群视野干扰与采购噪音 │ │ 跨客群商业信息泄漏风险 │ │ 商品主档管理维护噩梦 │
│ │ │ │ │ │
│ 餐饮客户在侧边栏看到西式 │ │ 西人超市看到餐饮特供大包 │ │ 若在每一个商品主档上打标 │
│ 烘焙面团，西人超市看到后 │ │ 装底料报价，引发比价质疑与 │ │ 控制，数万 SKU 重复维护，│
│ 厨火锅大桶油，选品效率低。│ │ 渠道窜货纠纷。 │ │ 人工极易疏漏且配置成本高。│
└──────────────────────────┘ └──────────────────────────┘ └──────────────────────────┘
为解决上述挑战，定制开发了 3will_website_sale_category_customer_filter 模块，构建起基于公开分类收敛、零侵入商品主档、层级递归继承、严格子集约束、四重服务拦截与销售代客无缝联动的企业级客群隔离过滤体系。
2. 核心架构设计与防线体系
【客户进入 B2B 商城 /shop 选品】
│
▼
【第 1 道防线：伙伴标签与代客上下文解析】
解析当前访问主体（普通门户客户 vs 销售人员代客上下文）
提取其实际生效的客户标签（如 [餐厅] 或 [西人超市]）
│
┌──────────────────────┴──────────────────────┐
▼ ▼
[未代客的内部销售人员] [外部客户 / 代客模式]
豁免一切过滤，全库商品与 计算客户允许访问的公开分类集合
全量分类树完整呈现 (全景模式) Allowed Category IDs
│
▼
【第 2 道防线：侧边栏分类树剪枝】
递归修剪侧边栏导航树与折叠手风琴，
仅渲染允许集合内的分类节点
│
▼
【第 3 道防线：商品列表与搜索过滤】
商品列表页与模糊搜索强制执行并集规则，
排除仅属于未授权分类的商品 SKU
│
▼
【第 4 道防线：URL 越权访问重定向】
用户若通过浏览器书签或恶意直连未授权
分类或商品页面，服务端一律 302 重定向
2.1 六大核心设计原则
| 编号 | 核心设计原则 | 业务价值与技术实现机制 |
|---|---|---|
| P-01 | 零侵入商品主档 (Zero Intrusion) | 无需在商品主档（product.template）增加任何权限字段。所有客群访问控制规则完全收敛在电商公开分类（product.public.category）上。商品只需挂载在相应公开分类下，自然具备分类的权限属性。 |
| P-02 | 未配即通用 (Universal by Default) | 顶级分类若不配置“适用客户标签”，默认对全平台所有注册客户和访客通用开放，极大降低基础品类的配置成本。 |
| P-03 | 层级自动继承 (Hierarchical Inheritance) | 子分类若未单独指定标签，自动递归继承上级分类的生效标签；子分类单独指定标签时，必须遵循“子集法则”。系统自动计算并展示清晰的“实际生效客户标签”。 |
| P-04 | 严格子集约束 (Strict Scope Constraint) | 后台设置 @api.constrains 强校验：子分类配置的客群范围必须是父分类客群范围的子集，不得越界放大。若操作员误配，系统抛出友好对话框阻断，杜绝“断头树”逻辑漏洞。 |
| P-05 | 商品并集可见 (Union Principle) | 当一个商品同时挂载在多个分类时（如某调味品同时属于“通用调味品”与“餐饮专用底料”），只要客户对其中任一分类拥有访问权限，该商品在前台即正常展示。 |
| P-06 | 销售代客动态跟随 (On-Behalf Integration) | 销售员未代客时拥有上帝视角，可全库检索与导购；当销售员进入“代客下单（On-Behalf）”模式选中某客户时，商城界面秒级切换为该客户的受限专属目录，所见即客户所见。 |
3. 业务全景泳道流程图 (Workflow)
4. 真实系统界面实况展示 (Screenshots)
本章节所有界面截图均采集自 Odoo 19 容器化测试环境（数据库：wt_issue_24_category_catalog_filter_db，服务端口：8075），采用真实餐饮及西人超市企业数据实测验证。
4.1 后台公开分类客群标签配置
图 7.9.1：在公开分类表单中，直接为“西式烘焙与进口选品”分配适用客户标签【西人超市】。系统自动计算“生效可见性”为“🔒 本级指定: 西人超市”，并在界面实时显示锁定标识。
4.2 子分类范围越界校验阻断
图 7.9.2：当主档管理员误将父分类为【西人超市】的子分类配置上【餐厅】标签时，系统保存时即刻触发严密的 Python 约束校验，弹出友好的阻断错误提示，杜绝权限配置越界。
4.3 餐厅客户与西人超市客户的前台视角隔离对比
| 餐厅客群客户视角 (100 DEGREE HOT POT) | 西人超市客户视角 (ROMEOS RETAIL GROUP) |
|---|---|
 |  |
| 侧边栏仅展示：通用食品日化、餐饮大包装与冷冻； 彻底隐藏：西式烘焙与进口选品。 | 侧边栏仅展示：通用食品日化、西式烘焙与进口选品； 彻底隐藏：餐饮大包装与冷冻。 |
图 7.9.3 & 7.9.4：不同客群客户登录商城后，侧边栏分类树自动剪枝，列表仅展示各自专属或共享通用的商品。
4.4 搜索彻底隔离与直接 URL 拦截防护
| 关键词搜索彻底隔离 | 未授权直接 URL 访问拦截 |
|---|---|
 |  |
| 餐厅客户搜索西人专属商品“发酵黄油”，服务端并集过滤生效，明确返回 0 件商品 (No results)。 | 客户尝试直接在地址栏敲入未授权分类路由，系统瞬间执行 302 拦截，安全重定向回 /shop 主页。 |
图 7.9.5 & 7.9.6：杜绝了任何通过前台搜索补全、模糊匹配或直接访问 URL 窥探未授权商品的可能。
4.5 销售人员代客下单（On-Behalf）视角动态切换
图 7.9.7：销售人员（Administrator）进入代客下单模式并绑定“100 DEGREE HOT POT”后，顶部显示蓝色代客横幅，全景视角瞬间收敛为该客户专属的餐饮分类视角，确保销售代客录单与客户真实视野完全一致。
5. 本模块文档导航矩阵
为帮助不同岗位的操作人员熟练掌握配置与排障，本特性提供完整的 4 篇操作规范手册与业务政策指南：
┌────────────────────────────────────────────────────────────────────────┐
│ 7.9 客群分类过滤文档体系 │
└───────────────────────────────────┬────────────────────────────────────┘
│
┌───────────────────────────────┼───────────────────────────────┐
▼ ▼ ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│ 10-sop-category-tag │ │ 20-sop-customer-tag │ │ 30-sop-isolation-and │
│ -configuration.md │ │ -binding.md │ │ -sales-on-behalf.md │
│ │ │ │ │ │
│ 【分类主档配置手册】 │ │ 【客户打标与验证手册】│ │ 【防线与销售代客手册】│
│ • 公开分类标签维护 │ │ • 商业伙伴标签设定 │ │ • 搜索隔离与 URL 拦截 │
│ • 递归继承状态推导 │ │ • 前台视角比对验收 │ │ • 销售代客全景切换 │
│ • 子集约束错误排除 │ │ • 并集商品归属管理 │ │ • 购物车与结算联动 │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
│
▼
┌───────────────────────┐
│ 40-policy-and-faq.md │
│ │
│ 【业务政策与排障指南】│
│ • 访问控制仲裁真值表 │
│ • 核心规则决策记录 │
│ • 常见排障与 FAQ 问答 │
└───────────────────────┘
- 👉 7.9.1 电商品类客群标签配置与层级继承 SOP (Category Tag SOP)：电商公开分类标签录入、继承推导逻辑、子集防越界报错处理指南。
- 👉 7.9.2 客户客群标签打标与商城视角验证 SOP (Customer Tag SOP)：商业伙伴标签绑定、多客群前台展示比对、多分类商品并集法则落地。
- 👉 7.9.3 搜索隔离、防越权拦截与销售代客 SOP (Isolation & On-Behalf SOP)：前台关键词检索防护、直接 URL 重定向拦截机制、销售人员代客下单实时视角跟随实操。
- 👉 7.9.4 客群隔离业务政策、算法矩阵与常见问题 (Policy & FAQ)：多客群访问权限判定真值表、架构设计权衡、实施与运维常见问题清单。