frontend/profileServiceREADME (1).md

# ProfileService - 角色管理服务

ProfileService是CarrotSkin皮肤站的角色管理微服务，负责处理Minecraft角色的创建、管理、RSA密钥生成和签名验证等核心功能。

## 📋 目录

- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [数据模型](#数据模型)
- [API接口](#api接口)
- [部署指南](#部署指南)
- [开发指南](#开发指南)
- [故障排查](#故障排查)

## 🚀 功能特性

### 核心功能
- **角色管理**: 创建、查询、更新、删除Minecraft角色
- **RSA密钥管理**: 自动生成RSA-2048密钥对，支持数据签名和验证
- **皮肤/披风关联**: 管理角色与皮肤、披风的关联关系
- **用户角色列表**: 支持查询用户下的所有角色
- **数据验证**: 完整的参数验证和业务逻辑检查

### 安全特性
- **RSA签名**: 支持使用私钥对数据进行签名
- **签名验证**: 支持使用公钥验证数据签名
- **权限控制**: 确保用户只能操作自己的角色
- **数据完整性**: 完整的事务处理和数据一致性保证

## 🏗️ 技术架构

### 技术栈
- **框架**: go-zero微服务框架
- **数据库**: MySQL 8.0+
- **缓存**: Redis (通过go-zero集成)
- **通信协议**: gRPC
- **密钥算法**: RSA-2048

### 服务架构
```
ProfileService
├── internal/
│   ├── config/          # 配置管理
│   ├── handler/         # gRPC处理器
│   ├── logic/           # 业务逻辑层
│   ├── model/           # 数据模型层
│   └── svc/            # 服务上下文
├── pb/                  # Protocol Buffers定义
└── docs/               # 文档和SQL脚本
```

## 📊 数据模型

### 数据库表结构

```sql
CREATE TABLE `profiles` (
  `uuid` VARCHAR(36) NOT NULL COMMENT '角色的UUID，通常为Minecraft玩家的UUID',
  `user_id` BIGINT UNSIGNED NOT NULL COMMENT '关联的用户ID',
  `name` VARCHAR(16) NOT NULL COMMENT '角色名 (Minecraft In-Game Name)',
  `skin_id` BIGINT UNSIGNED NULL DEFAULT NULL COMMENT '当前使用的皮肤ID',
  `cape_id` BIGINT UNSIGNED NULL DEFAULT NULL COMMENT '当前使用的披风ID',
  `rsa_private_key` TEXT NOT NULL COMMENT 'RSA-2048私钥 (PEM格式)',
  `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`uuid`),
  INDEX `idx_user_id` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

### 数据类型映射

| 字段 | SQL类型 | Go Model类型 | Proto类型 | 说明 |
|------|---------|-------------|-----------|------|
| uuid | VARCHAR(36) | string | string | 角色UUID |
| user_id | BIGINT UNSIGNED | uint64 | int64 | 用户ID |
| name | VARCHAR(16) | string | string | 角色名 |
| skin_id | BIGINT UNSIGNED NULL | sql.NullInt64 | int64 | 皮肤ID (0表示无皮肤) |
| cape_id | BIGINT UNSIGNED NULL | sql.NullInt64 | int64 | 披风ID (0表示无披风) |
| rsa_private_key | TEXT | string | string | RSA私钥 |
| created_at | TIMESTAMP | time.Time | string | 创建时间 |
| updated_at | TIMESTAMP | time.Time | string | 更新时间 |

## 🔌 API接口

### 对外接口 (Public APIs)

#### 1. CreateProfile - 创建角色
```protobuf
rpc CreateProfile(CreateProfileRequest) returns (CreateProfileResponse);
```
- **功能**: 创建新的Minecraft角色
- **验证**: UUID格式、角色名格式、用户权限
- **特性**: 自动生成RSA密钥对、角色名去重检查

#### 2. GetProfile - 获取角色信息
```protobuf
rpc GetProfile(GetProfileRequest) returns (GetProfileResponse);
```
- **功能**: 根据UUID获取角色基本信息
- **返回**: 不包含私钥的公开信息

#### 3. GetProfilesByUserId - 获取用户角色列表
```protobuf
rpc GetProfilesByUserId(GetProfilesByUserIdRequest) returns (GetProfilesByUserIdResponse);
```
- **功能**: 获取指定用户的所有角色列表
- **特性**: 支持空结果返回

#### 4. UpdateProfile - 更新角色信息
```protobuf
rpc UpdateProfile(UpdateProfileRequest) returns (UpdateProfileResponse);
```
- **功能**: 更新角色名、皮肤ID、披风ID
- **验证**: 角色名重复检查、权限验证
- **特性**: 支持NULL值处理 (0表示移除)

#### 5. DeleteProfile - 删除角色
```protobuf
rpc DeleteProfile(DeleteProfileRequest) returns (DeleteProfileResponse);
```
- **功能**: 删除指定角色
- **验证**: 权限检查

#### 6. GetProfilePublicKey - 获取角色公钥
```protobuf
rpc GetProfilePublicKey(GetProfilePublicKeyRequest) returns (GetProfilePublicKeyResponse);
```
- **功能**: 获取角色的RSA公钥
- **用途**: 用于验证角色签名

#### 7. VerifyProfileSignature - 验证角色签名
```protobuf
rpc VerifyProfileSignature(VerifyProfileSignatureRequest) returns (VerifyProfileSignatureResponse);
```
- **功能**: 验证使用角色私钥生成的签名
- **算法**: RSA-2048 + SHA-256

#### 8. GetProfileWithProperties - 查询角色属性
```protobuf
rpc GetProfileWithProperties(GetProfileWithPropertiesRequest) returns (GetProfileWithPropertiesResponse);
```
- **功能**: 查询角色完整信息，包含Minecraft协议兼容的属性和签名
- **用途**: 用于游戏客户端获取皮肤、披风等信息
- **特性**: 支持生成带签名和不带签名的属性

#### 9. GetProfilesByNames - 批量查询角色
```protobuf
rpc GetProfilesByNames(GetProfilesByNamesRequest) returns (GetProfilesByNamesResponse);
```
- **功能**: 根据角色名称列表批量查询角色信息
- **返回**: 简化的角色信息列表（UUID和名称）

#### 10. GetUserIdByProfileName - 根据角色名获取用户ID
```protobuf
rpc GetUserIdByProfileName(GetUserIdByProfileNameRequest) returns (GetUserIdByProfileNameResponse);
```
- **功能**: 根据角色名称查找关联的用户ID
- **用途**: 支持使用角色名进行登录等操作

### 对内接口 (Internal APIs)

#### 11. GetProfileInternalInfo - 获取角色内部信息
```protobuf
rpc GetProfileInternalInfo(GetProfileInternalInfoRequest) returns (ProfileInternalInfo);
```
- **功能**: 获取包含私钥的完整角色信息
- **权限**: 仅供内部微服务调用
- **安全**: 包含敏感信息，需要严格权限控制

#### 12. SignData - 使用私钥签名数据
```protobuf
rpc SignData(SignDataRequest) returns (SignDataResponse);
```
- **功能**: 使用角色私钥对数据进行签名
- **算法**: RSA-2048 + SHA-256
- **返回**: Base64编码的签名结果

## 🚀 部署指南

### 环境要求
- Go 1.19+
- MySQL 8.0+
- Redis 6.0+

### 配置文件示例

```yaml
# etc/profile.yaml
Name: profile.rpc
ListenOn: 0.0.0.0:8082

#Etcd:
#  Hosts:
#    - 127.0.0.1:2379
#  Key: profile.rpc

DataSource: root:password@tcp(localhost:3306)/carrot_skin?charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai

CacheConf:
  - Host: 127.0.0.1:6379
    Pass: ""
    Type: node
```

### 部署步骤

1. **数据库初始化**
```bash
mysql -u root -p carrot_skin < docs/profiles.sql
```

2. **编译服务**
```bash
go build -o profile-service .
```

3. **启动服务**
```bash
./profile-service -f etc/profile.yaml
```

## 🛠️ 开发指南

### 代码生成

使用提供的脚本重新生成代码：

```bash
# Windows
generate.bat

# Linux/Mac
chmod +x generate.sh
./generate.sh
```

### 业务逻辑扩展

所有业务逻辑都在 `internal/logic/` 目录下：

- `createProfileLogic.go` - 角色创建逻辑
- `getProfileLogic.go` - 角色查询逻辑
- `updateProfileLogic.go` - 角色更新逻辑
- `deleteProfileLogic.go` - 角色删除逻辑
- 等等...

### 数据模型扩展

如需添加新的数据库方法，在 `internal/model/profilesmodel.go` 中扩展：

```go
type ProfilesModel interface {
    profilesModel
    // 添加自定义方法
    FindByUserId(ctx context.Context, userId uint64) ([]*Profiles, error)
}
```

## 🔧 故障排查

### 常见问题

#### 1. 数据类型转换错误
**问题**: `sql.NullInt64` 类型处理错误
**解决**: 使用 `nullInt64ToValue()` 函数进行正确转换

#### 2. RSA密钥生成失败
**问题**: RSA密钥生成或解析失败
**解决**: 检查系统随机数生成器，确保有足够的熵

#### 3. 角色名重复
**问题**: 同一用户下角色名重复
**解决**: 创建和更新时都会进行重复检查

#### 4. UUID格式错误
**问题**: UUID格式不符合标准
**解决**: 确保UUID为36位标准格式 (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

### 日志级别

- **INFO**: 正常业务操作
- **ERROR**: 业务错误和系统错误
- **DEBUG**: 详细的调试信息

### 性能监控

- 数据库连接池状态
- Redis缓存命中率
- gRPC请求响应时间
- RSA密钥操作耗时