# V11 AI Readiness 事件说明

本文件说明 AI 层（Tuner/Safe）在 v11 中的就绪事件上报约定，以及与 Boot 层的协作关系。

## 统一事件
- 事件名：`module.state.changed`
- 载荷：
  - `module`: 模块名（如 `ai.tuner`、`ai.safe`、`startup`、`cache`、`auth`、`rbac`、`queue`、`lang`、`metrics`）
  - `previousState`: 之前状态（通常为 `initializing`）
  - `currentState`: 当前状态（`ready` 或 `unavailable`）
  - `meta`: 可选扩展（如 `{ enabled: true }`）

## AI 层模块
### ai.tuner
- 入口：`libs/wwjcloud-ai/src/tuner/services/tuner-ready.service.ts`
- 触发时机：`OnModuleInit`
- 依赖组件：`PerformanceAnalyzer`、`ResourceMonitor`、`CacheOptimizer`、`QueryOptimizer`
- 环境开关：`AI_TUNER_ENABLED`（默认 `true`）
- 判定逻辑：
  - 当开关启用且核心组件均成功注入 → `ready`
  - 当开关启用但组件缺失/异常 → `unavailable`
  - 当开关关闭 → `unavailable`

### ai.safe
- 入口：`libs/wwjcloud-ai/src/safe/services/safe-ready.service.ts`
- 触发时机：`OnModuleInit`
- 依赖组件：`SecurityAnalyzer`、`VulnerabilityDetector`、`AccessProtector`、`AiSecurityService`
- 环境开关：`AI_SAFE_ENABLED`（默认 `true`）
- 判定逻辑：
  - 当开关启用且核心组件均成功注入 → `ready`
  - 当开关启用但组件缺失/异常 → `unavailable`
  - 当开关关闭 → `unavailable`

## Boot 层（参考）
- `startup`：`StartupValidatorService` 在初始化时生成启动报告，并基于 `NODE_ENV` 是否缺失和 `Redis` 连接状态上报 `ready/unavailable`。
- `cache`：`CacheReadyService` 在 Redis 禁用时回退为 `ready`，启用时根据 `PING` 成功与否上报状态。
- `auth/rbac`：`AuthReadyService` 基于 `AUTH_ENABLED` 与 `RBAC_ENABLED` 分别上报 `ready/unavailable`。
- `queue`：`QueueReadyService` 依据 `QUEUE_ENABLED` 与驱动类型（`bullmq/kafka` → `ready`，未知 → `unavailable`）。
- `lang`、`metrics`：分别在初始化时根据语言目录存在与 `PROMETHEUS_ENABLED` 开关上报状态。

## 测试覆盖
- 位置：`src/ai-layer/*.spec.ts`、`src/boot-layer/*.spec.ts`
- 已覆盖用例：
  - AI：`tuner-ready.service`、`safe-ready.service` 启用/禁用、缺失组件场景
  - Boot：`startup`、`cache`、`auth/rbac`、`queue` 等常见启用/禁用与依赖失败场景

## 约定与扩展
- 所有模块应在 `OnModuleInit` 或初始化阶段发出首次状态，用于协调器与观测层消费。
- 新增模块应复用 `module.state.changed` 事件，保持载荷格式一致性，必要时在 `meta` 补充上下文。