35 KiB

Raw Blame History

用户系统功能文档

1. 功能概述

用户系统是 oak-general-business 的核心功能模块，提供了完整的用户管理、身份认证、权限控制解决方案。该系统支持多种登录方式，包括传统的密码登录、短信验证码登录、邮箱登录，以及现代化的微信登录等第三方授权登录。

1.1 核心价值

统一身份管理: 提供跨平台、跨应用的统一用户身份管理
多元化登录: 支持密码、短信、邮箱、微信等多种登录方式
安全可靠: 内置密码加密、验证码验证、令牌管理等安全机制
用户状态管理: 支持用户激活、禁用、合并等完整的生命周期管理
身份认证: 支持实名认证功能，包括身份证验证等

1.2 应用场景

Web应用: 网站用户注册、登录、个人信息管理
移动应用: 原生App的用户系统集成
微信生态: 小程序、公众号、H5页面的微信登录
多平台统一: 跨平台用户身份同步和管理
企业应用: 内部系统的用户权限管理

1.3 与其他功能模块的关系

令牌管理: 用户登录后生成和管理访问令牌
应用管理: 与应用配置紧密集成，支持不同应用的登录方式配置
微信生态: 集成微信登录、用户绑定等功能
会话消息: 为用户提供消息推送和会话管理
文件管理: 用户头像、实名认证文件等存储管理

参考代码路径:

核心实体：src/entities/User.ts, src/entities/Mobile.ts, src/entities/Email.ts, src/entities/LoginName.ts, src/entities/Passport.ts, src/entities/ChangePasswordTemp.ts
业务逻辑：src/aspects/user.ts, src/triggers/user.ts, src/triggers/passport.ts
前端组件：src/components/user/, src/components/passport/
功能特性：src/features/token.ts

2. 实体定义详解

用户系统包含以下核心实体，每个实体都有明确的职责和关系。

2.1 User（用户）实体

位置: src/entities/User.ts

User实体是整个用户系统的核心，扩展了oak-domain基础User实体，提供了完整的用户信息管理。

字段定义

字段名	类型	说明	是否必需
`name`	`String`	用户真实姓名	否
`nickname`	`String`	用户昵称	否
`passwordSha1`	`Text`	SHA1加密的密码	否
`birth`	`Datetime`	生日	否
`gender`	`'male' \| 'female'`	性别	否
`idCardType`	`'ID-Card' \| 'passport' \| 'Mainland-passport'`	证件类型	否
`idNumber`	`String<32>`	证件号码	否
`files`	`Array<ExtraFile>`	关联文件	是
`codes`	`Array<WechatQrCode>`	微信分享二维码	是
`isRoot`	`Boolean`	是否超级用户	否
`addresses`	`Address[]`	收货地址列表	否
`hasPassword`	`Boolean`	是否设置了密码	否
`verifyPasswordAt`	`Datetime`	最近验证密码时间	否

用户状态（UserState）

状态	说明	颜色
`shadow`	未激活（新注册用户默认状态）	#D3D3D3
`normal`	正常状态	#0000FF
`disabled`	已禁用	#FF0000
`merged`	已被合并到其他用户	#9A9A9A

用户操作（UserAction）

操作	说明	状态转换
`activate`	激活用户	`shadow` → `normal`
`disable`	禁用用户	`normal/shadow` → `disabled`
`enable`	启用用户	`disabled` → `normal`
`mergeTo`	合并到其他用户	`normal/shadow` → `merged`
`mergeFrom`	接受其他用户合并	`normal` → `normal`

实名认证状态（IdState）

状态	说明	颜色
`unverified`	未认证	#FF0000
`verifying`	认证中	#EEE8AA
`verified`	已认证	#0000FF

实名认证操作（IdAction）

操作	说明	状态转换
`verify`	提交认证	`unverified` → `verifying`
`accept`	通过认证	`unverified/verifying` → `verified`
`reject`	拒绝认证	`verifying/verified` → `unverified`

2.2 Mobile（手机号）实体

位置: src/entities/Mobile.ts

管理用户手机号信息，支持一个用户绑定多个手机号。

字段定义

字段名	类型	说明	是否必需
`mobile`	`String<16>`	手机号码	是
`user`	`User`	关联用户	否
`tokens`	`Array<Token>`	相关令牌	是

状态和操作

采用标准的Able模式：

状态: enabled（可用）、disabled（禁用）
操作: enable（启用）、disable（禁用）

2.3 Email（邮箱）实体

位置: src/entities/Email.ts

管理用户邮箱信息，支持邮箱登录和验证。

字段定义

字段名	类型	说明	是否必需
`email`	`String<32>`	邮箱地址	是
`user`	`User`	关联用户	是
`tokens`	`Array<Token>`	相关令牌	是

状态和操作

采用标准的Able模式：

状态: enabled（可用）、disabled（禁用）
操作: enable（启用）、disable（禁用）

2.4 LoginName（登录账号）实体

位置: src/entities/LoginName.ts

管理用户自定义登录账号，支持用户名密码登录。

字段定义

字段名	类型	说明	是否必需
`name`	`String<32>`	登录账号名	是
`user`	`User`	关联用户	是
`tokens`	`Array<Token>`	相关令牌	是

状态和操作

采用标准的Able模式：

状态: enabled（可用）、disabled（禁用）
操作: enable（启用）、disable（禁用）

2.5 Passport（登录方式）实体

位置: src/entities/Passport.ts

定义系统支持的登录方式及其配置。

字段定义

字段名	类型	说明	是否必需
`system`	`System`	所属系统	是
`type`	`Type`	登录方式类型	是
`config`	`SmsConfig \| EmailConfig \| PfwConfig \| MfwConfig \| PwdConfig`	登录方式配置	否
`enabled`	`Boolean`	是否启用	是

登录方式类型（Type）

类型	说明	颜色
`password`	密码登录	#7DC9E7
`sms`	短信验证码登录	#D3DDE6
`email`	邮箱验证码登录	#F95A37
`wechatWeb`	微信网站登录	#F298A6
`wechatMp`	小程序登录	#ADDCCA
`wechatPublic`	公众号登录	#D3ADF7
`wechatPublicForWeb`	公众号授权网页登录	#C0A27C
`wechatMpForWeb`	小程序授权网页登录	#FDC454
`wechatNative`	微信APP授权登录	#C0A27C

配置类型

短信配置（SmsConfig）:

mockSend?: boolean - 是否模拟发送
defaultOrigin?: 'ali' | 'tencent' | 'ctyun' - 默认渠道
templateName?: string - 验证码模板名
codeDuration?: number - 验证码有效时间（分钟）
digit?: number - 验证码位数（4-8位）

邮箱配置（EmailConfig）:

mockSend?: boolean - 是否模拟发送
account: string - 发送邮箱账号
subject: string - 邮件主题
text?: string - 邮件文本内容
html?: string - 邮件HTML内容
codeDuration?: number - 验证码有效时间（分钟）
digit?: number - 验证码位数（4-8位）
emailSuffixes?: string[] - 允许的邮箱后缀

密码配置（PwdConfig）:

mode: 'all' | 'plain' | 'sha1' - 密码存储模式
min: number - 最小长度
max: number - 最大长度
verify?: boolean - 是否开启正则校验
regexs?: string[] - 校验正则表达式
tip?: string - 登录提示语

2.6 ChangePasswordTemp（密码修改记录）实体

位置: src/entities/ChangePasswordTemp.ts

记录用户密码修改历史，用于安全审计和防护。

字段定义

字段名	类型	说明	是否必需
`user`	`User`	关联用户	是
`prevPassword`	`String<32>`	原密码（明文）	否
`newPassword`	`String<32>`	新密码（明文）	否
`prevPasswordSha1`	`Text`	原密码SHA1加密	否
`newPasswordSha1`	`Text`	新密码SHA1加密	否
`result`	`'success' \| 'fail'`	修改结果	是

2.7 实体关系图

erDiagram
    User ||--o{ Mobile : 绑定
    User ||--o{ Email : 绑定
    User ||--o{ LoginName : 绑定
    User ||--o{ Token : 生成
    User ||--o{ ChangePasswordTemp : 记录
    User ||--o{ ExtraFile : 文件
    User ||--o{ WechatQrCode : 二维码
    User ||--o{ Address : 地址
    
    Mobile ||--o{ Token : 生成
    Email ||--o{ Token : 生成
    LoginName ||--o{ Token : 生成
    
    System ||--o{ Passport : 配置
    Application ||--o{ Token : 应用范围
    
    User {
        string name
        string nickname
        string passwordSha1
        datetime birth
        string gender
        string idCardType
        string idNumber
        boolean isRoot
        boolean hasPassword
        datetime verifyPasswordAt
        string userState
        string idState
    }
    
    Mobile {
        string mobile
        string ableState
    }
    
    Email {
        string email
        string ableState
    }
    
    LoginName {
        string name
        string ableState
    }
    
    Passport {
        string type
        object config
        boolean enabled
    }
    
    Token {
        string entity
        string entityId
        string value
        datetime refreshedAt
        datetime disablesAt
        string ableState
    }
    
    ChangePasswordTemp {
        string prevPassword
        string newPassword
        string prevPasswordSha1
        string newPasswordSha1
        string result
    }

参考代码路径: src/entities/User.ts, src/entities/Mobile.ts, src/entities/Email.ts, src/entities/LoginName.ts, src/entities/Passport.ts, src/entities/ChangePasswordTemp.ts

3. 业务逻辑说明

用户系统的业务逻辑主要通过Aspect（前端代理层）、Trigger（触发器）和Feature（前端功能层）来实现。

3.1 UserAspect（用户业务逻辑层）

位置: src/aspects/user.ts

UserAspect提供了用户管理的核心业务方法，主要包括用户合并和密码管理功能。

主要方法

1. mergeUser() - 用户合并

用户合并是重要的业务功能，可以将多个用户账号合并为一个。

async function mergeUser(params: {
    from: string,        // 源用户ID
    to: string,          // 目标用户ID  
    mergeMobile?: true,  // 是否合并手机号
    mergeEmail?: true,   // 是否合并邮箱
    mergeWechatUser?: true, // 是否合并微信用户
}, context, innerLogic?: boolean)

业务流程：

验证操作权限（仅root用户可执行）
禁用源用户的所有令牌
将源用户状态更新为"已合并"，并指向目标用户
根据参数选择性合并手机号、邮箱、微信用户信息

2. updateUserPassword() - 密码更新

支持通过原密码或手机验证码来更新用户密码。

async function updateUserPassword(params: {
    userId: string,      // 用户ID
    prevPassword?: string, // 原密码
    captcha?: string,    // 验证码
    mobile?: string,     // 手机号
    newPassword: string, // 新密码
}, context, innerLogic?: boolean)

业务流程：

获取密码配置（存储模式、长度限制等）
验证修改频率限制（每天最多5次失败）
验证原密码或手机验证码
根据配置模式加密新密码
更新用户密码并记录修改历史

3. getChangePasswordChannels() - 获取修改密码渠道

查询用户可用的密码修改方式。

async function getChangePasswordChannels(params: { userId: string }, context)

返回可用渠道列表：['mobile', 'password']

3.2 用户触发器（User Triggers）

位置: src/triggers/user.ts

用户触发器在用户数据变更时自动执行业务逻辑。

主要触发器

1. 用户创建前置触发器

初始状态设置: 新用户默认状态为shadow（未激活）
密码处理: 设置hasPassword标志和verifyPasswordAt时间
昵称生成: 如果未提供昵称，自动生成随机昵称
系统关联: 自动创建用户与系统的关联关系

2. 超级用户设置触发器

首个用户: 系统中第一个创建的用户自动设为超级用户
权限控制: 确保系统至少有一个超级用户

3. 用户激活后置触发器

寄生模式清理: 用户激活时，自动使所有相关的寄生记录失效
令牌管理: 禁用寄生相关的令牌

4. 实名认证触发器

自动审核: 根据系统配置决定是否需要人工审核
状态流转: 未配置人工审核时，自动通过认证

3.3 登录方式触发器（Passport Triggers）

位置: src/triggers/passport.ts

管理登录方式的生命周期。

主要触发器

1. 登录方式禁用触发器

级联删除: 禁用登录方式时，自动删除相关的应用登录方式配置

2. 登录方式删除前置触发器

清理关联: 删除登录方式前，清理所有相关的应用配置

3.4 Token Feature（令牌功能层）

位置: src/features/token.ts

Token Feature提供了完整的用户认证和登录功能。

主要方法

登录方法：

loginByMobile() - 手机号登录
loginByEmail() - 邮箱登录
loginByAccount() - 账号密码登录
loginWechatMp() - 微信小程序登录
loginWechat() - 微信网页登录
loginByOAuth() - OAuth第三方登录

绑定方法：

bindByMobile() - 绑定手机号
bindByEmail() - 绑定邮箱

令牌管理：

get() - 获取当前令牌
refresh() - 刷新令牌
logout() - 退出登录

3.5 核心业务流程图

用户注册登录流程

flowchart TD
    A[用户发起登录] --> B{选择登录方式}
    
    B -->|短信登录| C[输入手机号]
    B -->|邮箱登录| D[输入邮箱]
    B -->|密码登录| E[输入账号密码]
    B -->|微信登录| F[微信授权]
    
    C --> C1[发送验证码]
    C1 --> C2[输入验证码]
    C2 --> G{验证码正确?}
    
    D --> D1[发送验证码]
    D1 --> D2[输入验证码]
    D2 --> G
    
    E --> H{账号密码正确?}
    H -->|是| I[生成Token]
    H -->|否| J[返回错误]
    
    F --> F1[获取微信code]
    F1 --> F2[验证微信授权]
    F2 --> G
    
    G -->|是| K{用户是否存在?}
    G -->|否| J
    
    K -->|存在| L{用户状态检查}
    K -->|不存在| M[创建新用户]
    
    M --> M1[设置初始状态为shadow]
    M1 --> M2[生成随机昵称]
    M2 --> M3[创建系统关联]
    M3 --> I
    
    L -->|正常/shadow| I
    L -->|禁用| N[返回账号禁用错误]
    L -->|已合并| O[重定向到目标用户]
    
    I --> P[保存Token到本地]
    P --> Q[发布登录事件]
    Q --> R[检查是否需要设置密码]
    R --> S[登录成功]

用户状态转换流程

stateDiagram-v2
    [*] --> shadow: 新用户注册
    
    shadow --> normal: activate(激活)
    shadow --> disabled: disable(禁用)
    shadow --> merged: mergeTo(合并到其他用户)
    
    normal --> disabled: disable(禁用)
    normal --> merged: mergeTo(合并到其他用户)
    normal --> normal: mergeFrom(接受其他用户合并)
    
    disabled --> normal: enable(启用)
    
    merged --> [*]: 最终状态
    
    note right of shadow
        未激活状态
        新注册用户默认状态
    end note
    
    note right of normal
        正常状态
        可以正常使用所有功能
    end note
    
    note right of disabled
        禁用状态
        无法登录和使用
    end note
    
    note right of merged
        已合并状态
        用户被合并到其他账号
    end note

实名认证流程

stateDiagram-v2
    [*] --> unverified: 初始状态
    
    unverified --> verifying: verify(提交认证)
    verifying --> verified: accept(通过认证)
    verifying --> unverified: reject(拒绝认证)
    verified --> unverified: reject(撤销认证)
    
    note right of unverified
        未认证状态
        用户未提交认证信息
    end note
    
    note right of verifying
        认证中状态
        已提交，等待审核
    end note
    
    note right of verified
        已认证状态
        通过实名认证
    end note

密码修改安全流程

sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as UserAspect
    participant DB as 数据库
    participant SMS as 短信服务
    
    U->>F: 请求修改密码
    F->>A: getChangePasswordChannels()
    A->>DB: 查询用户手机号和密码状态
    DB-->>A: 返回可用渠道
    A-->>F: 返回['mobile', 'password']
    
    alt 原密码验证
        U->>F: 输入原密码+新密码
        F->>A: updateUserPassword(prevPassword)
        A->>DB: 查询当天失败次数
        DB-->>A: 返回失败次数
        A->>A: 检查是否超过5次限制
        A->>DB: 验证原密码
        alt 密码正确
            A->>DB: 更新新密码
            A->>DB: 记录成功日志
            A-->>F: 返回成功
        else 密码错误
            A->>DB: 记录失败日志
            A-->>F: 返回错误和尝试次数
        end
    else 手机验证
        U->>F: 输入手机号
        F->>SMS: 发送验证码
        U->>F: 输入验证码+新密码
        F->>A: updateUserPassword(mobile, captcha)
        A->>DB: 验证验证码
        alt 验证码正确
            A->>DB: 更新新密码
            A->>DB: 记录成功日志
            A-->>F: 返回成功
        else 验证码错误
            A-->>F: 返回验证码错误
        end
    end

3.6 业务规则和约束

安全规则

密码修改限制: 每天最多允许5次密码修改失败
权限控制: 用户合并操作仅限超级用户执行
状态约束: 已禁用用户无法登录，已合并用户自动重定向

数据约束

唯一性约束: 手机号、邮箱、登录账号在系统内唯一
状态一致性: 用户状态变更会触发相关数据的级联更新
令牌关联: 用户状态变更时，相关令牌自动失效

业务约束

首用户特权: 系统第一个用户自动获得超级用户权限
激活清理: 用户激活时自动清理寄生模式记录
合并规则: 用户合并后，源用户的所有关联数据可选择性转移

参考代码路径: src/aspects/user.ts, src/triggers/user.ts, src/triggers/passport.ts, src/features/token.ts

4. 前端组件使用

用户系统提供了丰富的前端组件，支持Web PC、Web Mobile、小程序等多个平台。

4.1 组件列表

User相关组件

组件路径	组件名称	导入路径	支持平台
`src/components/user/login/`	用户登录组件	`oak-general-business/es/components/user/login`	Web PC, Web Mobile, 小程序
`src/components/user/authenticate/`	用户实名认证组件	`oak-general-business/es/components/user/authenticate`	Web PC, Web Mobile, 小程序
`src/components/user/info/`	用户信息组件	`oak-general-business/es/components/user/info`	Web PC, Web Mobile, 小程序
`src/components/user/manage/`	用户管理组件	`oak-general-business/es/components/user/manage`	Web PC, Web Mobile, 小程序
`src/components/user/password/update/`	密码修改组件	`oak-general-business/es/components/user/password/update`	Web PC, Web Mobile, 小程序
`src/components/user/password/verify/`	密码验证组件	`oak-general-business/es/components/user/password/verify`	Web PC, Web Mobile, 小程序

Passport相关组件

组件路径	组件名称	导入路径	支持平台
`src/components/passport/`	登录方式管理组件	`oak-general-business/es/components/passport`	Web PC
`src/components/passport/sms/`	短信登录组件	`oak-general-business/es/components/passport/sms`	Web PC, Web Mobile, 小程序
`src/components/passport/email/`	邮箱登录组件	`oak-general-business/es/components/passport/email`	Web PC, Web Mobile, 小程序
`src/components/passport/password/`	密码登录组件	`oak-general-business/es/components/passport/password`	Web PC, Web Mobile, 小程序
`src/components/passport/wechatMp/`	微信小程序登录组件	`oak-general-business/es/components/passport/wechatMp`	小程序
`src/components/passport/wechatPublic/`	微信公众号登录组件	`oak-general-business/es/components/passport/wechatPublic`	Web Mobile
`src/components/passport/wechatMpForWeb/`	小程序授权网页登录组件	`oak-general-business/es/components/passport/wechatMpForWeb`	Web PC
`src/components/passport/wechatPublicForWeb/`	公众号授权网页登录组件	`oak-general-business/es/components/passport/wechatPublicForWeb`	Web PC

4.2 核心组件详解

4.2.1 UserLogin 组件

导入路径: import UserLogin from "oak-general-business/es/components/user/login"

Props接口:

interface UserLoginProps {
    onlyCaptcha?: boolean;     // 仅验证码登录
    onlyPassword?: boolean;    // 仅密码登录
    disabled?: string;         // 禁用状态描述
    redirectUri?: string;      // 微信登录回调地址
    url?: string;             // 登录成功后跳转地址
    callback?: () => void;     // 登录成功回调函数
}

使用示例:

import UserLogin from "oak-general-business/es/components/user/login";

// 标准登录组件
<UserLogin 
    callback={() => console.log('登录成功')}
    url="/dashboard"
/>

// 仅短信验证码登录
<UserLogin 
    onlyCaptcha={true}
    callback={() => console.log('验证码登录成功')}
/>

// 仅密码登录
<UserLogin 
    onlyPassword={true}
    callback={() => console.log('密码登录成功')}
/>

功能特性:

自动检测应用配置的登录方式
支持多种登录方式切换
内置登录协议确认
自动保存登录状态偏好
支持微信登录二维码显示

4.2.2 UserAuthenticate 组件

导入路径: import UserAuthenticate from "oak-general-business/es/components/user/authenticate"

用于用户实名认证，支持身份证认证。

主要功能:

身份证号码输入和验证
身份证照片上传
认证状态显示
认证结果反馈

4.2.3 Passport 组件

导入路径: import Passport from "oak-general-business/es/components/passport"

Props接口:

interface PassportProps {
    systemId: string;         // 系统ID
    systemName: string;       // 系统名称
}

使用示例:

import Passport from "oak-general-business/es/components/passport";

<Passport 
    systemId="your-system-id"
    systemName="您的系统名称"
/>

功能特性:

登录方式列表管理
登录方式配置编辑
支持短信、邮箱、密码、微信等配置
实时配置验证和提示

4.2.4 PasswordUpdate 组件

导入路径: import PasswordUpdate from "oak-general-business/es/components/user/password/update"

支持通过原密码或手机验证码修改密码。

主要功能:

检测可用的密码修改方式
原密码验证
手机验证码验证
密码强度检查
修改记录追踪

4.3 组件组合使用

完整的用户注册登录流程

import React, { useState } from 'react';
import UserLogin from "oak-general-business/es/components/user/login";
import UserAuthenticate from "oak-general-business/es/components/user/authenticate";
import PasswordUpdate from "oak-general-business/es/components/user/password/update";

function UserSystem() {
    const [currentStep, setCurrentStep] = useState('login');
    const [user, setUser] = useState(null);

    const handleLoginSuccess = (userData) => {
        setUser(userData);
        // 检查是否需要实名认证
        if (!userData.idState || userData.idState === 'unverified') {
            setCurrentStep('authenticate');
        } else if (!userData.hasPassword) {
            setCurrentStep('setPassword');
        } else {
            setCurrentStep('dashboard');
        }
    };

    return (
        <div className="user-system">
            {currentStep === 'login' && (
                <UserLogin 
                    callback={handleLoginSuccess}
                    url="/dashboard"
                />
            )}
            
            {currentStep === 'authenticate' && (
                <UserAuthenticate 
                    onSuccess={() => setCurrentStep('dashboard')}
                />
            )}
            
            {currentStep === 'setPassword' && (
                <PasswordUpdate 
                    onSuccess={() => setCurrentStep('dashboard')}
                />
            )}
            
            {currentStep === 'dashboard' && (
                <div>欢迎进入系统！</div>
            )}
        </div>
    );
}

管理后台登录方式配置

import React from 'react';
import Passport from "oak-general-business/es/components/passport";

function SystemConfig() {
    return (
        <div className="system-config">
            <h2>登录方式配置</h2>
            <Passport 
                systemId="your-system-id"
                systemName="您的系统"
            />
        </div>
    );
}

4.4 平台适配说明

Web PC平台

支持完整的登录方式选择界面
支持微信扫码登录
提供管理后台登录方式配置

Web Mobile平台

针对移动端优化的界面布局
支持微信公众号内登录
触摸友好的交互设计

小程序平台

使用小程序原生组件
支持微信小程序登录
遵循小程序设计规范

参考代码路径: src/components/user/, src/components/passport/, src/components/login/

5. 接入指南

5.1 配置要求

系统配置（System）

在使用用户系统前，需要创建系统配置：

{
    id: "your-system-id",
    name: "您的系统名称",
    config: {
        App: {
            needManualVerification: false  // 是否需要人工审核实名认证
        }
    }
}

应用配置（Application）

不同类型的应用需要不同的配置：

Web应用配置:

{
    type: "web",
    name: "您的Web应用",
    systemId: "your-system-id",
    config: {
        wechat: {
            appId: "微信开放平台AppID",
            domain: "授权回调域名"
        }
    }
}

微信小程序配置:

{
    type: "wechatMp",
    name: "您的小程序",
    systemId: "your-system-id", 
    config: {
        appId: "小程序AppID",
        appSecret: "小程序AppSecret"
    }
}

微信公众号配置:

{
    type: "wechatPublic",
    name: "您的公众号",
    systemId: "your-system-id",
    config: {
        appId: "公众号AppID",
        appSecret: "公众号AppSecret",
        isService: true  // 是否为服务号
    }
}

登录方式配置（Passport）

每个系统需要配置支持的登录方式：

密码登录配置:

{
    systemId: "your-system-id",
    type: "password",
    enabled: true,
    config: {
        mode: "all",        // all: 明文+密文, plain: 仅明文, sha1: 仅密文
        min: 8,             // 最小长度
        max: 24,            // 最大长度
        verify: true,       // 开启正则校验
        regexs: [
            "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)[a-zA-Z\\d]{8,}$"
        ],
        tip: "密码需包含大小写字母和数字，至少8位"
    }
}

短信登录配置:

{
    systemId: "your-system-id",
    type: "sms",
    enabled: true,
    config: {
        mockSend: false,           // 生产环境设为false
        defaultOrigin: "ali",      // 默认短信渠道: ali/tencent/ctyun
        templateName: "login",     // 短信模板名称
        codeDuration: 5,           // 验证码有效期（分钟）
        digit: 6                   // 验证码位数
    }
}

邮箱登录配置:

{
    systemId: "your-system-id",
    type: "email",
    enabled: true,
    config: {
        mockSend: false,
        account: "noreply@yourcompany.com",
        subject: "登录验证码",
        html: "您的验证码是：${code}，有效期5分钟。",
        codeDuration: 5,
        digit: 6,
        emailSuffixes: ["gmail.com", "qq.com", "163.com"]  // 允许的邮箱后缀
    }
}

5.2 必需的页面和路由

基础页面

登录页面 (/login)

import UserLogin from "oak-general-business/es/components/user/login";

function LoginPage() {
    return (
        <div className="login-page">
            <UserLogin 
                callback={() => window.location.href = '/dashboard'}
                url="/dashboard"
            />
        </div>
    );
}

用户信息页面 (/profile)

import UserInfo from "oak-general-business/es/components/user/info";

function ProfilePage() {
    return (
        <div className="profile-page">
            <UserInfo />
        </div>
    );
}

实名认证页面 (/authenticate)

import UserAuthenticate from "oak-general-business/es/components/user/authenticate";

function AuthenticatePage() {
    return (
        <div className="authenticate-page">
            <UserAuthenticate 
                onSuccess={() => window.location.href = '/profile'}
            />
        </div>
    );
}

微信相关页面

微信登录回调页面 (/wechat/callback)

// 处理微信网页授权回调
import { useEffect } from 'react';

function WechatCallback() {
    useEffect(() => {
        const urlParams = new URLSearchParams(window.location.search);
        const code = urlParams.get('code');
        const state = urlParams.get('state');
        
        if (code && state) {
            // 调用登录API
            this.features.token.loginByOAuth(code, state)
                .then(() => {
                    window.location.href = '/dashboard';
                })
                .catch(err => {
                    console.error('微信登录失败:', err);
                });
        }
    }, []);

    return <div>正在处理微信登录...</div>;
}

参考代码路径: src/entities/System.ts, src/entities/Application.ts, src/entities/Passport.ts

6. API接口说明

用户系统通过Feature层提供前端调用方法，通过Aspect提供服务端业务逻辑。

6.1 Token Feature API

位置: src/features/token.ts

Token Feature是前端使用最多的API，提供完整的用户认证功能。

登录相关API

手机号登录:

async loginByMobile(
    mobile: string,          // 手机号
    captcha: string,         // 验证码
    disableRegister?: boolean // 禁止自动注册
): Promise<void>

邮箱登录:

async loginByEmail(
    email: string,           // 邮箱地址
    captcha: string,         // 验证码
    disableRegister?: boolean // 禁止自动注册
): Promise<void>

账号密码登录:

async loginByAccount(
    account: string,         // 登录账号
    password: string         // 密码
): Promise<void>

微信小程序登录:

async loginWechatMp(): Promise<void>

微信网页登录:

async loginWechat(
    code: string,                    // 微信授权码
    params?: { wechatLoginId?: string } // 登录ID（可选）
): Promise<void>

OAuth第三方登录:

async loginByOAuth(
    code: string,            // 授权码
    state: string            // 状态参数
): Promise<void>

绑定相关API

绑定手机号:

async bindByMobile(
    mobile: string,          // 手机号
    captcha?: string         // 验证码（可选）
): Promise<void>

绑定邮箱:

async bindByEmail(
    email: string,           // 邮箱地址
    captcha?: string         // 验证码（可选）
): Promise<void>

令牌管理API

获取当前令牌:

async get(): Promise<TokenSchema | null>

刷新令牌:

async refresh(): Promise<void>

退出登录:

async logout(): Promise<void>

清除本地令牌:

async clear(): Promise<void>

6.2 事件和回调

Feature事件

Token Feature会发布以下事件：

// 登录成功事件
features.token.subscribe('login', (token) => {
    console.log('用户登录:', token.user);
    // 可以在这里执行登录后的逻辑
});

// 退出登录事件
features.token.subscribe('logout', () => {
    console.log('用户已退出');
    // 清理用户相关数据
});

// 令牌刷新事件
features.token.subscribe('refresh', (newToken) => {
    console.log('令牌已刷新:', newToken);
});

组件回调

// 登录组件回调
<UserLogin 
    callback={(user) => {
        console.log('登录成功回调:', user);
        // 执行登录后逻辑
        window.location.href = '/dashboard';
    }}
/>

// 认证组件回调
<UserAuthenticate 
    onSuccess={() => {
        console.log('认证成功');
        // 认证成功后的处理
    }}
    onFail={(error) => {
        console.log('认证失败:', error);
        // 认证失败后的处理
    }}
/>

参考代码路径: src/features/token.ts, src/aspects/user.ts

7. 未来规划

7.1 功能增强方向

多因子认证（MFA）

计划时间: v6.0
功能描述: 支持TOTP、短信、邮箱等多种二次验证方式
应用场景: 企业级安全要求、金融系统

生物识别登录

计划时间: v6.5
功能描述: 支持指纹、面部识别登录
应用场景: 移动应用、高安全性要求场景

联邦身份认证

计划时间: v7.0
功能描述: 支持SAML、OpenID Connect等标准协议
应用场景: 企业单点登录（SSO）、多系统集成

智能风控

计划时间: v6.2
功能描述: 基于设备指纹、行为分析的风险控制
应用场景: 防止恶意登录、账号安全保护

7.2 已知缺陷和待修复问题

高优先级

用户合并功能不完善
- 问题: 当前用户合并只支持手机号、邮箱、微信用户，其他关联数据需要手动处理
- 影响: 数据迁移不完整，可能导致数据不一致
密码修改频率限制过于严格
- 问题: 每天5次失败限制可能影响正常用户使用
- 影响: 用户体验不佳

中等优先级

实名认证流程单一
- 问题: 目前仅支持身份证认证，缺少护照、港澳台证件的详细验证
- 影响: 限制了用户群体覆盖
微信登录状态同步延迟
- 问题: 微信用户信息更新时，系统同步存在延迟
- 影响: 用户信息可能不是最新的

低优先级

组件平台适配不一致
- 问题: 部分组件在不同平台表现不一致
- 影响: 用户体验略有差异
- 修复计划: v6.1版本统一平台适配标准

文档版本: v1.0
最后更新: 2025年10月25日
维护团队: oak-general-business开发团队

35 KiB Raw Blame History Unescape Escape

用户系统功能文档

1. 功能概述

1.1 核心价值

1.2 应用场景

1.3 与其他功能模块的关系

2. 实体定义详解

2.1 User（用户）实体

字段定义

用户状态（UserState）

用户操作（UserAction）

实名认证状态（IdState）

实名认证操作（IdAction）

2.2 Mobile（手机号）实体

字段定义

状态和操作

2.3 Email（邮箱）实体

字段定义

状态和操作

2.4 LoginName（登录账号）实体

字段定义

状态和操作

2.5 Passport（登录方式）实体

字段定义

登录方式类型（Type）

配置类型

2.6 ChangePasswordTemp（密码修改记录）实体

字段定义

2.7 实体关系图

3. 业务逻辑说明

3.1 UserAspect（用户业务逻辑层）

主要方法

3.2 用户触发器（User Triggers）

主要触发器

3.3 登录方式触发器（Passport Triggers）

主要触发器

3.4 Token Feature（令牌功能层）

主要方法

3.5 核心业务流程图

用户注册登录流程

用户状态转换流程

实名认证流程

密码修改安全流程

3.6 业务规则和约束

安全规则

数据约束

业务约束

4. 前端组件使用

4.1 组件列表

User相关组件

Passport相关组件

4.2 核心组件详解

4.2.1 UserLogin 组件

4.2.2 UserAuthenticate 组件

4.2.3 Passport 组件

4.2.4 PasswordUpdate 组件

4.3 组件组合使用

完整的用户注册登录流程

管理后台登录方式配置

4.4 平台适配说明

Web PC平台

Web Mobile平台

小程序平台

5. 接入指南

5.1 配置要求

系统配置（System）

应用配置（Application）

登录方式配置（Passport）

5.2 必需的页面和路由

基础页面

微信相关页面

6. API接口说明

6.1 Token Feature API

登录相关API

绑定相关API

令牌管理API

6.2 事件和回调

Feature事件

组件回调

7. 未来规划

35 KiB

Raw Blame History