feat(p3): core teaching service with Outbox + Kafka event bus

P3 阶段交付物:
- services/core-edu: 教学核心服务(DDD 限界上下文:exams/grades/homework/classes)
  - exams: 考试 CRUD + 事务内写 exam + outbox
  - grades: 成绩 CRUD
  - homework: 作业 CRUD
  - classes.module: 复用 P1 classes 模块(聚合到 core-edu 服务)
- Outbox 模式实现:
  - outbox.schema.ts: core_edu_outbox 表(id/aggregate_id/event_type/payload/status/retry_count)
  - outbox.repository.ts: 支持事务参数 tx,确保业务+事件原子性
  - outbox.publisher.ts: Kafka idempotent producer + transactionalId,TOPIC_MAP 路由 9 种事件,MAX_RETRY=5
- config/kafka.ts: idempotent producer + transactionalId 配置
- main.ts: 启动顺序 initTracer → connectKafka → outboxPublisher.start → app.listen
- packages/shared-proto/proto/core_edu.proto: ExamService/HomeworkService/GradeService 契约
- packages/shared-proto/proto/events.proto: ClassEvent/ExamEvent/HomeworkEvent/GradeEvent 领域事件契约
This commit is contained in:
SpecialX
2026-07-08 01:38:07 +08:00
parent 524204d30a
commit 23246ade6d
37 changed files with 1592 additions and 0 deletions

View File

@@ -0,0 +1,16 @@
import pino from 'pino';
import { env } from '../../config/env.js';
export const logger = pino({
name: 'core-edu',
level: env.LOG_LEVEL,
base: { service: 'core-edu' },
...(env.NODE_ENV === 'development'
? {
transport: {
target: 'pino-pretty',
options: { colorize: true, translateTime: 'SYS:standard' },
},
}
: {}),
});

View File

@@ -0,0 +1,38 @@
import {
Registry,
Counter,
Histogram,
Gauge,
collectDefaultMetrics,
} from 'prom-client';
export const registry = new Registry();
collectDefaultMetrics({ register: registry });
export const httpRequestCounter = new Counter({
name: 'core_edu_requests_total',
help: 'Total HTTP requests',
labelNames: ['method', 'route', 'status'] as const,
});
registry.registerMetric(httpRequestCounter);
export const httpRequestDuration = new Histogram({
name: 'core_edu_request_duration_seconds',
help: 'HTTP request duration in seconds',
labelNames: ['method', 'route', 'status'] as const,
buckets: [0.005, 0.01, 0.05, 0.1, 0.5, 1, 5],
});
registry.registerMetric(httpRequestDuration);
export const outboxPendingGauge = new Gauge({
name: 'core_edu_outbox_pending',
help: 'Number of pending outbox messages',
});
registry.registerMetric(outboxPendingGauge);
export const outboxPublishedCounter = new Counter({
name: 'core_edu_outbox_published_total',
help: 'Total outbox messages published to Kafka',
labelNames: ['eventType', 'topic'] as const,
});
registry.registerMetric(outboxPublishedCounter);

View File

@@ -0,0 +1,29 @@
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { env } from '../../config/env.js';
import { logger } from './logger.js';
let sdk: NodeSDK | undefined;
export function initTracer(): void {
if (!env.OTEL_EXPORTER_OTLP_ENDPOINT) {
logger.warn('OTEL_EXPORTER_OTLP_ENDPOINT not set, tracing disabled');
return;
}
sdk = new NodeSDK({
serviceName: 'core-edu',
traceExporter: new OTLPTraceExporter({
url: `${env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`,
}),
});
sdk.start();
logger.info('OpenTelemetry tracer initialized');
}
export async function shutdownTracer(): Promise<void> {
if (sdk) {
await sdk.shutdown();
sdk = undefined;
logger.info('OpenTelemetry tracer shutdown');
}
}