NextEdu/docs/architecture/audit/shared-audit.md

Shared 基础设施层审查报告

审查日期：2026-06-17 审查范围：src/shared/（db、lib、hooks、components、types）+ src/auth.ts + src/proxy.ts 审查依据：职责单一性、函数复杂度、模块间耦合、架构文档完整性

概览

• 文件总数：69（不含测试文件）
  • db/：3
  • lib/：13
  • hooks/：7
  • components/ui/：34
  • components/a11y/：4
  • components/（顶层）：4
  • types/：2
  • src/auth.ts、src/proxy.ts：2
• 发现问题数：15
• 严重程度分布：高 3 / 中 9 / 低 3

---

职责单一性问题

1. src/shared/db/schema.ts

• 问题：单个文件包含 54 张表定义，共 1111 行，超过项目规则中"任何文件不超过 1000 行"的硬性上限。文件涵盖用户、认证、题库、教学、学校、班级、考试、作业、AI、公告、审计、成绩、文件、课程计划、消息、考勤、排课、选课、监考、学情诊断等十余个业务域。此外分节编号混乱：section 12（Parent-Student Relations，行 958）出现在 section 14b（Notification Preferences，行 934）之后，P2 段落与主编号交错。
• 严重程度：高
• 建议：按业务域拆分为多个 schema 文件（如 schema/auth.ts、schema/academic.ts、schema/exam.ts、schema/audit.ts 等），通过 schema/index.ts 聚合导出。同时修正分节编号。

2. src/auth.ts

• 问题：293 行，混合了多种职责：
  1. NextAuth 配置（providers、callbacks、events）
  2. 密码安全 DB 操作（getOrCreatePasswordSecurity、recordFailedLogin、resetFailedLogin，行 56-130）——这些是数据访问层逻辑，不应内联在认证配置中
  3. 角色规范化工具（normalizeRole、resolvePrimaryRole，行 13-27）
  4. bcrypt 哈希规范化（normalizeBcryptHash，行 29-33）
  5. IP 解析（resolveClientIp，行 39-51）
  6. authorize 回调内联了限流、锁定检查、密码比对、日志记录全流程（86 行）
• 严重程度：高
• 建议：将密码安全 DB 操作迁移到 shared/lib/password-security-service.ts（与纯函数的 password-policy.ts 区分）；角色规范化迁移到 shared/lib/permissions.ts 或新建 shared/lib/role-utils.ts；resolveClientIp 迁移到 shared/lib/http-utils.ts（与三个 logger 共用）。

3. src/shared/lib/ai.ts

• 问题：218 行，混合了 5 类职责：

  1. 请求负载解析与校验（parseAiChatPayload，行 70-96）
  2. API Key 加密/解密（encryptAiApiKey/decryptAiApiKey，行 104-124）
  3. Provider 配置 DB 查询（getAiProviderConfig，行 126-179）
  4. AI 客户端创建与调用（getAiClient、createAiChatCompletion、testAiProviderConfig、testAiProviderById）
  5. 错误格式化（getAiErrorMessage）

  其中加密/解密与 Provider 配置查询属于数据层，与 AI 调用本身是不同关注点。

• 严重程度：中

• 建议：将加密/解密拆到 shared/lib/crypto.ts（通用加密工具）；将 Provider 配置查询拆到 shared/lib/ai-provider-repo.ts（数据访问）。ai.ts 保留负载解析与 AI 调用编排。

4. src/shared/components/onboarding-gate.tsx

• 问题：312 行组件，混合了：
  1. 多步表单 UI
  2. 角色推断业务逻辑（行 90-94）：通过权限反推角色（isAdmin/isTeacher/isStudent/isParent），逻辑脆弱且未使用 usePermission().hasRole()
  3. 硬编码教学学科列表（TEACHER_SUBJECTS，行 20）——业务数据固化在 shared 基础设施
  4. 直接 fetch("/api/onboarding/status") 和 fetch("/api/onboarding/complete")——耦合特定 API 路由
• 严重程度：中
• 建议：角色判断改用 usePermission().hasRole() 或 session 的 role 字段；学科列表迁移到 modules 层配置或 DB；API 调用通过 Server Action 封装。组件本身可考虑按步骤拆分子组件。

5. src/shared/components/global-search.tsx

• 问题：221 行组件，混合了：
  1. 搜索 UI 与下拉渲染
  2. 硬编码业务类型（ResultType = "question" | "textbook" | "exam" | "announcement"，行 12）与图标/标签映射（行 30-42）——业务知识泄漏到 shared 层
  3. 直接 fetch("/api/search?...")——耦合特定 API 路由与查询协议
  4. 快捷键、点击外部、键盘导航等交互逻辑内联
• 严重程度：中
• 建议：搜索结果类型与图标映射应由 API 返回或从 modules 层注入；API 调用抽取为独立 hook（useGlobalSearch）；交互逻辑可拆为 useSearchKeyboard 等。

6. src/proxy.ts

• 问题：75 行，硬编码了路由-权限映射（ROUTE_PERMISSIONS、API_PERMISSIONS，行 8-19），使用原始字符串如 "school:manage"、"exam:read"，未复用 Permissions 常量，违反项目规则"前端组件禁止硬编码 role/权限"的精神。resolveDefaultPath（行 21-27）将角色到默认路径的业务映射硬编码在代理中。
• 严重程度：中
• 建议：权限字符串改用 Permissions.SCHOOL_MANAGE 等常量；路由权限映射迁移到 shared/lib/route-permissions.ts 配置文件；角色-路径映射迁移到 modules 层或路由配置。

7. src/shared/lib/a11y.ts

• 问题：useA11yId（行 7-10）是一个 React Hook，但放置在 lib/ 目录而非 hooks/ 目录。项目约定 hooks/ 存放所有自定义 Hook，lib/ 存放纯工具函数。该文件其余函数（mergeA11yProps、describeInput、loadingAria）是纯函数，放置正确。
• 严重程度：低
• 建议：将 useA11yId 迁移到 shared/hooks/use-a11y-id.ts，a11y.ts 保留纯函数。

---

过耦合函数

1. resolveDataScope @ src/shared/lib/auth-guard.ts:64-130

• 行数：67
• 参数数：2（userId: string, roleNames: string[]）
• 问题：单个函数内根据角色分支查询 4 张不同的表（grades、classes、classSubjectTeachers、parentStudentRelations），将权限范围解析与数据访问混合。每个角色分支的查询逻辑独立，新增角色需修改此函数，违反开闭原则。
• 建议：将各角色的数据范围查询拆为独立函数（如 resolveTeacherScope、resolveParentScope），或迁移到各模块的 data-access 层，resolveDataScope 仅做分发。

2. getAiProviderConfig @ src/shared/lib/ai.ts:126-179

• 行数：53
• 参数数：1（providerId?: string）
• 问题：函数内有三段几乎相同的 DB 查询分支（按 providerId、按 isDefault、fallback），每段都 select 相同的字段、解密 apiKey、返回相同结构，存在明显代码重复。
• 建议：提取公共 mapProviderRow(row) 函数，三个分支简化为查询条件不同。或合并为单查询带 OR 条件 + 排序优先级。

3. authorize（NextAuth Credentials 回调）@ src/auth.ts:143-229

• 行数：86
• 参数数：1（credentials）
• 问题：单函数内串联了：邮箱密码校验 → 速率限制 → DB 用户查询 → 账户锁定检查 → 密码比对 → 失败计数 → 成功重置 → 角色查询 → 返回。流程长且混合了限流、安全策略、认证、日志多个关注点。内部还使用 Promise.all + 动态 import（行 165-168）加载 @/shared/db 和 schema，写法不寻常。
• 建议：将流程拆分为 checkRateLimit、checkAccountLockout、verifyPassword、loadUserRoles 等步骤函数，authorize 仅编排。动态 import 改为静态 import。

4. OnboardingGate 组件 @ src/shared/components/onboarding-gate.tsx:27-312

• 行数：285（组件函数体）
• 参数数：0（无 props，内部消费 session）
• 问题：单组件承担了状态检查、4 步表单、角色推断、API 提交、路由跳转。组件内 9 个 useState，3 个 useEffect，逻辑密集。
• 建议：按步骤拆分为 OnboardingRoleStep、OnboardingProfileStep、OnboardingRoleDetailStep、OnboardingCompleteStep 子组件；提取 useOnboarding hook 封装状态与提交逻辑。

5. GlobalSearch 组件 @ src/shared/components/global-search.tsx:49-221

• 行数：172（组件函数体）
• 参数数：2（className?, placeholder?）
• 问题：单组件承担了输入控制、防抖搜索、快捷键监听、点击外部关闭、键盘导航、结果渲染。6 个 useState，3 个 useEffect。
• 建议：提取 useGlobalSearch(query) hook 封装搜索请求与状态；提取 useSearchKeyboard 封装快捷键与导航。组件仅负责渲染。

---

模块间依赖问题

1. shared 层与 @/auth 的循环依赖

• 涉及模块：shared/lib/{audit-logger, change-logger, auth-guard} → @/auth → shared/lib/{login-logger, permissions, password-policy, rate-limit} + shared/db

• 问题类型：循环依赖

• 问题详情：

  • shared/lib/audit-logger.ts（行 7）import { auth } from "@/auth"
  • shared/lib/change-logger.ts（行 6）import { auth } from "@/auth"
  • shared/lib/auth-guard.ts（行 1）import { auth } from "@/auth"
  • 而 src/auth.ts 反向依赖 shared/lib/permissions、shared/lib/login-logger、shared/lib/password-policy、shared/lib/rate-limit、shared/db

  这构成了 shared/lib/* → auth → shared/lib/* 的循环。虽然 NextAuth 的 auth() 函数是运行时调用而非模块级副作用，目前不会导致运行时错误，但架构上 shared 基础设施层不应反向依赖业务层的认证入口。

• 建议：将 auth() 的 session 获取抽象为接口或通过参数注入。logger 函数改为接收 session 参数（由调用方传入），而非内部调用 auth()。或创建 shared/lib/session.ts 封装 session 获取，auth.ts 和 logger 都依赖它，打破循环。

2. shared 层对根模块 @/auth 的反向依赖

• 涉及模块：shared/lib/* → @/auth（根模块）
• 问题类型：反向依赖
• 问题详情：src/auth.ts 位于项目根目录，属于应用层（非 shared 层）。shared 层应是被依赖方，不应依赖应用层模块。三个文件（audit-logger、change-logger、auth-guard）直接 import @/auth，使 shared 层无法独立测试或复用。
• 建议：同上，通过依赖注入或提取 shared/lib/session.ts 解耦。

3. 三个 logger 重复实现 IP/Header 提取

• 涉及模块：shared/lib/audit-logger、shared/lib/change-logger、shared/lib/login-logger、src/auth.ts

• 问题类型：过度耦合（DRY 违反）

• 问题详情：三个 logger 各自重复实现相同的 IP/User-Agent 提取逻辑：

  • audit-logger.ts（行 27-32）：headerList.get("x-forwarded-for") ?? headerList.get("x-real-ip") ?? "unknown"
  • change-logger.ts（行 27-31）：相同逻辑
  • login-logger.ts（行 26-31）：相同逻辑
  • auth.ts（行 39-51）：resolveClientIp 也是类似逻辑（取 x-forwarded-for 第一段）

  四处实现略有差异（auth.ts 取逗号分隔第一段，其他取全值），存在不一致风险。

• 建议：提取 shared/lib/http-utils.ts，导出 getClientIp() 和 getUserAgent() 统一复用。

---

架构文档改进建议

1. 补充依赖关系图：当前 004 文档以函数/常量为粒度列举导出，但缺少模块间依赖方向的可视化图。建议在 005 JSON 中增加 dependencyMatrix 节点，记录 shared/lib/* → @/auth、@/auth → shared/lib/* 等依赖边，并在 004 Markdown 中用 Mermaid 图渲染。本次审查发现的循环依赖（shared ↔ auth）在当前文档中完全不可见。

2. 标注循环依赖与反向依赖：004/005 文档应明确标注 shared/lib/{audit-logger, change-logger, auth-guard} 对 @/auth 的依赖，以及这与 @/auth 对 shared/lib/* 的依赖构成的循环。当前文档将 auth 模块与 shared 模块分别描述，未揭示二者双向依赖。

3. 修正 schema.ts 分节编号：004 文档的"数据库表"章节按表名平铺列举，未反映 schema.ts 源文件中的分节结构。建议文档增加 schema.ts 分节映射表，并修正源文件中 section 12 出现在 section 14b 之后的编号混乱。

4. 增加 shared 层边界说明：004 文档应明确 shared 层"不应依赖应用层模块（如 @/auth）"的架构约束，以及哪些文件属于 shared 层的对外公共 API。当前文档未说明 shared 与根模块（auth.ts、proxy.ts）的边界。

5. 补充函数复杂度标注：005 JSON 中每个函数已有签名记录，但缺少行数与参数数量字段。建议增加 "lines" 和 "paramCount" 字段，便于自动识别过耦合函数（如本次发现的 authorize 86 行、resolveDataScope 67 行）。

6. 记录 proxy.ts 的路由权限映射：004 文档未记录 proxy.ts 中的 ROUTE_PERMISSIONS 和 API_PERMISSIONS 硬编码映射，也未说明这些映射与 Permissions 常量的关系。建议在 005 JSON 的 routes 节点中补充代理层权限规则。

---

附：审查范围文件清单

目录	文件数	最大文件（行数）	备注
src/shared/db/	3	schema.ts (1111)	超过 1000 行硬性上限
src/shared/lib/	13	ai.ts (218)
src/shared/hooks/	7	use-aria-live.ts (88)
src/shared/components/ui/	34	chart.tsx (329)	多为标准 shadcn/ui 组件
src/shared/components/a11y/	4	focus-trap.tsx (110)
src/shared/components/（顶层）	4	onboarding-gate.tsx (312)
src/shared/types/	2	permissions.ts (92)
src/auth.ts	1	auth.ts (293)
src/proxy.ts	1	proxy.ts (75)

注：components/ui/ 下 34 个文件多为 shadcn/ui 标准生成组件（基于 Radix UI），职责单一，未发现结构性问题，故未逐一列入问题清单。chart.tsx（329 行）为标准 shadcn chart 组件，行数较高但属框架约定，可接受。