《移动游戏产品的架构·商业化与发行工程》10.1 商业化埋点体系与事件规范

biz_<domain>_<object>_<action>

// file: src/biz/event-schema.ts
// tier: L1
// verify: node --test test/biz/event-schema.test.ts

export type EventCategory = "exposure" | "click" | "transaction" | "asset";
export type FieldType = "string" | "number" | "boolean";
export type Platform = "android" | "ios" | "taptap" | "web";
export type PropValue = string | number | boolean | null;
export type IssueCode =
  | "unknown-event"
  | "version-mismatch"
  | "bad-name"
  | "bad-meta"
  | "missing-required"
  | "unexpected-field"
  | "bad-type"
  | "pii-field";

export interface FieldSpec {
  readonly name: string;
  readonly type: FieldType;
  readonly required: boolean;
}
export interface EventDefinition {
  readonly name: string;
  readonly version: number;
  readonly category: EventCategory;
  readonly owner: string;
  readonly fields: readonly FieldSpec[];
}
export interface EventInput {
  readonly name: string;
  readonly version: number;
  readonly userId: string;
  readonly sessionId: string;
  readonly platform: Platform;
  readonly tsMs: number;
  readonly payload: Readonly<Record<string, PropValue>>;
}
export interface Issue {
  readonly code: IssueCode;
  readonly field: string;
  readonly detail: string;
}
export interface ValidationResult {
  readonly ok: boolean;
  readonly issues: readonly Issue[];
}
export interface NormalizedEvent {
  readonly eventId: string;
  readonly name: string;
  readonly version: number;
  readonly category: EventCategory;
  readonly userId: string;
  readonly sessionId: string;
  readonly platform: Platform;
  readonly tsMs: number;
  readonly props: Readonly<Record<string, PropValue>>;
}
export type NormalizeResult =
  | { readonly ok: true; readonly event: NormalizedEvent }
  | { readonly ok: false; readonly issues: readonly Issue[] };

const EVENT_NAME_PATTERN = /^biz_[a-z][a-z0-9]*(?:_[a-z0-9]+){2,4}$/;
const PLATFORMS: readonly Platform[] = ["android", "ios", "taptap", "web"];
const PII_FIELDS: readonly string[] = ["phone", "email", "id_card", "precise_lat", "precise_lng"];

function field(name: string, type: FieldType, required = false): FieldSpec {
  return { name, type, required };
}

export const MONETIZATION_CATALOG: readonly EventDefinition[] = [
  {
    name: "biz_store_item_expose",
    version: 2,
    category: "exposure",
    owner: "store",
    fields: [field("item_id", "string", true), field("slot", "string", true), field("currency", "string", true), field("price_cents", "number")],
  },
  {
    name: "biz_store_item_click",
    version: 2,
    category: "click",
    owner: "store",
    fields: [field("item_id", "string", true), field("slot", "string", true), field("price_cents", "number", true)],
  },
  {
    name: "biz_order_pay_success",
    version: 3,
    category: "transaction",
    owner: "payment",
    fields: [
      field("order_id", "string", true),
      field("product_id", "string", true),
      field("amount_cents", "number", true),
      field("currency", "string", true),
      field("channel", "string", true),
    ],
  },
  {
    name: "biz_ad_reward_complete",
    version: 2,
    category: "asset",
    owner: "ads",
    fields: [field("placement_id", "string", true), field("ecpm_cents", "number", true), field("reward_id", "string", true)],
  },
];

export function findEvent(catalog: readonly EventDefinition[], name: string): EventDefinition | null {
  for (const definition of catalog) {
    if (definition.name === name) {
      return definition;
    }
  }
  return null;
}

export function validateEvent(catalog: readonly EventDefinition[], input: EventInput): ValidationResult {
  const issues: Issue[] = [];
  if (!EVENT_NAME_PATTERN.test(input.name)) {
    issues.push({ code: "bad-name", field: "name", detail: `${input.name} does not follow biz_<domain>_<object>_<action>` });
  }
  if (input.userId.length === 0 || input.sessionId.length === 0) {
    issues.push({ code: "bad-meta", field: "userId", detail: "user and session ids are required" });
  }
  if (!Number.isFinite(input.tsMs) || input.tsMs <= 0) {
    issues.push({ code: "bad-meta", field: "tsMs", detail: `${input.tsMs} is not a valid timestamp` });
  }
  if (!PLATFORMS.includes(input.platform)) {
    issues.push({ code: "bad-meta", field: "platform", detail: `${input.platform} is not a known platform` });
  }

  const definition = findEvent(catalog, input.name);
  if (definition === null) {
    issues.push({ code: "unknown-event", field: "name", detail: `${input.name} is not registered` });
    return { ok: false, issues };
  }
  if (definition.version !== input.version) {
    issues.push({ code: "version-mismatch", field: "version", detail: `${input.name} expects v${definition.version}, got v${input.version}` });
  }

  const known = new Map<string, FieldSpec>();
  for (const spec of definition.fields) {
    known.set(spec.name, spec);
    const value = input.payload[spec.name];
    if (spec.required && (value === undefined || value === null)) {
      issues.push({ code: "missing-required", field: spec.name, detail: `${spec.name} is required by ${definition.name} v${definition.version}` });
    }
  }
  for (const key of Object.keys(input.payload)) {
    if (PII_FIELDS.includes(key)) {
      issues.push({ code: "pii-field", field: key, detail: `${key} must never enter the event stream` });
      continue;
    }
    const spec = known.get(key);
    if (spec === undefined) {
      issues.push({ code: "unexpected-field", field: key, detail: `${key} is not declared by the schema` });
      continue;
    }
    const value = input.payload[key];
    if (value !== undefined && value !== null && typeof value !== spec.type) {
      issues.push({ code: "bad-type", field: key, detail: `${key} expects ${spec.type}, got ${typeof value}` });
    }
  }
  return { ok: issues.length === 0, issues };
}

export function normalizeEvent(catalog: readonly EventDefinition[], input: EventInput, sequence: number): NormalizeResult {
  const check = validateEvent(catalog, input);
  if (!check.ok) {
    return { ok: false, issues: check.issues };
  }
  const definition = findEvent(catalog, input.name) as EventDefinition;
  const props: Record<string, PropValue> = {};
  for (const key of Object.keys(input.payload).sort()) {
    props[key] = input.payload[key] as PropValue;
  }
  return {
    ok: true,
    event: {
      eventId: eventId([input.name, input.version, input.userId, input.tsMs, sequence]),
      name: input.name,
      version: input.version,
      category: definition.category,
      userId: input.userId,
      sessionId: input.sessionId,
      platform: input.platform,
      tsMs: input.tsMs,
      props,
    },
  };
}

export function eventId(parts: readonly (string | number)[]): string {
  let hash = 0x811c9dc5;
  const text = parts.join("|");
  for (let index = 0; index < text.length; index += 1) {
    hash ^= text.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return `evt_${hash.toString(16).padStart(8, "0")}`;
}

export function formatEvent(event: NormalizedEvent): string {
  const props = Object.keys(event.props).sort().map((key) => `${key}=${String(event.props[key])}`).join(" ");
  return `${event.eventId} ${event.name} v${event.version} user=${event.userId} platform=${event.platform} ${props}`;
}