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/schemas/common.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+export const idStringSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9:_-]+$/u, 'id must match [A-Za-z0-9:_-]+');
+
+export const roomCodeSchema = z
+  .string()
+  .min(3)
+  .max(64)
+  .regex(/^[A-Z0-9-]+$/u, 'roomCode must match [A-Z0-9-]+ (uppercased)');
+
+export const userIdSchema = z
+  .union([z.string().min(1).max(64), z.number().int().positive()])
+  .transform((val) => String(val));
+
+export const okResponseSchema = z.object({
+  ok: z.literal(true),
+});
+
+export type OkResponse = z.infer<typeof okResponseSchema>;

media-server/src/schemas/consumer.schema.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+import { idStringSchema } from './common.js';
+import { rtpCapabilitiesSchema } from './rtp.js';
+
+export const createConsumerBodySchema = z.object({
+  routerId: idStringSchema,
+  transportId: idStringSchema,
+  producerId: idStringSchema,
+  rtpCapabilities: rtpCapabilitiesSchema,
+});
+
+export const consumerIdParamSchema = z.object({
+  id: idStringSchema,
+});
+
+export type CreateConsumerBody = z.infer<typeof createConsumerBodySchema>;
+export type ConsumerIdParam = z.infer<typeof consumerIdParamSchema>;

media-server/src/schemas/producer.schema.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+import { idStringSchema } from './common.js';
+import { rtpParametersSchema } from './rtp.js';
+
+export const mediaKindSchema = z.enum(['audio', 'video']);
+
+export const createProducerBodySchema = z.object({
+  transportId: idStringSchema,
+  kind: mediaKindSchema,
+  rtpParameters: rtpParametersSchema,
+  appData: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const producerIdParamSchema = z.object({
+  id: idStringSchema,
+});
+
+export type CreateProducerBody = z.infer<typeof createProducerBodySchema>;
+export type ProducerIdParam = z.infer<typeof producerIdParamSchema>;
+export type MediaKind = z.infer<typeof mediaKindSchema>;

media-server/src/schemas/router.schema.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+import { idStringSchema, roomCodeSchema } from './common.js';
+
+export const createRouterBodySchema = z.object({
+  roomCode: roomCodeSchema,
+});
+
+export const routerIdParamSchema = z.object({
+  routerId: idStringSchema,
+});
+
+export type CreateRouterBody = z.infer<typeof createRouterBodySchema>;
+export type RouterIdParam = z.infer<typeof routerIdParamSchema>;

media-server/src/schemas/rtp.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+
+/**
+ * 对 mediasoup 的 RtpParameters / RtpCapabilities 做"浅层存在性校验"。
+ *
+ * 不校验完整结构（交给 mediasoup native 层做严格校验），但至少保证：
+ *   - 必填字段存在
+ *   - codecs 至少 1 项
+ *   - 客户端传入 {} / null / 空数组 等明显错误 → 返回 400 VALIDATION_ERROR
+ *
+ * 通过 .passthrough() 保留未知字段向后兼容。
+ */
+
+const rtcpFeedbackSchema = z
+  .object({
+    type: z.string(),
+    parameter: z.string().optional(),
+  })
+  .passthrough();
+
+const baseCodecSchema = z
+  .object({
+    mimeType: z.string().min(1),
+    clockRate: z.number().int().positive(),
+    channels: z.number().int().positive().optional(),
+    parameters: z.record(z.string(), z.unknown()).optional(),
+    rtcpFeedback: z.array(rtcpFeedbackSchema).optional(),
+  })
+  .passthrough();
+
+const rtpParametersCodecSchema = baseCodecSchema.extend({
+  payloadType: z.number().int().min(0).max(255),
+});
+
+const rtpCapabilitiesCodecSchema = baseCodecSchema.extend({
+  kind: z.enum(['audio', 'video']).optional(),
+  preferredPayloadType: z.number().int().min(0).max(255).optional(),
+});
+
+const rtpHeaderExtensionParameterSchema = z
+  .object({
+    uri: z.string().min(1),
+    id: z.number().int().min(0),
+    encrypt: z.boolean().optional(),
+    parameters: z.record(z.string(), z.unknown()).optional(),
+  })
+  .passthrough();
+
+const rtpEncodingParametersSchema = z
+  .object({
+    ssrc: z.number().int().nonnegative().optional(),
+    rid: z.string().optional(),
+    scalabilityMode: z.string().optional(),
+    maxBitrate: z.number().int().nonnegative().optional(),
+  })
+  .passthrough();
+
+export const rtpParametersSchema = z
+  .object({
+    mid: z.string().optional(),
+    codecs: z.array(rtpParametersCodecSchema).min(1, 'rtpParameters.codecs must not be empty'),
+    headerExtensions: z.array(rtpHeaderExtensionParameterSchema).optional(),
+    encodings: z.array(rtpEncodingParametersSchema).optional(),
+    rtcp: z
+      .object({
+        cname: z.string().optional(),
+        reducedSize: z.boolean().optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+export const rtpCapabilitiesSchema = z
+  .object({
+    codecs: z
+      .array(rtpCapabilitiesCodecSchema)
+      .min(1, 'rtpCapabilities.codecs must not be empty'),
+    headerExtensions: z.array(z.unknown()).optional(),
+  })
+  .passthrough();
+
+export type RtpParametersInput = z.infer<typeof rtpParametersSchema>;
+export type RtpCapabilitiesInput = z.infer<typeof rtpCapabilitiesSchema>;

media-server/src/schemas/transport.schema.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+import { idStringSchema, userIdSchema } from './common.js';
+
+export const transportDirectionSchema = z.enum(['send', 'recv']);
+
+export const createTransportBodySchema = z.object({
+  routerId: idStringSchema,
+  userId: userIdSchema,
+  direction: transportDirectionSchema,
+});
+
+export const transportIdParamSchema = z.object({
+  id: idStringSchema,
+});
+
+const dtlsFingerprintSchema = z.object({
+  algorithm: z.enum([
+    'sha-1',
+    'sha-224',
+    'sha-256',
+    'sha-384',
+    'sha-512',
+  ]),
+  value: z.string().min(1),
+});
+
+const dtlsParametersSchema = z.object({
+  role: z.enum(['auto', 'client', 'server']).optional(),
+  fingerprints: z.array(dtlsFingerprintSchema).min(1),
+});
+
+export const connectTransportBodySchema = z.object({
+  dtlsParameters: dtlsParametersSchema,
+});
+
+export type CreateTransportBody = z.infer<typeof createTransportBodySchema>;
+export type TransportIdParam = z.infer<typeof transportIdParamSchema>;
+export type ConnectTransportBody = z.infer<typeof connectTransportBodySchema>;
+export type TransportDirection = z.infer<typeof transportDirectionSchema>;