# 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 | 权限点命名 `_` | 低：命名规范调整 | 高 | 无 | - **影响**：本评估总结供 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 --- **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>` 后缀，状态更新为已裁决