feat(p4): content analysis service with Neo4j knowledge graph and ClickHouse analytics

P4 阶段交付物： - services/content: 内容资源服务（NestJS） - textbooks: 教材 CRUD + 知识图谱绑定 - config/neo4j.ts: Neo4j driver 单例 - textbooks.service.ts: MySQL CRUD + Neo4j 知识图谱（createKnowledgeGraph/getPrerequisites） - package.json: 补充 @opentelemetry/sdk-node + exporter-trace-otlp-http - services/data-ana: 数据分析服务（Python FastAPI） - main.py: FastAPI + /healthz + class_performance + student_weakness 骨架 - clickhouse_client.py: ClickHouse 客户端封装 - config.py: 环境变量配置 - packages/shared-proto/proto/content.proto: TextbookService + KnowledgeGraphService 契约 - packages/shared-proto/proto/analytics.proto: AnalyticsService 契约（class_performance/student_weakness）
2026-07-08 01:38:35 +08:00
28 changed files with 936 additions and 0 deletions
--- a/packages/shared-proto/proto/analytics.proto
+++ b/packages/shared-proto/proto/analytics.proto
@@ -0,0 +1,61 @@
+syntax = "proto3";
+
+package next_edu_cloud.analytics.v1;
+
+service AnalyticsService {
+  rpc GetClassPerformance(GetClassPerformanceRequest) returns (ClassPerformance);
+  rpc GetStudentWeakness(GetStudentWeaknessRequest) returns (StudentWeakness);
+  rpc GetLearningTrend(GetLearningTrendRequest) returns (LearningTrend);
+}
+
+message GetClassPerformanceRequest {
+  string class_id = 1;
+  string subject_id = 2;
+  int64 start_date = 3;
+  int64 end_date = 4;
+}
+
+message ClassPerformance {
+  string class_id = 1;
+  double average_score = 2;
+  double pass_rate = 3;
+  repeated StudentScore scores = 4;
+}
+
+message StudentScore {
+  string student_id = 1;
+  double score = 2;
+  string grade = 3;
+}
+
+message GetStudentWeaknessRequest {
+  string student_id = 1;
+  string subject_id = 2;
+}
+
+message StudentWeakness {
+  string student_id = 1;
+  repeated WeakPoint weak_points = 2;
+}
+
+message WeakPoint {
+  string knowledge_point_id = 1;
+  string title = 2;
+  double mastery = 3;
+}
+
+message GetLearningTrendRequest {
+  string student_id = 1;
+  int64 start_date = 2;
+  int64 end_date = 3;
+}
+
+message LearningTrend {
+  string student_id = 1;
+  repeated TrendPoint points = 2;
+}
+
+message TrendPoint {
+  int64 date = 1;
+  double score = 2;
+}
--- a/packages/shared-proto/proto/content.proto
+++ b/packages/shared-proto/proto/content.proto
@@ -0,0 +1,47 @@
+syntax = "proto3";
+
+package next_edu_cloud.content.v1;
+
+service TextbookService {
+  rpc CreateTextbook(CreateTextbookRequest) returns (Textbook);
+  rpc GetTextbook(GetTextbookRequest) returns (Textbook);
+  rpc ListTextbooks(ListTextbooksRequest) returns (ListTextbooksResponse);
+}
+
+service KnowledgeGraphService {
+  rpc GetPrerequisites(GetPrerequisitesRequest) returns (KnowledgePointsResponse);
+  rpc GetLearningPath(GetLearningPathRequest) returns (LearningPath);
+}
+
+message Textbook {
+  string id = 1;
+  string title = 2;
+  string subject_id = 3;
+  string grade_id = 4;
+  string version = 5;
+}
+
+message CreateTextbookRequest {
+  string title = 1;
+  string subject_id = 2;
+  string grade_id = 3;
+  string version = 4;
+}
+
+message GetTextbookRequest { string id = 1; }
+message ListTextbooksRequest { string subject_id = 1; string grade_id = 2; }
+message ListTextbooksResponse { repeated Textbook textbooks = 1; }
+
+message KnowledgePoint {
+  string id = 1;
+  string title = 2;
+}
+
+message GetPrerequisitesRequest { string knowledge_point_id = 1; }
+message KnowledgePointsResponse { repeated KnowledgePoint points = 1; }
+
+message GetLearningPathRequest { string student_id = 1; string subject_id = 2; }
+message LearningPath {
+  repeated KnowledgePoint points = 1;
+  repeated string recommended_order = 2;
+}
--- a/services/content/Dockerfile
+++ b/services/content/Dockerfile
@@ -0,0 +1,19 @@
+# Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+RUN npm install -g pnpm
+COPY package.json pnpm-lock.yaml* ./
+RUN pnpm install --frozen-lockfile
+COPY tsconfig.json nest-cli.json ./
+COPY src ./src
+RUN pnpm build
+
+# Runtime stage
+FROM node:20-alpine
+WORKDIR /app
+RUN npm install -g pnpm
+COPY package.json pnpm-lock.yaml* ./
+RUN pnpm install --prod --frozen-lockfile
+COPY --from=builder /app/dist ./dist
+EXPOSE 3005
+CMD ["node", "dist/main.js"]
--- a/services/content/README.md
+++ b/services/content/README.md
@@ -0,0 +1,65 @@
+# content 内容资源服务
+
+> 版本：0.1（P4 骨架）
+> 端口：3005
+
+## 职责
+
+内容资源限界上下文，管理 Textbook、Chapter、KnowledgePoint 聚合。
+支持多存储：MySQL（教材/章节/知识点写模型）+ Neo4j（知识图谱前置依赖）+ Elasticsearch（题库全文检索，P4 后续补充）。
+
+## 技术栈
+
+- NestJS 10.x + TypeScript 5.6（ESM）
+- Drizzle ORM（MySQL）
+- neo4j-driver（知识图谱）
+- Zod（运行时校验）
+- pino（日志）+ prom-client（指标）+ OpenTelemetry（追踪）
+
+## 开发
+
+```bash
+pnpm install
+pnpm dev        # 端口 3005
+pnpm build
+pnpm typecheck
+pnpm lint
+pnpm test
+```
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `PORT` | 服务端口（默认 3005） |
+| `DATABASE_URL` | MySQL 连接串 |
+| `NEO4J_URL` | Neo4j Bolt 连接 URL |
+| `NEO4J_PASSWORD` | Neo4j 密码 |
+| `ES_URL` | Elasticsearch 地址 |
+| `JWT_SECRET` | JWT 密钥 |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry OTLP 端点（可选） |
+
+## 模块结构
+
+```
+src/
+├─ config/          # env、database(MySQL)、neo4j
+├─ shared/
+│  ├─ errors/       # ApplicationError + GlobalErrorFilter（CONTENT_* 前缀）
+│  └─ observability/# logger、metrics、tracer
+├─ textbooks/       # 教材/章节/知识点 + 知识图谱
+├─ app.module.ts
+└─ main.ts
+```
+
+## 关键端点
+
+- `POST /textbooks` 创建教材
+- `GET /textbooks` 教材列表
+- `GET /textbooks/:id` 教材详情
+- `TextbooksService.createKnowledgeGraph` 在 Neo4j 构建知识点前置依赖
+- `TextbooksService.getPrerequisites` 查询知识点前置链路
+
+## 对外契约
+
+gRPC 服务 `TextbookService`、`KnowledgeGraphService` 定义见 `packages/shared-proto/proto/content.proto`。
--- a/services/content/nest-cli.json
+++ b/services/content/nest-cli.json
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}
--- a/services/content/package.json
+++ b/services/content/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@edu/content-service",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "nest start --watch",
+    "build": "nest build",
+    "start": "node dist/main.js",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@nestjs/common": "^10.4.0",
+    "@nestjs/core": "^10.4.0",
+    "@nestjs/platform-express": "^10.4.0",
+    "drizzle-orm": "^0.31.0",
+    "mysql2": "^3.11.0",
+    "neo4j-driver": "^5.23.0",
+    "pino": "^9.4.0",
+    "prom-client": "^15.1.0",
+    "@opentelemetry/api": "^1.9.0",
+    "zod": "^3.23.0",
+    "uuid": "^10.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.0",
+    "@opentelemetry/sdk-node": "^0.55.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.55.0"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.4.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}
--- a/services/content/src/app.module.ts
+++ b/services/content/src/app.module.ts
@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+import { TextbooksModule } from './textbooks/textbooks.module.js';
+
+@Module({
+  imports: [TextbooksModule],
+})
+export class AppModule {}
--- a/services/content/src/config/database.ts
+++ b/services/content/src/config/database.ts
@@ -0,0 +1,24 @@
+import { drizzle } from 'drizzle-orm/mysql2';
+import mysql from 'mysql2/promise';
+import { env } from './env.js';
+
+let pool: mysql.Pool | null = null;
+
+export function getDb() {
+  if (!pool) {
+    pool = mysql.createPool({
+      uri: env.DATABASE_URL,
+      waitForConnections: true,
+      connectionLimit: 10,
+      queueLimit: 0,
+    });
+  }
+  return drizzle(pool);
+}
+
+export async function closeDb(): Promise<void> {
+  if (pool) {
+    await pool.end();
+    pool = null;
+  }
+}
--- a/services/content/src/config/env.ts
+++ b/services/content/src/config/env.ts
@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+const envSchema = z.object({
+  PORT: z.string().default('3005'),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url().optional(),
+  NEO4J_URL: z.string().url(),
+  NEO4J_PASSWORD: z.string(),
+  ES_URL: z.string().url(),
+  JWT_SECRET: z.string(),
+  JWT_ISSUER: z.string().default('next-edu-cloud'),
+  OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url().optional(),
+  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+});
+
+export type Env = z.infer<typeof envSchema>;
+
+export function loadEnv(): Env {
+  const result = envSchema.safeParse(process.env);
+  if (!result.success) {
+    console.error('❌ Invalid environment variables:', result.error.flatten().fieldErrors);
+    throw new Error('Invalid environment configuration');
+  }
+  return result.data;
+}
+
+export const env = loadEnv();
--- a/services/content/src/config/neo4j.ts
+++ b/services/content/src/config/neo4j.ts
@@ -0,0 +1,11 @@
+import neo4j from 'neo4j-driver';
+import { env } from './env.js';
+
+export const neo4jDriver = neo4j.driver(
+  env.NEO4J_URL,
+  neo4j.auth.basic('neo4j', env.NEO4J_PASSWORD)
+);
+
+export async function closeNeo4j(): Promise<void> {
+  await neo4jDriver.close();
+}
--- a/services/content/src/main.ts
+++ b/services/content/src/main.ts
@@ -0,0 +1,31 @@
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module.js';
+import { GlobalErrorFilter } from './shared/errors/global-error.filter.js';
+import { initTracer, shutdownTracer } from './shared/observability/tracer.js';
+import { env } from './config/env.js';
+import { logger } from './shared/observability/logger.js';
+
+async function bootstrap(): Promise<void> {
+  initTracer();
+
+  const app = await NestFactory.create(AppModule, {
+    logger: ['log', 'error', 'warn'],
+  });
+
+  app.useGlobalFilters(new GlobalErrorFilter());
+  app.enableShutdownHooks();
+
+  await app.listen(env.PORT);
+  logger.info({ port: env.PORT }, 'Content service started');
+
+  process.on('SIGTERM', async () => {
+    await app.close();
+    await shutdownTracer();
+  });
+}
+
+bootstrap().catch((err: unknown) => {
+  logger.error({ err }, 'Failed to start content service');
+  process.exit(1);
+});
--- a/services/content/src/shared/errors/application-error.ts
+++ b/services/content/src/shared/errors/application-error.ts
@@ -0,0 +1,96 @@
+export type ErrorType =
+  | 'validation'
+  | 'not_found'
+  | 'permission_denied'
+  | 'conflict'
+  | 'business'
+  | 'database'
+  | 'internal';
+
+export interface ErrorDetails {
+  [key: string]: unknown;
+}
+
+export abstract class ApplicationError extends Error {
+  abstract readonly type: ErrorType;
+  abstract readonly statusCode: number;
+  readonly code: string;
+  readonly details?: ErrorDetails;
+  // FIX #1: traceId 改为可写，以便 GlobalErrorFilter 注入请求级 traceId
+  traceId?: string;
+
+  constructor(message: string, code: string, details?: ErrorDetails) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      success: false,
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.details,
+        traceId: this.traceId,
+      },
+    };
+  }
+}
+
+export class ValidationError extends ApplicationError {
+  readonly type = 'validation' as const;
+  readonly statusCode = 400;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'CONTENT_VALIDATION_ERROR', details);
+  }
+}
+
+export class NotFoundError extends ApplicationError {
+  readonly type = 'not_found' as const;
+  readonly statusCode = 404;
+  constructor(resource: string, id: string) {
+    super(`${resource} not found: ${id}`, 'CONTENT_NOT_FOUND', { resource, id });
+  }
+}
+
+export class PermissionDeniedError extends ApplicationError {
+  readonly type = 'permission_denied' as const;
+  readonly statusCode = 403;
+  constructor(permission: string) {
+    super(`Permission denied: ${permission}`, 'CONTENT_PERMISSION_DENIED', { permission });
+  }
+}
+
+export class ConflictError extends ApplicationError {
+  readonly type = 'conflict' as const;
+  readonly statusCode = 409;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'CONTENT_CONFLICT', details);
+  }
+}
+
+export class BusinessError extends ApplicationError {
+  readonly type = 'business' as const;
+  readonly statusCode = 422;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'CONTENT_BUSINESS_ERROR', details);
+  }
+}
+
+export class DatabaseError extends ApplicationError {
+  readonly type = 'database' as const;
+  readonly statusCode = 500;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'CONTENT_DATABASE_ERROR', details);
+  }
+}
+
+export class InternalError extends ApplicationError {
+  readonly type = 'internal' as const;
+  readonly statusCode = 500;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'CONTENT_INTERNAL_ERROR', details);
+  }
+}
--- a/services/content/src/shared/errors/global-error.filter.ts
+++ b/services/content/src/shared/errors/global-error.filter.ts
@@ -0,0 +1,77 @@
+import { Catch, ExceptionFilter, ArgumentsHost, HttpException, Logger } from '@nestjs/common';
+import { Request, Response } from 'express';
+import { ZodError } from 'zod';
+import { ApplicationError } from './application-error.js';
+
+@Catch()
+export class GlobalErrorFilter implements ExceptionFilter {
+  private readonly logger = new Logger(GlobalErrorFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const traceId = (request.headers['x-request-id'] as string | undefined) ?? 'unknown';
+
+    let statusCode = 500;
+    let body: Record<string, unknown>;
+
+    if (exception instanceof ApplicationError) {
+      exception.traceId = traceId;
+      statusCode = exception.statusCode;
+      body = exception.toJSON();
+    } else if (exception instanceof ZodError) {
+      // FIX #3: 捕获 Zod 解析错误，转换为结构化 ValidationError 响应
+      statusCode = 400;
+      body = {
+        success: false,
+        error: {
+          code: 'CONTENT_VALIDATION_ERROR',
+          message: 'Validation failed',
+          details: exception.flatten(),
+          traceId,
+        },
+      };
+    } else if (exception instanceof HttpException) {
+      statusCode = exception.getStatus();
+      const res = exception.getResponse();
+      const message = this.extractHttpMessage(res, exception);
+      body = {
+        success: false,
+        error: {
+          code: 'HTTP_ERROR',
+          message,
+          traceId,
+        },
+      };
+    } else {
+      this.logger.error(
+        `Unhandled exception: ${exception}`,
+        exception instanceof Error ? exception.stack : undefined,
+      );
+      body = {
+        success: false,
+        error: {
+          code: 'INTERNAL_ERROR',
+          message: 'An unexpected error occurred',
+          traceId,
+        },
+      };
+    }
+
+    response.status(statusCode).json(body);
+  }
+
+  private extractHttpMessage(res: string | object, exception: HttpException): string {
+    if (typeof res === 'string') {
+      return res;
+    }
+    if (res && typeof res === 'object' && 'message' in res) {
+      // 从 HttpException 响应体收窄类型（NestJS 约定包含 message 字段）
+      const msg = (res as { message: unknown }).message;
+      return typeof msg === 'string' ? msg : exception.message;
+    }
+    return exception.message;
+  }
+}
--- a/services/content/src/shared/observability/logger.ts
+++ b/services/content/src/shared/observability/logger.ts
@@ -0,0 +1,20 @@
+import pino from 'pino';
+import { env } from '../../config/env.js';
+
+export const logger = pino({
+  level: env.LOG_LEVEL,
+  // 修复：pino 默认字段选项为 `base`，而非 `defaultFields`
+  base: {
+    service: 'content',
+    version: '0.1.0',
+  },
+  transport:
+    env.NODE_ENV === 'development'
+      ? {
+          target: 'pino-pretty',
+          options: { colorize: true },
+        }
+      : undefined,
+});
+
+export type Logger = typeof logger;
--- a/services/content/src/shared/observability/metrics.ts
+++ b/services/content/src/shared/observability/metrics.ts
@@ -0,0 +1,24 @@
+import promClient from 'prom-client';
+
+const registry = new promClient.Registry();
+// 修复：在本地 registry 上设置默认标签（原代码误用全局 register）
+registry.setDefaultLabels({ service: 'content' });
+
+registry.registerMetric(
+  new promClient.Counter({
+    name: 'content_requests_total',
+    help: 'Total number of content requests',
+    labelNames: ['method', 'endpoint', 'status'],
+  }),
+);
+
+registry.registerMetric(
+  new promClient.Histogram({
+    name: 'content_request_duration_seconds',
+    help: 'Content request duration in seconds',
+    labelNames: ['method', 'endpoint'],
+    buckets: [0.01, 0.05, 0.1, 0.3, 0.5, 1, 3, 5],
+  }),
+);
+
+export { registry as metricsRegistry };
--- a/services/content/src/shared/observability/tracer.ts
+++ b/services/content/src/shared/observability/tracer.ts
@@ -0,0 +1,25 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { env } from '../../config/env.js';
+
+let sdk: NodeSDK | null = null;
+
+export function initTracer(): void {
+  if (!env.OTEL_EXPORTER_OTLP_ENDPOINT) return;
+
+  sdk = new NodeSDK({
+    serviceName: 'content',
+    traceExporter: new OTLPTraceExporter({
+      url: `${env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`,
+    }),
+  });
+
+  sdk.start();
+  console.log('Tracer initialized');
+}
+
+export async function shutdownTracer(): Promise<void> {
+  if (sdk) {
+    await sdk.shutdown();
+  }
+}
--- a/services/content/src/textbooks/textbooks.controller.ts
+++ b/services/content/src/textbooks/textbooks.controller.ts
@@ -0,0 +1,25 @@
+import { Body, Controller, Get, Param, Post } from '@nestjs/common';
+import { TextbooksService } from './textbooks.service.js';
+
+@Controller('textbooks')
+export class TextbooksController {
+  constructor(private readonly service: TextbooksService) {}
+
+  @Post()
+  async create(@Body() body: unknown) {
+    const result = await this.service.create(body as any);
+    return { success: true, data: result };
+  }
+
+  @Get()
+  async list() {
+    const result = await this.service.list();
+    return { success: true, data: result };
+  }
+
+  @Get(':id')
+  async getById(@Param('id') id: string) {
+    const result = await this.service.getById(id);
+    return { success: true, data: result };
+  }
+}
--- a/services/content/src/textbooks/textbooks.module.ts
+++ b/services/content/src/textbooks/textbooks.module.ts
@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { TextbooksController } from './textbooks.controller.js';
+import { TextbooksService } from './textbooks.service.js';
+
+@Module({
+  controllers: [TextbooksController],
+  providers: [TextbooksService],
+})
+export class TextbooksModule {}
--- a/services/content/src/textbooks/textbooks.schema.ts
+++ b/services/content/src/textbooks/textbooks.schema.ts
@@ -0,0 +1,30 @@
+import { mysqlTable, varchar, char, timestamp, text, integer } from 'drizzle-orm/mysql-core';
+
+export const textbooks = mysqlTable('content_textbooks', {
+  id: char('id', { length: 36 }).notNull().primaryKey(),
+  title: varchar('title', { length: 200 }).notNull(),
+  subjectId: char('subject_id', { length: 36 }).notNull(),
+  gradeId: char('grade_id', { length: 36 }).notNull(),
+  version: varchar('version', { length: 50 }).notNull(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow().onUpdateNow(),
+});
+
+export const chapters = mysqlTable('content_chapters', {
+  id: char('id', { length: 36 }).notNull().primaryKey(),
+  textbookId: char('textbook_id', { length: 36 }).notNull(),
+  title: varchar('title', { length: 200 }).notNull(),
+  order: integer('order_num').notNull(),
+  parentId: char('parent_id', { length: 36 }),
+});
+
+export const knowledgePoints = mysqlTable('content_knowledge_points', {
+  id: char('id', { length: 36 }).notNull().primaryKey(),
+  chapterId: char('chapter_id', { length: 36 }).notNull(),
+  title: varchar('title', { length: 200 }).notNull(),
+  description: text('description'),
+});
+
+export type Textbook = typeof textbooks.$inferSelect;
+export type Chapter = typeof chapters.$inferSelect;
+export type KnowledgePoint = typeof knowledgePoints.$inferSelect;
--- a/services/content/src/textbooks/textbooks.service.ts
+++ b/services/content/src/textbooks/textbooks.service.ts
@@ -0,0 +1,69 @@
+import { Injectable } from '@nestjs/common';
+import { getDb } from '../config/database.js';
+import { neo4jDriver } from '../config/neo4j.js';
+import { textbooks, chapters, knowledgePoints } from './textbooks.schema.js';
+import { v4 as uuidv4 } from 'uuid';
+import { eq } from 'drizzle-orm';
+
+@Injectable()
+export class TextbooksService {
+  async create(data: { title: string; subjectId: string; gradeId: string; version: string }) {
+    const id = uuidv4();
+    const db = getDb();
+    await db.insert(textbooks).values({ id, ...data });
+    return { id, ...data };
+  }
+
+  async list() {
+    const db = getDb();
+    return db.select().from(textbooks);
+  }
+
+  async getById(id: string) {
+    const db = getDb();
+    const [result] = await db.select().from(textbooks).where(eq(textbooks.id, id));
+    return result;
+  }
+
+  // 知识图谱：在 Neo4j 中创建知识点节点和关系
+  async createKnowledgeGraph(knowledgePointId: string, title: string, prerequisiteIds: string[]): Promise<void> {
+    const session = neo4jDriver.session();
+    try {
+      await session.executeWrite((tx) =>
+        tx.run(
+          'MERGE (kp:KnowledgePoint {id: $id, title: $title})',
+          { id: knowledgePointId, title }
+        )
+      );
+
+      for (const prereqId of prerequisiteIds) {
+        await session.executeWrite((tx) =>
+          tx.run(
+            `MATCH (prereq:KnowledgePoint {id: $prereqId}), (kp:KnowledgePoint {id: $kpId})
+             MERGE (prereq)-[:PREREQUISITE_OF]->(kp)`,
+            { prereqId, kpId: knowledgePointId }
+          )
+        );
+      }
+    } finally {
+      await session.close();
+    }
+  }
+
+  // 查询知识图谱（前置知识点）
+  async getPrerequisites(knowledgePointId: string): Promise<unknown[]> {
+    const session = neo4jDriver.session();
+    try {
+      const result = await session.executeRead((tx) =>
+        tx.run(
+          `MATCH (kp:KnowledgePoint {id: $id})<-[:PREREQUISITE_OF*1..5]-(prereq)
+           RETURN prereq.id as id, prereq.title as title`,
+          { id: knowledgePointId }
+        )
+      );
+      return result.records.map((r) => ({ id: r.get('id'), title: r.get('title') }));
+    } finally {
+      await session.close();
+    }
+  }
+}
--- a/services/content/tsconfig.json
+++ b/services/content/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}
--- a/services/data-ana/Dockerfile
+++ b/services/data-ana/Dockerfile
@@ -0,0 +1,8 @@
+FROM python:3.12-slim
+WORKDIR /app
+RUN pip install uv
+COPY pyproject.toml .
+RUN uv sync --no-dev
+COPY src ./src
+EXPOSE 3006
+CMD ["uv", "run", "uvicorn", "src.data_ana.main:app", "--host", "0.0.0.0", "--port", "3006"]
--- a/services/data-ana/README.md
+++ b/services/data-ana/README.md
@@ -0,0 +1,58 @@
+# data-ana 数据分析服务
+
+> 版本：0.1（P4 骨架）
+> 端口：3006
+
+## 职责
+
+数据分析限界上下文（Python 实现），消费 core-edu 与 content 的领域事件，
+构建 ClickHouse 学情宽表，计算知识点掌握度。
+对外提供学情仪表盘查询、班级/年级/学校维度报表、个性化推荐数据支撑。
+
+## 技术栈
+
+- Python 3.12+ / FastAPI 0.115+
+- clickhouse-connect（ClickHouse 宽表查询）
+- pydantic + pydantic-settings（运行时校验与配置）
+- structlog（结构化日志）
+- prometheus-client（指标）
+- OpenTelemetry（分布式追踪）
+
+## 开发
+
+```bash
+uv sync
+uv run uvicorn src.data_ana.main:app --host 0.0.0.0 --port 3006 --reload
+```
+
+## 配置
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `PORT` | 3006 | 服务端口 |
+| `CLICKHOUSE_HOST` | localhost | ClickHouse 主机 |
+| `CLICKHOUSE_PORT` | 8123 | ClickHouse HTTP 端口 |
+| `CLICKHOUSE_DATABASE` | edu_analytics | ClickHouse 数据库 |
+| `OTEL_ENDPOINT` | http://localhost:4318 | OpenTelemetry 端点 |
+| `LOG_LEVEL` | info | 日志级别 |
+
+## 模块结构
+
+```
+src/data_ana/
+├─ __init__.py
+├─ main.py              # FastAPI 入口（健康检查 + 分析端点骨架）
+├─ config.py            # pydantic-settings 配置
+└─ clickhouse_client.py # ClickHouse 客户端单例
+```
+
+## 关键端点
+
+- `GET /healthz` 健康检查
+- `GET /metrics` Prometheus 指标
+- `GET /analytics/class/{class_id}/performance` 班级成绩分析（P4 骨架）
+- `GET /analytics/student/{student_id}/weakness` 学生薄弱知识点分析（P4 骨架）
+
+## 对外契约
+
+gRPC 服务 `AnalyticsService` 定义见 `packages/shared-proto/proto/analytics.proto`。
--- a/services/data-ana/pyproject.toml
+++ b/services/data-ana/pyproject.toml
@@ -0,0 +1,24 @@
+[project]
+name = "data-ana-service"
+version = "0.1.0"
+description = "数据分析服务 - ClickHouse + 学习分析"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "clickhouse-connect>=0.7.0",
+    "pydantic>=2.9.0",
+    "pydantic-settings>=2.5.0",
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "opentelemetry-instrumentation-fastapi>=0.48b0",
+    "prometheus-client>=0.20.0",
+    "structlog>=24.4.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]
--- a/services/data-ana/src/data_ana/init.py
+++ b/services/data-ana/src/data_ana/init.py
--- a/services/data-ana/src/data_ana/clickhouse_client.py
+++ b/services/data-ana/src/data_ana/clickhouse_client.py
@@ -0,0 +1,25 @@
+"""ClickHouse 客户端."""
+import clickhouse_connect
+from .config import settings
+
+_client = None
+
+
+def get_client():
+    """获取 ClickHouse 客户端."""
+    global _client
+    if _client is None:
+        _client = clickhouse_connect.get_client(
+            host=settings.clickhouse_host,
+            port=settings.clickhouse_port,
+            database=settings.clickhouse_database,
+        )
+    return _client
+
+
+async def close_client() -> None:
+    """关闭客户端."""
+    global _client
+    if _client:
+        _client.close()
+        _client = None
--- a/services/data-ana/src/data_ana/config.py
+++ b/services/data-ana/src/data_ana/config.py
@@ -0,0 +1,18 @@
+"""配置管理."""
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """应用配置."""
+
+    port: int = 3006
+    clickhouse_host: str = "localhost"
+    clickhouse_port: int = 8123
+    clickhouse_database: str = "edu_analytics"
+    otel_endpoint: str = "http://localhost:4318"
+    log_level: str = "info"
+
+    model_config = {"env_file": ".env", "env_prefix": ""}
+
+
+settings = Settings()
--- a/services/data-ana/src/data_ana/main.py
+++ b/services/data-ana/src/data_ana/main.py
@@ -0,0 +1,75 @@
+"""数据分析服务入口."""
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from prometheus_client import make_asgi_app
+import structlog
+
+logger = structlog.get_logger()
+tracer = trace.get_tracer(__name__)
+
+
+def init_tracer() -> None:
+    """初始化 OpenTelemetry."""
+    provider = TracerProvider()
+    exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """应用生命周期."""
+    init_tracer()
+    logger.info("data-ana service starting")
+    yield
+    logger.info("data-ana service stopping")
+
+
+app = FastAPI(
+    title="Data Analytics Service",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# Prometheus 指标
+app.mount("/metrics", make_asgi_app())
+
+
+@app.get("/healthz")
+async def healthz():
+    """健康检查."""
+    return {"status": "ok", "service": "data-ana"}
+
+
+@app.get("/analytics/class/{class_id}/performance")
+async def class_performance(class_id: str):
+    """班级成绩分析."""
+    with tracer.start_as_current_span("class_performance"):
+        # P4 骨架：从 ClickHouse 查询分析数据
+        return {
+            "success": True,
+            "data": {
+                "classId": class_id,
+                "averageScore": 0,
+                "passRate": 0,
+                "message": "P4 skeleton - ClickHouse integration pending",
+            },
+        }
+
+
+@app.get("/analytics/student/{student_id}/weakness")
+async def student_weakness(student_id: str):
+    """学生薄弱知识点分析."""
+    with tracer.start_as_current_span("student_weakness"):
+        return {
+            "success": True,
+            "data": {
+                "studentId": student_id,
+                "weakPoints": [],
+                "message": "P4 skeleton - weakness analysis pending",
+            },
+        }