feat(phase2e-2): media-server Task 0/1/2 落地 + 代码审查修复

本次提交一次性落盘 Phase 2e-2 的 Task 0（PoC Spike）、Task 1（骨架 + Fastify 5 升级）
和 Task 2（9 个内部 REST API + code-reviewer 审查修复），覆盖 media-server 子项目
从零到可用的全部工作。

【Task 0 - PoC Spike】
- media-server/poc/：Node + mediasoup + fastify-websocket + 前端 mediasoup-client
- Playwright 双 tab 自动化验证 2 人会议：4 transports / 4 producers / 4 consumers / RSS 61MB
- media-server/docs/poc-notes.md 归档 7 项关键坑 + 启动步骤 + Task 1/2/9 复用映射
- 锁定技术栈：mediasoup + fastify + mediasoup-client，不改用 livekit-server

【Task 1 - 骨架 + Fastify 5 升级】
- 依赖版本：mediasoup@3.19.0 + fastify@5.8.5 + fastify-plugin@5.1.0
           + @fastify/sensible@6.0.4 + @fastify/websocket@11.2.0
           + pino@9.3.2 + zod@3.23.8
- src 五件套：app.ts / config.ts / utils/logger.ts / mediasoup/worker.ts
             / middlewares/internal-auth.ts
- /healthz + /readyz + /internal/info 三端点实测通过
- X-Internal-Token 鉴权用 timingSafeEqual 防侧信道
- mediasoup Worker died 指数退避自愈通过 kill -9 验证
- 多阶段 Dockerfile：非 root + curl HEALTHCHECK + 暴露 40000-40199 UDP/TCP
- Fastify 4 → 5 升级：loggerInstance: logger 消灭两个 pino 实例

【Task 2 - 9 个内部 REST API + 审查修复】
接口全部挂 /internal/v1/* 前缀，覆盖 Router/Transport/Producer/Consumer 完整生命周期：
- POST /routers, DELETE /routers/:id
- POST /transports, POST /transports/:id/connect
- POST /producers, DELETE /producers/:id
- POST /consumers, POST /consumers/:id/resume, DELETE /consumers/:id

工程特性：
- zod 手动 parse + 全局 errorHandler（不引入 fastify-type-provider-zod 避免
  zod v4 依赖冲突）
- AppError 统一错误码（NOT_FOUND/CONFLICT/CAN_NOT_CONSUME/ROUTER_LIMIT_EXCEEDED
  /MEDIASOUP_ERROR/VALIDATION_ERROR/UNAUTHORIZED/INTERNAL_ERROR）
- 所有资源用 Map + observer.once('close') 自清理，Consumer 监听 producerclose 级联关闭
- Consumer 强制 paused:true 创建，/resume 独立接口
- Transport direction 强约束：recv 拒 produce、send 拒 consume

code-reviewer 子代理审查"有条件通过"，同步修复：
- M1 _clearXxxMap 新增 src/utils/test-guard.ts#assertTestOnly 守卫（生产误调用抛错）
- M2 新增 src/schemas/rtp.ts 对 rtpParameters / rtpCapabilities 做 codecs 浅层校验
  （mimeType/clockRate/payloadType 必填、codecs ≥1），消除 as unknown as 双跳断言
- m1 connectTransport 改乐观锁：先置位再 await，失败回退
- m2 改读 consumer.producerPaused（更符合 mediasoup 语义）
- m3 producerclose 改为 once（风格一致）
- m5 internal-auth 改为反向白名单 PRIVATE_PATH_PREFIXES = ['/internal/']

验证：
- typecheck / lint 0 错误
- vitest：65 passed / 8 spec 文件
- 覆盖率 stmts 82.87% / branches 75.83% / funcs 91.3% / lines 82.87%
- 9 接口 happy path + 6 类错误路径 curl 手测全部按预期返回

【文档同步】
- CURRENT_STATUS.md +232 行：新增 Task 0/1/2 完整记录 + 代码审查修复章节 + 延后清单
- project-context.mdc：Task 0/1/2 状态同步
- phase2e-2-design.md +20 行：Fastify 5 升级相关决策记录
- phase2e-2-implementation.plan.md +117 行：Task 0/1/2 实际产出 + 修复记录

余下 Minor/Nits（m4/m6~m10/n1~n10）登记至 Task 16 收尾清单一次性清扫。

Made-with: Cursor

media-server/src/app.ts

@@ -0,0 +1,145 @@
+import * as mediasoup from 'mediasoup';
+import sensible from '@fastify/sensible';
+import Fastify from 'fastify';
+
+import { config } from './config.js';
+import { registerErrorHandler } from './middlewares/error-handler.js';
+import { internalAuthPlugin } from './middlewares/internal-auth.js';
+import { closeWorker, getWorkerSnapshot, startWorker } from './mediasoup/worker.js';
+import { consumerRoutes } from './routes/consumer.route.js';
+import { producerRoutes } from './routes/producer.route.js';
+import { routerRoutes } from './routes/router.route.js';
+import { transportRoutes } from './routes/transport.route.js';
+import { logger } from './utils/logger.js';
+
+export async function buildApp() {
+  const app = Fastify({
+    loggerInstance: logger,
+    disableRequestLogging: false,
+    trustProxy: false,
+    bodyLimit: 256 * 1024,
+  });
+
+  await app.register(sensible);
+  registerErrorHandler(app);
+
+  app.get('/healthz', async () => {
+    const snapshot = getWorkerSnapshot();
+    return {
+      ok: snapshot.ready,
+      service: 'media-server',
+      mediasoupVersion: mediasoup.version,
+      workerPid: snapshot.pid,
+      workerRestartAttempts: snapshot.restartAttempts,
+      uptimeSec: Math.round(process.uptime()),
+      timestamp: new Date().toISOString(),
+    };
+  });
+
+  app.get('/readyz', async (_request, reply) => {
+    const snapshot = getWorkerSnapshot();
+    if (!snapshot.ready) {
+      reply.code(503);
+      return {
+        ready: false,
+        reason: 'mediasoup worker not ready',
+      };
+    }
+    return { ready: true };
+  });
+
+  await app.register(internalAuthPlugin);
+
+  app.get('/internal/info', async () => {
+    const snapshot = getWorkerSnapshot();
+    return {
+      service: 'media-server',
+      version: '0.1.0',
+      mediasoupVersion: mediasoup.version,
+      worker: snapshot,
+      listen: {
+        ip: config.mediasoup.listenIp,
+        announcedIp: config.mediasoup.announcedIp ?? null,
+        rtcMinPort: config.mediasoup.rtcMinPort,
+        rtcMaxPort: config.mediasoup.rtcMaxPort,
+      },
+    };
+  });
+
+  await app.register(
+    async (scope) => {
+      await scope.register(routerRoutes);
+      await scope.register(transportRoutes);
+      await scope.register(producerRoutes);
+      await scope.register(consumerRoutes);
+    },
+    { prefix: '/internal/v1' },
+  );
+
+  return app;
+}
+
+async function bootstrap(): Promise<void> {
+  const app = await buildApp();
+
+  try {
+    await startWorker();
+  } catch (err) {
+    logger.fatal(
+      { err: err instanceof Error ? err.message : String(err) },
+      'failed to start mediasoup worker, exiting',
+    );
+    process.exit(1);
+  }
+
+  try {
+    await app.listen({ host: config.http.host, port: config.http.port });
+    logger.info(
+      {
+        host: config.http.host,
+        port: config.http.port,
+        env: config.nodeEnv,
+      },
+      'media-server listening',
+    );
+  } catch (err) {
+    logger.fatal(
+      { err: err instanceof Error ? err.message : String(err) },
+      'failed to start HTTP server',
+    );
+    process.exit(1);
+  }
+
+  const shutdown = async (signal: string): Promise<void> => {
+    logger.info({ signal }, 'received shutdown signal');
+    try {
+      await app.close();
+    } catch (err) {
+      logger.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        'error while closing fastify',
+      );
+    }
+    await closeWorker();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => void shutdown('SIGINT'));
+  process.on('SIGTERM', () => void shutdown('SIGTERM'));
+  process.on('unhandledRejection', (reason) => {
+    logger.error({ reason }, 'unhandled promise rejection');
+  });
+  process.on('uncaughtException', (err) => {
+    logger.fatal({ err: err.message, stack: err.stack }, 'uncaught exception');
+    process.exit(1);
+  });
+}
+
+const isEntryPoint =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('app.ts') ||
+  process.argv[1]?.endsWith('app.js');
+
+if (isEntryPoint) {
+  void bootstrap();
+}