feat: auto committed

docs/troubleshooting/known-issues.md

@@ -373,15 +373,30 @@
 | DEV_MODE 鉴权    | DEV_MODE=true 时接受 dev-token，生产环境必须 JWT 校验            |
 | 广播端点         | POST /internal/broadcast，body {event, data}，调用 hub.Broadcast |
 
-### 2.9 ai-gateway（Python/FastAPI，P5）
+### 2.9 ai（Python/FastAPI，P5）
 
-| 场景              | 技术/规则                                                       |
-| ----------------- | --------------------------------------------------------------- |
-| LLM Provider 适配 | OpenAI 兼容 REST API（httpx 异步），不引入 openai SDK           |
-| 降级模式          | API key 为空或调用失败时返回骨架响应，标记 degraded: true       |
-| 流式 SSE          | AI 网关 → BFF → 前端三层透传，BFF 不缓冲                        |
-| 路由前缀          | 业务路由加 /ai 前缀（APIRouter prefix="/ai"），Gateway 代理 /ai |
-| dev_mode tracer   | dev_mode=true 时跳过 OTel exporter 初始化                       |
+| 场景                          | 技术/规则                                                                                                          |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| LLM Provider 适配             | 4 适配器（OpenAI/Anthropic/Baichuan/Ollama）+ ProviderFailoverChain + CircuitBreaker（3 次失败 60s 熔断）          |
+| 降级模式方案 B                 | success=true + error=null + data 内 degraded=true + degraded_reason（总裁 §2.6，非顶层 degraded 字段）             |
+| ActionState 信封              | 所有 HTTP 响应统一 `{success, data, error:{code,message,details?,traceId?}}`（004 §11.5 强制）                     |
+| 路由前缀                      | /v1/ai 前缀（APIRouter prefix="/v1/ai"），Gateway 代理 /api/v1/ai/* → /v1/ai/*                                     |
+| gRPC server                   | grpc.aio 端口 50058，8 RPC + 3 interceptor（Logging/Auth/Error）                                                   |
+| 评估三道防线                  | RuleValidator（JSON/字段/难度校验）→ LLMJudge（语义评分）→ QualityGate（综合决策门控）                             |
+| 备课工作流                    | P5 用 asyncio.create_task + Redis 状态存储（24h TTL），P6+ 评估 Temporal                                           |
+| 工作流状态机                  | pending→analyzing→generating→pending_review→persisted/failed，生成失败重试最多 3 次                               |
+| 限流三维度                    | user 10/min + IP 30/min + school 100/min，Redis Lua 原子令牌桶，Redis 不可用降级放行                               |
+| 用量记录                      | Redis INCRBY 按 user/school/month 维度，35 天过期；Kafka 发布 AIUsageEvent 到 edu.ai.usage topic                   |
+| Kafka 派生数据豁免 Outbox     | AIUsageEvent 为派生数据，004 §12.2 豁免 Outbox，直接 aiokafka producer（事务性 + 幂等）                             |
+| 安全层全本地                  | PIIRedactor（5 类 PII 正则脱敏）+ InputSanitizer（prompt injection 检测）+ OutputModerator（5 类敏感内容审核）      |
+| 六边形架构端口模式            | ContentClient/DataAnaClient/IamClient 均为抽象接口 + Mock + gRPC 实现，全并行模式用 Mock                           |
+| 权限校验                      | PermissionGuard 5 权限点（ai:chat / ai:question:generate / ai:expression:optimize / ai:lesson:generate / confirm） |
+| dev_mode tracer               | dev_mode=true 时跳过 OTel exporter 初始化 + 跳过权限校验                                                           |
+| proto 包名                    | 保持 `next_edu_cloud.<domain>.v1`（coord G17 裁决覆盖 project_rules §5）                                           |
+| proto_gen 排除 ruff            | pyproject.toml `[tool.ruff] exclude = ["src/ai/proto_gen"]`，自动生成文件不参与 lint                               |
+| ruff UP017                    | `datetime.now(timezone.utc)` 改用 `datetime.now(datetime.UTC)` 别名（Python 3.12+）                                |
+| ruff SIM103/SIM110            | `if x: return False; return True` 改 `return not x`；for 循环改 `all()` 表达式                                     |
+| PowerShell 不支持 &&          | RunCommand 用 cwd 参数指定工作目录，不用 `cd ... && uv run`                                                        |
 
 ### 2.10 shared-proto（契约包）