# 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

1. WHEN 用户提交微信授权code, THE Auth_System SHALL 调用微信API获取openid和unionid
2. WHEN 获取到openid后, THE Auth_System SHALL 查找是否存在该用户（优先通过unionid查找，其次通过openid查找）
3. WHEN 用户不存在时, THE Auth_System SHALL 自动创建新用户并生成默认头像和昵称
4. WHEN 用户存在时, THE Auth_System SHALL 更新用户的unionid（如果之前为空）
5. WHEN 登录成功后, THE Auth_System SHALL 生成JWT Token并返回给客户端
6. WHEN 用户在3秒内重复请求登录, THE Auth_System SHALL 返回"请勿频繁登录"错误（防抖机制）
7. IF 微信API调用失败, THEN THE Auth_System SHALL 返回明确的错误信息
8. WHEN 用户提供推荐人ID(pid), THE Auth_System SHALL 记录推荐关系

### Requirement 2: 手机号验证码登录

**User Story:** As a 用户, I want to 通过手机号和验证码登录, so that 我可以在没有微信的情况下也能登录系统

#### Acceptance Criteria

1. WHEN 用户提交手机号和验证码登录, THE Auth_System SHALL 从Redis获取并验证验证码是否正确
2. WHEN 验证码验证通过后, THE Auth_System SHALL 删除Redis中的验证码
3. WHEN 手机号用户不存在时, THE Auth_System SHALL 自动创建新用户并生成默认头像和昵称
4. WHEN 登录成功后, THE Auth_System SHALL 生成JWT Token并返回
5. IF 验证码错误或过期, THEN THE Auth_System SHALL 返回"验证码错误"
6. WHEN 用户在3秒内重复请求登录, THE Auth_System SHALL 返回"请勿频繁登录"错误
7. 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

1. WHEN 用户登录成功, THE Jwt_Service SHALL 生成包含用户ID的JWT Token
2. THE Jwt_Service SHALL 使用配置的密钥对Token进行签名
3. WHEN 请求携带Token访问受保护接口, THE Auth_System SHALL 验证Token的有效性
4. IF Token无效或过期, THEN THE Auth_System SHALL 返回状态码-1（未登录）
5. WHEN Token即将过期时, THE Jwt_Service SHALL 支持Token刷新功能
6. THE Auth_System SHALL 同时在数据库UserAccount表中存储account_token用于兼容旧系统

### Requirement 4: 用户信息管理

**User Story:** As a 用户, I want to 查看和修改我的个人信息, so that 我可以维护我的账户资料

#### Acceptance Criteria

1. WHEN 用户请求获取个人信息, THE User_Service SHALL 返回用户的完整信息（包括余额、积分、VIP等级等）
2. WHEN 用户更新昵称, THE User_Service SHALL 验证昵称不为空并保存
3. WHEN 用户上传新头像, THE User_Service SHALL 将Base64图片上传到腾讯云COS并更新头像URL
4. THE User_Service SHALL 对手机号进行脱敏处理（显示为138****8000格式）
5. WHEN 返回用户信息时, THE User_Service SHALL 计算并返回用户的VIP等级和相关权益

### Requirement 5: 手机号绑定

**User Story:** As a 用户, I want to 绑定我的手机号, so that 我可以使用手机号登录并接收重要通知

#### Acceptance Criteria

1. WHEN 用户请求绑定手机号, THE Auth_System SHALL 验证短信验证码
2. WHEN 手机号已被其他用户绑定, THE Auth_System SHALL 合并两个账户（保留手机号用户，迁移openid）
3. WHEN 账户合并后, THE Auth_System SHALL 返回新的Token
4. WHEN 手机号未被绑定, THE Auth_System SHALL 直接更新当前用户的手机号
5. IF 验证码错误, THEN THE Auth_System SHALL 返回"验证码错误"

### Requirement 6: 登录记录

**User Story:** As a 系统管理员, I want to 记录用户的登录信息, so that 可以进行安全审计和用户行为分析

#### Acceptance Criteria

1. WHEN 用户登录成功, THE Auth_System SHALL 记录登录日志（包括用户ID、设备类型、IP地址、登录时间）
2. WHEN 记录登录时, THE IP_Location_Service SHALL 解析IP地址获取省份和城市信息
3. THE Auth_System SHALL 更新UserAccount表中的最后登录时间和IP信息
4. WHEN 用户调用recordLogin接口, THE Auth_System SHALL 返回用户的uid、昵称和头像

### Requirement 7: 账号注销

**User Story:** As a 用户, I want to 注销我的账号, so that 我可以删除我在系统中的所有数据

#### Acceptance Criteria

1. WHEN 用户请求注销账号, THE Auth_System SHALL 记录注销请求日志
2. THE Auth_System SHALL 返回注销成功的消息
3. WHEN type参数为0时表示注销账号，type为1时表示取消注销

### Requirement 8: API接口文档更新

**User Story:** As a 开发者, I want to 在迁移完成后更新API接口文档, so that 可以追踪迁移进度和新接口地址

#### Acceptance Criteria

1. WHEN 每个接口迁移完成后, THE 开发者 SHALL 在docs/API接口文档.md中标记该接口为"已迁移"
2. THE 文档 SHALL 记录新接口的完整地址
3. THE 文档 SHALL 保留原接口信息以便对比