diff --git a/docs/superpowers/plans/2026-06-08-s1-comprehensive-scan.md b/docs/superpowers/plans/2026-06-08-s1-comprehensive-scan.md new file mode 100644 index 0000000..bb6900f --- /dev/null +++ b/docs/superpowers/plans/2026-06-08-s1-comprehensive-scan.md @@ -0,0 +1,320 @@ +# S1 全面扫描 — 实施计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 对「小菜记账」全项目进行三维度（缺陷/UI/功能）全面扫描，产出结构化问题清单 + +**Architecture:** 5 个并行扫描组 + 1 个汇总任务。每组用 Explore agent 深度检查文件，从缺陷/UI/功能三个维度输出 P0-P3 优先级发现。 + +**Tech Stack:** TypeScript, Vue 3, Uni-app, Express, MySQL + +--- + +## 文件结构 + +``` +client/src/ server/src/ +├── pages/ ├── index.ts +│ ├── index/index.vue ├── middleware/ +│ ├── add/index.vue │ ├── auth.ts +│ ├── bills/ │ ├── logger.ts +│ │ ├── index.vue │ └── requireAdmin.ts +│ │ └── filter-panel.vue ├── routes/ +│ ├── stats/index.vue │ ├── auth.ts +│ ├── profile/index.vue │ ├── transaction.ts +│ ├── profile-edit/index.vue │ ├── category.ts +│ ├── budget/index.vue │ ├── budget.ts +│ ├── category-manage/index.vue │ ├── stats.ts +│ ├── group-manage/index.vue │ ├── user.ts +│ ├── notifications/index.vue │ ├── group.ts +│ ├── feedback/index.vue │ ├── notification.ts +│ ├── privacy/index.vue │ ├── filter.ts +│ └── admin/ │ ├── feedback.ts +│ ├── index.vue │ ├── config.ts +│ ├── users.vue │ ├── admin.ts +│ ├── notifications.vue │ ├── track.ts +│ ├── feedback.vue │ ├── logs.ts +│ ├── config.vue │ └── backup.ts +│ ├── logs.vue ├── utils/ +│ └── track.vue │ ├── backup.ts +├── components/ │ └── date.ts +│ ├── Icon/Icon.vue └── db/ +│ ├── Numpad/Numpad.vue ├── connection.ts +│ ├── TransactionItem/...vue └── init.ts +│ ├── Skeleton/Skeleton.vue +│ ├── SaveSuccess/...vue +│ ├── BudgetBar/BudgetBar.vue +│ ├── CategoryIcon/...vue +│ └── ChartWrapper/...vue +├── stores/ +│ ├── transaction.ts +│ ├── category.ts +│ ├── budget.ts +│ ├── stats.ts +│ ├── user.ts +│ ├── group.ts +│ ├── filter.ts +│ ├── notification.ts +│ └── config.ts +├── api/ +│ ├── auth.ts, transaction.ts, category.ts +│ ├── budget.ts, stats.ts, user.ts +│ ├── group.ts, notification.ts, filter.ts +│ ├── feedback.ts, config.ts, admin.ts, logs.ts +│ └── index.ts +├── utils/ +│ ├── request.ts, format.ts, system.ts +│ ├── app-ready.ts, tracker.ts +└── config.ts +``` + +--- + +## 扫描检查清单（每个文件按此标准检查） + +每个文件从以下三个维度检查： + +### 🔧 缺陷维度 +- [ ] API 参数类型：`request()` 调用是否使用 `{ url, method?, data? }` 格式 +- [ ] null/undefined 处理：是否可能传递 undefined 到查询参数 +- [ ] 边界条件：空数组、空字符串、0 值的处理 +- [ ] 竞态条件：快速切换页面时请求是否可能覆盖 +- [ ] 小程序适配：胶囊按钮避让 (capsuleRight)、scroll-view 高度 +- [ ] 数据加载：onMounted 是否先 await waitForReady() +- [ ] catch 块：是否有用户提示而非静默失败 +- [ ] 后端响应格式：是否返回 `{ code: 0, data }` 或 `{ code: xxx, message }` + +### 🎨 UI 维度 +- [ ] 加载态：是否有 loading/skeleton，避免白屏 +- [ ] 空状态：无数据时是否有友好的空状态提示 +- [ ] 错误态：是否有错误提示机制 +- [ ] 触摸反馈：可点击元素是否有 `:active` 样式 +- [ ] 设计一致性：颜色/圆角/阴影使用 SCSS 变量，不硬编码 +- [ ] 触摸目标：交互元素 ≥ 44×44px +- [ ] emoji：禁止使用 emoji，必须用 Icon 组件 +- [ ] 动画：是否尊重 prefers-reduced-motion +- [ ] 文字对比度：≥ 4.5:1 (WCAG AA) + +### 🚀 功能维度 +- [ ] 分页：是否正确分页，是否有「没有更多了」 +- [ ] 筛选：筛选条件变更时是否重置页码 +- [ ] 输入校验：前端是否有校验，后端是否有校验 +- [ ] 错误码规范：0/40001/40300/40400/50000 +- [ ] 数据流：API → store → 组件是否清晰 + +### 优先级定义 +| 级别 | 含义 | 示例 | +|------|------|------| +| P0 | 数据/安全/崩溃 | 金额错误、SQL 注入、白屏 | +| P1 | 功能不可用 | 按钮无响应、数据不刷新、接口报错 | +| P2 | 体验不佳 | 空状态缺失、加载闪烁 | +| P3 | 建议改进 | 代码整洁、命名、注释 | + +--- + +### Task 1: 扫描组 1 — 核心页面 + +**Files (13):** +- `client/src/pages/index/index.vue` +- `client/src/pages/add/index.vue` +- `client/src/pages/bills/index.vue` +- `client/src/pages/bills/filter-panel.vue` +- `client/src/pages/stats/index.vue` +- `client/src/stores/transaction.ts` +- `client/src/stores/category.ts` +- `client/src/stores/budget.ts` +- `client/src/stores/stats.ts` +- `client/src/api/transaction.ts` +- `client/src/api/category.ts` +- `client/src/api/budget.ts` +- `client/src/api/stats.ts` + +- [ ] **Step 1: 并行读取所有文件** + +使用 Explore agent，读取上述全部 13 个文件，对每个文件按「扫描检查清单」逐项检查。 + +- [ ] **Step 2: 输出结构化发现清单** + +输出格式： + +```markdown +## 组 1: 核心页面 — 扫描结果 + +### 🔧 缺陷 + +| 优先级 | 文件:行号 | 问题 | 影响 | +|--------|----------|------|------| +| P1 | pages/bills/index.vue:42 | onMounted 缺少 waitForReady | 登录未完成就发请求，可能 401 | + +### 🎨 UI 问题 + +| 优先级 | 文件:行号 | 问题 | 影响 | +|--------|----------|------|------| +| P2 | pages/index/index.vue:xxx | 无空状态提示 | 新用户看到空白页 | + +### 🚀 功能缺口 + +| 优先级 | 文件:行号 | 问题 | 建议 | +|--------|----------|------|------| +| P2 | stores/transaction.ts | 无请求去重 | 快速点击可能重复提交 | +``` + +--- + +### Task 2: 扫描组 2 — 用户 & 设置 + +**Files (18):** +- `client/src/pages/profile/index.vue` +- `client/src/pages/profile-edit/index.vue` +- `client/src/pages/budget/index.vue` +- `client/src/pages/category-manage/index.vue` +- `client/src/pages/group-manage/index.vue` +- `client/src/pages/notifications/index.vue` +- `client/src/pages/feedback/index.vue` +- `client/src/pages/privacy/index.vue` +- `client/src/stores/user.ts` +- `client/src/stores/group.ts` +- `client/src/stores/filter.ts` +- `client/src/stores/notification.ts` +- `client/src/stores/config.ts` +- `client/src/api/user.ts` +- `client/src/api/group.ts` +- `client/src/api/notification.ts` +- `client/src/api/feedback.ts` +- `client/src/api/filter.ts` + +- [ ] **Step 1: 并行读取所有文件** + +使用 Explore agent，读取上述全部 18 个文件，对每个文件按「扫描检查清单」逐项检查。 + +- [ ] **Step 2: 输出结构化发现清单** + +格式同 Task 1。 + +--- + +### Task 3: 扫描组 3 — 管理后台 + +**Files (10):** +- `client/src/pages/admin/index.vue` +- `client/src/pages/admin/users.vue` +- `client/src/pages/admin/notifications.vue` +- `client/src/pages/admin/feedback.vue` +- `client/src/pages/admin/config.vue` +- `client/src/pages/admin/logs.vue` +- `client/src/pages/admin/track.vue` +- `client/src/api/admin.ts` +- `client/src/api/config.ts` +- `client/src/api/logs.ts` + +- [ ] **Step 1: 并行读取所有文件** + +使用 Explore agent，读取上述全部 10 个文件，对每个文件按「扫描检查清单」逐项检查。 + +- [ ] **Step 2: 输出结构化发现清单** + +格式同 Task 1。 + +--- + +### Task 4: 扫描组 4 — 后端路由 & 基础设施 + +**Files (23):** +- `server/src/index.ts` +- `server/src/middleware/auth.ts` +- `server/src/middleware/logger.ts` +- `server/src/middleware/requireAdmin.ts` +- `server/src/routes/auth.ts` +- `server/src/routes/transaction.ts` +- `server/src/routes/category.ts` +- `server/src/routes/budget.ts` +- `server/src/routes/stats.ts` +- `server/src/routes/user.ts` +- `server/src/routes/group.ts` +- `server/src/routes/notification.ts` +- `server/src/routes/filter.ts` +- `server/src/routes/feedback.ts` +- `server/src/routes/config.ts` +- `server/src/routes/admin.ts` +- `server/src/routes/track.ts` +- `server/src/routes/logs.ts` +- `server/src/routes/backup.ts` +- `server/src/utils/backup.ts` +- `server/src/utils/date.ts` +- `server/src/db/connection.ts` +- `server/src/db/init.ts` + +- [ ] **Step 1: 并行读取所有文件** + +使用 Explore agent，读取上述全部 23 个文件，对每个文件按以下关注点检查： + +**后端专项检查：** +- SQL 注入风险（参数化查询） +- 输入校验（类型、范围） +- 响应格式统一（`{ code, data/message }`） +- 错误码规范 +- LIMIT/OFFSET 参数类型（整数） +- 认证/授权逻辑完整性 +- 日志记录完整性 + +- [ ] **Step 2: 输出结构化发现清单** + +格式同 Task 1。 + +--- + +### Task 5: 扫描组 5 — 公共组件 & 基础设施 + +**Files (12):** +- `client/src/components/Icon/Icon.vue` +- `client/src/components/Numpad/Numpad.vue` +- `client/src/components/TransactionItem/TransactionItem.vue` +- `client/src/components/Skeleton/Skeleton.vue` +- `client/src/components/SaveSuccess/SaveSuccess.vue` +- `client/src/components/BudgetBar/BudgetBar.vue` +- `client/src/components/CategoryIcon/CategoryIcon.vue` +- `client/src/components/ChartWrapper/ChartWrapper.vue` +- `client/src/utils/request.ts` +- `client/src/utils/format.ts` +- `client/src/utils/tracker.ts` +- `client/src/config.ts` + +- [ ] **Step 1: 并行读取所有文件** + +使用 Explore agent，读取上述全部 12 个文件，对每个文件按「扫描检查清单」逐项检查。 + +- [ ] **Step 2: 输出结构化发现清单** + +格式同 Task 1。 + +--- + +### Task 6: 汇总 & 排期 + +- [ ] **Step 1: 合并 5 组发现清单** + +将所有扫描结果合并为一文档，按优先级分组： + +```markdown +# S1 全面扫描 — 汇总报告 + +## P0 — 立即修复（N 项） +| 组 | 文件 | 问题 | +|----|------|------| + +## P1 — 高优先级（N 项） +... + +## P2 — 中优先级（N 项） +... + +## P3 — 建议改进（N 项） +... +``` + +- [ ] **Step 2: 提交汇总报告** + +```bash +git add docs/superpowers/ +git commit -m "docs: S1 全面扫描汇总报告" +```