Environment-Monitoring-System/Design/账号管理功能设计.md

账号管理功能 - 设计文档

1. 功能描述

本模块负责处理所有用户的认证与基础账户操作，包括注册、登录和安全设置（如忘记密码、修改密码/手机号）。其核心目标是提供一个安全、可靠且用户体验良好的身份验证入口。

2. 涉及角色

• 所有角色: 该功能是所有需要登录系统的用户（公众监督员、监督员、网格员、管理员、决策者）的通用基础功能。

3. 业务规则

3.1 注册规则

• 唯一性约束: 注册时使用的邮箱和手机号必须在user_account表中是唯一的。
• 密码策略:
  • 复杂度: 8-16位，必须同时包含大写字母、小写字母、数字和特殊字符。
  • 确认机制: 注册时密码需要输入两次进行确认。
  • 存储安全: 密码在后端必须使用强哈希算法（如BCrypt）加盐后存储，绝不允许明文存储。
• 邮箱验证码规则:
  • 时效性: 验证码生成后5分钟内有效。
  • 冷却期: "获取验证码"按钮点击后，有60秒的冷却时间，防止恶意请求。
  • 尝试次数: 同一个验证码最多允许输错2次，第3次输错则该验证码立即失效，需重新获取。

3.2 登录规则

• 支持使用邮箱或手机号作为登录凭据。
• 登录失败时，应给出统一的、模糊的提示（如"用户名或密码错误"），避免泄露账户是否存在的信息。
• 可考虑引入登录尝试次数限制机制，例如连续失败5次后，临时锁定账户15分钟。

3.3 安全验证规则

• 身份确认: "忘记密码"或"修改手机号"等敏感操作，必须先通过"邮箱 + 姓名"进行第一步身份确认。
• 操作授权: 身份确认通过后，必须再次完成与注册流程完全相同的邮箱动态验证码校验，才能进行下一步操作。

3.4 JWT (Token) 规则

• Payload 结构: Token的Payload中应至少包含userId, role, email，以便后端进行快速的身份和权限识别。
• 有效期: Access Token的有效期应设置为较短的时间（如1小时），以降低泄露风险。
• 刷新机制: 提供一个Refresh Token，其有效期更长（如7天）。当Access Token过期后，前端可使用Refresh Token向后端申请新的Access Token，无需用户重新登录。
• 存储: 前端应将Access Token存储在内存中，将Refresh Token存储在HttpOnly、Secure的Cookie中，以提高安全性。

3.5 系统管理员操作规则

• 创建内部账户: 系统管理员(Admin)在NEPM端创建内部用户（如SUPERVISOR, GRID_WORKER）时，系统应生成一个安全的初始随机密码。
• 密码重置: 管理员可以为任何用户重置密码，重置后同样生成一个随机密码。
• 密码分发: 生成的初始密码或重置后的密码，应通过安全的、非系统内的方式（如邮件、短信）告知用户，并强制用户在首次登录后立即修改。

4. 功能实现流程

4.1 注册流程

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端界面
    participant Backend as 后端服务
    participant Mail as 邮箱服务

    User->>Frontend: 填写注册信息 (邮箱, 手机, 密码等)
    Note right of Frontend: 前端实时校验格式和密码强度
    User->>Frontend: 点击"获取验证码"
    Frontend->>Backend: POST /api/auth/send-verification-code
    Note over Backend: 生成6位验证码, 存入Redis并设5分钟过期
    Backend->>Mail: 调用163邮箱API发送验证码
    Mail-->>User: 收到验证码邮件
    User->>Frontend: 输入收到的验证码
    User->>Frontend: 点击"注册"
    Frontend->>Backend: POST /api/auth/register
    Backend->>Backend: 校验验证码 (正确性, 是否过期, 尝试次数)
    alt 验证成功
        Backend->>Backend: 校验邮箱/手机唯一性, BCrypt加密密码
        Backend->>Backend: 创建`user_account`记录
        Backend-->>Frontend: 注册成功 (201 Created)
    else 验证失败
        Backend-->>Frontend: 返回错误信息 (400 Bad Request)
    end

4.2 登录流程

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端
    participant Backend as 后端

    User->>Frontend: 输入邮箱/手机号和密码, 点击登录
    Frontend->>Backend: POST /api/auth/login
    Backend->>Backend: 验证用户信息和密码
    alt 验证成功
        Backend->>Backend: 生成Access Token和Refresh Token
        Backend-->>Frontend: 登录成功 (200 OK)<br>返回Access Token, 并设置Refresh Token到Cookie
        Note left of Frontend: 存储Token, 跳转到用户主页
    else 验证失败
        Backend->>Backend: 记录失败次数, 检查是否需要锁定账户
        Backend-->>Frontend: 返回"用户名或密码错误" (401 Unauthorized)
    end

4.3 忘记密码流程

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端界面
    participant Backend as 后端服务

    User->>Frontend: 点击"忘记密码", 输入邮箱和姓名
    Frontend->>Backend: POST /api/auth/request-password-reset
    Backend->>Backend: 校验邮箱和姓名是否存在且匹配
    alt 身份校验成功
        Backend-->>Frontend: 跳转至邮箱验证码页面
        Note right of Frontend: (后续流程与注册时的邮箱验证完全相同)
        User->>Frontend: 完成邮箱验证, 输入新密码
        Frontend->>Backend: POST /api/auth/reset-password
        Backend->>Backend: 更新用户密码
        Backend-->>Frontend: 密码重置成功 (200 OK)
    else 身份校验失败
        Backend-->>Frontend: 返回错误信息 (400 Bad Request)
    end

5. API 接口设计

5.1 用户注册

• URL: POST /api/auth/register
• 请求体: name, email, phone, password, verificationCode
• 响应: 201 Created

5.2 用户登录

• URL: POST /api/auth/login
• 请求体: principal (邮箱或手机号), password
• 响应: 200 OK, 返回 accessToken，并在Cookie中设置refreshToken。

5.3 发送邮箱验证码

• URL: POST /api/auth/send-verification-code
• 请求体: email, type (Enum: REGISTER, RESET_PASSWORD)
• 响应: 200 OK

5.4 刷新AccessToken

• URL: POST /api/auth/refresh-token
• 请求体: (空, Refresh Token从Cookie中获取)
• 响应: 200 OK, 返回新的accessToken。

5.5 请求密码重置

• URL: POST /api/auth/request-password-reset
• 请求体: email, name
• 响应: 200 OK (无论用户是否存在，都返回成功，防止信息泄露)

5.6 重置密码

• URL: POST /api/auth/reset-password
• 请求体: email, newPassword, verificationCode
• 响应: 200 OK

5.7 管理员创建用户

• URL: POST /api/admin/users
• 权限: ADMIN
• 请求体: name, email, phone, role, region, level
• 响应: 201 Created, 返回包含初始随机密码的用户信息。

6. 界面设计要求

6.1 注册页面

• 表单布局清晰，各输入项有明确的标签和占位提示。
• "获取验证码"按钮在点击后应变为不可用状态，并显示倒计时。
• 密码输入框应为密码类型，并提供一个可切换"显示/隐藏"密码的图标。
• 密码强度提示：实时根据用户输入，以进度条或文字形式提示密码强度（弱、中、强）。
• 所有输入项的错误提示应在输入框下方实时显示，内容明确。

6.2 登录页面

• 界面简洁，突出登录表单。
• 提供"忘记密码"的链接。
• 可选提供"记住我"的复选框。
• 登录成功后，应有平滑的过渡效果，并根据用户角色跳转到对应的系统主页（NEPS, NEPG, NEPM, NEPV）。

6.3 忘记密码/安全验证页面

• 流程应分步进行，保持每一步操作的单一和清晰。
• 第一步：身份验证（输入邮箱、姓名）。
• 第二步：安全验证（输入邮箱收到的验证码）。
• 第三步：重置密码（输入新密码并确认）。
• 每个步骤都应有清晰的标题和进度指示。
• 操作成功后，应明确提示用户"密码已重置，请使用新密码登录"，并引导至登录页面。