feat: 初始化项目

2025-08-13 15:17:33 +08:00
commit 4f9d648a50
72 changed files with 29051 additions and 0 deletions
--- a/docs/app-store-server-notifications.md
+++ b/docs/app-store-server-notifications.md
@@ -0,0 +1,190 @@
+# App Store 服务器通知接收接口
+
+## 概述
+
+本接口用于接收来自苹果App Store的服务器通知（App Store Server Notifications V2），处理用户订阅状态的变化，包括订阅、续订、过期、退款等事件。
+
+## 接口地址
+
+```
+POST /api/users/app-store-notifications
+```
+
+## 配置要求
+
+### 1. 在App Store Connect中配置
+
+1. 登录 [App Store Connect](https://appstoreconnect.apple.com)
+2. 选择你的应用
+3. 在左侧菜单中选择 "App信息"
+4. 滚动到 "App Store服务器通知" 部分
+5. 设置生产环境URL：`https://your-domain.com/api/users/app-store-notifications`
+6. 设置沙盒环境URL：`https://your-domain.com/api/users/app-store-notifications`
+7. 选择 "Version 2" 通知格式
+8. 保存设置
+
+### 2. 环境变量配置
+
+确保以下环境变量已正确设置：
+
+```bash
+# Apple相关配置
+APPLE_BUNDLE_ID=com.yourcompany.yourapp
+APPLE_KEY_ID=your_key_id
+APPLE_ISSUER_ID=your_issuer_id
+APPLE_PRIVATE_KEY_PATH=path/to/your/private/key.p8
+APPLE_APP_SHARED_SECRET=your_shared_secret
+```
+
+## 请求格式
+
+### 请求头
+```
+Content-Type: application/json
+```
+
+### 请求体
+```json
+{
+  "signedPayload": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjEyMzQ1Njc4OTAiLCJ0eXAiOiJKV1QifQ..."
+}
+```
+
+## 响应格式
+
+### 成功响应
+```json
+{
+  "code": 200,
+  "message": "通知处理成功",
+  "data": {
+    "processed": true,
+    "notificationType": "SUBSCRIBED",
+    "notificationUUID": "12345678-1234-1234-1234-123456789012",
+    "userId": "user_12345",
+    "transactionId": "1000000123456789"
+  }
+}
+```
+
+### 错误响应
+```json
+{
+  "code": 500,
+  "message": "处理通知失败: 无法解码通知负载",
+  "data": {
+    "processed": false
+  }
+}
+```
+
+## 支持的通知类型
+
+### 1. SUBSCRIBED（订阅）
+- **描述**: 用户首次订阅或重新订阅
+- **处理**: 更新用户的订阅状态和到期时间
+
+### 2. DID_RENEW（续订）
+- **描述**: 订阅成功续订
+- **处理**: 延长用户的订阅到期时间
+
+### 3. EXPIRED（过期）
+- **描述**: 订阅已过期
+- **处理**: 可以发送邮件通知或降级用户权限
+
+### 4. DID_FAIL_TO_RENEW（续订失败）
+- **描述**: 订阅续订失败（通常是支付问题）
+- **处理**: 发送付款提醒或进入宽限期
+
+### 5. REFUND（退款）
+- **描述**: 用户获得退款
+- **处理**: 立即撤销用户的订阅权限
+
+### 6. REVOKE（撤销）
+- **描述**: 通过家庭共享获得的权限被撤销
+- **处理**: 撤销用户的订阅权限
+
+### 7. DID_CHANGE_RENEWAL_STATUS（续订状态变更）
+- **描述**: 用户更改了自动续订设置
+- **处理**: 记录用户的续订偏好
+
+### 8. TEST（测试）
+- **描述**: 测试通知
+- **处理**: 仅记录日志，无特殊处理
+
+## 安全考虑
+
+### 1. 签名验证
+- 接口会验证通知的JWS签名
+- 确保通知来自苹果官方服务器
+- 验证bundleId匹配
+
+### 2. 重复处理
+- 建议实现幂等性处理
+- 根据notificationUUID去重
+- 避免重复处理相同通知
+
+### 3. 错误处理
+- 对于无法处理的通知，返回适当的HTTP状态码
+- 苹果会根据响应状态码决定是否重试
+
+## 日志记录
+
+接口会记录以下信息：
+- 收到的通知类型和UUID
+- 解码后的交易信息
+- 处理结果和任何错误
+- 用户ID和交易ID（如果可用）
+
+## 测试
+
+### 1. 使用App Store Connect测试
+1. 在App Store Connect中请求测试通知
+2. 检查服务器日志确认收到通知
+3. 验证通知处理逻辑是否正确
+
+### 2. 沙盒环境测试
+1. 使用沙盒环境进行购买测试
+2. 观察通知是否正确触发
+3. 验证用户状态是否正确更新
+
+## 故障排除
+
+### 常见问题
+
+1. **收不到通知**
+   - 检查App Store Connect中的URL配置
+   - 确保服务器可以从外网访问
+   - 检查防火墙设置
+
+2. **通知解码失败**
+   - 验证私钥文件路径和格式
+   - 检查环境变量配置
+   - 确认bundleId匹配
+
+3. **用户状态未更新**
+   - 检查appAccountToken是否正确设置
+   - 验证用户ID映射逻辑
+   - 查看数据库更新日志
+
+### 日志查看
+```bash
+# 查看相关日志
+grep "App Store" /path/to/your/logs/app.log
+grep "processAppStoreNotification" /path/to/your/logs/app.log
+```
+
+## 扩展功能
+
+可以根据业务需求扩展以下功能：
+
+1. **邮件通知**: 在特定事件发生时发送邮件
+2. **数据分析**: 收集订阅数据用于分析
+3. **第三方集成**: 将事件发送到其他系统
+4. **自定义业务逻辑**: 根据不同的通知类型执行特定操作
+
+## 相关文档
+
+- [App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications)
+- [App Store Server API](https://developer.apple.com/documentation/appstoreserverapi)
+- [StoreKit 2](https://developer.apple.com/documentation/storekit)