feat(chat): add ChatBubble widget and mock data for home screen

- Add ChatBubble reusable widget for chat messages - Add HomeMockData for chat list mock data - Add HomeScreen widget tests - Add AG-UI chat design and implementation plan docs - Add friendship design docs - Ignore backend/logs directory
2026-02-28 14:47:33 +08:00
parent 534efd182b
commit c3192a2431
8 changed files with 4475 additions and 0 deletions
@@ -0,0 +1,567 @@
+# AG-UI 聊天功能设计文档
+
+## 1. 概述
+
+本文档描述如何使用 AG-UI 协议实现 AI 聊天功能，包括：
+- 消息的发送与接收（通过 AG-UI 事件流）
+- AI 工具调用（Tool Call）机制
+- 日历卡片作为 Tool Result 渲染
+- 前端工具注册与执行
+- 本地持久化
+
+## 2. 架构设计
+
+### 2.1 整体流程
+
+```
+用户输入消息
+    ↓
+AgUiService.sendMessage()
+    ↓
+[Mock Mode] 规则引擎决策 → 事件流模拟
+[Real Mode] POST /api/chat → SSE 监听
+    ↓
+┌─────────────────────────────────────────────────────────────┐
+│  AG-UI Event Stream (按序处理)                              │
+├─────────────────────────────────────────────────────────────┤
+│  TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT* → TEXT_MESSAGE_END │
+│  TOOL_CALL_START → TOOL_CALL_ARGS* → TOOL_CALL_END          │
+│  TOOL_CALL_RESULT                                            │
+│  RUN_STARTED → ... → RUN_FINISHED                            │
+└─────────────────────────────────────────────────────────────┘
+    ↓
+ChatListItem 渲染
+```
+
+### 2.2 核心组件
+
+| 组件 | 职责 |
+|------|------|
+| `AgUiEvent` | AG-UI 事件数据模型 |
+| `AgUiService` | 事件流处理：发送消息、解析事件 |
+| `ToolRegistry` | 前端工具注册表：定义工具 + handler |
+| `AiDecisionEngine` | Mock 模式：规则引擎决定是否调用工具 |
+| `UiSchemaParser` | 解析 tool result 中的 UI Schema |
+| `UiSchemaRenderer` | 根据 schema 渲染对应组件 |
+| `ChatHistoryRepository` | 本地持久化：IndexedDB/localStorage |
+
+### 2.3 状态管理
+
+```
+ChatState {
+  messages: ChatListItem[]      // 渲染列表
+  pendingToolCalls: Map<call_id, ToolCallState>
+  isLoading: bool
+  runId: string | null
+}
+```
+
+## 3. 数据模型
+
+### 3.1 AG-UI 事件模型
+
+```dart
+// 基类
+abstract class AgUiEvent {
+  final String type;
+  final String? timestamp;
+}
+
+// 生命周期事件
+class RunStartedEvent extends AgUiEvent {
+  final String threadId;
+  final String runId;
+  final String? parentRunId;
+}
+
+class RunFinishedEvent extends AgUiEvent {
+  final String threadId;
+  final String runId;
+  final dynamic result;
+}
+
+// 文本消息事件
+class TextMessageStartEvent extends AgUiEvent {
+  final String messageId;
+  final String role; // "user" | "assistant" | "system"
+}
+
+class TextMessageContentEvent extends AgUiEvent {
+  final String messageId;
+  final String delta;
+}
+
+class TextMessageEndEvent extends AgUiEvent {
+  final String messageId;
+}
+
+// 工具调用事件
+class ToolCallStartEvent extends AgUiEvent {
+  final String toolCallId;
+  final String toolCallName;
+  final String? parentMessageId;
+}
+
+class ToolCallArgsEvent extends AgUiEvent {
+  final String toolCallId;
+  final String delta; // JSON fragment
+}
+
+class ToolCallEndEvent extends AgUiEvent {
+  final String toolCallId;
+}
+
+class ToolCallResultEvent extends AgUiEvent {
+  final String messageId;
+  final String toolCallId;
+  final ToolResult result; // 给 AI 的原始结果
+  final UiCard? ui;         // 给 UI 的渲染数据
+}
+
+class ToolCallErrorEvent extends AgUiEvent {
+  final String toolCallId;
+  final String error;
+  final String? code;
+}
+```
+
+### 3.2 Tool Result Schema（v1）
+
+```json
+{
+  "type": "tool_result",
+  "version": "v1",
+  "call_id": "call_abc123",
+  "tool_name": "create_calendar_event",
+  "result": {
+    "eventId": "evt_xxx",
+    "ok": true,
+    "message": "日程已创建"
+  },
+  "ui": {
+    "type": "card",
+    "cardType": "calendar_card.v1",
+    "data": {
+      "id": "evt_xxx",
+      "title": "产品评审会议",
+      "description": "讨论Q2路线图",
+      "startAt": "2026-03-01T10:00:00+08:00",
+      "endAt": "2026-03-01T11:00:00+08:00",
+      "timezone": "Asia/Shanghai",
+      "location": "会议室A",
+      "color": "#4F46E5",
+      "sourceType": "agentGenerated"
+    },
+    "actions": [
+      {"type": "open", "label": "打开", "target": "calendar/evt_xxx"},
+      {"type": "edit", "label": "编辑", "action": "edit_event"},
+      {"type": "delete", "label": "删除", "action": "delete_event"}
+    ]
+  }
+}
+```
+
+### 3.3 工具定义（前端 Tool Registry）
+
+```dart
+// 工具定义
+class ToolDefinition {
+  final String name;
+  final String description;
+  final Map<String, dynamic> parameters;
+  final ToolHandler handler;
+}
+
+// create_calendar_event 工具
+{
+  "name": "create_calendar_event",
+  "description": "创建一个日历事件或待办事项",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "title": {
+        "type": "string",
+        "description": "事件标题",
+        "minLength": 1,
+        "maxLength": 100
+      },
+      "description": {
+        "type": "string",
+        "description": "事件描述"
+      },
+      "startAt": {
+        "type": "string",
+        "format": "date-time",
+        "description": "开始时间 (ISO8601)"
+      },
+      "endAt": {
+        "type": "string",
+        "format": "date-time",
+        "description": "结束时间 (ISO8601)"
+      },
+      "timezone": {
+        "type": "string",
+        "default": "Asia/Shanghai"
+      },
+      "location": {
+        "type": "string"
+      },
+      "notes": {
+        "type": "string"
+      }
+    },
+    "required": ["title", "startAt"]
+  }
+}
+```
+
+### 3.4 ChatListItem 模型
+
+```dart
+enum ChatItemType { 
+  message,      // 纯文本消息
+  toolCall,     // 工具调用中
+  toolResult,   // 工具结果卡片
+  schedule      // 日历事件（兼容旧数据）
+}
+
+abstract class ChatListItem {
+  String get id;
+  DateTime get timestamp;
+  ChatItemType get type;
+  MessageSender get sender;
+}
+
+class TextMessageItem extends ChatListItem {
+  final String id;
+  final String content;
+  final DateTime timestamp;
+  final MessageSender sender;
+  final bool isStreaming; // 是否正在流式输出
+}
+
+class ToolCallItem extends ChatListItem {
+  final String id;
+  final String callId;
+  final String toolName;
+  final Map<String, dynamic> args; // 解析后的参数
+  final ToolCallStatus status; // pending | executing | completed | error
+  final ToolResult? result;
+  final UiCard? uiCard;
+}
+
+class CalendarCardItem extends ChatListItem {
+  final String id;
+  final String callId; // 关联的 tool call
+  final CalendarCardData data;
+  final List<CardAction> actions;
+}
+```
+
+## 4. 核心流程
+
+### 4.1 发送消息
+
+```dart
+Future<void> sendMessage(String content) async {
+  // 1. 添加用户消息到列表
+  final userMessage = TextMessageItem(
+    id: generateId(),
+    content: content,
+    timestamp: DateTime.now(),
+    sender: MessageSender.user,
+  );
+  _chatItems.add(userMessage);
+
+  // 2. 发起请求
+  if (Env.isMockApi) {
+    await _mockEventStream(content);
+  } else {
+    await _realEventStream(content);
+  }
+}
+```
+
+### 4.2 Mock 事件流（规则引擎）
+
+```dart
+class AiDecisionEngine {
+  // 意图关键词映射
+  static final Map<Intent, List<Pattern>> _intentPatterns = {
+    Intent.createEvent: [
+      RegExp(r'提醒|开会|预约|日程|安排'),
+      RegExp(r'明天|今天|后天|下周'),
+      RegExp(r'\d{1,2}点|\d{1,2}:\d{2}'),
+    ],
+    Intent.searchEvent: [
+      RegExp(r'查看|有什么|今天.*日程|明天.*安排'),
+    ],
+  };
+
+  Intent? matchIntent(String text) {
+    for (final entry in _intentPatterns.entries) {
+      for (final pattern in entry.value) {
+        if (pattern.hasMatch(text)) {
+          return entry.key;
+        }
+      }
+    }
+    return null;
+  }
+
+  // 支持强制触发：#tool:create_calendar_event {"title": "test"}
+  bool tryForceTrigger(String text) {...}
+}
+```
+
+### 4.3 事件解析与处理
+
+```dart
+Future<void> _processEvent(AgUiEvent event) async {
+  switch (event.type) {
+    case 'TEXT_MESSAGE_START':
+      _handleTextMessageStart(event);
+      break;
+    case 'TEXT_MESSAGE_CONTENT':
+      _handleTextMessageContent(event);
+      break;
+    case 'TEXT_MESSAGE_END':
+      _handleTextMessageEnd(event);
+      break;
+    case 'TOOL_CALL_START':
+      _handleToolCallStart(event);
+      break;
+    case 'TOOL_CALL_ARGS':
+      _handleToolCallArgs(event);
+      break;
+    case 'TOOL_CALL_END':
+      await _handleToolCallEnd(event);
+      break;
+    case 'TOOL_CALL_RESULT':
+      _handleToolCallResult(event);
+      break;
+    case 'TOOL_CALL_ERROR':
+      _handleToolCallError(event);
+      break;
+  }
+}
+
+void _handleToolCallStart(ToolCallStartEvent event) {
+  // 创建 pending 状态的 tool call item
+  final item = ToolCallItem(
+    id: event.toolCallId,
+    callId: event.toolCallId,
+    toolName: event.toolCallName,
+    args: {},
+    status: ToolCallStatus.pending,
+  );
+  _chatItems.add(item);
+}
+
+Future<void> _handleToolCallEnd(ToolCallEndEvent event) async {
+  // 1. 找到对应的 pending tool call
+  final toolCall = _findPendingToolCall(event.toolCallId);
+  if (toolCall == null) return;
+
+  // 2. 校验参数 JSON Schema
+  final validation = validateToolArgs(toolCall.toolName, toolCall.args);
+  if (!validation.ok) {
+    _emitToolCallError(event.toolCallId, validation.error);
+    return;
+  }
+
+  // 3. 执行工具 handler
+  toolCall.status = ToolCallStatus.executing;
+  final result = await ToolRegistry.execute(
+    toolCall.toolName,
+    toolCall.args,
+  );
+
+  // 4. 构建 tool result（包含 result + ui）
+  final toolResult = ToolResult(
+    eventId: result['eventId'],
+    ok: result['ok'] ?? true,
+    message: result['message'],
+  );
+
+  final uiCard = _buildUiCard(toolCall.toolName, result);
+
+  // 5. 发送 TOOL_CALL_RESULT 事件
+  _emitToolCallResult(event.toolCallId, toolResult, uiCard);
+}
+```
+
+### 4.4 UI Schema 渲染
+
+```dart
+class UiSchemaRenderer {
+  static final Map<String, Widget Function(UiCard)> _renderers = {
+    'calendar_card.v1': (card) => CalendarCardWidget(
+      data: CalendarCardData.fromJson(card.data),
+      actions: card.actions,
+    ),
+  };
+
+  static Widget render(UiCard card) {
+    final renderer = _renderers[card.cardType];
+    if (renderer != null) {
+      return renderer(card);
+    }
+    // Unknown card type fallback
+    return _renderUnknownCard(card);
+  }
+
+  static Widget _renderUnknownCard(UiCard card) {
+    return GenericCardWidget(
+      rawJson: jsonEncode(card.toJson()),
+      cardType: card.cardType,
+    );
+  }
+}
+```
+
+### 4.5 日历卡片组件
+
+```dart
+class CalendarCardWidget extends StatelessWidget {
+  final CalendarCardData data;
+  final List<CardAction> actions;
+
+  @override
+  Widget build(BuildContext context) {
+    final color = ColorExt.parse(data.color ?? '#4F46E5');
+    
+    return Container(
+      decoration: BoxDecoration(
+        color: Colors.white,
+        borderRadius: BorderRadius.circular(12),
+        boxShadow: [...],
+      ),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          // 颜色条
+          Container(
+            height: 4,
+            color: color,
+          ),
+          // 内容
+          Padding(
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Text(data.title, style: ...),
+                if (data.description != null) ...,
+                _buildTimeRow(),
+                if (data.location != null) ...,
+              ],
+            ),
+          ),
+          // Actions
+          if (actions.isNotEmpty) _buildActions(actions),
+        ],
+      ),
+    );
+  }
+}
+```
+
+## 5. 持久化设计
+
+### 5.1 存储结构
+
+```dart
+// localStorage / IndexedDB
+{
+  "chat_sessions": {
+    "current_thread_id": {
+      "messages": [...],  // ChatListItem JSON
+      "lastRunId": "run_xxx",
+      "updatedAt": "2026-02-28T12:00:00Z"
+    }
+  },
+  "calendar_events": {
+    "evt_xxx": {...}  // 独立存储的日历事件
+  }
+}
+```
+
+### 5.2 恢复逻辑
+
+```dart
+Future<void> restoreSession() async {
+  final session = await ChatHistoryRepository.load('current_thread_id');
+  if (session != null) {
+    _chatItems.clear();
+    _chatItems.addAll(session.messages);
+    _runId = session.lastRunId;
+  }
+}
+```
+
+## 6. 错误处理
+
+### 6.1 Tool Call 错误
+
+```dart
+void _emitToolCallError(String callId, String error) {
+  // 1. 更新 item 状态
+  final item = _findToolCallItem(callId);
+  item?.status = ToolCallStatus.error;
+  item?.errorMessage = error;
+
+  // 2. 渲染错误卡片
+  final errorCard = UiCard(
+    cardType: 'error_card.v1',
+    data: {'message': error},
+  );
+  
+  // 3. 触发 UI 更新
+  notifyListeners();
+}
+```
+
+### 6.2 事件流重连
+
+```dart
+// 断线重连时从 snapshot 恢复
+Future<void> reconnect() async {
+  final snapshot = await _fetchMessagesSnapshot();
+  _chatItems.clear();
+  _chatItems.addAll(snapshot.messages);
+  
+  // 重新订阅事件流
+  _subscribeToEvents();
+}
+```
+
+## 7. 实施计划
+
+### Phase 1: 基础框架
+- [ ] 定义 AG-UI 事件模型
+- [ ] 实现 AgUiService 基础结构
+- [ ] 实现 ToolRegistry
+
+### Phase 2: Mock 实现
+- [ ] 实现 AiDecisionEngine 规则引擎
+- [ ] 实现 Mock 事件流
+- [ ] 集成现有 HomeScreen
+
+### Phase 3: UI 渲染
+- [ ] 实现 UiSchemaParser
+- [ ] 实现 CalendarCardWidget
+- [ ] 实现 ToolPending / ToolError 状态卡片
+
+### Phase 4: 持久化
+- [ ] 实现 ChatHistoryRepository
+- [ ] 实现会话恢复
+
+### Phase 5: 真实后端对接
+- [ ] 实现 SSE 客户端
+- [ ] 实现事件流解析器
+
+## 8. 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| v1.0 | 2026-02-28 | 初始版本 |
@@ -0,0 +1,136 @@
+# 好友申请与待办消息功能设计
+
+**Date:** 2026-02-28
+**Status:** Approved
+
+## 1. 数据模型
+
+### Friendship 表 (已存在)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| user_low_id | UUID | 用户A ID (固定排序小值) |
+| user_high_id | UUID | 用户B ID (固定排序大值) |
+| initiator_id | UUID? | 发起请求者 |
+| status | VARCHAR(20) | pending/accepted/blocked/declined/canceled |
+| requested_at | TIMESTAMP? | 请求时间 |
+| accepted_at | TIMESTAMP? | 接受时间 |
+| blocked_by | UUID? | 被谁屏蔽 |
+| created_by/updated_by | UUID? | 审计字段 |
+
+### InboxMessage 表 (复用)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | UUID | 主键 |
+| recipient_id | UUID | 接收方 |
+| sender_id | UUID? | 发送方 |
+| message_type | VARCHAR(20) | FRIEND_REQUEST / CALENDAR / SYSTEM / GROUP |
+| friendship_id | UUID? | 关联 Friendship |
+| content | TEXT? | 附加消息 |
+| is_read | BOOLEAN | 已读状态 |
+| status | VARCHAR(20) | pending/accepted/rejected/dismissed |
+
+## 2. API 设计
+
+| 方法 | 路径 | 功能 |
+|------|------|------|
+| POST | /friends/requests | 发送好友请求 |
+| GET | /friends/requests/outgoing | 获取我发出的请求 |
+| GET | /friends/requests/inbox | 获取收到的好友请求 |
+| POST | /friends/requests/{id}/accept | 接受好友请求 |
+| POST | /friends/requests/{id}/decline | 拒绝好友请求 |
+| DELETE | /friends/requests/{id} | 取消我的请求 |
+| GET | /friends | 获取好友列表 |
+| DELETE | /friends/{id} | 删除好友 |
+
+## 3. 业务逻辑流程
+
+### 3.1 发送好友请求
+
+```
+1. 验证 target_user_id != current_user_id
+2. 检查是否已存在 Friendship 记录
+   - 已 accepted: 返回 409
+   - 已 pending: 返回 409
+   - 已 blocked: 返回 403
+3. 创建 Friendship (status=pending, initiator_id=current_user)
+4. 创建 InboxMessage (message_type=FRIEND_REQUEST, recipient=target_user)
+5. 提交事务
+```
+
+### 3.2 接受好友请求
+
+```
+1. 查询 Friendship 和 InboxMessage
+2. 验证 current_user == recipient
+3. 更新 Friendship (status=accepted, accepted_at=now)
+4. 更新 InboxMessage (status=accepted)
+5. 提交事务
+```
+
+### 3.3 拒绝好友请求
+
+```
+1. 查询 Friendship 和 InboxMessage
+2. 验证 current_user == recipient
+3. 更新 Friendship (status=declined)
+4. 更新 InboxMessage (status=rejected)
+5. 提交事务
+```
+
+### 3.4 获取好友列表
+
+```
+查询 Friendship WHERE (user_low_id=current OR user_high_id=current) AND status=accepted
+```
+
+## 4. 响应 Schema
+
+### FriendRequestResponse
+```python
+{
+    "id": "uuid",
+    "sender": {"id": "uuid", "username": "string", "avatar_url": "string?"},
+    "recipient": {"id": "uuid", "username": "string", "avatar_url": "string?"},
+    "content": "string?",
+    "status": "pending",
+    "created_at": "datetime"
+}
+```
+
+### FriendResponse
+```python
+{
+    "id": "uuid",
+    "friend": {"id": "uuid", "username": "string", "avatar_url": "string?"},
+    "status": "accepted",
+    "created_at": "datetime",
+    "accepted_at": "datetime?"
+}
+```
+
+## 5. 边界处理
+
+| 场景 | 状态码 | 响应 |
+|------|--------|------|
+| 对自己发送请求 | 400 | Cannot send friend request to yourself |
+| 已是好友 | 409 | Already friends |
+| 已有待处理请求 | 409 | Friend request already exists |
+| 被对方屏蔽 | 403 | Blocked by user |
+| 请求不存在 | 404 | Friend request not found |
+| 无权限操作 | 403 | Not authorized |
+
+## 6. 测试用例
+
+### 单元测试
+- FriendshipService 业务逻辑
+- 状态转换验证
+- 边界条件处理
+
+### 集成测试
+- POST /friends/requests - 成功/失败场景
+- GET /friends/requests/inbox - 返回正确列表
+- POST /friends/requests/{id}/accept - 状态更新
+- DELETE /friends/{id} - 删除好友
@@ -0,0 +1,870 @@
+# 好友申请功能实现计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 实现好友申请、待办消息、添加/删除好友等系列功能的后端API
+
+**Architecture:** 使用 repository/service/router 模式，复用已有的 Friendship 和 InboxMessage 模型，通过 inbox_messages 表存储好友请求通知
+
+**Tech Stack:** FastAPI, SQLAlchemy, Pydantic
+
+---
+
+### Task 1: 创建 friendships 模块目录结构和基础文件
+
+**Files:**
+- Create: `backend/src/v1/friendships/__init__.py`
+- Create: `backend/src/v1/friendships/schemas.py`
+- Create: `backend/src/v1/friendships/repository.py`
+- Create: `backend/src/v1/friendships/service.py`
+- Create: `backend/src/v1/friendships/dependencies.py`
+- Create: `backend/src/v1/friendships/router.py`
+
+**Step 1: 创建目录和基础 schema**
+
+```python
+# backend/src/v1/friendships/__init__.py
+```
+
+**Step 2: 创建 Pydantic schemas**
+
+```python
+# backend/src/v1/friendships/schemas.py
+from __future__ import annotations
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class UserBasicInfo(BaseModel):
+    id: str
+    username: str
+    avatar_url: Optional[str] = None
+
+
+class FriendRequestCreate(BaseModel):
+    target_user_id: UUID
+    content: Optional[str] = Field(None, max_length=200)
+
+
+class FriendRequestResponse(BaseModel):
+    id: UUID
+    sender: UserBasicInfo
+    recipient: UserBasicInfo
+    content: Optional[str]
+    status: str
+    created_at: datetime
+
+
+class FriendResponse(BaseModel):
+    id: UUID
+    friend: UserBasicInfo
+    status: str
+    created_at: datetime
+    accepted_at: Optional[datetime]
+
+
+class FriendRequestAction(BaseModel):
+    # For accept/decline - no body needed but kept for extensibility
+    pass
+```
+
+**Step 3: Commit**
+
+```bash
+git add backend/src/v1/friendships/
+git commit -m "feat(friendships): create module structure and schemas"
+```
+
+---
+
+### Task 2: 实现 FriendshipRepository
+
+**Files:**
+- Modify: `backend/src/v1/friendships/repository.py`
+
+**Step 1: 写入失败的测试**
+
+```python
+# backend/tests/unit/v1/friendships/test_friendship_repository.py
+import pytest
+from uuid import uuid4
+from v1.friendships.repository import FriendshipRepository
+
+
+@pytest.fixture
+def mock_session():
+    # Create mock async session
+    pass
+
+
+@pytest.mark.asyncio
+async def test_create_friendship_request(mock_session):
+    repository = FriendshipRepository(mock_session)
+    # Test creating friendship request
+    pass
+
+
+@pytest.mark.asyncio
+async def test_get_pending_request_between_users(mock_session):
+    repository = FriendshipRepository(mock_session)
+    # Test checking existing requests
+    pass
+```
+
+**Step 2: 运行测试确认失败**
+
+**Step 3: 实现 repository**
+
+```python
+# backend/src/v1/friendships/repository.py
+from __future__ import annotations
+
+from typing import Optional
+from uuid import UUID
+
+from sqlalchemy import select, and_, or_
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from models.friendships import Friendship, FriendshipStatus
+from models.inbox_messages import InboxMessage, InboxMessageType, InboxMessageStatus
+
+
+class FriendshipRepository:
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def create_request(
+        self,
+        user_low_id: UUID,
+        user_high_id: UUID,
+        initiator_id: UUID,
+        recipient_id: UUID,
+        content: Optional[str] = None,
+    ) -> tuple[Friendship, InboxMessage]:
+        friendship = Friendship(
+            user_low_id=user_low_id,
+            user_high_id=user_high_id,
+            initiator_id=initiator_id,
+            status=FriendshipStatus.PENDING,
+        )
+        self._session.add(friendship)
+        await self._session.flush()
+
+        inbox_message = InboxMessage(
+            recipient_id=recipient_id,
+            sender_id=initiator_id,
+            message_type=InboxMessageType.FRIEND_REQUEST,
+            friendship_id=friendship.id,
+            content=content,
+            status=InboxMessageStatus.PENDING,
+        )
+        self._session.add(inbox_message)
+        return friendship, inbox_message
+
+    async def get_friendship_between_users(
+        self, user_a_id: UUID, user_b_id: UUID
+    ) -> Optional[Friendship]:
+        low_id = min(user_a_id, user_b_id)
+        high_id = max(user_a_id, user_b_id)
+        stmt = select(Friendship).where(
+            and_(
+                Friendship.user_low_id == low_id,
+                Friendship.user_high_id == high_id,
+            )
+        )
+        result = await self._session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def get_pending_inbox_for_recipient(
+        self, friendship_id: UUID, recipient_id: UUID
+    ) -> Optional[InboxMessage]:
+        stmt = select(InboxMessage).where(
+            and_(
+                InboxMessage.friendship_id == friendship_id,
+                InboxMessage.recipient_id == recipient_id,
+                InboxMessage.message_type == InboxMessageType.FRIEND_REQUEST,
+            )
+        )
+        result = await self._session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def get_friendship_by_id(self, friendship_id: UUID) -> Optional[Friendship]:
+        stmt = select(Friendship).where(Friendship.id == friendship_id)
+        result = await self._session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    async def get_inbox_messages_for_user(
+        self, user_id: UUID, status: Optional[InboxMessageStatus] = None
+    ) -> list[InboxMessage]:
+        stmt = select(InboxMessage).where(
+            and_(
+                InboxMessage.recipient_id == user_id,
+                InboxMessage.message_type == InboxMessageType.FRIEND_REQUEST,
+            )
+        )
+        if status:
+            stmt = stmt.where(InboxMessage.status == status)
+        stmt = stmt.order_by(InboxMessage.created_at.desc())
+        result = await self._session.execute(stmt)
+        return list(result.scalars().all())
+
+    async def get_outgoing_requests(
+        self, user_id: UUID, status: Optional[FriendshipStatus] = None
+    ) -> list[Friendship]:
+        stmt = select(Friendship).where(Friendship.initiator_id == user_id)
+        if status:
+            stmt = stmt.where(Friendship.status == status)
+        else:
+            stmt = stmt.where(Friendship.status == FriendshipStatus.PENDING)
+        stmt = stmt.order_by(Friendship.created_at.desc())
+        result = await self._session.execute(stmt)
+        return list(result.scalars().all())
+
+    async def get_friends_list(self, user_id: UUID) -> list[Friendship]:
+        stmt = select(Friendship).where(
+            or_(
+                Friendship.user_low_id == user_id,
+                Friendship.user_high_id == user_id,
+            ),
+            Friendship.status == FriendshipStatus.ACCEPTED,
+        ).order_by(Friendship.updated_at.desc())
+        result = await self._session.execute(stmt)
+        return list(result.scalars().all())
+```
+
+**Step 4: 运行测试确认通过**
+
+**Step 5: Commit**
+
+```bash
+git add backend/src/v1/friendships/repository.py backend/tests/unit/v1/friendships/
+git commit -m "feat(friendships): implement repository"
+```
+
+---
+
+### Task 3: 实现 FriendshipService
+
+**Files:**
+- Modify: `backend/src/v1/friendships/service.py`
+
+**Step 1: 写入失败的测试**
+
+```python
+# backend/tests/unit/v1/friendships/test_friendship_service.py
+import pytest
+from uuid import uuid4
+from v1.friendships.service import FriendshipService
+
+
+@pytest.fixture
+def mock_repository():
+    pass
+
+
+@pytest.mark.asyncio
+async def test_send_friend_request_success(mock_repository):
+    service = FriendshipService(mock_repository, current_user)
+    # Test successful friend request
+    pass
+
+
+@pytest.mark.asyncio
+async def test_send_friend_request_to_self_fails():
+    # Test that sending to self returns 400
+    pass
+
+
+@pytest.mark.asyncio
+async def test_send_friend_request_when_already_friends():
+    # Test that sending to existing friend returns 409
+    pass
+```
+
+**Step 2: 运行测试确认失败**
+
+**Step 3: 实现 service**
+
+```python
+# backend/src/v1/friendships/service.py
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from fastapi import HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from core.auth.models import CurrentUser
+from core.db.base_service import BaseService
+from core.logging import get_logger
+from models.friendships import Friendship, FriendshipStatus
+from models.inbox_messages import InboxMessageStatus
+from models.profile import Profile
+from v1.friendships.repository import FriendshipRepository
+from v1.friendships.schemas import (
+    FriendRequestCreate,
+    FriendRequestResponse,
+    FriendResponse,
+    UserBasicInfo,
+)
+
+logger = get_logger("v1.friendships.service")
+
+
+class FriendshipService(BaseService):
+    def __init__(
+        self,
+        repository: FriendshipRepository,
+        session: AsyncSession,
+        current_user: CurrentUser,
+    ) -> None:
+        super().__init__(current_user=current_user)
+        self._repository = repository
+        self._session = session
+
+    async def send_request(
+        self, payload: FriendRequestCreate
+    ) -> FriendRequestResponse:
+        current_user_id = self.require_user_id()
+        target_user_id = payload.target_user_id
+
+        if current_user_id == target_user_id:
+            raise HTTPException(
+                status_code=400,
+                detail="Cannot send friend request to yourself"
+            )
+
+        # Check existing relationship
+        existing = await self._repository.get_friendship_between_users(
+            current_user_id, target_user_id
+        )
+
+        if existing:
+            if existing.status == FriendshipStatus.ACCEPTED:
+                raise HTTPException(status_code=409, detail="Already friends")
+            if existing.status == FriendshipStatus.PENDING:
+                raise HTTPException(status_code=409, detail="Friend request already exists")
+            if existing.status == FriendshipStatus.BLOCKED:
+                raise HTTPException(status_code=403, detail="Blocked by user")
+
+        user_low_id = min(current_user_id, target_user_id)
+        user_high_id = max(current_user_id, target_user_id)
+
+        friendship, inbox = await self._repository.create_request(
+            user_low_id=user_low_id,
+            user_high_id=user_high_id,
+            initiator_id=current_user_id,
+            recipient_id=target_user_id,
+            content=payload.content,
+        )
+        await self._session.commit()
+
+        sender_info = await self._get_profile_info(current_user_id)
+        recipient_info = await self._get_profile_info(target_user_id)
+
+        return FriendRequestResponse(
+            id=friendship.id,
+            sender=sender_info,
+            recipient=recipient_info,
+            content=payload.content,
+            status=friendship.status.value,
+            created_at=friendship.created_at,
+        )
+
+    async def accept_request(self, friendship_id: UUID) -> FriendRequestResponse:
+        current_user_id = self.require_user_id()
+
+        friendship = await self._repository.get_friendship_by_id(friendship_id)
+        if not friendship:
+            raise HTTPException(status_code=404, detail="Friend request not found")
+
+        # Determine recipient - must be the current user
+        recipient_id = friendship.user_low_id if friendship.user_high_id == current_user_id else friendship.user_high_id
+        if recipient_id != current_user_id:
+            raise HTTPException(status_code=403, detail="Not authorized")
+
+        inbox = await self._repository.get_pending_inbox_for_recipient(
+            friendship_id, current_user_id
+        )
+
+        friendship.status = FriendshipStatus.ACCEPTED
+        friendship.accepted_at = datetime.utcnow()
+        
+        if inbox:
+            inbox.status = InboxMessageStatus.ACCEPTED
+        
+        await self._session.commit()
+
+        initiator_info = await self._get_profile_info(friendship.initiator_id)
+        recipient_info = await self._get_profile_info(current_user_id)
+
+        return FriendRequestResponse(
+            id=friendship.id,
+            sender=initiator_info,
+            recipient=recipient_info,
+            content=inbox.content if inbox else None,
+            status=friendship.status.value,
+            created_at=friendship.created_at,
+        )
+
+    async def decline_request(self, friendship_id: UUID) -> FriendRequestResponse:
+        current_user_id = self.require_user_id()
+
+        friendship = await self._repository.get_friendship_by_id(friendship_id)
+        if not friendship:
+            raise HTTPException(status_code=404, detail="Friend request not found")
+
+        recipient_id = friendship.user_low_id if friendship.user_high_id == current_user_id else friendship.user_high_id
+        if recipient_id != current_user_id:
+            raise HTTPException(status_code=403, detail="Not authorized")
+
+        inbox = await self._repository.get_pending_inbox_for_recipient(
+            friendship_id, current_user_id
+        )
+
+        friendship.status = FriendshipStatus.DECLINED
+        
+        if inbox:
+            inbox.status = InboxMessageStatus.REJECTED
+        
+        await self._session.commit()
+
+        initiator_info = await self._get_profile_info(friendship.initiator_id)
+        recipient_info = await self._get_profile_info(current_user_id)
+
+        return FriendRequestResponse(
+            id=friendship.id,
+            sender=initiator_info,
+            recipient=recipient_info,
+            content=inbox.content if inbox else None,
+            status=friendship.status.value,
+            created_at=friendship.created_at,
+        )
+
+    async def cancel_request(self, friendship_id: UUID) -> None:
+        current_user_id = self.require_user_id()
+
+        friendship = await self._repository.get_friendship_by_id(friendship_id)
+        if not friendship:
+            raise HTTPException(status_code=404, detail="Friend request not found")
+
+        if friendship.initiator_id != current_user_id:
+            raise HTTPException(status_code=403, detail="Not authorized")
+
+        if friendship.status != FriendshipStatus.PENDING:
+            raise HTTPException(status_code=400, detail="Can only cancel pending requests")
+
+        inbox = await self._repository.get_pending_inbox_for_recipient(
+            friendship_id, friendship.user_low_id if friendship.user_high_id == current_user_id else friendship.user_high_id
+        )
+
+        friendship.status = FriendshipStatus.CANCELED
+        
+        if inbox:
+            inbox.status = InboxMessageStatus.DISMISSED
+        
+        await self._session.commit()
+
+    async def get_inbox(self) -> list[FriendRequestResponse]:
+        current_user_id = self.require_user_id()
+        inbox_messages = await self._repository.get_pending_inbox_for_user(
+            current_user_id, InboxMessageStatus.PENDING
+        )
+
+        results = []
+        for msg in inbox_messages:
+            friendship = await self._repository.get_friendship_by_id(msg.friendship_id)
+            if not friendship:
+                continue
+            
+            sender_info = await self._get_profile_info(msg.sender_id)
+            recipient_info = await self._get_profile_info(current_user_id)
+            
+            results.append(FriendRequestResponse(
+                id=friendship.id,
+                sender=sender_info,
+                recipient=recipient_info,
+                content=msg.content,
+                status=msg.status.value,
+                created_at=msg.created_at,
+            ))
+
+        return results
+
+    async def get_outgoing_requests(self) -> list[FriendRequestResponse]:
+        current_user_id = self.require_user_id()
+        friendships = await self._repository.get_outgoing_requests(current_user_id)
+
+        results = []
+        for friendship in friendships:
+            sender_info = await self._get_profile_info(current_user_id)
+            recipient_id = friendship.user_low_id if friendship.user_high_id == current_user_id else friendship.user_high_id
+            recipient_info = await self._get_profile_info(recipient_id)
+            
+            inbox = await self._repository.get_pending_inbox_for_recipient(
+                friendship.id, recipient_id
+            )
+
+            results.append(FriendRequestResponse(
+                id=friendship.id,
+                sender=sender_info,
+                recipient=recipient_info,
+                content=inbox.content if inbox else None,
+                status=friendship.status.value,
+                created_at=friendship.created_at,
+            ))
+
+        return results
+
+    async def get_friends_list(self) -> list[FriendResponse]:
+        current_user_id = self.require_user_id()
+        friendships = await self._repository.get_friends_list(current_user_id)
+
+        results = []
+        for friendship in friendships:
+            friend_id = friendship.user_low_id if friendship.user_high_id == current_user_id else friendship.user_high_id
+            friend_info = await self._get_profile_info(friend_id)
+
+            results.append(FriendResponse(
+                id=friendship.id,
+                friend=friend_info,
+                status=friendship.status.value,
+                created_at=friendship.created_at,
+                accepted_at=friendship.accepted_at,
+            ))
+
+        return results
+
+    async def remove_friend(self, friendship_id: UUID) -> None:
+        current_user_id = self.require_user_id()
+
+        friendship = await self._repository.get_friendship_by_id(friendship_id)
+        if not friendship:
+            raise HTTPException(status_code=404, detail="Friendship not found")
+
+        if friendship.status != FriendshipStatus.ACCEPTED:
+            raise HTTPException(status_code=400, detail="Can only remove accepted friends")
+
+        # Verify user is part of this friendship
+        if friendship.user_low_id != current_user_id and friendship.user_high_id != current_user_id:
+            raise HTTPException(status_code=403, detail="Not authorized")
+
+        # Soft delete - mark as canceled
+        friendship.status = FriendshipStatus.CANCELED
+        await self._session.commit()
+
+    async def _get_profile_info(self, user_id: UUID) -> UserBasicInfo:
+        from sqlalchemy import select
+        from models.profile import Profile
+        
+        stmt = select(Profile).where(Profile.id == user_id)
+        result = await self._session.execute(stmt)
+        profile = result.scalar_one_or_none()
+        
+        if not profile:
+            return UserBasicInfo(id=str(user_id), username="Unknown")
+        
+        return UserBasicInfo(
+            id=str(profile.id),
+            username=profile.username,
+            avatar_url=profile.avatar_url,
+        )
+```
+
+**Step 4: 运行测试确认通过**
+
+**Step 5: Commit**
+
+```bash
+git add backend/src/v1/friendships/service.py
+git commit -m "feat(friendships): implement service layer"
+```
+
+---
+
+### Task 4: 实现 Dependencies 和 Router
+
+**Files:**
+- Modify: `backend/src/v1/friendships/dependencies.py`
+- Modify: `backend/src/v1/friendships/router.py`
+
+**Step 1: 实现 dependencies**
+
+```python
+# backend/src/v1/friendships/dependencies.py
+from __future__ import annotations
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from core.auth.models import CurrentUser
+from core.db import get_db
+from v1.friendships.repository import FriendshipRepository
+from v1.friendships.service import FriendshipService
+from v1.users.dependencies import get_current_user
+
+
+async def get_friendship_repository(
+    session: Annotated[AsyncSession, Depends(get_db)]
+) -> FriendshipRepository:
+    return FriendshipRepository(session)
+
+
+async def get_friendship_service(
+    repository: Annotated[FriendshipRepository, Depends(get_friendship_repository)],
+    session: Annotated[AsyncSession, Depends(get_db)],
+    user: Annotated[CurrentUser, Depends(get_current_user)],
+) -> FriendshipService:
+    return FriendshipService(
+        repository=repository,
+        session=session,
+        current_user=user,
+    )
+```
+
+**Step 2: 实现 router**
+
+```python
+# backend/src/v1/friendships/router.py
+from __future__ import annotations
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Path, HTTPException
+
+from v1.friendships.dependencies import get_friendship_service
+from v1.friendships.schemas import (
+    FriendRequestCreate,
+    FriendRequestResponse,
+    FriendResponse,
+)
+from v1.friendships.service import FriendshipService
+
+
+router = APIRouter(prefix="/friends", tags=["friends"])
+
+
+@router.post("/requests", response_model=FriendRequestResponse, status_code=201)
+async def send_friend_request(
+    payload: FriendRequestCreate,
+    service: Annotated[FriendshipService, Depends(get_friendship_service)],
+) -> FriendRequestResponse:
+    return await service.send_request(payload)
+
+
+@router.get("/requests/inbox", response_model=list[FriendRequestResponse])
+async def get_inbox(
+    service: Annotated[FriendshipService, Depends(get_friendship_service)],
+) -> list[FriendRequestResponse]:
+    return await service.get_inbox()
+
+
+@router.get("/requests/outgoing", response_model=list[FriendRequestResponse])
+async def get_outgoing_requests(
+    service: Annotated[FriendshipService, Depends(get_friendship_service)],
+) -> list[FriendRequestResponse]:
+    return await service.get_outgoing_requests()
+
+
+@router.post("/requests/{friendship_id}/accept", response_model=FriendRequestResponse)
+async def accept_friend_request(
+    friendship_id: Annotated[UUID, Path()],
+    service: Annotated[FriendshipService, Depends(get_friendship_service)],
+) -> FriendRequestResponse:
+    return await service.accept_request(friendship_id)
+
+
+@router.post("/requests/{friendship_id}/decline", response_model=FriendRequestResponse)
+async def decline_friend_request(
+    friendship_id: Annotated[UUID, Path()],
+    service: Annotated[FriendshipService, Depends(get_friendship_service)],
+) -> FriendRequestResponse:
+    return await service.decline_request(friendship_id)
+
+
+@router.delete("/requests/{friendship_id}", status_code=204)
+async def cancel_friend_request(
+    friendship_id: Annotated[UUID, Path()],
+    service: Annotated[FriendshipService, Depends(get_friendship_service)],
+) -> None:
+    await service.cancel_request(friendship_id)
+
+
+@router.get("", response_model=list[FriendResponse])
+async def get_friends_list(
+    service: Annotated[FriendshipService, Depends(get_friendship_service)],
+) -> list[FriendResponse]:
+    return await service.get_friends_list()
+
+
+@router.delete("/{friendship_id}", status_code=204)
+async def remove_friend(
+    friendship_id: Annotated[UUID, Path()],
+    service: Annotated[FriendshipService, Depends(get_friendship_service)],
+) -> None:
+    await service.remove_friend(friendship_id)
+```
+
+**Step 3: 注册 router 到主路由**
+
+```python
+# backend/src/v1/router.py
+from fastapi import APIRouter
+from v1.auth.router import router as auth_router
+from v1.users.router import router as users_router
+from v1.profile.router import router as profile_router
+from v1.friendships.router import router as friendships_router
+
+router = APIRouter()
+
+router.include_router(auth_router)
+router.include_router(users_router)
+router.include_router(profile_router)
+router.include_router(friendships_router)
+```
+
+**Step 4: Commit**
+
+```bash
+git add backend/src/v1/friendships/dependencies.py backend/src/v1/friendships/router.py backend/src/v1/router.py
+git commit -m "feat(friendships): implement router and dependencies"
+```
+
+---
+
+### Task 5: 集成测试
+
+**Files:**
+- Create: `backend/tests/integration/test_friendship_routes.py`
+
+**Step 1: 写入测试**
+
+```python
+# backend/tests/integration/test_friendship_routes.py
+import pytest
+from httpx import AsyncClient, ASGITransport
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.pool import StaticPool
+
+from main import app  # FastAPI app
+from core.db.base import Base
+from core.db import get_db
+
+
+@pytest.fixture
+async def async_client():
+    # Setup test database
+    engine = create_async_engine(
+        "sqlite+aiosqlite:///:memory:",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+    
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    
+    async def override_get_db():
+        async with AsyncSession(engine) as session:
+            yield session
+    
+    app.dependency_overrides[get_db] = override_get_db
+    
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        yield client
+    
+    app.dependency_overrides.clear()
+
+
+@pytest.mark.asyncio
+async def test_send_friend_request_requires_auth(async_client):
+    response = await async_client.post(
+        "/api/v1/friends/requests",
+        json={"target_user_id": "..."}
+    )
+    assert response.status_code == 401
+
+
+# More tests...
+```
+
+**Step 2: 运行测试**
+
+**Step 3: Commit**
+
+---
+
+### Task 6: 运行 Lint 和 Typecheck
+
+**Step 1: 运行 ruff**
+
+```bash
+cd backend && uv run ruff check src/v1/friendships/
+```
+
+**Step 2: 运行 typecheck**
+
+```bash
+cd backend && uv run basedpyright src/v1/friendships/
+```
+
+**Step 3: Commit (if any fixes needed)**
+
+---
+
+### Task 7: 更新文档
+
+**Files:**
+- Modify: `docs/runtime/runtime-route.md`
+
+**Step 1: 添加 API 文档**
+
+```markdown
+## Friends
+
+### Send Friend Request
+- **POST** `/api/v1/friends/requests`
+- **Auth:** Required
+- **Body:** `{ "target_user_id": "uuid", "content": "string?" }`
+- **Response:** `FriendRequestResponse`
+
+### Get Inbox
+- **GET** `/api/v1/friends/requests/inbox`
+- **Auth:** Required
+- **Response:** `FriendRequestResponse[]`
+
+### Accept Request
+- **POST** `/api/v1/friends/requests/{id}/accept`
+- **Auth:** Required
+- **Response:** `FriendRequestResponse`
+
+### Decline Request
+- **POST** `/api/v1/friends/requests/{id}/decline`
+- **Auth:** Required
+- **Response:** `FriendRequestResponse`
+
+### Get Friends List
+- **GET** `/api/v1/friends`
+- **Auth:** Required
+- **Response:** `FriendResponse[]`
+
+### Remove Friend
+- **DELETE** `/api/v1/friends/{id}`
+- **Auth:** Required
+```
+
+**Step 2: Commit**
+
+```bash
+git add docs/runtime/runtime-route.md
+git commit -m "docs: add friendship API documentation"
+```