461 lines
16 KiB
Markdown
461 lines
16 KiB
Markdown
# GrandClaw 原型项目
|
||
|
||
> 企业级AI智算平台前端原型，专注于展示页面布局和内容，使用React + Vite构建。
|
||
|
||
## 文档编写原则
|
||
|
||
本文档遵循以下编写原则，以确保内容的准确性、可维护性和可读性：
|
||
|
||
### 内容原则
|
||
- **准确性优先**：所有技术描述、代码示例、路径配置必须与实际代码保持一致
|
||
- **简洁明了**：使用清晰简洁的语言，避免冗余描述
|
||
- **实用导向**：提供开发者实际需要的配置和开发指南
|
||
|
||
### 结构原则
|
||
- **分层组织**：按功能模块和技术领域分层组织内容
|
||
- **逻辑清晰**：从项目概述 → 技术栈 → 功能 → 开发指南 → 维护的顺序组织
|
||
- **易于检索**：使用明确的标题层级和目录结构
|
||
|
||
### 代码原则
|
||
- **代码即文档**：代码示例使用实际可运行的代码
|
||
- **注释克制**：仅在必要时添加注释，代码本身应自解释
|
||
|
||
## 文档更新原则
|
||
|
||
本文档随项目迭代持续更新，遵循以下更新策略：
|
||
|
||
### 更新触发条件
|
||
- 新增或移除核心功能模块
|
||
- 更改技术栈或依赖版本
|
||
- 添加新的页面或路由
|
||
- 新增通用组件或工具
|
||
- 重大架构调整
|
||
|
||
### 更新内容
|
||
- **版本对齐**：技术栈版本号必须与 package.json 保持一致
|
||
- **路径同步**：文件路径必须与实际项目结构一致
|
||
- **功能同步**：核心功能描述必须覆盖实际实现的所有功能
|
||
- **示例验证**：代码示例必须经过验证可正常运行
|
||
|
||
### 更新记录
|
||
- 每次重要更新在更新日志中记录
|
||
- 记录内容包括：日期、更新类型、具体变更
|
||
- 保持更新日志按时间倒序排列
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
GrandClaw 是一个企业级AI智能助手平台的前端原型项目，主要用于展示平台的主要页面布局、交互流程和视觉设计。项目采用现代化的前端技术栈，实现了四大核心模块：
|
||
|
||
- **首页**：平台入口，包含登录功能
|
||
- **工作台**：用户与AI助手交互的主要界面，包含聊天、技能市场、日志查询、定时任务等功能
|
||
- **管理台**：运营管理界面，包含总览、部门管理、用户管理、项目管理
|
||
- **开发台**：技能开发界面，包含我的技能、技能编辑、开发文档等
|
||
|
||
## 技术栈
|
||
|
||
### 核心框架
|
||
- **React 19.2.4**：UI组件库
|
||
- **React Router 7.13.1**：路由管理（使用HashRouter）
|
||
- **Vite 8.0.1**：构建工具和开发服务器
|
||
|
||
### UI与样式
|
||
- **react-icons 5.5.0**：图标库（Feather + FontAwesome图标集）
|
||
- **Sass 1.98.0**：CSS预处理器
|
||
- **SCSS模块化**：变量、混入、组件、布局、页面分离
|
||
|
||
### 构建优化
|
||
- **vite-plugin-singlefile 2.3.2**：单文件打包，解决CORS问题
|
||
- **相对路径配置**：支持直接打开HTML文件运行
|
||
- **注意**：构建时会显示弃用警告 `WARN inlineDynamicImports option is deprecated, please use codeSplitting: false instead.`，这是由 `vite-plugin-singlefile` 插件内部使用弃用选项导致的，不影响功能，可以忽略。
|
||
|
||
### 包管理
|
||
- **pnpm**：高效的包管理器
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
grandclaw-archtype/
|
||
├── dist/ # 构建输出目录（单个index.html）
|
||
├── public/ # 静态资源
|
||
├── src/ # 源代码
|
||
│ ├── App.jsx # 主路由配置
|
||
│ ├── main.jsx # 应用入口
|
||
│ ├── components/ # 通用组件
|
||
│ │ ├── Layout.jsx # 通用布局组件（侧边栏+主内容）
|
||
│ │ └── ListSelector.jsx # 列表选择器组件（支持单选/多选）
|
||
│ ├── hooks/ # 自定义Hook
|
||
│ │ └── useLocalStorage.js # localStorage状态管理Hook
|
||
│ ├── data/ # 模拟数据
|
||
│ │ ├── conversations.js # 聊天场景数据
|
||
│ │ ├── developerData.js # 开发台数据
|
||
│ │ ├── logs.js # 日志数据
|
||
│ │ ├── members.js # 成员数据
|
||
│ │ ├── skills.js # 技能数据
|
||
│ │ └── tasks.js # 定时任务数据
|
||
│ ├── pages/ # 页面组件
|
||
│ │ ├── HomePage.jsx # 首页
|
||
│ │ ├── LoginPage.jsx # 登录页面
|
||
│ │ ├── ConsolePage.jsx # 工作台主页面
|
||
│ │ ├── AdminPage.jsx # 管理台主页面
|
||
│ │ ├── DeveloperPage.jsx # 开发台主页面
|
||
│ │ ├── console/ # 工作台子页面
|
||
│ │ │ ├── ChatPage.jsx # 聊天页面
|
||
│ │ │ ├── SkillsPage.jsx # 技能市场
|
||
│ │ │ ├── SkillDetailPage.jsx # 技能详情
|
||
│ │ │ ├── LogsPage.jsx # 日志查询
|
||
│ │ │ ├── TasksPage.jsx # 定时任务
|
||
│ │ │ ├── TaskDetailPage.jsx # 任务详情
|
||
│ │ │ ├── AccountPage.jsx # 账号管理
|
||
│ │ │ ├── ProjectsPage.jsx # 项目管理
|
||
│ │ │ ├── MemberConfigPage.jsx # 成员配置
|
||
│ │ │ └── AddMemberPage.jsx # 增加成员
|
||
│ │ ├── admin/ # 管理台子页面
|
||
│ │ │ ├── OverviewPage.jsx # 运营总览
|
||
│ │ │ ├── DepartmentsPage.jsx # 部门管理
|
||
│ │ │ ├── AddDepartmentPage.jsx # 新增部门
|
||
│ │ │ ├── UsersPage.jsx # 用户管理
|
||
│ │ │ ├── AddUserPage.jsx # 新增用户
|
||
│ │ │ ├── AdminProjectsPage.jsx # 项目管理
|
||
│ │ │ └── AddProjectPage.jsx # 新增项目
|
||
│ │ └── developer/ # 开发台子页面
|
||
│ │ ├── MySkillsPage.jsx
|
||
│ │ ├── UploadSkillPage.jsx
|
||
│ │ ├── DevDocsPage.jsx
|
||
│ │ ├── DevAccountPage.jsx
|
||
│ │ └── SkillEditorPage.jsx
|
||
│ └── styles/ # SCSS样式模块
|
||
│ ├── _variables.scss # 设计系统变量
|
||
│ ├── _mixins.scss # 可复用混入
|
||
│ ├── _base.scss # 基础重置和全局样式
|
||
│ ├── _components.scss # 通用组件样式
|
||
│ ├── _layout.scss # 布局相关样式
|
||
│ ├── _pages.scss # 页面特定样式
|
||
│ └── global.scss # 主样式文件，导入所有模块
|
||
├── index.html # HTML入口文件
|
||
├── package.json # 项目配置和依赖
|
||
├── vite.config.js # Vite配置
|
||
└── pnpm-lock.yaml # 依赖锁定文件
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 环境要求
|
||
- Node.js 18+
|
||
- pnpm（推荐）或 npm
|
||
|
||
### 安装依赖
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 开发模式
|
||
```bash
|
||
pnpm dev
|
||
# 访问 http://localhost:5173
|
||
```
|
||
|
||
### 构建生产版本
|
||
```bash
|
||
pnpm build
|
||
# 生成 dist/index.html（单个HTML文件）
|
||
```
|
||
|
||
### 预览生产构建
|
||
直接双击 `dist/index.html` 文件，或在浏览器中打开。
|
||
|
||
## 核心功能
|
||
|
||
### 1. 首页
|
||
- 平台品牌展示
|
||
- 导航入口（工作台、开发台、管理台）
|
||
- 登录入口
|
||
|
||
### 2. 登录页面
|
||
- 用户名/邮箱登录
|
||
- 密码输入
|
||
- 验证码（防爆破）
|
||
- 记住我功能
|
||
- 忘记密码链接
|
||
|
||
### 3. 工作台（Console）
|
||
- **聊天界面**：支持多种聊天场景（欢迎页、普通对话、技能调用、文件上传）
|
||
- **技能市场**：浏览、订阅、查看技能详情
|
||
- **日志查询**：支持按用户、类型、状态筛选
|
||
- **定时任务**：管理定时任务，支持启用/禁用，查看任务详情
|
||
- **项目管理**：成员列表，增加成员
|
||
- **账号管理**：个人信息和密码修改
|
||
|
||
### 4. 管理台（Admin）
|
||
- **运营总览**：平台运营数据概览
|
||
- **部门管理**：部门列表，支持新增、编辑、启用/禁用、删除
|
||
- **用户管理**：用户列表，支持新增、编辑、启用/禁用、删除，角色区分（管理员/开发者/成员）
|
||
- **项目管理**：项目列表，支持新增、编辑、启用/禁用、删除
|
||
|
||
### 5. 开发台（Developer）
|
||
- **我的技能**：已开发的技能列表
|
||
- **创建技能**：上传新技能
|
||
- **技能编辑**：编辑技能配置、版本管理
|
||
- **开发文档**：技能开发相关文档
|
||
- **开发者设置**：开发者账号信息
|
||
|
||
## 路由结构
|
||
|
||
项目使用 **HashRouter**，所有路由基于哈希路径，支持直接打开HTML文件运行。
|
||
|
||
### 主要路由
|
||
```
|
||
/ # 首页
|
||
/login # 登录页面
|
||
/console # 工作台
|
||
/admin # 管理台
|
||
/developer # 开发台
|
||
```
|
||
|
||
### 路由配置（App.jsx）
|
||
```jsx
|
||
import { HashRouter as Router, Routes, Route } from 'react-router-dom';
|
||
|
||
<Router>
|
||
<Routes>
|
||
<Route path="/" element={<HomePage />} />
|
||
<Route path="/login" element={<LoginPage />} />
|
||
<Route path="/console" element={<ConsolePage />} />
|
||
<Route path="/admin" element={<AdminPage />} />
|
||
<Route path="/developer" element={<DeveloperPage />} />
|
||
</Routes>
|
||
</Router>
|
||
```
|
||
|
||
## 通用组件
|
||
|
||
### ListSelector 列表选择器
|
||
通用的列表选择器组件，支持单选和多选模式。
|
||
|
||
```jsx
|
||
import ListSelector from '../components/ListSelector.jsx';
|
||
|
||
<ListSelector
|
||
data={dataList} // 数据数组
|
||
selectedIds={selectedIds} // 已选项
|
||
onChange={handleChange} // 选择变化回调
|
||
searchPlaceholder="搜索..." // 搜索框占位符
|
||
columns={columns} // 列配置 [{ key, label }]
|
||
multiSelect={false} // 是否多选
|
||
selectedLabel="已选标签" // 已选标签文字
|
||
onClearSelected={() => {}} // 清除已选回调
|
||
/>
|
||
```
|
||
|
||
## 状态管理
|
||
|
||
### 1. 路由状态
|
||
- **顶级路由**：由React Router的URL哈希管理
|
||
- **子页面状态**：使用`localStorage`持久化
|
||
|
||
### 2. 导航状态持久化策略
|
||
每个主要页面（工作台、管理台、开发台）都有独立的`localStorage`键：
|
||
|
||
```javascript
|
||
// 工作台
|
||
localStorage.setItem('console_currentPage', 'chat');
|
||
localStorage.setItem('console_currentScene', 'welcome');
|
||
|
||
// 管理台
|
||
localStorage.setItem('admin_currentPage', 'overview');
|
||
|
||
// 开发台
|
||
localStorage.setItem('developer_currentPage', 'mySkills');
|
||
localStorage.setItem('developer_currentSkillId', '1');
|
||
```
|
||
|
||
### 3. 主页跳转 vs 刷新浏览器
|
||
通过`location.state.fromHome`区分两种导航来源：
|
||
|
||
```javascript
|
||
// 从主页跳转：显示默认页面
|
||
useEffect(() => {
|
||
if (location.state?.fromHome) {
|
||
setCurrentPage('chat'); // 默认页面
|
||
navigate('.', { replace: true, state: {} }); // 清除state
|
||
}
|
||
}, [location.state]);
|
||
|
||
// 刷新浏览器：从localStorage恢复
|
||
const [currentPage, setCurrentPage] = useState(() => {
|
||
return localStorage.getItem('console_currentPage') || 'chat';
|
||
});
|
||
```
|
||
|
||
## 样式系统
|
||
|
||
### SCSS模块化结构
|
||
```
|
||
src/styles/
|
||
├── _variables.scss # 设计系统变量（颜色、间距、阴影等）
|
||
├── _mixins.scss # 可复用混入（媒体查询、弹性布局等）
|
||
├── _base.scss # 基础重置、CSS变量定义、body样式
|
||
├── _components.scss # 通用组件（按钮、卡片、表单、状态标签）
|
||
├── _layout.scss # 布局相关（侧边栏、主内容区）
|
||
├── _pages.scss # 页面特定样式（首页、管理台等）
|
||
└── global.scss # 主文件，导入所有模块
|
||
```
|
||
|
||
### 设计系统变量（_variables.scss）
|
||
```scss
|
||
// 品牌主色
|
||
$primary: #3B82F6;
|
||
$primary-light: #EFF6FF;
|
||
$primary-dark: #2563EB;
|
||
|
||
// 功能色
|
||
$success: #10B981;
|
||
$warning: #F59E0B;
|
||
$danger: #EF4444;
|
||
|
||
// 中性色
|
||
$text-1: #1E293B;
|
||
$text-2: #475569;
|
||
$text-3: #94A3B8;
|
||
|
||
// 布局尺寸
|
||
$sidebar-width: 240px;
|
||
$header-height: 60px;
|
||
$radius-md: 8px;
|
||
```
|
||
|
||
### 状态标签样式
|
||
支持多种状态标签：
|
||
- `status-running` - 成功/运行中（绿色）
|
||
- `status-stopped` - 停止/禁用（灰色）
|
||
- `status-warning` - 警告（黄色）
|
||
- `status-error` - 失败/错误（红色）
|
||
|
||
### 角色标签样式
|
||
- `role-admin` - 管理员（蓝色）
|
||
- `role-member` - 成员（灰色）
|
||
- `role-developer` - 开发者（橙色）
|
||
|
||
## 数据模拟
|
||
|
||
所有数据都存储在 `src/data/` 目录下的JavaScript文件中，作为静态模拟数据。
|
||
|
||
### 数据文件说明
|
||
- `conversations.js`：聊天场景和对话历史
|
||
- `skills.js`：技能市场数据，包含技能详情、文件列表、版本历史
|
||
- `developerData.js`：开发台数据，包含我的技能、技能分类、开发文档
|
||
- `logs.js`：操作日志数据（成功/失败/警告状态）
|
||
- `tasks.js`：定时任务数据（包含任务配置和执行日志）
|
||
- `members.js`：项目成员数据
|
||
|
||
## 构建和部署
|
||
|
||
### 构建配置（vite.config.js）
|
||
```javascript
|
||
import { defineConfig } from 'vite';
|
||
import react from '@vitejs/plugin-react';
|
||
import { viteSingleFile } from 'vite-plugin-singlefile';
|
||
|
||
export default defineConfig({
|
||
base: './', // 相对路径，支持直接打开HTML文件
|
||
plugins: [
|
||
react(),
|
||
viteSingleFile() // 单文件打包
|
||
],
|
||
});
|
||
```
|
||
|
||
### 构建产物
|
||
运行 `pnpm build` 后生成：
|
||
- `dist/index.html`：包含所有JavaScript和CSS的单个HTML文件
|
||
- 支持直接双击打开，无需服务器
|
||
- 使用HashRouter，路由正常工作
|
||
|
||
### 部署方式
|
||
1. **本地运行**：直接双击 `dist/index.html`
|
||
2. **静态服务器**：将 `dist/` 目录部署到任何静态文件服务器
|
||
3. **CDN部署**：上传单个HTML文件到CDN即可
|
||
|
||
## 已知问题和注意事项
|
||
|
||
### 1. 聊天场景渲染
|
||
- 聊天内容使用 `dangerouslySetInnerHTML` 渲染HTML字符串
|
||
- 深度思考区域支持点击展开/折叠
|
||
- 聊天输入框仅为展示，无实际功能
|
||
|
||
### 2. 浏览器兼容性
|
||
- 需要现代浏览器（Chrome、Firefox、Safari、Edge）
|
||
- 不支持IE
|
||
- file://协议下可能存在某些限制
|
||
|
||
### 3. 状态持久化
|
||
- 使用localStorage存储子页面状态
|
||
- 清除浏览器数据会丢失导航状态
|
||
- 不同浏览器标签页共享localStorage
|
||
|
||
### 4. 性能考虑
|
||
- 单个HTML文件较大，首次加载可能稍慢
|
||
- 所有图标已通过react-icons优化，按需加载
|
||
- SCSS样式已编译为CSS，无运行时开销
|
||
|
||
### 5. 构建警告
|
||
- 构建时会显示弃用警告：`WARN inlineDynamicImports option is deprecated, please use codeSplitting: false instead.`
|
||
- 这个警告来自 `vite-plugin-singlefile` 插件内部，无法通过配置消除
|
||
- 警告不影响功能，可以安全忽略
|
||
|
||
## 开发建议
|
||
|
||
### 添加新页面
|
||
1. 在 `src/pages/` 目录下创建页面组件
|
||
2. 在父页面组件（如ConsolePage、AdminPage）中添加路由逻辑
|
||
3. 如果需要持久化状态，添加localStorage逻辑
|
||
4. 在 `src/styles/global.scss` 中添加页面特定样式
|
||
|
||
### 添加新组件
|
||
1. 在 `src/components/` 目录下创建组件
|
||
2. 在 `src/styles/global.scss` 中添加组件样式
|
||
3. 使用设计系统变量保持一致性
|
||
|
||
### 修改样式
|
||
1. 优先修改 `src/styles/_variables.scss` 中的变量
|
||
2. 添加新的混入到 `src/styles/_mixins.scss`
|
||
3. 组件样式添加到 `_components.scss`
|
||
4. 页面特定样式添加到 `global.scss`
|
||
|
||
### 调试技巧
|
||
1. 使用 `pnpm dev` 启动开发服务器
|
||
2. 检查浏览器控制台的localStorage操作
|
||
3. 使用React Developer Tools检查组件状态
|
||
4. 检查网络面板确认资源加载
|
||
|
||
## 更新日志
|
||
|
||
### 2026-03-19
|
||
- 完成从静态HTML原型到React项目的重构
|
||
- 实现四大核心模块：首页、工作台、管理台、开发台
|
||
- 集成react-icons图标库
|
||
- 实现SCSS样式模块化
|
||
- 配置Vite单文件打包
|
||
- 实现导航状态持久化
|
||
- 区分主页跳转和刷新浏览器行为
|
||
|
||
### 2026-03-19（功能更新）
|
||
- 新增登录页面，支持验证码防爆破
|
||
- 工作台定时任务支持查看详情、执行日志
|
||
- 管理台新增用户/部门/项目管理支持新增表单
|
||
- 新增ListSelector通用列表选择器组件
|
||
- 日志查询支持按用户、类型、状态筛选
|
||
- 用户管理支持管理员/开发者/成员角色区分
|
||
- 优化页面布局和样式
|
||
|
||
## 联系方式
|
||
|
||
- 项目原型演示用途
|
||
- 基于GrandClaw团队设计
|
||
- 前端技术栈：React + Vite + SCSS
|
||
|
||
---
|
||
|
||
*最后更新：2026-03-19*
|