# 用户登录与信息授权方案

> 版本：v1.0
> 最后更新：2026-05-06
> 适用范围：微信小程序云开发环境下的用户身份管理

---

## 一、方案概述

采用**静默登录**策略：用户进入小程序后无感知地完成身份识别与用户创建，不弹出任何授权弹窗。昵称和头像等个人信息在后续需要时（如个人中心、评论等场景）再引导用户主动授权。

**核心流程**：

```
用户打开小程序
    │
    ├─ 本地 Storage 有用户数据且未过期？
    │       │
    │       ├─ 是 → 直接使用本地数据，跳过登录
    │       │
    │       └─ 否 → 调用云函数 silentLogin
    │                   │
    │                   ├─ cloud.getWXContext() 获取 openid/unionid
    │                   │
    │                   ├─ 查询 users 集合（openid）
    │                   │       │
    │                   │       ├─ 存在 → 更新 lastActiveAt，返回用户数据
    │                   │       │
    │                   │       └─ 不存在 → 创建用户（nickName/avatarUrl 为空），返回用户数据
    │                   │
    │                   └─ 前端收到用户数据 → 写入内存 + Storage
    │
    └─ 完成，进入正常使用
```

---

## 二、技术细节

### 2.1 云函数：`userLogin`

**职责**：静默登录，upsert 用户记录。

```javascript
// cloudfunctions/userLogin/index.js
const cloud = require('wx-server-sdk');
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV });

const db = cloud.database();

exports.main = async (event, context) => {
    const wxContext = cloud.getWXContext();
    const openid = wxContext.OPENID;
    const unionid = wxContext.UNIONID || null;

    const usersCollection = db.collection('users');

    // 查询是否已存在
    const { data } = await usersCollection.where({ openid }).limit(1).get();

    const now = db.serverDate();

    if (data.length > 0) {
        // 已存在：更新 lastActiveAt 和 unionid（如果有新值）
        const user = data[0];
        const updateData = { lastActiveAt: now };
        if (unionid && !user.unionid) {
            updateData.unionid = unionid;
        }
        await usersCollection.doc(user._id).update({ data: updateData });

        return {
            code: 0,
            data: { ...user, ...updateData, lastActiveAt: new Date() },
        };
    } else {
        // 不存在：创建新用户
        const newUser = {
            openid,
            unionid,
            nickName: null,
            avatarUrl: null,
            totalDownloads: 0,
            createdAt: now,
            lastActiveAt: now,
        };
        const { _id } = await usersCollection.add({ data: newUser });

        return {
            code: 0,
            data: {
                _id,
                ...newUser,
                createdAt: new Date(),
                lastActiveAt: new Date(),
            },
        };
    }
};
```

**要点**：

- `cloud.getWXContext()` 在云函数中自动获取调用者的 `OPENID`，无需前端传 code
- `UNIONID` 仅在小程序绑定了开放平台且满足条件时才有值，所以设为可选
- 使用 `db.serverDate()` 确保时间由服务端生成，避免客户端时间不准
- `_id` 由云数据库自动生成（`add()` 时不指定），为随机唯一字符串；业务上通过 `openid` 唯一索引定位用户，`_id` 作为主键供子表（favorites、download_logs）的 `userId` 外键引用

---

### 2.2 前端登录逻辑

**位置**：建议封装为 `miniprogram/utils/auth.ts`

```typescript
// miniprogram/utils/auth.ts

interface UserInfo {
    _id: string;
    openid: string;
    unionid: string | null;
    nickName: string | null;
    avatarUrl: string | null;
    totalDownloads: number;
    createdAt: string;
    lastActiveAt: string;
}

const STORAGE_KEY = 'user_info';
const STORAGE_EXPIRE_KEY = 'user_info_expire';
const EXPIRE_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 天

/** 内存中的用户数据（App 生命周期内有效） */
let currentUser: UserInfo | null = null;

/**
 * 获取当前用户，优先内存 → Storage → 云函数登录
 */
export async function getUser(): Promise<UserInfo> {
    // 1. 内存中有，直接返回
    if (currentUser) return currentUser;

    // 2. 尝试从 Storage 读取
    const cached = loadFromStorage();
    if (cached) {
        currentUser = cached;
        return cached;
    }

    // 3. 静默登录
    return await silentLogin();
}

/**
 * 静默登录：调用云函数
 */
async function silentLogin(): Promise<UserInfo> {
    const { result } = await wx.cloud.callFunction({
        name: 'userLogin',
    });

    if (result.code !== 0) {
        throw new Error('登录失败');
    }

    const user = result.data as UserInfo;
    currentUser = user;
    saveToStorage(user);
    return user;
}

/**
 * 从 Storage 读取用户数据（检查过期）
 */
function loadFromStorage(): UserInfo | null {
    try {
        const expire = wx.getStorageSync(STORAGE_EXPIRE_KEY);
        if (!expire || Date.now() > expire) {
            // 已过期，清除
            wx.removeStorageSync(STORAGE_KEY);
            wx.removeStorageSync(STORAGE_EXPIRE_KEY);
            return null;
        }
        const user = wx.getStorageSync(STORAGE_KEY);
        return user || null;
    } catch {
        return null;
    }
}

/**
 * 写入 Storage
 */
function saveToStorage(user: UserInfo): void {
    try {
        wx.setStorageSync(STORAGE_KEY, user);
        wx.setStorageSync(STORAGE_EXPIRE_KEY, Date.now() + EXPIRE_DURATION);
    } catch {
        // Storage 写入失败不影响主流程
    }
}

/**
 * 清除登录状态（用于退出登录或需要强制刷新时）
 */
export function clearUser(): void {
    currentUser = null;
    wx.removeStorageSync(STORAGE_KEY);
    wx.removeStorageSync(STORAGE_EXPIRE_KEY);
}

/**
 * 强制刷新用户数据（跳过缓存）
 */
export async function refreshUser(): Promise<UserInfo> {
    clearUser();
    return await silentLogin();
}
```

---

### 2.3 调用时机

在 `app.ts` 的 `onLaunch` 中触发登录：

```typescript
// app.ts
import { getUser } from './utils/auth';

App({
    onLaunch() {
        // 初始化云开发
        wx.cloud.init({ env: 'your-env-id' });

        // 静默登录（不阻塞页面渲染）
        getUser().catch((err) => {
            console.error('静默登录失败', err);
        });
    },
});
```

**注意**：登录是异步的，不阻塞页面渲染。页面中需要用户数据时通过 `await getUser()` 获取，如果登录已完成会立即返回内存数据。

---

### 2.4 缓存过期策略

| 策略       | 说明                                      |
| ---------- | ----------------------------------------- |
| 有效期     | 7 天                                      |
| 过期后行为 | 下次 `getUser()` 时自动触发静默登录       |
| 过期目的   | 定期刷新 `lastActiveAt`，保持活跃数据准确 |
| 强制刷新   | 调用 `refreshUser()` 可随时强制重新登录   |

---

## 三、昵称与头像授权（后续实现）

静默登录不获取用户昵称和头像。当需要展示或使用这些信息时（如个人中心页），引导用户主动填写：

```typescript
// 使用微信头像昵称填写能力（基础库 2.21.2+）
// 在 wxml 中使用 <button open-type="chooseAvatar"> 获取头像
// 使用 <input type="nickname"> 获取昵称

export async function updateProfile(
    nickName: string,
    avatarUrl: string,
): Promise<void> {
    const { result } = await wx.cloud.callFunction({
        name: 'userLogin',
        data: {
            action: 'updateProfile',
            nickName,
            avatarUrl,
        },
    });

    if (result.code === 0) {
        // 更新本地缓存
        const user = await getUser();
        user.nickName = nickName;
        user.avatarUrl = avatarUrl;
        saveToStorage(user);
    }
}
```

> 注：微信已废弃 `wx.getUserProfile` 和 `wx.getUserInfo` 获取真实用户信息的能力，现在只能通过头像昵称填写组件让用户主动填写。

---

## 四、云函数目录结构

```
cloudfunctions/
└── userLogin/
    ├── index.js          ← 入口，支持 action 路由
    ├── package.json
    └── config.json       ← 云函数配置
```

若后续 `updateProfile` 等操作较多，可在同一个云函数内通过 `event.action` 路由：

```javascript
exports.main = async (event, context) => {
    const { action } = event;

    switch (action) {
        case 'updateProfile':
            return await handleUpdateProfile(event, context);
        default:
            return await handleSilentLogin(event, context);
    }
};
```

---

## 五、安全考虑

| 项目         | 措施                                                      |
| ------------ | --------------------------------------------------------- |
| openid 来源  | 仅从 `cloud.getWXContext()` 获取，不信任前端传入          |
| unionid      | 服务端获取，不暴露给前端                                  |
| Storage 数据 | 不存储敏感信息（openid 不算高敏感，但也不主动展示给用户） |
| 接口幂等     | upsert 逻辑天然幂等，重复调用不会创建多条记录             |

---

## 六、与现有架构的关系

- **数据库**：使用 `users` 集合，字段设计见 [小程序云开发方案和数据库设计.md](./小程序云开发方案和数据库设计.md) §3.5
- **其他云函数**：需要用户身份的云函数（如收藏、下载记录）通过 `cloud.getWXContext().OPENID` 查询 `users` 集合获取 `_id`，作为 `userId` 关联
- **前端**：各页面通过 `getUser()` 获取用户数据，无需关心登录细节