gitignore 提交

doc/jog-system-automated-test-plan.md

@@ -0,0 +1,478 @@
+# Jog System 自动化测试计划
+
+| 项目 | 内容 |
+| :--- | :--- |
+| 文档版本 | V1.0 |
+| 生成日期 | 2026-05-18 |
+| 适用范围 | Jog System 后端 Maven 多模块、Vue 3 前端、数据库迁移与部署验证 |
+| 测试目标 | 建立可持续运行的自动化测试体系，覆盖核心业务、接口契约、安全控制、前端流程和发布质量门禁 |
+
+---
+
+## 1. 项目扫描结论
+
+### 1.1 技术与模块
+
+本项目为前后端分离的博客系统：
+
+- 后端：Spring Boot 3.4.5、Java 21、Maven 多模块、Spring Security + JWT、MyBatis-Plus、MySQL、Redis、Flyway、SpringDoc OpenAPI。
+- 前端：Vue 3.5、Vite 6、Element Plus、Pinia、Vue Router、Axios、Tiptap。
+- 模块结构：
+  - `jog-common`：统一响应、分页模型、异常、枚举、限流注解等公共能力。
+  - `jog-framework`：安全配置、JWT、鉴权过滤器、XSS 过滤、限流切面、全局异常。
+  - `jog-module-system`：登录、注册、用户信息、管理员用户管理。
+  - `jog-module-blog`：文章、分类、标签、点赞、公开列表、后台文章管理。
+  - `jog-module-comment`：评论、回复、点赞、审核、后台评论管理。
+  - `jog-admin`：启动入口、应用配置、Flyway 数据库迁移。
+  - `jog-frontend`：前台浏览、登录注册、个人中心、文章编辑、后台管理页面。
+
+### 1.2 当前测试基础
+
+- 后端仅 `jog-admin` 显式引入 `spring-boot-starter-test`，其余业务模块未单独声明测试依赖。
+- 项目源码中未发现自有 `src/test` 测试目录。
+- 前端 `package.json` 当前仅包含 `dev`、`build`、`preview`，未配置单元测试、组件测试、E2E 测试或 lint 脚本。
+- `node_modules` 已存在于工作区，属于依赖产物，不纳入源码测试范围。
+
+### 1.3 扫描发现的测试重点
+
+- 后端 Controller 实际路径为 `/api/auth`、`/api/article`、`/api/comment`、`/api/admin/**`、`/api/public/**` 等。
+- 前端 API 封装中存在 `/api/public/user/login`、`/api/app/article/mine`、`/api/app/comment/**` 等路径，与当前后端 Controller 的部分路径不一致，应将“前后端接口契约一致性”列为首要自动化检查。
+- `SecurityConfig` 中 `/api/admin/**` 需要 `ADMIN` 角色，`/api/app/**` 需要 `USER` 或 `ADMIN`，但部分业务 Controller 未挂在 `/api/app` 下，需通过安全回归测试确认实际权限边界。
+- `application.yml` 中含真实数据库、Redis 地址和密码样式配置，测试环境应改用隔离配置与环境变量，禁止自动化测试直接访问生产或公网中间件。
+- 需求文档与当前代码实现存在差异，例如验证码、邮箱验证、多端会话上限、评论三级嵌套、图片上传、关注、通知、标签管理等能力并未完整落地，自动化测试应区分“已实现回归”和“需求缺口验证”。
+
+---
+
+## 2. 测试目标与质量门禁
+
+### 2.1 测试目标
+
+- 保证登录、注册、文章发布、文章浏览、点赞、评论、后台审核、分类和用户管理等核心链路稳定。
+- 保证 JWT 鉴权、角色权限、Token 刷新/登出、限流、XSS 防护、统一异常响应可持续回归。
+- 保证前后端 API 路径、请求方法、请求参数、响应结构一致。
+- 保证 Flyway 迁移脚本、实体映射、MyBatis-Plus 逻辑删除与分页查询可靠。
+- 保证前端路由守卫、表单校验、Axios 拦截器和关键页面交互可回归。
+
+### 2.2 推荐质量门禁
+
+| 阶段 | 必跑项 | 通过标准 |
+| :--- | :--- | :--- |
+| 本地提交前 | 后端单元测试、前端构建、前端单元测试 | 全部通过，无新增严重告警 |
+| 合并请求 | 后端集成测试、API 契约测试、前端组件测试、E2E 冒烟 | 全部通过，核心模块覆盖率达标 |
+| 发布前 | 全量 E2E、迁移脚本验证、安全回归、性能冒烟 | P0/P1 缺陷为 0，P2 有明确处理计划 |
+| 上线后 | 健康检查、核心链路巡检、日志错误扫描 | 首页/API/登录/发文/评论均可用 |
+
+### 2.3 覆盖率目标
+
+| 层级 | 建议目标 |
+| :--- | :--- |
+| 后端 Service 单元测试 | 行覆盖率 >= 80%，分支覆盖率 >= 70% |
+| 后端 Controller/API 测试 | 核心接口 100% 覆盖，错误路径至少覆盖主要业务错误码 |
+| 安全与鉴权测试 | 所有公开、登录、普通用户、管理员接口权限矩阵 100% 覆盖 |
+| 前端工具/API/Store 单元测试 | 行覆盖率 >= 70% |
+| 前端关键页面组件测试 | 登录、注册、首页、详情、编辑器、后台列表页面全覆盖 |
+| E2E 测试 | 核心用户旅程 100% 覆盖，非核心后台功能冒烟覆盖 |
+
+---
+
+## 3. 测试分层策略
+
+### 3.1 后端单元测试
+
+推荐工具：JUnit 5、Mockito、AssertJ、Spring Security Test。
+
+重点覆盖：
+
+- `AuthServiceImpl`
+  - 邮箱不存在、密码错误、账号锁定、登录成功。
+  - 管理员登录的角色校验。
+  - 注册邮箱唯一性、密码加密、默认用户状态。
+  - Refresh Token 校验失败、用户不存在、刷新成功。
+  - 登出时 Token 加入黑名单。
+- `UserServiceImpl`
+  - 当前用户信息查询。
+  - 用户列表分页、状态筛选。
+  - 管理员重置密码、锁定/解锁用户。
+- `ArticleServiceImpl`
+  - 创建草稿/发布文章、发布时间设置。
+  - 更新文章、标签重建、作者权限校验。
+  - 公开列表分页、分类/标签/关键词过滤。
+  - 我的文章、后台文章列表。
+  - 回收站、恢复、作者删除、管理员删除。
+  - 浏览量递增、点赞/取消点赞、文章不存在。
+- `CategoryServiceImpl`
+  - 分类创建、重名、更新、删除。
+  - 启用分类列表排序。
+- `CommentServiceImpl`
+  - 创建根评论和回复。
+  - 父评论不存在、回复层级限制。
+  - 评论列表根评论与回复排序。
+  - 作者删除权限、管理员审核、点赞/取消点赞。
+- `RateLimitAspect`、`JwtTokenProvider`、`TokenBlacklistService`、`XssFilter`
+  - 限流 Key 与过期时间。
+  - Token 生成、解析、过期、非法签名。
+  - 黑名单命中。
+  - 常见 XSS payload 过滤。
+
+### 3.2 后端集成测试
+
+推荐工具：Spring Boot Test、MockMvc、Testcontainers（MySQL、Redis）、Flyway、spring-security-test。
+
+重点覆盖：
+
+- 使用 Testcontainers 启动隔离 MySQL/Redis，运行 Flyway 迁移。
+- 验证 `V1__init_schema.sql` 与 `V2__init_data.sql` 可重复初始化干净环境。
+- 验证实体 `@TableName` 与实际表名一致，重点关注 `sys_user`/`blog_article` 等表与代码实体映射。
+- 验证 MyBatis-Plus 分页插件、逻辑删除字段、唯一索引冲突、事务回滚。
+- 使用 MockMvc 对 Controller 执行端到端接口测试，断言 HTTP 状态、统一响应结构、业务错误码和数据库副作用。
+
+### 3.3 API 契约测试
+
+推荐工具：SpringDoc OpenAPI 导出、Schemathesis 或 Dredd、Postman/Newman、或自定义 OpenAPI diff。
+
+契约测试必须覆盖：
+
+- 后端 OpenAPI 与前端 `src/api/*.js` 中路径、方法、参数一致。
+- 统一响应结构 `ApiResult` 字段稳定：`code`、`message`、`data`。
+- 分页响应 `PageResult` 字段稳定：列表、总数、页码、页大小。
+- 401、403、429、业务异常响应格式一致。
+- Token 刷新接口路径一致。当前前端调用 `/api/public/refresh-token`，后端扫描到的是 `/api/auth/refresh`，需优先纳入失败用例。
+
+### 3.4 前端单元与组件测试
+
+推荐工具：Vitest、Vue Test Utils、jsdom、MSW、Testing Library。
+
+重点覆盖：
+
+- `utils/request.js`
+  - 请求自动附加 `Authorization`。
+  - 业务 `code !== 200` 的错误处理。
+  - 401 清理本地 Token 并跳转登录。
+  - 403、429、网络错误提示。
+  - Token 刷新失败/成功后的重试逻辑。
+- `router/index.js`
+  - 未登录访问 `/app/**` 和 `/admin/**` 跳转登录。
+  - 登录后路由放行。
+  - 页面标题设置。
+  - 管理员路由需要补充前端角色校验测试；当前代码只检查 token，未检查 `requiresAdmin`。
+- 页面组件
+  - `Login.vue`、`Register.vue`：表单校验、提交状态、错误提示、登录后跳转。
+  - `Home.vue`：列表加载、分页、分类筛选、空状态。
+  - `ArticleDetail.vue`：详情渲染、评论列表、点赞、评论提交。
+  - `ArticleEditor.vue`：标题/内容校验、草稿/发布、分类标签选择、编辑回填。
+  - 后台 `Users.vue`、`Articles.vue`、`Comments.vue`、`Categories.vue`：列表、筛选、分页、操作确认。
+
+### 3.5 E2E 测试
+
+推荐工具：Playwright。
+
+建议用户旅程：
+
+1. 访客打开首页，查看公开文章列表，进入文章详情。
+2. 新用户注册、登录、进入个人控制台。
+3. 用户创建草稿、发布文章、编辑文章、移入回收站、恢复文章、删除文章。
+4. 另一用户浏览文章、点赞文章、发表评论、回复评论、取消点赞。
+5. 管理员登录后台，查看用户列表、重置密码、锁定用户。
+6. 管理员查看文章列表、删除违规文章。
+7. 管理员查看评论列表、审核评论、删除评论。
+8. 分类创建、编辑、删除后，前台筛选结果同步变化。
+9. 未登录用户访问编辑页会被重定向到登录页，并在登录后返回原目标页。
+10. 普通用户尝试访问后台应被拒绝。
+
+### 3.6 安全自动化测试
+
+重点用例：
+
+- JWT
+  - 缺失 Token、伪造 Token、过期 Token、黑名单 Token。
+  - 用户 Token 访问管理员接口返回 403。
+  - 管理员 Token 访问后台接口成功。
+- 限流
+  - 登录 60 秒内超过 5 次被限制。
+  - 注册 1 小时内超过 3 次被限制。
+  - 限流 Key 应区分 IP/用户/接口，避免全局误伤。
+- XSS
+  - 文章和评论中提交 `<script>`、事件属性、`javascript:` 链接。
+  - 富文本合法标签不应被过度清洗。
+- CORS/CSRF
+  - CORS 允许策略在生产环境应收敛，自动化检查不允许 `*` 与凭证同时进入生产配置。
+  - CSRF 已关闭，需确认仅用于 JWT 无状态 API。
+- 敏感信息
+  - 扫描配置文件中数据库密码、Redis 密码、JWT 密钥、邮箱密码。
+  - 自动化测试禁止连接 `application.yml` 中公网数据库和 Redis。
+
+### 3.7 性能与可靠性测试
+
+推荐工具：k6、JMeter 或 Gatling。
+
+冒烟指标：
+
+- 首页文章列表 P95 < 500ms。
+- 文章详情 P95 < 500ms。
+- 登录接口 P95 < 800ms。
+- 创建文章 P95 < 1000ms。
+- 评论列表 P95 < 500ms。
+- 50 并发用户下错误率 < 1%。
+
+专项场景：
+
+- 高频浏览文章详情时浏览量更新是否产生锁竞争或丢失更新。
+- 点赞/取消点赞并发操作是否出现负数计数或唯一索引冲突。
+- 评论列表在大量回复下的 N+1 查询问题。
+- 后台文章/评论/用户分页在万级数据下的响应时间。
+
+---
+
+## 4. 测试环境规划
+
+### 4.1 环境分层
+
+| 环境 | 用途 | 数据策略 |
+| :--- | :--- | :--- |
+| Local | 开发者快速回归 | H2 或 Testcontainers，测试结束自动销毁 |
+| CI | 合并请求质量门禁 | Testcontainers MySQL/Redis，固定种子数据 |
+| Staging | 发布前全量验证 | 与生产拓扑接近，脱敏数据 |
+| Prod Smoke | 上线后巡检 | 只执行只读或专用测试账号的轻量用例 |
+
+### 4.2 测试配置要求
+
+- 新增 `application-test.yml`，数据库和 Redis 全部来自 Testcontainers 或本地隔离实例。
+- Flyway 在测试环境启用，保证迁移脚本真实可用。
+- 禁止测试代码读取公网数据库地址、真实 Redis 密码、真实 SMTP。
+- 测试账号和测试文章使用固定前缀，例如 `auto_test_`，便于清理。
+- 前端 E2E 使用独立 `.env.test`，指向测试后端。
+
+---
+
+## 5. 测试数据设计
+
+### 5.1 基础数据
+
+| 类型 | 数据 |
+| :--- | :--- |
+| 管理员 | `admin@example.com`，角色 ADMIN |
+| 普通用户 A | `user_a@example.com`，角色 USER |
+| 普通用户 B | `user_b@example.com`，角色 USER |
+| 锁定用户 | `locked@example.com`，状态 LOCKED |
+| 分类 | 技术、生活、公告 |
+| 标签 | Java、Vue、测试、随笔 |
+| 文章 | 草稿、公开已发布、私密、回收站、已删除 |
+| 评论 | 根评论、一级回复、待审核、已屏蔽、已删除 |
+
+### 5.2 边界数据
+
+- 标题空、标题 200 字、标题 201 字。
+- 密码长度 5、6、20、21。
+- 评论内容空、1000 字、超过 1000 字。
+- 分页 `page=0`、`page=1`、`pageSize=1`、`pageSize=100`、`pageSize=101`。
+- 不存在的用户 ID、文章 ID、评论 ID、分类 ID。
+- 重复邮箱、重复分类名、重复点赞。
+- 富文本中包含合法 HTML、XSS payload、超长内容。
+
+---
+
+## 6. 自动化用例清单
+
+### 6.1 认证与用户
+
+| 编号 | 类型 | 场景 | 预期 |
+| :--- | :--- | :--- | :--- |
+| AUTH-001 | 单元/API | 正确邮箱密码登录 | 返回 accessToken、refreshToken、用户信息 |
+| AUTH-002 | 单元/API | 邮箱不存在 | 返回用户不存在错误，记录失败日志 |
+| AUTH-003 | 单元/API | 密码错误 | 返回密码错误，记录失败日志 |
+| AUTH-004 | 单元/API | 锁定用户登录 | 返回账号锁定 |
+| AUTH-005 | 单元/API | 普通用户调用管理员登录 | 返回权限不足 |
+| AUTH-006 | API | 注册新邮箱 | 用户入库，密码为 BCrypt |
+| AUTH-007 | API | 重复邮箱注册 | 返回邮箱已存在 |
+| AUTH-008 | API | 刷新 Token | 返回新的 accessToken 和 refreshToken |
+| AUTH-009 | API | 非法 refreshToken | 返回 Token 无效 |
+| AUTH-010 | API | 登出后使用旧 Token | 被拒绝或命中黑名单 |
+| USER-001 | API | 获取当前用户信息 | 返回登录用户资料 |
+| USER-002 | API | 管理员分页查询用户 | 返回分页结构 |
+| USER-003 | API | 管理员重置密码 | 新密码可登录，旧密码失效 |
+| USER-004 | API | 管理员锁定用户 | 被锁定用户无法登录 |
+
+### 6.2 文章与分类标签
+
+| 编号 | 类型 | 场景 | 预期 |
+| :--- | :--- | :--- | :--- |
+| BLOG-001 | 单元/API | 创建草稿 | 状态为草稿，无发布时间 |
+| BLOG-002 | 单元/API | 发布文章 | 状态为已发布，生成发布时间 |
+| BLOG-003 | 单元/API | 更新文章标签 | 旧关联删除，新关联创建 |
+| BLOG-004 | API | 非作者更新文章 | 返回权限不足 |
+| BLOG-005 | API | 公开列表仅显示公开已发布 | 草稿、私密、回收站不出现 |
+| BLOG-006 | API | 按分类筛选 | 只返回该分类文章 |
+| BLOG-007 | API | 按标签筛选 | 只返回该标签文章 |
+| BLOG-008 | API | 关键词搜索 | 标题或摘要匹配 |
+| BLOG-009 | API | 我的文章列表 | 只返回当前用户文章 |
+| BLOG-010 | API | 移入回收站 | 状态变为回收站 |
+| BLOG-011 | API | 恢复文章 | 状态变为草稿 |
+| BLOG-012 | API | 点赞文章 | 点赞记录创建，计数 +1 |
+| BLOG-013 | API | 取消点赞 | 点赞记录删除，计数 -1 且不为负 |
+| BLOG-014 | API | 后台文章列表 | 管理员可按状态/分类/关键词筛选 |
+| CAT-001 | API | 创建分类 | 分类入库，可在公开列表读取 |
+| CAT-002 | API | 重名分类 | 返回唯一性错误 |
+| CAT-003 | API | 更新分类 | 名称、描述、排序生效 |
+| CAT-004 | API | 删除分类 | 分类不可再查询或被逻辑处理 |
+
+### 6.3 评论
+
+| 编号 | 类型 | 场景 | 预期 |
+| :--- | :--- | :--- | :--- |
+| CMT-001 | 单元/API | 创建根评论 | 评论状态为通过，文章 ID 正确 |
+| CMT-002 | 单元/API | 回复根评论 | parentId 正确 |
+| CMT-003 | 单元/API | 回复二级评论 | 返回层级限制错误 |
+| CMT-004 | API | 非作者删除评论 | 返回权限不足 |
+| CMT-005 | API | 作者删除评论 | 评论被删除 |
+| CMT-006 | API | 评论列表 | 根评论倒序，回复正序 |
+| CMT-007 | API | 点赞评论 | 点赞记录创建，计数 +1 |
+| CMT-008 | API | 取消点赞评论 | 点赞记录删除，计数 -1 且不为负 |
+| CMT-009 | API | 管理员分页查询评论 | 返回分页结构 |
+| CMT-010 | API | 管理员审核评论 | 评论状态更新 |
+| CMT-011 | API | 管理员删除评论 | 评论不可见 |
+
+### 6.4 前端页面与交互
+
+| 编号 | 类型 | 场景 | 预期 |
+| :--- | :--- | :--- | :--- |
+| FE-001 | 单元 | Axios 自动附加 Token | 请求头包含 Bearer Token |
+| FE-002 | 单元 | 业务响应 code 非 200 | 展示错误并 reject |
+| FE-003 | 单元 | 401 响应 | 清理本地登录态并跳转登录 |
+| FE-004 | 单元 | 未登录访问 `/app/dashboard` | 跳转登录并携带 redirect |
+| FE-005 | 单元 | 未登录访问 `/admin` | 跳转登录 |
+| FE-006 | 组件 | 登录表单提交成功 | 保存 Token 并跳转 |
+| FE-007 | 组件 | 注册表单校验失败 | 阻止提交并提示 |
+| FE-008 | 组件 | 首页列表加载 | 渲染文章卡片、分页和空状态 |
+| FE-009 | 组件 | 文章详情加载 | 渲染正文、点赞、评论 |
+| FE-010 | 组件 | 编辑器发布文章 | 调用创建/更新 API |
+| FE-011 | 组件 | 后台列表操作 | 筛选、分页、删除/审核确认 |
+| FE-012 | 契约 | 前端 API 路径与后端 OpenAPI 对比 | 不允许出现未实现路径 |
+
+### 6.5 安全与异常
+
+| 编号 | 类型 | 场景 | 预期 |
+| :--- | :--- | :--- | :--- |
+| SEC-001 | API | 无 Token 访问需登录接口 | 返回 401 |
+| SEC-002 | API | 普通用户访问 `/api/admin/**` | 返回 403 |
+| SEC-003 | API | 管理员访问后台接口 | 成功 |
+| SEC-004 | API | 伪造 JWT | 返回 401 |
+| SEC-005 | API | 黑名单 JWT | 返回 401 |
+| SEC-006 | API | 登录限流 | 超限返回 429 或业务限流错误 |
+| SEC-007 | API | 注册限流 | 超限返回 429 或业务限流错误 |
+| SEC-008 | API | 文章提交 XSS | 脚本被过滤或拒绝 |
+| SEC-009 | API | 评论提交 XSS | 脚本被过滤或拒绝 |
+| SEC-010 | 静态扫描 | 配置文件敏感信息 | CI 阻断硬编码密码和密钥 |
+
+---
+
+## 7. CI/CD 自动化建议
+
+### 7.1 推荐脚本
+
+后端建议新增：
+
+```bash
+mvn -B clean verify
+```
+
+前端建议新增：
+
+```bash
+npm ci
+npm run test:unit
+npm run test:component
+npm run build
+npm run test:e2e
+```
+
+### 7.2 推荐新增依赖与脚本
+
+后端：
+
+- 在父 POM 统一管理测试依赖：JUnit 5、Mockito、AssertJ、Testcontainers MySQL/Redis、Spring Security Test、JaCoCo。
+- 将测试依赖下沉到需要测试的模块，避免只有启动模块能写测试。
+- 配置 Maven Surefire/Failsafe，区分单元测试和集成测试。
+
+前端：
+
+- 新增 Vitest、Vue Test Utils、jsdom、MSW、Playwright。
+- 在 `package.json` 中新增：
+  - `test:unit`
+  - `test:component`
+  - `test:e2e`
+  - `test:e2e:ui`
+  - `coverage`
+
+### 7.3 Pipeline 阶段
+
+1. 依赖安装与缓存。
+2. 后端编译与单元测试。
+3. 后端集成测试，启动 MySQL/Redis Testcontainers。
+4. 生成 OpenAPI 文档。
+5. 前端 API 封装与 OpenAPI 契约对比。
+6. 前端单元/组件测试。
+7. 前端生产构建。
+8. 启动完整应用，运行 Playwright E2E 冒烟。
+9. 上传测试报告、覆盖率报告和 E2E 截图/视频。
+
+---
+
+## 8. 缺陷分级与处理策略
+
+| 等级 | 定义 | 示例 | 处理要求 |
+| :--- | :--- | :--- | :--- |
+| P0 | 系统不可用或核心数据损坏 | 无法启动、登录全失败、发文数据丢失 | 立即阻断发布 |
+| P1 | 核心业务不可用或严重安全问题 | 普通用户可访问后台、Token 绕过、评论 XSS | 阻断合并/发布 |
+| P2 | 重要功能异常但有规避方式 | 筛选错误、分页异常、后台单项操作失败 | 发布前修复或明确延期 |
+| P3 | 轻微体验或边界问题 | 文案不准、空状态异常、非核心兼容问题 | 排入迭代 |
+
+---
+
+## 9. 当前优先落地路线
+
+### 第一阶段：补齐基础测试设施
+
+- 后端新增 `src/test` 目录、`application-test.yml`、JUnit/Mockito/Testcontainers/JaCoCo。
+- 前端新增 Vitest、Vue Test Utils、MSW、Playwright。
+- 建立 CI 基础命令：后端 `mvn verify`，前端 `npm run build` + 单元测试。
+
+### 第二阶段：先保护最容易出事故的链路
+
+- 认证：登录、注册、刷新、登出、管理员权限。
+- 契约：前端 API 路径和后端 Controller/OpenAPI 对比。
+- 文章：创建、发布、列表、详情、更新、删除、点赞。
+- 评论：创建、列表、回复、删除、审核、点赞。
+
+### 第三阶段：增强安全与发布信心
+
+- XSS、限流、JWT 黑名单、CORS、敏感信息扫描。
+- Flyway 迁移全量验证。
+- Playwright 覆盖访客、普通用户、管理员三类角色端到端流程。
+- k6/JMeter 做核心接口性能冒烟。
+
+---
+
+## 10. 风险清单
+
+| 风险 | 影响 | 建议 |
+| :--- | :--- | :--- |
+| 前后端 API 路径不一致 | 前端页面调用失败 | 优先建立契约测试，并统一 `/api/auth`、`/api/article`、`/api/comment` 或 `/api/app/**` 路由规范 |
+| 生产/公网中间件配置在默认配置中 | 自动化测试可能误连真实服务 | 建立 `application-test.yml`，CI 强制覆盖数据源 |
+| 自有测试目录缺失 | 回归依赖人工验证 | 先补 Service 单元测试和 Controller 集成测试 |
+| 需求文档与代码实现差异 | 验收标准不清 | 将未实现需求标为 pending/xfail，并建立需求追踪 |
+| 前端缺少测试脚本 | UI 回归成本高 | 引入 Vitest 和 Playwright，先覆盖核心旅程 |
+| 点赞计数并发更新 | 可能出现计数错乱或负数 | 加并发集成测试，必要时改为原子 SQL 更新 |
+| 评论和文章富文本安全 | XSS 风险 | 加 payload 回归测试，确认过滤链路覆盖请求体 |
+
+---
+
+## 11. 验收标准
+
+自动化测试计划落地后，应满足：
+
+- 每次合并请求自动运行后端单元测试、集成测试、前端单元/组件测试和构建。
+- 每次发布前自动运行核心 E2E、数据库迁移验证和安全回归。
+- 测试报告可追溯到用例、模块、提交和失败截图/日志。
+- 新增核心业务功能必须同步新增或更新自动化用例。
+- P0/P1 自动化失败不得合并，不得发布。
+

doc/jog-system-bug-list.md

@@ -0,0 +1,246 @@
+# Jog System 自动化测试 Bug 清单
+
+| 项目 | 内容 |
+| :--- | :--- |
+| 生成日期 | 2026-05-18 |
+| 测试依据 | `doc/jog-system-automated-test-plan.md` |
+| 测试范围 | 后端 Maven 编译/测试、前端 Vite 构建、前后端 API 契约静态检查、数据库迁移/实体映射静态检查、安全配置静态检查 |
+
+---
+
+## 1. 测试执行摘要
+
+| 测试项 | 命令/方式 | 结果 |
+| :--- | :--- | :--- |
+| 后端编译与测试 | `mvn -B test` | 通过编译，但所有模块均显示 `No tests to run`，未执行任何自有测试 |
+| 前端构建（旧 Node） | `npm run build` | 失败，Node `v16.20.2` 下 Vite 启动时报 `crypto$2.getRandomValues is not a function` |
+| 前端构建（已切换 Node） | `npm run build` | 通过，当前 Node `v24.15.0`、npm `11.12.1`，构建产物已输出到 `jog-admin/src/main/resources/static` |
+| API 契约检查 | 对比 `jog-frontend/src/api/*.js` 与后端 Controller | 发现多处路径和 HTTP 方法不一致 |
+| 数据库映射检查 | 对比实体 `@TableName` 与 Flyway 建表脚本 | 发现表名、字段名大面积不一致 |
+| 安全配置检查 | 对比 JWT 角色生成、SecurityConfig、Controller 路径 | 发现管理员角色无法匹配、用户接口未被鉴权规则保护 |
+
+---
+
+## 1.1 本轮修复记录
+
+| Bug | 当前状态 | 修复摘要 |
+| :--- | :--- | :--- |
+| BUG-003 | 已修复，待数据库集成验证 | 实体 `@TableName` 已对齐 `sys_*` / `blog_*` 表名 |
+| BUG-004 | 已修复，待数据库集成验证 | 对差异字段补充 `@TableField`，覆盖用户类型、会话 token/过期时间、登录结果、评论回复目标等 |
+| BUG-005 | 已修复 | JWT access token 角色改为 `ADMIN` / `USER`，过滤器兼容旧数字角色 |
+| BUG-006 | 已修复 | 用户侧 Controller 已统一到 `/api/app/**`，并由 SecurityConfig 保护 |
+| BUG-007 | 已修复 | 认证接口已对齐前端 `/api/public/user/login`、`/api/public/admin/login`、`/api/public/user/register`、`/api/public/refresh-token` |
+| BUG-008 | 已修复 | 文章、评论、用户接口已对齐前端 `/api/app/**` 路径 |
+| BUG-009 | 已修复 | 回收站、恢复、评论审核、用户重置密码、用户状态更新的 HTTP 方法已对齐前端 |
+| BUG-010 | 部分修复 | 已补标签列表/创建、验证码占位接口、关注/取关接口；验证码当前仅返回占位数据，不做真实校验 |
+| BUG-011 | 已修复 | 前端路由已根据 `requiresAdmin` 校验本地用户角色 |
+| BUG-012 | 已修复 | `V2__init_data.sql` 已移除 `USE blog_db` |
+| BUG-013 | 已修复 | 文章详情标签改为返回结构化 `Tag` 对象，匹配前端 `id/name` 使用方式 |
+
+---
+
+## 2. Bug 清单
+
+### BUG-001 前端构建在旧 Node 版本下无法启动
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P3 |
+| 状态 | 已验证解决：Node 已切换至 `v24.15.0` 后构建通过 |
+| 位置 | `jog-frontend/package.json`、本机 Node 环境 |
+| 复现 | 在 `jog-frontend` 执行 `npm run build` |
+| 实际结果 | `TypeError: crypto$2.getRandomValues is not a function` |
+| 期望结果 | 前端可完成生产构建 |
+| 证据 | 旧 Node 版本为 `v16.20.2`，切换到 `v24.15.0` 后 `npm run build` 成功 |
+| 建议 | 在 README/部署文档和 `package.json engines` 中声明 Node >= 20；本地和 CI 统一 Node 版本 |
+
+### BUG-002 使用新版 Node 后前端构建失败
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P3 |
+| 状态 | 无法复现/已恢复：用户切换 Node 后 `npm run build` 通过 |
+| 位置 | `jog-frontend/vite.config.js:29` |
+| 复现 | 使用 Node `v24.14.0` 执行 `node node_modules/vite/bin/vite.js build` |
+| 实际结果 | `[vite:build-html] The "fileName" or "name" properties of emitted chunks and assets must be strings that are neither absolute nor relative paths, received "E:/person/Jog/jog-frontend/index.html"` |
+| 期望结果 | 构建产物成功输出到后端静态资源目录 |
+| 最新验证 | 当前 Node `v24.15.0`、npm `11.12.1` 下执行 `npm run build` 成功 |
+| 建议 | 保留 CI 构建验证；若再次出现该错误，再检查 Node/npm/Vite 解析路径差异 |
+
+### BUG-002A 前端构建存在低优先级告警
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P3 |
+| 状态 | 待优化 |
+| 位置 | `jog-frontend` 构建配置与本机 npm 配置 |
+| 实际结果 | 构建成功，但 npm 输出多条 Unknown user config 警告；Vite 输出主 chunk 超过 500 kB 的警告 |
+| 期望结果 | CI 构建日志干净，首屏资源大小可控 |
+| 影响 | 暂不阻断发布，但会降低构建日志可读性，主包偏大可能影响首屏性能 |
+| 建议 | 清理过期 npm 配置；为 Element Plus、Tiptap 等依赖配置合理分包或接受当前 warning 并设置 chunk 预算 |
+
+### BUG-003 实体表名与 Flyway 建表脚本不一致，运行时会查不到表
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P0 |
+| 状态 | 待修复 |
+| 位置 | `jog-module-system/src/main/java/.../entity/*.java`、`jog-module-blog/src/main/java/.../entity/*.java`、`jog-module-comment/src/main/java/.../entity/*.java`、`jog-admin/src/main/resources/db/migration/V1__init_schema.sql` |
+| 复现 | 启用 Flyway 初始化后调用任意 Mapper 查询 |
+| 实际结果 | 实体使用 `@TableName("user")`、`article`、`comment`、`category` 等；SQL 创建的是 `sys_user`、`blog_article`、`blog_comment`、`blog_category` 等 |
+| 期望结果 | 实体表名与数据库真实表名一致 |
+| 影响 | 登录、注册、文章、评论、分类等数据库操作都会失败 |
+| 建议 | 统一命名策略：要么实体改为 `sys_*`/`blog_*`，要么迁移脚本改为无前缀表；推荐按迁移脚本保留前缀并修正实体 |
+
+### BUG-004 实体字段与数据库字段不一致，多个核心写入会失败或数据错列
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P0 |
+| 状态 | 待修复 |
+| 位置 | `User.java`、`UserSession.java`、`LoginLog.java`、`Comment.java`、`V1__init_schema.sql` |
+| 实际结果 | 例如 `User.type` 对应代码字段，但 SQL 是 `user_type`；`UserSession.refreshToken/expiresAt` 对应 SQL 的 `token/expire_time`；`LoginLog.email/status/userAgent` 对应 SQL 的 `username/result` 且 SQL 无 `user_agent`；`Comment.replyToId` 对应 SQL 的 `reply_to_user_id` |
+| 期望结果 | 字段名可通过 MyBatis-Plus 正确映射 |
+| 影响 | 登录记录、会话保存、用户角色、评论回复等核心链路会失败 |
+| 建议 | 为差异字段添加 `@TableField("实际字段名")`，或统一 SQL 字段命名；同时增加 Mapper 集成测试覆盖插入/查询 |
+
+### BUG-005 JWT 角色值与 Spring Security 角色规则不匹配，管理员接口会 403
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P0 |
+| 状态 | 待修复 |
+| 位置 | `jog-framework/src/main/java/fun/nojava/framework/security/JwtTokenProvider.java:18`、`JwtAuthenticationFilter.java:39`、`SecurityConfig.java:51` |
+| 实际结果 | Token 中 `role` 写入的是数字字符串 `0`/`1`，过滤器生成 `ROLE_0`/`ROLE_1`；但安全配置要求 `/api/admin/**` 具备 `ROLE_ADMIN` |
+| 期望结果 | 管理员 Token 应匹配 `ROLE_ADMIN`，普通用户 Token 应匹配 `ROLE_USER` |
+| 影响 | 管理后台 API 无法正常访问；普通用户权限判断也不稳定 |
+| 建议 | Token 中存储 `ADMIN`/`USER`，或在过滤器中将 `UserType` code 转换为角色名 |
+
+### BUG-006 用户文章/评论接口未被 Spring Security 鉴权规则保护
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P0 |
+| 状态 | 待修复 |
+| 位置 | `SecurityConfig.java:52`、`ArticleController.java:16`、`CommentController.java:19`、`UserController.java:15` |
+| 实际结果 | 安全配置只保护 `/api/app/**`，但后端用户业务接口实际是 `/api/article`、`/api/comment`、`/api/user`；这些路径最终落入 `anyRequest().permitAll()` |
+| 期望结果 | 创建/更新/删除文章、发表评论、删除评论、获取当前用户等接口必须要求登录 |
+| 影响 | 未登录用户可能访问写接口，`@AuthenticationPrincipal Long userId` 为空后还可能导致脏数据或空指针 |
+| 建议 | 统一后端用户接口前缀为 `/api/app/**`，或在 `SecurityConfig` 中显式保护 `/api/article/**`、`/api/comment/**`、`/api/user/**` |
+
+### BUG-007 前后端认证接口路径完全不一致
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P0 |
+| 状态 | 待修复 |
+| 位置 | `jog-frontend/src/api/auth.js:4`、`auth.js:8`、`auth.js:12`、`auth.js:20`、`jog-module-system/src/main/java/.../AuthController.java:18` |
+| 实际结果 | 前端调用 `/api/public/admin/login`、`/api/public/user/login`、`/api/public/user/register`、`/api/public/refresh-token`；后端提供 `/api/auth/admin/login`、`/api/auth/login`、`/api/auth/register`、`/api/auth/refresh` |
+| 期望结果 | 前端 API 封装与后端 Controller 路径一致 |
+| 影响 | 登录、注册、Token 刷新全部 404，系统无法完成认证 |
+| 建议 | 建立 OpenAPI 契约检查；统一使用 `/api/auth/**` 或调整后端兼容前端路径 |
+
+### BUG-008 前后端文章/评论/用户接口路径不一致
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P0 |
+| 状态 | 待修复 |
+| 位置 | `jog-frontend/src/api/article.js:12`、`article.js:24`、`comment.js:4`、`auth.js:24`、后端 `ArticleController.java:16`、`CommentController.java:19`、`UserController.java:15` |
+| 实际结果 | 前端使用 `/api/app/article`、`/api/app/article/mine`、`/api/app/comment`、`/api/app/user/me`；后端实际是 `/api/article`、`/api/article/my`、`/api/comment`、`/api/user/info` |
+| 期望结果 | 前后端路径一致 |
+| 影响 | 登录后的发文、我的文章、评论、当前用户信息等核心页面无法工作 |
+| 建议 | 统一用户端路径前缀和资源命名，建议后端对齐 `/api/app/**` 或前端全部改为后端当前路径 |
+
+### BUG-009 多个前端请求 HTTP 方法与后端不一致
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P1 |
+| 状态 | 待修复 |
+| 位置 | `jog-frontend/src/api/article.js:28`、`article.js:32`、`comment.js:24`、`admin.js:8`、`admin.js:12`；后端对应 Controller |
+| 实际结果 | 前端对回收站/恢复/审核/重置密码/状态更新使用 `PUT`；后端分别使用 `POST` |
+| 期望结果 | 同一接口请求方法一致 |
+| 影响 | 即使路径修正，仍会返回 405 或无法命中接口 |
+| 建议 | 按 REST 风格统一：状态变更可用 `PUT/PATCH`，动作型接口可用 `POST`，但前后端必须一致 |
+
+### BUG-010 前端调用了后端未实现的接口
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P1 |
+| 状态 | 待修复 |
+| 位置 | `jog-frontend/src/api/auth.js:16`、`auth.js:36`、`auth.js:40`、`article.js:44`、`article.js:60` |
+| 实际结果 | 前端调用验证码 `/api/public/captcha`、关注/取关、公开标签列表、管理员创建标签；后端未发现对应 Controller 映射 |
+| 期望结果 | 前端只调用已实现接口，或后端补齐对应接口 |
+| 影响 | 登录页验证码、关注功能、文章编辑标签选择、后台标签管理会失败 |
+| 建议 | 根据需求决定补实现还是移除前端入口；未实现需求应在自动化测试中标记为 pending |
+
+### BUG-011 前端管理员路由只校验 Token，不校验管理员角色
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P1 |
+| 状态 | 待修复 |
+| 位置 | `jog-frontend/src/router/index.js` |
+| 实际结果 | 路由定义有 `requiresAdmin`，但 `beforeEach` 只检查 `requiresAuth` 和 token，不检查用户类型 |
+| 期望结果 | 普通用户访问 `/admin/**` 应在前端被拒绝或重定向 |
+| 影响 | 普通用户可进入后台页面，虽然后端也应拦截，但会造成越权界面暴露和误导 |
+| 建议 | 从 `user_info` 或 Store 中读取用户类型，补充 `requiresAdmin` 判断；后端仍保留最终权限校验 |
+
+### BUG-012 V2 初始化脚本写死 `USE blog_db`，与当前配置不一致
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P1 |
+| 状态 | 待修复 |
+| 位置 | `jog-admin/src/main/resources/db/migration/V2__init_data.sql:4`、`application.yml` |
+| 实际结果 | 初始化脚本写死 `USE blog_db;`，当前应用数据源库名不是同一个命名 |
+| 期望结果 | Flyway 迁移脚本不应写死切库，应该使用当前连接的 schema |
+| 影响 | 首次初始化可能写入错误数据库或直接失败 |
+| 建议 | 删除 `USE blog_db;`，由 JDBC URL 指定 schema；CI 中增加 Flyway clean/migrate 测试 |
+
+### BUG-013 文章详情返回的标签结构与前端期望不一致
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P2 |
+| 状态 | 待修复 |
+| 位置 | `ArticleServiceImpl.java:283`、`ArticleVO.java`、`jog-frontend/src/views/ArticleDetail.vue:13`、`ArticleEditor.vue:100` |
+| 实际结果 | 后端 `ArticleVO.tags` 是 `List<String>`；前端按 `tag.id`、`tag.name` 使用 |
+| 期望结果 | 标签返回结构与前端一致 |
+| 影响 | 文章详情标签显示异常，编辑文章时标签无法正确回填 |
+| 建议 | 后端返回 `List<TagVO>`，或前端改为字符串数组渲染；编辑器需要 ID 时推荐返回结构化对象 |
+
+### BUG-014 限流 Key 未包含 IP 或用户维度，所有用户共享同一限流桶
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P2 |
+| 状态 | 待修复 |
+| 位置 | `jog-framework/src/main/java/fun/nojava/framework/aspect/RateLimitAspect.java:41` |
+| 实际结果 | Redis Key 仅为 `rate_limit:` + 注解 key，例如所有用户共享 `rate_limit:login` |
+| 期望结果 | 登录、注册等限流至少按 IP 或账号维度隔离 |
+| 影响 | 一个用户频繁请求会误伤所有用户；也无法实现需求中的“同一 IP”限流 |
+| 建议 | 将 IP、用户 ID、请求路径或账号加入限流 Key；补充并发/限流集成测试 |
+
+### BUG-015 当前项目没有自有自动化测试，质量门禁失效
+
+| 字段 | 内容 |
+| :--- | :--- |
+| 严重级别 | P2 |
+| 状态 | 待补齐 |
+| 位置 | 全项目 |
+| 实际结果 | `mvn -B test` 成功但所有模块均显示 `No tests to run`；前端没有 `test:unit`、`test:e2e` 等脚本 |
+| 期望结果 | 后端至少有 Service 单元测试、Controller 集成测试；前端至少有组件测试和 E2E 冒烟 |
+| 影响 | 构建通过不代表功能可用，无法防止上述契约/安全/数据库缺陷回归 |
+| 建议 | 按测试计划第一阶段补齐 JUnit/Mockito/Testcontainers/Vitest/Playwright，并纳入 CI |
+
+---
+
+## 3. 优先修复建议
+
+1. 先修复 P0：数据库实体映射、JWT 角色映射、安全保护路径、前后端认证/业务 API 路径。
+2. 再修复 P1：HTTP 方法不一致、缺失接口、管理员前端路由、Flyway `USE blog_db`。
+3. 最后补齐 P2：标签结构、限流维度、自动化测试设施。
+4. 修复后第一批自动化测试应优先覆盖：登录/注册、管理员登录和访问后台、创建文章、我的文章列表、发表评论、Flyway 初始化、前端构建。