docs: 全项目架构审查与文档体系重写
- 全项目逐文件审查: 4 份审计报告(shared/core-business/management/new-modules) - 重写 004 架构影响地图: 图优先 + 模块依赖图 + 数据流 + 调用链 + 问题分级 - 更新 005 结构化数据: 新增 architectureOverview/moduleDependencyGraph/knownIssues/dbTables 节点 - 更新 006 功能清单: 143 项功能标注实现状态, P0 覆盖率 80%->92% - 更新 007 差距审计: v2->v3, P0 完成 69%->84%, 新增架构技术债章节 - 更新 001 项目概览: 6 角色/54 权限/26 模块/54 表 - 新增 docs/README.md 文档索引 - 归档 11 份过时文档(002x2/003/designx8) 标注 - 更新 work_log
This commit is contained in:
SpecialX
196
docs/architecture/audit/shared-audit.md
Normal file
196
docs/architecture/audit/shared-audit.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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 组件，行数较高但属框架约定，可接受。
|
||||
Reference in New Issue
Block a user