novalon/everything-is-suitable
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- ADR-002: 订阅与每日运势推送功能设计决策
- PRD: 订阅与每日推送功能需求规格说明
- 实现计划文档
This commit is contained in:
zhangxiang
2026-08-13 08:06:01 +08:00
parent 7f0ef622e7
commit e6488cdab9
3 changed files with 773 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/2026-08-13-daily-fortune-push.md
+134
View File
@@ -0,0 +1,134 @@
# ADR-002: 订阅与每日运势推送功能设计
## 状态
✅ 已采纳
## 日期
2026-08-13
## 背景
用户希望在小程序端获得每日运势推送功能，无需手动打开应用即可在每日固定时间收到个性化运势推送。
## 需求
1. 用户可订阅每日运势推送服务
2. 每日固定时间（默认 07:00）推送当日运势
3. 推送内容基于用户生辰信息的紫微斗数命盘，由现有算法本地生成
4. 用户可自定义推送时间
5. 仅限微信小程序平台
## 约束
1. 纯客户端 → 需引入轻量后端用于推送（微信订阅消息要求服务端调用）
2. 微信订阅消息模板需在微信小程序后台申请，使用 `wx.subscribeMessage.send` 接口
3. 云函数运行环境为 Node.js，需兼容现有 TypeScript 算法
## 数据模型
### 云数据库：subscriptions 集合
```typescript
interface Subscription {
_id: string // 云数据库自动 ID
openid: string // 用户微信 openid（唯一索引）
templateId: string // 微信订阅消息模板 ID
birthInfo: { // 用户生辰信息（用于服务器端生成运势）
birthDate: string // 公历出生日期 YYYY-MM-DD
birthHour: number // 出生小时 (0-23)
birthMinute: number // 出生分钟 (0-59)
birthPlace: string // 出生地名称
longitude: number // 出生地经度
latitude: number // 出生地纬度
gender: 'MALE' | 'FEMALE'
}
pushTime: string // 推送时间，格式 "HH:mm"，默认 "07:00"
pushEnabled: boolean // 是否开启推送
subscribedAt: Date // 订阅时间
lastPushDate: string // 最后推送日期 YYYY-MM-DD（防重复推送）
expireAt: Date // 订阅过期时间（微信订阅消息有效期）
}
```
### 小程序端本地存储（新增）
| Key | 类型 | 存储内容 | 生命周期 |
|-----|------|---------|---------|
| `eis_push_subscription` | `Subscription` | 订阅信息缓存 | 持久化，订阅/取消时更新 |
## 决策
### 决策1：推送方案 — 微信订阅消息 + 微信云开发
**方案**：微信订阅消息（`wx.subscribeMessage.send`）+ 微信云开发（CloudBase）
**选择理由**：
- 微信订阅消息是微信小程序原生推送能力，用户可在"服务通知"中收到推送
- 微信云开发提供云函数 + 云数据库 + 定时触发器，与微信生态无缝集成
- 无需额外服务器，按量计费，小规模使用在免费额度内
- 云函数定时触发器（cron）支持每日定时执行
**替代方案排除**：
- 自建后端服务器：运维成本高，超出当前项目规模
- 纯本地推送：H5 不支持后台推送，小程序端无法跨平台
- 第三方推送服务：增加外部依赖和费用
### 决策2：算法复用方案 — 共享算法包
**方案**：将现有运势算法（纯函数层）抽取为独立 npm 包，小程序和云函数共享
**选择理由**：
- 现有运势算法（`fortuneStrategy.ts`、`ziweiAlgorithm.ts`、`fortune.ts`）是纯函数，无 UI 依赖
- 输入 `ZiweiChart + Date` 输出 `DailyFortune`，可在 Node.js 环境直接运行
- 结果一致性保障：小程序端和云函数推送使用同一份代码
- 后续算法更新只需维护一份代码
**依赖映射**：
```
共享算法包 @everything-suitable/algorithm/
├── fortuneStrategy.ts # 运势生成策略（纯函数）
├── fortune.ts # 综合运势生成（纯函数）
├── ziweiAlgorithm.ts # 紫微算法基础（纯函数，含幸运色/数字/方位）
├── types.ts # 类型定义
├── enums.ts # 枚举定义
└── index.ts # 导出入口
```
### 决策3：数据流设计
**订阅流程**：
```
小程序端 → 用户订阅 → 收集生辰信息 → 上传至云函数 → 存储至云数据库
```
**每日推送流程**：
```
云函数定时触发器 (07:00) → 查询当日所有订阅 → 对每用户调用共享算法生成运势
→ 调用 wx.subscribeMessage.send → 用户收到服务通知
```
### 决策4：推送模板结构
| 模板字段 | 内容 | 数据来源 |
|---------|------|---------|
| `date1` | 今日日期 | `new Date().toLocaleDateString('zh-CN')` |
| `thing2` | 综合运势评分 + 等级 | `overallScore` + `overallLuck` |
| `thing3` | 各维度运势建议 | `careerAdvice` / `wealthAdvice` / `relationshipAdvice` / `healthAdvice` |
| `thing4` | 幸运色 + 幸运数字 | `luckyColor` + `luckyNumber` |
## 影响
1. **新增目录**：`everything-is-suitable-uniapp/cloudfunctions/`（云函数目录）
2. **新增目录**：`packages/algorithm/`（共享算法包）
3. **新增依赖**：`@everything-suitable/algorithm`（共享算法包的本地引用）
4. **新增页面**：小程序端订阅管理页面（订阅/取消/配置推送时间）
5. **新增存储**：微信云开发环境配置（云数据库、云函数、定时触发器）
6. **不影响现有功能**：现有运势页面、紫微排盘、黄历查询不受影响
7. **不影响现有测试**：共享算法包抽取后，现有测试仍可正常运行
## 术语表
| 术语 | 定义 |
|------|------|
| 微信订阅消息 | 微信小程序提供的消息推送能力，用户订阅后可在"服务通知"中收到消息 |
| 微信云开发 | 微信生态内的 Serverless 云服务，提供云函数、云数据库、存储等 |
| 云函数 | 运行在微信云端的 Node.js 函数，通过定时触发器或事件触发 |
| 定时触发器 | 云函数的 cron 触发机制，支持按指定时间定期执行 |
| 共享算法包 | 从应用中抽取的纯算法模块，可在多环境（小程序/云函数）复用 |
| 生辰信息 | 用户的出生日期、时间、地点、性别等用于紫微斗数排盘的数据 |
| 服务通知 | 微信内用户接收订阅消息的入口，位于微信聊天列表"服务通知" |
docs/superpowers/plans/2026-08-13-daily-fortune-push/plan.md
+398
View File
@@ -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. **原有功能不受影响：** 现有运势页面、紫微排盘、黄历查询不受影响 ✅
docs/superpowers/specs/2026-08-13-daily-fortune-push-PRD.md
+241
View File
@@ -0,0 +1,241 @@
# PRD: 订阅与每日运势推送功能
## 1. 概述
### 1.1 产品名称
万事宜 — 订阅与每日运势推送
### 1.2 目标用户
已输入生辰信息并使用紫微斗数运势功能的微信小程序用户
### 1.3 核心价值
用户无需手动打开小程序，每日自动收到个性化运势推送，提升日活与用户粘性
### 1.4 约束条件
- 仅限微信小程序平台
- 依赖微信云开发（CloudBase）作为轻量后端
- 推送内容由现有算法本地/云端生成，无需外部数据源
## 2. 功能范围
### 2.1 范围内（MVP）
| 功能 | 说明 |
|------|------|
| F1: 订阅入口 | 在运势页面提供订阅入口，引导用户订阅每日推送 |
| F2: 微信订阅消息授权 | 调用 `wx.requestSubscribeMessage` 获取用户授权 |
| F3: 生辰信息上传 | 将用户生辰信息上传至云数据库，用于云端生成运势 |
| F4: 每日定时推送 | 云函数定时触发器每日 07:00 执行推送 |
| F5: 推送内容生成 | 云函数调用共享算法包生成当日运势 |
| F6: 推送时间配置 | 用户可自定义推送时间（默认 07:00） |
| F7: 取消订阅 | 用户可随时取消推送，清理云数据库订阅记录 |
| F8: 共享算法包抽取 | 将运势算法纯函数层抽取为独立 npm 包 |
### 2.2 范围外（后续迭代）
| 功能 | 说明 |
|------|------|
| 黄历每日推送 | 未来可扩展为推送当日宜忌 |
| 多模板推送 | 支持不同模板（运势、黄历、提醒等） |
| 多平台推送 | H5 浏览器推送、App 原生推送 |
| 推送统计 | 推送到达率、点击率分析 |
## 3. 用户故事
### US-01: 订阅推送
> 作为已设置生辰信息的用户，我希望在运势页面看到订阅入口，一键订阅每日运势推送，从而每天自动收到我的运势信息。
**验收标准**：
- [ ] 用户进入运势页面时，显示订阅入口（仅未订阅时）
- [ ] 点击订阅后，弹出微信订阅消息授权弹窗
- [ ] 用户授权后，生辰信息上传至云数据库
- [ ] 订阅成功后显示"已订阅"状态和每日推送时间
- [ ] 未输入生辰信息的用户提示先设置生辰信息
### US-02: 每日推送接收
> 作为已订阅用户，我希望每天在固定时间收到服务通知，查看当日的综合运势、各维度运势和幸运信息。
**验收标准**：
- [ ] 每日在用户配置的时间（默认 07:00）收到服务通知
- [ ] 推送内容包含：日期、综合运势评分+等级、各维度运势、幸运色+数字
- [ ] 推送内容与小程序内当日运势一致
- [ ] 同一用户每日不会收到重复推送
### US-03: 推送时间配置
> 作为已订阅用户，我希望在订阅管理页面修改推送时间，从而适配我的作息习惯。
**验收标准**：
- [ ] 订阅管理页面显示当前推送时间
- [ ] 用户可修改推送时间（步长 30 分钟）
- [ ] 修改后云端同步更新
- [ ] 修改后下一次推送按新时间执行
### US-04: 取消订阅
> 作为已订阅用户，我希望在订阅管理页面一键取消订阅，从而不再收到每日推送。
**验收标准**：
- [ ] 订阅管理页面提供"取消订阅"按钮
- [ ] 取消后删除云端订阅记录
- [ ] 取消后不再收到推送
- [ ] 取消后订阅入口重新显示
## 4. 架构与数据流
### 4.1 系统架构
```
┌──────────────────────────────────────────────────────┐
│ 微信小程序 │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ 运势页面 │ │ 订阅管理页面 │ │ 共享算法包 │ │
│ │ (订阅入口) │ │ (时间/取消) │ │ (本地使用) │ │
│ └──────┬───────┘ └──────┬───────┘ └───────────┘ │
│ │ │ │
│ └────────┬────────┘ │
│ │ │
│ wx.cloud.callFunction │
└──────────────────┼─────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────┐
│ 微信云开发 (CloudBase) │
│ ┌────────────────────┐ ┌────────────────────────┐ │
│ │ 云函数: subscribe │ │ 云函数: dailyPush │ │
│ │ - 存储订阅关系 │ │ - 定时触发器 07:00 │ │
│ │ - 存储生辰信息 │ │ - 调用共享算法包 │ │
│ │ - 更新推送时间 │ │ - 生成运势内容 │ │
│ │ - 取消订阅 │ │ - 调用 subscribe.send │ │
│ └────────────────────┘ └────────────────────────┘ │
│ ┌────────────────────────┐ │
│ │ 云函数: unsubscribe │ │
│ │ - 删除订阅记录 │ │
│ └────────────────────────┘ │
│ ┌────────────────────────────────────────────────┐ │
│ │ 云数据库: subscriptions 集合 │ │
│ │ { openid, templateId, birthInfo, pushTime, │ │
│ │ pushEnabled, subscribedAt, lastPushDate } │ │
│ └────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────┐ │
│ │ 共享算法包 @everything-suitable/algorithm │ │
│ │ (云函数依赖，纯 TypeScript 计算) │ │
│ └────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
```
### 4.2 数据流
**订阅流程**：
```
1. 用户点击"订阅每日推送"
2. 小程序检查用户是否已输入生辰信息
3. 调用 wx.requestSubscribeMessage 请求授权
4. 用户授权 → 小程序调用云函数 subscribe
5. 云函数将 { openid, birthInfo, templateId, pushTime } 写入云数据库
6. 返回成功 → 小程序 UI 更新为"已订阅"
```
**每日推送流程**：
```
1. 云函数定时触发器 (dailyPush) 在每日 07:00 触发
2. 查询云数据库 subscriptions 中 pushEnabled=true 且 lastPushDate != today 的记录
3. 对每条记录：
a. 使用 birthInfo 计算 ZiweiChart（本地算法）
b. 使用 chart + today 调用 generateDailyFortune
c. 格式化推送内容（模板字段绑定）
d. 调用 wx.subscribeMessage.send 发送
e. 更新 lastPushDate = today
```
## 5. 共享算法包定义
### 5.1 包结构
```
packages/algorithm/
├── package.json
├── tsconfig.json
├── src/
│ ├── index.ts # 导出入口
│ ├── fortuneStrategy.ts # 运势生成策略
│ ├── fortune.ts # 综合运势生成
│ ├── ziweiAlgorithm.ts # 紫微算法基础
│ ├── types.ts # 类型定义
│ ├── enums.ts # 枚举定义
│ └── __tests__/ # 算法测试
│ └── fortuneStrategy.test.ts
└── README.md
```
### 5.2 导出接口
```typescript
// 核心导出
export { generateDailyFortune } from './fortuneStrategy'
export { generateComprehensiveFortune } from './fortune'
export { calculateLuckyColor, calculateLuckyNumber, calculateLuckyDirection } from './ziweiAlgorithm'
export { determineLuckLevel, calculatePalaceScore } from './ziweiAlgorithm'
export type { DailyFortune, ZiweiChart, PalaceFortune } from './types'
```
## 6. 微信订阅消息模板
### 6.1 模板申请
在微信小程序管理后台 → 功能 → 订阅消息 → 公共模板库，搜索并选用合适的模板。
### 6.2 推荐模板字段映射
| 模板参数 | 值 | 说明 |
|---------|-----|------|
| `date1` | `{{data.date1}}` | 日期，格式：2026年8月14日 |
| `thing2` | `{{data.thing2}}` | 综合运势，格式：综合评分85分，等级：吉 |
| `thing3` | `{{data.thing3}}` | 各维度运势摘要 |
| `thing4` | `{{data.thing4}}` | 幸运信息，格式：幸运色红色 幸运数字7 |
### 6.3 推送内容示例
```
📅 2026年8月14日
🌟 综合运势：85分（吉）
📊 事业：今日事业运势吉显，适合处理重要工作事务
财运：财运亨通，可进行投资理财
感情：感情运势良好，适合表达爱意
健康：身体状况良好，精力充沛
🍀 幸运色：红色 幸运数字：7
```
## 7. 阶段与里程碑
| 阶段 | 内容 | 预估工时 | 依赖 |
|------|------|---------|------|
| **M1: 共享算法包** | 抽取算法为独立包，确保云函数可调用 | 2d | 无 |
| **M2: 云开发环境** | 开通微信云开发，创建数据库、云函数、定时触发器 | 1d | M1 |
| **M3: 订阅功能** | 小程序端订阅入口 + 订阅管理页面 + 云函数 | 2d | M2 |
| **M4: 每日推送** | 云函数 dailyPush 实现 + 定时触发器配置 | 1.5d | M2+M3 |
| **M5: 测试与验收** | 集成测试 + 推送验证 + 异常处理 | 1.5d | M4 |
## 8. 验收标准
### 8.1 功能验收
| # | 验收项 | 预期结果 |
|---|--------|---------|
| 1 | 未输入生辰信息时订阅 | 提示用户先设置生辰信息 |
| 2 | 首次订阅流程 | 微信授权弹窗 → 生辰信息上传 → 订阅成功 |
| 3 | 每日推送触发 | 用户在配置时间收到服务通知 |
| 4 | 推送内容正确性 | 推送内容与小程序内当日运势一致 |
| 5 | 推送时间修改 | 修改后下次推送按新时间执行 |
| 6 | 取消订阅 | 删除云端记录，不再收到推送 |
| 7 | 重复推送防护 | 同一用户每日仅收到一次推送 |
| 8 | 订阅消息过期 | 用户重新订阅后恢复正常推送 |
### 8.2 非功能验收
| # | 验收项 | 预期结果 |
|---|--------|---------|
| 1 | 云函数执行时间 | < 3s/用户（含算法计算） |
| 2 | 订阅消息到达率 | 微信官方保障，不做额外要求 |
| 3 | 用户数据安全 | 生辰信息仅用于推送计算，不另作他用 |
## 9. 术语表
| 术语 | 定义 |
|------|------|
| 微信订阅消息 | 微信小程序提供的消息推送能力，用户订阅后可在"服务通知"中收到消息 |
| 微信云开发 | 微信生态内的 Serverless 云服务，提供云函数、云数据库、存储等 |
| 云函数 | 运行在微信云端的 Node.js 函数 |
| 定时触发器 | 云函数的 cron 触发机制 |
| 共享算法包 | 从应用中抽取的纯算法模块 |
| 服务通知 | 微信内用户接收订阅消息的入口 |