wxserver/云开发功能说明.md

生日提醒小程序 - 云开发功能说明

📁 项目结构

生日提醒小程序/
├── cloudfunctions/              # 云函数目录
│   ├── login/                   # 获取用户openid
│   │   ├── index.js
│   │   ├── config.json
│   │   └── package.json
│   ├── syncAnniversary/         # 同步纪念日数据
│   │   ├── index.js
│   │   ├── config.json
│   │   └── package.json
│   └── sendReminder/            # 发送提醒消息
│       ├── index.js
│       ├── config.json          # 包含定时触发器配置
│       └── package.json
├── pages/                       # 小程序页面
├── utils/                       # 工具函数
├── app.js                       # 应用入口（已添加云开发初始化）
├── app.json                     # 应用配置
└── project.config.json          # 项目配置

---

🔧 核心功能实现

1. 云开发初始化（app.js）

// 应用启动时初始化云开发
wx.cloud.init({
  env: 'cloudbase-1gk3x0ia3a6b1f80',
  traceUser: true
})

// 自动获取用户openid
await wx.cloud.callFunction({ name: 'login' })

作用：

• 连接到你的云开发环境
• 获取用户唯一标识（openid）
• 为后续功能提供基础

---

2. 订阅消息授权（add-anniversary.js）

// 用户添加纪念日并开启提醒时
wx.requestSubscribeMessage({
  tmplIds: ['6J7Stt-lu7DKU6jblJ0nZGq_D81z5glnksf7qWfy5Yw']
})

流程：

1. 用户添加纪念日
2. 开启"是否提醒"开关
3. 点击保存
4. 弹出订阅授权弹窗
5. 用户点击"允许"
6. 数据保存到本地和云端

效果：

• ✅ 用户授权后才能收到推送
• ✅ 一次授权，长期有效
• ✅ 用户可随时管理订阅

---

3. 数据云端同步（syncAnniversary 云函数）

支持的操作：

添加纪念日

wx.cloud.callFunction({
  name: 'syncAnniversary',
  data: {
    action: 'add',
    data: { ...anniversaryData }
  }
})

更新纪念日

wx.cloud.callFunction({
  name: 'syncAnniversary',
  data: {
    action: 'update',
    data: { id, ...anniversaryData }
  }
})

删除纪念日

wx.cloud.callFunction({
  name: 'syncAnniversary',
  data: {
    action: 'delete',
    data: { id }
  }
})

数据结构：

{
  _id: "cloud-generated-id",
  _openid: "user-openid",           // 自动添加
  personId: "person-id",
  personName: "张三",
  type: "birthday",
  solarYear: 1990,
  solarMonth: 5,
  solarDay: 15,
  remindEnabled: true,
  remindDays: 7,
  remark: "记得买蛋糕",
  createTime: Date,
  updateTime: Date
}

---

4. 定时发送提醒（sendReminder 云函数）

执行时间：每天上午9:00

执行流程：

1. 查询所有启用提醒的纪念日
   ↓
2. 遍历每个纪念日
   ↓
3. 计算距离纪念日还有多少天
   ↓
4. 判断是否需要提醒
   - 当天生日：发送
   - 提前N天：发送（N=用户设置的remindDays）
   ↓
5. 检查今天是否已发送
   ↓
6. 调用微信API发送订阅消息
   ↓
7. 记录提醒日志

提醒内容示例：

称呼：张三
临近日期：还有3天
生日日期：2025年10月30日
温馨提示：别忘了准备一份礼物哦！

日志记录：

{
  anniversaryId: "anniversary-id",
  personName: "张三",
  typeName: "公历生日",
  daysUntil: 3,
  sendDate: Date,
  status: "success"  // 或 "failed"
}

---

🔄 数据流程图

用户添加纪念日

用户填写表单
    ↓
开启提醒开关
    ↓
点击保存
    ↓
[请求订阅授权] ← 用户授权
    ↓
保存到本地存储
    ↓
同步到云数据库 ← 包含 openid
    ↓
完成

定时提醒流程

每天 9:00
    ↓
云函数被触发
    ↓
查询云数据库
    ↓
筛选需要提醒的纪念日
    ↓
循环处理每条记录
    ↓
计算剩余天数
    ↓
满足条件？
 ├─ 是 → 发送订阅消息 → 记录日志
 └─ 否 → 跳过
    ↓
完成

---

🎯 关键技术点

1. openid 的作用

// openid 是用户在你的小程序中的唯一标识
{
  "_openid": "oABCD1234567890",  // 自动添加到数据库记录
  "personName": "张三",
  ...
}

用途：

• 区分不同用户的数据
• 发送订阅消息时指定接收者
• 保证数据安全（用户只能访问自己的数据）

2. 订阅消息模板

你的模板信息：

模板ID: 6J7Stt-lu7DKU6jblJ0nZGq_D81z5glnksf7qWfy5Yw

字段映射：
- name1.DATA → 称呼（人员姓名）
- thing2.DATA → 临近日期（还有X天）
- thing6.DATA → 生日日期（2025年10月30日）
- thing5.DATA → 温馨提示（备注或默认文案）

3. 定时触发器

Cron 表达式：0 0 9 * * * *

秒 分 时 日 月 星期 年
0  0  9  *  *  *    *

含义：每天上午9点0分0秒执行

修改提醒时间：

每天早上8点：  0 0 8 * * * *
每天晚上8点：  0 0 20 * * * *
每天早晚两次： 0 0 8,20 * * * *

---

📊 数据库设计

anniversaries（纪念日表）

字段	类型	说明	示例
_id	String	主键（自动生成）	"5f1e..."
_openid	String	用户openid（自动）	"oABC..."
personId	String	人员ID	"id_123..."
personName	String	人员姓名	"张三"
type	String	类型	"birthday"
solarMonth	Number	公历月份	10
solarDay	Number	公历日期	30
remindEnabled	Boolean	是否提醒	true
remindDays	Number	提前天数	7
remark	String	备注	"买蛋糕"

remind_logs（提醒日志表）

字段	类型	说明	示例
_id	String	主键（自动生成）	"5f1e..."
anniversaryId	String	纪念日ID	"5f1e..."
personName	String	人员姓名	"张三"
daysUntil	Number	剩余天数	3
sendDate	Date	发送时间	Date对象
status	String	状态	"success"

---

🚨 注意事项

1. 订阅消息限制

• ✅ 用户主动触发授权（不能自动弹出）
• ✅ 一次授权一个模板
• ✅ 用户可以随时取消订阅
• ❌ 不能发送营销类消息

2. 云函数限制

免费额度（每天）：

• 调用次数：10万次
• 运行时间：40万GBs
• 出流量：5GB

对于个人用户，完全够用！

3. 数据库限制

免费额度：

• 容量：5GB
• 读操作：5万次/天
• 写操作：3万次/天

估算：

• 100个用户，每人10条纪念日 = 1000条记录
• 每条约1KB，总共约1MB
• 完全在免费额度内！

---

🔍 调试技巧

1. 查看云函数日志

云开发控制台 → 云函数 → 选择函数 → 日志

可以看到：

• 函数执行时间
• 返回结果
• 错误信息
• console.log 输出

2. 测试云函数

云开发控制台 → 云函数 → 选择函数 → 测试

输入测试参数：{}
点击"运行测试"

3. 查看数据库

云开发控制台 → 数据库 → 选择集合

可以：
- 查看所有记录
- 编辑数据
- 删除数据
- 导出数据

4. 模拟定时触发

// 临时修改 Cron 表达式为每分钟执行
"0 */1 * * * * *"

// 测试完成后改回
"0 0 9 * * * *"

---

💡 优化建议

1. 添加提醒历史页面

显示用户收到的所有提醒记录。

2. 支持多个提醒时间

比如提前7天、3天、当天各提醒一次。

3. 自定义提醒文案

让用户可以自定义温馨提示内容。

4. 提醒统计

显示总共发送了多少条提醒，成功率等。

---

🎉 总结

现在你的小程序具备了完整的云端能力：

✅ 数据云端存储 - 永不丢失 ✅ 自动推送提醒 - 不再遗忘 ✅ 多设备同步 - 随处访问 ✅ 安全可靠 - openid隔离

开始享受智能生日提醒服务吧！ 🎂