# 🏗️ 项目设计规范与组件应用指南

## 1. 核心架构模式：Type B (Decoupled/Presentational)
本项目在进行复杂组件（如 `Chat`）迁移时，严格遵循 **"Smart Container + Dumb View"** 的解耦策略。

### 🧩 组件分类定义
*   **Smart Component (Container)**:
    *   **职责**: 负责业务逻辑、状态管理（Zustand/Redux）、API 调用、副作用处理（`useEffect`）。
    *   **特征**: 不直接编写复杂的 HTML/CSS，而是通过 Props 将数据和回调函数传递给 View 层。
    *   **示例**: `ChatContainer.tsx`
*   **Dumb Component (Presentational)**:
    *   **职责**: 负责 UI 渲染、样式展示、响应用户交互（触发 Props 中的回调）。
    *   **特征**: 纯函数式风格，高度依赖 Props，不直接访问全局 Store。易于测试和复用。
    *   **示例**: `ChatView.tsx`, `ChatActions.tsx`

### 🚀 开发 SOP (Standard Operating Procedure)
1.  **Analyze**: 分析原组件（如 Next.js 项目中的组件）的所有依赖项、状态变量和事件处理器。
2.  **Decouple**: 定义清晰的 `Props` 接口，将所有逻辑抽离到 Container 层。
3.  **Implement**: 先实现无状态的 View 层，再实现有状态的 Container 层进行集成。

---

## 2. UI 与样式规范 (UI & Styling)

### 🎨 设计语言
*   **基础风格**: 基于 Ant Design 的设计体系，强调简洁、专业感。
*   **圆角规范**: 全局统一使用 `8px` 圆角。
*   **颜色系统**: 优先使用 CSS Variables (如 `var(--primary)`, `var(--white)`, `var(--border-in-light)`)，严禁在 SCSS 中硬编码颜色值。

### 💅 样式实现规则
*   **CSS Modules**: 所有组件必须配套 `.module.scss` 文件，通过 `styles.className` 进行引用，防止全局样式污染。
*   **SCSS 规范**:
    *   使用 `@use` 而非 `@import`。
    *   避免冗余嵌套，保持选择器层级扁平化。
    *   间距与布局应通过变量或统一的 Utility Class 管理。

---

## 3. 公共组件应用规则 (Component Usage Rules)

### 🛠️ 组件分层使用指南

#### **A. 原子/基础组件 (Atomic Components)**
*   **来源**: `src/components/chat-client/button.tsx` 或 Ant Design 原生组件。
*   **原则**: 所有的交互按钮（IconButton, Button）必须优先使用封装好的原子组件，以保证视觉一致性。

#### **B. UI 库组件 (UI Library Components)**
*   **来源**: `src/components/chat-client/ui-lib.tsx`。
*   **用途**: 用于构建业务场景下的通用布局单元（如 `List`, `ListItem`, `Card`, `Popover`, `Toast`）。
*   **规则**:
    *   当需要实现类似“列表项”、“弹窗遮罩”或“加载状态”时，必须检查 `ui-lib` 是否已有实现。
    *   禁止在业务组件中重复编写基础的 `List` 或 `Modal` 样式逻辑。

#### **C. 业务复合组件 (Composite Components)**
*   **来源**: `src/components/chat-client/` 下的其他业务模块。
*   **规则**: 遵循上述 **Type B** 模式进行组合。例如，`ChatView` 会组合使用 `ChatActions`, `MessageSelector`, 和 `ui-lib` 中的组件。

### 📋 组件开发 Checklist
1.  [ ] **是否解耦？** 如果是复杂业务组件，是否拆分了 Container 和 View？
2.  [ ] **Props 是否完备？** View 层是否通过 Props 获取了所有必要的数据和回调？
3.  [ ] **样式是否规范？** 是否使用了 CSS Modules？是否使用了全局变量而非硬编码颜色/间距？
4.  [ ] **是否复用了 UI-Lib？** 是否在重复造 `List` 或 `Loading` 的轮子？
5.  [ ] **图标是否统一？** 是否优先使用了 Ant Design Icons 库？

---

## 4. Git 与协作规范
*   **提交信息**: 遵循 `type: description` 格式（如 `feat:`, `fix:`, `style:`, `docs:`, `refactor:`）。
*   **原子提交**: 在进行大规模重构前，必须先提交当前工作进度。
*   **文档同步**: 任何重大架构变更或交互逻辑调整，必须同步更新至项目文档（如 `INTERACTION_LOGIC.md` 或 `.claude-rules.md`）。