From 75c8d2c51f967c029b146ba0e4cff082efe71753 Mon Sep 17 00:00:00 2001
From: Tevin <tingquanren@163.com>
Date: Thu, 02 Apr 2026 16:11:59 +0800
Subject: [PATCH] docs: 更新项目文档，添加 STRUCTURE.md 结构说明
---
openspec/changes/archive/2026-04-02-update-project-docs-structure/.openspec.yaml | 2
openspec/changes/archive/2026-04-02-update-project-docs-structure/specs/docs-update/spec.md | 8 +
openspec/changes/archive/2026-04-02-update-project-docs-structure/proposal.md | 22 +++
openspec/changes/archive/2026-04-02-update-project-docs-structure/design.md | 58 +++++++++
openspec/changes/archive/2026-04-02-update-project-docs-structure/tasks.md | 16 ++
STRUCTURE.md | 164 +++++++++++++++++++++++++++
README.md | 45 ++++++-
7 files changed, 309 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
index 44d8676..b435336 100644
--- a/README.md
+++ b/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)
## 可用脚本
@@ -29,4 +60,6 @@
- 使用 TypeScript 严格模式
- ESLint 配置了类型检查规则，提交前需通过 lint
-- 组件开发遵循函数式组件 + Hooks 模式
\ No newline at end of file
+- 组件开发遵循函数式组件 + Hooks 模式
+- 组件文件以 `C` 开头（如 `CButton.tsx`）
+- 样式文件与组件同目录，使用 `c` 开头（如 `cButton.scss`）
\ No newline at end of file
diff --git a/STRUCTURE.md b/STRUCTURE.md
new file mode 100644
index 0000000..b6967f3
--- /dev/null
+++ b/STRUCTURE.md
@@ -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
\ No newline at end of file
diff --git a/openspec/changes/archive/2026-04-02-update-project-docs-structure/.openspec.yaml b/openspec/changes/archive/2026-04-02-update-project-docs-structure/.openspec.yaml
new file mode 100644
index 0000000..6a5db8c
--- /dev/null
+++ b/openspec/changes/archive/2026-04-02-update-project-docs-structure/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02
diff --git a/openspec/changes/archive/2026-04-02-update-project-docs-structure/design.md b/openspec/changes/archive/2026-04-02-update-project-docs-structure/design.md
new file mode 100644
index 0000000..75e9647
--- /dev/null
+++ b/openspec/changes/archive/2026-04-02-update-project-docs-structure/design.md
@@ -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 中预留位置，待后续补充
\ No newline at end of file
diff --git a/openspec/changes/archive/2026-04-02-update-project-docs-structure/proposal.md b/openspec/changes/archive/2026-04-02-update-project-docs-structure/proposal.md
new file mode 100644
index 0000000..c307e9f
--- /dev/null
+++ b/openspec/changes/archive/2026-04-02-update-project-docs-structure/proposal.md
@@ -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
+- 开发规范: 组件目录组织方式
\ No newline at end of file
diff --git a/openspec/changes/archive/2026-04-02-update-project-docs-structure/specs/docs-update/spec.md b/openspec/changes/archive/2026-04-02-update-project-docs-structure/specs/docs-update/spec.md
new file mode 100644
index 0000000..634cd4b
--- /dev/null
+++ b/openspec/changes/archive/2026-04-02-update-project-docs-structure/specs/docs-update/spec.md
@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: 文档结构规范化
+本项目为文档更新任务，不涉及新功能规格。文档更新包括 README.md、CLAUDE.md、STRUCTURE.md 的内容调整。
+
+#### Scenario: 文档更新完成
+- **WHEN** 项目文档结构完成更新
+- **THEN** README 包含项目定位和组件分类概述，CLAUDE 保留终端命令规范，STRUCTURE 包含详细目录结构
\ No newline at end of file
diff --git a/openspec/changes/archive/2026-04-02-update-project-docs-structure/tasks.md b/openspec/changes/archive/2026-04-02-update-project-docs-structure/tasks.md
new file mode 100644
index 0000000..b824a26
--- /dev/null
+++ b/openspec/changes/archive/2026-04-02-update-project-docs-structure/tasks.md
@@ -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 开头）
\ No newline at end of file
--
Gitblit v1.9.1