feat(p1): complete P1 foundation stage

- monorepo: pnpm workspace + go.work + pyproject.toml + commitlint/husky
- infra: docker-compose (minimal + full profiles) + init-sql + prometheus
- arch-scan: multi-language scanner skeleton (TS/Go/Python/Proto)
- shared-proto: buf v2 + classes.proto (ClassService CRUD contract)
- api-gateway: Go/Gin + JWT HS256 auth + reverse proxy + request ID
- classes: NestJS golden template (error system + observability + middleware + CRUD + tests)
- teacher-portal: Next.js + paper-feel UI design system
- CI/CD: 4 workflows (go/ts/py/proto)
- docs: migration guide + project_rules + coding-standards + git-workflow + ui-design-system + 004 + 9 module READMEs + known-issues + spec/plan migration + roadmap

docs/modules/ai/README.md

@@ -0,0 +1,111 @@
+# ai AI 网关服务
+
+> 版本：0.1（骨架）
+> 日期：2026-07-07
+> 状态：P5 待交付
+> 关联文档：[架构影响地图](../../architecture/004_architecture_impact_map.md)
+
+---
+
+## 1. 模块职责
+
+ai 是 AI 网关限界上下文（Python 实现），管理 LLMCall、Prompt、Generation 聚合。
+统一封装 LLM 调用（多模型路由、重试、限流、成本控制），提供辅助出题、表达优化、分层提问等能力。
+通过 gRPC 查询 content 题库与 data-ana 学情数据，结合知识图谱生成个性化内容。
+
+---
+
+## 2. 技术栈
+
+| 类别 | 技术 | 版本 | 用途 |
+|------|------|------|------|
+| 语言 | Python | 3.12+ | AI 生态 |
+| 框架 | FastAPI | 0.110+ | 异步 API |
+| LLM SDK | openai / anthropic | - | 多模型调用 |
+| 编排 | LangGraph | - | LLM 工作流编排 |
+| 检索 | Elasticsearch | 8.x | 题库检索（RAG） |
+| 缓存 | Redis | 7.x | Prompt 缓存、结果缓存 |
+| 校验 | pydantic | 2.x | 运行时校验 |
+| 追踪 | OpenTelemetry | - | LLM 调用链追踪 |
+
+---
+
+## 3. 架构图
+
+```mermaid
+graph TB
+    BFF[BFF 聚合层] -->|gRPC| AI[ai 服务]
+    AI --> ROUTER[ModelRouter<br/>多模型路由]
+    AI --> ORCH[LangGraph 编排]
+    AI --> RAG[RAG 检索增强]
+    RAG -->|gRPC| CONTENT[content 题库]
+    RAG -->|gRPC| ANA[data-ana 学情]
+    AI -->[(ES<br/>题库检索)]
+    AI -->[(Redis<br/>结果缓存)]
+    AI --> LLM[LLM API<br/>OpenAI/Claude]
+```
+
+> 待 P5 交付时补充完整的分层架构图与 LLM 编排图。
+
+---
+
+## 4. 核心流程图
+
+```mermaid
+sequenceDiagram
+    participant T as 教师
+    participant BFF as BFF
+    participant AI as ai 服务
+    participant CONTENT as content
+    participant ANA as data-ana
+    participant LLM as LLM API
+
+    T->>BFF: AI 辅助出题
+    BFF->>AI: gRPC GenerateQuestions(topic, difficulty)
+    AI->>CONTENT: gRPC 查询相关题目 + 知识点
+    AI->>ANA: gRPC 查询学情掌握度
+    AI->>AI: LangGraph 编排 Prompt
+    AI->>LLM: 调用 LLM 生成
+    LLM-->>AI: 生成结果
+    AI->>AI: 质量校验 + 缓存
+    AI-->>BFF: 生成的题目列表
+```
+
+> 待 P5 交付时补充：表达优化流程、分层提问流程、差异化建议流程。
+
+---
+
+## 5. 对外契约
+
+- **gRPC 服务**：AIService（GenerateQuestions、OptimizeExpression、SuggestDifferentiation、GenerateLayeredQuestions）（待 P5 定义 protobuf）
+- **消费事件**：无（按需 gRPC 调用）
+- **发布事件**：`edu.ai.generation.completed`（可选，用于审计）
+- **缓存**：Redis 存储生成结果（相同 prompt 24 小时缓存）
+
+> 待 P5 交付时补充完整 protobuf 定义与 Prompt 模板规范。
+
+---
+
+## 6. 依赖关系
+
+- **上游**：teacher-bff（AI 辅助功能）
+- **下游**：LLM API（OpenAI/Claude）、Elasticsearch、Redis、content（gRPC）、data-ana（gRPC）
+- **跨服务**：gRPC 调用 content 题库与 data-ana 学情，不消费事件
+
+---
+
+## 7. 架构约束
+
+1. LLM 调用必须经 ModelRouter，支持多模型故障切换
+2. 生成内容必须经质量校验，禁止直接返回未校验结果
+3. 调用成本必须记录，按用户/学校维度限额
+4. Prompt 模板必须版本化管理，禁止硬编码
+5. RAG 检索必须优先于 LLM 生成，减少幻觉
+
+> 待 P5 交付时补充完整约束清单。
+
+---
+
+## 8. 架构决策
+
+> 待 P5 交付时补充 ADR 记录，预计包括：Python+FastAPI 选型、LangGraph 编排选型、多模型路由策略、RAG 检索策略、成本控制策略。