Edu/apps/portal-shell/docs/needtodo/shared-NeedTodo.md

# 共享路由（Shared）待完成功能分析

> 参考项目：`e:\desktop\CICD\src\app\(dashboard)\`
> 当前项目：`e:\Desktop\Edu\apps\portal-shell\src\app\shell\`
> 规划依据：`apps\portal-shell\ARCHITECTURE.md` §9.1 / §9.2 / §9.3 / §9.5（共享 ~7 页）
> 分析时间：2026-07-24
> 分析范围：仅分析，不写代码

---

## 一、页面完成度总览

| 状态 | 路径                        | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ✅   | `/login`                    | 登录页                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ✅   | `/shell`                    | 仪表盘根（按角色分发到 `/shell/{teacher\|student\|parent\|admin}`）。**CICD 参考**：无单一分发器——CICD 根 `src/app/page.tsx` 直接 `redirect("/dashboard")`（教师仪表盘）；各角色仪表盘分散于 `(dashboard)/dashboard/`、`(dashboard)/student/dashboard/`、`(dashboard)/parent/dashboard/`、`(dashboard)/admin/dashboard/`。portal-shell 实现于 `src/app/shell/[[...route]]/page.tsx`（catch-all，空路由 → `redirect("/shell/{role}")`）+ `src/app/shell/layout.tsx`（AppFrame 框架，fail-closed 读 `x-user-role` 头） |
| ✅   | `/shell/forbidden`          | 403 页（`PUBLIC_ROUTES` 白名单）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ❌   | `/shell/notifications`      | 通知中心（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ❌   | `/shell/settings`           | 设置（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ❌   | `/shell/settings/security`  | 安全中心 / 改密码（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ❌   | `/shell/announcements`      | 公告列表（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ❌   | `/shell/announcements/[id]` | 公告详情（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ❌   | `/shell/messages`           | 消息（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ❌   | `/shell/messages/compose`   | 撰写消息（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ❌   | `/shell/messages/[id]`      | 消息详情（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ❌   | `/shell/profile`            | 个人资料（缺失）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

> 备注 1：portal-shell 现存 `widgets/topbar/notification-bell`（顶栏铃铛下拉）与 `widgets/universal/notifications-widget`（仪表盘内嵌通知卡片），但**无独立的通知中心整页**。
> 备注 2：`widgets/universal/announcements-widget` 已在 P1-2 下线（数据源迁移到 `adminDashboard` 聚合查询），**无用户端公告列表/详情页**。
> 备注 3：`shared/lib/navigation.ts` 与 `shared/lib/route-permissions.ts` **均未登记**上述任一共享路由，按 `route-permissions.ts` §5 fail-closed 规则，未登记的 `/shell/*` 路由会被默认拒绝 → 即便加了 page.tsx 也访问不到，必须同步登记权限配置。

---

## 二、缺失页面详情

### 2.1 `/shell/notifications`（通知中心）

- **CICD 参考**：无独立 `notifications/page.tsx`。CICD 中通知集成在三处：
  - `widgets/topbar/notification-bell` 的下拉（顶栏铃铛）
  - `messages/page.tsx` 内嵌的 `NotificationListSection`（与消息列表合并展示）
  - 通知偏好散落在 `settings` 页 + `notifications/preferences.ts`
- **功能描述**：
  - 用户视角的"通知中心"整页：分页列出当前用户的站内通知（`message_notifications` 表），支持未读/已读筛选、归档、标记已读、全部已读、按优先级（low/normal/high/urgent）筛选
  - 通知类型包括 `message` / `announcement` / `homework` / `grade` / `diagnostic` 五类
  - 通知带 `link` 字段可点击跳转到来源页（如作业/成绩/公告详情）
  - 顶栏铃铛仅展示最近 N 条 + 未读角标，整页才是完整列表
- **技术栈**：
  - Server Component + `Suspense` + `SectionErrorBoundary`（局部失败不影响其他区块）
  - `notifications/data-access.ts`：`getNotifications` / `markNotificationAsRead` / `markAllNotificationsAsRead` / `archiveNotification` / `getUnreadNotificationCount`（均 `cacheFn` 包装，tag=`notifications`，TTL=60s）
  - Server Actions：`notifications/actions.ts`（384 行，标记已读/归档/批量操作）
  - 客户端实时流：`use-notification-stream`（SSE）+ `use-desktop-notifications`（浏览器桌面通知）
  - 表：`message_notifications`（站内通知本体）、`notification_preferences`（偏好）、`notification_logs`（发送日志）
- **ARCHITECTURE.md 契约**：✅ `notifications(userId)`（§9.1 line 645，B1 共享）
  - portal-shell 已有 `GET_NOTIFICATIONS_LIST_DOC` GraphQL document（`universal.graphql.ts`），但形状待 P1-7 修正（后端返回平铺数组，前端按 `{items, total}` 解析）
  - `useNotifications` hook 已就绪（`lib/api/universal.ts`），可直接复用
- **多角色复用**：教师 / 学生 / 家长 / 管理员（全角色，权限点复用 `MESSAGE_READ`，无独立 `NOTIFICATION_READ`）
- **优先级**：**B1**（§9.1 line 645）

---

### 2.2 `/shell/settings`（设置）

- **CICD 参考**：`e:\desktop\CICD\src\app\(dashboard)\settings\page.tsx` + `error.tsx` + `loading.tsx`
- **功能描述**：
  - 个人资料编辑表单（姓名/性别/年龄/手机/地址）+ 头像上传
  - 通知偏好表单（`smsEnabled` / `emailEnabled` / `pushEnabled` + `homeworkNotifications` / `gradeNotifications` 等业务开关）
  - 安全中心入口（密码修改、最近登录记录、2FA、当前会话 User-Agent 标记）
  - **角色差异化**：通过 `resolveRoleSettingsConfig(roles)` 注入 `descriptionKey` / `backHref` / `generalExtra`（如管理员额外展示学校信息/品牌配置/AI 提供商配置卡片）
  - 子页 `/settings/security`：独立密码修改页 + 安全提示
- **技术栈**：
  - Server Component（`requireAuth`，不要求特定权限点）+ `SettingsServiceProvider`（Context 注入 `SettingsService` 接口）
  - Server Actions（`actions-service.ts`）：`updateProfileAction` / `updateNotificationPreferencesAction` / `actions-avatar.ts` / `actions-password.ts` / `actions-security.ts` / `actions-brand.ts` / `actions-system-settings.ts`
  - 数据源：`getUserProfile`（users 模块）+ `getNotificationPreferences`（notifications 模块）
  - 角色配置：`modules/settings/config/role-settings-config.tsx`（按角色注入额外卡片）
  - 客户端组件：`settings-view` / `profile-settings-form` / `notification-preferences-form` / `password-change-form` / `security-center-card` / `avatar-upload` / `theme-preferences-card` 等 22 个组件
  - 工具：`totp.ts`（2FA）、`security-utils.ts`（密码强度校验）
- **ARCHITECTURE.md 契约**：✅（§9.1 line 646，B1 共享，契约字段未细化）
  - portal-shell 当前无 settings 模块、无 `/shell/settings` 路由、无 `navigation.ts` 入口、无 `route-permissions.ts` 登记
- **多角色复用**：教师 / 学生 / 家长 / 管理员（全角色，按 `roles` 动态注入角色专属卡片）
- **优先级**：**B1**（§9.1 line 646）

---

### 2.3 `/shell/settings/security`（安全中心子页）

- **CICD 参考**：`e:\desktop\CICD\src\app\(dashboard)\settings\security\page.tsx` + `error.tsx` + `loading.tsx`
- **功能描述**：
  - 独立的密码修改页（`PasswordChangeForm`）+ 安全提示卡片
  - 与 `settings` 主页的"安全中心卡片"互补，提供专注的改密体验
- **技术栈**：
  - `requireAuth` + `PasswordChangeForm`（客户端组件，调 `updatePasswordAction`）
  - 复用 `modules/settings` 模块
- **ARCHITECTURE.md 契约**：🟡 未显式列出，但属于 `settings` 共享子页（§9.1 隐含）
- **多角色复用**：全角色
- **优先级**：B1（跟随 settings）

---

### 2.4 `/shell/announcements`（公告列表）

- **CICD 参考**：`e:\desktop\CICD\src\app\(dashboard)\announcements\page.tsx`
- **功能描述**：
  - 用户端公告列表（非管理端），分页展示当前用户**可见**的公告（school / grade / class 三类，按受众 `gradeIds[]` / `classIds[]` 数组过滤，P0-2 多受众修复）
  - 支持状态筛选（`published` / `draft` / `archived` / `all`），通过 `searchParams.status` 传递
  - `AnnouncementList` + `AnnouncementPagination`（客户端构建分页 URL，不传函数 prop）
  - 点击进入 `/announcements/[id]` 详情
  - 管理端在 `/admin/announcements`（不在共享范围）
- **技术栈**：
  - Server Component + `requirePermission(ANNOUNCEMENT_READ)` + `AnnouncementsServiceProvider`（Context）
  - `announcements/data-access.ts`（603 行，server-only）：`getUserAnnouncementsPageData(userId, dataScope, page, pageSize)` 受众过滤 + 分页
  - `isAnnouncementVisibleToAudience` 纯函数（单测覆盖三类矩阵）
  - 表：`announcements` + `announcement_reads`（已读回执独立表）
  - 缓存：`cacheFn` + `invalidateFor` 双路径失效（列表 + 详情）
- **ARCHITECTURE.md 契约**：❌（§9.2 line 668，"列表"契约未就绪，B3）
  - portal-shell 的 `announcements-widget` 已下线（P1-2），数据源迁到 `adminDashboard` 聚合，**用户端列表契约完全缺失**
- **多角色复用**：教师 / 学生 / 家长（查看自己受众范围内的公告）；管理员走 `/shell/admin/announcements` 管理端，不走共享列表
- **优先级**：**B3**（§9.2 line 668）

---

### 2.5 `/shell/announcements/[id]`（公告详情）

- **CICD 参考**：`e:\desktop\CICD\src\app\(dashboard)\announcements\[id]\page.tsx`
- **功能描述**：
  - 公告详情页，展示标题/内容/类型/发布时间/作者
  - **P0-1 越权修复**：`getAnnouncementByIdForUser(id, userId, dataScope)` 在 data-access 层结合受众与 status 过滤，不可见时统一返回 404（不暴露公告存在性）
  - `canManage={false}`（用户端只读，管理操作在 `/admin/announcements/[id]/edit`）
  - 进入详情后可触发已读回执 `markAnnouncementAsReadAction`
- **技术栈**：
  - Server Component + `requirePermission(ANNOUNCEMENT_READ)` + `notFound()` 守卫
  - `getAnnouncementByIdForUser` 受众过滤查询
  - `AnnouncementDetail` 客户端组件 + `AnnouncementsServiceProvider`
- **ARCHITECTURE.md 契约**：🟡 `announcement(id)` 已存在但形状/可见性语义待对齐（§9.2 line 668，B3）
- **多角色复用**：教师 / 学生 / 家长
- **优先级**：**B3**（§9.2 line 668）

---

### 2.6 `/shell/messages`（消息列表）

- **CICD 参考**：`e:\desktop\CICD\src\app\(dashboard)\messages\page.tsx` + `error.tsx` + `loading.tsx`
- **功能描述**：
  - **CICD 把"消息列表"和"通知列表"合并展示在同一页**（消息在上、通知在下，各自独立 `Suspense` + `SectionErrorBoundary`，局部失败互不影响）
  - 消息区：`MessageListSection`（按 `dataScope.type === "class_taught"` 决定是否显示"群发"按钮，即教师可群发全班家长）
  - 通知区：`NotificationListSection`（调 `getNotifications(userId, {page:1, pageSize:20})`）
  - 子页 `compose`：撰写新消息 + 草稿列表（`getRecipients` + `getMessageDrafts`）
  - 子页 `[id]`：消息详情（`getMessageDetailPageData`，含撤回、星标、举报、附件）
  - 子页 `group-compose`：教师群发（fan-out on write）
- **技术栈**：
  - Server Component + `requirePermission(MESSAGE_READ)` + 双 `Suspense` 流式加载
  - `messaging/data-access.ts`（barrel，拆分为 core/bulk/group/templates/reports 5 子文件）
  - 表：`messages` / `message_drafts` / `message_templates` / `message_reports` / `user_blocks`
  - Server Actions：`sendMessageAction` / `recallMessageAction`（2 分钟窗口服务端校验，不乐观更新）/ `sendGroupMessageAction`（fan-out on write）/ `reportMessageAction` / `blockUserAction`
  - 乐观更新：`useOptimistic` 仅用于星标切换
  - 收件人二次校验（P0-1）：`isReceiverAllowed` 防 UI 绕过越权
  - 通知集成：消息发送后调 `notifications/dispatcher.sendNotification` 多通道分发（in-app/sms/email/wechat，尊重偏好）
- **ARCHITECTURE.md 契约**：❌（§9.2 line 669，B3 末，契约完全缺失）
  - portal-shell 当前无 `messaging` 模块、无 `/shell/messages` 路由
  - msg 子图仅暴露 `notifications(userId)`，未暴露 messages 相关查询
- **多角色复用**：教师（可群发）/ 学生 / 家长 / 管理员（全角色私信，权限点 `MESSAGE_READ` / `MESSAGE_SEND`）
- **优先级**：**B3 末**（§9.2 line 669）

---

### 2.7 `/shell/messages/compose` / `/shell/messages/[id]`（消息子页）

- **CICD 参考**：
  - `e:\desktop\CICD\src\app\(dashboard)\messages\compose\page.tsx` + `loading.tsx`
  - `e:\desktop\CICD\src\app\(dashboard)\messages\[id]\page.tsx` + `loading.tsx`
  - `e:\desktop\CICD\src\app\(dashboard)\messages\group-compose\page.tsx` + `loading.tsx`
- **功能描述**：
  - `compose`：撰写表单（收件人选择 + 主题 + 内容 + 附件）+ 草稿列表（`MessageDraftList` 支持恢复编辑/删除）+ 快捷模板选择器（`message-template-picker`）
  - `[id]`：消息详情，含撤回（2 分钟窗口）、星标、举报、屏蔽、附件预览
  - `group-compose`：教师选择班级 → fan-out 群发全班家长（共享 `groupMessageId`）
- **技术栈**：同 §2.6
- **ARCHITECTURE.md 契约**：❌（§9.2 line 669 隐含，B3 末）
- **多角色复用**：教师（含群发）/ 学生 / 家长 / 管理员
- **优先级**：B3 末

---

### 2.8 `/shell/profile`（个人资料）

- **CICD 参考**：`e:\desktop\CICD\src\app\(dashboard)\profile\page.tsx` + `error.tsx` + `loading.tsx`
- **功能描述**：
  - 个人资料展示页（只读，编辑入口跳转到 `/settings`）
  - 头像上传区（`AvatarUpload`，独立 `SectionErrorBoundary`）
  - 个人信息卡：姓名 / 性别 / 年龄 / 手机 / 地址
  - 账户信息卡：邮箱 / 角色 Badge / 注册时间 / Onboarded 时间
  - **角色差异化概览**：`resolveProfileOverviewType(roles)` 决定底部展示 `ProfileStudentOverview`（学生学业概览）或 `ProfileTeacherOverview`（教师概览），均带 `Suspense` 骨架屏
- **技术栈**：
  - Server Component + `requireAuth`（无特定权限点）+ `getUserProfile(userId)` + `redirect("/login")` 守卫
  - 客户端组件：`AvatarUpload` / `ProfileStudentOverview` / `ProfileTeacherOverview`
  - 角色配置：`modules/settings/config/profile-overview-config.ts`
  - UI：`PageHeader` + `Card` + `Badge` + `Button` + `lucide-react` 图标
- **ARCHITECTURE.md 契约**：🟡 未在 §9 显式列出独立 `/shell/profile` 行，但 §9.5 计数 ~7 页共享 + CICD 有 `profile/page.tsx`，推断属于共享路由隐含项
  - portal-shell 当前无 `/shell/profile` 路由、无 settings 模块（profile 组件归属 settings 模块）
- **多角色复用**：教师 / 学生 / 家长 / 管理员（全角色，按 `resolveProfileOverviewType` 切换底部概览）
- **优先级**：B1/B3（跟随 settings，建议 B1 一并实现）

---

### 2.9 /register（注册页）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(auth)\register\page.tsx`（RSC，13 行，渲染 `<RegisterForm registerAction={registerAction} />`）；布局 `e:\desktop\CICD\src\app\(auth)\layout.tsx` 注入品牌配置（`getBrandConfig()`，失败回退默认）
- **功能描述**：账号注册页。表单字段：姓名 / 邮箱 / 密码 / 出生年月日 / 邀请码（可选，提供时覆盖默认 student 角色）。未成年人保护：根据 `birthDate` 计算 `age`，`< 18` 触发监护人信息区（监护人姓名 / 电话 / 关系下拉）+ 监护人同意复选框。必勾"同意《隐私政策》与《用户协议》"复选框（链接到 `/privacy`、`/terms`，`target="_blank"` 新窗打开）。注册成功 → `router.push("/login")` 跳登录页
- **技术栈**：RSC + `RegisterForm` 客户端组件（`modules/auth/components/register-form.tsx`）+ `registerAction` Server Action（`modules/auth/actions`）+ `next-intl`（`useTranslations("auth.register")`）+ shadcn UI（Button / Input / Label / Checkbox / Select）+ `notify` toast + `lucide-react` Loader2
- **ARCHITECTURE.md 契约**：❌（§9.5 line 723 缺口新增，B2/B5 末 N）。portal-shell 当前无 `/register` 路由、无 auth 模块（仅有 `api/auth/login` + `api/auth/logout` 两个 Route Handler），注册走 iam 后端但前端页面与 Server Action 完全缺失
- **多角色复用**：公开页（未登录用户），不涉及角色权限
- **优先级**：B5 末

---

### 2.10 /privacy（隐私政策）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(auth)\privacy\page.tsx`（RSC，纯静态内容）
- **功能描述**：隐私政策页（K12 教育场景），7 个章节：引言 / 信息收集说明（账户 / 身份 / 未成年人保护 / 学习数据 / 设备）/ 信息使用说明 / 信息保护措施（bcrypt + AES + RBAC + DataScope + HTTPS）/ 用户权利（查询 / 更正 / 删除 / 撤回同意 / 可携带）/ Cookie 政策 / 未成年人保护条款（未满 14 周岁须监护人陪同注册）/ 联系方式。底部"返回注册"链接到 `/register`
- **技术栈**：RSC + `next/link` + shadcn UI（Card / CardHeader / CardTitle / CardDescription / CardContent）+ `Metadata`（SEO）+ 纯静态文案（无 DB / 无 Server Action / 无客户端交互）
- **ARCHITECTURE.md 契约**：❌（§9.5 line 723 缺口新增，B2/B5 末 N）。portal-shell 当前无 `/privacy` 路由；属纯静态页，无后端契约依赖，仅需补页面 + i18n 文案
- **多角色复用**：公开页（未登录用户，注册页链接到它）
- **优先级**：B5 末

---

### 2.11 /terms（服务条款）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(auth)\terms\page.tsx`（RSC，纯静态内容）
- **功能描述**：用户服务协议页，7 个章节：引言 / 服务说明 / 用户注册（真实邮箱 + 未成年人监护人陪同 + 同意隐私政策与本协议）/ 用户行为规范 / 知识产权 / 免责声明（AI 生成内容仅供参考，可能存在偏差）/ 服务变更中断与终止 / 法律适用与争议解决（中华人民共和国法律）。底部"返回注册"链接到 `/register`
- **技术栈**：同 §2.10（RSC + next/link + shadcn Card + Metadata + 纯静态文案，无 DB / 无 Server Action）
- **ARCHITECTURE.md 契约**：❌（§9.5 line 723 缺口新增，B2/B5 末 N）。portal-shell 当前无 `/terms` 路由；纯静态页，无后端契约依赖
- **多角色复用**：公开页（未登录用户，注册页链接到它）
- **优先级**：B5 末

---

### 2.12 /onboarding（首次登录引导）

- **CICD 参考实现**：
  - 页面：`e:\desktop\CICD\src\app\(onboarding)\onboarding\page.tsx`（RSC + auth guard）
  - 路由组 loading：`e:\desktop\CICD\src\app\(onboarding)\loading.tsx`（骨架屏，匹配 stepper 卡片布局）
  - 模块：`e:\desktop\CICD\src\modules\onboarding\`（data-access / actions / schema / components / hooks / types）
  - ⚠️ `e:\desktop\CICD\src\app\api\onboarding\status\route.ts` 已 **@deprecated**（返回 410 Gone，已迁移到 Server Action `getOnboardingStatusAction`，保留仅为兼容性指示）
  - 注：`(onboarding)` 路由组下有 `loading.tsx`（组根级骨架屏）+ `onboarding/page.tsx`（子目录页），并非"无 page.tsx"
- **功能描述**：首次登录引导页。`getAuthContext()` 鉴权（未登录捕获 `PermissionDeniedError` → `redirect("/login")`）→ 读 DB `users.onboardedAt` 判断是否需要引导（`getOnboardingStatus`，DB 为唯一真相源，废弃 `session.user.onboarded` 冗余检查）→ 不需要则 `redirect("/dashboard")` → 需要则渲染 `OnboardingStepper`（`Suspense` 包裹，支持 `useSearchParams` URL query 持久化步骤）。按角色差异化步骤：
  - 通用：更新基础资料（姓名 / 电话 / 住址）
  - 学生：通过邀请码绑定班级（`enrollStudentByInvitationCode`）
  - 教师：通过邀请码绑定任课科目（`enrollTeacherByInvitationCode`，P0-3 多选循环绑定，修复 UI 多选但服务端只取第一个的 bug）
  - 家长：三因子验证绑定子女（邮箱 + 生日 YYYY-MM-DD + 手机后 4 位，组合空间 365×10000=3.65M 防枚举；支持多子女循环绑定 P1-4）
- **技术栈**：
  - RSC + `getAuthContext()`（`PermissionDeniedError` → redirect /login）+ `Suspense` + `OnboardingStepper` 客户端组件
  - data-access（`modules/onboarding/data-access.ts`，server-only）：`getOnboardingStatus`（`cacheFn` 300s，读 `users.onboardedAt` + `usersToRoles` + `roles`）/ `getUserOnboardedAt`（P0-5 幂等检查）/ `markUserOnboarded` / `updateUserProfile` / `bindParentToChild`（三因子验证 + 幂等）
  - Server Actions（`modules/onboarding/actions.ts`）：`getOnboardingStatusAction` + `completeOnboardingAction`（Zod `OnboardingSchema` 校验 / P0-5 服务端幂等已完成直接返回成功 / P1-2 局部失败收集不回滚整事务 / P0-4 审计日志 `onboarding.complete` / audit-P1-8 家长绑定速率限制每小时 5 次防三因子枚举 / `invalidateFor("onboarding.complete")` 缓存失效）
  - 跨模块：`modules/classes/data-access`（`enrollStudentByInvitationCode` / `enrollTeacherByInvitationCode`，含校验）
  - 表：`users.onboardedAt` / `usersToRoles` / `roles` / `parentStudentRelations`
- **ARCHITECTURE.md 契约**：❌（§9.5 line 723 缺口新增，B2/B5 末 N）。portal-shell 当前无 `/onboarding` 路由、无 onboarding 模块；iam 子图已有 `userProfile`，但 onboarding 状态查询（`onboardedAt`）与家长绑定子女（`parentStudentRelations`）契约需补；班级邀请码绑定依赖 classes 服务
- **多角色复用**：所有新注册的已登录用户（按角色差异化步骤：学生绑定班级码 / 教师绑定任课科目 / 家长绑定子女）；管理员一般预分配 onboarded，跳过引导
- **优先级**：B5 末

---

## 三、按角色复用矩阵

| 共享页面                        | 教师 | 学生 | 家长 | 管理员 | 备注                                             |
| ------------------------------- | ---- | ---- | ---- | ------ | ------------------------------------------------ |
| `/shell/notifications`          | ✅   | ✅   | ✅   | ✅     | 全角色，复用 `MESSAGE_READ` 权限点               |
| `/shell/settings`               | ✅   | ✅   | ✅   | ✅     | 全角色，`resolveRoleSettingsConfig` 注入角色卡片 |
| `/shell/settings/security`      | ✅   | ✅   | ✅   | ✅     | 全角色，密码修改 + 安全提示                      |
| `/shell/announcements`          | ✅   | ✅   | ✅   | ⚠️     | 管理员走 `/shell/admin/announcements` 管理端     |
| `/shell/announcements/[id]`     | ✅   | ✅   | ✅   | ⚠️     | 同上，管理员走管理端                             |
| `/shell/messages`               | ✅   | ✅   | ✅   | ✅     | 全角色私信；教师额外有群发入口                   |
| `/shell/messages/compose`       | ✅   | ✅   | ✅   | ✅     | 全角色可发起私信                                 |
| `/shell/messages/[id]`          | ✅   | ✅   | ✅   | ✅     | 全角色可查看自己参与的消息线程                   |
| `/shell/messages/group-compose` | ✅   | ❌   | ❌   | ⚠️     | 仅教师（按所教班级）+ 管理员                     |
| `/shell/profile`                | ✅   | ✅   | ✅   | ✅     | 全角色，底部概览按角色切换                       |

---

## 四、契约就绪情况（ARCHITECTURE.md §9.5）

| 共享页                             | 契约状态 | 后端子图  | 备注                                                                              |
| ---------------------------------- | -------- | --------- | --------------------------------------------------------------------------------- |
| `/shell/notifications`             | ✅       | msg       | `notifications(userId)` 已就绪；形状待 P1-7 修正（平铺数组 vs `{items,total}`）   |
| `/shell/settings`                  | ✅       | iam / msg | `userProfile` + `notificationPreferences` 已就绪                                  |
| `/shell/settings/security`         | ✅       | iam       | 密码修改走 iam，2FA 走 iam                                                        |
| `/shell/announcements`             | ❌       | content   | 列表契约缺失，需 content 子图补 `announcements(userScope)` 查询                   |
| `/shell/announcements/[id]`        | 🟡       | content   | `announcement(id)` 存在，可见性语义需对齐                                         |
| `/shell/messages`                  | ❌       | msg       | messages 查询契约完全缺失，需 msg 子图补 `messages(userId)` / `messageThread(id)` |
| `/shell/messages/compose` / `[id]` | ❌       | msg       | 同上，依赖 messages 契约                                                          |
| `/shell/profile`                   | ✅       | iam       | `userProfile` 已就绪；角色概览查询待补（学生/教师）                               |

> 节奏原则（§9.5）：契约就绪页先行；❌ 页用 MSW 先上 UI，契约工单跟踪后端补齐后切换真实查询。

---

## 五、portal-shell 现状盘点（已具备 / 待补齐）

### 5.1 已具备（可复用）

| 资产              | 路径                                               | 说明                               |
| ----------------- | -------------------------------------------------- | ---------------------------------- |
| 通知铃铛 widget   | `widgets/topbar/notification-bell/index.tsx`       | 顶栏下拉，调 `useNotificationBell` |
| 通知列表 widget   | `widgets/universal/notifications-widget/index.tsx` | 仪表盘内嵌，调 `useNotifications`  |
| 通知 GraphQL 文档 | `lib/api/operations/universal.graphql.ts`          | `GET_NOTIFICATIONS_LIST_DOC`       |
| 通知 hook         | `lib/api/universal.ts` → `useNotifications`        | 形状待 P1-7 修正                   |
| 顶栏通知 hook     | `lib/api/topbar.ts` → `useNotificationBell`        | 用于铃铛                           |
| 403 页            | `app/shell/forbidden/page.tsx`                     | ✅ 已就绪                          |
| 角色仪表盘分发    | `app/shell/page.tsx`                               | ✅ 已就绪（按角色 redirect）       |

### 5.2 待补齐（缺失）

| 缺失项                                                                | 影响                                                                                                           |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `app/shell/notifications/page.tsx` + `error.tsx` + `loading.tsx`      | 通知中心整页                                                                                                   |
| `app/shell/settings/page.tsx` + `error.tsx` + `loading.tsx`           | 设置主页                                                                                                       |
| `app/shell/settings/security/page.tsx` + `error.tsx` + `loading.tsx`  | 安全中心子页                                                                                                   |
| `app/shell/announcements/page.tsx` + `error.tsx` + `loading.tsx`      | 公告列表                                                                                                       |
| `app/shell/announcements/[id]/page.tsx` + `error.tsx` + `loading.tsx` | 公告详情                                                                                                       |
| `app/shell/messages/page.tsx` + `error.tsx` + `loading.tsx`           | 消息列表（含通知区）                                                                                           |
| `app/shell/messages/compose/page.tsx` + `loading.tsx`                 | 撰写消息                                                                                                       |
| `app/shell/messages/[id]/page.tsx` + `loading.tsx`                    | 消息详情                                                                                                       |
| `app/shell/messages/group-compose/page.tsx` + `loading.tsx`           | 教师群发                                                                                                       |
| `app/shell/profile/page.tsx` + `error.tsx` + `loading.tsx`            | 个人资料                                                                                                       |
| `modules/notifications/` 整模块                                       | 通知 data-access / actions / dispatcher / channels / hooks                                                     |
| `modules/messaging/` 整模块                                           | 消息 data-access / actions / components / hooks                                                                |
| `modules/announcements/` 整模块（用户端）                             | 公告 data-access / actions / components                                                                        |
| `modules/settings/` 整模块                                            | 设置 components / actions / config / lib                                                                       |
| `shared/lib/navigation.ts` 入口登记                                   | 5 个共享路由均未登记到 `NAVIGATION_ITEMS`                                                                      |
| `shared/lib/route-permissions.ts` 权限登记                            | 5 个共享路由均未登记到 `EXACT_ROUTE_PERMISSIONS` / `PREFIX_ROUTE_PERMISSIONS`，按 fail-closed 规则会被默认拒绝 |
| i18n key（`messages/zh-CN.json` / `en.json`）                         | `notifications.*` / `settings.*` / `announcements.*` / `messages.*` / `settings.profile.*` 文案键缺失          |

---

## 六、实施建议（按批次与优先级）

### 6.1 B1 优先（契约就绪，可直接接真实查询）

1. **`/shell/notifications`**：复用现有 `useNotifications` hook，新增 page + error + loading；同步登记 `EXACT_ROUTE_PERMISSIONS`（`requiredPermissions: ["MESSAGE_READ"]`，不限角色）+ `navigation.ts`（建议放在顶栏 / 通用区分组，但因 `NAVIGATION_ITEMS` 按角色 group，需考虑通用入口的 group 归属——或只在顶栏铃铛加"查看全部"链接跳到 `/shell/notifications`）
2. **`/shell/settings`** + **`/shell/settings/security`** + **`/shell/profile`**：三者强关联（profile 复用 settings 模块的 `AvatarUpload` / 角色概览组件），建议一次性补齐；需新建 `modules/settings/` 模块（22+ 客户端组件 + Server Actions）

### 6.2 B3（契约缺失，先用 MSW 上 UI）

1. **`/shell/announcements`** + **`/shell/announcements/[id]`**：列表契约缺失，需先用 MSW mock `announcements(userScope)` 查询；`announcement(id)` 已存在但可见性语义需对齐
2. **`/shell/messages`** + 子页：messages 契约完全缺失，需 msg 子图补 `messages(userId)` / `messageThread(id)` / `sendMessage` mutation 等；建议 B3 末实施

### 6.3 强制同步项（每次新增路由必做）

- `shared/lib/route-permissions.ts`：新增 `EXACT_ROUTE_PERMISSIONS` 条目（否则 fail-closed 拒绝）
- `shared/lib/navigation.ts`：如需侧边栏入口，新增 `NAVIGATION_ITEMS` 条目
- i18n：`messages/zh-CN.json` + `messages/en.json` 补对应文案键
- `pnpm run arch:scan` 更新 arch.db（按 project_rules §1 强制）
- 若架构设计意图变化，同步更新 `ARCHITECTURE.md` §9

---

## 七、关键风险与约束

1. **fail-closed 风险**：`route-permissions.ts` §5 规定 `/shell/**` 下未登记路由默认拒绝。若只加 page.tsx 不登记权限，访问会被 middleware 重定向到 `/shell/forbidden`。
2. **通知形状待修正**：`notifications(userId)` 后端返回平铺数组，前端按 `{items, total}` 解析（P1-7 待修）。B1 实施时需同步修正 `universal.graphql.ts` 与 `universal.ts` 的类型，或后端补齐 `{items, total}` 包装。
3. **消息撤回不乐观更新**：CICD 的 `recallMessageAction` 必须服务端校验 2 分钟窗口（`MESSAGE_RECALL_WINDOW_MS = 2 * 60 * 1000`），禁止 `useOptimistic` 乐观更新（会导致超时撤回误成功）。B3 实施时必须遵循此约束。
4. **公告可见性越权（P0-1）**：`getAnnouncementByIdForUser` 必须在 data-access 层结合受众 + status 过滤，不可见时统一返回 404（不暴露存在性）。B3 实施时必须复刻此守卫。
5. **消息收件人二次校验（P0-1）**：Server Action 必须调 `isReceiverAllowed` 校验 `receiverId` 在 sender 的 `DataScope` 内，防 UI 绕过越权。
6. **群发 fan-out on write**：群发时每条收件人写独立行，共享同一 `groupMessageId`，避免读时聚合。
7. **多 AI 模块边界**：按 project_rules §14.2，通知/消息/公告/设置分属不同模块，需协调 AI 分工；`shared-proto` 契约变更由协调 AI 负责。
8. **profile 归属 settings 模块**：CICD 中 `profile` 页复用 `modules/settings/components/avatar-upload` 与 `profile-{student,teacher}-overview`，实施时不能跳过 settings 模块直接做 profile。

---

## 八、根路径重定向说明（隐含覆盖页）

| 路径      | 实现位置                             | 行为                                                                              | CICD 对照                                                                         |
| --------- | ------------------------------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `/`（根） | `apps/portal-shell/src/app/page.tsx` | `redirect("/shell")` → 再由 `/shell` catch-all 按角色 redirect 到 `/shell/{role}` | CICD `src/app/page.tsx` 直接 `redirect("/dashboard")`（教师仪表盘，无角色分发层） |

> 说明：portal-shell 比 CICD 多一层"角色分发"——根 `/` → `/shell` → `/shell/{role}`，因为 portal-shell 是多角色统一入口（教师 / 学生 / 家长 / 管理员共用一个 app），而 CICD 默认进入教师仪表盘。此页属"隐含覆盖"（§一 总览未单列），已在 §一 `/shell` 行标注 CICD 参考路径。portal-shell `src/app/page.tsx` 当前已就绪（`redirect("/shell")`，portal-shell spec §8.2 路由前缀 `/shell/*`），无需补齐。