# admin-portal 问题记录

> 负责人：ai16
> 关联：[coord.md](../coord.md)、[contracts/admin-portal_contract.md](../contracts/admin-portal_contract.md)、[matrix.md](../matrix.md)、[ai-allocation.md §5 ai16](../../ai-allocation.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态

---

## §0 已有仲裁核查（ai16 复核）

> 任务要求：对 coord 已有仲裁进行核查。以下为 ai16 对照 admin-portal 实际职责逐条复核结论。

### 0.1 ARB-001（teacher-bff GraphQL schema 第一版）— 核查结论：✅ 通过，但存在依赖缺口

- **核查点**：ARB-001 §1.3 裁决"admin 命名空间 P2 不包含，P6 admin-portal 阶段新增 admin 命名空间"。
- **核查结论**：裁决方向正确（admin-portal 复用 teacher-bff + admin schema 命名空间，与 ai-allocation §5 ai16 设计重点一致）。
- **发现的缺口**：teacher-bff 当前 [02-architecture-design.md](../../../services/teacher-bff/docs/02-architecture-design.md) **未定义 admin 命名空间的 GraphQL schema**（全文仅 1 处 audit 提及，无 adminUsers/adminRoles/auditLogs/adminDashboard 等 Query）。admin-portal P6 的全部业务查询依赖该 schema，属前置依赖缺失。
- **建议**：请 coord 仲裁 admin 命名空间 schema 的归属与时间点——是否由 ai03（teacher-bff）在 P6 启动前补齐 `packages/shared-ts/contracts/graphql/teacher-bff.graphql` 的 admin 命名空间部分（参照本模块 [contract §2.4](../contracts/admin-portal_contract.md) 的 Query 清单）。
- **状态**：待 coord 仲裁（见新异议 ISSUE-005）

### 0.2 ARB-002（MF Shell 暴露清单）— 核查结论：✅ 通过，但 01/02 文档未跟进

- **核查点**：ARB-002 §2.2 Shell 暴露清单含 `GraphQLProvider` / `useGraphQLClient` / `useAuth` / `usePermission` / `AppShell` / `ErrorBoundary` / `Loading` / `Empty` / `RequirePermission`，**不含** `useApi` / `ApiClient`。
- **核查结论**：裁决正确。admin-portal 应通过 `useGraphQLClient()` 消费 teacher-bff GraphQL，而非 REST ApiClient。
- **发现的问题**：本模块 [01-understanding.md](../../../apps/admin-portal/docs/01-understanding.md) 与 [02-architecture-design.md](../../../apps/admin-portal/docs/02-architecture-design.md) 仍基于 REST `useApi()` / `ApiClient` 编写，未跟进 ARB-002。属本模块文档与仲裁不同步（见新异议 ISSUE-003）。
- **状态**：本模块文档待修订（见 ISSUE-003）

### 0.3 未仲裁但影响 admin-portal 的关键项

ARB-001/ARB-002 均未明确仲裁以下三项，而它们直接影响 admin-portal 实现，建议 coord 补充裁决：

| 待裁决项                                                        | 当前依据                                                     | 影响                                                          |
| --------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
| admin-portal 端口                                               | matrix.md / ai-allocation.md = 4003                          | 01/02 文档误用 3003（与 teacher-bff 冲突）                    |
| admin-portal 是否消费 push-gateway WebSocket                    | 同类 portal（parent-portal）契约 = 消费                      | 01/02 文档误声明"不消费推送"                                  |
| 审计日志消费机制（iam Kafka → teacher-bff → GraphQL auditLogs） | matrix.md §4 列 admin-portal 为 edu.iam.audit.created 消费方 | 前端不直连 Kafka，需经 teacher-bff 聚合，matrix.md 表述不精确 |

---

## 问题列表

### ISSUE-001-ai16：01/02 模块文档归属错误（ai07 → ai16）

- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：编号冲突 / 文档归属
- **描述**：[01-understanding.md](../../../apps/admin-portal/docs/01-understanding.md) 与 [02-architecture-design.md](../../../apps/admin-portal/docs/02-architecture-design.md) 头部均标注"AI：ai07（TS/React · 管理场景域前端 remote）"，分支名 `docs/admin-portal-stage1-stage2-design-ai07`。但 [ai-allocation.md §5](../../ai-allocation.md) 第 54/97/118/159/278 行明确 admin-portal 归属 **ai16**，ai07 实际负责 classes → core-edu 交接（见 [workline.md §4.7](../workline.md)）。
- **建议方案**：将 01/02 文档头部 AI 标识与分支命名更正为 ai16；ai07 在 admin-portal 的产出视为历史草稿，由 ai16 接管修订。
- **状态**：待 coord 仲裁

### ISSUE-002-ai16：01/02 文档端口错误（3003 → 4003），且 3003 与 teacher-bff 冲突

- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：契约不明确 / 编号冲突
- **描述**：01 §1 与 02 §12.1 声明 admin-portal 端口 3003，并称"与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐"。但 full-stack-runbook §2.1 中 **3003 = teacher-bff**，admin-portal 未列入该 runbook。coord 维护的 [matrix.md §1](../matrix.md) 与 ai-allocation.md 统一采用 4000 段：teacher-portal :4000 / student-portal :4001 / parent-portal :4002 / admin-portal :4003。
- **建议方案**：确认 admin-portal 端口为 **4003**；同步更新 full-stack-runbook §2.1 补齐 4 个 portal 的 4000 段端口（消除 runbook 与 matrix.md 的端口双轨制）。
- **状态**：待 coord 仲裁

### ISSUE-003-ai16：01/02 文档通信协议与 ARB-001/ARB-002 不一致（REST → GraphQL）

- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：契约不明确 / 前置依赖缺失
- **描述**：01 §3.1 / 02 §1、§4 全文基于 REST（`/api/v1/iam/*` + `/api/v1/admin/*` + `useApi()` + `ApiClient`）。但 ARB-001 已裁决 admin-portal 复用 teacher-bff GraphQL **admin 命名空间**，ARB-002 已裁决 Shell 暴露 `GraphQLProvider` + `useGraphQLClient`（不含 `useApi`）。02 §11.3 仍将"GraphQL vs REST"列为未决，与仲裁结论冲突。根因：01/02 文档参照的 teacher-portal 02 文档（同样基于 REST、将 GraphQL 列为未决）早于 ARB-001/002（2026-07-09），未跟进仲裁。
- **建议方案**：admin-portal 通信协议统一为 GraphQL（`POST /api/admin/graphql` → teacher-bff admin 命名空间）；删除 `useApi`/`ApiClient` 依赖，改用 `useGraphQLClient()`；02 §11.3 移除已裁决项。本模块 [contract.md](../contracts/admin-portal_contract.md) 已按 GraphQL 编写，作为修订基准。
- **状态**：待 coord 仲裁

### ISSUE-004-ai16：01/02 文档遗漏审计日志与学校设置（ai-allocation §5 明确职责）

- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：工作量超批 / 契约不明确
- **描述**：[ai-allocation.md §5 ai16](../../ai-allocation.md) 第 282 行明确 admin-portal 设计重点含"用户管理 + 角色权限管理 + 学校设置 + 组织管理 + **审计日志消费**"。但 01 §2.1/§L1 导航/§L2 路由表均**无审计日志、无学校设置**（仅有 dashboard/users/roles/permissions/viewports/organization/monitoring 7 个视口）。本模块 [contract.md §1.2/§2.4](../contracts/admin-portal_contract.md) 已含 audit-logs / system 路由与 auditLogs Query，与 01/02 不一致。
- **建议方案**：admin-portal 视口补齐为 9 个：dashboard / users / roles / permissions / viewports / organization / classes / teachers / students / audit-logs / system（按 ai-allocation §5 + contract §1.2 对齐）；审计日志经 teacher-bff GraphQL `auditLogs` Query 消费（聚合 iam `AuditEvent`）。
- **状态**：待 coord 仲裁

### ISSUE-005-ai16：teacher-bff 缺 admin 命名空间 GraphQL schema（前置依赖缺失）

- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：ARB-001 裁决 P6 新增 admin 命名空间，但 teacher-bff [02-architecture-design.md](../../../services/teacher-bff/docs/02-architecture-design.md) 未定义该 schema（无 adminUsers / adminRoles / adminClasses / adminTeachers / adminStudents / auditLogs / adminDashboard 等 Query/Mutation）。admin-portal P6 全部业务查询依赖此 schema，且需 SDL-first 存放于 `packages/shared-ts/contracts/graphql/teacher-bff.graphql`（ARB-001 §1.3）。
- **建议方案**：请 coord 仲裁——由 ai03 在 P6 启动前补齐 teacher-bff admin 命名空间 schema（参照本模块 contract §2.4 Query 清单），作为 admin-portal P6 的前置就绪信号；并更新 [matrix.md §3](../matrix.md) teacher-bff 行的 schema 文件状态。
- **状态**：待 coord 仲裁

### ISSUE-006-ai16：01/02 文档推送策略与同类 portal 契约不一致（轮询 → WebSocket）

- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：01 §3.3 / 02 §5 声明 admin-portal"不消费 WebSocket/SSE，采用轮询"。但同类 portal 契约（[parent-portal_contract.md §2.3](./parent-portal_contract.md)）消费 push-gateway `GET /ws`，本模块 [contract.md §2.3](../contracts/admin-portal_contract.md) 亦声明消费 WebSocket 实时通知。matrix.md §5 列 push-gateway WS 消费方含全部 portal。管理端审计告警/异常登录等场景对实时性有合理需求。
- **建议方案**：admin-portal 接入 push-gateway WebSocket（与同类 portal 一致），用于审计告警、异常登录、系统异常等实时通知；保留轮询仅用于监控指标（60s）与统计（5min）这类天然适合轮询的低频数据。
- **状态**：待 coord 仲裁

### ISSUE-007-ai16：matrix.md §4 将 admin-portal 列为 Kafka 直消费方，与前端层级矛盾

- **提请方**：ai16
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：[matrix.md §4](../matrix.md) 第 111 行将 admin-portal 列为 `edu.iam.audit.created` 的消费方。但前端不直连 Kafka（[contract.md §2.2](../contracts/admin-portal_contract.md) 已明确审计日志经 GraphQL 查询）。实际链路应为：iam → Kafka → **teacher-bff** 消费 → GraphQL `auditLogs` Query → admin-portal。
- **建议方案**：matrix.md §4 该行消费方更正为 **teacher-bff**（admin-portal 经 teacher-bff 间接消费），避免误导架构分层。
- **状态**：待 coord 仲裁

---

## §1 历史问题

### 1.1 仲裁结论汇总（coord 2026-07-10）

> 详见 [coord.md §23 ARB-021](../coord.md) 完整仲裁章节

| ISSUE | 标题                                                   | 仲裁结论摘要                                                                                                              | 执行方                           |
| ----- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| 001   | 01/02 模块文档归属错误（ai07 → ai16）                  | ✅ 修正为 ai16；ai07 产出视为历史草稿                                                                                     | ai16 修 01/02 头部               |
| 002   | 01/02 端口错误（3003 → 4003）                          | ✅ 确认 admin-portal 端口 4003；同步更新 full-stack-runbook §2.1 补齐 4 个 portal 4000 段                                 | ai16 修 01/02 + coord 修 runbook |
| 003   | 01/02 通信协议与 ARB-001/002 不一致（REST → GraphQL）  | ✅ 统一 GraphQL（`POST /api/admin/graphql` → teacher-bff admin 命名空间）；删除 useApi/ApiClient                          | ai16 修 01/02 全文               |
| 004   | 01/02 遗漏审计日志与学校设置                           | ✅ 视口补齐为 11 个：dashboard/users/roles/permissions/viewports/organization/classes/teachers/students/audit-logs/system | ai16 修 01/02                    |
| 005   | teacher-bff 缺 admin 命名空间 GraphQL schema           | ✅ ai03 在 P6 启动前补齐 teacher-bff admin 命名空间 schema（参照 contract §2.4）                                          | ai03 补 schema                   |
| 006   | 01/02 推送策略与同类 portal 不一致（轮询 → WebSocket） | ✅ admin-portal 接入 push-gateway WebSocket（审计告警/异常登录/系统异常）；保留轮询仅用于监控指标                         | ai16 修 01/02                    |
| 007   | matrix.md §4 将 admin-portal 列为 Kafka 直消费方       | ✅ 修正为 teacher-bff（admin-portal 经 teacher-bff 间接消费，链路：iam → Kafka → teacher-bff → GraphQL → admin-portal）   | coord 修 matrix.md §4            |
