docs: 全文档合规检查与修正 - 代码示例规范/行数准确性/路径一致性/状态同步

docs/architecture/audit/shared-audit.md

@@ -8,7 +8,8 @@
 
 - 文件总数：69（不含测试文件）
   - `db/`：3
-  - `lib/`：13
+  - `lib/`：17（新增 4 个 auth 拆分文件）
+  - `lib/ai/`：6（新增目录，P2-2 拆分）
   - `hooks/`：7
   - `components/ui/`：34
   - `components/a11y/`：4
@@ -17,6 +18,8 @@
   - `src/auth.ts`、`src/proxy.ts`：2
 - 发现问题数：15
 - 严重程度分布：高 3 / 中 9 / 低 3
+- 已修复问题：4（auth.ts 拆分、ai.ts 拆分、循环依赖、反向依赖）
+- 待修复问题：11（含 schema.ts 拆分 P2-1、onboarding-gate、global-search、proxy.ts 等）
 
 ---
 
@@ -28,30 +31,40 @@
 - **严重程度**：高
 - **建议**：按业务域拆分为多个 schema 文件（如 `schema/auth.ts`、`schema/academic.ts`、`schema/exam.ts`、`schema/audit.ts` 等），通过 `schema/index.ts` 聚合导出。同时修正分节编号。
 
-### 2. `src/auth.ts`
+### 2. `src/auth.ts` ✅ 已修复
 
-- **问题**：293 行，混合了多种职责：
+- **问题**：~~293 行，混合了多种职责~~
   1. NextAuth 配置（providers、callbacks、events）
-  2. 密码安全 DB 操作（`getOrCreatePasswordSecurity`、`recordFailedLogin`、`resetFailedLogin`，行 56-130）——这些是数据访问层逻辑，不应内联在认证配置中
+  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 共用）。
+- **修复状态**：2026-06-17 已完成拆分（P1-3）。auth.ts 从 293 行降至 193 行，4 类职责分别迁移到 shared/lib 下的独立文件：
+  - `password-security-service.ts`（84 行）- 密码安全 DB 操作
+  - `role-utils.ts`（31 行）- 角色规范化
+  - `bcrypt-utils.ts`（18 行）- bcrypt 哈希规范化
+  - `http-utils.ts`（27 行）- IP 解析（与三个 logger 共用）
 
-### 3. `src/shared/lib/ai.ts`
+### 3. `src/shared/lib/ai.ts` ✅ 已修复
 
-- **问题**：218 行，混合了 5 类职责：
+- **问题**：~~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 调用编排。
+- **修复状态**：2026-06-17 已完成拆分（P2-2，commit 6588f74）。原 `ai.ts`（218 行）拆分为 `src/shared/lib/ai/` 目录 6 个文件：
+  - `payload-parser.ts`（96 行）- 请求负载解析
+  - `api-key-crypto.ts`（34 行）- API Key 加密/解密
+  - `provider-config.ts`（66 行）- Provider 配置查询
+  - `client.ts`（67 行）- AI 客户端创建与调用
+  - `errors.ts`（9 行）- 错误格式化
+  - `index.ts`（7 行）- 聚合导出
+  
+  原 `ai.ts` 保留为向后兼容的重导出文件（9 行），调用方无需修改 import 路径。
 
 ### 4. `src/shared/components/onboarding-gate.tsx`
 
@@ -128,27 +141,27 @@
 
 ## 模块间依赖问题
 
-### 1. shared 层与 `@/auth` 的循环依赖
+### 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"`
+  - `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 都依赖它，打破循环。
+  这构成了 `shared/lib/*` → `auth` → `shared/lib/*` 的循环。
+- **修复状态**：2026-06-17 已完成（P0-3）。3 个文件（audit-logger.ts、change-logger.ts、auth-guard.ts）将静态 `import { auth } from "@/auth"` 改为动态 `const { auth } = await import("@/auth")`，打破模块级静态循环依赖。运行时调用链保持不变，但模块加载图无环。
 
-### 2. shared 层对根模块 `@/auth` 的反向依赖
+### 2. shared 层对根模块 `@/auth` 的反向依赖 ✅ 已修复
 
 - **涉及模块**：`shared/lib/*` → `@/auth`（根模块）
 - **问题类型**：反向依赖
 - **问题详情**：`src/auth.ts` 位于项目根目录，属于应用层（非 shared 层）。shared 层应是被依赖方，不应依赖应用层模块。三个文件（audit-logger、change-logger、auth-guard）直接 import `@/auth`，使 shared 层无法独立测试或复用。
-- **建议**：同上，通过依赖注入或提取 `shared/lib/session.ts` 解耦。
+- **修复状态**：2026-06-17 已完成（P0-3）。通过动态 import 打破静态反向依赖。shared 层不再有对 `@/auth` 的静态 import，仅保留运行时动态调用（用于获取 session）。
 
-### 3. 三个 logger 重复实现 IP/Header 提取
+### 3. 三个 logger 重复实现 IP/Header 提取 ✅ 部分修复
 
 - **涉及模块**：`shared/lib/audit-logger`、`shared/lib/change-logger`、`shared/lib/login-logger`、`src/auth.ts`
 - **问题类型**：过度耦合（DRY 违反）
@@ -156,10 +169,10 @@
   - `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`（原行 39-51）：`resolveClientIp` 也是类似逻辑（取 `x-forwarded-for` 第一段）
   
   四处实现略有差异（auth.ts 取逗号分隔第一段，其他取全值），存在不一致风险。
-- **建议**：提取 `shared/lib/http-utils.ts`，导出 `getClientIp()` 和 `getUserAgent()` 统一复用。
+- **修复状态**：2026-06-17 部分修复（P1-3）。`src/auth.ts` 的 `resolveClientIp` 已迁移到 `shared/lib/http-utils.ts`（27 行），auth.ts 改为从该文件导入。但三个 logger 文件内部的 IP/Header 提取逻辑尚未统一到 `http-utils.ts`（P2 待处理）。
 
 ---
 
@@ -183,14 +196,20 @@
 
 | 目录 | 文件数 | 最大文件（行数） | 备注 |
 |------|--------|------------------|------|
-| `src/shared/db/` | 3 | schema.ts (1111) | **超过 1000 行硬性上限** |
-| `src/shared/lib/` | 13 | ai.ts (218) | |
+| `src/shared/db/` | 3 | schema.ts (1111) | **超过 1000 行硬性上限**（P2-1 待拆分） |
+| `src/shared/lib/` | 17 | password-security-service.ts (84) | ai.ts 已拆分为 ai/ 目录（P2-2）；新增 4 个 auth 拆分文件（P1-3） |
+| `src/shared/lib/ai/` | 6 | payload-parser.ts (96) | 新增目录（P2-2 拆分） |
 | `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/auth.ts` | 1 | auth.ts (193) | ✅ 已从 293 行降至 193 行（P1-3 拆分） |
 | `src/proxy.ts` | 1 | proxy.ts (75) | |
 
 > 注：`components/ui/` 下 34 个文件多为 shadcn/ui 标准生成组件（基于 Radix UI），职责单一，未发现结构性问题，故未逐一列入问题清单。`chart.tsx`（329 行）为标准 shadcn chart 组件，行数较高但属框架约定，可接受。
+>
+> **变更说明**：
+> - `src/shared/lib/ai.ts`（原 218 行）已拆分为 `ai/` 目录 6 个文件，原文件保留为 9 行重导出（P2-2）
+> - `src/auth.ts`（原 293 行）已拆分出 4 个 shared/lib 文件，自身降至 193 行（P1-3）
+> - `src/shared/lib/` 新增：`password-security-service.ts`（84 行）、`role-utils.ts`（31 行）、`bcrypt-utils.ts`（18 行）、`http-utils.ts`（27 行）