xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docs): known-issues ai 模块经验更新（9 RPC + 6 权限点 + 2 新经验）

Browse Source 
gRPC server 8→9 RPC（新增 GenerateReport）

PermissionGuard 5→6 权限点（新增 ai:report:generate）

新增经验：Markdown 章节关键词提取 + main.py 模块级变量顺序
This commit is contained in:
SpecialX
2026-07-14 23:02:01 +08:00
parent 765f7da4c0
commit f212ba0813
1 changed files with 24 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/troubleshooting/known-issues.md
View File

@@ -444,28 +444,30 @@
### 2.9 ai（Python/FastAPI，P5） ### 2.9 ai（Python/FastAPI，P5）
| 场景 | 技术/规则 | | 场景 | 技术/规则 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| LLM Provider 适配 | 4 适配器（OpenAI/Anthropic/Baichuan/Ollama）+ ProviderFailoverChain + CircuitBreaker（3 次失败 60s 熔断） | | LLM Provider 适配 | 4 适配器（OpenAI/Anthropic/Baichuan/Ollama）+ ProviderFailoverChain + CircuitBreaker（3 次失败 60s 熔断） |
| 降级模式方案 B | success=true + error=null + data 内 degraded=true + degraded_reason（总裁 §2.6，非顶层 degraded 字段） | | 降级模式方案 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 强制） | | ActionState 信封 | 所有 HTTP 响应统一 `{success, data, error:{code,message,details?,traceId?}}`（004 §11.5 强制） |
| 路由前缀 | /v1/ai 前缀（APIRouter prefix="/v1/ai"），Gateway 代理 /api/v1/ai/* → /v1/ai/* | | 路由前缀 | /v1/ai 前缀（APIRouter prefix="/v1/ai"），Gateway 代理 /api/v1/ai/* → /v1/ai/* |
| gRPC server | grpc.aio 端口 50058，8 RPC + 3 interceptor（Logging/Auth/Error） | | gRPC server | grpc.aio 端口 50058，9 RPC + 3 interceptor（Logging/Auth/Error） |
| 评估三道防线 | RuleValidator（JSON/字段/难度校验）→ LLMJudge（语义评分）→ QualityGate（综合决策门控） | | 评估三道防线 | RuleValidator（JSON/字段/难度校验）→ LLMJudge（语义评分）→ QualityGate（综合决策门控） |
| 备课工作流 | P5 用 asyncio.create_task + Redis 状态存储（24h TTL），P6+ 评估 Temporal | | 备课工作流 | P5 用 asyncio.create_task + Redis 状态存储（24h TTL），P6+ 评估 Temporal |
| 工作流状态机 | pending→analyzing→generating→pending_review→persisted/failed，生成失败重试最多 3 次 | | 工作流状态机 | pending→analyzing→generating→pending_review→persisted/failed，生成失败重试最多 3 次 |
| 限流三维度 | user 10/min + IP 30/min + school 100/min，Redis Lua 原子令牌桶，Redis 不可用降级放行 | | 限流三维度 | user 10/min + IP 30/min + school 100/min，Redis Lua 原子令牌桶，Redis 不可用降级放行 |
| 用量记录 | Redis INCRBY 按 user/school/month 维度，35 天过期；Kafka 发布 AIUsageEvent 到 edu.ai.usage topic | | 用量记录 | Redis INCRBY 按 user/school/month 维度，35 天过期；Kafka 发布 AIUsageEvent 到 edu.ai.usage topic |
| Kafka 派生数据豁免 Outbox | AIUsageEvent 为派生数据，004 §12.2 豁免 Outbox，直接 aiokafka producer（事务性 + 幂等） | | Kafka 派生数据豁免 Outbox | AIUsageEvent 为派生数据，004 §12.2 豁免 Outbox，直接 aiokafka producer（事务性 + 幂等） |
| 安全层全本地 | PIIRedactor（5 类 PII 正则脱敏）+ InputSanitizer（prompt injection 检测）+ OutputModerator（5 类敏感内容审核） | | 安全层全本地 | PIIRedactor（5 类 PII 正则脱敏）+ InputSanitizer（prompt injection 检测）+ OutputModerator（5 类敏感内容审核） |
| 六边形架构端口模式 | ContentClient/DataAnaClient/IamClient 均为抽象接口 + Mock + gRPC 实现，全并行模式用 Mock | | 六边形架构端口模式 | ContentClient/DataAnaClient/IamClient 均为抽象接口 + Mock + gRPC 实现，全并行模式用 Mock |
| 权限校验 | PermissionGuard 5 权限点（ai:chat / ai:question:generate / ai:expression:optimize / ai:lesson:generate / confirm） | | 权限校验 | PermissionGuard 6 权限点（ai:chat / ai:question:generate / ai:expression:optimize / ai:lesson:generate / confirm / ai:report:generate） |
| dev_mode tracer | dev_mode=true 时跳过 OTel exporter 初始化 + 跳过权限校验 | | dev_mode tracer | dev_mode=true 时跳过 OTel exporter 初始化 + 跳过权限校验 |
| proto 包名 | 保持 `next_edu_cloud.<domain>.v1`（coord G17 裁决覆盖 project_rules §5） | | proto 包名 | 保持 `next_edu_cloud.<domain>.v1`（coord G17 裁决覆盖 project_rules §5） |
| proto_gen 排除 ruff | pyproject.toml `[tool.ruff] exclude = ["src/ai/proto_gen"]`，自动生成文件不参与 lint | | 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 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()` 表达式 | | ruff SIM103/SIM110 | `if x: return False; return True` 改 `return not x`；for 循环改 `all()` 表达式 |
| PowerShell 不支持 && | RunCommand 用 cwd 参数指定工作目录，不用 `cd ... && uv run` | | PowerShell 不支持 && | RunCommand 用 cwd 参数指定工作目录，不用 `cd ... && uv run` |
| Markdown 章节关键词提取 | `_extract_recommendations` 仅匹配 `#` 开头的标题行或纯文本标题行，避免列表项自身含「建议」关键词被误判为章节标题 |
| main.py 模块级变量顺序 | ReportService 依赖 DataAnaClientGrpc，必须在 `_data_ana_client` 定义后实例化，否则 NameError |
### 2.10 shared-proto（契约包） ### 2.10 shared-proto（契约包）