feat(invitation): 添加邀请注册功能并支持小程序码

- 新增邀请注册功能，允许管理员生成邀请链接和二维码 - 支持网页注册和小程序码注册两种方式 - 实现自动建立推荐关系的功能 - 添加邀请统计和自定义小程序页面等扩展功能 - 优化用户体验和错误处理
2025-09-05 16:58:49 +08:00
parent cf74d2670c
commit 5da7d1b2ad
8 changed files with 1459 additions and 75 deletions
--- a/docs/invitation-feature.md
+++ b/docs/invitation-feature.md
@@ -0,0 +1,201 @@
+# 邀请注册功能使用说明
+
+## 功能概述
+
+邀请注册功能允许管理员生成邀请链接和二维码，邀请新用户注册并自动建立推荐关系。支持网页二维码和小程序码两种方式。
+
+## 功能特点
+
+- ✅ **简单易用**：基于现有推荐关系功能，无需复杂配置
+- ✅ **双重支持**：支持网页注册和小程序注册
+- ✅ **自动关联**：用户注册后自动建立推荐关系
+- ✅ **多种分享**：支持链接复制、二维码下载等分享方式
+
+## 使用流程
+
+### 管理员操作
+
+1. **进入管理页面**
+   - 访问 `/shop/admin` 商店管理员页面
+   - 点击"邀请注册"按钮
+
+2. **生成邀请码**
+   - 弹窗会自动生成包含当前用户ID的邀请链接
+   - 选择二维码类型：网页二维码或小程序码
+
+3. **分享邀请**
+   - 复制邀请链接发送给用户
+   - 下载二维码图片分享
+   - 让用户直接扫描屏幕上的二维码
+
+### 用户注册
+
+#### 网页注册流程
+1. 用户点击邀请链接或扫描网页二维码
+2. 进入注册页面，会显示邀请提示信息
+3. 填写注册信息完成注册
+4. 系统自动建立与邀请人的推荐关系
+
+#### 小程序注册流程
+1. 用户扫描小程序码进入小程序
+2. 小程序自动识别邀请参数
+3. 用户在小程序内完成注册
+4. 系统自动建立推荐关系
+
+## 技术实现
+
+### 邀请链接格式
+```
+网页注册: https://domain.com/register?inviter=123
+小程序码: scene参数为 invite_123
+```
+
+### 核心文件
+
+1. **邀请弹窗组件**
+   ```
+   src/views/shop/shopAdmin/components/invitation-modal.vue
+   ```
+
+2. **小程序码API**
+   ```
+   src/api/miniprogram/index.ts
+   ```
+
+3. **注册页面优化**
+   ```
+   src/views/passport/register/index.vue
+   ```
+
+### API接口
+
+#### 生成小程序码
+```typescript
+// 生成邀请注册小程序码
+generateInviteRegisterCode(inviterId: number): Promise<string>
+
+// 参数说明
+{
+  page: 'pages/register/index',  // 小程序注册页面
+  scene: 'invite_123',           // 邀请参数
+  width: 180,                    // 二维码宽度
+  envVersion: 'trial'            // 环境版本
+}
+```
+
+#### 建立推荐关系
+```typescript
+// 绑定推荐关系
+bindUserReferee(data: UserReferee): Promise<string>
+
+// 参数说明
+{
+  dealerId: 123,    // 邀请人ID
+  userId: 456,      // 被邀请人ID
+  level: 1          // 推荐层级
+}
+```
+
+## 配置说明
+
+### 小程序码配置
+
+在 `src/api/miniprogram/index.ts` 中可以配置：
+
+```typescript
+// 基础URL配置
+const BaseUrl = SERVER_API_URL;
+
+// 小程序页面配置
+const MINIPROGRAM_PAGES = {
+  register: 'pages/register/index',  // 注册页面
+  index: 'pages/index/index'         // 首页
+};
+
+// 环境配置
+const ENV_VERSION = 'trial'; // release | trial | develop
+```
+
+### 注册页面配置
+
+在注册页面中，系统会自动检测URL参数：
+- `inviter`: 邀请人ID
+- 检测到邀请参数时显示邀请提示
+
+## 错误处理
+
+### 常见问题
+
+1. **小程序码加载失败**
+   - 检查小程序码生成接口是否正常
+   - 确认 `BaseUrl` 配置正确
+   - 查看网络连接状态
+
+2. **推荐关系建立失败**
+   - 检查用户ID是否正确获取
+   - 确认推荐关系API接口正常
+   - 查看控制台错误日志
+
+3. **邀请链接无效**
+   - 确认URL参数格式正确
+   - 检查注册页面参数解析逻辑
+
+### 调试方法
+
+1. **开启控制台日志**
+   ```javascript
+   // 在浏览器控制台查看
+   localStorage.setItem('debug', 'true');
+   ```
+
+2. **检查网络请求**
+   - 打开浏览器开发者工具
+   - 查看Network标签页的API请求
+
+3. **验证参数传递**
+   ```javascript
+   // 检查邀请参数
+   const urlParams = new URLSearchParams(window.location.search);
+   console.log('邀请人ID:', urlParams.get('inviter'));
+   ```
+
+## 扩展功能
+
+### 自定义小程序页面
+可以根据需要修改小程序码跳转的页面：
+
+```typescript
+export async function generateCustomInviteCode(inviterId: number, page: string) {
+  return generateMiniProgramCode({
+    page: page,
+    scene: `invite_${inviterId}`,
+    width: 180,
+    checkPath: true,
+    envVersion: 'trial'
+  });
+}
+```
+
+### 添加邀请统计
+可以扩展功能添加邀请统计：
+
+```typescript
+// 统计邀请成功数量
+export async function getInviteStats(inviterId: number) {
+  // 查询推荐关系表统计数据
+  return listUserReferee({ dealerId: inviterId });
+}
+```
+
+## 注意事项
+
+1. **权限控制**：确保只有管理员可以生成邀请码
+2. **参数验证**：注册时需要验证邀请人ID的有效性
+3. **重复注册**：防止同一用户重复建立推荐关系
+4. **小程序配置**：确保小程序端正确处理scene参数
+
+## 更新日志
+
+- **v1.0.0**: 基础邀请注册功能
+- **v1.1.0**: 添加小程序码支持
+- **v1.2.0**: 优化用户体验和错误处理