docs: S1 全面扫描实施计划

2026-06-08 16:40:43 +08:00
parent 2b04f057a9
commit 3279440ce6
1 changed files with 320 additions and 0 deletions
--- a/docs/superpowers/plans/2026-06-08-s1-comprehensive-scan.md
+++ 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 全面扫描汇总报告"
+```