# Proto 文件说明

> **目录**：Protocol Buffers 定义文件  
> **用途**：定义服务接口和数据结构

---

## 📁 文件结构

```
proto/
├── common.proto          # 通用消息定义（BaseResponse, PageRequest 等）
├── user.proto            # 用户服务定义（认证、身份、个人资料等）
├── social.proto          # 社交服务定义（好友、关注等功能）
└── README.md            # 本文档
```

---

## 🔧 编译 Proto 文件

### 1. 安装依赖

需要安装以下工具：

```bash
# 安装 protoc 编译器
# macOS
brew install protobuf

# Ubuntu/Debian
apt-get install protobuf-compiler

# 安装 Go 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install github.com/dubbogo/triple/cmd/protoc-gen-triple@latest

# 安装 HTTP 注解插件（可选）
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
```

### 2. 编译 Proto 文件

```bash
# 进入 backend 目录
cd /path/to/backend

# 编译 user.proto
protoc --proto_path=. \
  --go_out=. \
  --go_opt=module=github.com/topfans/backend \
  --go-triple_out=. \
  --go-triple_opt=module=github.com/topfans/backend \
  proto/user.proto

# 编译 social.proto
protoc --proto_path=. \
  --go_out=. \
  --go_opt=module=github.com/topfans/backend \
  --go-triple_out=. \
  --go-triple_opt=module=github.com/topfans/backend \
  proto/social.proto

# 生成的文件：
# - pkg/proto/user/user.pb.go            # 用户服务消息定义
# - pkg/proto/user/user.triple.go        # 用户服务 Dubbo Triple 接口
# - pkg/proto/social/social.pb.go        # 社交服务消息定义
# - pkg/proto/social/social.triple.go    # 社交服务 Dubbo Triple 接口
```

### 3. 批量编译所有 proto 文件

创建编译脚本 `scripts/compile-proto.sh`：

```bash
#!/bin/bash

set -e

# 进入项目根目录
cd "$(dirname "$0")/.."

echo "编译 Proto 文件..."

# 模块路径
MODULE_PATH="github.com/topfans/backend"

# 编译 user.proto
protoc --proto_path=. \
  --go_out=. \
  --go_opt=module=$MODULE_PATH \
  --go-triple_out=. \
  --go-triple_opt=module=$MODULE_PATH \
  proto/user.proto

echo "✅ user.proto 编译完成"

# 编译 social.proto
protoc --proto_path=. \
  --go_out=. \
  --go_opt=module=$MODULE_PATH \
  --go-triple_out=. \
  --go-triple_opt=module=$MODULE_PATH \
  proto/social.proto

echo "✅ social.proto 编译完成"

echo "所有 Proto 文件编译完成！"
```

使用脚本：

```bash
chmod +x scripts/compile-proto.sh
./scripts/compile-proto.sh
```

---

## 📋 social.proto 说明

### 核心 Message

#### 1. FriendRequest（好友请求）

```protobuf
message FriendRequest {
  int64 id = 1;                     // 请求ID
  int64 from_user_id = 2;           // 发送者用户ID
  int64 to_user_id = 3;             // 接收者用户ID
  int64 star_id = 4;                // 明星ID
  string message = 5;               // 请求附带消息
  string status = 6;                // 状态
  // ... 更多字段
}
```

**状态枚举**：
- `pending` - 待处理
- `accepted` - 已接受
- `rejected` - 已拒绝
- `expired` - 已过期

---

#### 2. Friendship（好友关系）

```protobuf
message Friendship {
  int64 id = 1;                     // 关系ID
  int64 user_id = 2;                // 用户ID
  int64 friend_id = 3;              // 好友用户ID
  int64 star_id = 4;                // 明星ID
  string status = 5;                // 状态
  string remark = 6;                // 备注名
  // ... 更多字段
}
```

**状态枚举**：
- `accepted` - 正常好友关系
- `blocked` - 已屏蔽（预留）

---

### 服务接口

#### SocialService

```protobuf
service SocialService {
  // 好友请求相关
  rpc SendFriendRequest(...)      // 发送好友请求
  rpc GetFriendRequests(...)      // 获取请求列表
  rpc HandleFriendRequest(...)    // 处理请求（接受/拒绝）
  
  // 好友关系相关
  rpc GetFriendList(...)          // 获取好友列表
  rpc DeleteFriend(...)           // 删除好友
  rpc SetFriendRemark(...)        // 设置备注
  rpc CheckFriendship(...)        // 检查好友关系
  rpc GetFriendCount(...)         // 获取好友数量
}
```

---

## 🎯 使用示例

### 1. 在 Service 层实现接口

```go
package service

import (
    pb "github.com/topfans/backend/pkg/proto/social"
)

type SocialService struct {
    // 依赖注入
    socialRepo repository.SocialRepository
    config     *config.SocialConfig
}

// 实现 SendFriendRequest
func (s *SocialService) SendFriendRequest(
    ctx context.Context,
    req *pb.SendFriendRequestRequest,
) (*pb.SendFriendRequestResponse, error) {
    // 从 Dubbo Attachments 获取用户信息
    userID := dubbo.GetAttachment(ctx, "user_id")
    starID := dubbo.GetAttachment(ctx, "star_id")
    
    // 业务逻辑...
    
    return &pb.SendFriendRequestResponse{
        Base: &common.BaseResponse{
            Code: common.StatusCode_STATUS_OK,
            Message: "ok",
            Timestamp: time.Now().UnixMilli(),
        },
        RequestId: requestID,
        Status: "pending",
    }, nil
}
```

---

### 2. 在 Gateway 层调用服务

```go
package controller

import (
    pb "github.com/topfans/backend/pkg/proto/social"
)

type SocialController struct {
    socialServiceClient pb.SocialServiceClient
}

func (c *SocialController) SendFriendRequest(ctx *gin.Context) {
    var req pb.SendFriendRequestRequest
    if err := ctx.ShouldBindJSON(&req); err != nil {
        response.BadRequest(ctx, err.Error())
        return
    }
    
    // 创建 Dubbo Context，设置 Attachments
    dubboCtx := context.Background()
    dubboCtx = context.WithValue(dubboCtx, constant.AttachmentKey, 
        map[string]interface{}{
            "user_id": ctx.GetInt64("user_id"),
            "star_id": ctx.GetInt64("star_id"),
        })
    
    // 调用 Dubbo 服务
    resp, err := c.socialServiceClient.SendFriendRequest(dubboCtx, &req)
    if err != nil {
        response.HandleError(ctx, err)
        return
    }
    
    response.Success(ctx, resp)
}
```

---

## 📊 HTTP 路由映射

基于 proto 文件中的 `google.api.http` 注解，自动生成以下路由：

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/friends/requests` | 发送好友请求 |
| GET | `/api/v1/friends/requests` | 获取请求列表 |
| POST | `/api/v1/friends/requests/{request_id}/handle` | 处理请求 |
| GET | `/api/v1/friends` | 获取好友列表 |
| DELETE | `/api/v1/friends/{friend_user_id}` | 删除好友 |
| PUT | `/api/v1/friends/{friend_user_id}/remark` | 设置备注 |
| GET | `/api/v1/friends/check/{user_id}/{friend_user_id}` | 检查好友关系 |
| GET | `/api/v1/friends/count` | 获取好友数量 |

---

## 🔄 Proto 文件修改流程

1. **修改 proto 文件**
2. **重新编译**：`./scripts/compile-proto.sh`
3. **更新 Service 实现**
4. **更新 Gateway Controller**
5. **测试验证**

---

## ✅ 检查清单

- [x] common.proto - 通用定义
- [x] user.proto - 用户服务（认证、身份、个人资料）
- [x] social.proto - 社交服务（好友、关注等功能）
- [x] 编译所有 proto 文件
- [ ] 实现 SocialService
- [ ] 创建 Provider
- [ ] 注册 Dubbo 服务

---

## 📚 参考资料

- [Protocol Buffers 官方文档](https://developers.google.com/protocol-buffers)
- [Dubbo-go 官方文档](https://dubbogo.github.io/)
- [gRPC HTTP 注解](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto)

---

**最后更新**：2026-01-06  
**版本**：v2.0（已重命名为 Social 服务）