xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
230 Commits 2 Branches 8 Tags
994441c2dcc6bdfbc67a0c96a86a6c8583daf633
Commit Graph

16 Commits

Author SHA1 Message Date
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