fix: code compliance audit and fix across all services

NestJS (6 services): implement @RequirePermission decorator with
SetMetadata+Reflector, register APP_GUARD globally, fix as assertions
to type guards, add explicit return types, fix import type for express,
fix /metrics implicit any, replace native Error with ApplicationError,
remove typeorm remnants, register LifecycleService.

teacher-bff: add logger, ApplicationError, GlobalErrorFilter, forward
real userId to downstream, log downstream failures, migrate health
controller to shared/health.

Go (2 services): interface to any, doc comments, CORS dev whitelist,
JWT secret fail-fast, push-gateway internal API auth, metrics and
readyz endpoints, remove dead code.

Python (2 services): lifespan return type, dev_mode to bool, data-ana
APIRouter, ai POST body model, ClickHouse async wrapping.

services/teacher-bff/src/app.module.ts

@@ -1,9 +1,8 @@
 import { Module } from "@nestjs/common";
 import { TeacherModule } from "./teacher/teacher.module.js";
-import { HealthController } from "./health.controller.js";
+import { HealthModule } from "./shared/health/health.module.js";
 
 @Module({
-  imports: [TeacherModule],
-  controllers: [HealthController],
+  imports: [TeacherModule, HealthModule],
 })
 export class AppModule {}

services/teacher-bff/src/main.ts

@@ -1,26 +1,31 @@
 import "reflect-metadata";
 import { NestFactory } from "@nestjs/core";
 import { AppModule } from "./app.module.js";
-import { env } from "./config/env.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";
+import { env } from "./config/env.js";
 import { metricsRegistry } from "./shared/observability/metrics.js";
+import type { Request, Response } from "express";
 
 async function bootstrap(): Promise<void> {
   initTracer();
+
   const app = await NestFactory.create(AppModule, {
     logger: ["log", "error", "warn"],
   });
 
+  app.useGlobalFilters(new GlobalErrorFilter());
   app.enableShutdownHooks();
 
   // Prometheus 指标端点：不鉴权，供 Prometheus 抓取。
-  app.getHttpAdapter().get("/metrics", async (_req, res) => {
+  app.getHttpAdapter().get("/metrics", async (_req: Request, res: Response) => {
     res.set("Content-Type", metricsRegistry.contentType);
     res.end(await metricsRegistry.metrics());
   });
 
   await app.listen(env.PORT);
-  console.log(`Teacher BFF started on port ${env.PORT}`);
+  logger.info({ port: env.PORT }, "Teacher BFF started");
 
   process.on("SIGTERM", async () => {
     await app.close();
@@ -29,6 +34,6 @@ async function bootstrap(): Promise<void> {
 }
 
 bootstrap().catch((err: unknown) => {
-  console.error("Failed to start Teacher BFF", err);
+  logger.error({ err }, "Failed to start Teacher BFF");
   process.exit(1);
 });

services/teacher-bff/src/shared/errors/application-error.ts

@@ -0,0 +1,118 @@
+export type ErrorType =
+  | "validation"
+  | "not_found"
+  | "permission_denied"
+  | "unauthorized"
+  | "conflict"
+  | "business"
+  | "database"
+  | "bad_gateway"
+  | "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;
+  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, "TEACHER_BFF_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}`, "TEACHER_BFF_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}`, "TEACHER_BFF_PERMISSION_DENIED", {
+      permission,
+    });
+  }
+}
+
+export class UnauthorizedError extends ApplicationError {
+  readonly type = "unauthorized" as const;
+  readonly statusCode = 401;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, "TEACHER_BFF_UNAUTHORIZED", details);
+  }
+}
+
+export class ConflictError extends ApplicationError {
+  readonly type = "conflict" as const;
+  readonly statusCode = 409;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, "TEACHER_BFF_CONFLICT", details);
+  }
+}
+
+export class BusinessError extends ApplicationError {
+  readonly type = "business" as const;
+  readonly statusCode = 422;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, "TEACHER_BFF_BUSINESS_ERROR", details);
+  }
+}
+
+export class DatabaseError extends ApplicationError {
+  readonly type = "database" as const;
+  readonly statusCode = 500;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, "TEACHER_BFF_DATABASE_ERROR", details);
+  }
+}
+
+export class BadGatewayError extends ApplicationError {
+  readonly type = "bad_gateway" as const;
+  readonly statusCode = 502;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, "TEACHER_BFF_BAD_GATEWAY", details);
+  }
+}
+
+export class InternalError extends ApplicationError {
+  readonly type = "internal" as const;
+  readonly statusCode = 500;
+  constructor(message: string, details?: ErrorDetails) {
+    super(message, "TEACHER_BFF_INTERNAL_ERROR", details);
+  }
+}

services/teacher-bff/src/shared/errors/global-error.filter.ts

@@ -0,0 +1,87 @@
+import {
+  Catch,
+  ExceptionFilter,
+  ArgumentsHost,
+  HttpException,
+  Logger,
+} from "@nestjs/common";
+import type { 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 traceIdHeader = request.headers["x-request-id"];
+    const traceId =
+      typeof traceIdHeader === "string" ? traceIdHeader : "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) {
+      statusCode = 400;
+      body = {
+        success: false,
+        error: {
+          code: "TEACHER_BFF_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;
+  }
+}

services/teacher-bff/src/shared/health/health.controller.ts

@@ -1,10 +1,12 @@
 import { Controller, Get } from "@nestjs/common";
 
+const SERVICE_NAME = "teacher-bff";
+
 /**
  * 健康检查端点。
  *
- * - GET /healthz：liveness，仅返回进程存活
- * - GET /readyz：readiness，无外部依赖可直接返回 ok
+ * - GET /healthz：liveness，仅返回进程存活。
+ * - GET /readyz：readiness，BFF 不直接访问 DB，可直接返回 ok。
  *
  * 不需要鉴权，必须在路由白名单中放行。
  */
@@ -14,7 +16,7 @@ export class HealthController {
   liveness(): { status: string; service: string; timestamp: string } {
     return {
       status: "ok",
-      service: "teacher-bff",
+      service: SERVICE_NAME,
       timestamp: new Date().toISOString(),
     };
   }
@@ -23,7 +25,7 @@ export class HealthController {
   readiness(): { status: string; service: string; timestamp: string } {
     return {
       status: "ok",
-      service: "teacher-bff",
+      service: SERVICE_NAME,
       timestamp: new Date().toISOString(),
     };
   }

services/teacher-bff/src/shared/health/health.module.ts

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common";
+import { HealthController } from "./health.controller.js";
+
+@Module({
+  controllers: [HealthController],
+})
+export class HealthModule {}

services/teacher-bff/src/shared/observability/logger.ts

@@ -0,0 +1,19 @@
+import pino from "pino";
+import { env } from "../../config/env.js";
+
+export const logger = pino({
+  level: env.LOG_LEVEL,
+  base: {
+    service: "teacher-bff",
+    version: "0.1.0",
+  },
+  transport:
+    env.NODE_ENV === "development"
+      ? {
+          target: "pino-pretty",
+          options: { colorize: true },
+        }
+      : undefined,
+});
+
+export type Logger = typeof logger;

services/teacher-bff/src/teacher/teacher.controller.ts

@@ -1,55 +1,70 @@
-import {
-  Controller,
-  Get,
-  Param,
-  Req,
-  UnauthorizedException,
-} from "@nestjs/common";
+import { Controller, Get, Param, Req } from "@nestjs/common";
 import type { Request } from "express";
 import { TeacherService } from "./teacher.service.js";
+import { UnauthorizedError } from "../shared/errors/application-error.js";
+
+interface SuccessResponse<T> {
+  success: true;
+  data: T;
+}
 
 @Controller("teacher")
 export class TeacherController {
   constructor(private readonly service: TeacherService) {}
 
   @Get("dashboard")
-  async dashboard(@Req() req: Request) {
-    const userId = req.headers["x-user-id"] as string;
-    if (!userId) {
-      throw new UnauthorizedException("Missing x-user-id header");
-    }
+  async dashboard(@Req() req: Request): Promise<SuccessResponse<unknown>> {
+    const userId = this.extractUserId(req);
     const data = await this.service.getDashboard(userId);
     return { success: true as const, data };
   }
 
   @Get("viewports")
-  async viewports(@Req() req: Request) {
-    const userId = req.headers["x-user-id"] as string;
-    if (!userId) {
-      throw new UnauthorizedException("Missing x-user-id header");
-    }
+  async viewports(@Req() req: Request): Promise<SuccessResponse<unknown>> {
+    const userId = this.extractUserId(req);
     const data = await this.service.getViewports(userId);
     return { success: true as const, data };
   }
 
   // 聚合：班级下的考试列表（core-edu）
   @Get("classes/:classId/exams")
-  async listExamsByClass(@Param("classId") classId: string) {
-    const data = await this.service.listExamsByClass(classId);
+  async listExamsByClass(
+    @Req() req: Request,
+    @Param("classId") classId: string,
+  ): Promise<SuccessResponse<unknown>> {
+    const userId = this.extractUserId(req);
+    const data = await this.service.listExamsByClass(userId, classId);
     return { success: true as const, data };
   }
 
   // 聚合：班级下的作业列表（core-edu）
   @Get("classes/:classId/homework")
-  async listHomeworkByClass(@Param("classId") classId: string) {
-    const data = await this.service.listHomeworkByClass(classId);
+  async listHomeworkByClass(
+    @Req() req: Request,
+    @Param("classId") classId: string,
+  ): Promise<SuccessResponse<unknown>> {
+    const userId = this.extractUserId(req);
+    const data = await this.service.listHomeworkByClass(userId, classId);
     return { success: true as const, data };
   }
 
   // 聚合：考试下的成绩列表（core-edu）
   @Get("exams/:examId/grades")
-  async listGradesByExam(@Param("examId") examId: string) {
-    const data = await this.service.listGradesByExam(examId);
+  async listGradesByExam(
+    @Req() req: Request,
+    @Param("examId") examId: string,
+  ): Promise<SuccessResponse<unknown>> {
+    const userId = this.extractUserId(req);
+    const data = await this.service.listGradesByExam(userId, examId);
     return { success: true as const, data };
   }
+
+  private extractUserId(req: Request): string {
+    const header = req.headers["x-user-id"];
+    const userId = typeof header === "string" ? header : undefined;
+    if (!userId) {
+      throw new UnauthorizedError("Missing x-user-id header");
+    }
+    return userId;
+  }
 }

services/teacher-bff/src/teacher/teacher.service.ts

@@ -1,5 +1,7 @@
 import { Injectable } from "@nestjs/common";
 import { env } from "../config/env.js";
+import { logger } from "../shared/observability/logger.js";
+import { BadGatewayError } from "../shared/errors/application-error.js";
 
 export interface ViewportItem {
   key: string;
@@ -10,13 +12,20 @@ export interface ViewportItem {
   requiredPermission: string | null;
 }
 
+interface DownstreamEnvelope<T> {
+  success: boolean;
+  data?: T;
+}
+
+interface DashboardData {
+  user: unknown;
+  classes: unknown;
+}
+
 @Injectable()
 export class TeacherService {
   // 聚合 IAM + classes 服务的数据
-  async getDashboard(userId: string): Promise<{
-    user: unknown;
-    classes: unknown;
-  }> {
+  async getDashboard(userId: string): Promise<DashboardData> {
     const [iamRes, classesRes] = await Promise.allSettled([
       fetch(`${env.IamServiceUrl}/iam/me`, {
         headers: { "x-user-id": userId },
@@ -26,13 +35,42 @@ export class TeacherService {
       }),
     ]);
 
-    return {
-      user: iamRes.status === "fulfilled" ? await iamRes.value.json() : null,
-      classes:
-        classesRes.status === "fulfilled"
-          ? await classesRes.value.json()
-          : null,
-    };
+    let user: unknown = null;
+    let classes: unknown = null;
+
+    if (iamRes.status === "fulfilled") {
+      if (iamRes.value.ok) {
+        user = await iamRes.value.json();
+      } else {
+        logger.warn(
+          { status: iamRes.value.status, url: iamRes.value.url },
+          "Downstream IAM service call failed",
+        );
+      }
+    } else {
+      logger.warn(
+        { err: iamRes.reason, service: "iam" },
+        "Downstream IAM service call rejected",
+      );
+    }
+
+    if (classesRes.status === "fulfilled") {
+      if (classesRes.value.ok) {
+        classes = await classesRes.value.json();
+      } else {
+        logger.warn(
+          { status: classesRes.value.status, url: classesRes.value.url },
+          "Downstream classes service call failed",
+        );
+      }
+    } else {
+      logger.warn(
+        { err: classesRes.reason, service: "classes" },
+        "Downstream classes service call rejected",
+      );
+    }
+
+    return { user, classes };
   }
 
   // 聚合 IAM 视口配置（L1 导航）
@@ -41,51 +79,80 @@ export class TeacherService {
       headers: { "x-user-id": userId },
     });
     if (!res.ok) {
-      return [];
+      logger.warn(
+        { status: res.status, url: res.url },
+        "Downstream IAM service call failed",
+      );
+      throw new BadGatewayError(`Downstream service returned ${res.status}`, {
+        service: "iam",
+        endpoint: "viewports",
+        status: res.status,
+      });
     }
-    const json = (await res.json()) as {
-      success: boolean;
-      data?: ViewportItem[];
-    };
+    const json = (await res.json()) as DownstreamEnvelope<ViewportItem[]>;
     return json.data ?? [];
   }
 
   // 聚合班级下的考试列表（core-edu）
-  async listExamsByClass(classId: string): Promise<unknown> {
+  async listExamsByClass(userId: string, classId: string): Promise<unknown> {
     const res = await fetch(
       `${env.CoreEduServiceUrl}/exams/class/${encodeURIComponent(classId)}`,
-      { headers: { "x-user-id": "bff" } },
+      { headers: { "x-user-id": userId } },
     );
     if (!res.ok) {
-      return [];
+      logger.warn(
+        { status: res.status, url: res.url },
+        "Downstream core-edu service call failed",
+      );
+      throw new BadGatewayError(`Downstream service returned ${res.status}`, {
+        service: "core-edu",
+        endpoint: "exams-by-class",
+        status: res.status,
+      });
     }
-    const json = (await res.json()) as { success: boolean; data?: unknown };
+    const json = (await res.json()) as DownstreamEnvelope<unknown>;
     return json.data ?? [];
   }
 
   // 聚合班级下的作业列表（core-edu）
-  async listHomeworkByClass(classId: string): Promise<unknown> {
+  async listHomeworkByClass(userId: string, classId: string): Promise<unknown> {
     const res = await fetch(
       `${env.CoreEduServiceUrl}/homework/class/${encodeURIComponent(classId)}`,
-      { headers: { "x-user-id": "bff" } },
+      { headers: { "x-user-id": userId } },
     );
     if (!res.ok) {
-      return [];
+      logger.warn(
+        { status: res.status, url: res.url },
+        "Downstream core-edu service call failed",
+      );
+      throw new BadGatewayError(`Downstream service returned ${res.status}`, {
+        service: "core-edu",
+        endpoint: "homework-by-class",
+        status: res.status,
+      });
     }
-    const json = (await res.json()) as { success: boolean; data?: unknown };
+    const json = (await res.json()) as DownstreamEnvelope<unknown>;
     return json.data ?? [];
   }
 
   // 聚合考试下的成绩列表（core-edu）
-  async listGradesByExam(examId: string): Promise<unknown> {
+  async listGradesByExam(userId: string, examId: string): Promise<unknown> {
     const res = await fetch(
       `${env.CoreEduServiceUrl}/grades/exam/${encodeURIComponent(examId)}`,
-      { headers: { "x-user-id": "bff" } },
+      { headers: { "x-user-id": userId } },
     );
     if (!res.ok) {
-      return [];
+      logger.warn(
+        { status: res.status, url: res.url },
+        "Downstream core-edu service call failed",
+      );
+      throw new BadGatewayError(`Downstream service returned ${res.status}`, {
+        service: "core-edu",
+        endpoint: "grades-by-exam",
+        status: res.status,
+      });
     }
-    const json = (await res.json()) as { success: boolean; data?: unknown };
+    const json = (await res.json()) as DownstreamEnvelope<unknown>;
     return json.data ?? [];
   }
 }