From 992cff1ef974dee5c39eafb88631556726a87a5b Mon Sep 17 00:00:00 2001 From: pqcqaq <905739777@qq.com> Date: Sun, 26 Oct 2025 11:04:46 +0800 Subject: [PATCH] =?UTF-8?q?=E7=94=A8=E6=88=B7=E7=B3=BB=E7=BB=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/genernal-business/users.md | 1299 ++++++++++++++++++++++++++++++++ 1 file changed, 1299 insertions(+) create mode 100644 src/genernal-business/users.md diff --git a/src/genernal-business/users.md b/src/genernal-business/users.md new file mode 100644 index 0000000..e832b06 --- /dev/null +++ b/src/genernal-business/users.md @@ -0,0 +1,1299 @@ +# 用户系统功能文档 + +## 1. 功能概述 + +用户系统是 oak-general-business 的核心功能模块，提供了完整的用户管理、身份认证、权限控制解决方案。该系统支持多种登录方式，包括传统的密码登录、短信验证码登录、邮箱登录，以及现代化的微信登录等第三方授权登录。 + +### 1.1 核心价值 + +- **统一身份管理**: 提供跨平台、跨应用的统一用户身份管理 +- **多元化登录**: 支持密码、短信、邮箱、微信等多种登录方式 +- **安全可靠**: 内置密码加密、验证码验证、令牌管理等安全机制 +- **用户状态管理**: 支持用户激活、禁用、合并等完整的生命周期管理 +- **身份认证**: 支持实名认证功能，包括身份证验证等 + +### 1.2 应用场景 + +1. **Web应用**: 网站用户注册、登录、个人信息管理 +2. **移动应用**: 原生App的用户系统集成 +3. **微信生态**: 小程序、公众号、H5页面的微信登录 +4. **多平台统一**: 跨平台用户身份同步和管理 +5. **企业应用**: 内部系统的用户权限管理 + +### 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` | 关联文件 | 是 | +| `codes` | `Array` | 微信分享二维码 | 是 | +| `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` | 相关令牌 | 是 | + +#### 状态和操作 + +采用标准的Able模式： +- **状态**: `enabled`（可用）、`disabled`（禁用） +- **操作**: `enable`（启用）、`disable`（禁用） + +### 2.3 Email（邮箱）实体 + +**位置**: `src/entities/Email.ts` + +管理用户邮箱信息，支持邮箱登录和验证。 + +#### 字段定义 + +| 字段名 | 类型 | 说明 | 是否必需 | +|--------|------|------|----------| +| `email` | `String<32>` | 邮箱地址 | 是 | +| `user` | `User` | 关联用户 | 是 | +| `tokens` | `Array` | 相关令牌 | 是 | + +#### 状态和操作 + +采用标准的Able模式： +- **状态**: `enabled`（可用）、`disabled`（禁用） +- **操作**: `enable`（启用）、`disable`（禁用） + +### 2.4 LoginName（登录账号）实体 + +**位置**: `src/entities/LoginName.ts` + +管理用户自定义登录账号，支持用户名密码登录。 + +#### 字段定义 + +| 字段名 | 类型 | 说明 | 是否必需 | +|--------|------|------|----------| +| `name` | `String<32>` | 登录账号名 | 是 | +| `user` | `User` | 关联用户 | 是 | +| `tokens` | `Array` | 相关令牌 | 是 | + +#### 状态和操作 + +采用标准的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 实体关系图 + +```mermaid +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() - 用户合并** + +用户合并是重要的业务功能，可以将多个用户账号合并为一个。 + +```typescript +async function mergeUser(params: { + from: string, // 源用户ID + to: string, // 目标用户ID + mergeMobile?: true, // 是否合并手机号 + mergeEmail?: true, // 是否合并邮箱 + mergeWechatUser?: true, // 是否合并微信用户 +}, context, innerLogic?: boolean) +``` + +**业务流程**： +1. 验证操作权限（仅root用户可执行） +2. 禁用源用户的所有令牌 +3. 将源用户状态更新为"已合并"，并指向目标用户 +4. 根据参数选择性合并手机号、邮箱、微信用户信息 + +**2. updateUserPassword() - 密码更新** + +支持通过原密码或手机验证码来更新用户密码。 + +```typescript +async function updateUserPassword(params: { + userId: string, // 用户ID + prevPassword?: string, // 原密码 + captcha?: string, // 验证码 + mobile?: string, // 手机号 + newPassword: string, // 新密码 +}, context, innerLogic?: boolean) +``` + +**业务流程**： +1. 获取密码配置（存储模式、长度限制等） +2. 验证修改频率限制（每天最多5次失败） +3. 验证原密码或手机验证码 +4. 根据配置模式加密新密码 +5. 更新用户密码并记录修改历史 + +**3. getChangePasswordChannels() - 获取修改密码渠道** + +查询用户可用的密码修改方式。 + +```typescript +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 核心业务流程图 + +#### 用户注册登录流程 + +```mermaid +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[登录成功] +``` + +#### 用户状态转换流程 + +```mermaid +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 +``` + +#### 实名认证流程 + +```mermaid +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 +``` + +#### 密码修改安全流程 + +```mermaid +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 业务规则和约束 + +#### 安全规则 + +1. **密码修改限制**: 每天最多允许5次密码修改失败 +2. **权限控制**: 用户合并操作仅限超级用户执行 +3. **状态约束**: 已禁用用户无法登录，已合并用户自动重定向 + +#### 数据约束 + +1. **唯一性约束**: 手机号、邮箱、登录账号在系统内唯一 +2. **状态一致性**: 用户状态变更会触发相关数据的级联更新 +3. **令牌关联**: 用户状态变更时，相关令牌自动失效 + +#### 业务约束 + +1. **首用户特权**: 系统第一个用户自动获得超级用户权限 +2. **激活清理**: 用户激活时自动清理寄生模式记录 +3. **合并规则**: 用户合并后，源用户的所有关联数据可选择性转移 + +**参考代码路径**: `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接口**: + +```typescript +interface UserLoginProps { + onlyCaptcha?: boolean; // 仅验证码登录 + onlyPassword?: boolean; // 仅密码登录 + disabled?: string; // 禁用状态描述 + redirectUri?: string; // 微信登录回调地址 + url?: string; // 登录成功后跳转地址 + callback?: () => void; // 登录成功回调函数 +} +``` + +**使用示例**: + +```jsx +import UserLogin from "oak-general-business/es/components/user/login"; + +// 标准登录组件 + console.log('登录成功')} + url="/dashboard" +/> + +// 仅短信验证码登录 + console.log('验证码登录成功')} +/> + +// 仅密码登录 + 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接口**: + +```typescript +interface PassportProps { + systemId: string; // 系统ID + systemName: string; // 系统名称 +} +``` + +**使用示例**: + +```jsx +import Passport from "oak-general-business/es/components/passport"; + + +``` + +**功能特性**: + +- 登录方式列表管理 +- 登录方式配置编辑 +- 支持短信、邮箱、密码、微信等配置 +- 实时配置验证和提示 + +#### 4.2.4 PasswordUpdate 组件 + +**导入路径**: `import PasswordUpdate from "oak-general-business/es/components/user/password/update"` + +支持通过原密码或手机验证码修改密码。 + +**主要功能**: + +- 检测可用的密码修改方式 +- 原密码验证 +- 手机验证码验证 +- 密码强度检查 +- 修改记录追踪 + +### 4.3 组件组合使用 + +#### 完整的用户注册登录流程 + +```jsx +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 ( +
+ {currentStep === 'login' && ( + + )} + + {currentStep === 'authenticate' && ( + setCurrentStep('dashboard')} + /> + )} + + {currentStep === 'setPassword' && ( + setCurrentStep('dashboard')} + /> + )} + + {currentStep === 'dashboard' && ( +
欢迎进入系统！
+ )} +
+ ); +} +``` + +#### 管理后台登录方式配置 + +```jsx +import React from 'react'; +import Passport from "oak-general-business/es/components/passport"; + +function SystemConfig() { + return ( +
+

登录方式配置

+ +
+ ); +} +``` + +### 4.4 平台适配说明 + +#### Web PC平台 + +- 支持完整的登录方式选择界面 +- 支持微信扫码登录 +- 提供管理后台登录方式配置 + +#### Web Mobile平台 + +- 针对移动端优化的界面布局 +- 支持微信公众号内登录 +- 触摸友好的交互设计 + +#### 小程序平台 + +- 使用小程序原生组件 +- 支持微信小程序登录 +- 遵循小程序设计规范 + +**参考代码路径**: `src/components/user/`, `src/components/passport/`, `src/components/login/` + +## 5. 接入指南 + +### 5.1 配置要求 + +#### 系统配置（System） + +在使用用户系统前，需要创建系统配置： + +```typescript +{ + id: "your-system-id", + name: "您的系统名称", + config: { + App: { + needManualVerification: false // 是否需要人工审核实名认证 + } + } +} +``` + +#### 应用配置（Application） + +不同类型的应用需要不同的配置： + +**Web应用配置**: + +```typescript +{ + type: "web", + name: "您的Web应用", + systemId: "your-system-id", + config: { + wechat: { + appId: "微信开放平台AppID", + domain: "授权回调域名" + } + } +} +``` + +**微信小程序配置**: + +```typescript +{ + type: "wechatMp", + name: "您的小程序", + systemId: "your-system-id", + config: { + appId: "小程序AppID", + appSecret: "小程序AppSecret" + } +} +``` + +**微信公众号配置**: + +```typescript +{ + type: "wechatPublic", + name: "您的公众号", + systemId: "your-system-id", + config: { + appId: "公众号AppID", + appSecret: "公众号AppSecret", + isService: true // 是否为服务号 + } +} +``` + +#### 登录方式配置（Passport） + +每个系统需要配置支持的登录方式： + +**密码登录配置**: + +```typescript +{ + 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位" + } +} +``` + +**短信登录配置**: + +```typescript +{ + systemId: "your-system-id", + type: "sms", + enabled: true, + config: { + mockSend: false, // 生产环境设为false + defaultOrigin: "ali", // 默认短信渠道: ali/tencent/ctyun + templateName: "login", // 短信模板名称 + codeDuration: 5, // 验证码有效期（分钟） + digit: 6 // 验证码位数 + } +} +``` + +**邮箱登录配置**: + +```typescript +{ + 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 必需的页面和路由 + +#### 基础页面 + +1. **登录页面** (`/login`) +```jsx +import UserLogin from "oak-general-business/es/components/user/login"; + +function LoginPage() { + return ( +
+ window.location.href = '/dashboard'} + url="/dashboard" + /> +
+ ); +} +``` + +2. **用户信息页面** (`/profile`) +```jsx +import UserInfo from "oak-general-business/es/components/user/info"; + +function ProfilePage() { + return ( +
+ +
+ ); +} +``` + +3. **实名认证页面** (`/authenticate`) +```jsx +import UserAuthenticate from "oak-general-business/es/components/user/authenticate"; + +function AuthenticatePage() { + return ( +
+ window.location.href = '/profile'} + /> +
+ ); +} +``` + +#### 微信相关页面 + +1. **微信登录回调页面** (`/wechat/callback`) +```jsx +// 处理微信网页授权回调 +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
正在处理微信登录...
; +} +``` + +**参考代码路径**: `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 + +**手机号登录**: + +```typescript +async loginByMobile( + mobile: string, // 手机号 + captcha: string, // 验证码 + disableRegister?: boolean // 禁止自动注册 +): Promise +``` + +**邮箱登录**: + +```typescript +async loginByEmail( + email: string, // 邮箱地址 + captcha: string, // 验证码 + disableRegister?: boolean // 禁止自动注册 +): Promise +``` + +**账号密码登录**: + +```typescript +async loginByAccount( + account: string, // 登录账号 + password: string // 密码 +): Promise +``` + +**微信小程序登录**: + +```typescript +async loginWechatMp(): Promise +``` + +**微信网页登录**: + +```typescript +async loginWechat( + code: string, // 微信授权码 + params?: { wechatLoginId?: string } // 登录ID（可选） +): Promise +``` + +**OAuth第三方登录**: + +```typescript +async loginByOAuth( + code: string, // 授权码 + state: string // 状态参数 +): Promise +``` + +#### 绑定相关API + +**绑定手机号**: + +```typescript +async bindByMobile( + mobile: string, // 手机号 + captcha?: string // 验证码（可选） +): Promise +``` + +**绑定邮箱**: + +```typescript +async bindByEmail( + email: string, // 邮箱地址 + captcha?: string // 验证码（可选） +): Promise +``` + +#### 令牌管理API + +**获取当前令牌**: + +```typescript +async get(): Promise +``` + +**刷新令牌**: + +```typescript +async refresh(): Promise +``` + +**退出登录**: + +```typescript +async logout(): Promise +``` + +**清除本地令牌**: + +```typescript +async clear(): Promise +``` + +### 6.2 事件和回调 + +#### Feature事件 + +Token Feature会发布以下事件： + +```typescript +// 登录成功事件 +features.token.subscribe('login', (token) => { + console.log('用户登录:', token.user); + // 可以在这里执行登录后的逻辑 +}); + +// 退出登录事件 +features.token.subscribe('logout', () => { + console.log('用户已退出'); + // 清理用户相关数据 +}); + +// 令牌刷新事件 +features.token.subscribe('refresh', (newToken) => { + console.log('令牌已刷新:', newToken); +}); +``` + +#### 组件回调 + +```typescript +// 登录组件回调 + { + console.log('登录成功回调:', user); + // 执行登录后逻辑 + window.location.href = '/dashboard'; + }} +/> + +// 认证组件回调 + { + 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 已知缺陷和待修复问题 + +#### 高优先级 + +1. **用户合并功能不完善** + - **问题**: 当前用户合并只支持手机号、邮箱、微信用户，其他关联数据需要手动处理 + - **影响**: 数据迁移不完整，可能导致数据不一致 + +2. **密码修改频率限制过于严格** + - **问题**: 每天5次失败限制可能影响正常用户使用 + - **影响**: 用户体验不佳 + +#### 中等优先级 + +3. **实名认证流程单一** + - **问题**: 目前仅支持身份证认证，缺少护照、港澳台证件的详细验证 + - **影响**: 限制了用户群体覆盖 + +4. **微信登录状态同步延迟** + - **问题**: 微信用户信息更新时，系统同步存在延迟 + - **影响**: 用户信息可能不是最新的 + +#### 低优先级 + +5. **组件平台适配不一致** + - **问题**: 部分组件在不同平台表现不一致 + - **影响**: 用户体验略有差异 + - **修复计划**: v6.1版本统一平台适配标准 + +--- + +*文档版本: v1.0* +*最后更新: 2025年10月25日* +*维护团队: oak-general-business开发团队*