docs: 更新项目文档，添加 STRUCTURE.md 结构说明

Tevin

9 days ago 75c8d2c51f967c029b146ba0e4cff082efe71753

docs: 更新项目文档，添加 STRUCTURE.md 结构说明

- 更新 README.md：补充项目定位、git 子模块引用方式、组件分类
- 新建 STRUCTURE.md：详细描述目录结构和组件分类规范
- 更新 CLAUDE.md：保持现有指引不变
- 添加 openspec 变更管理文档

Co-Authored-By: ClaudeCode <noreply@anthropic.com>

 README.md

@@ -1,6 +1,13 @@
# admin2-components

基于 React + TypeScript + Vite 的组件库项目
PC 端管理系统公共组件库，基于 React + TypeScript + Ant Design 构建。

## 项目定位

本项目是一套 PC 端管理系统的公共组件库，提供：
- **框架组件** - 管理系统页面主结构（侧边栏、顶部栏、多页签等）
- **表单组件** - 处理用户输入（日期选择、级联选择、文件上传等）
- **高级组件** - 复杂功能（表格、图表、弹窗、编辑器等）

## 技术栈

@@ -10,11 +17,35 @@
- Ant Design 6.3.5
- ESLint 9 (Flat Config)

## 项目类型
## 引用方式

- **UI 框架**: Ant Design
- **包管理器**: pnpm
- **代码规范**: ESLint (类型检查 + React X + React DOM)
作为 git 子模块挂载到业务项目根目录：

```bash
# 添加子模块到项目根目录
git submodule add <repository-url> components

# 更新子模块
git submodule update --init --recursive
```

业务项目需配置别名 `@components` 指向 `components/src` 目录。组件引用示例：

```tsx
import { CSideMenu } from '@components/framework/sideMenu/CSideMenu';
```

## 组件分类

| 分类 | 说明 |
|------|------|
| `framework` | 框架组件 - 页面主结构 |
| `forms` | 表单组件 - 用户输入 |
| `fragments` | 页面片段 - 布局元素 |
| `plugins` | 高级组件 - 复杂功能 |
| `bases` | 业务组件 - 领域特定 |

详细目录结构说明见 [STRUCTURE.md](./STRUCTURE.md)

## 可用脚本

@@ -30,3 +61,5 @@
- 使用 TypeScript 严格模式
- ESLint 配置了类型检查规则，提交前需通过 lint
- 组件开发遵循函数式组件 + Hooks 模式
- 组件文件以 `C` 开头（如 `CButton.tsx`）
- 样式文件与组件同目录，使用 `c` 开头（如 `cButton.scss`）

 STRUCTURE.md

New file
@@ -0,0 +1,164 @@
# 项目结构

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

## 整体结构

```
admin2-components/
├── src/                    # 源代码
│   ├── framework/          # 框架组件 - 页面主结构
│   ├── forms/              # 表单组件 - 用户输入
│   ├── fragments/          # 页面片段 - 布局元素
│   ├── plugins/            # 高级组件 - 复杂功能
│   ├── bases/              # 业务组件 - 领域特定
│   └── assets/             # 静态资源
├── test/                   # 测试案例（待补充）
├── 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/ - 测试案例

测试目录，待测试框架确定后补充结构。

初步规划：
```
test/
├── unit/          # 单元测试
├── integration/   # 集成测试
└── e2e/           # 端到端测试
```

## 文件命名规范

### 组件文件

- **组件文件**: 以 `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

 openspec/changes/archive/2026-04-02-update-project-docs-structure/.openspec.yaml

New file
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-04-02

 openspec/changes/archive/2026-04-02-update-project-docs-structure/design.md

New file
@@ -0,0 +1,58 @@
## Context

项目为 PC 端管理系统的公共组件库，技术栈为 React 19 + TypeScript + Ant Design 6.x。组件来源参考 `D:\AiSim\AdminManager\src\components`，采用 git 子模块方式挂载到业务项目，不走 npm 发布。

当前文档状态：
- README.md: 仅包含基础技术栈说明，缺少项目定位
- CLAUDE.md: 已包含终端命令规范
- STRUCTURE.md: 不存在

## Goals / Non-Goals

**Goals:**
- 清晰描述项目定位（公共组件库、git 子模块引用）
- 建立规范的组件目录分类体系
- 明确各文档职责分工

**Non-Goals:**
- 不涉及组件实现细节
- 不制定测试框架规范（后续讨论）
- 不规划组件导出方式（保持现有直接 import）

## Decisions

### 1. 文档分工

| 文件 | 内容定位 |
|------|----------|
| README.md | 项目概述、技术栈、快速开始、组件分类概述 |
| CLAUDE.md | Claude Code 工作指导（终端命令规范） |
| STRUCTURE.md | 详细目录结构说明、组件分类规范 |

**理由**: 遵循社区惯例，README 作为入口文档，CLAUDE.md 专门给 Claude Code 使用，结构文档独立更清晰。

### 2. 文件名选择: STRUCTURE.md vs project_structure.md

采用 `STRUCTURE.md`（全大写），理由：
- 与 `README`、`CHANGELOG` 风格一致
- 简洁醒目，约定俗成

### 3. 组件目录分类

沿用参考项目的分类方式：

```
src/
├── framework/   # 框架组件 - 页面主结构
├── forms/       # 表单组件 - 用户输入
├── fragments/   # 页面片段 - 布局元素
├── plugins/     # 高级组件 - 复杂功能
├── bases/       # 业务组件 - 领域特定
├── assets/      # 静态资源
test/            # 测试案例（待定测试框架）
```

## Risks / Trade-offs

- [风险] 组件分类可能随项目演进需要调整 → 文档保持简洁，后续迭代更新
- [风险] 测试框架待定，test 目录结构暂不明确 → STRUCTURE.md 中预留位置，待后续补充

 openspec/changes/archive/2026-04-02-update-project-docs-structure/proposal.md

New file
@@ -0,0 +1,22 @@
## Why

项目是 PC 端管理系统的公共组件库，需要更新文档以清晰描述项目定位、组件分类结构和开发规范。当前 README 内容过于简单，缺少项目结构说明和组件目录规范。

## What Changes

- **更新 README.md**: 补充项目定位（公共组件库、git 子模块引用）、组件分类概述
- **更新 CLAUDE.md**: 保持现有指引（可微调）
- **新建 STRUCTURE.md**: 详细描述 src 目录结构、组件分类规范、测试目录规划

## Capabilities

### New Capabilities
<!-- 文档更新任务，不涉及新的功能规格 -->

### Modified Capabilities
<!-- 无现有 specs 可修改 -->

## Impact

- 文档文件: README.md, CLAUDE.md, STRUCTURE.md
- 开发规范: 组件目录组织方式

 openspec/changes/archive/2026-04-02-update-project-docs-structure/specs/docs-update/spec.md

New file
@@ -0,0 +1,8 @@
## ADDED Requirements

### Requirement: 文档结构规范化
本项目为文档更新任务，不涉及新功能规格。文档更新包括 README.md、CLAUDE.md、STRUCTURE.md 的内容调整。

#### Scenario: 文档更新完成
- **WHEN** 项目文档结构完成更新
- **THEN** README 包含项目定位和组件分类概述，CLAUDE 保留终端命令规范，STRUCTURE 包含详细目录结构

 openspec/changes/archive/2026-04-02-update-project-docs-structure/tasks.md

New file
@@ -0,0 +1,16 @@
## 1. 更新 README.md

- [x] 1.1 补充项目定位（公共组件库、git 子模块引用方式）
- [x] 1.2 添加组件分类概述
- [x] 1.3 补充项目结构简要说明

## 2. 更新 CLAUDE.md

- [x] 2.1 检查并微调现有终端命令规范（如有需要）

## 3. 新建 STRUCTURE.md

- [x] 3.1 描述 src 目录结构和各子目录职责
- [x] 3.2 定义组件分类规范（framework/forms/fragments/plugins/bases/assets）
- [x] 3.3 规划 test 测试目录结构（预留位置，待测试框架确定后补充）
- [x] 3.4 添加文件命名规范说明（如组件文件以 C 开头）