# 好友功能设计方案（已确认版）

> **文档状态**：设计已确认 ✅  
> **创建时间**：2026-01-05  
> **确认时间**：2026-01-06  
> **目标**：定义好友系统的数据库设计、API 接口和业务流程

---

## 📋 目录

- [1. 功能概述](#1-功能概述)
- [2. 数据库设计](#2-数据库设计)
- [3. 业务流程设计](#3-业务流程设计)
- [4. API 接口设计](#4-api-接口设计)
- [5. 状态机设计](#5-状态机设计)
- [6. 实现步骤](#6-实现步骤)
- [7. 待讨论问题](#7-待讨论问题)

---

## 1. 功能概述

### 1.1 核心功能

- ✅ **发送好友请求**：用户 A 向用户 B 发送好友请求
- ✅ **接受好友请求**：用户 B 接受用户 A 的好友请求
- ✅ **拒绝好友请求**：用户 B 拒绝用户 A 的好友请求
- ✅ **删除好友**：用户可以删除已添加的好友
- ✅ **查看好友列表**：查看自己的好友列表
- ✅ **查看好友请求列表**：查看收到的好友请求

### 1.2 设计原则

1. **粉丝身份隔离**：好友关系基于粉丝身份（star_id）
   - 用户在不同明星的身份下可以有不同的好友圈
   - 例如：用户 A 作为"肖战粉丝"的好友 ≠ 作为"王一博粉丝"的好友

2. **双向关系**：好友关系是双向的
   - A 添加 B 为好友，B 也会自动成为 A 的好友
   - 删除好友时，双方都会失去好友关系

3. **请求-确认机制**：
   - A 发送请求 → B 收到请求 → B 接受/拒绝 → 建立/不建立好友关系

4. **数据一致性**：
   - 使用外键约束保证数据完整性
   - 使用事务保证操作原子性

---

## 2. 数据库设计

### 2.1 好友关系表（friendships）

**用途**：存储已确认的好友关系

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY | 主键，自增 |
| user_id | BIGINT | NOT NULL, FK | 用户 ID |
| friend_id | BIGINT | NOT NULL, FK | 好友用户 ID |
| star_id | BIGINT | NOT NULL, FK | 粉丝身份（明星 ID）|
| status | VARCHAR(20) | NOT NULL | 状态：accepted（已接受）、blocked（已屏蔽）|
| remark | VARCHAR(50) | NULLABLE | 备注名（好友昵称）|
| intimacy | INT | DEFAULT 0 | 亲密度（预留字段）|
| created_at | BIGINT | NOT NULL | 创建时间（毫秒时间戳）|
| updated_at | BIGINT | NOT NULL | 更新时间（毫秒时间戳）|

**索引设计**：
```sql
-- 复合唯一索引（防止重复添加）
UNIQUE INDEX uk_friendships_user_friend_star (user_id, friend_id, star_id)

-- 查询索引（优化好友列表查询性能）
-- 索引1: 用于基础好友列表查询
INDEX idx_friendships_user_star_status (user_id, star_id, status)

-- 索引2: 用于按时间排序的好友列表查询
INDEX idx_friendships_user_star_created (user_id, star_id, created_at DESC)

-- 索引3: 覆盖索引，包含常用查询字段，避免回表查询
INDEX idx_friendships_list_query (user_id, star_id, status, friend_id, created_at, remark)

-- 索引4: 反向查询索引（查询谁把我加为好友）
INDEX idx_friendships_friend_star (friend_id, star_id)
```

**外键约束**：
```sql
-- 用户外键
CONSTRAINT fk_friendships_user 
    FOREIGN KEY (user_id) REFERENCES users(id) 
    ON DELETE CASCADE

-- 好友外键
CONSTRAINT fk_friendships_friend 
    FOREIGN KEY (friend_id) REFERENCES users(id) 
    ON DELETE CASCADE

-- 明星外键
CONSTRAINT fk_friendships_star 
    FOREIGN KEY (star_id) REFERENCES stars(star_id) 
    ON DELETE CASCADE
```

**检查约束**：
```sql
-- 不能添加自己为好友
CONSTRAINT chk_friendships_not_self 
    CHECK (user_id != friend_id)
```

**设计说明**：
- ✅ 双向存储：A→B 和 B→A 各存一条记录，便于查询
- ✅ 级联删除：用户被删除时，相关好友关系自动清理
- ✅ status 字段预留 blocked 状态，支持未来的屏蔽功能

---

### 2.2 好友请求表（friend_requests）

**用途**：存储好友请求的历史记录

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY | 主键，自增 |
| from_user_id | BIGINT | NOT NULL, FK | 请求发送者 ID |
| to_user_id | BIGINT | NOT NULL, FK | 请求接收者 ID |
| star_id | BIGINT | NOT NULL, FK | 粉丝身份（明星 ID）|
| message | VARCHAR(200) | NULLABLE | 请求附带消息 |
| status | VARCHAR(20) | NOT NULL | 状态：pending、accepted、rejected、expired |
| created_at | BIGINT | NOT NULL | 创建时间（毫秒时间戳）|
| updated_at | BIGINT | NOT NULL | 更新时间（毫秒时间戳）|
| expires_at | BIGINT | NULLABLE | 过期时间（毫秒时间戳）|
| processed_at | BIGINT | NULLABLE | 处理时间（毫秒时间戳）|

**索引设计**：
```sql
-- 查询索引（优化好友请求列表查询性能）
-- 索引1: 用于查询收到的请求（按状态筛选）
INDEX idx_friend_requests_to_status (to_user_id, status, created_at DESC)

-- 索引2: 用于查询发出的请求
INDEX idx_friend_requests_from_status (from_user_id, status, created_at DESC)

-- 索引3: 用于查询特定明星下的请求
INDEX idx_friend_requests_star (star_id)

-- 索引4: 用于定时任务扫描过期请求
INDEX idx_friend_requests_expires (expires_at, status)

-- 索引5: 用于查询两个用户之间的最近请求（防骚扰机制）
INDEX idx_friend_requests_users_star (from_user_id, to_user_id, star_id, created_at DESC)
```

**外键约束**：
```sql
-- 发送者外键
CONSTRAINT fk_friend_requests_from 
    FOREIGN KEY (from_user_id) REFERENCES users(id) 
    ON DELETE CASCADE

-- 接收者外键
CONSTRAINT fk_friend_requests_to 
    FOREIGN KEY (to_user_id) REFERENCES users(id) 
    ON DELETE CASCADE

-- 明星外键
CONSTRAINT fk_friend_requests_star 
    FOREIGN KEY (star_id) REFERENCES stars(star_id) 
    ON DELETE CASCADE
```

**检查约束**：
```sql
-- 不能请求自己为好友
CONSTRAINT chk_friend_requests_not_self 
    CHECK (from_user_id != to_user_id)
```

**设计说明**：
- ✅ 保留历史记录：即使请求被处理，记录仍保留（便于追溯）
- ✅ 过期机制：请求 30 天后自动过期（通过定时任务更新 status）
- ✅ processed_at：记录何时处理，便于统计响应时间

---

## 3. 业务流程设计

### 3.1 发送好友请求流程

```
┌─────────────────────────────────────────────────────────────┐
│                     发送好友请求                              │
└─────────────────────────────────────────────────────────────┘

用户 A                        系统                        用户 B
  │                            │                            │
  │──① 点击"添加好友"──────────→│                            │
  │                            │                            │
  │                            │──② 验证参数────────────────│
  │                            │   - A 和 B 是否是同一人？    │
  │                            │   - B 是否存在？            │
  │                            │   - B 是否有该粉丝身份？     │
  │                            │                            │
  │                            │──③ 检查关系状态────────────│
  │                            │   - 是否已经是好友？        │
  │                            │   - 是否有未处理的请求？     │
  │                            │                            │
  │                            │──④ 创建好友请求────────────│
  │                            │   INSERT INTO friend_requests│
  │                            │   status = 'pending'       │
  │                            │                            │
  │←─⑤ 返回成功──────────────│                            │
  │   "好友请求已发送"           │                            │
  │                            │                            │
  │                            │──⑥ 推送通知（可选）────────→│
  │                            │   "您收到来自 A 的好友请求"   │
  │                            │                            │
```

**关键验证**：
1. ✅ 不能添加自己为好友
2. ✅ 目标用户必须存在
3. ✅ 目标用户必须有该粉丝身份
4. ✅ 检查是否已经是好友
5. ✅ **检查历史请求记录（防骚扰机制）**：
   - 查询最近的请求记录（所有状态）
   - 如果有 `pending` 请求 → 提示"已发送过请求"
   - 如果有 `rejected` 请求 → 检查是否过了冷却期（7天）
   - 如果有 `accepted` 请求 → 提示"已经是好友"

**异常处理**：
- 目标用户不存在 → 返回 404 "用户不存在"
- 目标用户没有该粉丝身份 → 返回 400 "对方没有该粉丝身份"
- 已经是好友 → 返回 400 "已经是好友"
- 已有未处理的请求 → 返回 400 "已发送过好友请求，请等待对方处理"
- 请求被拒绝且在冷却期内 → 返回 400 "请求已被拒绝，请 X 天后再试"

---

### 3.1.1 防骚扰机制详解

**问题**：如何防止用户被重复骚扰？

**解决方案**：基于请求历史的冷却期机制

#### 检查逻辑流程图

```
发送好友请求
    ↓
查询最近的请求记录（同 star_id 下）
    ↓
是否有历史请求？
    ├─ 否 → ✅ 允许发送
    └─ 是 ↓
         检查请求状态
         ├─ pending → ❌ "已发送过请求，请等待对方处理"
         ├─ accepted → ❌ "已经是好友"
         ├─ expired → ✅ 允许发送新请求
         └─ rejected ↓
              计算距离 processed_at 的时间
              ├─ < 7天 → ❌ "请求已被拒绝，请 X 天后再试"
              └─ ≥ 7天 → ✅ 允许发送新请求
```

#### 实现代码示例

```go
func (s *friendService) SendFriendRequest(req *pb.SendFriendRequestRequest, userID, starID int64) (*pb.SendFriendRequestResponse, error) {
    // ... 前置验证 ...
    
    // 检查历史请求记录
    latestRequest, err := s.friendRepo.GetLatestRequest(userID, req.FriendUserId, starID)
    if err != nil && !errors.Is(err, appErrors.ErrRequestNotFound) {
        return nil, err
    }
    
    if latestRequest != nil {
        switch latestRequest.Status {
        case "pending":
            return nil, errors.New("已发送过好友请求，请等待对方处理")
            
        case "accepted":
            return nil, errors.New("已经是好友")
            
        case "rejected":
            // 检查冷却期（7天 = 7 * 24 * 60 * 60 * 1000 毫秒）
            cooldownPeriod := int64(7 * 24 * 60 * 60 * 1000)
            now := time.Now().UnixMilli()
            
            if latestRequest.ProcessedAt != nil {
                timeSinceRejection := now - *latestRequest.ProcessedAt
                if timeSinceRejection < cooldownPeriod {
                    remainingDays := (cooldownPeriod - timeSinceRejection) / (24 * 60 * 60 * 1000)
                    return nil, fmt.Errorf("请求已被拒绝，请 %d 天后再试", remainingDays+1)
                }
            }
            
        case "expired":
            // 过期的请求可以重新发送
            break
        }
    }
    
    // 创建新请求...
}
```

#### 配置参数

所有时间限制配置已统一管理在 `backend/services/friendService/config/friend_config.go` 中：

```go
// FriendConfig 好友功能配置
type FriendConfig struct {
    TimeConstraints TimeConstraints  // 时间限制配置
    FriendLimit     FriendLimitConfig // 好友数量限制(预留)
}

// TimeConstraints 时间约束配置
type TimeConstraints struct {
    RejectionCooldownDays   int   // 被拒绝后的冷却期(天数) = 7天
    RequestExpiryDays       int   // 好友请求的过期时间(天数) = 30天
    RejectionCooldownMillis int64 // 被拒绝后的冷却期(毫秒)
    RequestExpiryMillis     int64 // 好友请求的过期时间(毫秒)
}
```

**配置说明**：
- ✅ 统一管理所有时间限制，便于维护
- ✅ 便于后续迁移到规则表进行动态配置
- ✅ 提供了丰富的辅助方法（计算剩余天数、检查是否过期等）

**使用示例**：
```go
// 初始化配置
config.InitFriendConfig()

// 检查是否在冷却期内
if config.GlobalFriendConfig.IsInCooldownPeriod(rejectedAtMillis) {
    remainingDays := config.GlobalFriendConfig.CalculateRemainingCooldownDays(rejectedAtMillis)
    return fmt.Errorf("请求已被拒绝，请 %d 天后再试", remainingDays)
}
```

---

### 3.2 接受好友请求流程

```
┌─────────────────────────────────────────────────────────────┐
│                     接受好友请求                              │
└─────────────────────────────────────────────────────────────┘

用户 A                        系统                        用户 B
  │                            │                            │
  │                            │←─① 点击"接受"──────────────│
  │                            │                            │
  │                            │──② 验证请求────────────────│
  │                            │   - 请求是否存在？          │
  │                            │   - 请求状态是否为 pending？ │
  │                            │   - 请求是否已过期？         │
  │                            │                            │
  │                            │──③ 开启事务────────────────│
  │                            │                            │
  │                            │──④ 更新请求状态────────────│
  │                            │   UPDATE friend_requests   │
  │                            │   status = 'accepted'      │
  │                            │   processed_at = now()     │
  │                            │                            │
  │                            │──⑤ 创建双向好友关系─────────│
  │                            │   INSERT INTO friendships  │
  │                            │   (A→B) status='accepted' │
  │                            │   (B→A) status='accepted' │
  │                            │                            │
  │                            │──⑥ 更新好友数量────────────│
  │                            │   UPDATE fan_profiles      │
  │                            │   social = social + 1      │
  │                            │   (A 和 B 的 social 字段)   │
  │                            │                            │
  │                            │──⑦ 提交事务────────────────│
  │                            │                            │
  │←─⑧ 推送通知（可选）───────────│                            │
  │   "B 接受了您的好友请求"       │                            │
  │                            │                            │
  │                            │──⑨ 返回成功─────────────→│
  │                            │   "已添加为好友"            │
  │                            │                            │
```

**关键操作**：
1. ✅ 使用事务保证原子性
2. ✅ 创建双向好友关系（A→B 和 B→A）
3. ✅ 更新 fan_profiles 表的 social 字段（好友数量）
4. ✅ 更新请求状态为 accepted

**异常处理**：
- 请求不存在 → 返回 404 "好友请求不存在"
- 请求已被处理 → 返回 400 "该请求已被处理"
- 请求已过期 → 返回 400 "该请求已过期"
- 事务失败 → 回滚所有操作，返回 500 "操作失败"

---

### 3.3 拒绝好友请求流程

```
┌─────────────────────────────────────────────────────────────┐
│                     拒绝好友请求                              │
└─────────────────────────────────────────────────────────────┘

用户 A                        系统                        用户 B
  │                            │                            │
  │                            │←─① 点击"拒绝"──────────────│
  │                            │                            │
  │                            │──② 验证请求────────────────│
  │                            │   - 请求是否存在？          │
  │                            │   - 请求状态是否为 pending？ │
  │                            │                            │
  │                            │──③ 更新请求状态────────────│
  │                            │   UPDATE friend_requests   │
  │                            │   status = 'rejected'      │
  │                            │   processed_at = now()     │
  │                            │                            │
  │                            │──④ 返回成功─────────────→│
  │                            │   "已拒绝好友请求"          │
  │                            │                            │
```

**关键操作**：
1. ✅ 只更新请求状态，不创建好友关系
2. ✅ 不通知请求发送者（避免尴尬）
3. ✅ 保留拒绝记录（可用于防骚扰）

---

### 3.4 删除好友流程

```
┌─────────────────────────────────────────────────────────────┐
│                       删除好友                               │
└─────────────────────────────────────────────────────────────┘

用户 A                        系统                        用户 B
  │                            │                            │
  │──① 点击"删除好友"──────────→│                            │
  │                            │                            │
  │                            │──② 验证好友关系────────────│
  │                            │   - 是否是好友？            │
  │                            │   - 关系是否存在？          │
  │                            │                            │
  │                            │──③ 开启事务────────────────│
  │                            │                            │
  │                            │──④ 删除双向好友关系─────────│
  │                            │   DELETE FROM friendships  │
  │                            │   WHERE (user_id=A AND friend_id=B)│
  │                            │   OR (user_id=B AND friend_id=A)│
  │                            │   AND star_id = X          │
  │                            │                            │
  │                            │──⑤ 更新好友数量────────────│
  │                            │   UPDATE fan_profiles      │
  │                            │   social = social - 1      │
  │                            │   (A 和 B 的 social 字段)   │
  │                            │                            │
  │                            │──⑥ 提交事务────────────────│
  │                            │                            │
  │←─⑦ 返回成功──────────────│                            │
  │   "已删除好友"               │                            │
  │                            │                            │
  │                            │──⑧ 推送通知（可选）────────→│
  │                            │   "A 已将您从好友列表移除"    │
  │                            │                            │
```

**关键操作**：
1. ✅ 使用事务保证原子性
2. ✅ 删除双向好友关系（A→B 和 B→A）
3. ✅ 更新 fan_profiles 表的 social 字段（减少好友数量）
4. ✅ 可选通知对方（根据产品需求决定）

**异常处理**：
- 好友关系不存在 → 返回 404 "好友关系不存在"
- 事务失败 → 回滚所有操作，返回 500 "操作失败"

---

## 4. API 接口设计

### 4.1 发送好友请求

**接口**：`POST /api/v1/friends/requests`

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
```

**请求体**：
```json
{
  "friend_user_id": 123,
  "message": "你好，我是你的粉丝，想和你成为好友"  // 可选
}
```

**成功响应**（200）：
```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "request_id": 456,
    "status": "pending",
    "created_at": 1704441600000
  }
}
```

**错误响应**：
```json
// 400 - 已经是好友
{
  "code": 400,
  "message": "已经是好友"
}

// 400 - 已发送过请求
{
  "code": 400,
  "message": "已发送过好友请求，请等待对方处理"
}

// 404 - 用户不存在
{
  "code": 404,
  "message": "用户不存在"
}
```

---

### 4.2 获取好友请求列表

**接口**：`GET /api/v1/friends/requests`

**请求头**：
```http
Authorization: Bearer <access_token>
```

**查询参数**：
```
type=received    // 收到的请求（默认）或 sent（发出的请求）
status=pending   // 请求状态（可选）：pending, accepted, rejected, all
page=1           // 页码（可选，默认 1）
page_size=20     // 每页数量（可选，默认 20）
```

**成功响应**（200）：
```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "request_id": 456,
        "user_id": 123,
        "nickname": "粉丝小明",
        "avatar_url": "https://...",
        "message": "你好，我是你的粉丝",
        "status": "pending",
        "created_at": 1704441600000,
        "expires_at": 1707033600000
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 20
  }
}
```

---

### 4.3 处理好友请求（接受/拒绝）

**接口**：`POST /api/v1/friends/requests/{request_id}/handle`

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
```

**请求体**：
```json
{
  "action": "accept"  // accept（接受）或 reject（拒绝）
}
```

**成功响应**（200）：
```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "action": "accept",
    "friendship_created": true  // 仅在 accept 时有此字段
  }
}
```

**错误响应**：
```json
// 404 - 请求不存在
{
  "code": 404,
  "message": "好友请求不存在"
}

// 400 - 请求已被处理
{
  "code": 400,
  "message": "该请求已被处理"
}
```

---

### 4.4 获取好友列表

**接口**：`GET /api/v1/friends`

**请求头**：
```http
Authorization: Bearer <access_token>
```

**查询参数**：
```
keyword=小明     // 搜索关键词（可选）
page=1          // 页码（可选，默认 1）
page_size=20    // 每页数量（可选，默认 20）
```

**成功响应**（200）：
```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "user_id": 123,
        "nickname": "粉丝小明",
        "avatar_url": "https://...",
        "remark": "我的好友",  // 备注名（如果有）
        "fan_level": 2,
        "intimacy": 100,  // 亲密度（预留字段）
        "created_at": 1704441600000  // 成为好友的时间
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  }
}
```

---

### 4.5 删除好友

**接口**：`DELETE /api/v1/friends/{user_id}`

**请求头**：
```http
Authorization: Bearer <access_token>
```

**成功响应**（200）：
```json
{
  "code": 200,
  "message": "ok",
  "data": {}
}
```

**错误响应**：
```json
// 404 - 好友关系不存在
{
  "code": 404,
  "message": "好友关系不存在"
}
```

---

### 4.6 设置好友备注

**接口**：`PUT /api/v1/friends/{user_id}/remark`

**请求头**：
```http
Authorization: Bearer <access_token>
Content-Type: application/json
```

**请求体**：
```json
{
  "remark": "我的好朋友"  // 最大 50 个字符
}
```

**成功响应**（200）：
```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "remark": "我的好朋友"
  }
}
```

---

## 5. 状态机设计

### 5.1 好友请求状态转换

```
                    ┌─────────────┐
                    │             │
          创建请求  │   pending   │
          ────────→│  (待处理)    │
                    │             │
                    └─────┬───┬───┘
                          │   │
                   接受   │   │   拒绝
                    ↓     │   │     ↓
            ┌──────────┐ │   │ ┌──────────┐
            │          │ │   │ │          │
            │ accepted │ │   │ │ rejected │
            │ (已接受)  │ │   │ │ (已拒绝)  │
            │          │ │   │ │          │
            └──────────┘ │   │ └──────────┘
                         │   │
                         │   │   30天后
                         │   └────────→
                         │         ┌──────────┐
                         │         │          │
                         └────────→│ expired  │
                                   │ (已过期)  │
                                   │          │
                                   └──────────┘
```

**状态说明**：
- `pending`：待处理（初始状态）
- `accepted`：已接受（终态，好友关系已建立）
- `rejected`：已拒绝（终态）
- `expired`：已过期（终态，通过定时任务自动更新）

**状态转换规则**：
1. ✅ `pending` → `accepted`：接受好友请求
2. ✅ `pending` → `rejected`：拒绝好友请求
3. ✅ `pending` → `expired`：30 天未处理自动过期
4. ❌ 终态不能再转换

---

### 5.2 好友关系状态

```
            ┌──────────┐
    创建关系│          │
    ───────→│ accepted │──┐ 删除好友
            │ (已接受)  │  │ ────────→ [关系记录被删除]
            │          │←─┘
            └─────┬────┘
                  │
                  │ 屏蔽（预留功能）
                  ↓
            ┌──────────┐
            │          │
            │ blocked  │
            │ (已屏蔽)  │
            │          │
            └──────────┘
```

**状态说明**：
- `accepted`：正常好友关系
- `blocked`：已屏蔽（预留字段，暂不实现）

---

## 6. 实现步骤

### 阶段 1：数据层（Model & Repository）

#### 步骤 1.1：创建数据模型

**文件**：`backend/pkg/models/friend.go`

**内容**：
- [ ] 定义 `Friendship` 结构体
- [ ] 定义 `FriendRequest` 结构体
- [ ] 添加 `BeforeCreate` 和 `BeforeUpdate` 钩子
- [ ] 添加表名映射方法

---

#### 步骤 1.2：创建 Repository

**文件**：`backend/services/friendService/repository/friend_repository.go`

**接口定义**：
```go
type FriendRepository interface {
    // 好友请求相关
    CreateRequest(request *models.FriendRequest) error
    GetRequestByID(requestID int64) (*models.FriendRequest, error)
    GetRequestsByUser(userID, starID int64, requestType string, status string) ([]*models.FriendRequest, error)
    GetLatestRequest(fromUserID, toUserID, starID int64) (*models.FriendRequest, error) // 新增：获取最近的请求记录
    UpdateRequestStatus(requestID int64, status string) error
    
    // 好友关系相关
    CreateFriendship(friendship *models.Friendship) error
    GetFriendship(userID, friendID, starID int64) (*models.Friendship, error)
    GetFriendsByUser(userID, starID int64) ([]*models.Friendship, error)
    DeleteFriendship(userID, friendID, starID int64) error
    UpdateRemark(userID, friendID, starID int64, remark string) error
    CountFriends(userID, starID int64) (int64, error)
}
```

**任务清单**：
- [ ] 实现 `CreateRequest` 方法
- [ ] 实现 `GetRequestByID` 方法
- [ ] 实现 `GetRequestsByUser` 方法
- [ ] 实现 `GetLatestRequest` 方法（获取两个用户之间最近的请求记录）
- [ ] 实现 `UpdateRequestStatus` 方法
- [ ] 实现 `CreateFriendship` 方法
- [ ] 实现 `GetFriendship` 方法
- [ ] 实现 `GetFriendsByUser` 方法
- [ ] 实现 `DeleteFriendship` 方法
- [ ] 实现 `UpdateRemark` 方法
- [ ] 实现 `CountFriends` 方法

---

### 阶段 2：服务层（Service）

#### 步骤 2.1：定义 Proto

**文件**：`backend/proto/friend/friend.proto`

**内容**：
- [ ] 定义好友请求相关的 Message
- [ ] 定义好友关系相关的 Message
- [ ] 定义 FriendService RPC 接口

---

#### 步骤 2.2：实现 Service

**文件**：`backend/services/friendService/service/friend_service.go`

**接口定义**：
```go
type FriendService interface {
    // 发送好友请求
    SendFriendRequest(req *pb.SendFriendRequestRequest, userID, starID int64) (*pb.SendFriendRequestResponse, error)
    
    // 获取好友请求列表
    GetFriendRequests(req *pb.GetFriendRequestsRequest, userID, starID int64) (*pb.GetFriendRequestsResponse, error)
    
    // 处理好友请求（接受/拒绝）
    HandleFriendRequest(req *pb.HandleFriendRequestRequest, userID, starID int64) (*pb.HandleFriendRequestResponse, error)
    
    // 获取好友列表
    GetFriendList(req *pb.GetFriendListRequest, userID, starID int64) (*pb.GetFriendListResponse, error)
    
    // 删除好友
    DeleteFriend(req *pb.DeleteFriendRequest, userID, starID int64) (*pb.DeleteFriendResponse, error)
    
    // 设置好友备注
    SetFriendRemark(req *pb.SetFriendRemarkRequest, userID, starID int64) (*pb.SetFriendRemarkResponse, error)
}
```

**任务清单**：
- [ ] 实现 `SendFriendRequest` 方法
  - [ ] 参数验证（不能添加自己为好友）
  - [ ] 检查目标用户是否存在（RPC 调用 userService）
  - [ ] 检查目标用户是否有该粉丝身份（RPC 调用 userService）
  - [ ] 检查是否已是好友
  - [ ] **检查历史请求记录（防骚扰机制）**：
    - [ ] 调用 `GetLatestRequest` 获取最近的请求
    - [ ] 如果状态为 `pending`：返回"已发送过请求"
    - [ ] 如果状态为 `rejected`：检查 `processed_at` 是否过了冷却期（7天）
    - [ ] 如果状态为 `accepted`：返回"已经是好友"
    - [ ] 如果状态为 `expired`：允许发送新请求
  - [ ] 创建好友请求记录
  
- [ ] 实现 `GetFriendRequests` 方法
  - [ ] 查询好友请求列表
  - [ ] 支持分页
  - [ ] 支持按状态筛选
  
- [ ] 实现 `HandleFriendRequest` 方法
  - [ ] 验证请求存在且状态为 pending
  - [ ] 如果是接受：
    - [ ] 使用事务
    - [ ] 更新请求状态
    - [ ] 创建双向好友关系
    - [ ] 更新 social 字段
  - [ ] 如果是拒绝：
    - [ ] 更新请求状态
  
- [ ] 实现 `GetFriendList` 方法
  - [ ] 查询好友列表
  - [ ] 支持分页
  - [ ] 支持关键词搜索
  - [ ] 关联查询用户信息
  
- [ ] 实现 `DeleteFriend` 方法
  - [ ] 使用事务
  - [ ] 删除双向好友关系
  - [ ] 更新 social 字段
  
- [ ] 实现 `SetFriendRemark` 方法
  - [ ] 更新备注名

---

#### 步骤 2.3：创建 friendService 主程序

**文件**：`backend/services/friendService/main.go`

**任务清单**：
- [ ] 初始化日志
- [ ] 初始化数据库连接
- [ ] 运行数据库迁移
- [ ] 初始化 Repository
- [ ] 初始化 Service
- [ ] 注册 Dubbo 服务
- [ ] 启动服务

---

### 阶段 3：网关层（Gateway）

#### 步骤 3.1：创建 DTO

**文件**：`backend/gateway/dto/friend_dto.go`

**任务清单**：
- [ ] 定义 `FriendRequestDTO`
- [ ] 定义 `FriendDTO`
- [ ] 定义各个响应 DTO

---

#### 步骤 3.2：创建转换器

**文件**：`backend/gateway/dto/friend_converter.go`

**任务清单**：
- [ ] 实现 Proto → DTO 转换函数

---

#### 步骤 3.3：创建 Controller

**文件**：`backend/gateway/controller/friend_controller.go`

**任务清单**：
- [ ] 实现 `SendFriendRequest` 方法
- [ ] 实现 `GetFriendRequests` 方法
- [ ] 实现 `HandleFriendRequest` 方法
- [ ] 实现 `GetFriendList` 方法
- [ ] 实现 `DeleteFriend` 方法
- [ ] 实现 `SetFriendRemark` 方法

---

#### 步骤 3.4：配置路由

**文件**：`backend/gateway/router/router.go`

**任务清单**：
- [ ] 添加好友相关路由

---

### 阶段 4：测试与优化

#### 步骤 4.1：单元测试

**任务清单**：
- [ ] Repository 层测试
- [ ] Service 层测试

---

#### 步骤 4.2：集成测试

**任务清单**：
- [ ] 测试发送好友请求
- [ ] 测试接受好友请求
- [ ] 测试拒绝好友请求
- [ ] 测试删除好友
- [ ] 测试查询好友列表
- [ ] 测试边界情况

---

#### 步骤 4.3：性能优化

**任务清单**：
- [ ] 添加数据库索引
- [ ] 优化 SQL 查询
- [ ] 添加缓存（可选）

---

## 7. 设计决策（已确认）✅

### 7.1 业务逻辑决策

#### 决策 1：好友数量限制 ✅

**问题**：是否需要限制好友数量？

**最终决策**：**暂不限制，后续引入规则表动态配置**

**理由**：
- ✅ 初期不限制，简化实现
- ✅ 预留扩展性，后续可通过规则表根据用户等级、会员状态等动态限制
- ✅ 在配置文件中预留了 `FriendLimitConfig` 结构体

**实现要点**：
- 在 `friend_config.go` 中预留了好友数量限制的配置项
- `FriendLimit.Enabled = false`（默认不启用）
- 后续可通过规则表动态调整每个用户的好友数量上限

---

#### 决策 2：重复请求策略 ⭐ **关键业务逻辑** ✅

**问题**：如果 A 的请求被 B 拒绝后，A 多久可以再次发送请求？

**最终决策**：**7 天后可以再次发送**

**理由**：
- ✅ 防止用户被重复骚扰
- ✅ 7 天是合理的冷却期（既不太短也不太长）
- ✅ 给用户二次机会（可能第一次拒绝是误操作）

**实现要点**（已在文档 3.1.1 节详细说明）：
1. 查询最近的请求记录（所有状态）
2. 如果状态为 `rejected`，检查 `processed_at` 距今是否超过 7 天
3. 未超过冷却期：返回 429 错误 + 剩余天数提示
4. 已超过冷却期：允许发送新请求

**配置位置**：
- `friend_config.go` → `TimeConstraints.RejectionCooldownDays = 7`
- 便于后续迁移到规则表

---

#### 决策 3：请求过期时间 ✅

**问题**：好友请求多久后自动过期？

**最终决策**：**30 天**

**理由**：
- ✅ 30 天是合理的等待期
- ✅ 避免请求列表堆积过多过期请求
- ✅ 给接收者足够的时间考虑

**实现要点**：
- 创建请求时，设置 `expires_at = created_at + 30天`
- 定时任务扫描过期请求，更新状态为 `expired`

**配置位置**：
- `friend_config.go` → `TimeConstraints.RequestExpiryDays = 30`
- 便于后续迁移到规则表

---

#### 决策 4：删除好友通知 ✅

**问题**：删除好友时，是否通知对方？

**最终决策**：**不通知对方（静默删除）**

**理由**：
- ✅ 避免尴尬和不必要的冲突
- ✅ 符合大多数社交产品的设计习惯
- ✅ 对方在下次查看好友列表时会自然发现

**实现要点**：
- 删除好友时，只删除双向关系记录
- 不发送任何推送通知
- 不在对方界面显示"已解除好友关系"

---

#### 决策 5：好友关系的数据保留 ✅

**问题**：删除好友后，是否保留历史关系记录？

**最终决策**：**完全删除（物理删除）**

**理由**：
- ✅ 简化数据模型，无需软删除字段
- ✅ 减少数据库存储压力
- ✅ 符合用户预期（删除就是删除）

**实现要点**：
- 使用 `DELETE FROM friendships WHERE ...`
- 同时删除双向关系（A→B 和 B→A）
- 更新 `fan_profiles` 表的 `social` 字段（好友数量 -1）

---

### 7.2 技术实现决策

#### 决策 6：好友列表查询优化 ✅

**问题**：好友列表可能很大，如何优化查询性能？

**最终决策**：**支持分页查询 + 添加数据库索引**

**实现方案**：
- ✅ **分页查询**：支持 `page` 和 `page_size` 参数
- ✅ **数据库索引**：添加以下索引优化查询
  ```sql
  -- 1. 复合索引：user_id + star_id + status (用于查询某用户在某明星下的好友列表)
  CREATE INDEX idx_friendships_user_star_status ON friendships(user_id, star_id, status);
  
  -- 2. 复合索引：user_id + star_id + created_at (用于按时间排序)
  CREATE INDEX idx_friendships_user_star_created ON friendships(user_id, star_id, created_at DESC);
  
  -- 3. 覆盖索引：包含常用查询字段，避免回表
  CREATE INDEX idx_friendships_list_query ON friendships(user_id, star_id, status, friend_id, created_at, remark);
  ```
- ✅ **关键词搜索优化**：
  - 如果有 `keyword` 参数，需要 JOIN `fan_profiles` 表查询昵称
  - 添加索引：`CREATE INDEX idx_fan_profiles_nickname ON fan_profiles(nickname);`
- ✅ **预加载用户信息**：避免 N+1 查询
  - 使用 `LEFT JOIN` 一次性查询好友的用户信息
  - 或使用 `IN` 查询批量获取用户信息

**查询示例**：
```sql
-- 基础查询（无关键词）
SELECT f.friend_id, f.remark, f.intimacy, f.created_at,
       fp.nickname, fp.avatar_url, fp.fan_level
FROM friendships f
LEFT JOIN fan_profiles fp ON f.friend_id = fp.user_id AND f.star_id = fp.star_id
WHERE f.user_id = ? AND f.star_id = ? AND f.status = 'accepted'
ORDER BY f.created_at DESC
LIMIT ? OFFSET ?;

-- 带关键词搜索
SELECT f.friend_id, f.remark, f.intimacy, f.created_at,
       fp.nickname, fp.avatar_url, fp.fan_level
FROM friendships f
LEFT JOIN fan_profiles fp ON f.friend_id = fp.user_id AND f.star_id = fp.star_id
WHERE f.user_id = ? AND f.star_id = ? AND f.status = 'accepted'
  AND (f.remark LIKE ? OR fp.nickname LIKE ?)
ORDER BY f.created_at DESC
LIMIT ? OFFSET ?;
```

**性能预期**：
- 无关键词查询：使用覆盖索引，性能极佳
- 带关键词查询：使用 `idx_fan_profiles_nickname` 索引，性能良好
- 分页查询：避免一次性加载大量数据

---

#### 决策 7：并发控制 ✅

**问题**：如何处理并发请求的冲突？

**最终决策**：**使用数据库事务保证原子性**

**实现方案**：
- ✅ **唯一索引防止重复记录**：
  ```sql
  CONSTRAINT uk_friendships_user_friend_star 
      UNIQUE (user_id, friend_id, star_id)
  ```
- ✅ **使用数据库事务**：
  - 接受好友请求：事务包含（更新请求状态 + 创建双向好友关系 + 更新 social 字段）
  - 删除好友：事务包含（删除双向好友关系 + 更新 social 字段）
- ✅ **事务隔离级别**：使用 `READ COMMITTED`（PostgreSQL 默认）
- ✅ **错误处理**：
  - 唯一索引冲突 → 返回"已经是好友"
  - 事务失败 → 回滚所有操作，返回 500 错误

**并发场景处理**：
1. **A 和 B 同时向对方发送请求**：
   - 允许两个请求都创建成功
   - 任一方接受后，双方都成为好友
   
2. **A 删除好友的同时，B 也在删除**：
   - 使用事务保证原子性
   - 第一个事务成功，第二个事务会因为记录不存在而失败
   - 返回友好的错误提示

---

#### 决策 8：跨服务调用 ✅

**问题**：friendService 需要验证用户信息，如何调用 userService？

**最终决策**：**通过 Dubbo RPC 调用**

**实现方案**：
- ✅ **创建 userService 客户端**：
  ```go
  type UserServiceClient interface {
      // 验证用户是否存在
      ValidateUser(ctx context.Context, userID int64) (bool, error)
      
      // 验证用户是否有指定的粉丝身份
      ValidateFanProfile(ctx context.Context, userID, starID int64) (bool, error)
      
      // 批量获取用户信息（用于好友列表展示）
      GetUsersByIDs(ctx context.Context, userIDs []int64) ([]*pb.UserInfo, error)
  }
  ```

- ✅ **调用时机**：
  - 发送好友请求前：验证目标用户是否存在 + 是否有该粉丝身份
  - 获取好友列表时：批量获取好友的用户信息

- ✅ **错误处理**：
  - RPC 调用失败 → 返回 500 错误
  - 用户不存在 → 返回 404 错误
  - 用户没有该粉丝身份 → 返回 400 错误

- ✅ **性能优化**：
  - 使用批量查询接口（`GetUsersByIDs`）避免 N+1 问题
  - 考虑添加本地缓存（Redis）缓存用户基本信息

---

### 7.3 扩展功能（可选）

#### 功能 1：好友分组

**描述**：支持将好友分组管理（如"亲友"、"同城"等）

**优先级**：低

---

#### 功能 2：好友推荐

**描述**：基于共同好友、兴趣等推荐可能认识的人

**优先级**：中

---

#### 功能 3：屏蔽功能

**描述**：屏蔽某人后，对方无法向你发送好友请求

**优先级**：中

---

#### 功能 4：亲密度系统

**描述**：根据互动频率计算好友亲密度

**优先级**：低

---

## 8. 附录

### 8.1 数据库脚本

#### 创建 friendships 表

```sql
CREATE TABLE friendships (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL,
    friend_id BIGINT NOT NULL,
    star_id BIGINT NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'accepted',
    remark VARCHAR(50),
    intimacy INT DEFAULT 0,
    created_at BIGINT NOT NULL,
    updated_at BIGINT NOT NULL,
    
    CONSTRAINT fk_friendships_user 
        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    CONSTRAINT fk_friendships_friend 
        FOREIGN KEY (friend_id) REFERENCES users(id) ON DELETE CASCADE,
    CONSTRAINT fk_friendships_star 
        FOREIGN KEY (star_id) REFERENCES stars(star_id) ON DELETE CASCADE,
    CONSTRAINT uk_friendships_user_friend_star 
        UNIQUE (user_id, friend_id, star_id),
    CONSTRAINT chk_friendships_not_self 
        CHECK (user_id != friend_id)
);

-- 查询索引（优化好友列表查询性能）
CREATE INDEX idx_friendships_user_star_status ON friendships(user_id, star_id, status);
CREATE INDEX idx_friendships_user_star_created ON friendships(user_id, star_id, created_at DESC);
CREATE INDEX idx_friendships_list_query ON friendships(user_id, star_id, status, friend_id, created_at, remark);
CREATE INDEX idx_friendships_friend_star ON friendships(friend_id, star_id);
```

#### 创建 friend_requests 表

```sql
CREATE TABLE friend_requests (
    id BIGSERIAL PRIMARY KEY,
    from_user_id BIGINT NOT NULL,
    to_user_id BIGINT NOT NULL,
    star_id BIGINT NOT NULL,
    message VARCHAR(200),
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    created_at BIGINT NOT NULL,
    updated_at BIGINT NOT NULL,
    expires_at BIGINT,
    processed_at BIGINT,
    
    CONSTRAINT fk_friend_requests_from 
        FOREIGN KEY (from_user_id) REFERENCES users(id) ON DELETE CASCADE,
    CONSTRAINT fk_friend_requests_to 
        FOREIGN KEY (to_user_id) REFERENCES users(id) ON DELETE CASCADE,
    CONSTRAINT fk_friend_requests_star 
        FOREIGN KEY (star_id) REFERENCES stars(star_id) ON DELETE CASCADE,
    CONSTRAINT chk_friend_requests_not_self 
        CHECK (from_user_id != to_user_id)
);

-- 查询索引（优化好友请求列表查询性能）
CREATE INDEX idx_friend_requests_to_status ON friend_requests(to_user_id, status, created_at DESC);
CREATE INDEX idx_friend_requests_from_status ON friend_requests(from_user_id, status, created_at DESC);
CREATE INDEX idx_friend_requests_star ON friend_requests(star_id);
CREATE INDEX idx_friend_requests_expires ON friend_requests(expires_at, status);
CREATE INDEX idx_friend_requests_users_star ON friend_requests(from_user_id, to_user_id, star_id, created_at DESC);
```

---

### 8.2 错误码定义

| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|--------|---------|------------|------|
| 20001 | 用户不存在 | 404 | 目标用户不存在 |
| 20002 | 对方没有该粉丝身份 | 400 | 目标用户没有指定的粉丝身份 |
| 20003 | 已经是好友 | 400 | 不能重复添加好友 |
| 20004 | 已发送过好友请求 | 400 | 已有未处理的好友请求 |
| 20005 | 好友请求不存在 | 404 | 请求 ID 不存在 |
| 20006 | 该请求已被处理 | 400 | 请求已经被接受或拒绝 |
| 20007 | 该请求已过期 | 400 | 请求已过期 |
| 20008 | 好友关系不存在 | 404 | 不是好友关系 |
| 20009 | 不能添加自己为好友 | 400 | 参数错误 |
| 20010 | 已达到好友数量上限 | 400 | 好友数量已达上限 |
| 20011 | 请求被拒绝，冷却期内 | 429 | 请求已被拒绝，请X天后再试 |

---

## 9. 变更历史

| 版本 | 日期 | 作者 | 变更内容 |
|------|------|------|---------|
| v0.1 | 2026-01-05 | System | 初始版本，包含基础设计 |
| v1.0 | 2026-01-06 | System | 确认所有设计决策，完善索引设计，创建配置文件 |

**v1.0 详细变更**：
- ✅ 确认问题1：暂不限制好友数量，后续引入规则表
- ✅ 确认问题2：7天冷却期，配置在 `friend_config.go`
- ✅ 确认问题3：30天过期时间，配置在 `friend_config.go`
- ✅ 确认问题4：删除好友不通知对方
- ✅ 确认问题5：完全删除好友关系
- ✅ 确认问题6：添加完整的数据库索引设计，支持分页查询
- ✅ 确认问题7：使用数据库事务保证原子性
- ✅ 确认问题8：通过 Dubbo RPC 调用 userService
- ✅ 创建 `friend_config.go` 统一管理时间限制配置
- ✅ 优化数据库索引设计（friendships 表 4个索引，friend_requests 表 5个索引）

---

## 10. 后续工作

- [x] 用户补充设计想法和修改意见 ✅
- [x] 根据反馈修订设计方案 ✅
- [x] 确定最终实现方案 ✅
- [ ] 开始编码实现（按照实现步骤章节执行）

---

**📝 设计方案已确认，可以开始实现了！** ✅

---