diff --git a/docs/superpowers/specs/2026-07-07-enterprise-architecture-normalization-design.md b/docs/superpowers/specs/2026-07-07-enterprise-architecture-normalization-design.md new file mode 100644 index 0000000..5c58ac8 --- /dev/null +++ b/docs/superpowers/specs/2026-07-07-enterprise-architecture-normalization-design.md @@ -0,0 +1,304 @@ +# 企业级架构规范化设计 + +> 日期: 2026-07-07 +> 状态: 已批准 +> 范围: P0 安全合规 + P1 大仓工程基建 + P2 配置升级 +> 实施策略: 方案 A(严格分阶段,每阶段独立提交) + +--- + +## 1. 背景与目标 + +### 1.1 现状诊断 + +通过 `arch:query violations` + 配置文件审查 + 文档检查,发现 14 个维度的企业级/大仓规范缺口,按严重级别分类: + +**P0 严重(影响安全/规范底线)** +- 32 个 Server Action 缺 `requirePermission()` 校验(集中在 ai/auth/parent/settings/rbac/onboarding) +- 5 个文件超过 1000 行硬性上限(`schema.ts` 2245 行、`invalidation-map.ts` 1195 行、`messaging/actions.ts` 973 行、`textbooks/data-access.ts` 907 行、`questions/data-access.ts` 828 行) + +**P1 工程基建缺口** +- 缺大仓标配文档: LICENSE / CHANGELOG.md / CONTRIBUTING.md / SECURITY.md / .env.example +- 缺提交期前钩子: 无 husky + lint-staged + commitlint,提交规范仅靠自觉 +- `docs/architecture/roadmap/tech-debt.md` 是空壳(11 行无内容) + +**P2 配置不完整** +- `tsconfig.json` 中 `noUncheckedIndexedAccess: false` +- CI 不跑 unit test(`ci.yml` 跳过 `test:unit`) +- `package.json` 无 `engines` / `packageManager` 字段 +- 无 bundle-analyzer / coverage 阈值 / `/api/health` 端点 / API 文档 + +### 1.2 目标 + +- P0: 消除所有架构违规(`arch:query violations` 输出仅剩已知豁免) +- P1: 大仓文档齐全 + 提交规范工具链强制 + tech-debt 可追踪 +- P2: TypeScript 严格模式全量开启 + CI 覆盖 unit test + 可观测性补充 + +--- + +## 2. 设计决策 + +| 决策点 | 选择 | 理由 | +|--------|------|------| +| 实施范围 | 全部 P0+P1+P2 | 完整治理 | +| 豁免机制 | JSDoc `@public` 标记 | 显式标记、可审计、与代码同源 | +| noUncheckedIndexedAccess | 一次性开启+全量修复 | 一步到位,避免债务拖延 | +| scripts 治理 | 本次不做,记入 tech-debt | 范围可控 | +| 提交钩子 | husky + lint-staged + commitlint | 全套强制规范 | +| LICENSE | 专有协议(内部项目) | 不计划开源 | +| 实施策略 | 方案 A(严格分阶段) | 每阶段可独立验证+回滚 | + +--- + +## 3. 阶段 1: P0 安全合规 + +### 3.1 Server Action 权限治理 + +**3.1.1 arch:scan 豁免标记机制** + +修改 `scripts/arch-scan/scanner.ts`:扫描函数时识别 JSDoc 中的 `@public` 标记,将该函数标记为 `is_public: true` 存入 `symbols` 表。 + +修改 `scripts/arch-scan/query.ts` 的 `violations` 命令:过滤掉 `is_public: true` 的 Server Action。 + +**3.1.2 合理豁免清单(加 `@public` 标记,共 ~12 个)** + +| 文件 | 函数 | 豁免理由 | +|------|------|---------| +| `auth/actions.ts` | registerAction | 注册(登录前) | +| `auth/actions.ts` | checkEmailAvailabilityAction | 邮箱可用性检查(注册时) | +| `auth/actions.ts` | preflightTwoFactorAction | 2FA 预检(登录中) | +| `invitation-codes/actions.ts` | validateInvitationCodeAction | 邀请码校验(注册时) | +| `onboarding/actions.ts` | getOnboardingStatusAction | 引导状态查询(登录后但引导前) | +| `onboarding/actions.ts` | completeOnboardingAction | 完成引导(引导阶段) | +| `settings/actions-security.ts` | preflightTwoFactorAction | 2FA 预检(登录中) | +| `settings/actions-security.ts` | verifyTwoFactorForLogin | 2FA 验证(登录中) | +| `rbac/actions.ts` | isAdminRole | 内部辅助函数(非对外 Action) | +| `shared/lib/audit-logger.ts` | logAudit | 基础设施(非 Action,被 Action 调用) | +| `shared/lib/change-logger.ts` | logDataChange | 基础设施(同上) | +| `shared/lib/login-logger.ts` | logLoginEvent | 基础设施(同上) | + +**3.1.3 真违规修复清单(补 requirePermission,共 ~20 个)** + +| 文件 | 函数 | 权限点 | +|------|------|--------| +| `ai/actions.ts` | suggestSimilarQuestionsAction | QUESTION_READ | +| `ai/actions.ts` | suggestGradingAction | HOMEWORK_GRADE | +| `ai/actions.ts` | generateLessonContentAction | LESSON_PLAN_CREATE | +| `ai/actions.ts` | generateQuestionVariantAction | QUESTION_CREATE | +| `ai/actions.ts` | analyzeWeaknessAction | DIAGNOSTIC_READ | +| `ai/actions.ts` | explainErrorAction | ERROR_BOOK_READ | +| `leave-requests/actions.ts` | listMyLeaveRequests | LEAVE_REQUEST_READ(自身) | +| `lesson-preparation/actions.ts` | duplicateLessonPlanFormAction | LESSON_PLAN_CREATE | +| `parent/actions.ts` | getChildrenAction | PARENT_DASHBOARD_VIEW | +| `parent/actions.ts` | getChildBasicInfoAction | PARENT_DASHBOARD_VIEW | +| `parent/actions.ts` | getChildDashboardDataAction | PARENT_DASHBOARD_VIEW | +| `parent/actions.ts` | getParentDashboardDataAction | PARENT_DASHBOARD_VIEW | +| `parent/actions.ts` | getChildNameListAction | PARENT_DASHBOARD_VIEW | +| `parent/actions.ts` | verifyParentChildRelationAction | PARENT_DASHBOARD_VIEW | +| `settings/actions-service.ts` | updateProfileAction | USER_PROFILE_UPDATE(自身) | +| `settings/actions.ts` | getAiProviderSummaries | SYSTEM_SETTINGS_READ | +| `settings/actions.ts` | upsertAiProviderAction | SYSTEM_SETTINGS_MANAGE | +| `settings/actions.ts` | testAiProviderAction | SYSTEM_SETTINGS_MANAGE | +| `settings/actions.ts` | deleteAiProviderAction | SYSTEM_SETTINGS_MANAGE | +| `settings/actions.ts` | canConfigurePublicAiProvider | SYSTEM_SETTINGS_READ | + +**注**: 若上述权限点不存在,需在 `shared/types/permissions.ts` 新增并注册到 `ROLE_PERMISSIONS_SEED` + `permission-bitmap.ts` + `permission-catalog.ts` + i18n `rbac.json` 五处。 + +### 3.2 超长文件拆分 + +**3.2.1 `shared/db/schema.ts` (2245 行) → 按域拆分** + +``` +src/shared/db/ +├─ schema.ts # barrel: re-export 所有 +├─ schema/ +│ ├─ users.ts # users + userRoles + parentStudentRelations +│ ├─ academic.ts # classes + subjects + grades + textbooks + chapters + knowledgePoints +│ ├─ exams.ts # exams + examQuestions + homeworkAssignments + submissions + answers +│ ├─ grades.ts # gradeRecords + gradeStats +│ ├─ attendance.ts # attendanceRecords + attendanceRules +│ ├─ messaging.ts # conversations + messages + messageReadStatus +│ ├─ notifications.ts # notifications + notificationPreferences +│ ├─ audit.ts # auditLogs + changeLogs +│ ├─ rbac.ts # roles + permissions + rolePermissions +│ ├─ files.ts # files + fileReferences +│ ├─ scheduling.ts # classSchedule + timeSlots +│ └─ misc.ts # 其余表 +``` + +**3.2.2 `shared/lib/cache/invalidation-map.ts` (1195 行) → 按模块拆分** + +``` +src/shared/lib/cache/ +├─ invalidation-map.ts # barrel + registerInvalidationMaps +├─ invalidation/ +│ ├─ exams.ts +│ ├─ homework.ts +│ ├─ grades.ts +│ ├─ attendance.ts +│ ├─ messaging.ts +│ ├─ textbooks.ts +│ └─ ... +``` + +**3.2.3 `messaging/actions.ts` (973 行) → 按职责拆分** + +``` +src/modules/messaging/ +├─ actions.ts # barrel +├─ actions-conversations.ts # 会话 CRUD +├─ actions-messages.ts # 消息发送/撤回 +├─ actions-starred.ts # 星标 +└─ actions-read.ts # 已读状态 +``` + +**3.2.4 `textbooks/data-access.ts` (907 行) → 按实体拆分** + +``` +src/modules/textbooks/ +├─ data-access.ts # barrel + 核心 +├─ data-access-graph.ts # 已有 +├─ data-access-chapters.ts # 章节 CRUD +└─ data-access-knowledge-points.ts # 知识点 CRUD +``` + +**3.2.5 `questions/data-access.ts` (828 行) → 按职责拆分** + +``` +src/modules/questions/ +├─ data-access.ts # barrel + 核心 CRUD +└─ data-access-search.ts # FULLTEXT 检索 +``` + +--- + +## 4. 阶段 2: P1 大仓工程基建 + +### 4.1 大仓文档 + +| 文件 | 内容 | +|------|------| +| `LICENSE` | "Copyright (c) 2026 EazyGame. 保留所有权利。未经许可不得复制、修改、分发。" | +| `CHANGELOG.md` | Keep-a-changelog 格式,初始 `## [1.0.0] - 2026-07-07` 条目(记录文档体系重设计完成) | +| `CONTRIBUTING.md` | 分支策略(main 保护) + Conventional Commits + 提交前检查(lint+tsc) + 模块 README 维护规则 + arch:scan 同步 | +| `SECURITY.md` | 漏洞报告流程 + 安全联系人 + 响应 SLA + 不公开披露策略 | +| `.env.example` | 从 `src/env.mjs` 提取所有键(DATABASE_URL/NEXTAUTH_SECRET/NEXTAUTH_URL/AI keys/...)含注释说明 | + +### 4.2 提交规范工具链 + +**4.2.1 依赖安装** + +```bash +npm install -D husky lint-staged @commitlint/cli @commitlint/config-conventional @next/bundle-analyzer +``` + +**4.2.2 配置文件** + +- `.husky/pre-commit`: `npx lint-staged` +- `.husky/commit-msg`: `npx commitlint --edit $1` +- `commitlint.config.js`: extends conventional + scope-enum(35 模块名) +- `lint-staged.config.js`: `*.{ts,tsx}` → `eslint --fix` + `prettier --write`;`*.md` → `prettier --write` +- `package.json` scripts: `"prepare": "husky"` + +### 4.3 tech-debt.md 填充 + +整理待解决技术债(从 known-issues 工作经验日志 + 本次诊断补充): +- scripts 目录混放治理(.sh/.ps1/.js/.mjs/.ts 统一) +- API 文档自动化(OpenAPI 生成) +- proctoring 模块的 exams 依赖未被 arch.db 捕获(scanner 改进) +- FULLTEXT 索引迁移工具化 +- client-error 上报机制完善(Task 12-14) +- React Flow 移除后的历史包袱清理 + +--- + +## 5. 阶段 3: P2 配置升级 + +### 5.1 TypeScript 严格化 + +- `tsconfig.json`: `"noUncheckedIndexedAccess": true` +- 全量修复类型错误: 数组索引 `arr[0]` → `arr[0]!` 或 `arr.at(0) ?? defaultValue`;对象索引 `obj[key]` → 显式判空 + +### 5.2 CI 完善 + +**`ci.yml` 修改**: +- Lint → **Unit test** → Typecheck → Architecture scan → Integration → E2E → Build + +**`vitest.unit.config.ts` 加 coverage**: +```ts +coverage: { + provider: "v8", + lines: 60, + functions: 60, + branches: 60, + statements: 60, +} +``` + +**`package.json` 补充字段**: +```json +{ + "engines": { "node": ">=22" }, + "packageManager": "npm@10.9.0" +} +``` + +### 5.3 可观测性补充 + +**`/api/health` 路由**: +```ts +// src/app/api/health/route.ts +export async function GET() { + return Response.json({ + status: "ok", + uptime: process.uptime(), + timestamp: new Date().toISOString(), + version: process.env.npm_package_version, + }); +} +``` + +**Dockerfile 加 HEALTHCHECK**(审查现有 Dockerfile 后修改): +```dockerfile +HEALTHCHECK --interval=30s --timeout=3s --retries=3 \ + CMD wget -qO- http://localhost:3000/api/health || exit 1 +``` + +**bundle-analyzer**: +- `package.json` scripts: `"analyze": "ANALYZE=true next build"` +- `next.config.ts` 包装 `@next/bundle-analyzer` + +### 5.4 API 文档 + +`docs/api/README.md`: 17 个路由清单 + 请求/响应 schema 示例(从 `withApiErrorHandler` 与 `ActionState` 推导) + +--- + +## 6. 验收标准 + +| 阶段 | 验收项 | +|------|--------| +| P0 | `npm run arch:query -- violations` 仅剩 0 个真违规(豁免项不报);`npx tsc --noEmit` 0 错误;`npm run lint` 0 错误;5 个超长文件全部 < 1000 行 | +| P1 | `LICENSE`/`CHANGELOG.md`/`CONTRIBUTING.md`/`SECURITY.md`/`.env.example` 存在;`npm run prepare` 安装 husky 钩子;commitlint 拒绝非规范提交;`tech-debt.md` 含至少 6 条待解决项 | +| P2 | `noUncheckedIndexedAccess: true` 且 tsc 0 错误;CI 跑 unit test;`/api/health` 返回 200;`npm run analyze` 可用;`package.json` 含 engines+packageManager | + +--- + +## 7. 实施约束 + +- 每阶段开始前 `git commit` 一次快照(用户要求"实施前提交备份") +- 每阶段完成后 `git commit` + `git push` +- 每阶段必须通过 `npx tsc --noEmit` + `npm run lint` + `npm run arch:scan` +- 阶段 1 完成后更新 `docs/troubleshooting/known-issues.md` 工作经验日志 +- 阶段 3 完成后更新 `docs/architecture/004_architecture_impact_map.md`(若架构意图变化) +- 全程不改 `project_rules.md` 除非有新的强制规则 + +--- + +## 8. 不在本次范围 + +- scripts 目录治理(记入 tech-debt) +- OpenAPI 自动生成(记入 tech-debt,本次仅手写静态文档) +- 分支保护策略(Gitea 配置,不在代码层) +- 数据库迁移工具化(已有 drizzle-kit) +- 客户端错误上报机制完善(Task 12-14,独立项目)