主数据服务设计（Master Data Service Design - MDS-D）¶
文档编号：DOC-P51-D / MDS-D 版本：V1.5 创建日期：2026-08-05 最后更新：2026-08-26 维护人：BO / TL / DT 关联文档：README.md、业务架构说明 BAS、QSV、CPT、DIS 派单服务、OPS、TND、RQD、RNV 装修服务特征库、SCAT 服务目录清单、EVAL 单证流程评估、CCRR 交叉一致性审查
V1.5 升级摘要（SCAT 服务目录视图层纳入 + SCL/DLV 同步修订）： - 基于 SCAT V1.1 服务目录清单设计，新增 SCAT 为七库的统一服务目录视图层（非主数据子库，仅提供查询视图） - SCAT 聚合 SCL（标准安装）+ RNV（装修工程）+ MTN 维修服务（CAT-10，对齐 SCL CAT-01~09 维修版）+ DLV（配送）形成 CST/MFR 双视角服务目录 - §四 七库总览新增 SCAT 行（视图层，DOC-P53），SCL 行同步更新（V1.2 新增 CAT-10 MTN 维修 + F1-F4 故障级别费率矩阵），DLV 行同步更新（V1.2 配送范围收窄为内地→香港） - 关联文档新增 SCAT V1.1
V1.4 升级摘要（RNV 装修服务特征库纳入七库总览）： - 基于 EVAL V1.0 2.4 修改项（装修工程新增 CAT-09）独立成 RNV V1.0 装修服务特征库，MDS 六库扩展为七库 - 原 §四 六库总览 → 七库总览，新增 RNV 装修服务特征库（6 大分部 + 4 个装修专用复杂度维度 + 主材工料分离 + 多版本报价模板） - §1.1 服务定位：六类→七类主体档案；§1.2 核心概念：六库→七库；§3.2 实体清单：新增 RenovationCatalog；§3.3 VO 清单：新增 RenovationFactor VO - §3.4 领域服务：SixLibraryCRUDService → SevenLibraryCRUDService；§3.6 仓储：新增 RenovationCatalogRepository - RNV 与 SCL 边界：RNV「安装工程」分部引用 SCL 主体；RNV 自身维护装修工程特有的分部维度（拆除难度/新建结构/水电隐蔽/楼梯形式）
V1.3 升级摘要（V8.0 韩段二-5 DDD 重构 + 六库补全）： - 新增 §二 DDD 战略设计（子域定位 + BC + 上下文映射 + ACL），模板遵循 BAS §六 DDD 实施规范 - 新增 §三 DDD 战术设计（聚合根 MasterDataCatalog + 6 实体 + 8 VO + 5 领域服务 + 8 领域事件 + 仓储工厂 + 状态机） - 原 §二 四库总览 → §四 六库总览，新增 PPL 生产商档案库 + DLV 物流商档案库 - 原 §三~§八 章节编号整体 +2（§三→§五、§四→§六、§五→§七、§六→§八、§七→§九、§八→§十） - 遗留修复：原 §4.3 DSP → DIS 派单服务，对齐 V8.0 架构；原数据闭环图 DSP → DIS
V1.2 升级摘要（V8.0 阶段一派单服务独立化）： - §3.2 不负责职责表「派单匹配算法」归属服务由 DSP 改为 DIS 派单服务，对齐 TL C8 业务架构解耦指示 - MDS 六库（SCL/BPL/WPL/CPL/PPL/DLV）继续作为主数据底座，向 DIS 供给 DLV 业务模式分类 + M3 字段子表 + 保险赔付记录 DLV-019
一、定位与核心概念¶
1.1 服务定位¶
主数据服务（MDS）是平台的主体档案中心——统一管理师傅、客户、安装服务品类、楼宇、生产商、物流商、装修工程七类核心主数据，为各业务服务提供共享主数据支撑。
MDS 与 CPT 的核心区别： - MDS 存储"主体"：师傅/客户/品类/楼宇/生产商/物流商的长期属性档案，生命周期长于单次交易 - CPT 存储"过程"：单次客户项目的全生命周期记录（L1~L8 阶段） - 关系：CPT 通过 ID 引用 MDS 中的主体档案；CPT 采集的实际数据反哺 MDS 画像更新
1.2 核心概念¶
| 概念 | 定义 | 说明 |
|---|---|---|
| 主数据 | 平台核心主体对象的属性档案 | 师傅/客户/品类/楼宇/生产商/物流商/装修工程，跨服务共享、长期存在 |
| 主体 vs 过程 | 主体档案 vs 单次交易过程 | MDS=主体；CPT=过程；二者通过 ID 关联 |
| 七库 | MDS 下设七个特征库 | SCL 服务库 / BPL 楼宇库 / WPL 师傅库 / CPL 客户库 / PPL 生产商库 / DLV 物流商库 / RNV 装修工程库 |
| 数据闭环 | CPT 采集数据反哺 MDS 画像 | 实际工时→师傅画像；评分→师傅等级；楼宇核实→楼宇档案；成交价偏差→品类费率；装修实际工时→RNV 复杂度维度校准 |
1.3 双重价值¶
- 共享主数据源：消除各业务服务的数据孤岛，确保七类主体信息全平台一致。
- 画像持续进化：基于 CPT 采集的实际运营数据，持续校准师傅等级、客户标签、楼宇系数、品类费率、生产商评级、物流商评分、装修复杂度维度。
二、DDD 战略设计（新增）¶
本章节模板遵循 BAS §六 DDD 实施规范。子域边界成熟期前不轻易变更，变更须 TL 审批并升级 BAS 版本。
2.1 子域定位¶
| 子域名称 | 子域类型 | 核心价值 | 对应 BC |
|---|---|---|---|
| 主数据供给 | 核心子域 | 七库主体档案的唯一权威来源，全平台共享底座 | MasterData BC |
| 标签体系管理 | 支撑子域 | 按 TSMM 标准管理四库标签，确保分类一致 | LabelManagement BC（共享 TSMM） |
子域说明： - 主数据供给为核心子域：所有业务服务（QSV/CPT/DIS/OPS）均强依赖 MDS 提供的主体档案与系数因子，是报价、派单、跟踪、营销的前置条件。 - 标签体系管理为支撑子域：通过共享内核（SK）模式与 TSMM 标签体系元模型 对齐，SCL/BPL/WPL/CPL 的标签分类、隐私规则、版本机制统一由 TSMM 定义。
2.2 限界上下文（BC）¶
graph TD
subgraph MDS["MDS 主数据服务限界上下文"]
direction LR
MDBC["MasterData BC<br/>(主数据供给核心)<br/>聚合根：MasterDataCatalog<br/>七库 CRUD + 校准 + 供给"]
LMBC["LabelManagement BC<br/>(标签体系支撑)<br/>对接 TSMM 共享内核<br/>标签 CRUD + 版本 + 隐私"]
MDBC -- "SK 共享标签标准" --> LMBC
end
subgraph EXT["外部服务 BC"]
QSVBC["QSV 报价决策 BC"]
CPTBC["CPT 客户跟踪 BC"]
DISBC["DIS 派单决策 BC"]
OPSBC["OPS 获客运营 BC"]
TSMBC["TSMM 标签元模型 BC"]
end
MDBC -- "OHS 开放主机服务" --> QSVBC
MDBC -- "OHS + ACL 反哺" --> CPTBC
MDBC -- "OHS 开放主机服务" --> DISBC
MDBC -- "OHS 开放主机服务" --> OPSBC
LMBC -- "SK 共享内核" --- TSMBC2.3 上下文映射模式¶
| 对端 BC | 映射模式 | MDS 角色 | 说明 |
|---|---|---|---|
| QSV 报价决策 | OHS（开放主机服务） | 上游 | MDS 主动暴露标准供给 API（品类费率、楼宇系数、师傅等级系数），QSV 按契约消费 |
| CPT 客户跟踪 | OHS + ACS（客户供应商） | 上游 + 下游 | 正向：MDS→CPT 供给主体 ID（OHS）；反向：CPT→MDS 反哺实际数据（ACS，CPT 为供应商，MDS 消费校准数据） |
| DIS 派单决策 | OHS（开放主机服务） | 上游 | MDS 暴露 DLV 业务模式分类、M3 合同字段子表、保险赔付记录；DIS 按契约消费 |
| OPS 获客运营 | OHS（开放主机服务） | 上游 | MDS 暴露 CPL 客户标签/信任徽章、WPL 师傅个人品牌资料；OPS 精准营销消费 |
| TSMM 标签元模型 | SK（共享内核） | 合作者 | 标签分类框架、隐私规则、数据字典共享，SCL/BPL/WPL/CPL 标签结构统一对齐 TSMM |
2.4 防腐层（ACL）VO 定义¶
MDS 作为上游，消费 CPT 反哺数据时建立 ACL，将 CPT 过程模型转换为 MDS 主体画像模型：
| ACL 目标 VO | 来源 CPT 字段 | 转换规则 | 消费方 |
|---|---|---|---|
| CatalogFactor VO | CPT 成交价 vs QSV 报价、L6 实际工时 | 计算偏差率 → 生成 SCL 费率校准建议 | SCL 校准引擎 |
| BuildingFactor VO | CPT L2 楼宇核实结果（电梯/楼层/管理要求） | 对比原 BPL 档案，生成差异修正记录 | BPL 楼宇库 |
| WorkerFactor VO | CPT L6 实际工时、L8 NPS 评分、L6 异常次数 | 月度综合评分 → 跨阈值触发等级变更 | WPL 师傅库 |
| CustomerFactor VO | CPT L4 签约行为、L7 验收、L8 复购/推荐意向、NPS 分数 | 实时更新标签 + 月度徽章复核 | CPL 客户库 |
| LogisticsFactor VO | CPT L5 配送时效、L5 破损记录、DIS C7 保险赔付记录 | 计算 DLV 综合评分 → 影响 M2/M3 派单权重 | DLV 物流商库 |
三、DDD 战术设计（新增）¶
3.1 聚合根：MasterDataCatalog¶
唯一标识：catalogId（全局七库档案聚合入口，MDS-服务级单例）
不变量（Invariants）：
1. 档案唯一性：七库中任一主体档案，(libraryCode, businessKey) 组合全局唯一（libraryCode=SCL/BPL/WPL/CPL/PPL/DLV/RNV）
2. ID 编码规范一致性：所有档案 ID 严格遵循 {lib}-{yyyyMMdd}-{NNNN} 格式，禁止自定义编码
3. 标签版本严格递增：SCL/BPL/WPL/CPL/RNV 的标签变更时，labelVersion 字段必须单调 +1，禁止回退
4. 隐私字段按 PDPO 脱敏：跨服务 API 返回 L3/L4 字段时必须经过 PrivacyDesensitizationService 处理，禁止明文输出
3.2 实体清单（7）¶
| 实体名称 | 所属库 | 唯一标识 | 核心字段 | 聚合边界 |
|---|---|---|---|---|
| ServiceCategory | SCL | sclId |
品类编码、类目层级、基础费率、产品参数映射、技能要求矩阵 | 独立聚合根条目 |
| BuildingProfile | BPL | bplId |
楼宇名称、地址、类型系数、电梯配置、楼层区间、管理要求、最后核实日期 | 独立聚合根条目 |
| WorkerProfile | WPL | wplId |
师傅姓名、等级（SK1/SK2/SK3）、技能矩阵、服务区域、可用时段、历史评分、收入 | 独立聚合根条目 |
| CustomerProfile | CPL | cplId |
客户姓名、联系方式、五维标签、信任徽章、复购意向、推荐关系链 | 独立聚合根条目 |
| ProducerProfile | PPL | pplId |
生产商名称、品牌等级、品类范围、合作条款、历史成交、质保条款 | 独立聚合根条目 |
| LogisticsProfile | DLV | dlvId |
物流商名称、业务模式（M1/M2/M3）、服务区域、M3 合同子表、C7 保险赔付记录 | 独立聚合根条目 |
| RenovationCatalog | RNV | rnvId |
分部编码（RNV-01~06）、细分类目、计价单位、复杂度维度（CD-DEMO/CD-BLDR/CD-HIDE/CD-STAIR）、主材工料分离规则、多版本报价模板 | 独立聚合根条目 |
3.3 值对象（VO）清单（9）¶
| VO 名称 | 适用实体 | 字段结构 | 说明 |
|---|---|---|---|
| MasterDataId VO | 全部 7 实体 | { libraryCode, datePart, sequence } |
ID 编码标准，序列化后即实体主键 |
| Label VO | SCL/BPL/WPL/CPL/RNV | { tagId, category, name, value, version, privacyLevel } |
对齐 TSMM，含隐私等级 L1~L4 |
| PrivacyLevel VO | 全部敏感字段 | { level: L1/L2/L3/L4, desensitizeRule } |
分级脱敏规则映射 |
| CatalogRateFactor VO | SCL | { baseFee, productParams[], skillRequirements[] } |
报价用品类费率因子 |
| BuildingCoefficient VO | BPL | { buildingType, floorMultiplier, hasElevator, managementPenalty } |
报价用楼宇系数因子 |
| SkillMatrix VO | WPL | { sclCategory[], levelMultipliers{}, maxDistanceKm, availabilitySlots[] } |
DIS 派单用技能矩阵 |
| TrustBadge VO | CPL | { badgeCode, badgeName, validFrom, validTo, evidenceRef } |
客户信任徽章，可核验 |
| LogisticsMode VO | DLV | { mode: M1/M2/M3, contractFields{}, insuranceClaims[] } |
DIS 派单用物流模式信息 |
| RenovationFactor VO | RNV | { divisionCode, unit, complexityDimensions[], mainMaterialSeparated, quoteTemplates[] } |
报价用装修分部因子，含 4 个装修专用复杂度维度（CD-DEMO/CD-BLDR/CD-HIDE/CD-STAIR）+ 主材工料分离标志 + 多版本报价模板（internal_cost/customer_facing/negotiated） |
3.4 领域服务清单（5）¶
| 领域服务名称 | 职责 | 输入 | 输出 | 调用方 |
|---|---|---|---|---|
| SevenLibraryCRUDService | 七库档案的增删改查 + 版本历史 | libraryCode + CRUD 操作 + 数据 |
操作结果 + 版本号 | OPR 运营后台、数据采集接口 |
| LabelManagementService | 标签 CRUD + 版本递增 + TSMM 合规校验 | 实体 ID + 标签变更集 |
变更后的 labelVersion |
CPT 反哺、OPS 客户分群 |
| MasterDataIdService | 七库 ID 编码生成 + 冲突检测 | libraryCode + date |
唯一 MasterDataId VO |
SevenLibraryCRUDService |
| PrivacyDesensitizationService | 按 L1~L4 分级对字段脱敏 | 原始数据 + 请求方服务标识 |
脱敏后数据（禁止反向解密） | 所有对外供给 API |
| SupplyAPIService | 向 QSV/CPT/DIS/OPS 暴露标准供给查询 | 消费方 + 因子类型 + ID 集合 |
对应 ACL VO 列表（CatalogFactor/BuildingFactor/WorkerFactor/CustomerFactor/LogisticsFactor/RenovationFactor） | QSV、CPT、DIS、OPS |
3.5 领域事件清单（8）¶
| 事件名称 | 触发时机 | 关键载荷 | 订阅方 |
|---|---|---|---|
| MasterDataCreated | SevenLibraryCRUDService 创建档案成功 | libraryCode + entityId + createdBy + timestamp |
OPS（新客户/师傅通知） |
| MasterDataUpdated | 档案核心字段变更（非标签） | libraryCode + entityId + changedFields{} + before/after |
QSV（费率/系数变更重算缓存） |
| MasterDataDeleted | 档案逻辑删除（极少发生） | libraryCode + entityId + reason + operator |
OPR 审计日志 |
| MasterDataLabelChanged | 标签变更（labelVersion 递增） | libraryCode + entityId + oldVersion + newVersion + deltaLabels[] |
OPS（客户分群重算）、WPL（等级校准触发） |
| BuildingCoefficientExpired | BPL 楼宇系数超季度未核实 + 偏差累计超阈值 | bplId + lastVerifiedDate + deviationRate |
TL（楼宇档案更新任务派发） |
| WorkerDowngraded | WPL 师傅月度评分跨降级阈值 + 审批通过 | wplId + oldLevel + newLevel + triggerMonth + finalScore |
QSV（等级系数变更）、DIS（派单权重调整） |
| CustomerConflictRaised | CPL 同一客户多个档案（手机号/邮箱重复）疑似冲突 | conflictingCplIds[] + matchedFields{} + confidence |
OL（人工合并审核） |
| MasterDataSuppliedToService | SupplyAPIService 被调用（审计用） | consumerService + factorType + entityIds[] + rowCount + timestamp |
MDS 访问审计日志 |
3.6 仓储 + 工厂¶
| 类型 | 名称 | 职责 |
|---|---|---|
| 仓储 | ServiceCategoryRepository | SCL 条目持久化 + 查询（按品类编码、费率区间） |
| 仓储 | BuildingProfileRepository | BPL 条目持久化 + 查询（按区域、类型系数） |
| 仓储 | WorkerProfileRepository | WPL 条目持久化 + 查询（按技能、区域、等级、时段） |
| 仓储 | CustomerProfileRepository | CPL 条目持久化 + 查询（按标签、徽章、复购意向） |
| 仓储 | ProducerProfileRepository | PPL 条目持久化 + 查询（按品牌、品类范围） |
| 仓储 | LogisticsProfileRepository | DLV 条目持久化 + 查询（按模式、区域、评分） |
| 仓储 | RenovationCatalogRepository | RNV 条目持久化 + 查询（按分部编码、复杂度维度、计价单位） |
| 工厂 | MasterDataIdFactory | 包装 MasterDataIdService，批量生成 ID（如当日 100 条师傅档案录入） |
| 工厂 | SevenLibraryEntityFactory | 接收录入表单数据 → 构造对应实体（ServiceCategory/BuildingProfile/RenovationCatalog 等），确保不变量检查 |
3.7 主数据档案生命周期状态机¶
stateDiagram-v2
[*] --> DRAFT: 运营录入/批量导入
DRAFT --> PENDING_REVIEW: 提交审核
PENDING_REVIEW --> ACTIVE: BO/OL 审核通过
PENDING_REVIEW --> DRAFT: 审核驳回(需修改)
ACTIVE --> INACTIVE: 主体停用(如师傅离职/生产商解约)
INACTIVE --> ACTIVE: 重新启用(审核流程)
ACTIVE --> ARCHIVED: 长期无交易(>365天，逻辑归档)
ARCHIVED --> ACTIVE: 重新激活(BO审批)
ACTIVE --> DELETED: 逻辑删除(仅合规场景，SPO审批)状态说明： - DRAFT：草稿，未通过审核，禁止被 QSV/CPT/DIS/OPS 消费 - PENDING_REVIEW：待审核，需 BO/OL 按七库分级权限审批 - ACTIVE：启用态，可被全平台消费；仅 ACTIVE 状态允许被 SupplyAPIService 返回 - INACTIVE：停用态，不再参与新报价/派单，但 CPT 历史过程数据可引用 - ARCHIVED：归档态，冷数据，查询需走归档仓储接口 - DELETED：逻辑删除，仅合规场景（如客户 PDPO 删除权请求），SPO 双审
四、七库总览 + SCAT 服务目录视图（V1.5 新增）¶
V1.5 新增 SCAT 视图层（对齐 SCAT V1.1）：SCAT（Service Catalog，DOC-P53）不属于主数据子库，而是基于七库的统一服务目录视图层——聚合 SCL（标准安装）+ RNV（装修工程）+ MTN 维修服务（CAT-10，对齐 SCL CAT-01~09 维修版）+ DLV（配送）形成 CST/MFR 双视角服务目录。SCAT 不存储主数据，仅提供查询视图。
| 简称 | 编号 | 全称 | 核心内容 | 主要消费方 |
|---|---|---|---|---|
| SCL | DOC-P51-S | 安装服务特征库（Service Catalog Library） | 10 大品类目录（V1.2 新增 CAT-10 MTN 维修）、56 细分类目、产品参数映射、基础费率、技能要求、F1-F4 故障级别费率矩阵 | QSV（费率/参数/维修费率）、CPT（服务类型）、DIS（技能匹配）、SCAT（视图聚合） |
| BPL | DOC-P51-B | 楼宇特征库（Building Profile Library） | 楼宇档案、类型系数、电梯配置、楼层、管理要求 | QSV（楼宇系数/楼层附加）、CPT（楼宇核实）、SCAT（视图聚合） |
| WPL | DOC-P51-W | 师傅特征库（Worker Profile Library） | 师傅档案、等级体系（SK1/SK2/SK3）、技能矩阵、服务区域、历史表现 | QSV（等级系数）、CPT（师傅ID）、DIS（派单匹配）、OPS（师傅个人品牌） |
| CPL | DOC-P51-C | 客户特征库（Customer Profile Library） | 客户档案、五维标签体系、信任徽章、复购意向、推荐关系链 | CPT（客户ID）、OPS（客户画像/营销）、QSV（历史客户优惠） |
| PPL | DOC-P51-P | 生产商档案库（Producer Profile Library） | 生产商档案、品牌等级（普通/高端1.2/高端1.4）、品类范围、合作条款、质保条款 | MFR Portal（开放报价）、QSV（品牌溢价因子）、CPT（产品来源） |
| DLV | DOC-P51-L | 物流商档案库（Deliverer Profile Library） | 物流商档案、业务模式（M1自营/M2独立/M3跨境）、M3合同子表、C7保险赔付记录、综合评分；V1.2 配送范围收窄为内地→香港（不承接海外跨境） | DIS（三模式派单匹配 + 保险负向权重）、CPT（配送商ID）、SCAT（视图聚合 MFR 配送目录） |
| RNV | DOC-P51-R | 装修服务特征库（Renovation Catalog Library） | 6 大分部目录（拆除/新建/水电/楼梯/安装/其他）、4 个装修专用复杂度维度（CD-DEMO/CD-BLDR/CD-HIDE/CD-STAIR）、主材工料分离、多版本报价模板 | QSV（装修分部费率/复杂度系数）、CPT（装修工程采集）、CPT-F（主材/工料分离）、SCAT（视图聚合 L3 装修目录） |
| SCAT（视图层） | DOC-P53 | 服务目录清单（Service Catalog，视图层，非主数据子库） | V1.1 平台服务范围权威清单，双视角（CST 不含配送 / MFR 含内地跨境配送 D2 + 组合 A-F），聚合 SCL+RNV+MTN维修+DLV，10 大品类 56 细分 + 9 维修品类×4 故障级别 + 6 配送项 + 6 组合模式 | QSV（L1-L3 服务分层 + F1-F4 维修费率 + D2 配送范围）、CPT（L1-L3 阶段映射）、CST Portal（CST 可见目录）、MFR Portal（MFR 可见目录） |
五、服务边界与职责¶
5.1 MDS 负责的职责¶
| 职责 | 说明 |
|---|---|
| 主数据录入 | 师傅招募录入、品类目录维护、楼宇档案建立、客户档案创建、生产商入驻、物流商签约、装修工程分部维护 |
| 主数据存储 | 七库的持久化存储、版本管理、变更历史、逻辑归档 |
| 主数据查询（供给） | 对外提供 ID 查询、属性查询、批量查询 API；仅返回 ACTIVE 状态档案 + 隐私脱敏 |
| 主数据校准 | 基于 CPT/DIS 反哺数据，定期校准师傅等级、客户标签、楼宇系数、品类费率、物流商评分、装修复杂度维度 |
| 主数据权限 | 客户/师傅/生产商/物流商隐私字段 L1~L4 分级脱敏、按服务分配字段级访问权限 |
| 标签与 ID 管理 | 标签版本严格递增、ID 编码规范一致性、冲突检测与合并 |
5.2 MDS 不负责的职责（明确边界）¶
| 不负责项 | 归属服务 | 理由 |
|---|---|---|
| 单次客户项目跟踪记录 | CPT | 过程数据，非主体档案；MDS 仅通过 ACL 消费 CPT 反哺结果 |
| 报价计算逻辑 | QSV | 消费 SCL/BPL/WPL/PPL 因子后由 QSV PricingEngine 自行计算 |
| 派单匹配算法 | DIS 派单服务 | V8.0 阶段一独立化为 DIS 服务；MDS 仅供给 DLV 模式 + 技能矩阵 + C7 赔付记录 |
| 营销活动执行/物料生成 | OPS | 消费 CPL 标签/WPL 个人品牌资料后由 OPS 自行触达 |
| 支付交易记录 | PAY（待建） | 交易过程数据，非主体档案 |
| 各端 App 前端实现 | TND D05~D09 | 前端实现，非主数据本身 |
5.3 与原 TND D03 楼宇数据库的关系¶
原 TND 技术规划 中 D03「楼宇数据库设计」属主数据范畴，本次迁移至 MDS/BPL：
- TND D03 编号保留但标记为「已迁移至 MDS/BPL」
- 后续楼宇库的业务设计文档位于 docs/主数据服务/楼宇特征库设计.md
- 楼宇库的技术实现方案（数据模型、存储、采集接口）仍可在 TND 下另立技术文档
六、与各业务服务的对接方案¶
6.1 与 QSV 报价服务的对接¶
sequenceDiagram
participant QSV as QSV 报价服务
participant MDS as MDS 主数据服务
participant SCL as SCL 服务库
participant BPL as BPL 楼宇库
participant WPL as WPL 师傅库
QSV->>MDS: 查询报价参数(品类+楼宇+师傅等级)
MDS->>SCL: 查品类基础费率/产品参数
MDS->>BPL: 查楼宇类型系数/电梯配置
MDS->>WPL: 查师傅等级系数
SCL-->>MDS: 费率/参数
BPL-->>MDS: 系数/附加
WPL-->>MDS: 等级系数
MDS-->>QSV: 返回完整参数集
QSV->>QSV: 按报价公式计算QSV 从 MDS 消费的数据：
| QSV 参数 | 数据来源 | MDS 库 |
|---|---|---|
| 品类基础费率（P1） | 品类目录 × 基础费率表 | SCL |
| 产品参数映射（影响工时/难度） | 产品参数 → 工时映射表 | SCL |
| 楼宇类型系数（P3） | 楼宇类型 → 系数映射 | BPL |
| 楼层附加费（P3） | 电梯配置 + 楼层 | BPL |
| 师傅等级系数（P8） | 师傅等级 → 系数映射 | WPL |
6.2 与 CPT 客户跟踪服务的对接¶
CPT 从 MDS 引用的主体 ID：
| CPT 字段 | MDS 来源 | 用途 |
|---|---|---|
| 客户ID | CPL | 关联客户主体档案 |
| 师傅ID | WPL | 关联师傅主体档案 |
| 服务类型 | SCL | 关联品类目录 |
| 楼宇ID | BPL | 关联楼宇档案（L2 现场核实后回写） |
| 生产商ID | PPL | 关联产品来源品牌（MFR 开放报价场景） |
| 配送商ID | DLV | 关联 L5 实际配送执行方 |
CPT 反哺 MDS 的数据：
| CPT 采集数据 | 反哺目标 | 更新内容 |
|---|---|---|
| 师傅实际工时 | WPL | 师傅效率画像、工时统计 |
| 客户评分（L8 NPS） | WPL | 师傅评分更新、等级校准 |
| 客户验收/复购行为 | CPL | 客户标签、复购意向、信任徽章 |
| 师傅现场核实的楼宇信息 | BPL | 楼宇档案修正（电梯/楼层/管理要求） |
| 实际成交价 vs 报价 | SCL | 品类费率校准建议 |
| L5 配送时效 + 破损记录 | DLV | 物流商综合评分、C7 保险赔付累计 |
| L6 产品质量反馈 | PPL | 生产商评级、质保条款复核 |
6.3 与 DIS 派单服务的对接¶
V8.0 阶段一独立化为 DIS 服务，MDS 仅作为主数据底座供给，派单匹配算法由 DIS 自行负责。
DIS 从 MDS 消费的数据：
| DIS 需求 | MDS 来源 | 用途 |
|---|---|---|
| 师傅技能品类 + 技能矩阵 | WPL | 匹配订单品类要求 |
| 师傅服务区域 + 最大距离 | WPL | 匹配订单区域 |
| 师傅可用时段 | WPL | 匹配订单时段 |
| 师傅等级（SK1/SK2/SK3） | WPL | 优先派单高等级师傅；计算等级乘数 |
| 师傅实时状态 | WPL（动态字段） | 在线/忙碌/休假过滤 |
| 物流商业务模式（M1/M2/M3） | DLV | 三模式派单路由 |
| M3 合同字段子表 | DLV | M3 模式合同匹配优先级 |
| C7 保险赔付累计记录 | DLV | 负向权重（-20~-80）调整派单评分 |
6.4 与 OPS 运营服务的对接¶
OPS 从 MDS 消费的数据：
| OPS 需求 | MDS 来源 | 用途 |
|---|---|---|
| 客户标签（五维体系） | CPL | 精准营销分群（S01~S06 场景） |
| 客户复购意向 | CPL | 复购推送触发 |
| 客户推荐关系链 | CPL | 推荐激励计算、裂变获客 |
| 师傅个人品牌资料 + 案例 | WPL | 师傅名片、口碑物料展示 |
| 信任徽章（客户 + 师傅） | CPL + WPL | 可验证的信任标识、转化率提升 |
| 生产商品牌等级 | PPL | B 端合作拓展、高端客户匹配 |
七、数据闭环与校准机制¶
7.1 数据闭环总览¶
flowchart LR
subgraph MDS["MDS 主数据服务（七库）"]
SCL["SCL 服务库"]
BPL["BPL 楼宇库"]
WPL["WPL 师傅库"]
CPL["CPL 客户库"]
PPL["PPL 生产商库"]
DLV["DLV 物流商库"]
RNV["RNV 装修工程库"]
end
subgraph BIZ["业务服务"]
QSV["QSV 报价"]
CPT["CPT 跟踪"]
DIS["DIS 派单"]
OPS["OPS 运营"]
end
MDS -- "主数据供给（SupplyAPIService）" --> BIZ
CPT -.->|"工时/评分/复购/楼宇/破损/质量/装修工时"| MDS
QSV -.->|"成交价vs报价偏差"| SCL
DIS -.->|"C7赔付累计/配送评分"| DLV
CPT -.->|"装修实际工时/主材用量"| RNV7.2 校准周期与流程¶
| 校准对象 | 校准周期 | 触发条件 | 责任人 | 审批 |
|---|---|---|---|---|
| 师傅等级（WPL） | 月度 | 累计接单量 + 评分跨阈值 | OL | BO |
| 客户标签/徽章（CPL） | 实时 + 月度 | CPT 事件触发实时；月度全量复核 | 系统自动 + OL | BO |
| 楼宇系数（BPL） | 季度 | 累计偏差超阈值（>15%） | TL | BO |
| 品类费率（SCL） | 月度 | QSV 校准建议偏差率 >10% | BO | SPO |
| 生产商评级（PPL） | 季度 | L6 质量反馈累计、质保履约率 | TL | BO |
| 物流商评分（DLV） | 月度 | L5 破损率超阈值、C7 赔付累计超 HKD 5,000 | OL | BO |
| 装修复杂度维度（RNV） | 季度 | CPT L6 装修实际工时累计偏差超阈值（>20%） | TL | BO |
7.3 校准流程（以师傅等级为例）¶
flowchart TD
A["CPT 采集师傅月度数据"] --> B["WPL WorkerFactor ACL 计算综合评分"]
B --> C{"评分是否跨升级/降级阈值?"}
C -- "是" --> D["生成等级变更建议（含前后对比）"]
D --> E["OL 审核"]
E -- "通过" --> F["BO 审批"]
F -- "通过" --> G["发布 WorkerDowngraded/Upgraded 事件"]
G --> H["更新 WPL 师傅等级 + labelVersion+1"]
H --> I["记入 MDS 访问审计日志"]
I --> J["通知 QSV/DIS 刷新等级系数缓存"]
C -- "否" --> K["维持当前等级"]
E -- "驳回" --> L["记录驳回原因 + OL 备注"]
F -- "驳回" --> L八、数据安全与权限¶
8.1 数据分级¶
| 等级 | 含义 | 涉及字段（含七库扩展） | 访问权限 |
|---|---|---|---|
| L1 公开 | 可对外展示 | 师傅昵称/等级/案例、品类目录、楼宇类型、生产商品牌名、物流商服务区域 | 全服务可读 + 公开页面 |
| L2 内部 | 平台内部共享 | 师傅真实姓名/手机、客户基本信息、楼宇详细地址、生产商联系人、物流商对接人 | 已授权服务可读 |
| L3 敏感 | 需脱敏访问 | 客户手机/地址/支付信息、师傅收入、生产商合作条款价格、物流商结算费率 | 仅 CPT/PAY/OL 经 PrivacyDesensitizationService 脱敏访问 |
| L4 机密 | 严格管控 | 客户身份证明、师傅身份证明、银行账户、生产商商业机密、M3 合同全文 | 仅合规岗位 + SPO 双审 |
8.2 隐私保护原则¶
- 最小化原则：业务服务仅可访问其必需字段（如 QSV 不需客户手机号、DIS 不需生产商合同条款）
- 脱敏原则：跨服务传输 L3/L4 字段须脱敏（如手机号 138****5678、收入范围 HKD 20k-30k），由 PrivacyDesensitizationService 强制执行
- 审计原则：所有主数据访问记录 MasterDataSuppliedToService 事件，保留 180 天
- 合规原则：符合香港《个人资料（私隐）条例》（PDPO），支持客户/师傅「数据删除权」「资料查阅权」请求，走 DELETED 状态机流程（SPO 双审）
九、实施优先级¶
按业务急需度排序（V8.0 七库扩展版）：
| 优先级 | 库 | 理由 | MVP 前置依赖 |
|---|---|---|---|
| P0 | SCL 安装服务库 | QSV 报价引擎冷启动必需品类费率与产品参数；覆盖 MVP 5 大品类 | 报价引擎 |
| P0 | BPL 楼宇特征库 | QSV 楼宇系数是报价最大变量；筹备期需建立港岛/九龙核心楼宇库 >2,000 栋 | 报价引擎 |
| P1 | WPL 师傅特征库 | DIS 派单必需；师傅等级系数影响报价；MVP 阶段至少 50+ 在职师傅 | 派单系统、报价 |
| P1 | DLV 物流商档案库 | DIS 三模式派单必需；MVP 至少 M1（自营 3 车）+ M2（独立 5 人）签约 | 派单系统 |
| P2 | PPL 生产商档案库 | MFR Portal 开放报价场景；MVP 前 10 家合作品牌入驻 | 报价引擎（品牌溢价）、MFR 端 |
| P2 | CPL 客户特征库 | 试运营期客户量小（<500），初期可用 CPT 字段替代；扩张期营销必需 | OPS 营销系统、复购推荐 |
| P2 | RNV 装修服务特征库 | 装修工程专项需求，承接 EVAL 2.4 修改项独立成库；MVP 阶段装修单量小，可延后；扩张期装修业务必需 | 报价引擎（装修分部费率/复杂度系数） |
建议实施顺序：SCL → BPL → WPL → DLV → PPL → CPL → RNV
十、后续规划¶
- MDS 技术方案（七库数据模型、存储选型、供给 API 规格，归入 TND Dxx）
- 七库数据采集与录入 SOP 细化（含批量导入模板）
- 与 QSV/CPT/DIS/OPS 的 API 对接规格定义（OpenAPI 3.0 + ACL VO 契约）
- 主数据字段级权限矩阵详细设计（七库 × 四分级 × 五服务）
- 数据质量监控与异常告警（档案冲突、系数过期、赔付超标）
- 主数据版本快照与回滚机制（git tag 对齐归档）
修订记录¶
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V1.0 | 2026-08-05 | DT | 首版创建：服务定位、四库总览、服务边界、对接方案、数据闭环、安全权限、实施优先级 |
| V1.1 | 2026-08-05 | DT | MKT→OPS 全局替换：四库总览消费方、服务边界、§4.4 对接方案、数据闭环图统一为 OPS 运营服务 |
| V1.2 | 2026-08-05 | DT | V8.0 阶段一派单服务独立化：§3.2「派单匹配算法」→ DIS 归属；新增 MDS 向 DIS 供给 DLV 模式 + 合同子表 + C7 赔付记录的说明 |
| V1.3 | 2026-08-21 | DT | V8.0 阶段二-5 DDD 重构 + 六库补全：① 新增 §二 DDD 战略（2 子域 + 2 BC + 5 映射 + 5 ACL VO）② 新增 §三 DDD 战术（聚合根 MasterDataCatalog + 6 实体 + 8 VO + 5 领域服务 + 8 领域事件 + 仓储工厂 + 状态机）③ 四库→六库（新增 PPL/DLV 总览 + 优先级 + 校准 + 分级）④ DSP→DIS 全局修复 ⑤ 章节编号整体 +2（原§二→§四，原§八→§十）⑥ 关联文档新增 BAS 锚点 ⑦ 遗留修复：数据闭环图补充 PPL/DLV/DIS |
| V1.4 | 2026-08-25 | DT | RNV 装修服务特征库纳入七库总览（基于 EVAL V1.0 2.4 修改项）：① §1.1 服务定位六类→七类主体档案；② §1.2 核心概念六库→七库 + 数据闭环新增 RNV 反哺；③ §3.1 不变量 libraryCode 增加 RNV；④ §3.2 实体清单 6→7 新增 RenovationCatalog；⑤ §3.3 VO 清单 8→9 新增 RenovationFactor VO（含 4 个装修专用复杂度维度 + 主材工料分离 + 多版本报价模板）；⑥ §3.4 领域服务 SixLibraryCRUDService→SevenLibraryCRUDService + SupplyAPIService 增加 RenovationFactor；⑦ §3.6 仓储新增 RenovationCatalogRepository + 工厂 SixLibraryEntityFactory→SevenLibraryEntityFactory；⑧ §四 六库总览→七库总览新增 RNV 行；⑨ §5.1 职责新增装修工程分部维护 + 装修复杂度校准；⑩ 关联文档新增 RNV V1.0、EVAL V1.0、CCRR V1.0 |
| V1.5 | 2026-08-26 | DT | SCAT 服务目录视图层纳入 + SCL/DLV 同步修订（对齐 SCAT V1.1 + SCL V1.2 + DLV V1.2）：① §四 七库总览 → 七库总览 + SCAT 服务目录视图，新增 SCAT 行（视图层，DOC-P53，非主数据子库）；② §四 SCAT 行说明 SCAT 聚合 SCL+RNV+MTN维修+DLV 形成双视角；③ §四 SCL 行同步更新（10 大品类 56 细分，V1.2 新增 CAT-10 MTN 维修 + F1-F4 故障级别费率矩阵）；④ §四 DLV 行同步更新（V1.2 配送范围收窄为内地→香港，不承接海外跨境）；⑤ §四 各库主要消费方列新增 SCAT（视图聚合）；⑥ 关联文档新增 SCAT V1.1；⑦ 头部新增 V1.5 升级摘要。依据用户原话：「维修要对故障级别进行分级…配送服务只涉及内地跨境，不考虑海外跨境」+ SCAT V1.1 修订决策同步。 |