docs: 添加订阅与每日运势推送功能的设计文档

- ADR-002: 订阅与每日运势推送功能设计决策 - PRD: 订阅与每日推送功能需求规格说明 - 实现计划文档
2026-08-13 08:06:01 +08:00
parent 7f0ef622e7
commit e6488cdab9
3 changed files with 773 additions and 0 deletions
@@ -0,0 +1,398 @@
+# 订阅与每日运势推送 — 实现计划
+
+> **面向 AI 代理的工作者：** 必需子技能：使用 subagent-driven-development（推荐）或 executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
+
+**目标：** 为微信小程序添加每日运势订阅与推送功能，用户可在每日固定时间自动收到个性化运势推送。
+
+**架构：** 微信云开发（CloudBase）作为轻量后端，云函数 + 云数据库 + 定时触发器。运势算法抽取为共享 npm 包，小程序和云函数共用。
+
+**设计规格：** `docs/superpowers/specs/2026-08-13-daily-fortune-push-PRD.md`
+
+**ADR：** `docs/adr/2026-08-13-daily-fortune-push.md`
+
+---
+
+## 整体架构流程
+
+```mermaid
+graph TD
+    subgraph 小程序端
+        A[运势页面] -->|"点击订阅"| B[wx.requestSubscribeMessage]
+        B -->|"用户授权"| C[调用云函数 subscribe]
+        C -->|"返回成功"| D[UI 更新为"已订阅"]
+        D --> E[订阅管理页面]
+        E -->|"修改时间"| F[调用云函数 updatePushTime]
+        E -->|"取消订阅"| G[调用云函数 unsubscribe]
+    end
+    subgraph 云开发
+        C --> H[(云数据库 subscriptions)]
+        F --> H
+        G --> H
+        I[定时触发器 07:00] --> J[云函数 dailyPush]
+        J -->|"查询当日订阅"| H
+        J -->|"调用共享算法"| K[生成运势内容]
+        K --> L[wx.subscribeMessage.send]
+        L --> M[用户收到服务通知]
+    end
+    subgraph 共享算法包
+        N[packages/algorithm] -->|"fortuneStrategy"| K
+        N -->|"ziweiAlgorithm"| K
+        N -->|"types/enums"| K
+    end
+```
+
+## 依赖关系
+
+```mermaid
+graph TD
+    I1["Issue 1: 共享算法包抽取<br/>P0 ⭐ 2d"] --> I2["Issue 2: 云开发环境搭建<br/>P0 ⭐ 1d"]
+    I1 --> I3["Issue 3: 订阅功能实现<br/>P0 ⭐ 2d"]
+    I2 --> I3
+    I2 --> I4["Issue 4: 每日推送云函数<br/>P0 ⭐ 1.5d"]
+    I3 --> I4
+    I4 --> I5["Issue 5: 订阅管理功能<br/>P1 ⭐ 1d"]
+    I4 --> I6["Issue 6: 集成测试与验收<br/>P0 ⭐ 1.5d"]
+    I5 --> I6
+```
+
+---
+
+## Issue 1: 共享算法包抽取
+
+**优先级：** P0
+**预估工时：** 2d
+**依赖：** 无
+
+**描述：** 将现有运势算法中的纯函数层抽取为独立 npm 包 `packages/algorithm/`，使其可在 UniApp 和 Node.js 云函数中复用。
+
+### 文件结构
+
+| 操作 | 文件路径 | 说明 |
+|------|---------|------|
+| 创建 | `packages/algorithm/package.json` | 包配置，声明类型和入口 |
+| 创建 | `packages/algorithm/tsconfig.json` | TypeScript 配置 |
+| 创建 | `packages/algorithm/src/index.ts` | 导出入口 |
+| 复制 | `packages/algorithm/src/types.ts` | 类型定义（从 `src/algorithms/types.ts` 抽取） |
+| 复制 | `packages/algorithm/src/enums.ts` | 枚举定义（从 `src/algorithms/enums.ts` 抽取） |
+| 复制 | `packages/algorithm/src/fortuneStrategy.ts` | 运势生成策略 |
+| 复制 | `packages/algorithm/src/fortune.ts` | 综合运势生成 |
+| 复制 | `packages/algorithm/src/ziweiAlgorithm.ts` | 紫微算法基础 |
+| 复制 | `packages/algorithm/src/__tests__/fortuneStrategy.test.ts` | 算法测试 |
+| 修改 | `everything-is-suitable-uniapp/package.json` | 添加本地依赖引用 |
+| 修改 | `everything-is-suitable-uniapp/tsconfig.json` | 添加 paths 别名 |
+
+### 验收标准
+
+- [ ] 算法包在 Node.js 环境下可独立运行（`node -e "require('./packages/algorithm')"` 无报错）
+- [ ] 算法包所有测试通过（`cd packages/algorithm && npx vitest run`）
+- [ ] 小程序端引用算法包后，原有运势功能正常运行
+- [ ] 算法包导出接口与 PRD 定义的接口一致
+- [ ] 原有测试不受影响（`cd everything-is-suitable-uniapp && npx vitest run` 全部通过）
+
+---
+
+## Issue 2: 微信云开发环境搭建
+
+**优先级：** P0
+**预估工时：** 1d
+**依赖：** 无
+
+**描述：** 开通微信云开发环境，创建云数据库集合、云函数脚手架、定时触发器配置。
+
+### 任务清单
+
+- [ ] **步骤 1：开通微信云开发**
+  - 在微信小程序管理后台开通云开发
+  - 创建环境（如 `prod`），记下环境 ID
+  - 创建 `cloudfunctions/` 目录并初始化
+
+- [ ] **步骤 2：创建云数据库集合**
+  - 集合名：`subscriptions`
+  - 索引：`openid`（唯一索引）、`pushEnabled`、`lastPushDate`
+  - 权限：仅云函数可读写（不开放客户端直接访问）
+
+- [ ] **步骤 3：创建云函数骨架**
+  ```bash
+  cloudfunctions/
+  ├── subscribe/          # 订阅处理
+  ├── unsubscribe/        # 取消订阅
+  ├── updatePushTime/     # 更新推送时间
+  ├── dailyPush/          # 每日推送（含定时触发器）
+  └── package.json
+  ```
+  - 每个云函数创建 `index.js` 骨架，导出 `main` 函数
+  - 公共依赖：`@everything-suitable/algorithm`（通过本地路径引用）
+
+- [ ] **步骤 4：配置 dailyPush 定时触发器**
+  - 在 `cloudfunctions/dailyPush/` 下创建 `config.json`
+  - cron 表达式：`0 0 7 * * * *`（每日 07:00）
+  - 后续支持用户自定义时间时，调整为每分钟扫描（`0 * * * * * *`）并过滤用户配置时间
+
+### 验收标准
+
+- [ ] 云开发环境开通成功，可正常访问
+- [ ] 云数据库 `subscriptions` 集合可正常读写
+- [ ] 云函数 `subscribe` 可正常部署和调用
+- [ ] 定时触发器配置已上传，云函数可被定时触发
+
+---
+
+## Issue 3: 订阅功能实现
+
+**优先级：** P0
+**预估工时：** 2d
+**依赖：** Issue 1, Issue 2
+
+**描述：** 实现小程序端订阅入口 + 订阅管理页面 + 云函数 subscribe/unsubscribe。
+
+### 3.1 小程序端
+
+#### 订阅入口（运势页面）
+- 在 `src/pages/fortune/index.vue` 中添加订阅入口区域
+- 未订阅时显示"订阅每日推送"按钮
+- 已订阅时显示"已订阅"状态 + 推送时间 + "管理"入口
+- 未输入生辰信息时提示用户先设置生辰信息
+
+#### 订阅管理页面
+- 新建页面：`src/pages/push-subscription/index.vue`
+- 功能：
+  - 显示当前推送时间
+  - 修改推送时间（步长 30 分钟，07:00-22:00）
+  - 取消订阅按钮
+  - 订阅状态说明
+
+### 3.2 云函数：subscribe
+
+```typescript
+// cloudfunctions/subscribe/index.js
+exports.main = async (event, context) => {
+  const { birthInfo, templateId, pushTime } = event
+  const { OPENID } = cloud.getWXContext()
+
+  // 校验参数
+  // 检查是否已存在订阅
+  // 写入 subscriptions 集合
+  // 返回 { success: true }
+}
+```
+
+### 3.3 云函数：unsubscribe
+
+```typescript
+// cloudfunctions/unsubscribe/index.js
+exports.main = async (event, context) => {
+  const { OPENID } = cloud.getWXContext()
+
+  // 删除 subscriptions 中对应记录
+  // 返回 { success: true }
+}
+```
+
+### 验收标准
+
+- [ ] 未订阅时，运势页面显示"订阅每日推送"入口
+- [ ] 点击订阅 → 弹出微信订阅消息授权弹窗
+- [ ] 授权成功 → 云函数存储订阅记录 → UI 更新为"已订阅"
+- [ ] 未输入生辰信息时，点击订阅提示先设置生辰信息
+- [ ] 订阅管理页面可正常打开，显示当前推送时间
+- [ ] 取消订阅 → 云端记录删除 → 运势页面恢复显示订阅入口
+
+---
+
+## Issue 4: 每日推送云函数实现
+
+**优先级：** P0
+**预估工时：** 1.5d
+**依赖：** Issue 2, Issue 3
+
+**描述：** 实现 dailyPush 云函数，在每日定时触发时生成运势内容并推送。
+
+### 云函数逻辑
+
+```mermaid
+graph TD
+    A[定时触发 dailyPush] --> B[查询 subscriptions]
+    B --> C{pushEnabled=true<br/>&& lastPushDate != today?}
+    C -->|"否"| D[跳过]
+    C -->|"是"| E[读取 birthInfo]
+    E --> F[生成 ZiweiChart]
+    F --> G[计算今日运势]
+    G --> H[格式化推送内容]
+    H --> I[wx.subscribeMessage.send]
+    I --> J{发送成功?}
+    J -->|"是"| K[更新 lastPushDate = today]
+    J -->|"否"| L[记录错误日志]
+```
+
+### 关键实现细节
+
+```typescript
+// cloudfunctions/dailyPush/index.js
+const cloud = require('wx-server-sdk')
+const { generateDailyFortune } = require('@everything-suitable/algorithm')
+const { calculateLuckyColor, calculateLuckyNumber } = require('@everything-suitable/algorithm')
+
+cloud.init()
+const db = cloud.database()
+
+exports.main = async (event, context) => {
+  const today = new Date()
+  const todayStr = today.toISOString().slice(0, 10)
+
+  // 查询今日需要推送的订阅
+  const { data: subscriptions } = await db.collection('subscriptions')
+    .where({
+      pushEnabled: true,
+      lastPushDate: db.command.neq(todayStr).or(db.command.not exists),
+    })
+    .get()
+
+  for (const sub of subscriptions) {
+    try {
+      // 检查是否到推送时间
+      const [hour, minute] = sub.pushTime.split(':')
+      if (today.getHours() !== parseInt(hour) || today.getMinutes() !== parseInt(minute)) {
+        continue
+      }
+
+      // 生成 ZiweiChart（基于生辰信息）
+      const chart = generateZiweiChart(sub.birthInfo)
+
+      // 生成今日运势
+      const fortune = generateDailyFortune(chart, today)
+      fortune.luckyColor = calculateLuckyColor(chart, today)
+      fortune.luckyNumber = calculateLuckyNumber(chart, today)
+
+      // 发送订阅消息
+      await cloud.openapi.subscribeMessage.send({
+        touser: sub.openid,
+        templateId: sub.templateId,
+        data: {
+          date1: { value: formatDate(today) },
+          thing2: { value: `综合运势评分${fortune.overallScore}分，等级：${fortune.overallLuck}` },
+          thing3: { value: formatFortuneSummary(fortune) },
+          thing4: { value: `幸运色：${fortune.luckyColor}  幸运数字：${fortune.luckyNumber}` },
+        },
+      })
+
+      // 更新最后推送日期
+      await db.collection('subscriptions').doc(sub._id).update({
+        data: { lastPushDate: todayStr },
+      })
+    } catch (err) {
+      console.error(`Push failed for ${sub.openid}:`, err)
+    }
+  }
+}
+```
+
+### 验收标准
+
+- [ ] 定时触发器在每日 07:00 正确触发云函数
+- [ ] 云函数正确过滤已订阅且未推送的用户
+- [ ] 推送内容包含：日期、综合运势、各维度运势、幸运信息
+- [ ] 推送内容与小程序内当日运势计算一致
+- [ ] 同一用户每日不会收到重复推送
+- [ ] 推送失败时记录错误日志，不影响其他用户推送
+- [ ] 用户自定义推送时间在 minutely 扫描模式下正常工作
+
+---
+
+## Issue 5: 订阅管理功能
+
+**优先级：** P1
+**预估工时：** 1d
+**依赖：** Issue 4
+
+**描述：** 完善订阅管理页面的推送时间配置功能，以及相关的云函数 updatePushTime。
+
+### 5.1 小程序端
+
+- 推送时间选择器（Picker 组件，步长 30 分钟）
+- "保存"按钮，调用云函数更新推送时间
+- 保存成功提示
+
+### 5.2 云函数：updatePushTime
+
+```typescript
+// cloudfunctions/updatePushTime/index.js
+exports.main = async (event, context) => {
+  const { pushTime } = event  // "HH:mm" 格式
+  const { OPENID } = cloud.getWXContext()
+
+  // 校验 pushTime 格式
+  // 更新 subscriptions 集合中对应记录的 pushTime
+  // 返回 { success: true }
+}
+```
+
+### 验收标准
+
+- [ ] 推送时间选择器按 30 分钟步长显示可选时间
+- [ ] 保存后云端记录更新
+- [ ] 修改后下一次推送按新时间执行
+- [ ] 保存成功/失败均有明确提示
+
+---
+
+## Issue 6: 集成测试与验收
+
+**优先级：** P0
+**预估工时：** 1.5d
+**依赖：** Issue 4, Issue 5
+
+**描述：** 对订阅和每日推送功能进行完整的集成测试、异常场景验证和最终验收。
+
+### 测试场景
+
+#### 6.1 功能测试
+- [ ] **TC-01：完整订阅流程** — 输入生辰信息 → 订阅 → 授权 → 订阅成功
+- [ ] **TC-02：未输入生辰信息时订阅** — 提示用户先设置生辰信息
+- [ ] **TC-03：取消订阅** — 取消订阅 → 云端记录删除 → 订阅入口恢复
+- [ ] **TC-04：修改推送时间** — 修改时间 → 保存 → 云端更新
+- [ ] **TC-05：每日推送触发** — 定时触发 → 运势生成 → 推送成功
+- [ ] **TC-06：重复推送防护** — 同一用户同一日不重复推送
+- [ ] **TC-07：推送内容正确性** — 推送内容与小程序内当日运势一致
+- [ ] **TC-08：多次订阅同一用户** — 幂等处理，不重复创建记录
+
+#### 6.2 异常测试
+- [ ] **TC-09：用户拒绝授权** — 订阅消息授权被拒绝 → 提示用户
+- [ ] **TC-10：云函数超时** — 单个用户推送失败 → 不影响其他用户
+- [ ] **TC-11：生辰信息不完整** — 缺少必要字段 → 提示用户补充
+- [ ] **TC-12：订阅消息过期** — 用户重新订阅后恢复正常
+
+#### 6.3 算法兼容性测试
+- [ ] **TC-13：共享算法包 Node.js 运行** — 算法包在云函数环境输出与小程序一致
+- [ ] **TC-14：边界日期** — 跨年、闰年日期运势计算正确
+
+### 验收标准
+
+- [ ] 所有功能测试场景通过
+- [ ] 所有异常测试场景通过，系统表现符合预期
+- [ ] 共享算法包在小程序和云函数中计算结果一致
+- [ ] 原有测试不受影响（`cd everything-is-suitable-uniapp && npx vitest run` 全部通过）
+- [ ] 云函数执行时间 < 3s/用户
+
+---
+
+## 执行顺序建议
+
+```
+Week 1:
+  ├── Day 1-2: Issue 1 — 共享算法包抽取（可并行）
+  ├── Day 1:   Issue 2 — 云开发环境搭建（可并行）
+  ├── Day 3-4: Issue 3 — 订阅功能实现
+  └── Day 5:   Issue 4 — 每日推送云函数
+
+Week 2:
+  ├── Day 1:   Issue 5 — 订阅管理功能
+  └── Day 2-3: Issue 6 — 集成测试与验收
+```
+
+## 自检清单
+
+1. **规格覆盖度：** PRD 中 F1-F8 全部覆盖 ✅
+2. **占位符扫描：** 无 TODO/待定/后续实现 ✅
+3. **类型一致性：** 云数据库字段与 PRD 定义一致 ✅
+4. **测试覆盖：** 功能测试 14 项 + 异常测试 4 项 + 算法兼容性 2 项 ✅
+5. **原有功能不受影响：** 现有运势页面、紫微排盘、黄历查询不受影响 ✅