| 1 | # Components 组件库 |
| 2 | |
| 3 | 本目录存放跨页面复用的全局组件。开发前先确认组件归属，避免把页面私有组件、业务域组件和 UI primitive 混在根目录。 |
| 4 | |
| 5 | ## 目录边界 |
| 6 | |
| 7 | | 目录 | 说明 | |
| 8 | | ----------------- | --------------------------------------------------------------------------------------------- | |
| 9 | | `ui/` | shadcn/ui 基础组件与项目级 UI primitive，只放低业务语义的按钮、弹窗、表单、选择器等基础能力。 | |
| 10 | | `common/` | 跨页面、跨业务域复用的小型通用组件，例如图片、头像、通用弹窗入口。 | |
| 11 | | `Chat/` | 聊天和 AI Agent 任务会话相关共享组件。 | |
| 12 | | `Plugin/` | 浏览器插件相关共享组件。 | |
| 13 | | `PublishDialog/` | 内容发布对话框及发布流程组件。 | |
| 14 | | `ChannelManager/` | 频道管理弹窗与相关状态，当前保留为全局业务组件。 | |
| 15 | | `draft-box/` | 草稿箱共享业务组件。 | |
| 16 | |
| 17 | ## 放置规则 |
| 18 | |
| 19 | - 禁止在 `src/components` 根目录新增孤立业务组件；必须归入 `common`、`ui` 或明确业务域目录。 |
| 20 | - 仅跨页面、跨业务域复用且低业务耦合的小组件放入 `common`。 |
| 21 | - 明确属于某个业务域的复用组件放入对应二级目录，例如草稿箱组件放 `draft-box/`。 |
| 22 | - 只在单个页面、布局或模块内使用的组件放到对应局部 `components/`，不要提前提升到全局目录。 |
| 23 | - 新增或调整二级目录组件时，更新该二级目录自己的 `README.md`；顶层 README 只维护目录边界和索引。 |
| 24 | - 组件目录使用 PascalCase 独立文件夹，通过 `index.tsx` 导出；样式文件使用 `[组件名].module.scss`。 |
| 25 | |
| 26 | ## 二级目录文档 |
| 27 | |
| 28 | - `common/README.md`：通用小组件清单与边界。 |
| 29 | - `Chat/README.md`：聊天业务域组件清单。 |
| 30 | - 其它业务域目录在新增组件或迁移组件时同步补充自己的 `README.md`。 |
| 31 | |
| 32 | ## 关键说明 |
| 33 | |
| 34 | ### `ui/` - shadcn/ui 基础组件 |
| 35 | |
| 36 | 新增 shadcn/ui 组件时使用项目既有方式安装或复制，并保持低业务语义。禁止把频道、聊天、插件、草稿箱等业务组件放入 `ui/`。 |
| 37 | |
| 38 | ### `ChannelManager/` - 频道管理弹窗 |
| 39 | |
| 40 | 当前作为全局业务组件保留在 `src/components/ChannelManager`。如后续要移动到 layout，必须先拆出中立 store，避免普通页面直接依赖 `src/app/layout` 内部实现。 |
| 41 | |
| 42 | ### `PublishDialog/` - 内容发布对话框 |
| 43 | |
| 44 | PC 端与移动端发布流程分离；修改发布能力时必须同时检查桌面端、移动端和插件发布联动。 |
| 45 | |
| 46 | ## 新增组件检查 |
| 47 | |
| 48 | 1. 先查阅本文件和目标二级目录 `README.md`，确认无可复用组件。 |
| 49 | 2. 确认组件是否跨页面复用；单页使用优先放页面局部目录。 |
| 50 | 3. 确认业务域归属；不要因为“可能以后复用”提前放到全局根目录。 |
| 51 | 4. 新增全局组件后同步更新对应二级目录 `README.md`。 |
| 52 |