diff --git a/docs/adr/2026-08-13-daily-fortune-push.md b/docs/adr/2026-08-13-daily-fortune-push.md new file mode 100644 index 0000000..3c1743d --- /dev/null +++ b/docs/adr/2026-08-13-daily-fortune-push.md @@ -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 触发机制,支持按指定时间定期执行 | +| 共享算法包 | 从应用中抽取的纯算法模块,可在多环境(小程序/云函数)复用 | +| 生辰信息 | 用户的出生日期、时间、地点、性别等用于紫微斗数排盘的数据 | +| 服务通知 | 微信内用户接收订阅消息的入口,位于微信聊天列表"服务通知" | \ No newline at end of file diff --git a/docs/superpowers/plans/2026-08-13-daily-fortune-push/plan.md b/docs/superpowers/plans/2026-08-13-daily-fortune-push/plan.md new file mode 100644 index 0000000..0d30cf1 --- /dev/null +++ b/docs/superpowers/plans/2026-08-13-daily-fortune-push/plan.md @@ -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: 共享算法包抽取
P0 ⭐ 2d"] --> I2["Issue 2: 云开发环境搭建
P0 ⭐ 1d"] + I1 --> I3["Issue 3: 订阅功能实现
P0 ⭐ 2d"] + I2 --> I3 + I2 --> I4["Issue 4: 每日推送云函数
P0 ⭐ 1.5d"] + I3 --> I4 + I4 --> I5["Issue 5: 订阅管理功能
P1 ⭐ 1d"] + I4 --> I6["Issue 6: 集成测试与验收
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
&& 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. **原有功能不受影响:** 现有运势页面、紫微排盘、黄历查询不受影响 ✅ \ No newline at end of file diff --git a/docs/superpowers/specs/2026-08-13-daily-fortune-push-PRD.md b/docs/superpowers/specs/2026-08-13-daily-fortune-push-PRD.md new file mode 100644 index 0000000..a6c0f42 --- /dev/null +++ b/docs/superpowers/specs/2026-08-13-daily-fortune-push-PRD.md @@ -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 触发机制 | +| 共享算法包 | 从应用中抽取的纯算法模块 | +| 服务通知 | 微信内用户接收订阅消息的入口 | \ No newline at end of file