## 1. 架构设计

```mermaid
flowchart TB
    subgraph Frontend["前端 (React + Vite)"]
        UI["shadcn/ui 组件层"]
        Pages["页面层"]
        Hooks["Hooks 层"]
        Store["Zustand 状态管理"]
        SDK["array-sdk 通信层"]
    end

    subgraph Backend["后端 (FastAPI + SQLite)"]
        API["REST API"]
        WS["WebSocket"]
    end

    UI --> Pages
    Pages --> Hooks
    Hooks --> Store
    Hooks --> SDK
    Store --> SDK
    SDK --> API
    SDK --> WS
```

## 2. 技术说明

- **前端框架**：React 18 + TypeScript + Vite 6
- **UI 组件库**：shadcn/ui（Radix UI + Tailwind CSS）
- **状态管理**：Zustand（轻量、无 boilerplate、支持中间件）
- **样式方案**：Tailwind CSS 4 + CSS 变量主题系统
- **图标**：Lucide React
- **动画**：Framer Motion
- **Markdown 渲染**：react-markdown + remark-gfm + rehype-highlight
- **HTTP/WebSocket**：array-sdk（从旧项目迁移，纯 JS 无框架依赖）
- **路由**：React Router DOM v7（Hash 模式，兼容静态部署）
- **国际化**：自定义 i18n hook（中/英双语）
- **PWA**：vite-plugin-pwa
- **项目初始化**：vite-init react-ts 模板

## 3. 路由定义

| 路由 | 用途 |
|------|------|
| `/` | 登录页（未登录时）或主工作台（已登录时） |
| `/task/:taskId` | 主工作台，自动选中指定任务 |

## 4. API 定义

本项目为纯前端，所有 API 调用通过 array-sdk 与后端通信。SDK 封装层提供以下接口：

### 4.1 认证

```typescript
interface AuthAPI {
  login(serverUrl: string, apiKey: string): Promise<Worker>
  loginByPassword(serverUrl: string, username: string, password: string): Promise<Worker>
  register(serverUrl: string, name: string, username: string, password: string, profile?: RegisterProfile): Promise<Worker>
  autoLogin(): Promise<Worker | null>
  logout(): void
}
```

### 4.2 Worker

```typescript
interface WorkerAPI {
  getWorkers(params?: { orgId?: string }): Promise<Worker[]>
  getWorkerProfile(workerId: string): Promise<Worker>
  updateProfile(data: Partial<WorkerProfile>): Promise<Worker>
  getWorkerWorkload(workerId: string): Promise<Workload>
  discoverWorkers(options: DiscoverOptions): Promise<DiscoverResult>
}
```

### 4.3 Task

```typescript
interface TaskAPI {
  getTasks(params?: { orgId?: string; categoryId?: string }): Promise<Task[]>
  getTask(taskId: string): Promise<Task>
  createTask(title: string, participantIds: string[], priority?: string, extra?: CreateTaskExtra): Promise<Task>
  updateTaskStatus(taskId: string, status: TaskStatus): Promise<Task>
  updateTaskTitle(taskId: string, title: string): Promise<Task>
  addParticipant(taskId: string, workerId: string): Promise<Participant[]>
  removeParticipant(taskId: string, workerId: string): Promise<void>
}
```

### 4.4 Message

```typescript
interface MessageAPI {
  getMessages(taskId: string, scope?: string, includePrivate?: boolean, limit?: number, page?: number): Promise<Message[]>
  sendMessage(taskId: string, content: string, options?: SendMessageOptions): Promise<Message>
  sendMessageWithAttachments(taskId: string, content: string, fileIds: string[], options?: SendMessageOptions): Promise<Message>
}
```

### 4.5 Attachment

```typescript
interface AttachmentAPI {
  uploadAttachment(taskId: string, file: File): Promise<Attachment>
  listAttachments(taskId: string): Promise<{ attachments: Attachment[]; total: number }>
  deleteAttachment(taskId: string, attachmentId: string): Promise<void>
  getAttachmentUrl(taskId: string, attachmentId: string): string
}
```

### 4.6 Organization

```typescript
interface OrganizationAPI {
  listMyOrganizations(): Promise<Organization[]>
  getOrganization(orgId: string): Promise<Organization>
  createOrganization(name: string, description?: string): Promise<Organization>
  updateOrganization(orgId: string, data: Partial<Organization>): Promise<Organization>
  createInvite(orgId: string, options?: InviteOptions): Promise<OrgInvite>
  listInvites(orgId: string): Promise<OrgInvite[]>
  joinOrganization(inviteCode: string): Promise<JoinResult>
  listOrgMembers(orgId: string): Promise<OrgMember[]>
  removeOrgMember(orgId: string, workerId: string): Promise<void>
  updateMemberRole(orgId: string, workerId: string, role: 'admin' | 'member'): Promise<OrgMember>
  renameOrgMember(orgId: string, workerId: string, name: string): Promise<OrgMember>
}
```

### 4.7 Category

```typescript
interface CategoryAPI {
  createCategory(name: string, orgId?: string): Promise<Category>
  listCategories(orgId?: string): Promise<Category[]>
  updateCategory(categoryId: string, opts: Partial<Category>): Promise<Category>
  deleteCategory(categoryId: string): Promise<boolean>
}
```

### 4.8 Review

```typescript
interface ReviewAPI {
  createReview(workerId: string, params: CreateReviewParams): Promise<Review>
  getWorkerReviews(workerId: string, options?: PaginationOptions): Promise<ReviewListResult>
  getReviewSummary(workerId: string): Promise<ReviewSummary>
}
```

### 4.9 Notification

```typescript
interface NotificationAPI {
  getNotifications(isRead?: boolean): Promise<Notification[]>
  markNotificationRead(notificationId: string): Promise<void>
  markAllNotificationsRead(): Promise<void>
}
```

### 4.10 WebSocket

```typescript
interface WebSocketAPI {
  startWebSocket(callbacks: WSCallbacks): () => void
  stopWebSocket(): void
}

interface WSCallbacks {
  onEvent: (event: WSEvent) => void
  onConnected: () => void
  onDisconnected: () => void
  onError: (err: Error) => void
}

type WSEventType = 'task.message' | 'participant.joined' | 'task.updated' | 'worker_status_changed' | 'tasks.pending_recovery'
```

## 5. 数据模型

```mermaid
erDiagram
    Organization ||--o{ Category : "has"
    Organization ||--o{ OrgMember : "has"
    Organization ||--o{ OrgInvite : "has"
    Worker ||--o{ Task : "creates"
    Worker ||--o{ Review : "receives"
    Task ||--o{ Participant : "has"
    Task ||--o{ Message : "has"
    Task ||--o{ Attachment : "has"
    Task }o--|| Category : "belongs_to"
    Message }o--o| Message : "reply_to"
    Message }o--o| Worker : "private_to"

    Worker {
        string id PK
        string name
        string type
        string status
        string organization
        string location
        string description
        string[] tags
        object capabilities
        number maxConcurrentTasks
    }

    Task {
        string id PK
        string title
        string description
        string status
        string priority
        string creator_id FK
        string org_id FK
        string category_id FK
        datetime created_at
        datetime last_message_at
    }

    Message {
        string id PK
        string task_id FK
        string sender_id FK
        string content
        string type
        string reply_to_id FK
        string private_to_id FK
        datetime created_at
    }

    Attachment {
        string id PK
        string task_id FK
        string filename
        string content_type
        number size
        string url
        string thumbnail_url
        number width
        number height
        number duration
    }

    Review {
        string id PK
        string worker_id FK
        string task_id FK
        string reviewer_id FK
        number rating
        string[] capability_tags
        string comment
        string suggestion
    }
```

## 6. 项目目录结构

```
human-adapter-react/
├── src/
│   ├── components/          # UI 组件
│   │   ├── ui/              # shadcn/ui 基础组件
│   │   ├── layout/          # 布局组件
│   │   │   ├── TopBar.tsx
│   │   │   ├── WorkersPanel.tsx
│   │   │   ├── TaskList.tsx
│   │   │   └── Resizer.tsx
│   │   ├── chat/            # 聊天相关组件
│   │   │   ├── ChatDetail.tsx
│   │   │   ├── MessageList.tsx
│   │   │   ├── MessageBubble.tsx
│   │   │   ├── MessageInput.tsx
│   │   │   ├── MentionPopup.tsx
│   │   │   ├── ReplyPreview.tsx
│   │   │   ├── AttachmentRenderer.tsx
│   │   │   ├── DMTab.tsx
│   │   │   └── ScrollToBottom.tsx
│   │   ├── task/            # 任务相关组件
│   │   │   ├── TaskCard.tsx
│   │   │   ├── TaskComposer.tsx
│   │   │   ├── TaskDrawer.tsx
│   │   │   ├── StatusSelector.tsx
│   │   │   └── ParticipantManager.tsx
│   │   ├── org/             # 组织相关组件
│   │   │   ├── OrgSwitcher.tsx
│   │   │   ├── OrgDetailSheet.tsx
│   │   │   └── InviteManager.tsx
│   │   ├── profile/         # 个人中心组件
│   │   │   ├── ProfileDialog.tsx
│   │   │   └── ShortcutSettings.tsx
│   │   ├── review/          # 评价组件
│   │   │   ├── ReviewDialog.tsx
│   │   │   └── ReviewSummary.tsx
│   │   ├── auth/            # 登录组件
│   │   │   └── LoginPage.tsx
│   │   └── shared/          # 共享组件
│   │       ├── LedLogo.tsx
│   │       ├── LedMatrix.tsx
│   │       ├── RobotIcon.tsx
│   │       ├── WorkerAvatar.tsx
│   │       ├── Toast.tsx
│   │       └── PwaInstallBanner.tsx
│   ├── hooks/               # 自定义 Hooks
│   │   ├── useAuth.ts
│   │   ├── useMessages.ts
│   │   ├── useWorkers.ts
│   │   ├── useTasks.ts
│   │   ├── useOrganization.ts
│   │   ├── useNotifications.ts
│   │   ├── useReviews.ts
│   │   ├── useProfile.ts
│   │   ├── useWebSocket.ts
│   │   ├── useI18n.ts
│   │   ├── useTheme.ts
│   │   ├── useAutoScroll.ts
│   │   └── useDrafts.ts
│   ├── stores/              # Zustand Store
│   │   ├── authStore.ts
│   │   ├── appStore.ts
│   │   └── uiStore.ts
│   ├── lib/                 # 工具库
│   │   ├── sdk.ts           # array-sdk 封装
│   │   ├── api.ts           # API 薄封装层
│   │   ├── i18n.ts          # 国际化字典
│   │   ├── utils.ts         # 通用工具函数
│   │   └── constants.ts     # 常量定义
│   ├── pages/               # 页面
│   │   ├── LoginPage.tsx
│   │   └── WorkbenchPage.tsx
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css            # Tailwind 入口 + CSS 变量
├── public/
├── sdk-js/                  # array-sdk 源码（从旧项目迁移）
│   ├── src/
│   │   ├── client.ts
│   │   ├── adapter.ts
│   │   └── index.ts
│   └── package.json
├── .trae/documents/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── components.json          # shadcn/ui 配置
└── postcss.config.js
```

## 7. 关键架构决策

### 7.1 状态管理：Zustand vs Context

选择 Zustand 的理由：
- 无 Provider 包裹，任何组件直接 `useStore()` 即可
- 支持 `subscribeWithSelector` 中间件，精确控制重渲染
- 支持 `persist` 中间件，自动持久化到 localStorage
- 比 Redux 少 90% boilerplate，比 Jotai 更适合复杂状态

```typescript
// appStore.ts 示例
import { create } from 'zustand'
import { persist } from 'zustand/middleware'

interface AppState {
  workers: Worker[]
  tasks: Task[]
  selectedTaskId: string | null
  wsConnected: boolean
  setWorkers: (workers: Worker[]) => void
  setTasks: (tasks: Task[]) => void
  selectTask: (id: string | null) => void
}

export const useAppStore = create<AppState>()(
  persist(
    (set) => ({
      workers: [],
      tasks: [],
      selectedTaskId: null,
      wsConnected: false,
      setWorkers: (workers) => set({ workers }),
      setTasks: (tasks) => set({ tasks }),
      selectTask: (id) => set({ selectedTaskId: id }),
    }),
    { name: 'array-app-store', partialize: (s) => ({ selectedTaskId: s.selectedTaskId }) }
  )
)
```

### 7.2 消息系统：自定义 Hook

不使用 Vercel AI SDK 的 `useChat()`，因为：
- 本项目的消息模型更复杂（私密消息、@提及、引用回复、附件）
- WebSocket 事件格式是后端自定义的
- 需要精确控制乐观消息的生命周期

自定义 `useMessages` Hook 借鉴 AI SDK 的状态机思想：

```typescript
type MessageStatus = 'idle' | 'sending' | 'streaming' | 'error'

interface UseMessagesReturn {
  messages: Message[]
  pendingMessages: PendingMessage[]
  isLoading: boolean
  isAtBottom: boolean
  sendMessage: (content: string, options?: SendOptions) => Promise<void>
  retryMessage: (pendingId: string) => Promise<void>
  cancelMessage: (pendingId: string) => void
  loadMore: () => Promise<void>
  hasMore: boolean
  scrollToBottom: () => void
}
```

### 7.3 主题系统：Tailwind CSS 变量

```css
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --accent: 221.2 83.2% 53.3%;
  /* ... shadcn 默认变量 */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --primary: 217.2 91.2% 59.8%;
  --accent: 217.2 91.2% 59.8%;
}
```

切换主题只需在 `<html>` 上添加/移除 `dark` 类，所有组件自动响应。

### 7.4 SDK 迁移策略

array-sdk 是纯 JavaScript，无框架依赖，直接迁移：
- `sdk-js/` 目录整体复制到新项目
- `package.json` 中 `"array-sdk": "file:./sdk-js"` 保持不变
- API 封装层 `lib/api.ts` 从旧项目 `api/index.js` 翻译为 TypeScript
- 所有方法签名添加 TypeScript 类型

### 7.5 组件拆分原则

旧项目 TaskDetail.vue 72KB → 拆分为 8+ 个子组件：

| 旧代码位置 | 新组件 | 职责 |
|------------|--------|------|
| 消息流模板 | `MessageList.tsx` | 消息列表渲染 + 时间分割线 |
| 单条消息 | `MessageBubble.tsx` | 消息气泡 + 头像 + 引用 + 附件 |
| 回复输入栏 | `MessageInput.tsx` | 输入框 + 发送按钮 + 快捷键 |
| @提及弹窗 | `MentionPopup.tsx` | 搜索 + 选择参与者 |
| 私密消息 | `DMTab.tsx` | 私聊通道列表 + 消息 |
| 附件渲染 | `AttachmentRenderer.tsx` | 图片/视频/音频/文件智能渲染 |
| 任务抽屉 | `TaskDrawer.tsx` | 参与者 + 详情 + 评价 |
| 状态选择器 | `StatusSelector.tsx` | 状态下拉切换 |