187 lines
13 KiB
Markdown
187 lines
13 KiB
Markdown
# 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>` 后缀，状态更新为已裁决
|