这是园区数字化落地系列的技术第三篇。前两篇我们分别聊了《四层架构与数据建模》和《四端协同的事件驱动架构》。本文接着往后走一步：数据从业务端流到问数端之后，怎么保证"问数平台算出来的数"和"业务方心里的数"是同一个数。这个问题的工程答案，叫口径中心（Metric / Semantic Layer）。

一个问数平台能不能"敢用"，瓶颈往往不在模型，而在口径。模型再聪明，喂给它"空置率"三个字，它也得先明白你说的空置到底是哪一种空置。

一、为什么需要一个"口径中心"

园区经营里同一句话，不同人理解完全不同：

• 招商说"空置率"，指的是当前没租出去、且状态可租的房源；
• 运营说"空置率"，会把已签合同但还没进场的也临时算进去；
• 财务做预算时说的"空置"，往往按计费状态反推——合同到期了但还在计费，那就不算空。

Excel 时代，这种分歧靠人脑在开会时对一遍，对完就忘。问数平台时代，分歧被放大成"同一句话，点一下出来三个数"。没有口径治理，问数平台就是高级别的瞎猜——它确实"回答"了，只是答的是它自己默认的口径。

所以真正的工程做法是：把口径当成一等公民存起来，让报表、问数平台、原系统的看板，全部从同一份定义里取数。这就是口径中心。

二、口径中心在四层架构中的位置

回顾一下四层：

• L1 业务层：智慧园区系统把业务在线跑完，留痕；
• L2 数据层：结构化沉淀（房源、租客、合同、账单、工单、能耗）；
• L3 问数层：自然语言提问 → 计算 → 结论 + 图表 + 明细 + 来源；
• L4 展现层：大屏、移动端、报表。

口径中心不单独成层，而是插在L2 与 L3 之间，作为共享语义层。它的职责是：把"业务方说的词"翻译成"数据库里怎么算"。L3 每次回答前，先来这一层查口径，再生成 SQL。

关键点：口径中心是只读消费L2 的数据，不写回。这也意味着它和前面的事件驱动架构是解耦的——L2 怎么来数据（CDC / Outbox / 物化视图），口径中心不关心。

三、数据模型：把口径当作表来存

最常见的问题是"口径写哪儿"——散落在各业务系统的存储过程里，或者写死在问数平台的代码里。两种都会腐化。正确做法是一张口径定义表：

sql

-- 指标口径定义表：口径的一等公民落地 CREATE TABLE metric_def ( metric_code VARCHAR(64) NOT NULL COMMENT '口径编码, 如 vacant_room_cnt', metric_name VARCHAR(128) NOT NULL COMMENT '口径中文名', biz_domain VARCHAR(32) NOT NULL COMMENT '业务域: room/contract/bill/workorder', agg_type VARCHAR(16) NOT NULL COMMENT '聚合方式: count/sum/ratio', source_tables JSON NOT NULL COMMENT '来源表清单, 如 [dim_room,fact_lease]', definition_sql TEXT NOT NULL COMMENT '口径计算 SQL 片段(模板)', owner VARCHAR(32) NOT NULL COMMENT '口径负责人(必须是业务方)', version INT NOT NULL DEFAULT 1 COMMENT '口径版本', effective_from DATE NOT NULL COMMENT '生效日期', effective_to DATE DEFAULT NULL COMMENT '失效日期, NULL=当前生效', status TINYINT NOT NULL DEFAULT 1 COMMENT '1生效 0停用', created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (metric_code, version) ) COMMENT='指标口径定义表'; -- 口径维度表：决定这个口径能按哪些维度下钻(楼栋/楼层/行业) CREATE TABLE metric_dimension ( metric_code VARCHAR(64) NOT NULL, version INT NOT NULL, dim_key VARCHAR(32) NOT NULL COMMENT 'building/floor/industry/...', dim_label VARCHAR(64) NOT NULL, PRIMARY KEY (metric_code, version, dim_key) ) COMMENT='口径可下钻维度'; -- 口径来源血缘表：每个口径取自哪些表哪些字段, 审计用 CREATE TABLE metric_source ( metric_code VARCHAR(64) NOT NULL, version INT NOT NULL, src_table VARCHAR(64) NOT NULL, src_column VARCHAR(64) NOT NULL, op VARCHAR(16) NOT NULL COMMENT 'count/sum/filter/join', PRIMARY KEY (metric_code, version, src_table, src_column) ) COMMENT='口径数据血缘';

三张表的关系很清晰：metric_def是口径本体，metric_dimension描述可下钻维度，metric_source记录血缘，用于审计和"这个数到底来自哪"。

四、指标怎么算：用 SQL 把口径写死

口径不能停在"名词解释"，必须能落地成确定的 SQL。下面是三个真实口径的计算定义。

口径 1：空置房源数（count 类）

sql

-- vacant_room_cnt: 当前无有效合同 且 状态=可租 且 不在装修期 SELECT COUNT(*) AS vacant_room_cnt FROM dim_room r WHERE r.room_status = 'AVAILABLE' -- 房源状态=可租 AND NOT EXISTS ( -- 无覆盖当天的有效合同 SELECT 1 FROM fact_lease l WHERE l.room_id = r.room_id AND l.status = 'ACTIVE' AND l.start_date <= CURDATE() AND l.end_date >= CURDATE() ) AND (r.decorate_end IS NULL OR r.decorate_end < CURDATE()); -- 不在装修期

口径 2：月度收缴率（ratio 类）

sql

-- collection_rate: 实收 / 应收, 按账单账期月份 SELECT b.bill_month, SUM(b.actual_amount) / NULLIF(SUM(b.due_amount), 0) AS collection_rate FROM fact_bill b WHERE b.bill_month = '2026-09' GROUP BY b.bill_month;

口径 3：未来 N 天到期合同数（窗口类）

sql

-- expiring_contract_cnt: 未来30天内到期且仍有效的合同 SELECT COUNT(*) AS expiring_cnt FROM fact_lease l WHERE l.status = 'ACTIVE' AND l.end_date BETWEEN CURDATE() AND CURDATE() + INTERVAL 30 DAY;

注意三个口径都带明确的过滤条件，不是"SELECT COUNT() FROM room WHERE status=空"。口径的可信度，等于过滤条件写清楚的程度。* 招商、运营、财务那三种"空置"，本质上就是这三个过滤条件组合不同——把它们拆开写成独立口径，比在一个口径里加分支参数更不容易出错。

五、用配置代替改代码：口径即配置

口径写进表之后，问数平台每次回答前查表拼 SQL。但给业务方直接改数据库并不友好。更工程化的做法是把口径做成配置文件，由口径中心加载进metric_def：

yaml

metrics: - code: vacant_room_cnt name: 空置房源数 domain: room agg: count version: 3 effective_from: 2026-01-01 owner: 招商运营部 source: - dim_room - fact_lease filters: - "room_status = 'AVAILABLE'" - "NOT EXISTS active lease overlapping today" - "decorate_end IS NULL OR decorate_end < today" dimensions: [building, floor, industry] - code: collection_rate name: 月度收缴率 domain: bill agg: ratio version: 2 effective_from: 2026-01-01 owner: 财务部 source: - fact_bill numerator: actual_amount denominator: due_amount grain: bill_month dimensions: [building, industry]

这样业务方改口径，提交一份 YAML（走评审），口径中心重新加载即可，不需要动问数平台的代码。这是口径能长期维护的前提——如果每次改口径都要发版，三个月后没人愿意维护了，口径就会悄悄过期。

六、口径会变：版本与一致性

口径不是一次定终身的。今年"空置"把装修期排除，明年招商政策变了，要把装修期也算进去。如果直接 UPDATE 那行记录，历史数据就变味了：去年 Q4 的空置率，和今年 Q4 的空置率，口径不一样，不能同比。

解法是用metric_def里的version+effective_from+effective_to：

• 新口径以新版本写入，旧版本不删、只把effective_to填上；
• 查询时带"数据日期"，口径中心选"该日期生效的那一版"；
• 历史报表永远能复算，因为历史口径还在。

一句话原则：口径要可追溯，口径变更要像数据一样留痕。这也是后面审计能成立的基础。

七、权限与审计：谁能定义口径、谁能查

口径中心是敏感的——它定义了"公司怎么看自己"。权限设计要分两面：

1. 定义口径的权限（写权限）

• 只有口径负责人（业务方）能发起变更，且走评审；
• 技术方可以帮忙写 YAML，但owner字段必须是业务方，避免"技术拍脑袋定业务口径"。

2. 查询口径的权限（读权限）

问数平台以只读账号接入 L2，只读意味着改不了业务数据；查询对象与结果范围事前约定。更细的粒度用行级权限，比如招商只能查自己负责楼栋，财务能查全量但看不到租客个人隐私字段（脱敏）。

每次查询落一条日志：

sql

CREATE TABLE metric_query_log ( id BIGINT AUTO_INCREMENT PRIMARY KEY, user_id VARCHAR(32) NOT NULL COMMENT '谁查的', metric_code VARCHAR(64) NOT NULL COMMENT '查的哪个口径', asked_at DATETIME NOT NULL COMMENT '什么时间', row_scope VARCHAR(64) COMMENT '命中的行级范围(如 building=7)', result_rows INT COMMENT '返回多少行', INDEX idx_user (user_id), INDEX idx_at (asked_at) ) COMMENT='口径查询留痕';

审计的价值不只合规。当某天业务方说"这个数不对"，你拉出metric_query_log+ 当时生效的metric_def.version，就能精确还原"那天用的到底是哪一版口径、查的哪栋楼"——扯皮到此为止。

八、口径如何支撑"结果可核对"

口径中心不只是给问数平台算数。前文提到问数平台回答分四层——结论、图表、明细、来源——背后全是口径中心在撑：

• 结论：来自metric_def.definition_sql的执行结果，口径即算法；
• 图表：同一份 SQL 换聚合维度（走metric_dimension）即得，维度复用；
• 明细：把definition_sql的过滤条件原样展开，点开即见每一行是怎么被算进去的；
• 来源：来自metric_source血缘表，精确到"取自哪张表的哪个字段、做了什么操作"。

所以"结果可核对"不是口号，是数据模型里已经落好的三张表。没有口径中心，问数平台想给出"来源"都得现场拼，拼不准是常态。这也是为什么前面两篇反复强调"交代数据从哪来"——口径中心就是那个能交代清楚的底座。

九、性能权衡：实时计算 vs 预计算

口径写好了，下一个问题是"什么时候算"。两条路线：

• 实时计算：用户提问时现场跑definition_sql。永远最新、零额外存储；但多表 JOIN + 窗口函数的复杂口径，在大数据量下会慢。
• 预计算（物化视图 / 定时任务）：按维度把结果算好落表，提问直接读。快；但口径一变要重建物化视图，且占存储。

取舍经验如下：

实践上：明细下钻和临时问用实时，大屏固定指标用预计算。关键是口径中心统一管理两者的定义——切换时只改调用方式，不改口径本身，业务含义始终一致。

十、工程踩坑表

下面是落地口径中心时最常踩的坑，按出现频率排：

十一、关于本文涉及的两套系统

口径中心不是凭空来的，它的数据底座和落地环境是这两套系统配合的结果：

• 智慧园区系统（四端一体运营平台）：负责把业务在线发生、过程留痕、数据结构化沉淀。没有它，口径中心就没有可靠的 L2 数据源——垃圾进，垃圾算。
• 数智安全问数平台（鲁联数智 提供）：在 L2 之上加一个问数入口，以只读方式接入，不改原业务表结构；口径中心就是它"敢给结论"的核心配置能力——结论之下是确定的口径，口径之下是可追溯的 SQL 与来源。

一句话：智慧园区系统负责有得查，问数平台负责问得清，而口径中心决定了"问清楚"这件事到底靠不靠谱。

本文为园区数字化落地系列技术第三篇。前两篇分别为《四层架构与数据建模》《四端协同的事件驱动架构》，均围绕同一套"发生 → 沉淀 → 提问 → 决策"闭环展开。