refactor: publish mileage metric catalog

2026-08-07 13:54:51 +08:00
parent 13e720c2c3
commit ce50265771
5 changed files with 177 additions and 0 deletions
@@ -0,0 +1,100 @@
+export type MetricDomain = 'mileage';
+export type MetricUnit = 'km' | 'percent' | 'vehicle' | 'timestamp';
+export type MetricAggregation = 'sum' | 'weighted-ratio' | 'distinct-count' | 'latest';
+export type MetricTimeSemantics = 'flow' | 'snapshot' | 'freshness';
+
+export interface MetricDefinition {
+  id: string;
+  domain: MetricDomain;
+  label: string;
+  description: string;
+  unit: MetricUnit;
+  aggregation: MetricAggregation;
+  timeSemantics: MetricTimeSemantics;
+  formula: string;
+  sources: readonly string[];
+  dimensions: readonly string[];
+  drillEntity: 'vehicle' | 'assessment-target';
+}
+
+export const METRIC_CATALOG_VERSION = 1;
+
+const MILEAGE_METRICS: readonly MetricDefinition[] = [
+  {
+    id: 'mileage.daily_total',
+    domain: 'mileage',
+    label: '当日总里程',
+    description: '所选自然日内有效车辆日里程之和。',
+    unit: 'km',
+    aggregation: 'sum',
+    timeSemantics: 'flow',
+    formula: 'SUM(vehicle_daily_mileage_km)',
+    sources: ['OneOS mileage API'],
+    dimensions: ['date', 'department', 'region', 'customer', 'vehicle-model', 'plate'],
+    drillEntity: 'vehicle',
+  },
+  {
+    id: 'mileage.period_total',
+    domain: 'mileage',
+    label: '区间总里程',
+    description: '所选自然日区间内有效车辆日里程之和。',
+    unit: 'km',
+    aggregation: 'sum',
+    timeSemantics: 'flow',
+    formula: 'SUM(vehicle_daily_mileage_km) OVER selected_date_range',
+    sources: ['OneOS mileage range API'],
+    dimensions: ['date', 'department', 'region', 'customer', 'vehicle-model', 'plate'],
+    drillEntity: 'vehicle',
+  },
+  {
+    id: 'mileage.vehicle_count',
+    domain: 'mileage',
+    label: '监控车辆数',
+    description: '当前权限和筛选范围内的去重车辆数量。',
+    unit: 'vehicle',
+    aggregation: 'distinct-count',
+    timeSemantics: 'snapshot',
+    formula: 'COUNT(DISTINCT vehicle_id)',
+    sources: ['Asset database'],
+    dimensions: ['department', 'region', 'customer', 'vehicle-model'],
+    drillEntity: 'vehicle',
+  },
+  {
+    id: 'mileage.assessment_completion_rate',
+    domain: 'mileage',
+    label: '考核完成率',
+    description: '按目标里程加权汇总，不平均车辆或考核组的完成率。',
+    unit: 'percent',
+    aggregation: 'weighted-ratio',
+    timeSemantics: 'snapshot',
+    formula: 'SUM(completed_mileage_km) / NULLIF(SUM(target_mileage_km), 0) * 100',
+    sources: ['Mileage assessment database'],
+    dimensions: ['assessment-year', 'assessment-target', 'department', 'customer', 'plate'],
+    drillEntity: 'assessment-target',
+  },
+  {
+    id: 'mileage.data_freshness',
+    domain: 'mileage',
+    label: '数据统计时间',
+    description: '当前选源协议最后一条有效里程数据的业务时间。',
+    unit: 'timestamp',
+    aggregation: 'latest',
+    timeSemantics: 'freshness',
+    formula: 'COALESCE(data_time, updated_at, calculated_at)',
+    sources: ['OneOS mileage API'],
+    dimensions: ['source-protocol', 'plate'],
+    drillEntity: 'vehicle',
+  },
+];
+
+export const METRIC_CATALOG: readonly MetricDefinition[] = MILEAGE_METRICS;
+
+export function isMetricDomain(value: string): value is MetricDomain {
+  return METRIC_CATALOG.some(metric => metric.domain === value);
+}
+
+export function listMetricDefinitions(domain?: MetricDomain): MetricDefinition[] {
+  return METRIC_CATALOG
+    .filter(metric => !domain || metric.domain === domain)
+    .map(metric => ({ ...metric }));
+}