# 项目结构

本文档详细描述 `admin2-components` 项目的目录结构和组件分类规范。

## 整体结构

```
admin2-components/
├── src/                    # 源代码
│   ├── framework/          # 框架组件 - 页面主结构
│   ├── forms/              # 表单组件 - 用户输入
│   ├── fragments/          # 页面片段 - 布局元素
│   ├── plugins/            # 高级组件 - 复杂功能
│   ├── bases/              # 业务组件 - 领域特定
│   └── assets/             # 静态资源
├── test/                   # Vitest 测试配置和案例
├── example/                # 组件展示案例
├── public/                 # 公共资源
├── openspec/               # 变更管理
├── README.md               # 项目概述
├── CLAUDE.md               # Claude 工作指导
└── STRUCTURE.md            # 本文档
```

## src/ 目录

### framework/ - 框架组件

页面主结构相关的组件，管理系统的整体布局。

```
framework/
├── headerBar/      # 顶部导航栏
├── sideMenu/       # 侧边菜单
├── pageViews/      # 多页签视图
├── screenGrid/     # 屏幕网格布局
└── scrollablePanes/ # 可滚动面板
```

**典型组件**: `CHeaderBar`, `CSideMenu`, `CPageViews`, `CScreenGrid`

### forms/ 表单组件

处理用户输入的各类表单组件。

```
forms/
├── datePicker/         # 日期选择
├── cascader/           # 级联选择
├── select/             # 下拉选择
├── input/              # 文本输入
├── upload/             # 文件上传
├── colorPicker/        # 颜色选择
├── chinaAddress/       # 中国地址级联
└── ...
```

**典型组件**: `CDatePicker`, `CChinaCascader`, `CImageUploader`, `CFileUploader`

### fragments/ - 页面片段

页面中的小型布局元素和UI片段。

```
fragments/
├── contentBox/     # 内容盒子
├── gridBox/        # 网格盒子
├── flatForm/       # 扁平表单
├── helper/         # 辅助工具
├── notice/         # 通知提示
├── text/           # 文本组件
├── icons/          # 图标组件
└── ...
```

**典型组件**: `CContentBox`, `CGridBox`, `CFlatForm`, `CHelper`, `CNotice`

### plugins/ - 高级组件

复杂功能组件，通常包含较多业务逻辑。

```
plugins/
├── richTable/       # 高级表格
├── tableForm/       # 表格表单
├── editableTable/   # 可编辑表格
├── echarts/         # 图表组件
├── draggableModal/  # 可拖拽弹窗
├── detailTabsModel/ # 详情页签弹窗
├── imageViewer/     # 图片查看器
├── itemEditor/      # 条目编辑器
├── richEditor/      # 富文本编辑器
└── ...
```

**典型组件**: `CRichTable`, `CEditableTable`, `CEchartsPie`, `CDraggableModal`

### bases/ - 业务组件

领域特定的业务组件，与具体业务场景强相关。

```
bases/
├── Director/            # 总监相关
├── DirectorHome/        # 总监首页
├── DirectorOperationListing/  # 运营列表
└── ...
```

**典型组件**: `Director`, `DirectorHome`, `DirectorOperationListing`

### assets/ - 静态资源

静态资源文件，如图片、数据文件等。

```
assets/
├── images/        # 图片资源
├── datas/         # 数据文件（如地区数据）
└── ...
```

## test/ - 测试目录

Vitest 测试配置和测试案例。

```
test/
├── setup.ts       # Jest DOM 全局断言配置
├── unit/          # 单元测试
├── integration/   # 集成测试
└── e2e/           # 端到端测试（Playwright）
```

## example/ - 组件展示案例

用于独立展示和调试组件的示例页面，是项目的入口点。

```
example/
├── App.tsx       # 演示应用入口
├── main.tsx      # 渲染入口
└── index.css    # 全局样式
```

**入口文件**: `index.html` 引用 `/example/main.tsx` 作为模块入口。

## 文件命名规范

### 组件文件

- **组件文件**: 以 `C` 开头，如 `CButton.tsx`
- **样式文件**: 以 `c` 开头，如 `cButton.scss`
- **类型文件**: 以 `types` 结尾，如 `buttonTypes.ts`

### 目录命名

- 组件目录: 使用 CamelCase，如 `datePicker`、`richTable`
- 目录内的组件文件放在对应名称的子目录中

### 示例

```
forms/
└── datePicker/
    ├── CDatePicker.tsx      # 主组件
    ├── cDatePicker.scss     # 样式
    ├── useDatePicker.ts     # Hook（可选）
    └── datePickerTypes.ts   # 类型定义（可选）
```

## 组件开发规范

1. **函数组件**: 使用函数式组件 + Hooks
2. **TypeScript**: 严格模式，提供完整的类型定义
3. **样式隔离**: 使用 CSS Modules 或 SCSS 避免样式污染
4. **单一职责**: 每个组件专注于单一功能
5. **可复用性**: 提取通用逻辑为自定义 Hook