xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
240 Commits 2 Branches 8 Tags
081cb5fbc38bfd1635e3c7e860f723914539577c
Commit Graph

67 Commits

Author SHA1 Message Date
SpecialX
081cb5fbc3 feat(portal-shell): homework 模块 7 页迁移（教师域 §9.1 B2） 
§9.1 教师域 homework 模块完整迁移（继 exams 之后第二个 B2 模块）：

7 页路由结构（与旧 teacher-portal 同构）：
- /shell/teacher/homework：列表页（?classId/status/q 筛选）
- /shell/teacher/homework/new：布置作业表单页
- /shell/teacher/homework/[id]：详情 + 内联批改（含提交列表 + recordGrade 表单）
- /shell/teacher/homework/submissions：跨作业提交评审列表
- /shell/teacher/homework/submissions/[submissionId]：单份提交批改 + AI 建议 + 上下份导航
- /shell/teacher/homework/submissions/[submissionId]/scan-grading：扫描批改工作台（三栏）
- /shell/teacher/homework/assignments/[id]/submissions：按作业批量批改 + 统计 + AI 批量评分

数据契约（混合）：
- ✅ homework(id: ID!) 真实查询（schema 已就绪，详情页用）
- ❌ 列表/mutation/submissions/grading/aiBatchGrading 全部 @contract-pending MSW 兜底
  · 9 个 hook 走 MSW，待后端补齐 mutation 后切换真实 fetcher

§11.3 DoD 11 项验收：
1. route-permissions：EXACT + PREFIX 表 /shell/teacher/homework 已配置
2. 页面模板：list/new 用 ListPageShell/FormPageShell；detail/grading 用 DetailPageShell；
   scan-grading 用 WorkbenchPageShell（三栏，未使用 emptyNode）
3. 三态：loading(Skeleton)/error(errorNode 或 errorSummary)/empty(emptyNode) 全实现
4. lib/api hooks：homework.ts 10 个 hooks（useHomework 真实 + 9 个 MSW）
5. @contract-pending MSW：graphql-data.ts 扩展 6 块 mock + 10 个 switch case
6. i18n：homework 节点扩展 8 个分区共 130+ keys（list/detail/new/submissions/grading/
   scan/assignment/error）中英对齐
7. lint：0 errors（4 warnings 在 __generated__）
8. lint:tokens：0 errors
9. notify：mutation 反馈走 @/shared/lib/notify（非 sonner 直引）
10. vitest：transformations 纯函数单测齐全，全量 323/323 通过（新增 ~50 测试）
11. typecheck：0 errors（noUncheckedIndexedAccess 安全访问）

附带修复：
- 修复 2 处遗留 broken link：
  · widgets/sidebar/quick-actions: /homework/new → /shell/teacher/homework/new
  · widgets/topbar/global-search: /homework → /shell/teacher/homework
- scripts/check-page-count.ts baseline 同步 13 → 26（与 exams 6 + homework 7 一致）

剩余模块：grades(5)+lesson-plans(6)+questions(1)+textbooks(2)+attendance(4)+classes(3)+
students(1)+course-plans(2)+elective(3)+error-book(1)+diagnostic(2)+analytics(2)+ai-*(3)+
knowledge-graph(1)+practice(1)+schedule-changes(1)+leave(1) 共 39 页。
 2026-07-22 18:11:15 +08:00
SpecialX
dca25fc42f feat(portal-shell): exams 三子页面迁移（analytics/build/edit） 
§9.1 教师域 exams 模块补完（继 d066da5 列表/详情/表单后）：
- /shell/teacher/exams/[id]/analytics：详情页（图表）- 混合契约
  · 基础统计 ✅ assignmentAnalysis（data-ana 子图，schema 已就绪）
  · 扩展字段（排名/每题正确率）❌ MSW 兜底（@contract-pending）
  · 含 Summary/Distribution/QuestionAccuracy/Rankings 四区
- /shell/teacher/exams/[id]/build：工作台页（组卷）@contract-pending
  · 三栏：题库候选 / 已选题目 / 预览
  · 支持搜索/类型/难度筛选，添加/移除/上移/下移/改分
- /shell/teacher/exams/[id]/edit：工作台页（富文本试卷）@contract-pending
  · contentEditable + 工具栏（B/I/U/H1-H3/列表）
  · 右栏试卷属性面板

§11.3 DoD 11 项验收：
1. route-permissions：PREFIX 表 /shell/teacher/exams/ 已覆盖
2. 页面模板：analytics 用 DetailPageShell；build/edit 用 WorkbenchPageShell
3. 三态：loading/error/empty 均实现（workbench 用 errorNode 合并 empty）
4. lib/api hooks：useExamAnalytics/useExamBuild/useQuestionsLibrary/
   useSaveExamBuild/useExamRichEditor/useSaveExamRichContent 6 个
5. @contract-pending MSW 模式：graphql-data.ts 扩展 6 个 case
6. i18n：analytics(19 keys)+build(28 keys)+edit(13 keys) 中英对齐
7. lint：0 errors（4 warnings 在 __generated__）
8. lint:tokens：0 errors
9. notify：success/error/warning 走 @/shared/lib/notify（非 sonner 直引）
10. vitest：transformations 新增 10 函数 22 测试，全量 273/273 通过
11. typecheck：0 errors（noUncheckedIndexedAccess 安全 swap 写法）

剩余：proctoring 标注"二期 WS"按 §9.1 暂缓。
 2026-07-22 17:38:51 +08:00
SpecialX
d066da563f feat(portal-shell): 教师域考试管理页面迁移（P2） 
按 ARCHITECTURE.md §9.1/§10 P2 要求，迁移教师域 exams 模块：
- 列表页 /shell/teacher/exams（ListPageShell + URL 状态 + 客户端二次筛选）
- 详情页 /shell/teacher/exams/[id]（DetailPageShell + 真实 exam(id) 查询）
- 新建页 /shell/teacher/exams/new（FormPageShell + MSW 兜底）
- 纯函数 transformations.ts + 19 个 vitest 单测
- @contract-pending：exams(classId) 列表查询、createExam mutation 走 MSW
- 三态 UI（loading/error/empty）+ 路由级 loading.tsx/error.tsx
- i18n：zh-CN/en 双语补全，无硬编码中文
- MSW handlers 支持 variables 透传

§11.3 DoD 验收：
- lint: 0 errors（4 个 __generated__ 预存警告）
- typecheck: 0 errors
- test: 250/250 passed（含 19 个新增 transformations 测试）
- lint:tokens: 0 errors
 2026-07-22 17:02:05 +08:00
SpecialX
92f24e2e91 docs(portal-shell): align P1-7 acceptance criteria with actual scope 2026-07-22 16:10:52 +08:00
SpecialX
7c511e74bd feat(portal-shell): add CI structural checks for routes, pages, codegen (P1-8) 
ARCHITECTURE.md §10 P1-8: three structural checks wired into CI to
prevent regressions identified in the §1.3 audit.

Scripts (apps/portal-shell/scripts/):
- check-route-table.ts: scans src/app/shell/**/page.tsx, parses
  route-permissions.ts (EXACT/PREFIX/DASHBOARD/PUBLIC_ROUTES), fails
  if any actual /shell/* route is unregistered. Reports ghost entries
  (EXACT declarations without page.tsx) as informational.
- check-page-count.ts: asserts total page.tsx >= 13 and per-category
  minimums (dashboards/login/root/forbidden/catch-all/dev-templates).
- check-codegen.ts: runs pnpm run codegen, fails if any output with
  skipDocumentsValidation:false has operations referencing non-existent
  schema fields (currently enforces dashboard-types.ts output from P1-7).

npm scripts: check:routes / check:pages / check:codegen / check:all

CI: .github/workflows/ci.yml quality-ts job — new "Portal-shell
structural checks (P1-8)" step between typecheck and test.

Acceptance (ARCHITECTURE.md §10 P1-8 — "CI 对预埋违规报红"):
- Route violation: planted /shell/test-violation/page.tsx → check:routes
  exits 1 with "unregistered route" error; reverted → PASS
- Codegen violation: planted non_existent_field in GetTeacherDashboard →
  check:codegen exits 1 with "Cannot query field" error; reverted → PASS
- Page count: baseline=13, deleting any page.tsx triggers FAIL
- Clean state: all 3 checks PASS (10 routes, 28 EXACT, 24 ghost entries
  informational, 13 pages, codegen 3 outputs SUCCESS)

Refs: ARCHITECTURE.md §5.3, §10 P1-8, §11.6, §11.7 红线 #5
 2026-07-22 15:57:58 +08:00
SpecialX
0beeff6329 feat(portal-shell): restore codegen typescript-operations for data-ana domain (P1-7) 
ARCHITECTURE.md §10 P1-7: dashboard domain's 6 operations strictly
match the schema, so disable skipDocumentsValidation for that output
and restore per-operation type generation.

Changes:
- codegen.yml: add dashboard-types.ts output (typescript +
  typescript-operations plugins, skipDocumentsValidation: false);
  move documents config into each generates entry
- dashboard.ts: remove 14 handwritten interfaces and 6 internal query
  type aliases; derive types via NonNullable<GetXxxQuery['xxx']> so
  the public hook API shape stays unchanged
- admin/student/teacher page.tsx: add ?? "--" / ?? 0 null guards on
  StatCard value props to match schema nullable semantics (parent page
  already uses toFixed chain, no change needed)

Acceptance (ARCHITECTURE.md §10 P1-7):
- codegen 3 outputs all SUCCESS
- tsc 0 errors / eslint 0 errors / vitest 231 passed / next build ok
- 6 operations strictly match schema with 0 errors

Refs: ARCHITECTURE.md §5.3 data layer / §10 P1-7
 2026-07-22 15:37:06 +08:00
SpecialX
a28a6bd6ea feat(portal-shell): clean widget design tokens and fix lint:tokens (P1-6) 
516 mechanical replacements across 25 widget files:
- spacing xs/sm/md/lg/xl to numeric 1/2/3/4/6
- text-heading-3 to text-lg font-semibold
- bg-danger to bg-destructive
- border border dedup

Fix .eslintrc.tokens.js to use typescript-eslint parser (was importing
uninstalled @typescript-eslint/parser). lint:tokens now passes.
 2026-07-22 15:07:38 +08:00
SpecialX
9358372657 feat(portal-shell): add MSW mock layer with production bundle exclusion (P1-5) 
MSW v2.7.0 fallback layer covering dashboard/users/exams/grades domains.
NEXT_PUBLIC_MSW=1 enables browser Service Worker + SSR route handler mock
responses without backend. Production build excludes all mock data via
Turbopack resolveAlias redirecting @/mocks to empty stub.

Acceptance: build bundle (client+server) verified clean of mock strings;
typecheck/lint/vitest (231 tests) all pass.
 2026-07-22 14:48:30 +08:00
SpecialX
da05c9107a feat(portal-shell): integrate next-intl + merge messages from teacher-portal (P1-4) 
- Add next-intl v4.13.2 with cookie-based locale (no i18n routing)
- Create src/i18n/request.ts reading NEXT_LOCALE cookie
- Merge zh-CN/en messages from teacher-portal + add shell.dev.templates namespace
- Wrap next.config.js with withNextIntl plugin (Turbopack resolveAlias)
- Refactor RootLayout to async + NextIntlClientProvider + getLocale/getMessages
- Replace ThemeI18nProvider with ThemeProvider (theme-only, i18n removed)
- Remove locale/setLocale from PluginStore
- Rework locale-switcher to useLocale/useTranslations + router.refresh
- Update dev/templates page to use getTranslations (Server Component)
- Fix WorkbenchPageShell test (loading prop + center instead of children)

Verified: locale switch via NEXT_LOCALE cookie changes <html lang> and messages
zh-CN: 保存/取消/切换侧栏 | en: Save/Cancel/Toggle sidebar
typecheck 0 errors | lint 0 errors 2 warnings (generated) | vitest 231 passed
 2026-07-22 13:40:44 +08:00
SpecialX
994441c2dc feat(portal-shell): add page templates quartet (list/detail/form/workbench) (P1-3) 
P1-3 验收通过：4 个页面模板 + 4 个 dev 示例页 + 三态规范。

新增文件：
- src/shared/components/page-templates/
  - list-page.tsx：ListPageShell + ListPageSkeleton
  - detail-page.tsx：DetailPageShell + DetailSection + DetailField + DetailPageSkeleton
  - form-page.tsx：FormPageShell + FormPageSkeleton
  - workbench-page.tsx：WorkbenchPageShell + WorkbenchPanel + WorkbenchPageSkeleton
  - index.ts：barrel 导出
- src/app/shell/dev/templates/
  - page.tsx：索引页（4 个模板入口）
  - list/page.tsx：列表页示例（支持 ?state=loading|empty|success）
  - detail/page.tsx：详情页示例
  - form/page.tsx：表单页示例
  - workbench/page.tsx：工作台页示例
- src/shared/components/__tests__/page-templates.test.tsx：19 个单测

修改文件：
- src/shared/lib/route-permissions.ts：新增 PREFIX /shell/dev/（空 config = 仅校验登录）
- ARCHITECTURE.md：P1-3 状态回填 ✅ + 验收证据

路径命名修正：
- 原 ARCHITECTURE.md 写 /shell/_dev/templates/*，但 Next.js 将下划线开头的
  文件夹视为"私有文件夹"（不参与路由），实测被 [[...route]] catch-all 兜底接管。
- 改用 dev 命名后，显式路由优先匹配，catch-all 不再触发。

三态规范验证：
- GET /shell/dev/templates/list?state=loading → 200，含 animate-pulse 骨架
- GET /shell/dev/templates/list?state=empty → 200，含"暂无数据"空态
- GET /shell/dev/templates/list（默认 success）→ 200，含表格数据

质量校验：
- tsc --noEmit 通过
- eslint（新/改文件）通过
- vitest run 全量 21 test files / 231 tests 全部通过（212 原有 + 19 新增）

Refs: apps/portal-shell/ARCHITECTURE.md §7.3 页面四种类型与模板、
      §7.4 页面级数据获取模式、§11.3 每页硬性清单（DoD）三态规范
 2026-07-22 13:02:11 +08:00
SpecialX
03e3ec4f60 fix(portal-shell): wrap sidebar in client component to respect RSC boundary 
P1-1 regression introduced by layout.tsx RSC refactor: navigation.ts
exports `icon: LucideIcon` (function refs) which cannot cross the RSC
boundary from a Server Component to a Client Component.

Fix:
- Introduce ShellSidebar (Client Component) that owns the navigation
  filtering + icon refs entirely on the client side.
- layout.tsx (RSC) now only passes serializable strings (`role` and
  `permsBitmap`) to ShellSidebar; no function references cross the
  boundary.

Error before fix:
  Error: Functions cannot be passed directly to Client Components
  unless you explicitly expose it by marking it with "use server".
  {$$typeof: ..., render: function LayoutDashboard}

Refs: apps/portal-shell/ARCHITECTURE.md §7.2 AppFrame, §10 P1-1,
      §11.7 red line #5 (fail-closed identity).
 2026-07-22 12:47:00 +08:00
SpecialX
98058eb16b feat(portal-shell): wire dashboards to real data-ana queries (P1-2) 
- add dashboard.graphql.ts with 6 real aggregate queries
  (teacherDashboard / studentDashboard / parentDashboard /
   adminDashboard / warnings / errorBookStats), snake_case aligned
- add dashboard.ts with 6 hooks + full domain model types
- add 4 role dashboard pages (teacher/student/parent/admin)
  using DashboardShell + StatCard + DashboardSection with
  loading / error / success tri-state
- update [[...route]]/page.tsx to redirect /shell -> /shell/{role}
- retire 6 fake contract queries and hooks (grades/homeworks/
  schedule/attendance/exams/announcements) and mark widget
  placeholders as migrated
- update universal.test.ts to drop retired hook tests
- mark ARCHITECTURE.md P1-2 as completed with acceptance evidence
 2026-07-22 12:33:22 +08:00
SpecialX
f92fdf8efe feat(portal-shell): wire AppFrame + navigation + permission filter (P1-1) 
实现 ARCHITECTURE.md §10 P1-1：
- 新增 src/shared/lib/navigation.ts：27 项静态导航注册表，
  按 teacher/student/parent/admin 四角色分区，group 字段用于角色过滤
- 新增 src/app/shell/layout.tsx：RSC AppFrame，从 headers() 读取
  middleware 注入的身份头，batchCheckRoutePermission 按位图二次过滤
- 新增 src/shared/components/layout/user-menu.tsx：顶部用户菜单，
  显示 userId + role，登出 POST /api/auth/logout
- 新增 src/shared/lib/__tests__/navigation.test.ts：P1-1 验收单测
  （7 用例：href 登记一致性 + 4 角色隔离 + 权限检查）
- 修改 src/shared/lib/route-permissions.ts：补全 7 个列表页根路由
  的 EXACT 登记（/shell/admin/announcements、/shell/admin/classes、
  /shell/teacher/exams 等），与 PREFIX 表互补避免 catch-all 拒绝

验收：
- vitest run navigation → 7/7 passed
- tsc --noEmit 通过；eslint（5 文件）通过

回填 ARCHITECTURE.md §10 P1-1 状态为 ✅，附验收证据。

关联：ARCHITECTURE.md §7.2 AppFrame / §10 P1-1
 2026-07-22 12:17:16 +08:00
SpecialX
dc13a2afb4 docs(portal-shell): backfill ARCHITECTURE.md §10 P0 completion status 
- §10 P0 表格新增"状态"列，全部标记 ✅
- 新增"P0 验收证据（2026-07-22）"小节，逐条附命令/文件引用
- 文档头部状态行从"待实施"改为
  "P0 已完成 + P1 进行中"
- 验收依据：
  P0-1 login API 401 实测
  P0-2 middleware + forbidden page 代码
  P0-3 localStorage 仅匹配删除注释
  P0-4 getDefaultConfig 实现
  P0-5 instrumentation register() 实现
  P0-6 vitest 27/27 通过
  P0-7 eslint 0 errors
  P0-8 git status 干净
 2026-07-22 11:42:02 +08:00
SpecialX
cfb7b005fd feat(portal-shell): v2.1 P0 auth + middleware + login + graphql proxy 
- 新增 ARCHITECTURE.md v3.0：portal-shell 架构权威文档
  涵盖 §3.4 V3-A2/A3 认证链、§4 GraphQL 联邦、§5 安全、
  §6 部署、§10 P0-P3 验收清单
- 新增 middleware.ts：认证 + 路由门禁
  httpOnly cookie edu_session（JWT）读取
  DEV_MODE 合成 dev-user/teacher 身份（NODE_ENV!=production &&
  NEXT_PUBLIC_DEV_MODE=true）
  生产模式 jose JWKS RS256 验签（iss/aud 校验）
  路由权限位图注入 x-user-id/x-user-role/x-user-permissions 头
  /shell/** 强制 checkRoutePermission，拒绝跳 /shell/forbidden
- 新增 instrumentation.ts：生产环境 DEV_MODE 强制 false
  防止生产环境误开 DEV_MODE 合成身份
- 新增 app/api/auth/login/route.ts + logout/route.ts
  登录走 api-gateway /v1/iam/login
  设置 httpOnly + Secure + SameSite=Strict cookie
- 新增 app/api/graphql/route.ts：同域 GraphQL 代理
  转发到 apollo-router，注入 router-authorization 头
- 新增 app/login/page.tsx + login-form.tsx
  zod 表单校验，next 参数支持
- 新增 app/shell/forbidden/page.tsx：403 页面
- 更新 route-permissions.ts：补全 P0 路由权限映射
- 更新 permission-bitmap.ts（shared-ts）：位图编码/解码
- 更新 apollo-client.ts：DEV_MODE APQ 关闭，错误处理
- 更新 config-fetcher.ts：config-service 直连降级
- 更新 ApolloProvider.tsx：SSR/RSC 兼容
- 更新 eslint.config.js：design-tokens/no-hardcoded-fonts
  白名单调整
 2026-07-22 11:35:36 +08:00
SpecialX
f586a0b19e feat(portal-shell): v2.0 P1-P4 token migration + unit tests + prod endpoint + e2e 
P1: 31 widget 旧纸感令牌批量迁移到 shadcn 标准（1104 次替换）
- bg-paper→bg-background / bg-surface→bg-card / text-ink→text-foreground
- 保留 button.tsx 中 bg-accent（shadcn 标准 hover 语义令牌）

P2: v2.0 新增组件单元测试补齐（5 文件 81 用例）
- permission-bitmap: 24 用例（含 GRADE_READ 重复去重）
- route-permissions: 26 用例（4 张表优先级 + AND/OR 语义）
- notify: 12 用例（sonner toast 双重性质 vi.hoisted mock）
- use-error-report: 9 用例（jsdom Blob vi.stubGlobal mock）
- plugin-boundary: 10 用例（错误边界 + 骨架变体）

P3: 错误上报端点生产替换（后端 /api/v1/log）
- api-gateway: internal/log/handler.go（slog 结构化日志，64KB 限制，204 返回）
- main.go: 注册 POST /api/v1/log 路由
- useErrorReport: 环境感知端点（prod→/api/v1/log，dev→/api/log）

P4: E2E 测试（3 文件 30 用例）
- streaming: 4 用例（React 19 use() + Suspense，act 包裹 render）
- error-boundaries: 6 用例（三级错误边界层级 L1/L2/L3）
- security-boundaries: 20 用例（L1 角色门禁 + L2 权限点 + L3 数据范围）
- vitest setup: IS_REACT_ACT_ENVIRONMENT + jest-dom matchers

验证：typecheck 0 错误 / lint 0 错误 / build 6 路由 / 206 测试全部通过
 2026-07-17 16:49:00 +08:00
SpecialX
9cedf0c437 feat(portal-shell): v2.0 P0 shadcn standardization + security + streaming + error handling 
- shadcn/ui 标准化：废弃纸感令牌，统一 bg-background/text-foreground 等
- Tailwind v4 + @theme inline，移除 tailwind.config.js
- React 19 use() + Suspense 流式渲染，首屏骨架秒出
- 三级错误边界：Route → Section → Widget 层层兜底
- 错误上报：useErrorReport → sendBeacon → /api/log mock 端点
- 三层安全边界：L1 角色门禁 / L2 权限点门禁 / L3 数据范围
- 权限位图 base36 压缩：67 权限点 → ~14 字符，JWT 体积减少 ≥ 99%
- notify 统一 Toast 封装，禁止业务直接 import sonner
- PluginBoundary 替代 PluginLoader（错误边界 + Suspense + Skeleton 三件套）

验证：typecheck 0 错误 / lint 0 错误 / build 6 路由生成成功
 2026-07-17 16:10:05 +08:00
SpecialX
f7e52b5b7f docs(portal-shell): update README to v1.1 with data layer and GraphQL hardening 
- 版本 1.0 -> 1.1，日期 2026-07-17
- 新增 §13 数据访问层与 GraphQL 安全栈（6 子节）
- 更新 §5/§9.6/§10/§11/§12/附录 A/B/C
- 修正 004 §16.5 测试数（admin 31->4，sidebar 5->9）
- arch:scan 通过（TS 20 模块/4803 符号）
 2026-07-17 13:47:40 +08:00
SpecialX
9bee920e4d test(portal-shell): add security stack tests for PQ manifest and APQ 
Covers v2.1 M3 安全加固验证：
- PQ Manifest 完整性（6 cases）：DocumentNode 校验、sha256 稳定性、确定性、唯一性、manifest 文件有效性、hash 一致性
- Query depth limit（2 cases）：11 层嵌套构造、合法查询构造（实际拒绝由 apollo-router limits.max_depth=10 执行）
- APQ behavior（2 cases）：默认启用、NEXT_PUBLIC_APOLLO_APQ=false 关闭

测试结果：95/95 passed (85 原有 + 10 新增)
 2026-07-17 13:35:37 +08:00
SpecialX
b30d43f983 feat(portal-shell): enable Apollo Client APQ + PQ manifest generator 
Task 12-13 of portal-shell data abstraction plan (M3 security).

APQ (Automatic Persisted Queries):
- Add createPersistedQueryLink with sha256 to apollo-client.ts
- Production: client sends only query hash, not plaintext query
- Dev: NEXT_PUBLIC_APOLLO_APQ=false to disable for debugging
- Prevents attackers from crafting arbitrary queries via DevTools

PQ Manifest generator:
- New scripts/generate-pq-manifest.ts iterates operations barrel
- Outputs public/pq-manifest.json (sha256 -> query text whitelist)
- prebuild hook: codegen + generate-pq-manifest before next build
- 51 queries currently registered

- crypto-hash dependency added
- typecheck + lint (0 errors) + test (85/85) verified
 2026-07-17 13:31:11 +08:00
SpecialX
2910a90271 feat(portal-shell): extract domain API layer and migrate 31 widgets 
Task 4-10 of portal-shell data abstraction plan (M1-M2).

Add 7 domain API modules under src/lib/api/ (parent/admin/teacher/
student/universal/sidebar/topbar), each exposing semantic hooks that
wrap useWidgetQuery/useWidgetMutation and return flattened domain
models. Widget code now imports from @/lib/api instead of inlining
gql literals.

- 31 widgets migrated (gql literal count in widgets: 0)
- 7 test files (85 cases, all passing)
- topbar.useNotifications renamed to useNotificationBell to avoid
  barrel export collision with universal.useNotifications
- typecheck + lint (0 errors) + test (85/85) verified
 2026-07-17 13:07:24 +08:00
SpecialX
f623dcf4a7 feat(portal-shell): extract gql documents to operations layer 
M1 Task 3: 从 31 widget 抽取 51 个 gql 文档到 7 个 operations 文件

- universal(7) + sidebar(3) + topbar(3) + teacher(6) + student(8) + parent(4) + admin(20) = 51 DOC

- operations/index.ts barrel 统一出口

- codegen.yml 启用 documents + skipDocumentsValidation（services 子图字段待补齐）

- 生成 types.ts (28KB) + operations.ts (10KB)
 2026-07-17 12:37:36 +08:00
SpecialX
7c234947e1 feat(portal-shell): add graphql-codegen configuration 
M1 Task 2: 配置 graphql-codegen 与 federation schema 预处理

- codegen.yml: schema 从 combined-schema.graphql 读取（federation 已剥离）

- scripts/normalize-schema.ts: 把 7 个子图的 extend type Query 合并为 type Query

- package.json: 新增 codegen/codegen:watch scripts + 4 个 codegen deps + tsx

- .gitignore: 忽略 src/lib/api/__generated__/

- documents 配置暂注释，Task 3 创建 operations 文件后启用
 2026-07-17 12:12:37 +08:00
SpecialX
989603e318 feat(portal-shell): add lib/api skeleton with errors and types 
M1 Task 1: 创建 4 层数据抽象层的骨架文件

- errors.ts: ApiError + GraphQLErrorCode 枚举

- types.ts: Pagination / PaginatedResult / UseQueryResult / UseMutationResult

- internal.ts: normalizeError 把 ApolloError 转为 ApiError

- index.ts: barrel 出口
 2026-07-17 12:06:01 +08:00
SpecialX
514e26ebb4 feat(portal-shell): implement portal-shell with apollo-router integration 
M8: portal-shell unified frontend shell (Modular Monolith + micro-kernel).

- Apollo Client -> apollo-router (port 4010, RSC prefetch)

- 5 layouts: classic/focus/split/triple/canvas

- Registry + PluginLoader (dynamic import ssr:false)

- 3-layer props merge, Zustand PluginStore

- 4 widgets: grades/notification-bell/user-menu/class-selector

- config-service: new pluginConfig GraphQL resolver

- apollo-router: CORS + header propagation for portal-shell

- docker-compose.yml: portal-shell service block
 2026-07-15 08:06:09 +08:00
SpecialX
81a539b9ab chore(deps): 统一依赖管理 - pnpm 11 + node:22 + golang:1.25 + python:3.12 + shared-* 集中化
Some checks failed
CI / quality-ts (push) Failing after 6s
Details
CI / quality-go (push) Failing after 25s
Details
CI / quality-proto (push) Failing after 6s
Details
CI / deploy (push) Has been skipped
Details 
- Node.js 统一到 node:22-alpine，Go 统一到 golang:1.25-alpine，Python 统一到 python:3.12-slim

- pnpm 升级到 11.13.0（corepack），新增 allowBuilds 白名单解决 ERR_PNPM_IGNORED_BUILDS

- 新增 packages/shared-py 集中 Python 共享依赖，shared-ts 补充 graphql-yoga/prom-client

- api-gateway 修复 go.mod 的 shared-go 依赖 + Dockerfile 改用 repo 根作 context

- Python 服务（data-ana/ai）Dockerfile 改用 repo 根作 context + 声明 uv workspace sources

- 16 个服务的 Dockerfile + CI + docker-compose.tools.yml 全部对齐版本矩阵

- known-issues.md 沉淀 9 条 pnpm 11 / uv workspace / Go shared-go 迁移经验

- 验证：4 服务完全成功（api-gateway /healthz 200），其余 install 成功（build 失败为预存 TS 错误）
 2026-07-14 12:04:49 +08:00
SpecialX
74077c7083 docs(parent-portal): 恢复 nextstep.md v1 原貌 + 新增 nextstep-v2.md 核查报告 
v1 保持原样（2026-07-13 初版下游待办）

v2 新增（2026-07-14 核查结果）：1 项已完成（pnpm-lock），4 项仍未完成（端点路径/Docker/schema/api-gateway 镜像）

v2 新发现：extended-resolvers.ts 存在但未集成且引用不存在的类型；parent-bff Dockerfile pnpm 版本未固定
 2026-07-14 10:14:43 +08:00
SpecialX
0066afc55e feat(teacher-portal): v2 下游核查 + push-gateway 接入 + 测试扩展至 87 + ui-components 12/12 
v2 核查结论：

- iam/push-gateway/api-gateway 已就绪

- teacher-bff teacher 域仍是 P2 占位（56/61 operations 不可用）

- 5 个 gRPC target 留空走降级模式 B

- 保留 MSW mock，记录 12 项 teacher-bff 待补工作到 nextstep-v2.md

v2 完成工作：

- push-gateway WebSocket 接入（环境变量 + URL query token + Reconnect 协议）

- 单元测试扩展（usePermission 15 + useAuth 9，总计 87/87 passed）

- ui-components 剩余 3 组件（Chart/Calendar/RichTextEditor，12/12）

- 设计令牌完整迁移（无 hsl/hex 字面量）

- i18n 5/55 页面 + 26 模块 key

- 性能优化（size-limit 9 项 + 5 页面懒加载）

- useAuth 迁移阻塞核查（iam 未实现 Set-Cookie，修正 v1 假设）

文档：新增 nextstep-v2.md；workline.md §5.7 添加 v2 工作记录。

验证：typecheck + lint + 87/87 tests + arch:scan 全部通过。
 2026-07-14 08:47:18 +08:00
SpecialX
ae6fe23be6 docs(student-portal): nextstep-v2 二次核查下游服务实现状态 2026-07-14 08:43:45 +08:00
SpecialX
21f2485749 docs(student-portal): nextstep-v2 核查下游服务实现状态+记录42个resolver未装配问题 2026-07-14 08:36:02 +08:00
SpecialX
41179ff0a9 docs(parent-portal): nextstep.md v2 核查下游服务完成情况 
v2 核查结果：parent-bff pnpm-lock 已添加，但端点路径/schema/Docker 构建/extended-resolvers 集成仍未完成

api-gateway Docker 构建仍失败（golang:1.22-alpine 无法拉取）

parent-portal 自身 Docker 镜像构建成功，容器 healthy，typecheck + lint 零错误
 2026-07-14 08:29:25 +08:00
SpecialX
0b42302a64 docs(admin-portal): 新增 nextstep-v2.md 记录下游核查结果 
v1 声称完成的下游工作经核查实际未完成：
- api-gateway: /api/admin/graphql 路由未注册，go vet 编译失败
- teacher-bff: resolver 已完成但 schema 未同步（命名空间 vs 扁平）
- iam: proto 缺 BatchGetUsers rpc 声明

v2 记录详细核查证据和修复要求
 2026-07-14 08:26:27 +08:00
SpecialX
96a936e154 feat(parent-portal): docker 构建修复 + 禁用 mock + 记录下游待办 
Dockerfile 改用 standalone 模式

next.config.js 添加 output standalone

修复 cssnano-simple 构建失败：globals.css 注释含 */ 被误解析

tailwind.config.js 覆盖 boxShadow 为 rgba 格式 + 禁用 ringWidth

组件修复：替换 / 语法为 inline style 或自定义类

otel.ts 添加 webpackIgnore 跳过 optionalDependencies 静态分析

.env.example 默认禁用 mock

新增 .dockerignore 和 docs/nextstep.md

删除 postcss.config.js

验证：Docker 镜像构建成功，容器 healthy，typecheck + lint 零错误
 2026-07-13 17:21:39 +08:00
SpecialX
8b729a710f feat(teacher-portal): Docker Desktop 验证通过 + 切换 standalone 模式 + nextstep.md 
- Dockerfile 切换为 Next.js output:standalone 模式
  - 解决 pnpm symlink 在 runtime 下无法解析 react/jsx-runtime 的问题
  - 修复 tsconfig.base.json 未 COPY 到 builder 阶段的问题
- next.config.js 添加 output:"standalone" 配置
- Docker Desktop 验证通过：
  - 镜像构建成功 (1.32GB)
  - 容器启动 Ready in 69ms
  - /api/health 健康检查返回 200
  - 27 静态路由 + 11 动态路由全部 HTTP 200
- 新增 nextstep.md：
  - 下游依赖清单（teacher-bff 61 GraphQL operations + iam + push-gateway）
  - 本模块待补工作（单元测试/设计令牌硬化/i18n/ui-components 扩展/性能/A11y）
  - Docker 部署注意事项 + 路由清单 + 已知问题
- workline.md §5.6 记录 Docker 验证结果
 2026-07-13 16:52:13 +08:00
SpecialX
40f07b7a16 feat(student-portal): 完成Docker构建验证+全量测试通过+nextstep下游依赖文档 2026-07-13 16:49:31 +08:00
SpecialX
64b2016fa8 feat(admin-portal): docker 本地测试通过 + 下游工作清单 
docker Desktop 本地验证：
- 镜像构建成功（edu/admin-portal:test）
- 容器运行正常（端口 4003）
- /api/health、/api/ready、/login、/admin/dashboard 全部 200

修复项：
- next.config.js 添加 output: standalone
- package.json 添加 autoprefixer 依赖
- login/layout.tsx 提供 AuthProvider/ToastProvider

部署配置：
- docker-compose.deploy.yml 添加 admin-portal 服务
- deploy.env.example 添加 ADMIN_PORTAL_PORT

下游工作清单（nextstep.md）：
- api-gateway: 缺 /api/admin/graphql 路由
- teacher-bff: 缺 16 Query + 11 Mutation
- iam: 缺 BatchGetUsers 等 RPC
 2026-07-13 16:19:35 +08:00
SpecialX
18d94c0cc2 feat(parent-portal): 完成参考项目(CICD)家长端功能全量覆盖 - 9 新页面 + 3 页面增强 + 763 测试通过 
## 变更内容

### P0 高优先级新页面
- /parent/leave: 请假表单(react-hook-form + Zod) + 历史列表(状态筛选)
- /parent/grades/report-card: 报告卡(学年/学期筛选 + 打印 + 教师评语)
- /parent/children/[studentId]: 子女详情聚合页(5 Tab: overview/homework/grades/exams/schedule)

### P1 中优先级新页面
- /parent/error-book: 错题本(5 项统计 + Top 错题 + 薄弱知识点)
- /parent/diagnostic: 诊断报告(掌握度摘要 + 已发布诊断报告)
- /parent/practice: 练习统计(4 项统计 + 练习历史)

### P2 低优先级新页面
- /parent/course-plans + [id]: 课程计划列表 + 详情(章节列表)
- /parent/lesson-plans + [planId]/view: 备课列表(学科筛选) + 只读详情
- /parent/elective: 选修课(分类色点 + 状态徽标)

### P3 现有页面增强
- /parent/dashboard: ParentAttentionBanner + 多子女卡片网格 + 趋势图标 + 逾期高亮
- /parent/attendance: AttendanceRateCard + AttendanceWarningBanner + 月份导航
- /parent/grades: GrowthArchiveChart + ExportGradesButton + 班级均对比线

### 基础设施
- types/index.ts: +20 新类型(LeaveRequest/ReportCard/ErrorBookStats/DiagnosticReport/PracticeStats/CoursePlan/LessonPlan/ElectiveSelection/ChildDetail/ScheduleItem 等)
- operations.ts: +19 GraphQL operations(17 query + 2 mutation)
- fixtures.ts: +18 mock 数据集
- handlers.ts: +19 MSW GraphQL handler

### 质量校验
- typecheck: 0 错误
- lint: 0 错误
- test: 71 文件 / 763 测试全部通过(从 413 增至 763, +350 测试)

### 文档
- workline.md: 新增 §7 参考项目(CICD)差距分析与实现安排 + §7.3-7.5 实现进度与覆盖完成度

### 设计决策
- 保留当前"单子女切换"范式(MultiChildTabBar + useChildSwitcher),不迁移到"多子女同屏对比"
- 仪表盘除外:已增强为多子女卡片网格并列展示
- 参考项目所有 11 个家长端页面功能已 100% 覆盖

Refs: ARB-020 §22, ARB-022 §24.4
 2026-07-13 15:12:56 +08:00
SpecialX
d49d211425 feat(teacher-portal): 完成参考项目差距闭环 P3-P7 全量实现 
- P3 考试/作业/成绩 mutation + 详情页 + 批改界面 + 乐观更新 + 多 Tab 同步
- P4 知识图谱 SVG 可视化 + 学情分析仪表盘 + parent-portal Remote
- P5 WebSocket 通知中心 + AI 出题(SSE) + AI 教案 + AI 学情报告
- P6 可观测性硬化：Sentry + WebVitals + OTel + A11y + 性能配置 + Cookie 迁移
- P7 参考项目差距闭环：新增 35 个页面覆盖 13 个缺失模块
  - attendance(考勤 4 页)/questions(题库)/textbooks(教材 2 页)
  - classes/[id] 详情 + classes/schedule 课表
  - course-plans(2 页)/diagnostic(2 页)/error-book/practice
  - exams/[id]/build 组卷 + exams/[id]/analytics 考后分析
  - exams/[id]/edit-rich 富文本编辑 + exams/[id]/proctoring 监考
  - grades/entry 批量录入 + grades/stats 统计 + grades/analytics 分析 + grades/report-card 报告卡
  - homework/submissions 列表 + assignments/[id]/submissions 批量批改
  - homework/submissions/[submissionId] 单份批改 + scan-grading 扫描批改
  - lesson-plans 编辑器 + library + calendar + heatmap 5 页
  - elective 选修课 3 页 /leave 请假 /schedule-changes 调课
- P7 基础设施：61 GraphQL operations + 5 handlers + 13 fixtures + 11 viewports
- 集成 browser.ts/server.ts 注册所有 p7 handlers(fallthrough 顺序)
- viewports.ts 扩展 11 个新导航项
- 验证：tsc --noEmit 零错误 + eslint 零错误
- 文档：workline.md 新增 §5 P7 参考项目差距闭环(含完整文件清单)
 2026-07-13 14:27:04 +08:00
SpecialX
f13ca612e6 feat(student-portal): 实现CICD参考项目差距功能 - 错题本/请假/选课/自适应练习/公告/课案/课程计划/成绩报告卡/学情诊断增强 2026-07-13 13:39:28 +08:00
SpecialX
7c8e0f5dea feat(parent-portal): 完成 P4-P6 全部任务 + ARB-022 §24.4 双 /v1 修正 + 413 测试通过 
主要变更：
1. ARB-022 §24.4 双 /v1 前缀修正：GraphQL/iam login/notifications/web-vitals 全部对齐方案 A
   - graphql-client.ts: /api/v1/parent/v1/graphql
   - auth.ts: /api/v1/iam/v1/login + /api/v1/iam/v1/refresh
   - useWebSocket.ts: /api/v1/parent/v1/notifications
   - observability/env.ts: /api/v1/parent/v1/web-vitals
   - 同步更新 contract.md / 01-understanding.md / 02-architecture-design.md

2. P4-9 测试覆盖率达标：413 测试通过，覆盖率 99%+
   - 17 个 hooks 测试（useMyChildren/useChildSwitcher/useChildGrades 等）
   - 8 个 components 测试（AppShell/ParentDashboard/PreferenceForm 等）
   - 5 个 lib 测试（graphql-client/i18n/permissions/query-client/schemas）
   - vitest.config.ts 排除 pages/observability/middleware（由集成/E2E 覆盖）

3. ARB-020 §22.5 switchChild 双层实现（GraphQL Mutation 后端审计 + Zustand 前端缓存）

4. P6 硬化全部完成：
   - P6-1 OTel browser SDK + Web Vitals 挂载（observability/otel.ts + web-vitals.ts）
   - P6-2 A11y WCAG 2.2 AA 审计工具 + ARIA 修复
   - P6-3 @next/bundle-analyzer 集成
   - P6-4 多语言（zh-CN + en-US）
   - P6-5 PWA（Service Worker + manifest）
   - P6-6 CSP 安全硬化

5. 补齐参考项目差距页面：exams/exam result/classes/learning-path/settings/trend

6. 文档同步：workline.md / contract.md / known-issues.md 全部更新

parent-portal 全部 P4-P6 任务已完成，无剩余工作项。
 2026-07-13 13:10:07 +08:00
SpecialX
7cf9aec20e feat(admin-portal): 完成参考项目差距闭环 - 4 批次补齐 + Vitest 测试 
差距分析闭环（workline §7-§8）：
- P0：审计子模块 3 页 + 学校组织 7 页
- P1：系统设置 4 Card + 公告管理 + 邀请码管理
- P2：文件管理 + AI 配置
- P6：5 测试文件 / 69 用例全过

共享基础设施：
- permissions +11 权限点 +14 路由
- view-models +20 接口
- i18n +100 key
- graphql-client +25 operation
- fixtures/handlers +15 mock +20 handler

质量：typecheck + lint 零错误，vitest 69/69 通过，arch.db 已更新
 2026-07-13 13:05:29 +08:00
SpecialX
fad6e43b47 feat(student-portal): 实现参考项目差距功能 - 手写板/图片上传/教师批注/课表/设置/作业分析/加入班级/延期申请/多维筛选 2026-07-13 12:54:43 +08:00
SpecialX
d1db3dfdee docs(student-portal): 落实 ARB-019 全部执行项 + 粘贴策略分层 + ExamForceSubmitted + mutation命名对齐 + 工作进度更新 2026-07-11 11:56:36 +08:00
SpecialX
a6b0c54fba fix: 修复登录路由 + 端口冲突 + Prometheus 配置 + outbox 表结构 + 补充监控基础设施 
1. teacher-portal 登录 JSON 解析错误修复
   - 根因：next.config.js rewrites /api/auth/* → gateway /api/auth/*，
     但 gateway 只在 /api/v1 路由组下注册代理，/api/auth/* 返回 404 纯文本
   - 修复：rewrites 映射 /api/auth/* → /api/v1/iam/*（对齐 iam controller @Controller("v1/iam")）

2. msg / data-ana 端口冲突修复
   - 根因：msg env.ts PORT 默认 3006，与 data-ana（config.py http_port=3006）冲突
   - 修复：msg PORT 默认 3006→3007（对齐端口分配表 msg=3007, data-ana=3006）

3. Prometheus classes-service 3001 DOWN 修复
   - 根因：classes 已合并入 core-edu（P3 裁决 C1），但 prometheus.yml 仍有 classes-service scrape 配置
   - 修复：从 prometheus.yml 删除 classes-service job

4. iam outbox 表 aggregate_id 列长度修复
   - 根因：iam_outbox.aggregate_id VARCHAR(32)，但 UUID 是 36 字符，导致 "Data too long" 错误
   - 修复：DDL 中 VARCHAR(32) → VARCHAR(36)；ALTER TABLE 修复现有数据库

5. 补充未搭建的监控基础设施
   - docker-compose.yml 新增 Alertmanager（9093）/ Loki（3100）/ Promtail（observability profile）
   - prometheus.yml alertmanager target 更新为 edu-alertmanager:9093

验证：
- TS typecheck 19 项目全部通过
- 登录链路 teacher-portal → gateway → iam 验证通过
- Prometheus targets 不再有 classes-service
- 3 个新基础设施容器（alertmanager/loki/promtail）启动成功

AI identity: trae-main（基础设施修复会话）
 2026-07-11 09:22:09 +08:00
SpecialX
61d824924a fix: 修复集成测试中发现的全部 bug — 15 服务端到端验证通过 
修复涵盖 6 大类问题：

1. api-gateway
   - 路径前缀剥离 /api 而非 /api/v1，保留下游 /v1/ controller 前缀
   - JWKS URL 默认值修复
   - publicPaths 白名单对齐 /v1/iam/*

2. iam
   - iam.module.ts exports 补充 PermissionCacheService 和 IamRepository
   - main.ts resolveProtoPath() 多路径探测 proto 文件

3. core-edu
   - app.module.ts AuthMiddleware 全局注册

4. BFF 层 GraphQL 端点（teacher-bff / parent-bff / student-bff）
   - teacher-bff: mock dataScope OWN→SELF 对齐 GraphQL enum；WHATWG Request header .get() 提取
   - parent-bff: handleNodeRequestAndResponse 不存在 → 直接 yoga(req,res)；WHATWG Request header .get() 提取
   - student-bff: auth.resolver 移除 ActionState 信封返回扁平对象；WHATWG Request header .get() 提取

5. ai
   - Kafka 事务降级 + 10s 超时
   - gRPC 拦截器降级
   - dev mode 禁用事务模式

6. 前端 + 共享包
   - teacher-portal: MF 插件条件实例化 + transpilePackages + extensionAlias
   - ui-components: error-boundary.tsx 添加 use client
   - ui-tokens: tailwind-theme.css 移除 @layer base
   - shared-ts: 导出从源码改为 dist 编译产物；OutboxModule global:true

7. infra
   - .gitignore 补充 keys/ *.pem *.key secrets/ 排除规则
   - infra/init-sql/02-all-services-schema.sql 36 张表 DDL

验证结果：
- TS typecheck: 19 个 workspace 项目全部通过
- Go vet + Ruff: 通过
- 15 服务全部启动成功
- 3 个 BFF GraphQL 端点 + 4 个前端页面全部 200
- Gateway → iam → core-edu 端到端链路验证通过

AI identity: trae-main（集成测试修复会话）
 2026-07-11 01:41:46 +08:00
SpecialX
32780c2296 chore(admin-portal): merge admin-portal full implementation into main 2026-07-10 19:19:52 +08:00
SpecialX
606acb674f chore(student-portal): merge student-portal full implementation into main 2026-07-10 19:19:35 +08:00
SpecialX
860557e166 chore(teacher-portal): merge teacher-portal full implementation into main 2026-07-10 19:19:19 +08:00
SpecialX
74474a2d04 feat(student-portal): 完整实现 student-portal 微前端 
包含 src 全部实现、Dockerfile、配置文件、contracts 包等
 2026-07-10 19:10:36 +08:00
SpecialX
1eacd1ed87 feat(teacher-portal): 完整实现 teacher-portal 微前端 
包含 settings/students/api、graphql、mocks、ui-tokens 设计令牌等
 2026-07-10 19:10:20 +08:00