6.2 KiB
6.2 KiB
Requirements Document
Introduction
本文档定义了将PHP用户认证系统迁移到.NET 8的需求规范。迁移范围包括微信小程序登录、手机号验证码登录、JWT Token管理、用户信息管理、手机号绑定、登录记录和账号注销功能。迁移过程中需要保持与现有UniApp前端的100%兼容性。
Glossary
- Auth_System: 用户认证系统，负责处理用户登录、注册、Token管理等功能
- Wechat_Service: 微信服务，负责与微信API交互获取openid和用户信息
- Sms_Service: 短信服务，负责验证短信验证码（发送验证码暂不迁移，继续使用PHP接口）
- Jwt_Service: JWT服务，负责生成、验证和刷新JWT Token
- User_Service: 用户服务，负责用户信息的增删改查
- Redis_Cache: Redis缓存服务，用于存储验证码和防抖锁
- IP_Location_Service: IP地理位置服务，用于解析用户登录IP的地理位置
Requirements
Requirement 1: 微信小程序登录
User Story: As a 用户, I want to 通过微信小程序授权登录, so that 我可以快速进入系统而无需输入账号密码
Acceptance Criteria
- WHEN 用户提交微信授权code, THE Auth_System SHALL 调用微信API获取openid和unionid
- WHEN 获取到openid后, THE Auth_System SHALL 查找是否存在该用户（优先通过unionid查找，其次通过openid查找）
- WHEN 用户不存在时, THE Auth_System SHALL 自动创建新用户并生成默认头像和昵称
- WHEN 用户存在时, THE Auth_System SHALL 更新用户的unionid（如果之前为空）
- WHEN 登录成功后, THE Auth_System SHALL 生成JWT Token并返回给客户端
- WHEN 用户在3秒内重复请求登录, THE Auth_System SHALL 返回"请勿频繁登录"错误（防抖机制）
- IF 微信API调用失败, THEN THE Auth_System SHALL 返回明确的错误信息
- WHEN 用户提供推荐人ID(pid), THE Auth_System SHALL 记录推荐关系
Requirement 2: 手机号验证码登录
User Story: As a 用户, I want to 通过手机号和验证码登录, so that 我可以在没有微信的情况下也能登录系统
Acceptance Criteria
- WHEN 用户提交手机号和验证码登录, THE Auth_System SHALL 从Redis获取并验证验证码是否正确
- WHEN 验证码验证通过后, THE Auth_System SHALL 删除Redis中的验证码
- WHEN 手机号用户不存在时, THE Auth_System SHALL 自动创建新用户并生成默认头像和昵称
- WHEN 登录成功后, THE Auth_System SHALL 生成JWT Token并返回
- IF 验证码错误或过期, THEN THE Auth_System SHALL 返回"验证码错误"
- WHEN 用户在3秒内重复请求登录, THE Auth_System SHALL 返回"请勿频繁登录"错误
- WHEN 用户提供推荐人ID(pid), THE Auth_System SHALL 记录推荐关系
注意: 发送短信验证码接口暂不迁移，继续使用PHP原有接口
Requirement 3: JWT Token管理
User Story: As a 系统, I want to 使用JWT Token进行用户认证, so that 可以实现无状态的安全认证
Acceptance Criteria
- WHEN 用户登录成功, THE Jwt_Service SHALL 生成包含用户ID的JWT Token
- THE Jwt_Service SHALL 使用配置的密钥对Token进行签名
- WHEN 请求携带Token访问受保护接口, THE Auth_System SHALL 验证Token的有效性
- IF Token无效或过期, THEN THE Auth_System SHALL 返回状态码-1（未登录）
- WHEN Token即将过期时, THE Jwt_Service SHALL 支持Token刷新功能
- THE Auth_System SHALL 同时在数据库UserAccount表中存储account_token用于兼容旧系统
Requirement 4: 用户信息管理
User Story: As a 用户, I want to 查看和修改我的个人信息, so that 我可以维护我的账户资料
Acceptance Criteria
- WHEN 用户请求获取个人信息, THE User_Service SHALL 返回用户的完整信息（包括余额、积分、VIP等级等）
- WHEN 用户更新昵称, THE User_Service SHALL 验证昵称不为空并保存
- WHEN 用户上传新头像, THE User_Service SHALL 将Base64图片上传到腾讯云COS并更新头像URL
- THE User_Service SHALL 对手机号进行脱敏处理（显示为138****8000格式）
- WHEN 返回用户信息时, THE User_Service SHALL 计算并返回用户的VIP等级和相关权益
Requirement 5: 手机号绑定
User Story: As a 用户, I want to 绑定我的手机号, so that 我可以使用手机号登录并接收重要通知
Acceptance Criteria
- WHEN 用户请求绑定手机号, THE Auth_System SHALL 验证短信验证码
- WHEN 手机号已被其他用户绑定, THE Auth_System SHALL 合并两个账户（保留手机号用户，迁移openid）
- WHEN 账户合并后, THE Auth_System SHALL 返回新的Token
- WHEN 手机号未被绑定, THE Auth_System SHALL 直接更新当前用户的手机号
- IF 验证码错误, THEN THE Auth_System SHALL 返回"验证码错误"
Requirement 6: 登录记录
User Story: As a 系统管理员, I want to 记录用户的登录信息, so that 可以进行安全审计和用户行为分析
Acceptance Criteria
- WHEN 用户登录成功, THE Auth_System SHALL 记录登录日志（包括用户ID、设备类型、IP地址、登录时间）
- WHEN 记录登录时, THE IP_Location_Service SHALL 解析IP地址获取省份和城市信息
- THE Auth_System SHALL 更新UserAccount表中的最后登录时间和IP信息
- WHEN 用户调用recordLogin接口, THE Auth_System SHALL 返回用户的uid、昵称和头像
Requirement 7: 账号注销
User Story: As a 用户, I want to 注销我的账号, so that 我可以删除我在系统中的所有数据
Acceptance Criteria
- WHEN 用户请求注销账号, THE Auth_System SHALL 记录注销请求日志
- THE Auth_System SHALL 返回注销成功的消息
- WHEN type参数为0时表示注销账号，type为1时表示取消注销
Requirement 8: API接口文档更新
User Story: As a 开发者, I want to 在迁移完成后更新API接口文档, so that 可以追踪迁移进度和新接口地址
Acceptance Criteria
- WHEN 每个接口迁移完成后, THE 开发者 SHALL 在docs/API接口文档.md中标记该接口为"已迁移"
- THE 文档 SHALL 记录新接口的完整地址
- THE 文档 SHALL 保留原接口信息以便对比