refactor: 代码架构重构 - 提取组件、统一状态管理和数据访问层
- 新增布局组件（SidebarBrand、SidebarUser、SidebarNavItem） - 新增通用UI组件（EmptyState、StatusBadge、TagInput、SearchBar） - 新增全局状态管理（UserContext） - 新增自定义Hooks（usePageState、useNavigation） - 新增统一数据访问层（src/services/api.js） - 新增常量配置（constants/pages.js、constants/storageKeys.js） - 样式文件模块化，拆分页面特定样式 - 更新README文档，添加组件和使用说明 - 同步OpenSpec规范到主specs目录
This commit is contained in:
228
README.md
228
README.md
@@ -82,11 +82,22 @@ grandclaw-archtype/
|
||||
├── src/ # 源代码
|
||||
│ ├── App.jsx # 主路由配置
|
||||
│ ├── main.jsx # 应用入口
|
||||
│ ├── components/ # 通用组件
|
||||
│ ├── components/ # 组件
|
||||
│ │ ├── layout/ # 布局组件（SidebarBrand、SidebarUser、SidebarNavItem）
|
||||
│ │ ├── common/ # 通用UI组件（EmptyState、StatusBadge、TagInput、SearchBar）
|
||||
│ │ ├── Layout.jsx # 通用布局组件（侧边栏+主内容）
|
||||
│ │ └── ListSelector.jsx # 列表选择器组件（支持单选/多选）
|
||||
│ ├── contexts/ # 全局状态管理
|
||||
│ │ └── UserContext.jsx # 用户信息上下文
|
||||
│ ├── hooks/ # 自定义Hook
|
||||
│ │ └── useLocalStorage.js # localStorage状态管理Hook
|
||||
│ │ ├── useLocalStorage.js # localStorage状态管理Hook
|
||||
│ │ ├── usePageState.js # 页面状态持久化Hook
|
||||
│ │ └── useNavigation.js # 导航逻辑Hook
|
||||
│ ├── constants/ # 常量定义
|
||||
│ │ ├── pages.js # 页面配置（路由、标题、图标）
|
||||
│ │ └── storageKeys.js # localStorage键名常量
|
||||
│ ├── services/ # 数据访问层
|
||||
│ │ └── api.js # 统一数据访问接口
|
||||
│ ├── data/ # 模拟数据
|
||||
│ │ ├── conversations.js # 聊天场景数据
|
||||
│ │ ├── developerData.js # 开发台数据
|
||||
@@ -232,7 +243,105 @@ import { HashRouter as Router, Routes, Route } from 'react-router-dom';
|
||||
|
||||
## 通用组件
|
||||
|
||||
### ListSelector 列表选择器
|
||||
### 布局组件
|
||||
|
||||
#### SidebarBrand 品牌区域
|
||||
侧边栏顶部的品牌展示组件。
|
||||
|
||||
```jsx
|
||||
import { SidebarBrand } from '../components/layout/SidebarBrand.jsx';
|
||||
|
||||
<SidebarBrand subtitle="企业级AI平台" />
|
||||
```
|
||||
|
||||
#### SidebarUser 用户信息
|
||||
侧边栏底部的用户信息展示组件，使用全局用户上下文。
|
||||
|
||||
```jsx
|
||||
import { SidebarUser } from '../components/layout/SidebarUser.jsx';
|
||||
|
||||
<SidebarUser
|
||||
onClick={() => navigate('/account')}
|
||||
wrapperClassName="sidebar-user"
|
||||
infoClassName="sidebar-user-info"
|
||||
nameClassName="sidebar-user-name"
|
||||
roleClassName="sidebar-user-role"
|
||||
/>
|
||||
```
|
||||
|
||||
#### SidebarNavItem 导航项
|
||||
侧边栏导航菜单项组件。
|
||||
|
||||
```jsx
|
||||
import { SidebarNavItem } from '../components/layout/SidebarNavItem.jsx';
|
||||
|
||||
<SidebarNavItem
|
||||
icon={<FiMessageSquare />}
|
||||
label="智能助手"
|
||||
active={currentPage === 'chat'}
|
||||
onClick={() => setCurrentPage('chat')}
|
||||
itemClassName="sidebar-nav-item"
|
||||
iconClassName="sidebar-nav-icon"
|
||||
textClassName="sidebar-nav-text"
|
||||
/>
|
||||
```
|
||||
|
||||
### 通用UI组件
|
||||
|
||||
#### EmptyState 空状态
|
||||
用于展示空列表或无数据状态的组件。
|
||||
|
||||
```jsx
|
||||
import EmptyState from '../components/common/EmptyState.jsx';
|
||||
|
||||
<EmptyState
|
||||
icon={<FiInbox size={48} />}
|
||||
title="暂无数据"
|
||||
description="当前没有可显示的内容"
|
||||
/>
|
||||
```
|
||||
|
||||
#### StatusBadge 状态标签
|
||||
用于显示状态（成功、失败、警告等）的标签组件。
|
||||
|
||||
```jsx
|
||||
import StatusBadge from '../components/common/StatusBadge.jsx';
|
||||
|
||||
<StatusBadge status="success" text="运行中" />
|
||||
<StatusBadge status="error" text="失败" />
|
||||
<StatusBadge status="warning" text="警告" />
|
||||
<StatusBadge status="stopped" text="已停止" />
|
||||
```
|
||||
|
||||
#### TagInput 标签输入
|
||||
支持输入标签的输入框组件。
|
||||
|
||||
```jsx
|
||||
import TagInput from '../components/common/TagInput.jsx';
|
||||
|
||||
<TagInput
|
||||
tags={tags}
|
||||
onChange={setTags}
|
||||
placeholder="输入标签后按回车添加"
|
||||
/>
|
||||
```
|
||||
|
||||
#### SearchBar 搜索框
|
||||
通用的搜索输入框组件。
|
||||
|
||||
```jsx
|
||||
import SearchBar from '../components/common/SearchBar.jsx';
|
||||
|
||||
<SearchBar
|
||||
value={searchQuery}
|
||||
onChange={setSearchQuery}
|
||||
placeholder="搜索..."
|
||||
/>
|
||||
```
|
||||
|
||||
### 列表组件
|
||||
|
||||
#### ListSelector 列表选择器
|
||||
通用的列表选择器组件，支持单选和多选模式。
|
||||
|
||||
```jsx
|
||||
@@ -252,11 +361,69 @@ import ListSelector from '../components/ListSelector.jsx';
|
||||
|
||||
## 状态管理
|
||||
|
||||
### 1. 路由状态
|
||||
- **顶级路由**：由React Router的URL哈希管理
|
||||
- **子页面状态**：使用`localStorage`持久化
|
||||
### 全局状态
|
||||
|
||||
### 2. 导航状态持久化策略
|
||||
#### UserContext 用户信息上下文
|
||||
全局用户信息状态，通过 `UserProvider` 提供给整个应用。
|
||||
|
||||
```jsx
|
||||
import { UserProvider, useUserContext } from '../contexts/UserContext.jsx';
|
||||
|
||||
// 在 App.jsx 中包裹
|
||||
<UserProvider user={{ name: '张三', avatar: '张', role: 'AI 产品部' }}>
|
||||
<App />
|
||||
</UserProvider>
|
||||
|
||||
// 在组件中使用
|
||||
function Component() {
|
||||
const { user } = useUserContext();
|
||||
return <div>{user.name}</div>;
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义 Hooks
|
||||
|
||||
#### usePageState 页面状态持久化
|
||||
处理页面切换状态的 Hook，支持 localStorage 持久化和主页跳转重置。
|
||||
|
||||
```javascript
|
||||
import { usePageState } from '../hooks/usePageState.js';
|
||||
import { CONSOLE_PAGES } from '../constants/pages.js';
|
||||
import { CONSOLE_KEYS } from '../constants/storageKeys.js';
|
||||
|
||||
const { currentPage, setCurrentPage } = usePageState({
|
||||
storageKey: CONSOLE_KEYS.CURRENT_PAGE,
|
||||
defaultPage: 'chat',
|
||||
pageTitles: CONSOLE_PAGES,
|
||||
});
|
||||
```
|
||||
|
||||
#### useNavigation 导航逻辑
|
||||
封装页面导航逻辑的 Hook，支持携带额外数据。
|
||||
|
||||
```javascript
|
||||
import { useNavigation } from '../hooks/useNavigation.js';
|
||||
|
||||
const { navigateToPage, extraData } = useNavigation(setCurrentPage);
|
||||
|
||||
// 导航到指定页面
|
||||
navigateToPage('skills', { skillId: '1' });
|
||||
|
||||
// 获取导航传递的数据
|
||||
const skillId = extraData.skillId;
|
||||
```
|
||||
|
||||
#### useLocalStorage localStorage 状态管理
|
||||
同步组件状态到 localStorage 的 Hook。
|
||||
|
||||
```javascript
|
||||
import { useLocalStorage } from '../hooks/useLocalStorage.js';
|
||||
|
||||
const [value, setValue] = useLocalStorage('myKey', 'defaultValue');
|
||||
setValue('newValue'); // 自动同步到 localStorage
|
||||
```
|
||||
|
||||
### 导航状态持久化策略
|
||||
每个主要页面（工作台、管理台、开发台）都有独立的`localStorage`键：
|
||||
|
||||
```javascript
|
||||
@@ -272,7 +439,7 @@ localStorage.setItem('developer_currentPage', 'mySkills');
|
||||
localStorage.setItem('developer_currentSkillId', '1');
|
||||
```
|
||||
|
||||
### 3. 主页跳转 vs 刷新浏览器
|
||||
### 主页跳转 vs 刷新浏览器
|
||||
通过`location.state.fromHome`区分两种导航来源：
|
||||
|
||||
```javascript
|
||||
@@ -339,9 +506,46 @@ $radius-md: 8px;
|
||||
- `role-member` - 成员（灰色）
|
||||
- `role-developer` - 开发者（橙色）
|
||||
|
||||
## 数据访问层
|
||||
|
||||
项目使用统一的数据访问接口 `src/services/api.js`，所有数据获取都通过 API 层进行，便于未来对接后端服务。
|
||||
|
||||
### API 使用示例
|
||||
|
||||
```javascript
|
||||
import { api } from '../services/api.js';
|
||||
|
||||
// 获取技能列表
|
||||
const skills = api.skills.list();
|
||||
|
||||
// 获取单个技能详情
|
||||
const skill = api.skills.getById('1');
|
||||
|
||||
// 获取日志列表
|
||||
const logs = api.logs.list();
|
||||
|
||||
// 按条件筛选日志
|
||||
const filteredLogs = api.logs.filter({ user, type, status });
|
||||
|
||||
// 获取开发者技能
|
||||
const mySkills = api.developer.getMySkills();
|
||||
|
||||
// 获取成员列表
|
||||
const members = api.members.list();
|
||||
```
|
||||
|
||||
### API 模块结构
|
||||
- `api.user` - 用户信息
|
||||
- `api.skills` - 技能市场（列表、详情、文件、版本、图标）
|
||||
- `api.conversations` - 聊天场景和对话历史
|
||||
- `api.logs` - 操作日志（列表、筛选）
|
||||
- `api.developer` - 开发台数据（技能、分类、模型、文档）
|
||||
- `api.members` - 项目成员
|
||||
- `api.tasks` - 定时任务
|
||||
|
||||
## 数据模拟
|
||||
|
||||
所有数据都存储在 `src/data/` 目录下的JavaScript文件中，作为静态模拟数据。
|
||||
所有数据都存储在 `src/data/` 目录下的JavaScript文件中，作为静态模拟数据。API 服务层统一从这些文件读取数据。
|
||||
|
||||
### 数据文件说明
|
||||
- `conversations.js`：聊天场景和对话历史
|
||||
@@ -434,6 +638,12 @@ export default defineConfig({
|
||||
## 更新日志
|
||||
|
||||
### 2026-03-20
|
||||
- 代码架构重构：提取布局组件（SidebarBrand、SidebarUser、SidebarNavItem）
|
||||
- 代码架构重构：创建通用UI组件（EmptyState、StatusBadge、TagInput、SearchBar）
|
||||
- 代码架构重构：新增全局状态管理（UserContext）
|
||||
- 代码架构重构：新增自定义Hooks（usePageState、useNavigation、useLocalStorage）
|
||||
- 代码架构重构：新增统一数据访问层（src/services/api.js）
|
||||
- 代码架构重构：新增常量配置（constants/pages.js、constants/storageKeys.js）
|
||||
- 文档同步：更新开发台子页面列表，补充 NewVersionPage
|
||||
- 文档同步：补充开发台功能描述（上传新版本）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user