2219 lines
62 KiB
Markdown
2219 lines
62 KiB
Markdown
# Analytics & Presence Service
|
||
|
||
RWA 用户活跃度与在线状态上下文微服务 - 基于 DDD 架构的 NestJS 实现
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: NestJS + TypeScript
|
||
- **ORM**: Prisma
|
||
- **消息队列**: Kafka
|
||
- **缓存**: Redis (ioredis)
|
||
- **定时任务**: @nestjs/schedule
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
analytics-presence-service/
|
||
├── src/
|
||
│ ├── api/ # 表现层
|
||
│ │ ├── controllers/
|
||
│ │ │ ├── analytics.controller.ts
|
||
│ │ │ └── presence.controller.ts
|
||
│ │ ├── dto/
|
||
│ │ │ ├── request/
|
||
│ │ │ │ ├── batch-events.dto.ts
|
||
│ │ │ │ ├── heartbeat.dto.ts
|
||
│ │ │ │ └── query-dau.dto.ts
|
||
│ │ │ └── response/
|
||
│ │ │ ├── dau-stats.dto.ts
|
||
│ │ │ ├── online-count.dto.ts
|
||
│ │ │ └── online-history.dto.ts
|
||
│ │ ├── validators/
|
||
│ │ │ └── event.validator.ts
|
||
│ │ └── api.module.ts
|
||
│ │
|
||
│ ├── application/ # 应用层
|
||
│ │ ├── commands/
|
||
│ │ │ ├── record-events/
|
||
│ │ │ │ ├── record-events.command.ts
|
||
│ │ │ │ └── record-events.handler.ts
|
||
│ │ │ ├── record-heartbeat/
|
||
│ │ │ │ ├── record-heartbeat.command.ts
|
||
│ │ │ │ └── record-heartbeat.handler.ts
|
||
│ │ │ └── calculate-dau/
|
||
│ │ │ ├── calculate-dau.command.ts
|
||
│ │ │ └── calculate-dau.handler.ts
|
||
│ │ ├── queries/
|
||
│ │ │ ├── get-dau-stats/
|
||
│ │ │ │ ├── get-dau-stats.query.ts
|
||
│ │ │ │ └── get-dau-stats.handler.ts
|
||
│ │ │ ├── get-online-count/
|
||
│ │ │ │ ├── get-online-count.query.ts
|
||
│ │ │ │ └── get-online-count.handler.ts
|
||
│ │ │ └── get-online-history/
|
||
│ │ │ ├── get-online-history.query.ts
|
||
│ │ │ └── get-online-history.handler.ts
|
||
│ │ ├── services/
|
||
│ │ │ └── analytics-application.service.ts
|
||
│ │ ├── schedulers/
|
||
│ │ │ └── analytics.scheduler.ts
|
||
│ │ └── application.module.ts
|
||
│ │
|
||
│ ├── domain/ # 领域层
|
||
│ │ ├── aggregates/
|
||
│ │ │ └── daily-active-stats/
|
||
│ │ │ ├── daily-active-stats.aggregate.ts
|
||
│ │ │ ├── daily-active-stats.factory.ts
|
||
│ │ │ └── daily-active-stats.spec.ts
|
||
│ │ ├── entities/
|
||
│ │ │ ├── event-log.entity.ts
|
||
│ │ │ └── online-snapshot.entity.ts
|
||
│ │ ├── value-objects/
|
||
│ │ │ ├── install-id.vo.ts
|
||
│ │ │ ├── event-name.vo.ts
|
||
│ │ │ ├── event-properties.vo.ts
|
||
│ │ │ ├── device-info.vo.ts
|
||
│ │ │ └── time-window.vo.ts
|
||
│ │ ├── events/
|
||
│ │ │ ├── session-started.event.ts
|
||
│ │ │ ├── heartbeat-received.event.ts
|
||
│ │ │ └── dau-calculated.event.ts
|
||
│ │ ├── repositories/
|
||
│ │ │ ├── event-log.repository.interface.ts
|
||
│ │ │ ├── daily-active-stats.repository.interface.ts
|
||
│ │ │ └── online-snapshot.repository.interface.ts
|
||
│ │ ├── services/
|
||
│ │ │ ├── dau-calculation.service.ts
|
||
│ │ │ └── online-detection.service.ts
|
||
│ │ └── domain.module.ts
|
||
│ │
|
||
│ ├── infrastructure/ # 基础设施层
|
||
│ │ ├── persistence/
|
||
│ │ │ ├── prisma/
|
||
│ │ │ │ ├── schema.prisma
|
||
│ │ │ │ └── prisma.service.ts
|
||
│ │ │ ├── entities/
|
||
│ │ │ │ ├── event-log.entity.ts
|
||
│ │ │ │ ├── daily-active-stats.entity.ts
|
||
│ │ │ │ └── online-snapshot.entity.ts
|
||
│ │ │ ├── mappers/
|
||
│ │ │ │ ├── event-log.mapper.ts
|
||
│ │ │ │ ├── daily-active-stats.mapper.ts
|
||
│ │ │ │ └── online-snapshot.mapper.ts
|
||
│ │ │ └── repositories/
|
||
│ │ │ ├── event-log.repository.impl.ts
|
||
│ │ │ ├── daily-active-stats.repository.impl.ts
|
||
│ │ │ └── online-snapshot.repository.impl.ts
|
||
│ │ ├── redis/
|
||
│ │ │ ├── redis.module.ts
|
||
│ │ │ ├── redis.service.ts
|
||
│ │ │ └── presence-redis.repository.ts
|
||
│ │ ├── kafka/
|
||
│ │ │ ├── kafka.module.ts
|
||
│ │ │ ├── event-publisher.service.ts
|
||
│ │ │ └── event-consumer.service.ts
|
||
│ │ └── infrastructure.module.ts
|
||
│ │
|
||
│ ├── shared/ # 共享层
|
||
│ │ ├── decorators/
|
||
│ │ │ ├── current-user.decorator.ts
|
||
│ │ │ └── public.decorator.ts
|
||
│ │ ├── guards/
|
||
│ │ │ ├── jwt-auth.guard.ts
|
||
│ │ │ └── optional-auth.guard.ts
|
||
│ │ ├── filters/
|
||
│ │ │ └── domain-exception.filter.ts
|
||
│ │ ├── interceptors/
|
||
│ │ │ └── transform.interceptor.ts
|
||
│ │ ├── exceptions/
|
||
│ │ │ ├── domain.exception.ts
|
||
│ │ │ └── application.exception.ts
|
||
│ │ └── utils/
|
||
│ │ └── timezone.util.ts
|
||
│ │
|
||
│ ├── config/
|
||
│ │ ├── app.config.ts
|
||
│ │ ├── database.config.ts
|
||
│ │ ├── redis.config.ts
|
||
│ │ ├── jwt.config.ts
|
||
│ │ └── kafka.config.ts
|
||
│ │
|
||
│ ├── app.module.ts
|
||
│ └── main.ts
|
||
│
|
||
├── test/
|
||
│ ├── unit/
|
||
│ ├── integration/
|
||
│ └── e2e/
|
||
│
|
||
├── database/
|
||
│ └── migrations/
|
||
│
|
||
├── prisma/
|
||
│ └── schema.prisma
|
||
│
|
||
├── .env.example
|
||
├── .env.development
|
||
├── .env.production
|
||
├── Dockerfile
|
||
├── docker-compose.yml
|
||
├── package.json
|
||
├── tsconfig.json
|
||
└── README.md
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
- ✅ 用户行为事件批量上报与存储
|
||
- ✅ 日活 DAU 统计（按自然日去重）
|
||
- ✅ 实时在线人数统计（3分钟窗口）
|
||
- ✅ 心跳机制（前台60秒间隔）
|
||
- ✅ 按省/市维度的活跃用户分析
|
||
- ✅ 在线人数历史趋势查询
|
||
- ✅ 与 Identity Context 的用户标识集成
|
||
- ✅ Kafka 事件发布（供其他服务订阅）
|
||
|
||
---
|
||
|
||
## 一、领域层设计
|
||
|
||
### 1.1 聚合根：DailyActiveStats
|
||
|
||
```typescript
|
||
// src/domain/aggregates/daily-active-stats/daily-active-stats.aggregate.ts
|
||
|
||
import { AggregateRoot } from '@nestjs/cqrs';
|
||
import { DauCalculatedEvent } from '../../events/dau-calculated.event';
|
||
|
||
export class DailyActiveStats extends AggregateRoot {
|
||
private _day: Date;
|
||
private _dauCount: number;
|
||
private _dauByProvince: Map<string, number>;
|
||
private _dauByCity: Map<string, number>;
|
||
private _calculatedAt: Date;
|
||
private _version: number;
|
||
|
||
private constructor() {
|
||
super();
|
||
}
|
||
|
||
// Getters
|
||
get day(): Date {
|
||
return this._day;
|
||
}
|
||
|
||
get dauCount(): number {
|
||
return this._dauCount;
|
||
}
|
||
|
||
get dauByProvince(): Map<string, number> {
|
||
return new Map(this._dauByProvince);
|
||
}
|
||
|
||
get dauByCity(): Map<string, number> {
|
||
return new Map(this._dauByCity);
|
||
}
|
||
|
||
get calculatedAt(): Date {
|
||
return this._calculatedAt;
|
||
}
|
||
|
||
get version(): number {
|
||
return this._version;
|
||
}
|
||
|
||
// 工厂方法
|
||
static create(props: {
|
||
day: Date;
|
||
dauCount: number;
|
||
dauByProvince?: Map<string, number>;
|
||
dauByCity?: Map<string, number>;
|
||
}): DailyActiveStats {
|
||
const stats = new DailyActiveStats();
|
||
stats._day = props.day;
|
||
stats._dauCount = props.dauCount;
|
||
stats._dauByProvince = props.dauByProvince ?? new Map();
|
||
stats._dauByCity = props.dauByCity ?? new Map();
|
||
stats._calculatedAt = new Date();
|
||
stats._version = 1;
|
||
|
||
stats.apply(new DauCalculatedEvent(stats._day, stats._dauCount));
|
||
return stats;
|
||
}
|
||
|
||
// 重新计算
|
||
recalculate(newDauCount: number, byProvince?: Map<string, number>, byCity?: Map<string, number>): void {
|
||
this._dauCount = newDauCount;
|
||
if (byProvince) this._dauByProvince = byProvince;
|
||
if (byCity) this._dauByCity = byCity;
|
||
this._calculatedAt = new Date();
|
||
this._version++;
|
||
|
||
this.apply(new DauCalculatedEvent(this._day, this._dauCount));
|
||
}
|
||
|
||
// 从持久化恢复
|
||
static reconstitute(props: {
|
||
day: Date;
|
||
dauCount: number;
|
||
dauByProvince: Map<string, number>;
|
||
dauByCity: Map<string, number>;
|
||
calculatedAt: Date;
|
||
version: number;
|
||
}): DailyActiveStats {
|
||
const stats = new DailyActiveStats();
|
||
stats._day = props.day;
|
||
stats._dauCount = props.dauCount;
|
||
stats._dauByProvince = props.dauByProvince;
|
||
stats._dauByCity = props.dauByCity;
|
||
stats._calculatedAt = props.calculatedAt;
|
||
stats._version = props.version;
|
||
return stats;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 实体：EventLog
|
||
|
||
```typescript
|
||
// src/domain/entities/event-log.entity.ts
|
||
|
||
import { InstallId } from '../value-objects/install-id.vo';
|
||
import { EventName } from '../value-objects/event-name.vo';
|
||
import { EventProperties } from '../value-objects/event-properties.vo';
|
||
|
||
export class EventLog {
|
||
private _id: bigint | null;
|
||
private _userId: bigint | null;
|
||
private _installId: InstallId;
|
||
private _eventName: EventName;
|
||
private _eventTime: Date;
|
||
private _properties: EventProperties;
|
||
private _createdAt: Date;
|
||
|
||
private constructor() {}
|
||
|
||
// Getters
|
||
get id(): bigint | null {
|
||
return this._id;
|
||
}
|
||
|
||
get userId(): bigint | null {
|
||
return this._userId;
|
||
}
|
||
|
||
get installId(): InstallId {
|
||
return this._installId;
|
||
}
|
||
|
||
get eventName(): EventName {
|
||
return this._eventName;
|
||
}
|
||
|
||
get eventTime(): Date {
|
||
return this._eventTime;
|
||
}
|
||
|
||
get properties(): EventProperties {
|
||
return this._properties;
|
||
}
|
||
|
||
get createdAt(): Date {
|
||
return this._createdAt;
|
||
}
|
||
|
||
/**
|
||
* 获取用于DAU去重的唯一标识
|
||
* 优先使用 userId，否则使用 installId
|
||
*/
|
||
get dauIdentifier(): string {
|
||
return this._userId?.toString() ?? this._installId.value;
|
||
}
|
||
|
||
// 工厂方法
|
||
static create(props: {
|
||
userId?: bigint | null;
|
||
installId: InstallId;
|
||
eventName: EventName;
|
||
eventTime: Date;
|
||
properties?: EventProperties;
|
||
}): EventLog {
|
||
const log = new EventLog();
|
||
log._id = null;
|
||
log._userId = props.userId ?? null;
|
||
log._installId = props.installId;
|
||
log._eventName = props.eventName;
|
||
log._eventTime = props.eventTime;
|
||
log._properties = props.properties ?? EventProperties.empty();
|
||
log._createdAt = new Date();
|
||
return log;
|
||
}
|
||
|
||
// 从持久化恢复
|
||
static reconstitute(props: {
|
||
id: bigint;
|
||
userId: bigint | null;
|
||
installId: InstallId;
|
||
eventName: EventName;
|
||
eventTime: Date;
|
||
properties: EventProperties;
|
||
createdAt: Date;
|
||
}): EventLog {
|
||
const log = new EventLog();
|
||
log._id = props.id;
|
||
log._userId = props.userId;
|
||
log._installId = props.installId;
|
||
log._eventName = props.eventName;
|
||
log._eventTime = props.eventTime;
|
||
log._properties = props.properties;
|
||
log._createdAt = props.createdAt;
|
||
return log;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.3 实体：OnlineSnapshot
|
||
|
||
```typescript
|
||
// src/domain/entities/online-snapshot.entity.ts
|
||
|
||
import { TimeWindow } from '../value-objects/time-window.vo';
|
||
|
||
export class OnlineSnapshot {
|
||
private _id: bigint | null;
|
||
private _ts: Date;
|
||
private _onlineCount: number;
|
||
private _windowSeconds: number;
|
||
|
||
private constructor() {}
|
||
|
||
get id(): bigint | null {
|
||
return this._id;
|
||
}
|
||
|
||
get ts(): Date {
|
||
return this._ts;
|
||
}
|
||
|
||
get onlineCount(): number {
|
||
return this._onlineCount;
|
||
}
|
||
|
||
get windowSeconds(): number {
|
||
return this._windowSeconds;
|
||
}
|
||
|
||
static create(props: {
|
||
ts: Date;
|
||
onlineCount: number;
|
||
windowSeconds?: number;
|
||
}): OnlineSnapshot {
|
||
const snapshot = new OnlineSnapshot();
|
||
snapshot._id = null;
|
||
snapshot._ts = props.ts;
|
||
snapshot._onlineCount = props.onlineCount;
|
||
snapshot._windowSeconds = props.windowSeconds ?? TimeWindow.DEFAULT_ONLINE_WINDOW_SECONDS;
|
||
return snapshot;
|
||
}
|
||
|
||
static reconstitute(props: {
|
||
id: bigint;
|
||
ts: Date;
|
||
onlineCount: number;
|
||
windowSeconds: number;
|
||
}): OnlineSnapshot {
|
||
const snapshot = new OnlineSnapshot();
|
||
snapshot._id = props.id;
|
||
snapshot._ts = props.ts;
|
||
snapshot._onlineCount = props.onlineCount;
|
||
snapshot._windowSeconds = props.windowSeconds;
|
||
return snapshot;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.4 值对象
|
||
|
||
```typescript
|
||
// src/domain/value-objects/install-id.vo.ts
|
||
|
||
import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
|
||
import { DomainException } from '../../shared/exceptions/domain.exception';
|
||
|
||
export class InstallId {
|
||
private readonly _value: string;
|
||
|
||
private constructor(value: string) {
|
||
this._value = value;
|
||
}
|
||
|
||
get value(): string {
|
||
return this._value;
|
||
}
|
||
|
||
static generate(): InstallId {
|
||
return new InstallId(uuidv4());
|
||
}
|
||
|
||
static fromString(value: string): InstallId {
|
||
if (!value || value.trim() === '') {
|
||
throw new DomainException('InstallId cannot be empty');
|
||
}
|
||
// 允许非UUID格式，但需要有基本长度
|
||
if (value.length < 8 || value.length > 128) {
|
||
throw new DomainException('InstallId length must be between 8 and 128 characters');
|
||
}
|
||
return new InstallId(value.trim());
|
||
}
|
||
|
||
equals(other: InstallId): boolean {
|
||
return this._value === other._value;
|
||
}
|
||
|
||
toString(): string {
|
||
return this._value;
|
||
}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/value-objects/event-name.vo.ts
|
||
|
||
import { DomainException } from '../../shared/exceptions/domain.exception';
|
||
|
||
export class EventName {
|
||
// 预定义的事件名
|
||
static readonly APP_SESSION_START = new EventName('app_session_start');
|
||
static readonly PRESENCE_HEARTBEAT = new EventName('presence_heartbeat');
|
||
static readonly APP_SESSION_END = new EventName('app_session_end');
|
||
|
||
private readonly _value: string;
|
||
|
||
private constructor(value: string) {
|
||
this._value = value;
|
||
}
|
||
|
||
get value(): string {
|
||
return this._value;
|
||
}
|
||
|
||
static fromString(value: string): EventName {
|
||
if (!value || value.trim() === '') {
|
||
throw new DomainException('EventName cannot be empty');
|
||
}
|
||
const trimmed = value.trim().toLowerCase();
|
||
if (trimmed.length > 64) {
|
||
throw new DomainException('EventName cannot exceed 64 characters');
|
||
}
|
||
// 验证格式：字母、数字、下划线
|
||
if (!/^[a-z][a-z0-9_]*$/.test(trimmed)) {
|
||
throw new DomainException('EventName must start with letter and contain only lowercase letters, numbers, and underscores');
|
||
}
|
||
return new EventName(trimmed);
|
||
}
|
||
|
||
/**
|
||
* 是否为DAU统计事件
|
||
*/
|
||
isDauEvent(): boolean {
|
||
return this._value === EventName.APP_SESSION_START.value;
|
||
}
|
||
|
||
equals(other: EventName): boolean {
|
||
return this._value === other._value;
|
||
}
|
||
|
||
toString(): string {
|
||
return this._value;
|
||
}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/value-objects/event-properties.vo.ts
|
||
|
||
export interface EventPropertiesData {
|
||
os?: string;
|
||
osVersion?: string;
|
||
appVersion?: string;
|
||
networkType?: string;
|
||
clientTs?: number;
|
||
province?: string;
|
||
city?: string;
|
||
[key: string]: unknown;
|
||
}
|
||
|
||
export class EventProperties {
|
||
private readonly _data: EventPropertiesData;
|
||
|
||
private constructor(data: EventPropertiesData) {
|
||
this._data = { ...data };
|
||
}
|
||
|
||
get data(): EventPropertiesData {
|
||
return { ...this._data };
|
||
}
|
||
|
||
get os(): string | undefined {
|
||
return this._data.os;
|
||
}
|
||
|
||
get osVersion(): string | undefined {
|
||
return this._data.osVersion;
|
||
}
|
||
|
||
get appVersion(): string | undefined {
|
||
return this._data.appVersion;
|
||
}
|
||
|
||
get networkType(): string | undefined {
|
||
return this._data.networkType;
|
||
}
|
||
|
||
get clientTs(): number | undefined {
|
||
return this._data.clientTs;
|
||
}
|
||
|
||
get province(): string | undefined {
|
||
return this._data.province;
|
||
}
|
||
|
||
get city(): string | undefined {
|
||
return this._data.city;
|
||
}
|
||
|
||
static empty(): EventProperties {
|
||
return new EventProperties({});
|
||
}
|
||
|
||
static fromData(data: EventPropertiesData): EventProperties {
|
||
return new EventProperties(data);
|
||
}
|
||
|
||
toJSON(): EventPropertiesData {
|
||
return this._data;
|
||
}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/value-objects/device-info.vo.ts
|
||
|
||
export class DeviceInfo {
|
||
private readonly _os: 'Android' | 'iOS';
|
||
private readonly _osVersion: string;
|
||
private readonly _deviceModel?: string;
|
||
private readonly _screenResolution?: string;
|
||
|
||
private constructor(props: {
|
||
os: 'Android' | 'iOS';
|
||
osVersion: string;
|
||
deviceModel?: string;
|
||
screenResolution?: string;
|
||
}) {
|
||
this._os = props.os;
|
||
this._osVersion = props.osVersion;
|
||
this._deviceModel = props.deviceModel;
|
||
this._screenResolution = props.screenResolution;
|
||
}
|
||
|
||
get os(): 'Android' | 'iOS' {
|
||
return this._os;
|
||
}
|
||
|
||
get osVersion(): string {
|
||
return this._osVersion;
|
||
}
|
||
|
||
get deviceModel(): string | undefined {
|
||
return this._deviceModel;
|
||
}
|
||
|
||
get screenResolution(): string | undefined {
|
||
return this._screenResolution;
|
||
}
|
||
|
||
static create(props: {
|
||
os: string;
|
||
osVersion: string;
|
||
deviceModel?: string;
|
||
screenResolution?: string;
|
||
}): DeviceInfo {
|
||
const normalizedOs = props.os.toLowerCase() === 'ios' ? 'iOS' : 'Android';
|
||
return new DeviceInfo({
|
||
os: normalizedOs,
|
||
osVersion: props.osVersion,
|
||
deviceModel: props.deviceModel,
|
||
screenResolution: props.screenResolution,
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/value-objects/time-window.vo.ts
|
||
|
||
export class TimeWindow {
|
||
static readonly DEFAULT_ONLINE_WINDOW_SECONDS = 180; // 3分钟
|
||
static readonly DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 60; // 60秒
|
||
|
||
private readonly _windowSeconds: number;
|
||
|
||
private constructor(windowSeconds: number) {
|
||
this._windowSeconds = windowSeconds;
|
||
}
|
||
|
||
get windowSeconds(): number {
|
||
return this._windowSeconds;
|
||
}
|
||
|
||
static default(): TimeWindow {
|
||
return new TimeWindow(TimeWindow.DEFAULT_ONLINE_WINDOW_SECONDS);
|
||
}
|
||
|
||
static ofSeconds(seconds: number): TimeWindow {
|
||
if (seconds <= 0) {
|
||
throw new Error('TimeWindow must be positive');
|
||
}
|
||
return new TimeWindow(seconds);
|
||
}
|
||
|
||
/**
|
||
* 计算在线阈值时间戳
|
||
*/
|
||
getThresholdTimestamp(now: Date = new Date()): number {
|
||
return Math.floor(now.getTime() / 1000) - this._windowSeconds;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.5 领域事件
|
||
|
||
```typescript
|
||
// src/domain/events/session-started.event.ts
|
||
|
||
export class SessionStartedEvent {
|
||
static readonly EVENT_NAME = 'analytics.session.started';
|
||
|
||
constructor(
|
||
public readonly userId: bigint | null,
|
||
public readonly installId: string,
|
||
public readonly occurredAt: Date,
|
||
public readonly metadata: {
|
||
appVersion?: string;
|
||
os?: string;
|
||
osVersion?: string;
|
||
},
|
||
) {}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/events/heartbeat-received.event.ts
|
||
|
||
export class HeartbeatReceivedEvent {
|
||
static readonly EVENT_NAME = 'presence.heartbeat.received';
|
||
|
||
constructor(
|
||
public readonly userId: bigint,
|
||
public readonly installId: string,
|
||
public readonly occurredAt: Date,
|
||
) {}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/events/dau-calculated.event.ts
|
||
|
||
export class DauCalculatedEvent {
|
||
static readonly EVENT_NAME = 'analytics.dau.calculated';
|
||
|
||
constructor(
|
||
public readonly day: Date,
|
||
public readonly dauCount: number,
|
||
) {}
|
||
}
|
||
```
|
||
|
||
### 1.6 仓储接口
|
||
|
||
```typescript
|
||
// src/domain/repositories/event-log.repository.interface.ts
|
||
|
||
import { EventLog } from '../entities/event-log.entity';
|
||
import { EventName } from '../value-objects/event-name.vo';
|
||
|
||
export interface DauQueryResult {
|
||
total: number;
|
||
byProvince: Map<string, number>;
|
||
byCity: Map<string, number>;
|
||
}
|
||
|
||
export interface IEventLogRepository {
|
||
/**
|
||
* 批量插入事件日志
|
||
*/
|
||
batchInsert(logs: EventLog[]): Promise<void>;
|
||
|
||
/**
|
||
* 插入单条事件日志
|
||
*/
|
||
insert(log: EventLog): Promise<EventLog>;
|
||
|
||
/**
|
||
* 查询DAU（去重用户数）
|
||
*/
|
||
queryDau(
|
||
eventName: EventName,
|
||
startTime: Date,
|
||
endTime: Date,
|
||
): Promise<DauQueryResult>;
|
||
|
||
/**
|
||
* 按时间范围查询事件
|
||
*/
|
||
findByTimeRange(
|
||
eventName: EventName,
|
||
startTime: Date,
|
||
endTime: Date,
|
||
limit?: number,
|
||
): Promise<EventLog[]>;
|
||
}
|
||
|
||
export const EVENT_LOG_REPOSITORY = Symbol('IEventLogRepository');
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/repositories/daily-active-stats.repository.interface.ts
|
||
|
||
import { DailyActiveStats } from '../aggregates/daily-active-stats/daily-active-stats.aggregate';
|
||
|
||
export interface IDailyActiveStatsRepository {
|
||
/**
|
||
* 保存或更新日活统计
|
||
*/
|
||
upsert(stats: DailyActiveStats): Promise<void>;
|
||
|
||
/**
|
||
* 按日期查询
|
||
*/
|
||
findByDate(day: Date): Promise<DailyActiveStats | null>;
|
||
|
||
/**
|
||
* 按日期范围查询
|
||
*/
|
||
findByDateRange(startDate: Date, endDate: Date): Promise<DailyActiveStats[]>;
|
||
}
|
||
|
||
export const DAILY_ACTIVE_STATS_REPOSITORY = Symbol('IDailyActiveStatsRepository');
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/repositories/online-snapshot.repository.interface.ts
|
||
|
||
import { OnlineSnapshot } from '../entities/online-snapshot.entity';
|
||
|
||
export interface IOnlineSnapshotRepository {
|
||
/**
|
||
* 插入快照
|
||
*/
|
||
insert(snapshot: OnlineSnapshot): Promise<OnlineSnapshot>;
|
||
|
||
/**
|
||
* 按时间范围查询
|
||
*/
|
||
findByTimeRange(
|
||
startTime: Date,
|
||
endTime: Date,
|
||
interval?: '1m' | '5m' | '1h',
|
||
): Promise<OnlineSnapshot[]>;
|
||
|
||
/**
|
||
* 获取最新快照
|
||
*/
|
||
findLatest(): Promise<OnlineSnapshot | null>;
|
||
}
|
||
|
||
export const ONLINE_SNAPSHOT_REPOSITORY = Symbol('IOnlineSnapshotRepository');
|
||
```
|
||
|
||
### 1.7 领域服务
|
||
|
||
```typescript
|
||
// src/domain/services/dau-calculation.service.ts
|
||
|
||
import { Injectable } from '@nestjs/common';
|
||
import { DailyActiveStats } from '../aggregates/daily-active-stats/daily-active-stats.aggregate';
|
||
import { DauQueryResult } from '../repositories/event-log.repository.interface';
|
||
|
||
@Injectable()
|
||
export class DauCalculationService {
|
||
/**
|
||
* 从查询结果创建日活统计聚合
|
||
*/
|
||
createStatsFromQueryResult(day: Date, result: DauQueryResult): DailyActiveStats {
|
||
return DailyActiveStats.create({
|
||
day,
|
||
dauCount: result.total,
|
||
dauByProvince: result.byProvince,
|
||
dauByCity: result.byCity,
|
||
});
|
||
}
|
||
|
||
/**
|
||
* 合并多个查询结果（用于增量计算）
|
||
*/
|
||
mergeQueryResults(results: DauQueryResult[]): DauQueryResult {
|
||
const allIdentifiers = new Set<string>();
|
||
const byProvince = new Map<string, Set<string>>();
|
||
const byCity = new Map<string, Set<string>>();
|
||
|
||
// 注意：这里简化处理，实际需要原始数据才能正确去重
|
||
// 生产环境应该在数据库层面完成去重
|
||
let total = 0;
|
||
const provinceCount = new Map<string, number>();
|
||
const cityCount = new Map<string, number>();
|
||
|
||
for (const result of results) {
|
||
total = Math.max(total, result.total);
|
||
for (const [province, count] of result.byProvince) {
|
||
provinceCount.set(province, Math.max(provinceCount.get(province) ?? 0, count));
|
||
}
|
||
for (const [city, count] of result.byCity) {
|
||
cityCount.set(city, Math.max(cityCount.get(city) ?? 0, count));
|
||
}
|
||
}
|
||
|
||
return {
|
||
total,
|
||
byProvince: provinceCount,
|
||
byCity: cityCount,
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/services/online-detection.service.ts
|
||
|
||
import { Injectable } from '@nestjs/common';
|
||
import { TimeWindow } from '../value-objects/time-window.vo';
|
||
|
||
@Injectable()
|
||
export class OnlineDetectionService {
|
||
private readonly timeWindow: TimeWindow;
|
||
|
||
constructor() {
|
||
this.timeWindow = TimeWindow.default();
|
||
}
|
||
|
||
/**
|
||
* 判断用户是否在线
|
||
*/
|
||
isOnline(lastHeartbeatTs: number, now: Date = new Date()): boolean {
|
||
const threshold = this.timeWindow.getThresholdTimestamp(now);
|
||
return lastHeartbeatTs > threshold;
|
||
}
|
||
|
||
/**
|
||
* 获取在线判定阈值时间戳
|
||
*/
|
||
getOnlineThreshold(now: Date = new Date()): number {
|
||
return this.timeWindow.getThresholdTimestamp(now);
|
||
}
|
||
|
||
/**
|
||
* 获取窗口秒数
|
||
*/
|
||
getWindowSeconds(): number {
|
||
return this.timeWindow.windowSeconds;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 二、应用层设计
|
||
|
||
### 2.1 命令：RecordEvents
|
||
|
||
```typescript
|
||
// src/application/commands/record-events/record-events.command.ts
|
||
|
||
export interface EventItemDto {
|
||
eventName: string;
|
||
userId?: string;
|
||
installId: string;
|
||
clientTs: number;
|
||
properties?: Record<string, unknown>;
|
||
}
|
||
|
||
export class RecordEventsCommand {
|
||
constructor(public readonly events: EventItemDto[]) {}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/application/commands/record-events/record-events.handler.ts
|
||
|
||
import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
|
||
import { Inject, Injectable } from '@nestjs/common';
|
||
import { RecordEventsCommand, EventItemDto } from './record-events.command';
|
||
import { EventLog } from '../../../domain/entities/event-log.entity';
|
||
import { InstallId } from '../../../domain/value-objects/install-id.vo';
|
||
import { EventName } from '../../../domain/value-objects/event-name.vo';
|
||
import { EventProperties } from '../../../domain/value-objects/event-properties.vo';
|
||
import {
|
||
IEventLogRepository,
|
||
EVENT_LOG_REPOSITORY,
|
||
} from '../../../domain/repositories/event-log.repository.interface';
|
||
import { RedisService } from '../../../infrastructure/redis/redis.service';
|
||
import { EventPublisherService } from '../../../infrastructure/kafka/event-publisher.service';
|
||
import { SessionStartedEvent } from '../../../domain/events/session-started.event';
|
||
import { formatToDateKey } from '../../../shared/utils/timezone.util';
|
||
|
||
export interface RecordEventsResult {
|
||
accepted: number;
|
||
failed: number;
|
||
errors?: string[];
|
||
}
|
||
|
||
@Injectable()
|
||
@CommandHandler(RecordEventsCommand)
|
||
export class RecordEventsHandler implements ICommandHandler<RecordEventsCommand> {
|
||
constructor(
|
||
@Inject(EVENT_LOG_REPOSITORY)
|
||
private readonly eventLogRepository: IEventLogRepository,
|
||
private readonly redisService: RedisService,
|
||
private readonly eventPublisher: EventPublisherService,
|
||
) {}
|
||
|
||
async execute(command: RecordEventsCommand): Promise<RecordEventsResult> {
|
||
const { events } = command;
|
||
const errors: string[] = [];
|
||
const validLogs: EventLog[] = [];
|
||
|
||
// 1. 验证并转换事件
|
||
for (let i = 0; i < events.length; i++) {
|
||
try {
|
||
const log = this.toEventLog(events[i]);
|
||
validLogs.push(log);
|
||
} catch (e) {
|
||
errors.push(`Event[${i}]: ${e.message}`);
|
||
}
|
||
}
|
||
|
||
if (validLogs.length === 0) {
|
||
return { accepted: 0, failed: events.length, errors };
|
||
}
|
||
|
||
// 2. 批量写入数据库
|
||
await this.eventLogRepository.batchInsert(validLogs);
|
||
|
||
// 3. 更新实时DAU (HyperLogLog)
|
||
const todayKey = formatToDateKey(new Date());
|
||
for (const log of validLogs) {
|
||
if (log.eventName.isDauEvent()) {
|
||
await this.redisService.pfadd(
|
||
`analytics:dau:${todayKey}`,
|
||
log.dauIdentifier,
|
||
);
|
||
|
||
// 4. 发布领域事件
|
||
await this.eventPublisher.publish(
|
||
SessionStartedEvent.EVENT_NAME,
|
||
new SessionStartedEvent(
|
||
log.userId,
|
||
log.installId.value,
|
||
log.eventTime,
|
||
{
|
||
appVersion: log.properties.appVersion,
|
||
os: log.properties.os,
|
||
osVersion: log.properties.osVersion,
|
||
},
|
||
),
|
||
);
|
||
}
|
||
}
|
||
|
||
return {
|
||
accepted: validLogs.length,
|
||
failed: events.length - validLogs.length,
|
||
errors: errors.length > 0 ? errors : undefined,
|
||
};
|
||
}
|
||
|
||
private toEventLog(dto: EventItemDto): EventLog {
|
||
return EventLog.create({
|
||
userId: dto.userId ? BigInt(dto.userId) : null,
|
||
installId: InstallId.fromString(dto.installId),
|
||
eventName: EventName.fromString(dto.eventName),
|
||
eventTime: new Date(dto.clientTs * 1000),
|
||
properties: EventProperties.fromData(dto.properties ?? {}),
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 命令：RecordHeartbeat
|
||
|
||
```typescript
|
||
// src/application/commands/record-heartbeat/record-heartbeat.command.ts
|
||
|
||
export class RecordHeartbeatCommand {
|
||
constructor(
|
||
public readonly userId: bigint,
|
||
public readonly installId: string,
|
||
public readonly appVersion: string,
|
||
public readonly clientTs: number,
|
||
) {}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/application/commands/record-heartbeat/record-heartbeat.handler.ts
|
||
|
||
import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
|
||
import { Injectable } from '@nestjs/common';
|
||
import { RecordHeartbeatCommand } from './record-heartbeat.command';
|
||
import { PresenceRedisRepository } from '../../../infrastructure/redis/presence-redis.repository';
|
||
import { EventPublisherService } from '../../../infrastructure/kafka/event-publisher.service';
|
||
import { HeartbeatReceivedEvent } from '../../../domain/events/heartbeat-received.event';
|
||
|
||
export interface RecordHeartbeatResult {
|
||
ok: boolean;
|
||
serverTs: number;
|
||
}
|
||
|
||
@Injectable()
|
||
@CommandHandler(RecordHeartbeatCommand)
|
||
export class RecordHeartbeatHandler implements ICommandHandler<RecordHeartbeatCommand> {
|
||
constructor(
|
||
private readonly presenceRedisRepository: PresenceRedisRepository,
|
||
private readonly eventPublisher: EventPublisherService,
|
||
) {}
|
||
|
||
async execute(command: RecordHeartbeatCommand): Promise<RecordHeartbeatResult> {
|
||
const { userId, installId, appVersion, clientTs } = command;
|
||
const now = Math.floor(Date.now() / 1000);
|
||
|
||
// 1. 更新Redis在线状态
|
||
await this.presenceRedisRepository.updateUserPresence(userId.toString(), now);
|
||
|
||
// 2. 发布领域事件
|
||
await this.eventPublisher.publish(
|
||
HeartbeatReceivedEvent.EVENT_NAME,
|
||
new HeartbeatReceivedEvent(userId, installId, new Date()),
|
||
);
|
||
|
||
return { ok: true, serverTs: now };
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 命令：CalculateDau
|
||
|
||
```typescript
|
||
// src/application/commands/calculate-dau/calculate-dau.command.ts
|
||
|
||
export class CalculateDauCommand {
|
||
constructor(public readonly date: Date) {}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/application/commands/calculate-dau/calculate-dau.handler.ts
|
||
|
||
import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
|
||
import { Inject, Injectable, Logger } from '@nestjs/common';
|
||
import { CalculateDauCommand } from './calculate-dau.command';
|
||
import {
|
||
IEventLogRepository,
|
||
EVENT_LOG_REPOSITORY,
|
||
} from '../../../domain/repositories/event-log.repository.interface';
|
||
import {
|
||
IDailyActiveStatsRepository,
|
||
DAILY_ACTIVE_STATS_REPOSITORY,
|
||
} from '../../../domain/repositories/daily-active-stats.repository.interface';
|
||
import { DauCalculationService } from '../../../domain/services/dau-calculation.service';
|
||
import { EventName } from '../../../domain/value-objects/event-name.vo';
|
||
import {
|
||
startOfDayInTimezone,
|
||
endOfDayInTimezone,
|
||
} from '../../../shared/utils/timezone.util';
|
||
|
||
@Injectable()
|
||
@CommandHandler(CalculateDauCommand)
|
||
export class CalculateDauHandler implements ICommandHandler<CalculateDauCommand> {
|
||
private readonly logger = new Logger(CalculateDauHandler.name);
|
||
|
||
constructor(
|
||
@Inject(EVENT_LOG_REPOSITORY)
|
||
private readonly eventLogRepository: IEventLogRepository,
|
||
@Inject(DAILY_ACTIVE_STATS_REPOSITORY)
|
||
private readonly dauStatsRepository: IDailyActiveStatsRepository,
|
||
private readonly dauCalculationService: DauCalculationService,
|
||
) {}
|
||
|
||
async execute(command: CalculateDauCommand): Promise<void> {
|
||
const { date } = command;
|
||
const timezone = 'Asia/Shanghai';
|
||
|
||
const startOfDay = startOfDayInTimezone(date, timezone);
|
||
const endOfDay = endOfDayInTimezone(date, timezone);
|
||
|
||
this.logger.log(`Calculating DAU for ${date.toISOString().split('T')[0]}`);
|
||
|
||
// 1. 查询去重用户数
|
||
const result = await this.eventLogRepository.queryDau(
|
||
EventName.APP_SESSION_START,
|
||
startOfDay,
|
||
endOfDay,
|
||
);
|
||
|
||
// 2. 创建或更新统计聚合
|
||
const existingStats = await this.dauStatsRepository.findByDate(date);
|
||
|
||
if (existingStats) {
|
||
existingStats.recalculate(result.total, result.byProvince, result.byCity);
|
||
await this.dauStatsRepository.upsert(existingStats);
|
||
} else {
|
||
const stats = this.dauCalculationService.createStatsFromQueryResult(date, result);
|
||
await this.dauStatsRepository.upsert(stats);
|
||
}
|
||
|
||
this.logger.log(`DAU calculated: ${result.total} users`);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 查询：GetOnlineCount
|
||
|
||
```typescript
|
||
// src/application/queries/get-online-count/get-online-count.query.ts
|
||
|
||
export class GetOnlineCountQuery {
|
||
constructor() {}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/application/queries/get-online-count/get-online-count.handler.ts
|
||
|
||
import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
|
||
import { Injectable } from '@nestjs/common';
|
||
import { GetOnlineCountQuery } from './get-online-count.query';
|
||
import { PresenceRedisRepository } from '../../../infrastructure/redis/presence-redis.repository';
|
||
import { OnlineDetectionService } from '../../../domain/services/online-detection.service';
|
||
|
||
export interface OnlineCountResult {
|
||
count: number;
|
||
windowSeconds: number;
|
||
queriedAt: Date;
|
||
}
|
||
|
||
@Injectable()
|
||
@QueryHandler(GetOnlineCountQuery)
|
||
export class GetOnlineCountHandler implements IQueryHandler<GetOnlineCountQuery> {
|
||
constructor(
|
||
private readonly presenceRedisRepository: PresenceRedisRepository,
|
||
private readonly onlineDetectionService: OnlineDetectionService,
|
||
) {}
|
||
|
||
async execute(query: GetOnlineCountQuery): Promise<OnlineCountResult> {
|
||
const now = new Date();
|
||
const threshold = this.onlineDetectionService.getOnlineThreshold(now);
|
||
|
||
const count = await this.presenceRedisRepository.countOnlineUsers(threshold);
|
||
|
||
return {
|
||
count,
|
||
windowSeconds: this.onlineDetectionService.getWindowSeconds(),
|
||
queriedAt: now,
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.5 查询：GetDauStats
|
||
|
||
```typescript
|
||
// src/application/queries/get-dau-stats/get-dau-stats.query.ts
|
||
|
||
export class GetDauStatsQuery {
|
||
constructor(
|
||
public readonly startDate: Date,
|
||
public readonly endDate: Date,
|
||
) {}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/application/queries/get-dau-stats/get-dau-stats.handler.ts
|
||
|
||
import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
|
||
import { Inject, Injectable } from '@nestjs/common';
|
||
import { GetDauStatsQuery } from './get-dau-stats.query';
|
||
import {
|
||
IDailyActiveStatsRepository,
|
||
DAILY_ACTIVE_STATS_REPOSITORY,
|
||
} from '../../../domain/repositories/daily-active-stats.repository.interface';
|
||
|
||
export interface DauStatsItem {
|
||
day: string;
|
||
dauCount: number;
|
||
byProvince?: Record<string, number>;
|
||
byCity?: Record<string, number>;
|
||
}
|
||
|
||
export interface DauStatsResult {
|
||
data: DauStatsItem[];
|
||
total: number;
|
||
}
|
||
|
||
@Injectable()
|
||
@QueryHandler(GetDauStatsQuery)
|
||
export class GetDauStatsHandler implements IQueryHandler<GetDauStatsQuery> {
|
||
constructor(
|
||
@Inject(DAILY_ACTIVE_STATS_REPOSITORY)
|
||
private readonly dauStatsRepository: IDailyActiveStatsRepository,
|
||
) {}
|
||
|
||
async execute(query: GetDauStatsQuery): Promise<DauStatsResult> {
|
||
const { startDate, endDate } = query;
|
||
|
||
const statsList = await this.dauStatsRepository.findByDateRange(startDate, endDate);
|
||
|
||
const data: DauStatsItem[] = statsList.map((stats) => ({
|
||
day: stats.day.toISOString().split('T')[0],
|
||
dauCount: stats.dauCount,
|
||
byProvince: Object.fromEntries(stats.dauByProvince),
|
||
byCity: Object.fromEntries(stats.dauByCity),
|
||
}));
|
||
|
||
return {
|
||
data,
|
||
total: data.length,
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.6 定时任务
|
||
|
||
```typescript
|
||
// src/application/schedulers/analytics.scheduler.ts
|
||
|
||
import { Injectable, Logger } from '@nestjs/common';
|
||
import { Cron, CronExpression } from '@nestjs/schedule';
|
||
import { CommandBus } from '@nestjs/cqrs';
|
||
import { subDays } from 'date-fns';
|
||
import { CalculateDauCommand } from '../commands/calculate-dau/calculate-dau.command';
|
||
import { PresenceRedisRepository } from '../../infrastructure/redis/presence-redis.repository';
|
||
import { OnlineDetectionService } from '../../domain/services/online-detection.service';
|
||
import { OnlineSnapshot } from '../../domain/entities/online-snapshot.entity';
|
||
import { IOnlineSnapshotRepository, ONLINE_SNAPSHOT_REPOSITORY } from '../../domain/repositories/online-snapshot.repository.interface';
|
||
import { Inject } from '@nestjs/common';
|
||
|
||
@Injectable()
|
||
export class AnalyticsScheduler {
|
||
private readonly logger = new Logger(AnalyticsScheduler.name);
|
||
|
||
constructor(
|
||
private readonly commandBus: CommandBus,
|
||
private readonly presenceRedisRepository: PresenceRedisRepository,
|
||
private readonly onlineDetectionService: OnlineDetectionService,
|
||
@Inject(ONLINE_SNAPSHOT_REPOSITORY)
|
||
private readonly snapshotRepository: IOnlineSnapshotRepository,
|
||
) {}
|
||
|
||
/**
|
||
* 每分钟记录在线人数快照
|
||
*/
|
||
@Cron(CronExpression.EVERY_MINUTE)
|
||
async recordOnlineSnapshot(): Promise<void> {
|
||
try {
|
||
const now = new Date();
|
||
const threshold = this.onlineDetectionService.getOnlineThreshold(now);
|
||
const count = await this.presenceRedisRepository.countOnlineUsers(threshold);
|
||
|
||
const snapshot = OnlineSnapshot.create({
|
||
ts: now,
|
||
onlineCount: count,
|
||
windowSeconds: this.onlineDetectionService.getWindowSeconds(),
|
||
});
|
||
|
||
await this.snapshotRepository.insert(snapshot);
|
||
this.logger.debug(`Online snapshot recorded: ${count} users`);
|
||
} catch (error) {
|
||
this.logger.error('Failed to record online snapshot', error);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 每小时清理过期在线数据
|
||
*/
|
||
@Cron(CronExpression.EVERY_HOUR)
|
||
async cleanupExpiredPresence(): Promise<void> {
|
||
try {
|
||
const threshold = Math.floor(Date.now() / 1000) - 86400; // 24小时前
|
||
await this.presenceRedisRepository.removeExpiredUsers(threshold);
|
||
this.logger.log('Expired presence data cleaned up');
|
||
} catch (error) {
|
||
this.logger.error('Failed to cleanup expired presence', error);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 每天凌晨 1:00 计算前一天 DAU (Asia/Shanghai)
|
||
*/
|
||
@Cron('0 0 1 * * *', { timeZone: 'Asia/Shanghai' })
|
||
async calculateYesterdayDau(): Promise<void> {
|
||
try {
|
||
const yesterday = subDays(new Date(), 1);
|
||
await this.commandBus.execute(new CalculateDauCommand(yesterday));
|
||
this.logger.log('Yesterday DAU calculated');
|
||
} catch (error) {
|
||
this.logger.error('Failed to calculate yesterday DAU', error);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 每小时滚动计算当天 DAU (用于实时看板)
|
||
*/
|
||
@Cron(CronExpression.EVERY_HOUR)
|
||
async calculateTodayDauRolling(): Promise<void> {
|
||
try {
|
||
await this.commandBus.execute(new CalculateDauCommand(new Date()));
|
||
this.logger.debug('Today DAU rolling calculation completed');
|
||
} catch (error) {
|
||
this.logger.error('Failed to calculate today DAU', error);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、基础设施层设计
|
||
|
||
### 3.1 Prisma Schema
|
||
|
||
```prisma
|
||
// prisma/schema.prisma
|
||
|
||
generator client {
|
||
provider = "prisma-client-js"
|
||
}
|
||
|
||
datasource db {
|
||
provider = "postgresql"
|
||
url = env("DATABASE_URL")
|
||
}
|
||
|
||
// 事件日志表 (append-only)
|
||
model EventLog {
|
||
id BigInt @id @default(autoincrement())
|
||
userId BigInt? @map("user_id")
|
||
installId String @map("install_id") @db.VarChar(64)
|
||
eventName String @map("event_name") @db.VarChar(64)
|
||
eventTime DateTime @map("event_time") @db.Timestamptz()
|
||
properties Json? @db.JsonB
|
||
createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz()
|
||
|
||
@@index([eventTime], name: "idx_event_log_event_time")
|
||
@@index([eventName], name: "idx_event_log_event_name")
|
||
@@index([eventName, eventTime], name: "idx_event_log_event_name_time")
|
||
@@map("analytics_event_log")
|
||
}
|
||
|
||
// 日活统计表
|
||
model DailyActiveStats {
|
||
day DateTime @id @map("day") @db.Date
|
||
dauCount Int @map("dau_count")
|
||
dauByProvince Json? @map("dau_by_province") @db.JsonB
|
||
dauByCity Json? @map("dau_by_city") @db.JsonB
|
||
calculatedAt DateTime @map("calculated_at") @db.Timestamptz()
|
||
version Int @default(1)
|
||
|
||
@@map("analytics_daily_active_users")
|
||
}
|
||
|
||
// 在线人数快照表
|
||
model OnlineSnapshot {
|
||
id BigInt @id @default(autoincrement())
|
||
ts DateTime @unique @db.Timestamptz()
|
||
onlineCount Int @map("online_count")
|
||
windowSeconds Int @default(180) @map("window_seconds")
|
||
|
||
@@index([ts(sort: Desc)], name: "idx_online_snapshots_ts")
|
||
@@map("analytics_online_snapshots")
|
||
}
|
||
```
|
||
|
||
### 3.2 Redis 仓储实现
|
||
|
||
```typescript
|
||
// src/infrastructure/redis/presence-redis.repository.ts
|
||
|
||
import { Injectable } from '@nestjs/common';
|
||
import { RedisService } from './redis.service';
|
||
|
||
@Injectable()
|
||
export class PresenceRedisRepository {
|
||
private readonly ONLINE_USERS_KEY = 'presence:online_users';
|
||
|
||
constructor(private readonly redisService: RedisService) {}
|
||
|
||
/**
|
||
* 更新用户在线状态
|
||
*/
|
||
async updateUserPresence(userId: string, timestamp: number): Promise<void> {
|
||
await this.redisService.zadd(this.ONLINE_USERS_KEY, timestamp, userId);
|
||
}
|
||
|
||
/**
|
||
* 统计在线用户数
|
||
*/
|
||
async countOnlineUsers(thresholdTimestamp: number): Promise<number> {
|
||
return this.redisService.zcount(
|
||
this.ONLINE_USERS_KEY,
|
||
thresholdTimestamp,
|
||
'+inf',
|
||
);
|
||
}
|
||
|
||
/**
|
||
* 获取在线用户列表
|
||
*/
|
||
async getOnlineUsers(thresholdTimestamp: number, limit?: number): Promise<string[]> {
|
||
const args: [string, number | string, number | string] = [
|
||
this.ONLINE_USERS_KEY,
|
||
thresholdTimestamp,
|
||
'+inf',
|
||
];
|
||
|
||
if (limit) {
|
||
return this.redisService.zrangebyscore(
|
||
this.ONLINE_USERS_KEY,
|
||
thresholdTimestamp,
|
||
'+inf',
|
||
'LIMIT',
|
||
0,
|
||
limit,
|
||
);
|
||
}
|
||
|
||
return this.redisService.zrangebyscore(
|
||
this.ONLINE_USERS_KEY,
|
||
thresholdTimestamp,
|
||
'+inf',
|
||
);
|
||
}
|
||
|
||
/**
|
||
* 移除过期用户
|
||
*/
|
||
async removeExpiredUsers(thresholdTimestamp: number): Promise<number> {
|
||
return this.redisService.zremrangebyscore(
|
||
this.ONLINE_USERS_KEY,
|
||
'-inf',
|
||
thresholdTimestamp,
|
||
);
|
||
}
|
||
|
||
/**
|
||
* 获取用户最后心跳时间
|
||
*/
|
||
async getUserLastHeartbeat(userId: string): Promise<number | null> {
|
||
const score = await this.redisService.zscore(this.ONLINE_USERS_KEY, userId);
|
||
return score ? Number(score) : null;
|
||
}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/infrastructure/redis/redis.service.ts
|
||
|
||
import { Injectable, OnModuleDestroy } from '@nestjs/common';
|
||
import { ConfigService } from '@nestjs/config';
|
||
import Redis from 'ioredis';
|
||
|
||
@Injectable()
|
||
export class RedisService implements OnModuleDestroy {
|
||
private readonly client: Redis;
|
||
|
||
constructor(private readonly configService: ConfigService) {
|
||
this.client = new Redis({
|
||
host: this.configService.get<string>('REDIS_HOST', 'localhost'),
|
||
port: this.configService.get<number>('REDIS_PORT', 6379),
|
||
password: this.configService.get<string>('REDIS_PASSWORD'),
|
||
db: this.configService.get<number>('REDIS_DB', 0),
|
||
});
|
||
}
|
||
|
||
async onModuleDestroy(): Promise<void> {
|
||
await this.client.quit();
|
||
}
|
||
|
||
// ZSET 操作
|
||
async zadd(key: string, score: number, member: string): Promise<number> {
|
||
return this.client.zadd(key, score, member);
|
||
}
|
||
|
||
async zcount(key: string, min: number | string, max: number | string): Promise<number> {
|
||
return this.client.zcount(key, min, max);
|
||
}
|
||
|
||
async zrangebyscore(
|
||
key: string,
|
||
min: number | string,
|
||
max: number | string,
|
||
...args: (string | number)[]
|
||
): Promise<string[]> {
|
||
return this.client.zrangebyscore(key, min, max, ...args);
|
||
}
|
||
|
||
async zremrangebyscore(key: string, min: number | string, max: number | string): Promise<number> {
|
||
return this.client.zremrangebyscore(key, min, max);
|
||
}
|
||
|
||
async zscore(key: string, member: string): Promise<string | null> {
|
||
return this.client.zscore(key, member);
|
||
}
|
||
|
||
// HyperLogLog 操作
|
||
async pfadd(key: string, ...elements: string[]): Promise<number> {
|
||
return this.client.pfadd(key, ...elements);
|
||
}
|
||
|
||
async pfcount(...keys: string[]): Promise<number> {
|
||
return this.client.pfcount(...keys);
|
||
}
|
||
|
||
// 通用操作
|
||
async expire(key: string, seconds: number): Promise<number> {
|
||
return this.client.expire(key, seconds);
|
||
}
|
||
|
||
async del(...keys: string[]): Promise<number> {
|
||
return this.client.del(...keys);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 仓储实现
|
||
|
||
```typescript
|
||
// src/infrastructure/persistence/repositories/event-log.repository.impl.ts
|
||
|
||
import { Injectable } from '@nestjs/common';
|
||
import { PrismaService } from '../prisma/prisma.service';
|
||
import {
|
||
IEventLogRepository,
|
||
DauQueryResult,
|
||
} from '../../../domain/repositories/event-log.repository.interface';
|
||
import { EventLog } from '../../../domain/entities/event-log.entity';
|
||
import { EventName } from '../../../domain/value-objects/event-name.vo';
|
||
import { EventLogMapper } from '../mappers/event-log.mapper';
|
||
|
||
@Injectable()
|
||
export class EventLogRepositoryImpl implements IEventLogRepository {
|
||
constructor(
|
||
private readonly prisma: PrismaService,
|
||
private readonly mapper: EventLogMapper,
|
||
) {}
|
||
|
||
async batchInsert(logs: EventLog[]): Promise<void> {
|
||
const data = logs.map((log) => this.mapper.toPersistence(log));
|
||
await this.prisma.eventLog.createMany({ data });
|
||
}
|
||
|
||
async insert(log: EventLog): Promise<EventLog> {
|
||
const data = this.mapper.toPersistence(log);
|
||
const created = await this.prisma.eventLog.create({ data });
|
||
return this.mapper.toDomain(created);
|
||
}
|
||
|
||
async queryDau(
|
||
eventName: EventName,
|
||
startTime: Date,
|
||
endTime: Date,
|
||
): Promise<DauQueryResult> {
|
||
// 使用原生 SQL 进行去重统计
|
||
const result = await this.prisma.$queryRaw<
|
||
{ total: bigint; province: string | null; city: string | null; count: bigint }[]
|
||
>`
|
||
WITH base AS (
|
||
SELECT
|
||
COALESCE(user_id::text, install_id) AS identifier,
|
||
properties->>'province' AS province,
|
||
properties->>'city' AS city
|
||
FROM analytics_event_log
|
||
WHERE event_name = ${eventName.value}
|
||
AND event_time >= ${startTime}
|
||
AND event_time < ${endTime}
|
||
),
|
||
unique_users AS (
|
||
SELECT DISTINCT identifier, province, city FROM base
|
||
)
|
||
SELECT
|
||
COUNT(DISTINCT identifier) AS total,
|
||
province,
|
||
city,
|
||
COUNT(*) AS count
|
||
FROM unique_users
|
||
GROUP BY GROUPING SETS ((), (province), (city))
|
||
`;
|
||
|
||
let total = 0;
|
||
const byProvince = new Map<string, number>();
|
||
const byCity = new Map<string, number>();
|
||
|
||
for (const row of result) {
|
||
if (row.province === null && row.city === null) {
|
||
total = Number(row.total);
|
||
} else if (row.province !== null && row.city === null) {
|
||
byProvince.set(row.province, Number(row.count));
|
||
} else if (row.city !== null && row.province === null) {
|
||
byCity.set(row.city, Number(row.count));
|
||
}
|
||
}
|
||
|
||
return { total, byProvince, byCity };
|
||
}
|
||
|
||
async findByTimeRange(
|
||
eventName: EventName,
|
||
startTime: Date,
|
||
endTime: Date,
|
||
limit?: number,
|
||
): Promise<EventLog[]> {
|
||
const records = await this.prisma.eventLog.findMany({
|
||
where: {
|
||
eventName: eventName.value,
|
||
eventTime: {
|
||
gte: startTime,
|
||
lt: endTime,
|
||
},
|
||
},
|
||
orderBy: { eventTime: 'desc' },
|
||
take: limit,
|
||
});
|
||
|
||
return records.map((r) => this.mapper.toDomain(r));
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.4 Kafka 事件发布
|
||
|
||
```typescript
|
||
// src/infrastructure/kafka/event-publisher.service.ts
|
||
|
||
import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
|
||
import { ConfigService } from '@nestjs/config';
|
||
import { Kafka, Producer, logLevel } from 'kafkajs';
|
||
|
||
@Injectable()
|
||
export class EventPublisherService implements OnModuleInit, OnModuleDestroy {
|
||
private kafka: Kafka;
|
||
private producer: Producer;
|
||
private readonly topic: string;
|
||
|
||
constructor(private readonly configService: ConfigService) {
|
||
this.kafka = new Kafka({
|
||
clientId: 'analytics-presence-service',
|
||
brokers: this.configService.get<string>('KAFKA_BROKERS', 'localhost:9092').split(','),
|
||
logLevel: logLevel.WARN,
|
||
});
|
||
this.producer = this.kafka.producer();
|
||
this.topic = this.configService.get<string>('KAFKA_TOPIC_ANALYTICS', 'analytics-events');
|
||
}
|
||
|
||
async onModuleInit(): Promise<void> {
|
||
await this.producer.connect();
|
||
}
|
||
|
||
async onModuleDestroy(): Promise<void> {
|
||
await this.producer.disconnect();
|
||
}
|
||
|
||
async publish(eventType: string, payload: unknown): Promise<void> {
|
||
await this.producer.send({
|
||
topic: this.topic,
|
||
messages: [
|
||
{
|
||
key: eventType,
|
||
value: JSON.stringify({
|
||
eventType,
|
||
payload,
|
||
occurredAt: new Date().toISOString(),
|
||
}),
|
||
},
|
||
],
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、表现层设计
|
||
|
||
### 4.1 DTO 定义
|
||
|
||
```typescript
|
||
// src/api/dto/request/batch-events.dto.ts
|
||
|
||
import { IsArray, IsString, IsOptional, IsNumber, ValidateNested, IsObject } from 'class-validator';
|
||
import { Type } from 'class-transformer';
|
||
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
|
||
|
||
export class EventItemDto {
|
||
@ApiProperty({ description: '事件名称', example: 'app_session_start' })
|
||
@IsString()
|
||
eventName: string;
|
||
|
||
@ApiPropertyOptional({ description: '用户ID (登录用户)', example: '12345' })
|
||
@IsOptional()
|
||
@IsString()
|
||
userId?: string;
|
||
|
||
@ApiProperty({ description: '安装ID', example: 'uuid-xxx-xxx' })
|
||
@IsString()
|
||
installId: string;
|
||
|
||
@ApiProperty({ description: '客户端时间戳 (秒)', example: 1732685100 })
|
||
@IsNumber()
|
||
clientTs: number;
|
||
|
||
@ApiPropertyOptional({ description: '事件属性' })
|
||
@IsOptional()
|
||
@IsObject()
|
||
properties?: Record<string, unknown>;
|
||
}
|
||
|
||
export class BatchEventsDto {
|
||
@ApiProperty({ type: [EventItemDto], description: '事件列表' })
|
||
@IsArray()
|
||
@ValidateNested({ each: true })
|
||
@Type(() => EventItemDto)
|
||
events: EventItemDto[];
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/api/dto/request/heartbeat.dto.ts
|
||
|
||
import { IsString, IsNumber } from 'class-validator';
|
||
import { ApiProperty } from '@nestjs/swagger';
|
||
|
||
export class HeartbeatDto {
|
||
@ApiProperty({ description: '安装ID', example: 'uuid-xxx-xxx' })
|
||
@IsString()
|
||
installId: string;
|
||
|
||
@ApiProperty({ description: 'App版本', example: '1.0.0' })
|
||
@IsString()
|
||
appVersion: string;
|
||
|
||
@ApiProperty({ description: '客户端时间戳 (秒)', example: 1732685100 })
|
||
@IsNumber()
|
||
clientTs: number;
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/api/dto/request/query-dau.dto.ts
|
||
|
||
import { IsDateString, IsOptional } from 'class-validator';
|
||
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
|
||
|
||
export class QueryDauDto {
|
||
@ApiProperty({ description: '开始日期', example: '2025-01-01' })
|
||
@IsDateString()
|
||
startDate: string;
|
||
|
||
@ApiProperty({ description: '结束日期', example: '2025-01-15' })
|
||
@IsDateString()
|
||
endDate: string;
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/api/dto/response/online-count.dto.ts
|
||
|
||
import { ApiProperty } from '@nestjs/swagger';
|
||
|
||
export class OnlineCountResponseDto {
|
||
@ApiProperty({ description: '在线人数', example: 1234 })
|
||
count: number;
|
||
|
||
@ApiProperty({ description: '时间窗口(秒)', example: 180 })
|
||
windowSeconds: number;
|
||
|
||
@ApiProperty({ description: '查询时间', example: '2025-01-15T10:30:00.000Z' })
|
||
queriedAt: string;
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/api/dto/response/dau-stats.dto.ts
|
||
|
||
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
|
||
|
||
export class DauDayItemDto {
|
||
@ApiProperty({ description: '日期', example: '2025-01-15' })
|
||
day: string;
|
||
|
||
@ApiProperty({ description: 'DAU', example: 5678 })
|
||
dauCount: number;
|
||
|
||
@ApiPropertyOptional({ description: '按省份统计' })
|
||
byProvince?: Record<string, number>;
|
||
|
||
@ApiPropertyOptional({ description: '按城市统计' })
|
||
byCity?: Record<string, number>;
|
||
}
|
||
|
||
export class DauStatsResponseDto {
|
||
@ApiProperty({ type: [DauDayItemDto], description: 'DAU数据' })
|
||
data: DauDayItemDto[];
|
||
|
||
@ApiProperty({ description: '记录数', example: 15 })
|
||
total: number;
|
||
}
|
||
```
|
||
|
||
### 4.2 控制器
|
||
|
||
```typescript
|
||
// src/api/controllers/analytics.controller.ts
|
||
|
||
import { Controller, Post, Get, Body, Query, UseGuards } from '@nestjs/common';
|
||
import { CommandBus, QueryBus } from '@nestjs/cqrs';
|
||
import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
|
||
import { BatchEventsDto } from '../dto/request/batch-events.dto';
|
||
import { QueryDauDto } from '../dto/request/query-dau.dto';
|
||
import { DauStatsResponseDto } from '../dto/response/dau-stats.dto';
|
||
import { RecordEventsCommand } from '../../application/commands/record-events/record-events.command';
|
||
import { GetDauStatsQuery } from '../../application/queries/get-dau-stats/get-dau-stats.query';
|
||
import { Public } from '../../shared/decorators/public.decorator';
|
||
import { JwtAuthGuard } from '../../shared/guards/jwt-auth.guard';
|
||
|
||
@ApiTags('Analytics')
|
||
@Controller('analytics')
|
||
export class AnalyticsController {
|
||
constructor(
|
||
private readonly commandBus: CommandBus,
|
||
private readonly queryBus: QueryBus,
|
||
) {}
|
||
|
||
@Post('events')
|
||
@Public()
|
||
@ApiOperation({ summary: '批量上报事件' })
|
||
async batchEvents(@Body() dto: BatchEventsDto) {
|
||
return this.commandBus.execute(new RecordEventsCommand(dto.events));
|
||
}
|
||
|
||
@Get('dau')
|
||
@UseGuards(JwtAuthGuard)
|
||
@ApiBearerAuth()
|
||
@ApiOperation({ summary: '查询DAU统计' })
|
||
async getDauStats(@Query() dto: QueryDauDto): Promise<DauStatsResponseDto> {
|
||
return this.queryBus.execute(
|
||
new GetDauStatsQuery(new Date(dto.startDate), new Date(dto.endDate)),
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// src/api/controllers/presence.controller.ts
|
||
|
||
import { Controller, Post, Get, Body, UseGuards, Req } from '@nestjs/common';
|
||
import { CommandBus, QueryBus } from '@nestjs/cqrs';
|
||
import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
|
||
import { HeartbeatDto } from '../dto/request/heartbeat.dto';
|
||
import { OnlineCountResponseDto } from '../dto/response/online-count.dto';
|
||
import { RecordHeartbeatCommand } from '../../application/commands/record-heartbeat/record-heartbeat.command';
|
||
import { GetOnlineCountQuery } from '../../application/queries/get-online-count/get-online-count.query';
|
||
import { JwtAuthGuard } from '../../shared/guards/jwt-auth.guard';
|
||
import { CurrentUser } from '../../shared/decorators/current-user.decorator';
|
||
|
||
@ApiTags('Presence')
|
||
@Controller('presence')
|
||
export class PresenceController {
|
||
constructor(
|
||
private readonly commandBus: CommandBus,
|
||
private readonly queryBus: QueryBus,
|
||
) {}
|
||
|
||
@Post('heartbeat')
|
||
@UseGuards(JwtAuthGuard)
|
||
@ApiBearerAuth()
|
||
@ApiOperation({ summary: '心跳上报' })
|
||
async heartbeat(
|
||
@CurrentUser('userId') userId: bigint,
|
||
@Body() dto: HeartbeatDto,
|
||
) {
|
||
return this.commandBus.execute(
|
||
new RecordHeartbeatCommand(
|
||
userId,
|
||
dto.installId,
|
||
dto.appVersion,
|
||
dto.clientTs,
|
||
),
|
||
);
|
||
}
|
||
|
||
@Get('online-count')
|
||
@UseGuards(JwtAuthGuard)
|
||
@ApiBearerAuth()
|
||
@ApiOperation({ summary: '获取当前在线人数' })
|
||
async getOnlineCount(): Promise<OnlineCountResponseDto> {
|
||
const result = await this.queryBus.execute(new GetOnlineCountQuery());
|
||
return {
|
||
count: result.count,
|
||
windowSeconds: result.windowSeconds,
|
||
queriedAt: result.queriedAt.toISOString(),
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、共享层工具
|
||
|
||
```typescript
|
||
// src/shared/utils/timezone.util.ts
|
||
|
||
import { format, startOfDay, endOfDay } from 'date-fns';
|
||
import { toZonedTime, fromZonedTime } from 'date-fns-tz';
|
||
|
||
const DEFAULT_TIMEZONE = 'Asia/Shanghai';
|
||
|
||
/**
|
||
* 获取指定时区的一天开始时间
|
||
*/
|
||
export function startOfDayInTimezone(date: Date, timezone: string = DEFAULT_TIMEZONE): Date {
|
||
const zonedDate = toZonedTime(date, timezone);
|
||
const start = startOfDay(zonedDate);
|
||
return fromZonedTime(start, timezone);
|
||
}
|
||
|
||
/**
|
||
* 获取指定时区的一天结束时间
|
||
*/
|
||
export function endOfDayInTimezone(date: Date, timezone: string = DEFAULT_TIMEZONE): Date {
|
||
const zonedDate = toZonedTime(date, timezone);
|
||
const end = endOfDay(zonedDate);
|
||
return fromZonedTime(end, timezone);
|
||
}
|
||
|
||
/**
|
||
* 格式化为日期Key (YYYY-MM-DD)
|
||
*/
|
||
export function formatToDateKey(date: Date, timezone: string = DEFAULT_TIMEZONE): string {
|
||
const zonedDate = toZonedTime(date, timezone);
|
||
return format(zonedDate, 'yyyy-MM-dd');
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、环境配置
|
||
|
||
```bash
|
||
# .env.example
|
||
|
||
# 应用配置
|
||
NODE_ENV=development
|
||
PORT=3001
|
||
|
||
# 数据库
|
||
DATABASE_URL=postgresql://user:password@localhost:5432/rwa_analytics?schema=public
|
||
|
||
# Redis
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD=
|
||
REDIS_DB=0
|
||
|
||
# JWT (与 Identity Service 共用)
|
||
JWT_SECRET=your-jwt-secret
|
||
JWT_EXPIRES_IN=7d
|
||
|
||
# Kafka
|
||
KAFKA_BROKERS=localhost:9092
|
||
KAFKA_TOPIC_ANALYTICS=analytics-events
|
||
|
||
# 时区
|
||
TZ=Asia/Shanghai
|
||
```
|
||
|
||
---
|
||
|
||
## 七、领域不变式
|
||
|
||
1. **InstallId 不可为空** - 每个事件必须携带 InstallId
|
||
2. **DAU 去重逻辑** - 优先使用 userId，其次使用 installId
|
||
3. **时区统一** - 所有 DAU 计算使用 Asia/Shanghai 时区
|
||
4. **心跳仅限登录用户** - 未登录用户不参与在线统计
|
||
5. **事件日志 append-only** - 不允许修改或删除事件记录
|
||
6. **在线判定窗口** - 默认 180 秒（3分钟）
|
||
7. **心跳间隔** - 客户端前台状态下每 60 秒上报一次
|
||
|
||
---
|
||
|
||
## 八、与其他上下文的集成
|
||
|
||
### 8.1 消费 Identity Context 事件
|
||
|
||
```typescript
|
||
// src/infrastructure/kafka/event-consumer.service.ts
|
||
|
||
import { Injectable, OnModuleInit } from '@nestjs/common';
|
||
import { CommandBus } from '@nestjs/cqrs';
|
||
import { Kafka, Consumer, EachMessagePayload } from 'kafkajs';
|
||
import { ConfigService } from '@nestjs/config';
|
||
|
||
@Injectable()
|
||
export class EventConsumerService implements OnModuleInit {
|
||
private consumer: Consumer;
|
||
|
||
constructor(
|
||
private readonly configService: ConfigService,
|
||
private readonly commandBus: CommandBus,
|
||
) {
|
||
const kafka = new Kafka({
|
||
clientId: 'analytics-presence-consumer',
|
||
brokers: this.configService.get<string>('KAFKA_BROKERS', 'localhost:9092').split(','),
|
||
});
|
||
this.consumer = kafka.consumer({ groupId: 'analytics-presence-group' });
|
||
}
|
||
|
||
async onModuleInit(): Promise<void> {
|
||
await this.consumer.connect();
|
||
|
||
// 订阅 Identity Context 的用户创建事件
|
||
await this.consumer.subscribe({ topic: 'identity-events', fromBeginning: false });
|
||
|
||
await this.consumer.run({
|
||
eachMessage: async (payload: EachMessagePayload) => {
|
||
await this.handleMessage(payload);
|
||
},
|
||
});
|
||
}
|
||
|
||
private async handleMessage(payload: EachMessagePayload): Promise<void> {
|
||
const { message } = payload;
|
||
const key = message.key?.toString();
|
||
const value = message.value?.toString();
|
||
|
||
if (!value) return;
|
||
|
||
const event = JSON.parse(value);
|
||
|
||
// 处理用户创建事件 - 可用于初始化用户统计
|
||
if (key === 'user.account.created') {
|
||
// 可选：记录注册事件
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 为 Reporting Context 提供数据
|
||
|
||
```typescript
|
||
// src/api/controllers/internal.controller.ts
|
||
|
||
import { Controller, Get, Query, UseGuards } from '@nestjs/common';
|
||
import { QueryBus } from '@nestjs/cqrs';
|
||
import { ApiTags, ApiOperation } from '@nestjs/swagger';
|
||
import { InternalGuard } from '../../shared/guards/internal.guard';
|
||
import { GetDauStatsQuery } from '../../application/queries/get-dau-stats/get-dau-stats.query';
|
||
|
||
@ApiTags('Internal')
|
||
@Controller('internal/analytics')
|
||
@UseGuards(InternalGuard)
|
||
export class InternalController {
|
||
constructor(private readonly queryBus: QueryBus) {}
|
||
|
||
@Get('dau')
|
||
@ApiOperation({ summary: '内部接口: 获取DAU数据' })
|
||
async getDauForReporting(
|
||
@Query('startDate') startDate: string,
|
||
@Query('endDate') endDate: string,
|
||
) {
|
||
return this.queryBus.execute(
|
||
new GetDauStatsQuery(new Date(startDate), new Date(endDate)),
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 九、快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 文件
|
||
```
|
||
|
||
### 3. 初始化数据库
|
||
|
||
```bash
|
||
npm run prisma:generate
|
||
npm run prisma:migrate
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
```bash
|
||
# 开发模式
|
||
npm run start:dev
|
||
|
||
# 生产模式
|
||
npm run build
|
||
npm run start:prod
|
||
```
|
||
|
||
### 5. Docker 部署
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## API 文档
|
||
|
||
启动服务后访问: http://localhost:3001/api/docs
|
||
|
||
## 主要 API
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| POST | /analytics/events | 批量上报事件 | 可选 |
|
||
| GET | /analytics/dau | 查询DAU统计 | 必需 |
|
||
| POST | /presence/heartbeat | 心跳上报 | 必需 |
|
||
| GET | /presence/online-count | 获取在线人数 | 必需 |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
Proprietary
|