## 0. 范围文件用途注释与注释门禁

| 文件 | 文件用途 | 核心职责 | 上下游关联文件 | 主要关联逻辑 | 风险点 |
| --- | --- | --- | --- | --- | --- |
| `backend/pom.xml` | 后端依赖清单 | 引入 Security、JWT、迁移测试所需依赖 | `SecurityConfig.java`、认证服务 | Maven → Spring Security/密码编码器/JWT | 版本不兼容或引入脆弱依赖 |
| `backend/src/main/resources/db/migration/V*_system_user_auth.sql` | 数据库迁移脚本 | 以可检查、可回滚的步骤扩展 `as_system_user`，创建哈希变更触发器但不写入 `Jeddy` 的哈希 | `SystemUserEntity.java`、部署文档 | 迁移 → 表列/索引/触发器 → 认证服务 | 线上表结构、重复用户名、默认权限或触发器逻辑错误 |
| `backend/src/main/java/com/xyw/console/asset/entity/SystemUserEntity.java` | 用户表实体映射 | 读写账号、哈希、状态、权限和版本字段 | Mapper、用户服务 | Controller → Service → Entity/Mapper → `as_system_user` | 字段名不一致或意外序列化密码哈希 |
| `backend/src/main/java/com/xyw/console/config/SecurityConfig.java` | Spring Security 总开关 | 配置认证过滤器、Cookie、CSRF、公开路由和 401/403 | `AuthTokenFilter.java`、`WebConfig.java` | 浏览器 → Filter Chain → Controller | 保护不足或 CORS/CSRF 阻断合法请求 |
| `backend/src/main/java/com/xyw/console/auth/AuthTokenFilter.java` | 每请求身份验证 | 校验 Cookie 内令牌、账号状态和版本 | `AuthTokenService.java`、`SystemUserMapper.java` | Request → Cookie → 用户查询 → SecurityContext | 旧令牌未失效或错误放行 |
| `backend/src/main/java/com/xyw/console/auth/AuthTokenService.java` | 登录凭证生成与验证 | 签发、解析和清除短期令牌 Cookie | Auth 服务、过滤器 | 登录/改密 → JWT → HttpOnly Cookie → 过滤器 | 密钥泄露、过期策略错误 |
| `backend/src/main/java/com/xyw/console/auth/AuthService.java` | 认证业务规则 | 登录、当前用户与登出 | 用户服务、令牌服务、Mapper | AuthController → AuthService → 密码/令牌/用户表 | 密码明文进入日志或无法撤销会话 |
| `backend/src/main/java/com/xyw/console/auth/SystemUserAdminService.java` | 账号管理规则 | 角色创建边界、开发者隐藏、启停、仅开发者重置密码与权限保存 | Mapper、权限服务 | UserAdminController → Service → `as_system_user` | 超级管理员越权创建开发者或修改密码 |
| `backend/src/main/java/com/xyw/console/auth/PagePermissionService.java` | 页面权限判定 | 校验注册页面、三档权限并向接口提供最低权限校验 | 认证服务、资产 Controller | 当前用户 → 权限映射 → READ/EDIT 决策 | 新页面默认被意外授权 |
| `backend/src/main/java/com/xyw/console/auth/dto/*.java` | 认证与账号接口契约 | 校验请求、限制响应字段、避免回传密码 | 两个 Controller、前端 API 客户端 | 页面表单 → DTO → Service → 安全响应 | DTO 误含哈希或明文 |
| `backend/src/main/java/com/xyw/console/auth/AuthController.java` | 登录/本人接口入口 | 暴露登录、当前用户、登出、改密 API | `AuthService.java` | Vue → `/api/auth/*` → 认证服务 | 认证错误信息泄漏 |
| `backend/src/main/java/com/xyw/console/auth/SystemUserAdminController.java` | 账号管理接口入口 | 暴露列表、创建、编辑、启停、重置、权限 API | 管理服务、权限服务 | 权限页 → `/api/system-users/*` → 用户表 | 仅前端限制导致绕过 |
| `backend/src/main/java/com/xyw/console/asset/controller/PhoneAssetController.java`、`WecomAccountController.java` | 现有资产业务 API | 为读/写方法接入最低页面权限 | `PagePermissionService.java` | 资产页 API → 页面权限 → 原业务服务 | 破坏原有成功响应 |
| `frontend/src/main.js` | Vue 应用入口 | 注入认证状态和启动身份恢复 | `App.js`、router、认证模块 | 浏览器启动 → `/api/auth/me` → 路由 | 启动闪屏或未认证短暂显示业务页 |
| `frontend/src/router/index.js` | 前端路由表 | 注册登录、改密、无权、账号权限页及守卫 | `auth-store.js`、页面组件 | URL → 守卫 → 认证/权限 → 组件 | 手工地址绕过菜单 |
| `frontend/src/App.js` | 主壳和侧栏 | 用服务端权限过滤菜单，增加设置图标入口 | 路由、认证状态 | 权限结果 → 菜单 → RouterLink | 开发者入口被展示 |
| `frontend/src/modules/auth/auth-api-client.js`、`auth-store.js` | 认证请求和内存状态 | 使用 Cookie 凭证请求、保存安全用户资料、统一 401 和开发者登录欢迎条件 | 后端 AuthController、路由 | 页面事件 → API → Cookie/当前用户 → UI | token 被写入浏览器持久存储或错误展示专属提示 |
| `frontend/src/modules/auth/LoginView.js` | 登录页 | 收集密码、不回显、不持久化，并仅为 `Jeddy` 显示专属欢迎提示 | 认证客户端、router | 表单 → Auth API → 成功提示/跳转 | 失败信息、密码显示或误提示不当 |
| `frontend/src/modules/settings/UserPermissionView.js` | 独立账号和权限页 | 管理账号与逐页面板，开发者永不展示 | 用户管理 API、Element Plus | 管理员 → 表单/权限面板 → API → 列表 | 错误角色选项或权限值 |
| `frontend/src/modules/*/*-api-client.js`、资产视图 | 现有业务 API 与页面 | 自动携带 Cookie，并按 READ/EDIT 控制按钮 | 后端资产 Controller、认证状态 | 权限 → 控件状态 → 接口调用 | 只读用户仍发送写请求 |
| `frontend/src/styles/app.css` | 页面样式 | 登录页、设置菜单、权限面板和无权页的局部样式 | 新增 Vue 视图 | 组件 class → CSS | 全局样式污染资产页 |
| `backend/src/test/**/auth/*.java`、`frontend/tests/auth-permission.spec.js` | 回归测试 | 覆盖登录、开发者专属提示、角色边界、开发者隐藏和 READ/EDIT/NONE | 所有认证/权限模块 | 测试 → API/UI → 断言 | 仅测前端不测后端越权 |

实施时，表中每个新增或改动的方法、对象方法、箭头函数以及含业务逻辑的回调 MUST 增加中文新手注释，且每条注释必须写清：代码作用（白话）、关联文件、关联逻辑（调用链/消息链/数据流）。不得只写“登录”“查询”等重复代码字面意思的注释。

| 方法/回调范围 | 必须说明的关联逻辑 |
| --- | --- |
| `SecurityConfig.securityFilterChain`、`passwordEncoder`、`corsConfigurationSource` | 浏览器请求 → Security Filter Chain → Controller；为何 Cookie/CSRF/CORS 必须同时配置 |
| `AuthTokenFilter.shouldNotFilter`、`doFilterInternal` | HTTP 请求 → Cookie → JWT 解析 → 用户状态/版本核验 → SecurityContext |
| `AuthTokenService.issue`、`parseAndValidate`、`clearCookie` | 登录 → 签名 Cookie；请求 → 验签；登出 → 清 Cookie |
| `AuthService.login`、`me`、`logout` | AuthController → 密码校验/用户表/令牌服务 → 安全响应；登录成功如何传递 `Jeddy` 专属提示判定所需的安全身份 |
| `SystemUserAdminService.listVisibleUsers`、`createUser`、`updateUser`、`resetPassword`、`changeStatus`、`assertManageableRole` | 管理员身份 → 角色边界/开发者隐藏 → `as_system_user` → 会话撤销 |
| `PagePermissionService.validatePermissions`、`effectivePermissions`、`requirePageAccess` | 权限面板 → JSON 映射 → READ/EDIT 判定 → 资产 Controller |
| `AuthController` 与 `SystemUserAdminController` 所有接口方法 | 浏览器 DTO → Service → 统一 `ApiResponse`；响应为何绝不含密码/哈希 |
| `PhoneAssetController`、`WecomAccountController` 被改动的读写方法 | 页面权限校验 → 保留原业务 Service 和原响应结构 |
| `auth-api-client` 的 `request/login/me/logout`、`auth-store` 的 `bootstrap/setCurrentUser/clearCurrentUser` | Vue 页面 → `credentials: include` 请求 → Cookie 会话 → 路由/菜单状态；为何只有登录成功事件可触发 `Jeddy` 提示 |
| `router` 的 `beforeEach` 守卫和 `App.js` 的菜单生成回调 | Hash URL/当前权限 → 允许、跳转登录或无权页；菜单隐藏不是后端授权替代品 |
| `LoginView`、`UserPermissionView` 的提交、加载、权限转换和确认回调 | 表单 → DTO → API → 成功刷新或不泄漏原因的错误反馈；密码字段为何仅开发者可见和提交 |

## 1. 迁移前核对与安全基础

- [ ] 1.1 对目标环境的 `as_system_user` 执行只读结构与数据质量核对：列、索引、重复用户名、角色码、状态值和现有数据量；把结果记录为部署前置条件，不写入数据库。
- [ ] 1.2 已获数据库结构变更批准：只读核对通过后，新增可审查的版本化迁移和反向回滚说明；保留原列，增加 `page_permissions`、`password_updated_at`、`auth_version`，建立用户名唯一索引，并创建仅在 `password_hash` 实际变化时自动更新时间、递增会话版本的触发器；迁移不得写入 `Jeddy` 的密码或哈希。
- [ ] 1.3 增加 Spring Security、JWT 与迁移工具依赖，固定兼容版本，并通过依赖检查确认不存在已知高危漏洞。
- [ ] 1.4 新增安全配置、密码编码器、Cookie/CSRF/CORS 策略和认证过滤器；仅公开登录、当前身份初始化所需接口与静态前端资源，其他 API 默认拒绝未认证访问。
- [ ] 1.5 增加部署前只读核对清单：固定开发者 `Jeddy` 必须为 `DEVELOPER` 且启用，其 BCrypt 哈希只由受控数据库操作人工写入；严禁将明文密码、哈希、JWT 密钥或数据库凭据写入 Git、迁移脚本或日志。

## 2. 后端认证与密码生命周期

- [ ] 2.1 新建认证请求/响应 DTO，验证用户名仅含字母、数字、下划线及密码边界，并在序列化和异常处理路径排除密码、哈希、Cookie 和密钥。
- [ ] 2.2 实现 BCrypt 密码校验与升级编码检测；密码设置/重置仅由开发者账号服务复用，且不创建任何自助改密接口或页面。
- [ ] 2.3 实现令牌签发、验签、过期、清除和 `auth_version` 校验；开发者重置密码、受控人工更新哈希和禁用账号必须立即使旧会话失效。
- [ ] 2.4 实现登录、当前用户和登出 API；失败响应保持一致，防止账户枚举；当前用户安全资料仅提供前端判断 `Jeddy` 专属欢迎提示所需的用户名与角色。
- [ ] 2.5 为认证接口添加单元/集成测试：正确登录、错误凭据统一响应、禁用账号、未登录 401、过期令牌、开发者重置后旧会话失效、手工更新 `Jeddy` 哈希后触发器更新时间并使旧会话失效、无自助改密端点和 CSRF 写操作。

## 3. 后端账号与逐页权限

- [ ] 3.1 扩展 `SystemUserEntity` 与 Mapper 查询，显式映射新增字段并为所有用户管理查询恒定排除 `DEVELOPER`，避免直接 `selectById` 泄露。
- [ ] 3.2 建立固定角色、首期五个注册页面键（总览、域名资料、企微资料、手机号资产、提醒中心）和 `NONE`/`READ`/`EDIT` 枚举；未知角色、未知页面和缺失权限全部按拒绝处理。
- [ ] 3.3 实现页面权限服务和统一 Controller 权限检查；开发者全量编辑、超级管理员全量编辑、其他角色仅使用已保存的逐页权限。
- [ ] 3.4 实现账号列表、创建、编辑、启停、仅开发者可用的密码设置/重置与权限保存 API，强制开发者/超级管理员创建边界：超级管理员新建账号必须无密码且默认禁用；阻止禁用最后一个可用管理账号。
- [ ] 3.5 为手机号和企微资产的 GET/POST/PUT/DELETE 接入相应页面的 READ/EDIT 校验，保持其原有 DTO、成功响应和业务服务调用不变。
- [ ] 3.6 为账号和权限 API 添加测试：开发者隐藏、开发者可创建全部、超级管理员不能创建开发者或修改密码、业务角色 403、只读用户读成功写失败、无权限用户 403、新页面默认拒绝。

## 4. 前端认证、路由与设置入口

- [ ] 4.1 新增认证 API 客户端和内存认证状态；所有请求使用 `credentials: 'include'`，统一处理 401 并禁止任何 token/password 写入 localStorage、sessionStorage 或日志。
- [ ] 4.2 新增登录页和无权页；登录失败使用不暴露账号状态的提示，且只有 `Jeddy` 以开发者角色登录成功的当次显示“🎉 欢迎系统开发者-BOSS：Jeddy 上线”。
- [ ] 4.3 扩展路由：注册 `/login`、无权和 `/settings/users-permissions`，并在全局守卫中根据 `/api/auth/me` 的服务端权限结果决定跳转；不注册自助改密路由。
- [ ] 4.4 改造主侧栏：按有效权限展示业务菜单，在“设置”分组新增图标加“账号与权限”文字入口；该入口仅开发者与超级管理员可见。
- [ ] 4.5 新增账号与权限独立路由页：列表中绝不展示开发者；创建和编辑表单按当前管理员身份过滤角色选项和密码输入（仅开发者可填）；逐页面板仅显示首期五个页面，并以单选/互斥勾选保证每页仅有无权限、只读、编辑之一。
- [ ] 4.6 让手机号和企微页面依据当前权限禁用或隐藏写操作，并保留后端 403 的错误提示；不以 UI 隐藏替代接口校验。
- [ ] 4.7 为新页面添加局部样式、键盘可达标签、加载/空态/403 状态，并在窄屏下验证菜单与权限面板可用。

## 5. 接口契约、测试和验收

- [ ] 5.1 编写或更新 OpenAPI/Apifox 可导入文档，分为“认证”和“账号与权限”两组，至少包含最小请求、成功响应、401/403/校验失败示例、错误码和前端调用点。
- [ ] 5.2 为后端增加 API 集成测试，为前端增加 Playwright 测试：登录、仅 `Jeddy` 的专属欢迎提示、菜单过滤、路由守卫、开发者隐藏、角色创建边界、超级管理员无密码权限、只读禁写、无权限 403、开发者重置后旧会话失效。
- [ ] 5.3 使用本地 `playwright_local` 执行登录与权限 smoke；不得对线上环境进行保存、提交、删除、密码重置或其他写操作。
- [ ] 5.4 执行 Maven 测试、前端构建/测试和最小 Apifox 回归；为每项输出 `[PASS]`/`[FAIL]`，失败退出码非 0，并把测试证据记入验收记录。
- [ ] 5.5 完成部署前检查：配置 JWT 密钥、Cookie Secure 策略、允许来源、数据库备份、首个开发者账号交接；验证密钥和 `.env` 均未被 Git 追踪。
- [ ] 5.6 输出最终新手流程图，覆盖登录成功/失败、`Jeddy` 专属欢迎提示、菜单/路由/接口三层权限、只读/编辑/无权限、开发者改密或禁用后的会话失效和迁移失败回滚。
