xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
14d836beb01bb3f5f54037726fe7d68739febd27
Edu/docs/architecture/issues/objections/teacher-portal_issue.md
SpecialX 14d836beb0 feat: auto committed
2026-07-10 15:05:47 +08:00

13 KiB
Raw Blame History

teacher-portal 问题记录

负责人：ai13 关联：coord.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

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> 后缀，状态更新为已裁决

Reference in New Issue View Git Blame Copy Permalink