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

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)

Analyze: 分析原组件（如 Next.js 项目中的组件）的所有依赖项、状态变量和事件处理器。
Decouple: 定义清晰的 Props 接口，将所有逻辑抽离到 Container 层。
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

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

4. Git 与协作规范

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