feat(iam): 角色权限管理 + 权限缓存 + 指标 + 鉴权中间件增强 + nextstep 文档

services/iam/src/middleware/auth.middleware.ts

@@ -15,6 +15,42 @@ export interface AuthenticatedRequest extends Request {
   userDataScope?: string;
 }
 
+/**
+ * 审计上下文：从 HTTP 请求头中提取的客户端信息（president §5.5）.
+ * ip: 客户端 IP（X-Forwarded-For 首个 IP）
+ * userAgent: User-Agent
+ * traceId: 链路追踪 ID（X-Request-Id / X-Trace-Id）
+ */
+export interface AuditContext {
+  ip?: string | null;
+  userAgent?: string | null;
+  traceId?: string | null;
+}
+
+/**
+ * 从 Express Request 中提取审计上下文（ip / userAgent / traceId）.
+ * 供 Controller 调用并传递给 Service 的审计日志方法.
+ */
+export function extractAuditContext(req: Request): AuditContext {
+  const forwardedFor = req.headers["x-forwarded-for"];
+  const ip =
+    (typeof forwardedFor === "string"
+      ? forwardedFor.split(",")[0]?.trim()
+      : undefined) ??
+    req.ip ??
+    null;
+  const userAgentHeader = req.headers["user-agent"];
+  const userAgent =
+    typeof userAgentHeader === "string" ? userAgentHeader : null;
+  const requestIdHeader = req.headers["x-request-id"];
+  const traceIdHeader = req.headers["x-trace-id"];
+  const traceId =
+    (typeof requestIdHeader === "string" && requestIdHeader) ||
+    (typeof traceIdHeader === "string" && traceIdHeader) ||
+    null;
+  return { ip, userAgent, traceId };
+}
+
 @Injectable()
 export class AuthMiddleware implements NestMiddleware {
   use(req: AuthenticatedRequest, _res: Response, next: NextFunction): void {