# teacher-portal 问题记录

> 负责人：ai13
> 关联：[coord.md](../coord.md)、[contracts/teacher-portal_contract.md](../contracts/teacher-portal_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态
> 迁移说明：本文件 ISSUE-036~041 迁移自旧 `docs/issues.md` §2.7（已按总裁裁决 §0.4 编号冲突整理规则保留原始编号 + 追加 `<提请AI>` 后缀）

---

## 问题列表

### ISSUE-036-ai13：03-long-term-architecture.md "REST→GraphQL 演进策略"与 F9 裁决冲突

- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：裁决冲突 + 文档同步遗漏
- **阶段**：P2
- **描述**：
  - coord F9 裁决："P2 起 BFF 用 GraphQL，前端用 urql/apollo"，禁止"P2-P6 REST，未来切 GraphQL"
  - ai13 `apps/teacher-portal/docs/03-long-term-architecture.md` §1.4（提请时误记为 §6，实际 §6 是 i18n）仍保留"REST→GraphQL 切换策略"过渡方案（P2-P4 REST + P5+ 迁移 + feature flag 灰度）
  - 与 F9 裁决直接冲突，违反"不分阶段"原则
- **建议方案**：
  1. 删除 §1.4 "REST → GraphQL 切换策略"整节
  2. 替换为"GraphQL 客户端架构（P2 起最终方案）"
  3. 同步更新 §1.1 P2 行 + §1.2 表格 + §12.3 #3 待裁决问题
- **状态**：✅ 已回写闭合（2026-07-09，批次 0.15 后）
- **coord 裁决**：总裁裁决 §3.4 + §4.4 第 5 条（删除过渡方案本身，保留设计决策记录）
- **回写执行**：详见 [03-long-term-architecture.md §14.1](../../../apps/teacher-portal/docs/03-long-term-architecture.md)

---

### ISSUE-037-ai13：ai13 与 ai03 的 GraphQL schema 契约协调机制未明确

- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：契约不明确
- **阶段**：P2
- **描述**：
  - F9 裁决：P2 起 BFF 用 GraphQL（teacher-bff ai03 实现 GraphQL Yoga server），前端用 urql（teacher-portal ai13 实现 GraphQL client）
  - B1 裁决：GraphQL Yoga + DataLoader
  - ai13 与 ai03 的 GraphQL schema 契约如何协调未明确：
    - schema 定义权归属（ai03 定义 server schema，ai13 消费？还是 coord 仲裁第一版？）
    - schema 版本管理（GraphQL schema 演进如何同步前后端？）
    - 查询/变更/订阅的命名规范（camelCase vs snake_case？分页规范？）
    - 错误响应格式（GraphQL errors 数组 vs ActionState 信封？）
  - 与 ISSUE-019（ai08 core-edu 调用侧）/ ISSUE-030（ai04 student-bff 前端消费侧）同类但不同 BFF
- **建议方案**：
  1. coord 在批次 1 启动前仲裁 teacher-bff GraphQL schema 第一版
  2. 建立"schema-first"工作流：ai03 定义 → coord 仲裁 → ai13 消费 → 变更需 PR + 双方 review
  3. 明确 GraphQL 规范：camelCase 命名、Relay Cursor Connections 分页、errors 数组扩展 ActionState 字段（extensions.code = BFF_TEACHER_*）
  4. 建立 schema 注册表（packages/shared-ts/contracts/graphql/）
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §2.2（GraphQL schema 仲裁机制）—— SDL-first，存放 `packages/shared-ts/contracts/graphql/`，各 BFF AI 起草 + coord 仲裁第一版
- **执行**：ai13 待 ai03 起草 teacher-bff schema 后消费，coord 批次 1 启动前仲裁

---

### ISSUE-038-ai13：MF 暴露 AppShell 整体是否包含 GraphQL client 单例未明确

- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：契约不明确
- **阶段**：P2
- **描述**：
  - F10 裁决："暴露 AppShell 整体，各 Remote 自行决定内部布局"
  - 问题：AppShell 整体暴露是否包含 GraphQL client 单例（urql Client）？
    - 方案 A（包含）：Shell 初始化 GraphQL client，通过 React Context 注入给所有 Remote，共享同一 client 实例 + 缓存
    - 方案 B（不包含）：各 Remote 自行初始化，缓存隔离
  - 方案 A 风险：MF 跨 React 实例时 Context 共享有坑（shared singleton 要求）
  - 方案 B 风险：缓存隔离导致跨 Remote 数据不一致
- **建议方案**：建议方案 A（Shell 暴露 GraphQL client 单例）
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §2.17（采纳方案 A：Shell 暴露 GraphQLProvider，student/parent/admin Remote 复用 Shell 单例）
- **执行**：ai13 P2 实现 Shell GraphQLProvider，ai14/ai15/ai16 消费；MF shared 配置 react/urql/graphql 设为 singleton

---

### ISSUE-039-ai13：F8 ai13 维护 packages 的建立时机与依赖未明确

- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：前置依赖未就绪 + 工作归属不明
- **阶段**：P2
- **描述**：
  - F8 裁决："ai13 维护 ui-tokens/ui-components/hooks，coord 仅维护 shared-ts/contracts"
  - 问题：
    - 这 3 个 packages 何时建立？P2 启动前？P2 启动时？
    - ai13 P2 首次实现是否依赖这 3 个 packages 已就位？
    - packages 的依赖关系：ui-components 依赖 ui-tokens，hooks 依赖 ui-components？还是平级？
    - 4 个 portal 是否都消费？版本管理策略？
  - ai-work-orchestration.md §3.1 批次 0 未列出这 3 个 packages 的建立任务
- **建议方案**：
  1. ai13 在 P2 启动前（批次 0 末）建立 3 个 packages 骨架
  2. 依赖关系：ui-tokens（无依赖）→ ui-components（依赖 ui-tokens）→ hooks（依赖 ui-components）
  3. 4 个 portal 统一消费，版本通过 pnpm workspace 协议（"workspace:*"）
  4. ai13 完成后通知 ai14/ai15/ai16 消费
- **状态**：✅ 已裁决 + 已执行
- **coord 裁决**：总裁裁决 §2.18（ai13 在 P2 启动前 = 批次 0.15 建立 3 个 packages 骨架，4 个 portal 统一消费）
- **执行**：ai13 已于批次 0.15 完成建立：
  - `packages/ui-tokens/`（colors/typography/spacing/shadows + index.ts）
  - `packages/ui-components/`（cn/error-boundary/loading/empty/require-permission + index.ts）
  - `packages/hooks/`（use-auth/use-permission/use-a11y-id/use-toast/use-trace-id/use-aria-live/use-api/use-viewports + types + index.ts）
  - 依赖方向：ui-tokens ← ui-components ← hooks（hooks 不依赖 iam，权限数据 props 注入）
  - pnpm-workspace.yaml 已注册 packages/*

---

### ISSUE-040-ai13：ai13 teacher-portal P2 功能范围与下游服务启用阶段的关系未明确

- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：跨度过大
- **阶段**：P2
- **描述**：
  - ai-work-orchestration.md §4.3 明确 ai13 P2 范围：client 改造 + MF shell + 共享组件抽取
  - 但 teacher-portal P2 阶段需对接 teacher-bff（ai03 P2 启动）的哪些 GraphQL 查询未明确：
    - P2 仅实现登录 + Dashboard 框架？
    - 还是包含班级列表 + 学生列表等基础教学功能？
  - teacher-bff P2 只调 iam（gRPC），core-edu P3 / content P4 / data-ana P4 才启用
  - 若 teacher-portal P2 实现班级/学生/作业等页面，但 teacher-bff P2 无法 gRPC 调 core-edu（P3 才启用），数据来源断裂
  - ISSUE-004/005 已裁决"BFF 跨阶段扩展下游"是允许的例外，但前端是否也跟随？
- **建议方案**：
  1. 明确 ai13 P2 功能范围：登录 + 权限上下文 + Dashboard 框架 + 个人设置 + 班级列表（iam 数据）+ 学生列表（iam 数据）
  2. P3 起跟随 teacher-bff 扩展 core-edu 相关页面
  3. 前端路由骨架 P2 一次性建立，但页面内容随 BFF 能力分阶段填充
- **状态**：✅ 已裁决
- **coord 裁决**：总裁裁决 §3.5（ai13 P2 功能范围：登录 + 权限上下文 + Dashboard 框架 + 个人设置 + 班级列表 + 学生列表；P3-P5 跟随 teacher-bff 扩展）
- **执行**：ai13 P2 按此范围实现，见 workline.md §3 P2 详细任务

---

### ISSUE-041-ai13：仲裁评估总结 - 关键裁决对 ai13 的可行性与影响评估

- **提请方**：ai13
- **日期**：2026-07-09
- **类型**：跨度过大（评估总结）
- **阶段**：P2-P6
- **描述**：ai13 完整阅读 coord-final-decisions.md（80+ 项裁决）+ ai-work-orchestration.md（批次 0-5 规划）+ issues.md（35 个已识别问题），对 ai13 的关键裁决影响评估：

  | 裁决编号 | 裁决内容                         | 对 ai13 影响                      | 可行性                                 | 风险                                   |
  | -------- | -------------------------------- | --------------------------------- | -------------------------------------- | -------------------------------------- |
  | F9       | P2 起 GraphQL（urql）            | 高：从 REST 改造为 GraphQL client | 中：schema 契约协调成本高（ISSUE-037） | schema 未及时仲裁阻塞 P2               |
  | F12      | P2 localStorage token            | 低：与原设计一致                  | 高                                     | 无                                     |
  | F8       | ai13 维护 3 个 packages          | 中：新增 packages 建立任务        | 高：ai13 已设计完毕                    | 时机不明确（ISSUE-039）                |
  | F10      | MF 暴露 AppShell 整体            | 中：Shell 设计需包含 Provider     | 高                                     | GraphQL client 单例不明确（ISSUE-038） |
  | F7       | 权限点命名 `<RESOURCE>_<ACTION>` | 低：命名规范调整                  | 高                                     | 无                                     |

- **影响**：本评估总结供 coord 参考，不直接阻塞工作；具体阻塞问题已分别提请（ISSUE-036~040，均已裁决）
- **建议方案**：
  1. coord 优先处理 ISSUE-037（schema 仲裁机制）+ ISSUE-039（packages 时机），二者是 ai13 P2 启动的关键前置 —— ✅ 均已裁决
  2. ai13 在等待 coord 仲裁期间，先完成 03 文档回写（删除 REST→GraphQL）+ packages 骨架建立 —— ✅ 均已完成
  3. ai13 与 ai03 建立 schema 协调通道（PR review + 双方签字）
- **状态**：✅ 仅供参考，无具体裁决需求（所有子问题 ISSUE-036~040 均已裁决）
- **coord 裁决**：总裁裁决 §10 问题索引表确认 ISSUE-036~041-ai13 映射到 §2.2/2.17/2.18/3.4/3.5

---

### ISSUE-042-ai13：仲裁核查 - 01/02 文档未同步已裁决的 GraphQL 架构

- **提请方**：ai13
- **日期**：2026-07-10
- **类型**：文档同步遗漏（仲裁核查）
- **阶段**：P2
- **描述**：
  - 按"对已有仲裁进行核查"要求，审查 ISSUE-036~041（均已裁决）在文档中的落地情况
  - 核查发现：`apps/teacher-portal/docs/01-understanding.md` 和 `02-architecture-design.md` 仍为 ai07 标识 + REST 架构，**未同步**以下已裁决事项：
    - F9（ISSUE-036）：P2 起 all-in GraphQL，无 REST 过渡 — 01 §1/§3.1 仍写"P2-P3 用 REST 过渡"；02 全文基于 REST（ApiClient/TanStack Query/契约清单）
    - ARB-001（ISSUE-037）：teacher-bff GraphQL schema 第一版 5 Query — 01 §3.1 列 REST 端点；02 §4/§10 全 REST
    - ARB-002（ISSUE-038/039）：MF Shell 暴露清单（GraphQLProvider + hooks + UI 组件 + urql/graphql singleton）— 01 未提；02 §1.2 exposes 仅 AppShell+shared-deps、P2 配 3 remotes、shared 无 urql
    - 总裁 §2.17（ISSUE-038）：GraphQL client 单例方案 A — 02 §11.3.2 仍列"GraphQL vs REST"未决（已裁决）
  - 对照已回写的 `03-long-term-architecture.md §1.4`（GraphQL 最终方案），01/02 严重滞后
- **建议方案**：
  1. 01-understanding.md：ai07→ai13；§1 删除 REST 过渡；§3.1 REST 端点→GraphQL queries（ARB-001）；§4 技术栈补 urql；补 ARB-002 暴露清单
  2. 02-architecture-design.md：ai07→ai13；全文 REST→GraphQL 重写（MF 配置对齐 ARB-002；API 层改 urql client；契约清单改 GraphQL；§11.3 未决决策改已决策）
- **状态**：✅ 已回写闭合（2026-07-10，审查批次）
- **coord 裁决**：无需新裁决（复用 ISSUE-036~040 已有裁决），本次为文档同步执行
- **回写执行**：
  - `01-understanding.md`：已修正 ai07→ai13、§1 REST→GraphQL、§3.1 REST 端点→GraphQL queries（ARB-001）、§4 补 urql/GraphQL client 技术栈、补 ARB-002 暴露清单、端口对齐、字体令牌描述
  - `02-architecture-design.md`：全量重写为 GraphQL 架构（§1 MF 图加 GraphQLProvider 层；§1.2 MF 配置对齐 ARB-002 exposes/shared/remotes=0；§2 领域模型数据源改 GraphQL Query；§3 缓存层改 urql cacheExchange；§4 API 设计改 urql client 单例 + ARB-001 Query/Mutation；§10 契约清单改 GraphQL；§11.3 未决决策改已决策表；端口 3000→4000）

---

**AI Agent**: ai13（teacher-portal）
**Branch**: feat/teacher-portal-issues-migrate-ai13
**Coordinator**: coord-ai
**迁移说明**：本文件 ISSUE-036~041 迁移自旧 `docs/issues.md` §2.7，按总裁裁决 §0.4 保留原始编号 + 追加 `<提请AI>` 后缀，状态更新为已裁决
