feat(p5): messaging, push gateway and AI assistant services

P5 阶段交付物： - services/msg: 消息通知服务（NestJS） - notifications: 发送通知 + ES 全文检索 + search - config/elasticsearch.ts: ES Client 单例 - package.json: 补充 @opentelemetry/sdk-node + exporter-trace-otlp-http - services/push-gateway: WebSocket 推送网关（Go Gin） - internal/hub/hub.go: WebSocket 连接池管理（Register/Unregister/SendToUser） - internal/ws/handler.go: JWT 鉴权 + WebSocket 升级 + 内部推送 API - services/ai: AI 辅助服务（Python FastAPI） - /chat + /chat/stream（SSE 流式） - /generate/question + /optimize/expression - config.py: OpenAI 兼容 API 配置 - packages/shared-proto/proto/msg.proto: NotificationService 契约（send/search） - packages/shared-proto/proto/ai.proto: AiService 契约（含 stream 方法）
feat(p4): content analysis service with Neo4j knowledge graph and ClickHouse analytics
2026-07-08 01:39:02 +08:00 · 2026-07-08 01:38:35 +08:00 · 2026-07-08 01:38:07 +08:00
99 changed files with 3792 additions and 0 deletions
--- a/packages/shared-proto/proto/ai.proto
+++ b/packages/shared-proto/proto/ai.proto
@@ -0,0 +1,60 @@
+syntax = "proto3";
+
+package next_edu_cloud.ai.v1;
+
+service AiService {
+  rpc Chat(ChatRequest) returns (ChatResponse);
+  rpc StreamChat(ChatRequest) returns (stream ChatChunk);
+  rpc GenerateQuestion(GenerateQuestionRequest) returns (GeneratedQuestion);
+  rpc OptimizeExpression(OptimizeExpressionRequest) returns (OptimizedExpression);
+}
+
+message ChatRequest {
+  repeated ChatMessage messages = 1;
+  string model = 2;
+  double temperature = 3;
+}
+
+message ChatMessage {
+  string role = 1;
+  string content = 2;
+}
+
+message ChatResponse {
+  string content = 1;
+  string model = 2;
+  Usage usage = 3;
+}
+
+message Usage {
+  int32 prompt_tokens = 1;
+  int32 completion_tokens = 2;
+  int32 total_tokens = 3;
+}
+
+message ChatChunk {
+  string content = 1;
+  bool done = 2;
+}
+
+message GenerateQuestionRequest {
+  string prompt = 1;
+  string subject = 2;
+  string difficulty = 3;
+}
+
+message GeneratedQuestion {
+  string question = 1;
+  string answer = 2;
+  string explanation = 3;
+}
+
+message OptimizeExpressionRequest {
+  string text = 1;
+  string context = 2;
+}
+
+message OptimizedExpression {
+  string optimized = 1;
+  repeated string suggestions = 2;
+}
--- 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/packages/shared-proto/proto/core_edu.proto
+++ b/packages/shared-proto/proto/core_edu.proto
@@ -0,0 +1,181 @@
+syntax = "proto3";
+
+package next_edu_cloud.core_edu.v1;
+
+// CoreEdu service contracts - P3 core teaching domain.
+// Covers exam management, homework assignment, and grade recording.
+// Event contracts live in events.proto under next_edu_cloud.events.v1.
+
+service ExamService {
+  rpc CreateExam(CreateExamRequest) returns (CreateExamResponse);
+  rpc GetExam(GetExamRequest) returns (Exam);
+  rpc ListExamsByClass(ListExamsByClassRequest) returns (ListExamsResponse);
+  rpc UpdateExam(UpdateExamRequest) returns (UpdateExamResponse);
+  rpc DeleteExam(DeleteExamRequest) returns (DeleteExamResponse);
+}
+
+service HomeworkService {
+  rpc AssignHomework(AssignHomeworkRequest) returns (AssignHomeworkResponse);
+  rpc GetHomework(GetHomeworkRequest) returns (Homework);
+  rpc ListHomeworkByClass(ListHomeworkByClassRequest) returns (ListHomeworkResponse);
+  rpc SubmitHomework(SubmitHomeworkRequest) returns (SubmitHomeworkResponse);
+}
+
+service GradeService {
+  rpc RecordGrade(RecordGradeRequest) returns (RecordGradeResponse);
+  rpc GetGrade(GetGradeRequest) returns (Grade);
+  rpc ListGradesByStudent(ListGradesByStudentRequest) returns (ListGradesResponse);
+  rpc ListGradesByExam(ListGradesByExamRequest) returns (ListGradesResponse);
+  rpc ListGradesByHomework(ListGradesByHomeworkRequest) returns (ListGradesResponse);
+}
+
+message Exam {
+  string id = 1;
+  string class_id = 2;
+  string title = 3;
+  string description = 4;
+  string exam_date = 5;
+  string duration = 6;
+  string total_score = 7;
+  string status = 8;
+  string created_by = 9;
+  string created_at = 10;
+  string updated_at = 11;
+}
+
+message Homework {
+  string id = 1;
+  string class_id = 2;
+  string title = 3;
+  string description = 4;
+  string due_date = 5;
+  string status = 6;
+  string created_by = 7;
+  string created_at = 8;
+  string updated_at = 9;
+}
+
+message Grade {
+  string id = 1;
+  string student_id = 2;
+  string exam_id = 3;
+  string homework_id = 4;
+  string score = 5;
+  string feedback = 6;
+  string graded_by = 7;
+  string created_at = 8;
+  string updated_at = 9;
+}
+
+message CreateExamRequest {
+  string class_id = 1;
+  string title = 2;
+  string description = 3;
+  string exam_date = 4;
+  string duration = 5;
+  string total_score = 6;
+  string created_by = 7;
+}
+
+message CreateExamResponse {
+  string id = 1;
+}
+
+message GetExamRequest {
+  string id = 1;
+}
+
+message ListExamsByClassRequest {
+  string class_id = 1;
+}
+
+message ListExamsResponse {
+  repeated Exam exams = 1;
+}
+
+message UpdateExamRequest {
+  string id = 1;
+  string title = 2;
+  string description = 3;
+  string exam_date = 4;
+  string duration = 5;
+  string total_score = 6;
+  string status = 7;
+}
+
+message UpdateExamResponse {
+  bool success = 1;
+}
+
+message DeleteExamRequest {
+  string id = 1;
+}
+
+message DeleteExamResponse {
+  bool success = 1;
+}
+
+message AssignHomeworkRequest {
+  string class_id = 1;
+  string title = 2;
+  string description = 3;
+  string due_date = 4;
+  string created_by = 5;
+}
+
+message AssignHomeworkResponse {
+  string id = 1;
+}
+
+message GetHomeworkRequest {
+  string id = 1;
+}
+
+message ListHomeworkByClassRequest {
+  string class_id = 1;
+}
+
+message ListHomeworkResponse {
+  repeated Homework homework = 1;
+}
+
+message SubmitHomeworkRequest {
+  string id = 1;
+}
+
+message SubmitHomeworkResponse {
+  bool success = 1;
+}
+
+message RecordGradeRequest {
+  string student_id = 1;
+  string exam_id = 2;
+  string homework_id = 3;
+  string score = 4;
+  string feedback = 5;
+  string graded_by = 6;
+}
+
+message RecordGradeResponse {
+  string id = 1;
+}
+
+message GetGradeRequest {
+  string id = 1;
+}
+
+message ListGradesByStudentRequest {
+  string student_id = 1;
+}
+
+message ListGradesByExamRequest {
+  string exam_id = 1;
+}
+
+message ListGradesByHomeworkRequest {
+  string homework_id = 1;
+}
+
+message ListGradesResponse {
+  repeated Grade grades = 1;
+}
--- a/packages/shared-proto/proto/events.proto
+++ b/packages/shared-proto/proto/events.proto
@@ -0,0 +1,60 @@
+syntax = "proto3";
+
+package next_edu_cloud.events.v1;
+
+// Cross-service event contracts published by CoreEdu via the transactional
+// outbox pattern and consumed by downstream services (notifications, analytics,
+// audit, etc.). Topics follow the convention edu.{domain}.events.
+//
+// Event routing (TOPIC_MAP in outbox.publisher.ts):
+//   edu.exam.events       <- exam.created / exam.updated / exam.deleted
+//   edu.homework.events   <- homework.assigned / homework.submitted / homework.graded
+//   edu.grade.events      <- grade.recorded / grade.updated
+//   edu.class.events      <- class.transferred
+
+message ClassEvent {
+  string event_id = 1;
+  string aggregate_id = 2;
+  string event_type = 3;
+  int64 occurred_at = 4;
+  string class_id = 5;
+  string name = 6;
+  string action = 7;
+  map<string, string> metadata = 8;
+}
+
+message ExamEvent {
+  string event_id = 1;
+  string aggregate_id = 2;
+  string event_type = 3;
+  int64 occurred_at = 4;
+  string exam_id = 5;
+  string class_id = 6;
+  string title = 7;
+  string action = 8;
+  map<string, string> metadata = 9;
+}
+
+message HomeworkEvent {
+  string event_id = 1;
+  string aggregate_id = 2;
+  string event_type = 3;
+  int64 occurred_at = 4;
+  string homework_id = 5;
+  string class_id = 6;
+  string title = 7;
+  string action = 8;
+  map<string, string> metadata = 9;
+}
+
+message GradeEvent {
+  string event_id = 1;
+  string aggregate_id = 2;
+  string event_type = 3;
+  int64 occurred_at = 4;
+  string grade_id = 5;
+  string student_id = 6;
+  string score = 7;
+  string action = 8;
+  map<string, string> metadata = 9;
+}
--- a/packages/shared-proto/proto/msg.proto
+++ b/packages/shared-proto/proto/msg.proto
@@ -0,0 +1,48 @@
+syntax = "proto3";
+
+package next_edu_cloud.msg.v1;
+
+service NotificationService {
+  rpc SendNotification(SendNotificationRequest) returns (Notification);
+  rpc ListNotifications(ListNotificationsRequest) returns (ListNotificationsResponse);
+  rpc MarkAsRead(MarkAsReadRequest) returns (Empty);
+  rpc SearchNotifications(SearchNotificationsRequest) returns (SearchNotificationsResponse);
+}
+
+message Notification {
+  string id = 1;
+  string user_id = 2;
+  string type = 3;
+  string title = 4;
+  string content = 5;
+  string channel = 6;
+  bool is_read = 7;
+  int64 created_at = 8;
+}
+
+message SendNotificationRequest {
+  string user_id = 1;
+  string type = 2;
+  string title = 3;
+  string content = 4;
+  string channel = 5;
+}
+
+message ListNotificationsRequest {
+  string user_id = 1;
+  bool only_unread = 2;
+}
+
+message ListNotificationsResponse {
+  repeated Notification notifications = 1;
+}
+
+message MarkAsReadRequest { string id = 1; }
+message SearchNotificationsRequest {
+  string user_id = 1;
+  string query = 2;
+}
+message SearchNotificationsResponse {
+  repeated Notification notifications = 1;
+}
+message Empty {}
--- a/services/ai/Dockerfile
+++ b/services/ai/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 3008
+CMD ["uv", "run", "uvicorn", "src.ai.main:app", "--host", "0.0.0.0", "--port", "3008"]
--- a/services/ai/README.md
+++ b/services/ai/README.md
@@ -0,0 +1,45 @@
+# AI 网关服务
+
+> 版本：0.1（P5 骨架）
+> 端口：3008
+
+## 职责
+
+AI 网关限界上下文（Python 实现），统一封装 LLM 调用（多模型路由、重试、限流、成本控制）。
+提供辅助出题、表达优化、分层提问等能力。通过 gRPC 查询 content 题库与 data-ana 学情数据。
+
+## 技术栈
+
+- Python 3.12 + FastAPI 0.115
+- Pydantic 2 + pydantic-settings
+- OpenTelemetry（LLM 调用链追踪）
+- prometheus-client + structlog
+- SSE 流式响应
+
+## 开发
+
+```bash
+uv sync
+uv run uvicorn src.ai.main:app --reload --port 3008
+```
+
+## API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /healthz | 健康检查 |
+| POST | /chat | LLM 聊天接口 |
+| POST | /chat/stream | 流式聊天（SSE） |
+| POST | /generate/question | 生成题目 |
+| POST | /optimize/expression | 优化表达 |
+| GET | /metrics | Prometheus 指标 |
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| port | 3008 | 服务端口 |
+| openai_api_key | - | OpenAI API 密钥 |
+| anthropic_api_key | - | Anthropic API 密钥 |
+| otel_endpoint | http://localhost:4318 | OpenTelemetry OTLP 端点 |
+| log_level | info | 日志级别 |
--- a/services/ai/pyproject.toml
+++ b/services/ai/pyproject.toml
@@ -0,0 +1,23 @@
+[project]
+name = "ai-service"
+version = "0.1.0"
+description = "AI 网关服务 - LLM 集成 + RAG"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "pydantic>=2.9.0",
+    "pydantic-settings>=2.5.0",
+    "httpx>=0.27.0",
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "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/ai/src/ai/init.py
+++ b/services/ai/src/ai/init.py
--- a/services/ai/src/ai/config.py
+++ b/services/ai/src/ai/config.py
@@ -0,0 +1,18 @@
+"""配置管理."""
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """应用配置."""
+
+    port: int = 3008
+    openai_api_key: str = ""
+    anthropic_api_key: str = ""
+    otel_endpoint: str = "http://localhost:4318"
+    log_level: str = "info"
+
+    model_config = {"env_file": ".env", "env_prefix": ""}
+
+
+settings = Settings()
--- a/services/ai/src/ai/main.py
+++ b/services/ai/src/ai/main.py
@@ -0,0 +1,111 @@
+"""AI 网关服务入口."""
+
+from contextlib import asynccontextmanager
+
+import structlog
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from prometheus_client import make_asgi_app
+from pydantic import BaseModel
+
+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("ai service starting")
+    yield
+    logger.info("ai service stopping")
+
+
+app = FastAPI(
+    title="AI Gateway Service",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.mount("/metrics", make_asgi_app())
+
+
+class ChatRequest(BaseModel):
+    """聊天请求."""
+
+    messages: list[dict]
+    model: str = "gpt-4o-mini"
+    temperature: float = 0.7
+    stream: bool = False
+
+
+class ChatResponse(BaseModel):
+    """聊天响应."""
+
+    content: str
+    model: str
+    usage: dict
+
+
+@app.get("/healthz")
+async def healthz():
+    """健康检查."""
+    return {"status": "ok", "service": "ai"}
+
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat(req: ChatRequest):
+    """LLM 聊天接口."""
+    with tracer.start_as_current_span("ai_chat"):
+        # P5 骨架：实际调用 OpenAI/Anthropic API
+        # 需要从环境变量获取 API key
+        return {
+            "content": "P5 skeleton - LLM integration pending",
+            "model": req.model,
+            "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
+        }
+
+
+@app.post("/chat/stream")
+async def chat_stream(req: ChatRequest):
+    """流式聊天（SSE）."""
+
+    async def generate():
+        with tracer.start_as_current_span("ai_chat_stream"):
+            # P5 骨架：流式调用 LLM
+            yield "data: P5 skeleton\n\n"
+            yield "data: [DONE]\n\n"
+
+    return StreamingResponse(generate(), media_type="text/event-stream")
+
+
+@app.post("/generate/question")
+async def generate_question(prompt: str):
+    """生成题目."""
+    with tracer.start_as_current_span("generate_question"):
+        return {
+            "success": True,
+            "data": {"question": "P5 skeleton - question generation pending"},
+        }
+
+
+@app.post("/optimize/expression")
+async def optimize_expression(text: str):
+    """优化表达."""
+    with tracer.start_as_current_span("optimize_expression"):
+        return {
+            "success": True,
+            "data": {"optimized": "P5 skeleton - expression optimization pending"},
+        }
--- 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/core-edu/Dockerfile
+++ b/services/core-edu/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 3004
+CMD ["node", "dist/main.js"]
--- a/services/core-edu/README.md
+++ b/services/core-edu/README.md
@@ -0,0 +1,52 @@
+# core-edu 教学核心服务
+
+> P3 核心教学阶段骨架 | 端口 3004
+
+## 职责
+
+core-edu 是教学核心限界上下文，合并 P1 的 classes 域，管理考试 / 作业 / 成绩聚合。
+覆盖教学全链路：考试发布、作业提交、成绩录入与查询。
+
+## 模块结构
+
+```
+src/
+├─ config/           # env / database / kafka
+├─ shared/
+│  ├─ outbox/        # 事务性发件箱（schema + repository + publisher）
+│  ├─ errors/        # 应用错误 + 全局错误过滤器
+│  └─ observability/ # logger / metrics / tracer
+├─ middleware/       # auth.middleware / permission.guard
+├─ classes/          # P3 待合并（骨架）
+├─ exams/            # 考试域
+├─ homework/         # 作业域
+├─ grades/           # 成绩域
+├─ app.module.ts
+└─ main.ts
+```
+
+## 关键机制
+
+- **Outbox 模式**：写业务数据同事务写 `core_edu_outbox`，OutboxPublisher 定时扫描并发送到 Kafka，保证事件可靠投递。
+- **Kafka 集成**：idempotent + transactional producer，按 eventType 路由到 `edu.{domain}.events` 主题。
+- **事件契约**：见 `packages/shared-proto/proto/events.proto`。
+
+## 开发
+
+```bash
+pnpm install
+pnpm dev          # 端口 3004
+pnpm typecheck
+pnpm lint
+pnpm test
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认 |
+|------|------|------|
+| `PORT` | 服务端口 | 3004 |
+| `DATABASE_URL` | MySQL 连接串 | - |
+| `KAFKA_BROKERS` | Kafka broker 列表（逗号分隔） | localhost:9092 |
+| `JWT_SECRET` | JWT 密钥 | - |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP 上报地址（可选） | - |
--- a/services/core-edu/nest-cli.json
+++ b/services/core-edu/nest-cli.json
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}
--- a/services/core-edu/package.json
+++ b/services/core-edu/package.json
@@ -0,0 +1,42 @@
+{
+  "name": "@edu/core-edu-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",
+    "kafkajs": "^2.2.0",
+    "pino": "^9.4.0",
+    "prom-client": "^15.1.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-node": "^0.53.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.53.0",
+    "zod": "^3.23.0",
+    "uuid": "^10.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.0"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.4.0",
+    "@nestjs/schematics": "^10.2.0",
+    "@types/express": "^4.17.0",
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "eslint": "^9.10.0",
+    "pino-pretty": "^11.2.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}
--- a/services/core-edu/src/app.module.ts
+++ b/services/core-edu/src/app.module.ts
@@ -0,0 +1,15 @@
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { ExamsModule } from './exams/exams.module.js';
+import { HomeworkModule } from './homework/homework.module.js';
+import { GradesModule } from './grades/grades.module.js';
+import { ClassesModule } from './classes/classes.module.js';
+import { AuthMiddleware } from './middleware/auth.middleware.js';
+
+@Module({
+  imports: [ExamsModule, HomeworkModule, GradesModule, ClassesModule],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer): void {
+    consumer.apply(AuthMiddleware).forRoutes('/api/*');
+  }
+}
--- a/services/core-edu/src/classes/classes.module.ts
+++ b/services/core-edu/src/classes/classes.module.ts
@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+
+/**
+ * Classes module - P3 skeleton placeholder.
+ *
+ * The classes domain was merged into CoreEdu in P3. This empty module
+ * exists so that future class-transfer features and event handlers can
+ * be registered without restructuring the AppModule imports.
+ */
+@Module({
+  controllers: [],
+  providers: [],
+  exports: [],
+})
+export class ClassesModule {}
--- a/services/core-edu/src/config/database.ts
+++ b/services/core-edu/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/core-edu/src/config/env.ts
+++ b/services/core-edu/src/config/env.ts
@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+const envSchema = z.object({
+  PORT: z.string().default('3004'),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url().optional(),
+  JWT_SECRET: z.string(),
+  JWT_ISSUER: z.string().default('next-edu-cloud'),
+  KAFKA_BROKERS: z.string().default('localhost:9092'),
+  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/core-edu/src/config/kafka.ts
+++ b/services/core-edu/src/config/kafka.ts
@@ -0,0 +1,25 @@
+import { Kafka } from 'kafkajs';
+import { env } from './env.js';
+
+export const kafka = new Kafka({
+  brokers: env.KAFKA_BROKERS.split(','),
+  clientId: 'core-edu-service',
+});
+
+export const producer = kafka.producer({
+  idempotent: true,
+  transactionalId: 'core-edu-tx',
+});
+
+export const consumer = kafka.consumer({ groupId: 'core-edu-group' });
+
+export async function connectKafka(): Promise<void> {
+  await producer.connect();
+  await consumer.connect();
+  console.log('Kafka connected');
+}
+
+export async function disconnectKafka(): Promise<void> {
+  await producer.disconnect();
+  await consumer.disconnect();
+}
--- a/services/core-edu/src/exams/exams.controller.ts
+++ b/services/core-edu/src/exams/exams.controller.ts
@@ -0,0 +1,57 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Post,
+  Put,
+  UseGuards,
+} from '@nestjs/common';
+import { ExamsService, type CreateExamInput, type UpdateExamInput } from './exams.service.js';
+import { PermissionGuard, Permissions } from '../../middleware/permission.guard.js';
+
+interface SuccessResponse<T> {
+  data: T;
+  timestamp: string;
+}
+
+@Controller('api/v1/exams')
+export class ExamsController {
+  constructor(private readonly examsService: ExamsService) {}
+
+  @Post()
+  @UseGuards(new PermissionGuard(Permissions.EXAM_CREATE))
+  async create(@Body() body: CreateExamInput): Promise<SuccessResponse<{ id: string }>> {
+    const result = await this.examsService.createExam(body);
+    return { data: result, timestamp: new Date().toISOString() };
+  }
+
+  @Get(':id')
+  @UseGuards(new PermissionGuard(Permissions.EXAM_READ))
+  async findOne(@Param('id') id: string): Promise<SuccessResponse<Awaited<ReturnType<ExamsService['getExam']>>>> {
+    const data = await this.examsService.getExam(id);
+    return { data, timestamp: new Date().toISOString() };
+  }
+
+  @Get('class/:classId')
+  @UseGuards(new PermissionGuard(Permissions.EXAM_READ))
+  async listByClass(@Param('classId') classId: string): Promise<SuccessResponse<Awaited<ReturnType<ExamsService['listExamsByClass']>>>> {
+    const data = await this.examsService.listExamsByClass(classId);
+    return { data, timestamp: new Date().toISOString() };
+  }
+
+  @Put(':id')
+  @UseGuards(new PermissionGuard(Permissions.EXAM_UPDATE))
+  async update(@Param('id') id: string, @Body() body: UpdateExamInput): Promise<SuccessResponse<{ success: true }>> {
+    await this.examsService.updateExam(id, body);
+    return { data: { success: true }, timestamp: new Date().toISOString() };
+  }
+
+  @Delete(':id')
+  @UseGuards(new PermissionGuard(Permissions.EXAM_DELETE))
+  async remove(@Param('id') id: string): Promise<SuccessResponse<{ success: true }>> {
+    await this.examsService.deleteExam(id);
+    return { data: { success: true }, timestamp: new Date().toISOString() };
+  }
+}
--- a/services/core-edu/src/exams/exams.module.ts
+++ b/services/core-edu/src/exams/exams.module.ts
@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { ExamsController } from './exams.controller.js';
+import { ExamsService } from './exams.service.js';
+
+@Module({
+  controllers: [ExamsController],
+  providers: [ExamsService],
+  exports: [ExamsService],
+})
+export class ExamsModule {}
--- a/services/core-edu/src/exams/exams.repository.ts
+++ b/services/core-edu/src/exams/exams.repository.ts
@@ -0,0 +1,28 @@
+import { eq } from 'drizzle-orm';
+import { db } from '../../config/database.js';
+import { exams, type Exam, type NewExam } from './exams.schema.js';
+
+export class ExamsRepository {
+  async findById(id: string): Promise<Exam | undefined> {
+    const [result] = await db
+      .select()
+      .from(exams)
+      .where(eq(exams.id, id))
+      .limit(1);
+    return result;
+  }
+
+  async findByClassId(classId: string): Promise<Exam[]> {
+    return db.select().from(exams).where(eq(exams.classId, classId));
+  }
+
+  async update(id: string, data: Partial<NewExam>): Promise<void> {
+    await db.update(exams).set(data).where(eq(exams.id, id));
+  }
+
+  async delete(id: string): Promise<void> {
+    await db.delete(exams).where(eq(exams.id, id));
+  }
+}
+
+export const examsRepository = new ExamsRepository();
--- a/services/core-edu/src/exams/exams.schema.ts
+++ b/services/core-edu/src/exams/exams.schema.ts
@@ -0,0 +1,25 @@
+import {
+  mysqlTable,
+  varchar,
+  text,
+  timestamp,
+  char,
+  datetime,
+} from 'drizzle-orm/mysql-core';
+
+export const exams = mysqlTable('core_edu_exams', {
+  id: char('id', { length: 36 }).notNull().primaryKey(),
+  classId: char('class_id', { length: 36 }).notNull(),
+  title: varchar('title', { length: 200 }).notNull(),
+  description: text('description'),
+  examDate: datetime('exam_date').notNull(),
+  duration: varchar('duration', { length: 50 }).notNull(),
+  totalScore: varchar('total_score', { length: 10 }).notNull(),
+  status: varchar('status', { length: 20 }).notNull().default('draft'),
+  createdBy: char('created_by', { length: 36 }).notNull(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow().onUpdateNow(),
+});
+
+export type Exam = typeof exams.$inferSelect;
+export type NewExam = typeof exams.$inferInsert;
--- a/services/core-edu/src/exams/exams.service.ts
+++ b/services/core-edu/src/exams/exams.service.ts
@@ -0,0 +1,127 @@
+import { randomUUID } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { Injectable } from '@nestjs/common';
+import { db } from '../../config/database.js';
+import { exams } from './exams.schema.js';
+import { examsRepository } from './exams.repository.js';
+import { outboxRepository } from '../../shared/outbox/outbox.repository.js';
+import type { Exam, NewExam } from './exams.schema.js';
+import { NotFoundError, ValidationError } from '../../shared/errors/application-error.js';
+
+export interface CreateExamInput {
+  classId: string;
+  title: string;
+  description?: string;
+  examDate: Date;
+  duration: string;
+  totalScore: string;
+  createdBy: string;
+}
+
+export interface UpdateExamInput {
+  title?: string;
+  description?: string;
+  examDate?: Date;
+  duration?: string;
+  totalScore?: string;
+  status?: string;
+}
+
+@Injectable()
+export class ExamsService {
+  async createExam(input: CreateExamInput): Promise<{ id: string }> {
+    if (!input.classId || !input.title || !input.createdBy) {
+      throw new ValidationError('classId, title, createdBy are required');
+    }
+
+    const id = randomUUID();
+    const exam: NewExam = {
+      id,
+      classId: input.classId,
+      title: input.title,
+      description: input.description,
+      examDate: input.examDate,
+      duration: input.duration,
+      totalScore: input.totalScore,
+      status: 'draft',
+      createdBy: input.createdBy,
+    };
+
+    await db.transaction(async (tx) => {
+      await tx.insert(exams).values(exam);
+      await outboxRepository.create(
+        {
+          id: randomUUID(),
+          aggregateId: id,
+          aggregateType: 'exam',
+          eventType: 'exam.created',
+          payload: JSON.stringify({
+            id,
+            classId: input.classId,
+            title: input.title,
+          }),
+          status: 'pending',
+        },
+        tx,
+      );
+    });
+
+    return { id };
+  }
+
+  async getExam(id: string): Promise<Exam> {
+    const exam = await examsRepository.findById(id);
+    if (!exam) {
+      throw new NotFoundError(`Exam ${id} not found`);
+    }
+    return exam;
+  }
+
+  async listExamsByClass(classId: string): Promise<Exam[]> {
+    return examsRepository.findByClassId(classId);
+  }
+
+  async updateExam(id: string, data: UpdateExamInput): Promise<void> {
+    const existing = await examsRepository.findById(id);
+    if (!existing) {
+      throw new NotFoundError(`Exam ${id} not found`);
+    }
+
+    await db.transaction(async (tx) => {
+      await tx.update(exams).set(data).where(eq(exams.id, id));
+      await outboxRepository.create(
+        {
+          id: randomUUID(),
+          aggregateId: id,
+          aggregateType: 'exam',
+          eventType: 'exam.updated',
+          payload: JSON.stringify({ id, changes: data }),
+          status: 'pending',
+        },
+        tx,
+      );
+    });
+  }
+
+  async deleteExam(id: string): Promise<void> {
+    const existing = await examsRepository.findById(id);
+    if (!existing) {
+      throw new NotFoundError(`Exam ${id} not found`);
+    }
+
+    await db.transaction(async (tx) => {
+      await tx.delete(exams).where(eq(exams.id, id));
+      await outboxRepository.create(
+        {
+          id: randomUUID(),
+          aggregateId: id,
+          aggregateType: 'exam',
+          eventType: 'exam.deleted',
+          payload: JSON.stringify({ id }),
+          status: 'pending',
+        },
+        tx,
+      );
+    });
+  }
+}
--- a/services/core-edu/src/grades/grades.controller.ts
+++ b/services/core-edu/src/grades/grades.controller.ts
@@ -0,0 +1,55 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { GradesService, type RecordGradeInput } from './grades.service.js';
+import { PermissionGuard, Permissions } from '../../middleware/permission.guard.js';
+
+interface SuccessResponse<T> {
+  data: T;
+  timestamp: string;
+}
+
+@Controller('api/v1/grades')
+export class GradesController {
+  constructor(private readonly gradesService: GradesService) {}
+
+  @Post()
+  @UseGuards(new PermissionGuard(Permissions.GRADE_CREATE))
+  async record(@Body() body: RecordGradeInput): Promise<SuccessResponse<{ id: string }>> {
+    const result = await this.gradesService.recordGrade(body);
+    return { data: result, timestamp: new Date().toISOString() };
+  }
+
+  @Get(':id')
+  @UseGuards(new PermissionGuard(Permissions.GRADE_READ))
+  async findOne(@Param('id') id: string): Promise<SuccessResponse<Awaited<ReturnType<GradesService['getGrade']>>>> {
+    const data = await this.gradesService.getGrade(id);
+    return { data, timestamp: new Date().toISOString() };
+  }
+
+  @Get('student/:studentId')
+  @UseGuards(new PermissionGuard(Permissions.GRADE_READ))
+  async listByStudent(@Param('studentId') studentId: string): Promise<SuccessResponse<Awaited<ReturnType<GradesService['listByStudent']>>>> {
+    const data = await this.gradesService.listByStudent(studentId);
+    return { data, timestamp: new Date().toISOString() };
+  }
+
+  @Get('exam/:examId')
+  @UseGuards(new PermissionGuard(Permissions.GRADE_READ))
+  async listByExam(@Param('examId') examId: string): Promise<SuccessResponse<Awaited<ReturnType<GradesService['listByExam']>>>> {
+    const data = await this.gradesService.listByExam(examId);
+    return { data, timestamp: new Date().toISOString() };
+  }
+
+  @Get('homework/:homeworkId')
+  @UseGuards(new PermissionGuard(Permissions.GRADE_READ))
+  async listByHomework(@Param('homeworkId') homeworkId: string): Promise<SuccessResponse<Awaited<ReturnType<GradesService['listByHomework']>>>> {
+    const data = await this.gradesService.listByHomework(homeworkId);
+    return { data, timestamp: new Date().toISOString() };
+  }
+}
--- a/services/core-edu/src/grades/grades.module.ts
+++ b/services/core-edu/src/grades/grades.module.ts
@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { GradesController } from './grades.controller.js';
+import { GradesService } from './grades.service.js';
+
+@Module({
+  controllers: [GradesController],
+  providers: [GradesService],
+  exports: [GradesService],
+})
+export class GradesModule {}
--- a/services/core-edu/src/grades/grades.schema.ts
+++ b/services/core-edu/src/grades/grades.schema.ts
@@ -0,0 +1,22 @@
+import {
+  mysqlTable,
+  varchar,
+  text,
+  timestamp,
+  char,
+} from 'drizzle-orm/mysql-core';
+
+export const grades = mysqlTable('core_edu_grades', {
+  id: char('id', { length: 36 }).notNull().primaryKey(),
+  studentId: char('student_id', { length: 36 }).notNull(),
+  examId: char('exam_id', { length: 36 }),
+  homeworkId: char('homework_id', { length: 36 }),
+  score: varchar('score', { length: 10 }).notNull(),
+  feedback: text('feedback'),
+  gradedBy: char('graded_by', { length: 36 }).notNull(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow().onUpdateNow(),
+});
+
+export type Grade = typeof grades.$inferSelect;
+export type NewGrade = typeof grades.$inferInsert;
--- a/services/core-edu/src/grades/grades.service.ts
+++ b/services/core-edu/src/grades/grades.service.ts
@@ -0,0 +1,87 @@
+import { randomUUID } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { Injectable } from '@nestjs/common';
+import { db } from '../../config/database.js';
+import { grades } from './grades.schema.js';
+import { outboxRepository } from '../../shared/outbox/outbox.repository.js';
+import type { Grade, NewGrade } from './grades.schema.js';
+import { NotFoundError, ValidationError } from '../../shared/errors/application-error.js';
+
+export interface RecordGradeInput {
+  studentId: string;
+  examId?: string;
+  homeworkId?: string;
+  score: string;
+  feedback?: string;
+  gradedBy: string;
+}
+
+@Injectable()
+export class GradesService {
+  async recordGrade(input: RecordGradeInput): Promise<{ id: string }> {
+    if (!input.studentId || !input.score || !input.gradedBy) {
+      throw new ValidationError('studentId, score, gradedBy are required');
+    }
+    if (!input.examId && !input.homeworkId) {
+      throw new ValidationError('Either examId or homeworkId must be provided');
+    }
+
+    const id = randomUUID();
+    const record: NewGrade = {
+      id,
+      studentId: input.studentId,
+      examId: input.examId,
+      homeworkId: input.homeworkId,
+      score: input.score,
+      feedback: input.feedback,
+      gradedBy: input.gradedBy,
+    };
+
+    await db.transaction(async (tx) => {
+      await tx.insert(grades).values(record);
+      await outboxRepository.create(
+        {
+          id: randomUUID(),
+          aggregateId: id,
+          aggregateType: 'grade',
+          eventType: 'grade.recorded',
+          payload: JSON.stringify({
+            id,
+            studentId: input.studentId,
+            score: input.score,
+            examId: input.examId,
+            homeworkId: input.homeworkId,
+          }),
+          status: 'pending',
+        },
+        tx,
+      );
+    });
+
+    return { id };
+  }
+
+  async getGrade(id: string): Promise<Grade> {
+    const [record] = await db
+      .select()
+      .from(grades)
+      .where(eq(grades.id, id))
+      .limit(1);
+    if (!record) {
+      throw new NotFoundError(`Grade ${id} not found`);
+    }
+    return record;
+  }
+
+  async listByStudent(studentId: string): Promise<Grade[]> {
+    return db.select().from(grades).where(eq(grades.studentId, studentId));
+  }
+
+  async listByExam(examId: string): Promise<Grade[]> {
+    return db.select().from(grades).where(eq(grades.examId, examId));
+  }
+
+  async listByHomework(homeworkId: string): Promise<Grade[]> {
+    return db.select().from(grades).where(eq(grades.homeworkId, homeworkId));
+  }
+}
--- a/services/core-edu/src/homework/homework.controller.ts
+++ b/services/core-edu/src/homework/homework.controller.ts
@@ -0,0 +1,48 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { HomeworkService, type AssignHomeworkInput } from './homework.service.js';
+import { PermissionGuard, Permissions } from '../../middleware/permission.guard.js';
+
+interface SuccessResponse<T> {
+  data: T;
+  timestamp: string;
+}
+
+@Controller('api/v1/homework')
+export class HomeworkController {
+  constructor(private readonly homeworkService: HomeworkService) {}
+
+  @Post()
+  @UseGuards(new PermissionGuard(Permissions.HOMEWORK_CREATE))
+  async assign(@Body() body: AssignHomeworkInput): Promise<SuccessResponse<{ id: string }>> {
+    const result = await this.homeworkService.assignHomework(body);
+    return { data: result, timestamp: new Date().toISOString() };
+  }
+
+  @Get(':id')
+  @UseGuards(new PermissionGuard(Permissions.HOMEWORK_READ))
+  async findOne(@Param('id') id: string): Promise<SuccessResponse<Awaited<ReturnType<HomeworkService['getHomework']>>>> {
+    const data = await this.homeworkService.getHomework(id);
+    return { data, timestamp: new Date().toISOString() };
+  }
+
+  @Get('class/:classId')
+  @UseGuards(new PermissionGuard(Permissions.HOMEWORK_READ))
+  async listByClass(@Param('classId') classId: string): Promise<SuccessResponse<Awaited<ReturnType<HomeworkService['listByClass']>>>> {
+    const data = await this.homeworkService.listByClass(classId);
+    return { data, timestamp: new Date().toISOString() };
+  }
+
+  @Post(':id/submit')
+  @UseGuards(new PermissionGuard(Permissions.HOMEWORK_SUBMIT))
+  async submit(@Param('id') id: string): Promise<SuccessResponse<{ success: true }>> {
+    await this.homeworkService.submitHomework(id);
+    return { data: { success: true }, timestamp: new Date().toISOString() };
+  }
+}
--- a/services/core-edu/src/homework/homework.module.ts
+++ b/services/core-edu/src/homework/homework.module.ts
@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { HomeworkController } from './homework.controller.js';
+import { HomeworkService } from './homework.service.js';
+
+@Module({
+  controllers: [HomeworkController],
+  providers: [HomeworkService],
+  exports: [HomeworkService],
+})
+export class HomeworkModule {}
--- a/services/core-edu/src/homework/homework.schema.ts
+++ b/services/core-edu/src/homework/homework.schema.ts
@@ -0,0 +1,23 @@
+import {
+  mysqlTable,
+  varchar,
+  text,
+  timestamp,
+  char,
+  datetime,
+} from 'drizzle-orm/mysql-core';
+
+export const homework = mysqlTable('core_edu_homework', {
+  id: char('id', { length: 36 }).notNull().primaryKey(),
+  classId: char('class_id', { length: 36 }).notNull(),
+  title: varchar('title', { length: 200 }).notNull(),
+  description: text('description'),
+  dueDate: datetime('due_date').notNull(),
+  status: varchar('status', { length: 20 }).notNull().default('assigned'),
+  createdBy: char('created_by', { length: 36 }).notNull(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow().onUpdateNow(),
+});
+
+export type Homework = typeof homework.$inferSelect;
+export type NewHomework = typeof homework.$inferInsert;
--- a/services/core-edu/src/homework/homework.service.ts
+++ b/services/core-edu/src/homework/homework.service.ts
@@ -0,0 +1,98 @@
+import { randomUUID } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { Injectable } from '@nestjs/common';
+import { db } from '../../config/database.js';
+import { homework } from './homework.schema.js';
+import { outboxRepository } from '../../shared/outbox/outbox.repository.js';
+import type { Homework, NewHomework } from './homework.schema.js';
+import { NotFoundError, ValidationError } from '../../shared/errors/application-error.js';
+
+export interface AssignHomeworkInput {
+  classId: string;
+  title: string;
+  description?: string;
+  dueDate: Date;
+  createdBy: string;
+}
+
+@Injectable()
+export class HomeworkService {
+  async assignHomework(input: AssignHomeworkInput): Promise<{ id: string }> {
+    if (!input.classId || !input.title || !input.createdBy) {
+      throw new ValidationError('classId, title, createdBy are required');
+    }
+
+    const id = randomUUID();
+    const record: NewHomework = {
+      id,
+      classId: input.classId,
+      title: input.title,
+      description: input.description,
+      dueDate: input.dueDate,
+      status: 'assigned',
+      createdBy: input.createdBy,
+    };
+
+    await db.transaction(async (tx) => {
+      await tx.insert(homework).values(record);
+      await outboxRepository.create(
+        {
+          id: randomUUID(),
+          aggregateId: id,
+          aggregateType: 'homework',
+          eventType: 'homework.assigned',
+          payload: JSON.stringify({
+            id,
+            classId: input.classId,
+            title: input.title,
+          }),
+          status: 'pending',
+        },
+        tx,
+      );
+    });
+
+    return { id };
+  }
+
+  async getHomework(id: string): Promise<Homework> {
+    const [record] = await db
+      .select()
+      .from(homework)
+      .where(eq(homework.id, id))
+      .limit(1);
+    if (!record) {
+      throw new NotFoundError(`Homework ${id} not found`);
+    }
+    return record;
+  }
+
+  async listByClass(classId: string): Promise<Homework[]> {
+    return db.select().from(homework).where(eq(homework.classId, classId));
+  }
+
+  async submitHomework(id: string): Promise<void> {
+    const existing = await this.getHomework(id);
+    if (existing.status === 'submitted') {
+      throw new ValidationError(`Homework ${id} already submitted`);
+    }
+
+    await db.transaction(async (tx) => {
+      await tx
+        .update(homework)
+        .set({ status: 'submitted' })
+        .where(eq(homework.id, id));
+      await outboxRepository.create(
+        {
+          id: randomUUID(),
+          aggregateId: id,
+          aggregateType: 'homework',
+          eventType: 'homework.submitted',
+          payload: JSON.stringify({ id }),
+          status: 'pending',
+        },
+        tx,
+      );
+    });
+  }
+}
--- a/services/core-edu/src/main.ts
+++ b/services/core-edu/src/main.ts
@@ -0,0 +1,50 @@
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module.js';
+import { env } from './config/env.js';
+import { connectKafka, disconnectKafka } from './config/kafka.js';
+import { outboxPublisher } from './shared/outbox/outbox.publisher.js';
+import { GlobalErrorFilter } from './shared/errors/global-error.filter.js';
+import { initTracer, shutdownTracer } from './shared/observability/tracer.js';
+import { logger } from './shared/observability/logger.js';
+
+async function bootstrap(): Promise<void> {
+  initTracer();
+
+  const app = await NestFactory.create(AppModule, { bufferLogs: true });
+  app.setGlobalPrefix('api');
+  app.useGlobalFilters(new GlobalErrorFilter());
+  app.enableShutdownHooks();
+
+  // Connect Kafka producer/consumer before starting the outbox publisher
+  await connectKafka();
+
+  // Start the transactional outbox publisher - polls pending messages
+  // and publishes them to Kafka topics defined in TOPIC_MAP.
+  await outboxPublisher.start();
+
+  await app.listen(env.PORT);
+  logger.info(
+    { port: env.PORT, service: 'core-edu' },
+    'CoreEdu service is listening',
+  );
+
+  process.on('SIGTERM', async () => {
+    logger.info('SIGTERM received, shutting down gracefully...');
+    await outboxPublisher.stop();
+    await disconnectKafka();
+    await shutdownTracer();
+    await app.close();
+    process.exit(0);
+  });
+
+  process.on('SIGINT', async () => {
+    logger.info('SIGINT received, shutting down gracefully...');
+    await outboxPublisher.stop();
+    await disconnectKafka();
+    await shutdownTracer();
+    await app.close();
+    process.exit(0);
+  });
+}
+
+void bootstrap();
--- a/services/core-edu/src/middleware/auth.middleware.ts
+++ b/services/core-edu/src/middleware/auth.middleware.ts
@@ -0,0 +1,40 @@
+import {
+  Injectable,
+  NestMiddleware,
+  UnauthorizedException,
+} from '@nestjs/common';
+import type { Request, Response, NextFunction } from 'express';
+
+export interface AuthenticatedUser {
+  id: string;
+  role: string;
+  permissions: string[];
+}
+
+export interface AuthenticatedRequest extends Request {
+  user?: AuthenticatedUser;
+}
+
+@Injectable()
+export class AuthMiddleware implements NestMiddleware {
+  use(req: AuthenticatedRequest, _res: Response, next: NextFunction): void {
+    const userId = req.headers['x-user-id'] as string | undefined;
+    const role = req.headers['x-user-role'] as string | undefined;
+    const permissionsHeader = req.headers['x-user-permissions'] as
+      | string
+      | undefined;
+
+    if (!userId || !role) {
+      throw new UnauthorizedException(
+        'Missing authentication headers (x-user-id, x-user-role)',
+      );
+    }
+
+    req.user = {
+      id: userId,
+      role,
+      permissions: permissionsHeader ? permissionsHeader.split(',') : [],
+    };
+    next();
+  }
+}
--- a/services/core-edu/src/middleware/permission.guard.ts
+++ b/services/core-edu/src/middleware/permission.guard.ts
@@ -0,0 +1,48 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  ForbiddenException,
+} from '@nestjs/common';
+import type { AuthenticatedRequest } from './auth.middleware.js';
+
+export const Permissions = {
+  EXAM_CREATE: 'exam:create',
+  EXAM_READ: 'exam:read',
+  EXAM_UPDATE: 'exam:update',
+  EXAM_DELETE: 'exam:delete',
+  HOMEWORK_CREATE: 'homework:create',
+  HOMEWORK_READ: 'homework:read',
+  HOMEWORK_UPDATE: 'homework:update',
+  HOMEWORK_DELETE: 'homework:delete',
+  HOMEWORK_GRADE: 'homework:grade',
+  HOMEWORK_SUBMIT: 'homework:submit',
+  GRADE_CREATE: 'grade:create',
+  GRADE_READ: 'grade:read',
+  GRADE_UPDATE: 'grade:update',
+  GRADE_DELETE: 'grade:delete',
+  CLASS_MANAGE: 'class:manage',
+  CLASS_READ: 'class:read',
+  CLASS_TRANSFER: 'class:transfer',
+} as const;
+
+export type Permission = (typeof Permissions)[keyof typeof Permissions];
+
+@Injectable()
+export class PermissionGuard implements CanActivate {
+  constructor(private readonly requiredPermission: Permission) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<AuthenticatedRequest>();
+    const user = request.user;
+    if (!user) {
+      throw new ForbiddenException('User not authenticated');
+    }
+    if (!user.permissions.includes(this.requiredPermission)) {
+      throw new ForbiddenException(
+        `Missing permission: ${this.requiredPermission}`,
+      );
+    }
+    return true;
+  }
+}
--- a/services/core-edu/src/shared/errors/application-error.ts
+++ b/services/core-edu/src/shared/errors/application-error.ts
@@ -0,0 +1,60 @@
+export enum CoreEduErrorCode {
+  VALIDATION_ERROR = 'CORE_EDU_VALIDATION_ERROR',
+  NOT_FOUND = 'CORE_EDU_NOT_FOUND',
+  UNAUTHORIZED = 'CORE_EDU_UNAUTHORIZED',
+  FORBIDDEN = 'CORE_EDU_FORBIDDEN',
+  CONFLICT = 'CORE_EDU_CONFLICT',
+  INTERNAL_ERROR = 'CORE_EDU_INTERNAL_ERROR',
+  EXAM_NOT_FOUND = 'CORE_EDU_EXAM_NOT_FOUND',
+  HOMEWORK_NOT_FOUND = 'CORE_EDU_HOMEWORK_NOT_FOUND',
+  GRADE_NOT_FOUND = 'CORE_EDU_GRADE_NOT_FOUND',
+  OUTBOX_PUBLISH_FAILED = 'CORE_EDU_OUTBOX_PUBLISH_FAILED',
+}
+
+export class ApplicationError extends Error {
+  constructor(
+    public readonly code: CoreEduErrorCode,
+    message: string,
+    public readonly statusCode: number = 500,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = 'ApplicationError';
+  }
+}
+
+export class ValidationError extends ApplicationError {
+  constructor(message: string, details?: unknown) {
+    super(CoreEduErrorCode.VALIDATION_ERROR, message, 400, details);
+  }
+}
+
+export class NotFoundError extends ApplicationError {
+  constructor(message: string, details?: unknown) {
+    super(CoreEduErrorCode.NOT_FOUND, message, 404, details);
+  }
+}
+
+export class UnauthorizedError extends ApplicationError {
+  constructor(message: string = 'Unauthorized') {
+    super(CoreEduErrorCode.UNAUTHORIZED, message, 401);
+  }
+}
+
+export class ForbiddenError extends ApplicationError {
+  constructor(message: string = 'Forbidden') {
+    super(CoreEduErrorCode.FORBIDDEN, message, 403);
+  }
+}
+
+export class ConflictError extends ApplicationError {
+  constructor(message: string, details?: unknown) {
+    super(CoreEduErrorCode.CONFLICT, message, 409, details);
+  }
+}
+
+export class InternalError extends ApplicationError {
+  constructor(message: string = 'Internal server error', details?: unknown) {
+    super(CoreEduErrorCode.INTERNAL_ERROR, message, 500, details);
+  }
+}
--- a/services/core-edu/src/shared/errors/global-error.filter.ts
+++ b/services/core-edu/src/shared/errors/global-error.filter.ts
@@ -0,0 +1,63 @@
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+} from '@nestjs/common';
+import { ZodError } from 'zod';
+import { ApplicationError, CoreEduErrorCode } from './application-error.js';
+import { logger } from '../observability/logger.js';
+
+@Catch()
+export class GlobalErrorFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse();
+    const request = ctx.getRequest();
+
+    let statusCode = HttpStatus.INTERNAL_SERVER_ERROR;
+    let code = CoreEduErrorCode.INTERNAL_ERROR;
+    let message = 'Internal server error';
+    let details: unknown;
+
+    if (exception instanceof ApplicationError) {
+      statusCode = exception.statusCode;
+      code = exception.code;
+      message = exception.message;
+      details = exception.details;
+    } else if (exception instanceof ZodError) {
+      statusCode = HttpStatus.BAD_REQUEST;
+      code = CoreEduErrorCode.VALIDATION_ERROR;
+      message = 'Validation failed';
+      details = exception.flatten().fieldErrors;
+    } else if (exception instanceof HttpException) {
+      statusCode = exception.getStatus();
+      const resp = exception.getResponse();
+      message =
+        typeof resp === 'string'
+          ? resp
+          : (resp as { message?: string }).message ?? exception.message;
+    } else if (exception instanceof Error) {
+      message = exception.message;
+    }
+
+    logger.error(
+      {
+        err: exception,
+        path: request.url,
+        method: request.method,
+        code,
+      },
+      `Request failed: ${message}`,
+    );
+
+    response.status(statusCode).json({
+      code,
+      message,
+      details,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+    });
+  }
+}
--- a/services/core-edu/src/shared/observability/logger.ts
+++ b/services/core-edu/src/shared/observability/logger.ts
@@ -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' },
+        },
+      }
+    : {}),
+});
--- a/services/core-edu/src/shared/observability/metrics.ts
+++ b/services/core-edu/src/shared/observability/metrics.ts
@@ -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);
--- a/services/core-edu/src/shared/observability/tracer.ts
+++ b/services/core-edu/src/shared/observability/tracer.ts
@@ -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');
+  }
+}
--- a/services/core-edu/src/shared/outbox/outbox.publisher.ts
+++ b/services/core-edu/src/shared/outbox/outbox.publisher.ts
@@ -0,0 +1,88 @@
+import { logger } from '../observability/logger.js';
+import { producer } from '../../config/kafka.js';
+import { outboxRepository } from './outbox.repository.js';
+import type { OutboxMessage } from './outbox.schema.js';
+
+const TOPIC_MAP: Record<string, string> = {
+  'exam.created': 'edu.exam.events',
+  'exam.updated': 'edu.exam.events',
+  'exam.deleted': 'edu.exam.events',
+  'homework.assigned': 'edu.homework.events',
+  'homework.submitted': 'edu.homework.events',
+  'homework.graded': 'edu.homework.events',
+  'grade.recorded': 'edu.grade.events',
+  'grade.updated': 'edu.grade.events',
+  'class.transferred': 'edu.class.events',
+};
+
+const POLL_INTERVAL_MS = 5000;
+const BATCH_SIZE = 100;
+const MAX_RETRY = 5;
+
+export class OutboxPublisher {
+  private intervalId: NodeJS.Timeout | null = null;
+  private isPolling = false;
+
+  async start(): Promise<void> {
+    logger.info('OutboxPublisher started');
+    this.intervalId = setInterval(() => {
+      void this.poll();
+    }, POLL_INTERVAL_MS);
+  }
+
+  async stop(): Promise<void> {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    logger.info('OutboxPublisher stopped');
+  }
+
+  private async poll(): Promise<void> {
+    if (this.isPolling) return;
+    this.isPolling = true;
+    try {
+      const messages = await outboxRepository.findPending(BATCH_SIZE);
+      for (const message of messages) {
+        await this.publish(message);
+      }
+    } catch (error) {
+      logger.error({ error }, 'Outbox poll failed');
+    } finally {
+      this.isPolling = false;
+    }
+  }
+
+  private async publish(message: OutboxMessage): Promise<void> {
+    const topic = TOPIC_MAP[message.eventType] ?? 'edu.fallback.events';
+    try {
+      await producer.send({
+        topic,
+        messages: [
+          {
+            key: message.aggregateId,
+            value: message.payload,
+            headers: {
+              eventType: message.eventType,
+              aggregateType: message.aggregateType,
+            },
+          },
+        ],
+      });
+      await outboxRepository.markProcessed(message.id);
+      logger.info(
+        { id: message.id, eventType: message.eventType, topic },
+        'Outbox message published',
+      );
+    } catch (error) {
+      logger.error({ error, id: message.id }, 'Outbox publish failed');
+      if (message.retryCount + 1 >= MAX_RETRY) {
+        await outboxRepository.markFailed(message.id);
+      } else {
+        await outboxRepository.incrementRetry(message.id);
+      }
+    }
+  }
+}
+
+export const outboxPublisher = new OutboxPublisher();
--- a/services/core-edu/src/shared/outbox/outbox.repository.ts
+++ b/services/core-edu/src/shared/outbox/outbox.repository.ts
@@ -0,0 +1,42 @@
+import { eq, sql } from 'drizzle-orm';
+import { db } from '../../config/database.js';
+import { outbox, type OutboxMessage, type NewOutboxMessage } from './outbox.schema.js';
+
+type DbClient = typeof db;
+
+export class OutboxRepository {
+  async create(message: NewOutboxMessage, tx: DbClient = db): Promise<void> {
+    await tx.insert(outbox).values(message);
+  }
+
+  async findPending(limit: number = 100): Promise<OutboxMessage[]> {
+    return db
+      .select()
+      .from(outbox)
+      .where(eq(outbox.status, 'pending'))
+      .limit(limit);
+  }
+
+  async markProcessed(id: string): Promise<void> {
+    await db
+      .update(outbox)
+      .set({ status: 'processed', processedAt: new Date() })
+      .where(eq(outbox.id, id));
+  }
+
+  async incrementRetry(id: string): Promise<void> {
+    await db
+      .update(outbox)
+      .set({ retryCount: sql`${outbox.retryCount} + 1` })
+      .where(eq(outbox.id, id));
+  }
+
+  async markFailed(id: string): Promise<void> {
+    await db
+      .update(outbox)
+      .set({ status: 'failed' })
+      .where(eq(outbox.id, id));
+  }
+}
+
+export const outboxRepository = new OutboxRepository();
--- a/services/core-edu/src/shared/outbox/outbox.schema.ts
+++ b/services/core-edu/src/shared/outbox/outbox.schema.ts
@@ -0,0 +1,16 @@
+import { mysqlTable, varchar, text, timestamp, char, bigint } from 'drizzle-orm/mysql-core';
+
+export const outbox = mysqlTable('core_edu_outbox', {
+  id: char('id', { length: 36 }).notNull().primaryKey(),
+  aggregateId: char('aggregate_id', { length: 36 }).notNull(),
+  aggregateType: varchar('aggregate_type', { length: 50 }).notNull(),
+  eventType: varchar('event_type', { length: 100 }).notNull(),
+  payload: text('payload').notNull(),
+  status: varchar('status', { length: 20 }).notNull().default('pending'),
+  retryCount: bigint('retry_count', { mode: 'number' }).notNull().default(0),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  processedAt: timestamp('processed_at'),
+});
+
+export type OutboxMessage = typeof outbox.$inferSelect;
+export type NewOutboxMessage = typeof outbox.$inferInsert;
--- a/services/core-edu/tsconfig.json
+++ b/services/core-edu/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/core-edu/vitest.config.ts
+++ b/services/core-edu/vitest.config.ts
@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['test/unit/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'dist/', 'test/', '**/*.d.ts'],
+      thresholds: {
+        statements: 60,
+        branches: 60,
+        functions: 60,
+        lines: 60,
+      },
+    },
+  },
+});
--- 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",
+            },
+        }
--- a/services/msg/Dockerfile
+++ b/services/msg/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 3007
+CMD ["node", "dist/main.js"]
--- a/services/msg/README.md
+++ b/services/msg/README.md
@@ -0,0 +1,43 @@
+# Msg 消息通知服务
+
+> 版本：0.1（P5 骨架）
+> 端口：3007
+
+## 职责
+
+消息通知限界上下文，管理通知的多渠道分发（站内信、邮件、短信、推送）。
+消费 Kafka 事件，写入 MySQL + Elasticsearch，调用 Push Gateway 实时推送。
+
+## 技术栈
+
+- NestJS 10 + TypeScript 5
+- Drizzle ORM + MySQL 8
+- Elasticsearch 8（全文检索）
+- Kafka（事件消费，骨架）
+- pino + prom-client + OpenTelemetry
+
+## 开发
+
+```bash
+pnpm install
+pnpm dev   # http://localhost:3007
+```
+
+## API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /notifications | 发送通知 |
+| GET | /notifications | 查询用户通知列表 |
+| POST | /notifications/:id/read | 标记已读 |
+| GET | /notifications/search?q= | 全文检索通知 |
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| PORT | 3007 | 服务端口 |
+| DATABASE_URL | - | MySQL 连接串 |
+| KAFKA_BROKERS | localhost:9092 | Kafka broker 列表 |
+| ES_URL | http://localhost:9200 | Elasticsearch 地址 |
+| JWT_SECRET | - | JWT 密钥 |
--- a/services/msg/nest-cli.json
+++ b/services/msg/nest-cli.json
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}
--- a/services/msg/package.json
+++ b/services/msg/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "@edu/msg-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",
+    "kafkajs": "^2.2.0",
+    "@elastic/elasticsearch": "^8.15.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/msg/src/app.module.ts
+++ b/services/msg/src/app.module.ts
@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+import { NotificationsModule } from './notifications/notifications.module.js';
+
+@Module({
+  imports: [NotificationsModule],
+})
+export class AppModule {}
--- a/services/msg/src/config/database.ts
+++ b/services/msg/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/msg/src/config/elasticsearch.ts
+++ b/services/msg/src/config/elasticsearch.ts
@@ -0,0 +1,13 @@
+import { Client } from '@elastic/elasticsearch';
+import { env } from './env.js';
+
+export const esClient = new Client({ node: env.ES_URL });
+
+export async function checkEsConnection(): Promise<void> {
+  try {
+    await esClient.ping();
+    console.log('Elasticsearch connected');
+  } catch (err) {
+    console.error('Elasticsearch connection failed:', err);
+  }
+}
--- a/services/msg/src/config/env.ts
+++ b/services/msg/src/config/env.ts
@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+const envSchema = z.object({
+  PORT: z.string().default('3007'),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url().optional(),
+  JWT_SECRET: z.string(),
+  JWT_ISSUER: z.string().default('next-edu-cloud'),
+  KAFKA_BROKERS: z.string().default('localhost:9092'),
+  ES_URL: z.string().url().default('http://localhost:9200'),
+  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/msg/src/main.ts
+++ b/services/msg/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 }, 'Msg service started');
+
+  process.on('SIGTERM', async () => {
+    await app.close();
+    await shutdownTracer();
+  });
+}
+
+bootstrap().catch((err: unknown) => {
+  logger.error({ err }, 'Failed to start msg service');
+  process.exit(1);
+});
--- a/services/msg/src/notifications/notifications.controller.ts
+++ b/services/msg/src/notifications/notifications.controller.ts
@@ -0,0 +1,32 @@
+import { Body, Controller, Get, Param, Post, Query, Req } from '@nestjs/common';
+import { NotificationsService } from './notifications.service.js';
+import type { SendNotificationDto } from './notifications.service.js';
+
+@Controller('notifications')
+export class NotificationsController {
+  constructor(private readonly service: NotificationsService) {}
+
+  @Post()
+  async send(@Body() body: unknown) {
+    const result = await this.service.send(body as SendNotificationDto);
+    return { success: true, data: result };
+  }
+
+  @Get()
+  async list(@Req() req: { userId: string }, @Query('unread') unread: string) {
+    const result = await this.service.listByUser(req.userId, unread === 'true');
+    return { success: true, data: result };
+  }
+
+  @Post(':id/read')
+  async markAsRead(@Param('id') id: string) {
+    await this.service.markAsRead(id);
+    return { success: true };
+  }
+
+  @Get('search')
+  async search(@Req() req: { userId: string }, @Query('q') q: string) {
+    const result = await this.service.search(req.userId, q);
+    return { success: true, data: result };
+  }
+}
--- a/services/msg/src/notifications/notifications.module.ts
+++ b/services/msg/src/notifications/notifications.module.ts
@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { NotificationsController } from './notifications.controller.js';
+import { NotificationsService } from './notifications.service.js';
+
+@Module({
+  controllers: [NotificationsController],
+  providers: [NotificationsService],
+})
+export class NotificationsModule {}
--- a/services/msg/src/notifications/notifications.schema.ts
+++ b/services/msg/src/notifications/notifications.schema.ts
@@ -0,0 +1,24 @@
+import { mysqlTable, varchar, char, timestamp, text, boolean, json } from 'drizzle-orm/mysql-core';
+
+export const notifications = mysqlTable('msg_notifications', {
+  id: char('id', { length: 36 }).notNull().primaryKey(),
+  userId: char('user_id', { length: 36 }).notNull(),
+  type: varchar('type', { length: 50 }).notNull(),
+  title: varchar('title', { length: 200 }).notNull(),
+  content: text('content').notNull(),
+  channel: varchar('channel', { length: 20 }).notNull().default('in_app'),
+  isRead: boolean('is_read').notNull().default(false),
+  metadata: json('metadata'),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+});
+
+export const notificationPreferences = mysqlTable('msg_notification_preferences', {
+  userId: char('user_id', { length: 36 }).notNull().primaryKey(),
+  emailEnabled: boolean('email_enabled').notNull().default(true),
+  smsEnabled: boolean('sms_enabled').notNull().default(false),
+  pushEnabled: boolean('push_enabled').notNull().default(true),
+  inAppEnabled: boolean('in_app_enabled').notNull().default(true),
+});
+
+export type Notification = typeof notifications.$inferSelect;
+export type NotificationPreference = typeof notificationPreferences.$inferSelect;
--- a/services/msg/src/notifications/notifications.service.ts
+++ b/services/msg/src/notifications/notifications.service.ts
@@ -0,0 +1,110 @@
+import { Injectable } from '@nestjs/common';
+import { getDb } from '../config/database.js';
+import { notifications, notificationPreferences } from './notifications.schema.js';
+import type { NotificationPreference } from './notifications.schema.js';
+import { v4 as uuidv4 } from 'uuid';
+import { eq, and } from 'drizzle-orm';
+import { esClient } from '../config/elasticsearch.js';
+import { logger } from '../shared/observability/logger.js';
+
+export interface SendNotificationDto {
+  userId: string;
+  type: string;
+  title: string;
+  content: string;
+  channel?: string;
+  metadata?: Record<string, unknown>;
+}
+
+@Injectable()
+export class NotificationsService {
+  async send(dto: SendNotificationDto) {
+    const id = uuidv4();
+    const db = getDb();
+
+    // 检查用户偏好
+    const [pref] = await db.select().from(notificationPreferences).where(eq(notificationPreferences.userId, dto.userId));
+
+    const channel = dto.channel || 'in_app';
+    if (pref && !this.isChannelEnabled(pref, channel)) {
+      logger.info({ userId: dto.userId, channel }, 'Notification skipped by preference');
+      return { skipped: true };
+    }
+
+    // 写入 DB
+    await db.insert(notifications).values({
+      id,
+      userId: dto.userId,
+      type: dto.type,
+      title: dto.title,
+      content: dto.content,
+      channel,
+      metadata: dto.metadata,
+    });
+
+    // 索引到 ES（全文检索）
+    try {
+      await esClient.index({
+        index: 'notifications',
+        id,
+        document: {
+          userId: dto.userId,
+          type: dto.type,
+          title: dto.title,
+          content: dto.content,
+          channel,
+          createdAt: new Date().toISOString(),
+        },
+      });
+    } catch (err) {
+      logger.error({ err }, 'Failed to index notification in ES');
+    }
+
+    // TODO: 触发 Push Gateway 推送（P5 后期）
+
+    return { id, skipped: false };
+  }
+
+  async listByUser(userId: string, onlyUnread: boolean = false) {
+    const db = getDb();
+    const conditions = onlyUnread
+      ? and(eq(notifications.userId, userId), eq(notifications.isRead, false))
+      : eq(notifications.userId, userId);
+    return db.select().from(notifications).where(conditions);
+  }
+
+  async markAsRead(id: string) {
+    const db = getDb();
+    await db.update(notifications).set({ isRead: true }).where(eq(notifications.id, id));
+  }
+
+  async search(userId: string, query: string) {
+    const result = await esClient.search({
+      index: 'notifications',
+      query: {
+        bool: {
+          must: [
+            { term: { userId } },
+            {
+              multi_match: {
+                query,
+                fields: ['title', 'content'],
+              },
+            },
+          ],
+        },
+      },
+    });
+    return result.hits.hits;
+  }
+
+  private isChannelEnabled(pref: NotificationPreference, channel: string): boolean {
+    switch (channel) {
+      case 'email': return pref.emailEnabled;
+      case 'sms': return pref.smsEnabled;
+      case 'push': return pref.pushEnabled;
+      case 'in_app': return pref.inAppEnabled;
+      default: return true;
+    }
+  }
+}
--- a/services/msg/src/shared/errors/application-error.ts
+++ b/services/msg/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, 'MSG_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}`, 'MSG_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}`, 'MSG_PERMISSION_DENIED', { permission });
+  }
+}
+
+export class ConflictError extends ApplicationError {
+  readonly type = 'conflict' as const;
+  readonly statusCode = 409;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'MSG_CONFLICT', details);
+  }
+}
+
+export class BusinessError extends ApplicationError {
+  readonly type = 'business' as const;
+  readonly statusCode = 422;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'MSG_BUSINESS_ERROR', details);
+  }
+}
+
+export class DatabaseError extends ApplicationError {
+  readonly type = 'database' as const;
+  readonly statusCode = 500;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'MSG_DATABASE_ERROR', details);
+  }
+}
+
+export class InternalError extends ApplicationError {
+  readonly type = 'internal' as const;
+  readonly statusCode = 500;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, 'MSG_INTERNAL_ERROR', details);
+  }
+}
--- a/services/msg/src/shared/errors/global-error.filter.ts
+++ b/services/msg/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: 'MSG_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/msg/src/shared/observability/logger.ts
+++ b/services/msg/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: 'msg',
+    version: '0.1.0',
+  },
+  transport:
+    env.NODE_ENV === 'development'
+      ? {
+          target: 'pino-pretty',
+          options: { colorize: true },
+        }
+      : undefined,
+});
+
+export type Logger = typeof logger;
--- a/services/msg/src/shared/observability/metrics.ts
+++ b/services/msg/src/shared/observability/metrics.ts
@@ -0,0 +1,24 @@
+import promClient from 'prom-client';
+
+const registry = new promClient.Registry();
+// 修复：在本地 registry 上设置默认标签（原代码误用全局 register）
+registry.setDefaultLabels({ service: 'msg' });
+
+registry.registerMetric(
+  new promClient.Counter({
+    name: 'msg_requests_total',
+    help: 'Total number of msg requests',
+    labelNames: ['method', 'endpoint', 'status'],
+  }),
+);
+
+registry.registerMetric(
+  new promClient.Histogram({
+    name: 'msg_request_duration_seconds',
+    help: 'Msg 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/msg/src/shared/observability/tracer.ts
+++ b/services/msg/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: 'msg',
+    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/msg/tsconfig.json
+++ b/services/msg/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/push-gateway/Dockerfile
+++ b/services/push-gateway/Dockerfile
@@ -0,0 +1,13 @@
+FROM golang:1.22-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o push-gateway .
+
+FROM alpine:3.20
+RUN apk --no-cache add ca-certificates
+WORKDIR /app
+COPY --from=builder /app/push-gateway .
+EXPOSE 8081
+CMD ["./push-gateway"]
--- a/services/push-gateway/README.md
+++ b/services/push-gateway/README.md
@@ -0,0 +1,42 @@
+# Push Gateway 推送网关服务
+
+> 版本：0.1（P5 骨架）
+> 端口：8081
+
+## 职责
+
+实时推送基础设施服务（Go 实现），管理 WebSocket 长连接。
+接收 Msg 服务的推送请求，维护用户在线连接池，将消息实时投递到浏览器/移动端。
+
+## 技术栈
+
+- Go 1.22 + Gin 1.10
+- gorilla/websocket 1.5
+- golang-jwt/jwt/v5（JWT 鉴权）
+- zap（结构化日志，骨架）
+
+## 开发
+
+```bash
+go mod tidy
+go run main.go   # :8081
+```
+
+## API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /healthz | 健康检查 |
+| GET | /ws?token=JWT | WebSocket 升级端点（JWT 鉴权） |
+| POST | /internal/push | 内部推送 API（Msg 服务调用） |
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| PUSH_GATEWAY_PORT | 8081 | 服务端口 |
+| JWT_SECRET | p1-dev-secret-change-in-production | JWT 密钥 |
+
+## WebSocket 心跳
+
+客户端发送 `ping` 文本帧，服务端回复 `pong`。
--- a/services/push-gateway/go.mod
+++ b/services/push-gateway/go.mod
@@ -0,0 +1,11 @@
+module github.com/edu-cloud/push-gateway
+
+go 1.22
+
+require (
+	github.com/gin-gonic/gin v1.10.0
+	github.com/golang-jwt/jwt/v5 v5.2.1
+	github.com/google/uuid v1.6.0
+	github.com/gorilla/websocket v1.5.3
+	go.uber.org/zap v1.27.0
+)
--- a/services/push-gateway/internal/config/config.go
+++ b/services/push-gateway/internal/config/config.go
@@ -0,0 +1,22 @@
+package config
+
+import "os"
+
+type Config struct {
+	Port      string
+	JWTSecret string
+}
+
+func Load() *Config {
+	return &Config{
+		Port:      getEnv("PUSH_GATEWAY_PORT", "8081"),
+		JWTSecret: getEnv("JWT_SECRET", "p1-dev-secret-change-in-production"),
+	}
+}
+
+func getEnv(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}
--- a/services/push-gateway/internal/hub/hub.go
+++ b/services/push-gateway/internal/hub/hub.go
@@ -0,0 +1,59 @@
+package hub
+
+import (
+	"sync"
+
+	"github.com/gorilla/websocket"
+)
+
+// Hub 管理 WebSocket 客户端连接
+type Hub struct {
+	mu      sync.RWMutex
+	clients map[string]map[*websocket.Conn]bool // userID -> connections
+}
+
+func NewHub() *Hub {
+	return &Hub{
+		clients: make(map[string]map[*websocket.Conn]bool),
+	}
+}
+
+func (h *Hub) Register(userID string, conn *websocket.Conn) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	if h.clients[userID] == nil {
+		h.clients[userID] = make(map[*websocket.Conn]bool)
+	}
+	h.clients[userID][conn] = true
+}
+
+func (h *Hub) Unregister(userID string, conn *websocket.Conn) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	if conns, ok := h.clients[userID]; ok {
+		delete(conns, conn)
+		if len(conns) == 0 {
+			delete(h.clients, userID)
+		}
+	}
+}
+
+// SendToUser 向指定用户的所有连接推送消息
+func (h *Hub) SendToUser(userID string, message []byte) error {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+
+	conns, ok := h.clients[userID]
+	if !ok {
+		return nil
+	}
+
+	for conn := range conns {
+		if err := conn.WriteMessage(websocket.TextMessage, message); err != nil {
+			return err
+		}
+	}
+	return nil
+}
--- a/services/push-gateway/internal/ws/handler.go
+++ b/services/push-gateway/internal/ws/handler.go
@@ -0,0 +1,99 @@
+package ws
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/edu-cloud/push-gateway/internal/hub"
+	"github.com/gin-gonic/gin"
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/gorilla/websocket"
+)
+
+var upgrader = websocket.Upgrader{
+	CheckOrigin: func(r *http.Request) bool {
+		return true // P5 骨架，生产环境需校验 origin
+	},
+}
+
+type Handler struct {
+	hub       *hub.Hub
+	jwtSecret string
+}
+
+func NewHandler(h *hub.Hub, jwtSecret string) *Handler {
+	return &Handler{hub: h, jwtSecret: jwtSecret}
+}
+
+func (h *Handler) HandleWebSocket(c *gin.Context) {
+	// 从 query 参数获取 token（WebSocket 无法设置 Authorization 头）
+	tokenStr := c.Query("token")
+	if tokenStr == "" {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
+		return
+	}
+
+	token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
+		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, jwt.ErrSignatureInvalid
+		}
+		return []byte(h.jwtSecret), nil
+	})
+
+	if err != nil || !token.Valid {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
+		return
+	}
+
+	claims, ok := token.Claims.(jwt.MapClaims)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid claims"})
+		return
+	}
+
+	userID, ok := claims["sub"].(string)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "missing user id"})
+		return
+	}
+
+	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		return
+	}
+	defer conn.Close()
+
+	h.hub.Register(userID, conn)
+	defer h.hub.Unregister(userID, conn)
+
+	// 读取循环（保持连接，处理心跳）
+	for {
+		_, msg, err := conn.ReadMessage()
+		if err != nil {
+			break
+		}
+		// 处理心跳 ping
+		if strings.ToLower(string(msg)) == "ping" {
+			conn.WriteMessage(websocket.TextMessage, []byte("pong"))
+		}
+	}
+}
+
+// PushHandler 接收来自 Msg 服务的推送请求
+func (h *Handler) PushHandler(c *gin.Context) {
+	var req struct {
+		UserID  string `json:"user_id"`
+		Message string `json:"message"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"success": false, "error": gin.H{"code": "INVALID_REQUEST", "message": err.Error()}})
+		return
+	}
+
+	if err := h.hub.SendToUser(req.UserID, []byte(req.Message)); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"success": false, "error": gin.H{"code": "PUSH_FAILED", "message": err.Error()}})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
--- a/services/push-gateway/main.go
+++ b/services/push-gateway/main.go
@@ -0,0 +1,63 @@
+package main
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/edu-cloud/push-gateway/internal/config"
+	"github.com/edu-cloud/push-gateway/internal/hub"
+	"github.com/edu-cloud/push-gateway/internal/ws"
+	"github.com/gin-gonic/gin"
+)
+
+func main() {
+	cfg := config.Load()
+	gin.SetMode(gin.ReleaseMode)
+
+	h := hub.NewHub()
+	wsHandler := ws.NewHandler(h, cfg.JWTSecret)
+
+	r := gin.New()
+	r.Use(gin.Recovery())
+
+	r.GET("/healthz", func(c *gin.Context) {
+		c.JSON(200, gin.H{"status": "ok", "service": "push-gateway"})
+	})
+
+	// WebSocket 升级端点
+	r.GET("/ws", wsHandler.HandleWebSocket)
+
+	// 内部推送 API（Msg 服务调用）
+	api := r.Group("/internal")
+	api.POST("/push", wsHandler.PushHandler)
+
+	srv := &http.Server{
+		Addr:         ":" + cfg.Port,
+		Handler:      r,
+		ReadTimeout:  10 * time.Second,
+		WriteTimeout: 60 * time.Second, // WebSocket 长连接
+	}
+
+	go func() {
+		log.Printf("Push Gateway listening on :%s", cfg.Port)
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			log.Fatalf("listen: %s\n", err)
+		}
+	}()
+
+	quit := make(chan os.Signal, 1)
+	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+	<-quit
+	log.Println("Shutting down Push Gateway...")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := srv.Shutdown(ctx); err != nil {
+		log.Fatal("Server forced to shutdown:", err)
+	}
+}