项目结构

本文档详细描述 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   # 类型定义（可选）

组件开发规范

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