docs: ai 协作文档体系重构与多 ai 仲裁结果落地

1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
2026-07-10 12:58:22 +08:00
parent 2a2a56f541
commit faaaf29f67
120 changed files with 23201 additions and 2 deletions
--- a/docs/architecture/issues/objections/teacher-portal_issue.md
+++ b/docs/architecture/issues/objections/teacher-portal_issue.md
@@ -0,0 +1,161 @@
+# 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
+
+---
+
+**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>` 后缀，状态更新为已裁决