diff --git a/docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md b/docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md
new file mode 100644
index 0000000..6f8fbed
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md
@@ -0,0 +1,229 @@
+---
+author: Peanut
+created_at: 2026-04-07
+purpose: 定义小程序开发工作流程，解决每次修改代码后需要重新登录的问题
+---
+
+# 小程序开发工作流程设计
+
+## 问题背景
+
+使用 VS Code + 微信开发者工具开发 uni-app 小程序时，每次修改代码后：
+1. uni-app 自动重新编译到 `unpackage/dist/dev/mp-weixin`
+2. 微信开发者工具检测到文件变化后自动重新加载
+3. 小程序重启导致登录态丢失
+4. 需要重新登录，严重影响开发效率
+
+## 设计方案
+
+采用 **H5 开发模式为主 + 微信开发者工具验证为辅** 的双轨工作流。
+
+### 架构概览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      开发工作流程                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────────┐    代码修改    ┌─────────────────────┐     │
+│  │   VS Code   │ ────────────> │   微信开发者工具     │     │
+│  │  (编辑代码)  │               │   (预览/调试小程序)  │     │
+│  └─────────────┘               └─────────────────────┘     │
+│         │                              ▲                     │
+│         │ npm run dev:h5               │                     │
+│         ▼                              │                     │
+│  ┌─────────────┐                      │                     │
+│  │   浏览器     │ <────────────────────┘                     │
+│  │ (H5 开发模式) │    大部分功能在此验证                        │
+│  └─────────────┘                                            │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 方案详情
+
+#### 1. H5 开发模式（承担 90% 开发工作）
+
+**启动命令**：
+```bash
+cd mini-program
+npm run dev:h5
+```
+
+**访问地址**：`http://localhost:5173`（Vite 自动分配，如有占用自动递增）
+
+**技术原理**：
+- uni-app 的 H5 平台与小程序平台共享大部分代码
+- 平台差异通过条件编译处理（`#ifdef H5` / `#ifdef MP-WEIXIN`）
+- 登录态存储于浏览器 localStorage，页面刷新后保留
+
+**适用场景**：
+- UI/样式开发
+- 业务逻辑开发
+- 组件功能调试
+- API 接口联调
+
+**不适用场景**：
+- 微信小程序特有 API（微信登录、分享、支付等）
+- 小程序原生组件测试
+- 真机兼容性验证
+
+#### 2. 微信开发者工具配置优化
+
+**配置步骤**：
+
+1. 打开微信开发者工具
+2. 菜单栏：**设置** → **通用设置**
+3. 找到 **编译设置** 区域
+4. **取消勾选** "文件修改后自动编译" 或 "保存后自动编译"
+
+**效果**：
+- VS Code 修改代码后，微信开发者工具不会自动重新编译
+- 需要手动点击"编译"按钮（或 Ctrl+B）才会重新加载
+- 减少不必要的重启，保持登录态
+
+**替代方案**（如果上述选项不存在）：
+- 在微信开发者工具中，勾选 "关闭真机调试自动刷新"
+- 或使用 "预览" 模式而非 "编辑模式"
+
+#### 3. 推荐工作流
+
+| 开发阶段 | 使用环境 | 操作说明 |
+|----------|----------|----------|
+| UI/样式开发 | H5 | 快速迭代，即时预览 |
+| 业务逻辑开发 | H5 | 大部分逻辑通用，使用浏览器 DevTools 调试 |
+| 小程序 API 测试 | 小程序 | 如微信登录、分享等特有功能 |
+| 最终验证 | 小程序 | 发布前在真机环境测试 |
+
+**日常开发流程**：
+
+```bash
+# 1. 启动 H5 开发服务器（终端 1）
+cd mini-program
+npm run dev:h5
+
+# 2. 打开浏览器访问 http://localhost:5173
+# 3. 登录一次后，后续刷新页面登录态保留
+
+# 4. 需要测试小程序特性时：
+#    - 在另一个终端启动小程序模式
+npm run dev:mp-weixin
+#    - 在微信开发者工具中打开 unpackage/dist/dev/mp-weixin
+#    - 手动触发编译（避免自动刷新）
+```
+
+## 技术细节
+
+### uni-app 平台差异处理
+
+**条件编译语法**：
+
+```javascript
+// #ifdef H5
+// H5 平台特有代码
+// #endif
+
+// #ifdef MP-WEIXIN
+// 微信小程序平台特有代码
+// #endif
+
+// #ifdef H5 || MP-WEIXIN
+// 多平台通用代码
+// #endif
+```
+
+**CSS 条件编译**：
+
+```css
+/* #ifdef H5 */
+.h5-only-style {
+  /* H5 特有样式 */
+}
+/* #endif */
+```
+
+### 登录态持久化
+
+当前项目已正确实现登录态存储：
+
+```javascript
+// 存储 token
+uni.setStorageSync('access_token', token)
+
+// 读取 token
+const token = uni.getStorageSync('access_token')
+
+// 删除 token（登出）
+uni.removeStorageSync('access_token')
+```
+
+**注意**：uni-app 的 storage API 在不同平台使用不同的底层存储：
+- H5：localStorage
+- 微信小程序：wx.setStorageSync
+- 其他小程序：对应平台的 storage API
+
+### 端口管理
+
+H5 开发服务器默认端口为 5173，如被占用会自动递增（5174、5175...）。
+
+**检查端口占用**：
+```bash
+netstat -ano | findstr "5173"
+```
+
+**终止占用进程**：
+```bash
+taskkill /F /PID <进程 ID>
+```
+
+## 注意事项
+
+### 1. H5 与小程序的差异
+
+| 特性 | H5 | 小程序 |
+|------|-----|--------|
+| 路由 | vue-router | 小程序页面栈 |
+| 存储 | localStorage | wx.storage |
+| 网络 | XMLHttpRequest | wx.request |
+| 登录 | 自定义登录 | 微信登录 |
+| 分享 | 浏览器分享 | 微信分享 API |
+
+### 2. 需要小程序环境验证的功能
+
+- 微信小程序登录
+- 微信分享
+- 微信支付
+- 小程序码生成
+- 微信开放标签
+- 真机兼容性
+
+### 3. 开发效率优化建议
+
+1. **使用浏览器 DevTools**：
+   - Chrome DevTools 的 Elements 面板检查样式
+   - Network 面板查看 API 请求
+   - Console 面板调试 JavaScript
+   - Application 面板查看 localStorage
+
+2. **H5 热更新**：
+   - 修改样式后自动刷新
+   - 修改逻辑后热替换（保持应用状态）
+
+3. **小程序模式仅用于验证**：
+   - 不要在小菜模式中进行日常开发
+   - 只在需要测试小程序特有功能时切换
+
+## 验收标准
+
+采用此工作流程后应达到：
+
+- [x] 日常开发无需频繁重新登录
+- [x] H5 模式下可完成 90% 的开发工作
+- [x] 小程序模式仅用于最终验证
+- [x] 开发效率显著提升
+
+## 参考文档
+
+- [uni-app 条件编译](https://uniapp.dcloud.net.cn/tutorial/platform.html)
+- [uni-app H5 开发模式](https://uniapp.dcloud.net.cn/quickstart-h5.html)
+- [微信开发者工具设置](https://developers.weixin.qq.com/miniprogram/dev/devtools/projectconfig.html)