refactor: P1-3/4/6 解耦修复 - 拆分 auth/users 文件 + notifications 反向依赖

docs/architecture/005_architecture_data.json

@@ -527,6 +527,97 @@
               "auth.ts (events.signIn, events.signOut)"
             ]
           },
+          {
+            "name": "normalizeRole",
+            "file": "lib/role-utils.ts",
+            "signature": "normalizeRole(value: unknown): NormalizedRole",
+            "purpose": "将角色值规范化为 admin/teacher/student/parent 之一（纯函数，legacy 别名 grade_head/teaching_head→teacher）",
+            "deps": [],
+            "usedBy": [
+              "auth.ts (jwt/session callbacks)",
+              "lib/role-utils.resolvePrimaryRole"
+            ]
+          },
+          {
+            "name": "resolvePrimaryRole",
+            "file": "lib/role-utils.ts",
+            "signature": "resolvePrimaryRole(roleNames: string[]): NormalizedRole",
+            "purpose": "从多角色列表解析主角色（优先级 admin>teacher>parent>student，纯函数）",
+            "deps": [
+              "lib/role-utils.normalizeRole"
+            ],
+            "usedBy": [
+              "auth.ts (authorize, jwt callback)"
+            ]
+          },
+          {
+            "name": "normalizeBcryptHash",
+            "file": "lib/bcrypt-utils.ts",
+            "signature": "normalizeBcryptHash(value: string): string",
+            "purpose": "将存储的 bcrypt 哈希规范化为 $2b$ 前缀形式（纯函数，兼容 legacy 无前缀存储）",
+            "deps": [],
+            "usedBy": [
+              "auth.ts (authorize)"
+            ]
+          },
+          {
+            "name": "resolveClientIp",
+            "file": "lib/http-utils.ts",
+            "signature": "resolveClientIp(): Promise<string>",
+            "purpose": "从请求头解析客户端 IP（x-forwarded-for/x-real-ip，best-effort，失败返回 unknown）",
+            "deps": [
+              "next/headers"
+            ],
+            "usedBy": [
+              "auth.ts (authorize 速率限制键)"
+            ]
+          },
+          {
+            "name": "getOrCreatePasswordSecurity",
+            "file": "lib/password-security-service.ts",
+            "signature": "getOrCreatePasswordSecurity(db, passwordSecurity, userId: string): Promise<PasswordSecurityRow>",
+            "purpose": "获取或创建用户的 password_security 行（server-only）",
+            "deps": [
+              "drizzle-orm.eq",
+              "@paralleldrive/cuid2",
+              "shared.db",
+              "shared.db.schema.passwordSecurity"
+            ],
+            "usedBy": [
+              "auth.ts (authorize)",
+              "lib/password-security-service.recordFailedLogin",
+              "lib/password-security-service.resetFailedLogin"
+            ]
+          },
+          {
+            "name": "recordFailedLogin",
+            "file": "lib/password-security-service.ts",
+            "signature": "recordFailedLogin(db, passwordSecurity, userId: string): Promise<{ locked: boolean; lockedUntil: Date | null }>",
+            "purpose": "递增失败登录计数，达到阈值则锁定账户（server-only）",
+            "deps": [
+              "lib/password-security-service.getOrCreatePasswordSecurity",
+              "lib/password-policy.PASSWORD_RULES",
+              "shared.db",
+              "shared.db.schema.passwordSecurity"
+            ],
+            "usedBy": [
+              "auth.ts (authorize 密码校验失败分支)"
+            ]
+          },
+          {
+            "name": "resetFailedLogin",
+            "file": "lib/password-security-service.ts",
+            "signature": "resetFailedLogin(db, passwordSecurity, userId: string): Promise<void>",
+            "purpose": "登录成功后重置失败计数与锁定状态（server-only）",
+            "deps": [
+              "lib/password-security-service.getOrCreatePasswordSecurity",
+              "shared.db",
+              "shared.db.schema.passwordSecurity"
+            ],
+            "usedBy": [
+              "auth.ts (authorize 登录成功分支)"
+            ]
+          },
           {
             "name": "isAllowedMimeType",
             "file": "lib/file-storage.ts",
@@ -1801,7 +1892,19 @@
     },
     "auth": {
       "path": "src/auth.ts",
-      "description": "用户认证：NextAuth配置、JWT/Session callbacks、events回调(登录日志)、middleware。集成密码安全策略（账户锁定、失败登录追踪）和登录速率限制",
+      "description": "用户认证：NextAuth配置（handlers/auth/signIn/signOut）、JWT/Session callbacks、events回调(登录日志)。集成密码安全策略（账户锁定、失败登录追踪）和登录速率限制。P1-3 拆分后，辅助函数已迁移至 shared/lib/{role-utils,bcrypt-utils,http-utils,password-security-service}",
+      "imports": [
+        "shared/lib/permissions",
+        "shared/lib/login-logger",
+        "shared/lib/password-policy",
+        "shared/lib/rate-limit",
+        "shared/lib/role-utils",
+        "shared/lib/bcrypt-utils",
+        "shared/lib/http-utils",
+        "shared/lib/password-security-service",
+        "shared/db",
+        "shared/db/schema"
+      ],
       "exports": {
         "functions": [
           {
@@ -4850,25 +4953,6 @@
               "actions.importUsersAction"
             ]
           },
-          {
-            "name": "batchImportUsers",
-            "signature": "(records: UserImportRecord[]) => Promise<UserImportResult>",
-            "file": "import-export.ts",
-            "purpose": "批量创建用户（默认密码 123456 bcrypt 哈希，自动创建 usersToRoles，student 通过邀请码自动加入班级）",
-            "deps": [
-              "shared.db",
-              "shared.db.schema.users",
-              "shared.db.schema.roles",
-              "shared.db.schema.usersToRoles",
-              "shared.db.schema.classes",
-              "shared.db.schema.classEnrollments",
-              "bcryptjs",
-              "@paralleldrive/cuid2"
-            ],
-            "usedBy": [
-              "actions.importUsersAction"
-            ]
-          },
           {
             "name": "exportUsersToExcel",
             "signature": "(params: { scope: DataScope; role?: string }) => Promise<Buffer>",
@@ -4887,6 +4971,47 @@
             ]
           }
         ],
+        "userService": [
+          {
+            "name": "batchImportUsers",
+            "signature": "(records: UserImportRecord[]) => Promise<UserImportResult>",
+            "file": "user-service.ts",
+            "purpose": "批量创建用户（默认密码 123456 bcrypt 哈希，自动创建 usersToRoles，student 通过邀请码自动加入班级——委托 class-registration）",
+            "deps": [
+              "shared.db",
+              "shared.db.schema.users",
+              "shared.db.schema.roles",
+              "shared.db.schema.usersToRoles",
+              "bcryptjs",
+              "@paralleldrive/cuid2",
+              "class-registration.registerStudentByInvitationCode"
+            ],
+            "usedBy": [
+              "actions.importUsersAction",
+              "import-export.ts (re-export 向后兼容)"
+            ]
+          }
+        ],
+        "classRegistration": [
+          {
+            "name": "registerStudentByInvitationCode",
+            "signature": "(studentId: string, invitationCode: string) => Promise<ClassRegistrationResult>",
+            "file": "class-registration.ts",
+            "purpose": "通过邀请码将学生注册到班级，委托 classes/data-access.enrollStudentByInvitationCode，返回结构化结果（不抛异常）",
+            "deps": [
+              "classes/data-access.enrollStudentByInvitationCode"
+            ],
+            "usedBy": [
+              "user-service.batchImportUsers"
+            ]
+          },
+          {
+            "name": "ClassRegistrationResult",
+            "type": "type",
+            "file": "class-registration.ts",
+            "definition": "{ success: boolean; error?: string }"
+          }
+        ],
         "types": [
           {
             "name": "UserImportRecord",
@@ -4910,11 +5035,12 @@
           {
             "name": "UserImportResult",
             "type": "type",
-            "file": "import-export.ts",
+            "file": "user-service.ts",
             "definition": "{ successCount, failedCount, errors: Array<{ row, email, error }> }",
             "usedBy": [
               "batchImportUsers",
-              "importUsersAction"
+              "importUsersAction",
+              "import-export.ts (re-export 向后兼容)"
             ]
           }
         ],
@@ -10255,7 +10381,8 @@
     "users": {
       "dependsOn": [
         "shared",
-        "auth"
+        "auth",
+        "classes"
       ],
       "uses": {
         "shared": [
@@ -10265,14 +10392,15 @@
           "db.schema.users",
           "db.schema.roles",
           "db.schema.usersToRoles",
-          "db.schema.classes",
-          "db.schema.classEnrollments",
           "types.permissions",
           "types.action-state",
           "lib.excel"
         ],
         "auth": [
           "auth"
+        ],
+        "classes": [
+          "data-access.enrollStudentByInvitationCode"
         ]
       }
     },
@@ -10952,7 +11080,9 @@
       "title": "auth.ts 混合 5 类职责",
       "file": "src/auth.ts",
       "problem": "NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调函数混合",
-      "suggestion": "拆分为 auth-config/password-security/role-normalizer/ip-utils 等多文件"
+      "suggestion": "拆分为 auth-config/password-security/role-normalizer/ip-utils 等多文件",
+      "status": "resolved",
+      "resolution": "已拆分：密码安全DB操作→shared/lib/password-security-service.ts，角色规范化→shared/lib/role-utils.ts，bcrypt哈希规范化→shared/lib/bcrypt-utils.ts，IP解析→shared/lib/http-utils.ts。auth.ts 现 208 行仅保留 NextAuth 配置"
     },
     {
       "id": "P1-4",