# User Profiles 用户档案模块

## 模块概述

User Profiles模块是一个通用的用户档案数据访问服务，提供完整的用户档案信息管理功能。作为Core层的通用工具模块，它专注于用户档案数据的持久化存储和访问，为位置广播系统和其他业务模块提供数据支撑。

**核心职责：**
- 用户档案数据的增删改查操作
- 用户位置信息的实时更新和查询
- 支持MySQL和内存两种存储模式
- 提供高性能的位置数据访问接口

**技术特点：**
- 基于TypeORM的数据库映射
- 支持动态模块配置
- 完整的数据验证和异常处理
- 统一的日志记录和性能监控

## 对外接口

### UserProfilesService 主要方法

| 方法名 | 功能描述 |
|--------|----------|
| `create(createUserProfileDto)` | 创建新用户档案，支持完整的档案信息初始化 |
| `findOne(id)` | 根据档案ID查询用户档案详情 |
| `findByUserId(userId)` | 根据用户ID查询档案信息，返回null如果不存在 |
| `findByMap(mapId, status?, limit?, offset?)` | 查询指定地图中的用户列表，支持状态过滤和分页 |
| `update(id, updateData)` | 更新用户档案信息，支持部分字段更新 |
| `updatePosition(userId, positionData)` | 专用于位置更新的高性能接口 |
| `batchUpdateStatus(userIds, status)` | 批量更新多个用户的状态 |
| `findAll(queryDto)` | 查询用户档案列表，支持多种过滤条件 |
| `count(conditions?)` | 统计符合条件的档案数量 |
| `remove(id)` | 删除指定的用户档案 |
| `existsByUserId(userId)` | 检查用户是否已有档案记录 |

### UserProfilesModule 配置方法

| 方法名 | 功能描述 |
|--------|----------|
| `forDatabase()` | 配置MySQL数据库模式，适用于生产环境 |
| `forMemory()` | 配置内存存储模式，适用于开发测试 |
| `forRoot(useMemory?)` | 自动选择存储模式，根据环境变量决定 |

### 数据传输对象 (DTOs)

| DTO类名 | 用途 |
|---------|------|
| `CreateUserProfileDto` | 创建用户档案时的数据验证和传输 |
| `UpdateUserProfileDto` | 更新用户档案时的数据验证和传输 |
| `UpdatePositionDto` | 专用于位置更新的轻量级数据传输 |
| `QueryUserProfileDto` | 查询用户档案时的过滤条件和分页参数 |

## 内部依赖

### 项目内部依赖

| 依赖模块 | 用途 | 依赖关系 |
|----------|------|----------|
| 无 | 作为Core层通用工具模块，不依赖其他业务模块 | - |

### 外部依赖

| 依赖包 | 版本要求 | 用途 |
|--------|----------|------|
| `@nestjs/common` | ^10.0.0 | NestJS核心功能，依赖注入和装饰器 |
| `@nestjs/typeorm` | ^10.0.0 | TypeORM集成，数据库操作 |
| `typeorm` | ^0.3.0 | ORM框架，实体映射和查询构建 |
| `class-validator` | ^0.14.0 | 数据验证装饰器 |
| `class-transformer` | ^0.5.0 | 数据转换和序列化 |
| `@nestjs/swagger` | ^7.0.0 | API文档生成 |

### 数据库依赖

| 数据库 | 表名 | 关系 |
|--------|------|------|
| MySQL | `user_profiles` | 主表，存储用户档案信息 |
| MySQL | `users` | 外键关联，user_id字段 |

## 核心特性

### 技术特性

1. **双存储模式支持**
   - MySQL数据库模式：生产环境数据持久化
   - 内存存储模式：开发测试快速启动
   - 动态模式切换：根据环境自动选择

2. **高性能位置更新**
   - 专用位置更新接口：`updatePosition()`
   - 只更新位置相关字段，减少数据传输
   - 自动时间戳管理：`last_position_update`

3. **完整数据验证**
   - 基于class-validator的输入验证
   - 自定义验证规则和错误消息
   - 数据格式转换和类型安全

4. **统一日志监控**
   - 结构化日志记录
   - 操作耗时统计
   - 错误堆栈跟踪

### 功能特性

1. **用户档案管理**
   - 完整的CRUD操作
   - 支持富文本简历内容
   - JSON格式的标签和社交链接
   - 皮肤和外观定制

2. **位置信息管理**
   - 实时位置更新
   - 地图用户查询
   - 位置历史跟踪
   - 批量状态管理

3. **查询优化**
   - 多条件组合查询
   - 分页和排序支持
   - 索引优化的数据库设计
   - 缓存友好的接口设计

### 质量特性

1. **可测试性**
   - 完整的单元测试覆盖
   - 集成测试支持
   - Mock友好的接口设计
   - 内存模式便于测试

2. **可扩展性**
   - 模块化设计
   - 接口抽象和依赖注入
   - 支持自定义存储实现
   - 灵活的配置选项

3. **可维护性**
   - 清晰的代码结构
   - 完整的类型定义
   - 详细的注释文档
   - 统一的错误处理

## 潜在风险

### 技术风险

1. **数据库连接风险**
   - **风险**：MySQL连接失败或超时
   - **影响**：用户档案服务不可用
   - **缓解**：支持内存模式降级，连接池配置

2. **大数据量性能风险**
   - **风险**：用户档案数据量增长导致查询变慢
   - **影响**：位置查询响应时间增加
   - **缓解**：数据库索引优化，分页查询限制

3. **并发更新风险**
   - **风险**：高并发位置更新可能导致数据竞争
   - **影响**：位置数据不一致
   - **缓解**：数据库事务控制，乐观锁机制

### 业务风险

1. **数据一致性风险**
   - **风险**：用户档案与用户基础信息不同步
   - **影响**：数据完整性问题
   - **缓解**：外键约束，定期数据校验

2. **隐私数据风险**
   - **风险**：用户简历和社交信息泄露
   - **影响**：用户隐私安全问题
   - **缓解**：日志脱敏，访问权限控制

### 运维风险

1. **存储空间风险**
   - **风险**：用户档案数据持续增长
   - **影响**：数据库存储空间不足
   - **缓解**：定期数据清理，存储监控

2. **备份恢复风险**
   - **风险**：数据备份失败或恢复困难
   - **影响**：数据丢失风险
   - **缓解**：自动备份策略，恢复测试

### 安全风险

1. **SQL注入风险**
   - **风险**：动态查询可能存在注入漏洞
   - **影响**：数据库安全威胁
   - **缓解**：TypeORM参数化查询，输入验证

2. **数据访问风险**
   - **风险**：未授权访问用户档案数据
   - **影响**：用户数据泄露
   - **缓解**：接口权限验证，审计日志

## 使用示例

### 基本使用

```typescript
// 在业务模块中导入
@Module({
  imports: [
    UserProfilesModule.forDatabase(), // 生产环境
    // 或 UserProfilesModule.forMemory(), // 测试环境
  ],
})
export class BusinessModule {}

// 在服务中注入使用
@Injectable()
export class SomeBusinessService {
  constructor(
    @Inject('IUserProfilesService')
    private readonly userProfiles: UserProfilesService,
  ) {}

  async getUserLocation(userId: bigint) {
    const profile = await this.userProfiles.findByUserId(userId);
    return profile ? {
      map: profile.current_map,
      x: profile.pos_x,
      y: profile.pos_y
    } : null;
  }
}
```

### 位置更新示例

```typescript
// 更新用户位置
await userProfilesService.updatePosition(
  BigInt(123),
  {
    current_map: 'forest',
    pos_x: 150.5,
    pos_y: 200.3
  }
);

// 查询地图用户
const onlineUsers = await userProfilesService.findByMap(
  'plaza', 
  1, // 在线状态
  20, // 限制20个
  0   // 偏移量0
);
```

## 版本历史

- **v1.0.0** (2026-01-08): 初始版本，支持基础用户档案管理和位置广播功能