398 lines
14 KiB
Markdown
398 lines
14 KiB
Markdown
# 订阅与每日运势推送 — 实现计划
|
||
|
||
> **面向 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. **原有功能不受影响：** 现有运势页面、紫微排盘、黄历查询不受影响 ✅ |