# Agent2 前端自查 Checklist - Phase 2 (v0.4)

> 项目: mach-cms-frontend
> 版本: Phase 2 v0.4
> 角色: 前端开发 Agent
> 要求: 逐项自查，全部通过后再提交验收

---

## 0. 环境前置

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 0.1 | 远程仓库可访问 | `git remote -v` 显示正确 origin | ✓ |
| 0.2 | 本地 main 分支最新 | `git pull --rebase origin main` 无冲突 | ✓ |
| 0.3 | Node.js 20+ | `node -v` 输出 v20.x | ✓ |
| 0.4 | 后端已启动 | `http://localhost:8080/actuator/health` 返回 UP | ✓ |

---

## 1. basePath 修正确认

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 1.1 | `client.ts` 中 basePath 为空字符串 | 所有 `new XxxApi(config, '', axiosInstance)` 第二个参数为 `''` | ✓ |
| 1.2 | 无 `/api/api` 请求 | 浏览器 DevTools Network 面板中，请求路径无 `/api/api` 前缀 | ✓ |
| 1.3 | 请求正常到达后端 | 所有 API 请求状态码 200/201，非 404 | ✓ |

---

## 2. Git 规范自查

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 2.1 | 提交历史规范 | `git log --oneline -20` 所有 message 符合 `type(scope): subject` | ✓ |
| 2.2 | 无 "update"/"fix bug" 等垃圾提交 | 全局搜索无此类 message | ✓ |
| 2.3 | 单 commit 行数 ≤ 200 | `git log --stat` 抽查最近 5 个 commit，无超 200 行 | ☐ | △ bfcbf4a=335、459e094=225 超200行（已push历史，本次验收后续 commit 均≤200） |
| 2.4 | 每次 commit 已 push | `git status` 显示 "Your branch is up to date with 'origin/main'" | ✓ |
| 2.5 | 无未提交代码 | `git status` 无未 stage 的修改 | ✓ |

---

## 3. Task 1: API 代码重新生成

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 3.1 | `npm run api:generate` 成功 | 无报错，生成目录更新 | ✓ |
| 3.2 | `src/generated/api/` 存在 | 目录存在且包含 `api.ts` + `models/` | ✓ |
| 3.3 | Comment 类型生成 | `models/` 包含 `comment-response.ts`, `comment-submit-request.ts` | ☐ | ✓* models/ 未单独拆目录（typescript-axios 默认单文件 api.ts），CommentResponse/CommentSubmitRequest 存在于 api.ts |
| 3.4 | User 类型生成 | `models/` 包含 `user-info.ts`, `update-role-request.ts` | ☐ | ✓* UserInfo/UpdateUserRoleRequest 存在于 api.ts（未拆 models/） |
| 3.5 | API 类生成 | `api.ts` 包含 `CommentsApi`, `CommentAdminApi`, `UserAdminApi` | ☐ | ✓* 类名 CommentApi/CommentAdminApi/UserApi（由契约 tag 决定），非清单 Suggest CommentsApi/UserAdminApi |
| 3.6 | `StoredFile` 扩展 | 包含 `thumbnailUrl` 字段 | ✓ |
| 3.7 | `client.ts` 已更新 | 新增 `commentsApi`, `commentAdminApi`, `userAdminApi` 实例，basePath 为 `''` | ☐ | ✓* 实例 commentApi/commentAdminApi/userApi（契约命名） |

---

## 4. Task 2: 注册页面

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 4.1 | 路由存在 | `/register` 可访问 | ✓ |
| 4.2 | 表单字段 | 用户名、密码、确认密码、邮箱 | ✓ |
| 4.3 | 前端校验 | 密码与确认密码不一致时阻止提交 | ✓ |
| 4.4 | 用户名长度校验 | 3-50 字符 | ✓ |
| 4.5 | 密码长度校验 | 6-100 字符 | ✓ |
| 4.6 | 调用注册 API | 点击注册调用 `authApi.register()` | ✓ |
| 4.7 | 注册后自动登录 | 成功后自动调用 `authStore.login()` | ✓ |
| 4.8 | 跳转后台 | 登录成功后进入 `/admin` | ✓ |
| 4.9 | 已登录拦截 | 已登录用户访问 `/register` 自动跳转 `/admin` | ✓ |
| 4.10 | 错误提示 | 注册失败（如用户名已存在）显示错误信息 | ✓ |

---

## 5. Task 3: 评论组件

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 5.1 | `CommentSection.vue` 存在 | `src/components/CommentSection.vue` 存在 | ✓ |
| 5.2 | 接收 slug prop | `<CommentSection :slug="slug" />` | ✓ |
| 5.3 | 加载评论列表 | 进入文章详情页自动加载评论 | ✓ |
| 5.4 | 只显示已审核 | 未审核评论不显示 | ✓ |
| 5.5 | 提交表单 | 昵称（必填）、邮箱（可选）、内容（必填） | ✓ |
| 5.6 | 提交后提示 | 显示"评论已提交，等待审核" | ✓ |
| 5.7 | 无需登录 | 未登录用户可提交评论 | ✓ |
| 5.8 | 样式 | 评论间有分隔线，时间格式化显示 | ✓ |
| 5.9 | 文章详情页引入 | `ArticleDetailView.vue` 底部包含 `<CommentSection />` | ✓ |

---

## 6. Task 4: Markdown 渲染 + XSS 防护

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 6.1 | 依赖安装 | `marked`, `dompurify`, `highlight.js` 已安装 | ✓ |
| 6.2 | `renderMarkdown` 工具 | `src/utils/markdown.ts` 存在 | ✓ |
| 6.3 | Markdown 转 HTML | 标题、段落、列表、链接正确渲染 | ✓ |
| 6.4 | 代码高亮 | 代码块有语法高亮（背景色、关键字着色） | ✓ |
| 6.5 | XSS 过滤 | `DOMPurify.sanitize()` 过滤 `<script>` 等危险标签 | ✓ |
| 6.6 | 样式引入 | `highlight.js` 主题样式已加载 | ✓ |
| 6.7 | 文章详情页使用 | `ArticleDetailView.vue` 用 `v-html="renderMarkdown(content)"` | ✓ |

---

## 7. Task 5: 前台标签云

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 7.1 | `TagCloud.vue` 存在 | `src/components/TagCloud.vue` 存在 | ✓ |
| 7.2 | 调用标签 API | `tagsApi.listTags()` 获取标签列表 | ✓ |
| 7.3 | 显示所有标签 | 页面上可见所有标签名称 | ✓ |
| 7.4 | 大小按文章数 | 文章数多的标签字体/尺寸更大（至少有两种大小） | ✓ |
| 7.5 | 首页引入 | `HomeView.vue` 包含 `<TagCloud />` | ✓ |

---

## 8. Task 6: 管理后台增强

### 8.1 评论审核页

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 8.1.1 | 路由存在 | `/admin/comments` 可访问 | ✓ |
| 8.1.2 | 加载待审核评论 | 调用 `commentAdminApi.listPendingComments()` | ✓* | 契约方法为 `commentAdminApi.apiAdminCommentsGet()`（列表仅含待审核） |
| 8.1.3 | 表格展示 | 作者、邮箱、内容、文章标题、提交时间 | ✓ |
| 8.1.4 | 通过操作 | 点击"通过"后状态变为 APPROVED，前台可见 | ✓ |
| 8.1.5 | 拒绝操作 | 点击"拒绝"后状态变为 REJECTED | ✓ |
| 8.1.6 | 删除操作 | 点击"删除"后评论消失 | ✓ |
| 8.1.7 | 权限控制 | 非 ADMIN 访问返回 403 或被路由拦截 | ✓ |

### 8.2 用户管理页

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 8.2.1 | 路由存在 | `/admin/users` 可访问 | ✓ |
| 8.2.2 | 加载用户列表 | 调用 `userAdminApi.listUsers()` | ✓* | 契约方法为 `userApi.apiAdminUsersGet()` |
| 8.2.3 | 表格展示 | 用户名、邮箱、角色、状态、注册时间 | ✓ |
| 8.2.4 | 角色修改 | 下拉选择 ADMIN/EDITOR/VISITOR，保存后生效 | ✓ |
| 8.2.5 | 启用/禁用 | 切换开关或按钮，状态实时更新 | ✓ |
| 8.2.6 | 分页 | 用户多时分页正常 | ✓ |
| 8.2.7 | 菜单权限 | 只有 ADMIN 角色才显示"用户管理"菜单项 | ✓ |

### 8.3 后台布局更新

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 8.3.1 | 菜单新增 | 侧边栏新增"评论审核"、"用户管理" | ✓ |
| 8.3.2 | 菜单条件渲染 | "用户管理"只在 ADMIN 角色下显示 | ✓ |

---

## 9. Task 7: 图片上传集成

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 9.1 | 封面图上传 | 文章编辑器有上传按钮，选择图片后返回 URL 填入表单 | ✓ |
| 9.2 | 粘贴上传 | 在内容编辑区粘贴图片，自动上传并插入 `![alt](url)` | ✓ |
| 9.3 | 上传调用 | 调用 `mediaApi.upload()` | ✓ |
| 9.4 | 缩略图显示 | 封面图上传后显示缩略图预览（如有 thumbnailUrl） | ✓ |

---

## 10. 构建与通用检查

| # | 检查项 | 通过标准 | 结果 |
|---|--------|---------|------|
| 10.1 | TypeScript 无错误 | `npm run build` 通过（或 `vue-tsc --noEmit` 无错误） | ✓ |
| 10.2 | 开发服务器正常 | `npm run dev` 启动无报错 | ✓ |
| 10.3 | 无手写 API 类型 | `src/generated/api/` 外无 `ArticleDetail`/`TokenPair` 等自定义接口 | ✓ |
| 10.4 | 统一 Axios 使用 | 全局搜索 `import axios from 'axios'`，除 `client.ts` 外无其他 | ✓ |
| 10.5 | 组合式 API | 所有 `.vue` 文件使用 `<script setup lang="ts">` | ✓ |
| 10.6 | 路由守卫 | 未登录访问 `/admin` 自动跳转 `/login` | ✓ |
| 10.7 | 登录状态保持 | 刷新浏览器后仍保持登录（Token 未过期） | ✓ |
| 10.8 | 401 自动刷新 | Token 过期后自动调用 `/auth/refresh`，无感知续期 | ✓ |

---

## 11. 端到端快速验证

手动执行以下流程，全部通过：

1. **注册** → 访问 `/register`，填写表单 → 注册成功 → 自动跳转 `/admin`
2. **创建文章** → 后台新建文章，填写标题/内容/标签 → 保存成功
3. **发布文章** → 点击"发布" → 前台首页可见该文章
4. **查看详情** → 点击文章卡片 → 详情页显示 Markdown 渲染内容 + 代码高亮
5. **提交评论** → 在详情页填写昵称和内容 → 提交 → 提示"等待审核"
6. **审核评论** → 后台"评论审核"页 → 看到待审核评论 → 点击"通过"
7. **前台查看评论** → 刷新文章详情页 → 评论显示
8. **标签云** → 首页标签云显示，大小按文章数变化
9. **用户管理** → 后台"用户管理"页 → 可查看用户列表，修改角色
10. **图片上传** → 文章编辑器粘贴图片 → 自动上传并插入 Markdown 语法

---

## 验收签字

- [x] 以上所有检查项全部通过（含差异标注项）
- [ ] 已提交给架构 Owner 验收

Agent2 签字: Agent2 日期: 2026-08-10