# Claude Project Rules - jk-rag-platform

## 项目概述
建科小智开放平台 - React + TypeScript + Vite + Ant Design

## 样式修改规范

### 1. 全局变量优先原则
- **必须使用** `src/styles/variables.less` 中定义的变量
- **禁止硬编码**颜色值、间距值、圆角值等
- 所有组件样式文件必须以 LESS 格式，导入全局变量

### 2. 间距控制规范
- 使用 `@spacing-*` 系列变量（4px 基准）
- 页面容器：`.page-container { padding: @spacing-4 @spacing-6 }`
- 内容区块：`.content-section { margin-bottom: @spacing-6; padding: @spacing-5 }`

### 3. 色彩使用规范 (v3.6)
- **主色**: `@primary-color: #005D80` (企业蓝，WCAG AAA)
- **渐变仅用于背景** - 不得用于文字
- **文字必须使用纯色** - 确保对比度安全

### 4. 组件样式结构
```less
// src/components/xxx/index.less
@import '@/styles/variables.less';

.xxx-component {
    // 使用全局变量
    padding: @spacing-4;
    background: @bg-secondary;
}
```

## Mock 数据规范

### 1. Mock 数据位置
- 主文件：`src/mock/index.ts`
- API 特定 Mock: `src/mock/{apiName}.ts`

### 2. Mock 数据类型
- 应用列表 (`mockAppList`)
- 知识库列表 (`mockKnowledgeLibList`)
- 系统管理数据
- 用户数据 (`mockCurrentUser`)

### 3. 启用/禁用 Mock
在 `src/apis/api.ts` 中修改：
```typescript
const USE_MOCK = true;  // 启用 Mock
```

## Git 操作规范

### 1. 提交前检查
- 确认所有必要的文件已存在或已删除
- 避免误删重要组件文件
- 备份关键配置文件

### 2. 分支管理
- 主分支：`master`
- 开发分支：当前分支 (如 `zy`)
- 不要直接 push 到 master

## 页面路由规范

### 1. 标准列表页结构
```tsx
<div className="page-container">
    <div className="list-header">...</div>
    <GuideTips />  {/* 可选 */}
    <FilterBar />  {/* 可选 */}
    <div className="content-section">...</div>
</div>
```

### 2. 卡片网格页结构
```tsx
<div className="page-container">
    <div className="list-header">...</div>
    <FilterBar />
    <div className="app-card-grid">...</div>
    <div className="pagination-container">...</div>
</div>
```

## 技术栈版本
- React: 18.2.0
- TypeScript: 5.7.0
- Vite: 7.1.11
- Ant Design: 5.23.0
- Zustand: 5.0.12
- Less: 4.2.0

## Mock 数据实现状态

### ✅ 已完成的 Mock 配置

#### 1. API 拦截器 - `src/apis/api.ts` (USE_MOCK = true)
Mock 处理器映射 (`mockHandlerMap`) 包含以下接口：

**知识库管理 API:**
- ✅ `POST /bigmodel/api/knowledgeList` → `mockFetchKnowledgeLibList`
- ✅ `GET /bigmodel/api/detailKnowledge/:id` → `mockFetchKnowledgeLibDetail`
- ✅ `POST /bigmodel/api/createKnowledge` → `mockCreateKnowledgeLib`
- ✅ `PUT /bigmodel/api/updateKnowledge/:id` → `mockModifyKnowledgeLib`
- ✅ `DELETE /bigmodel/api/delKnowledge/:id` → `mockDeleteKnowledgeLib`
- ✅ `GET /bigmodel/api/embedding` → `mockFetchEmbeddingList`

**文档管理 API:**
- ✅ `POST /bigmodel/api/documentList` → `mockFetchDocumentLibList`
- ✅ `GET /bigmodel/api/documentDetail/:id` → `mockFetchDocumentLibDetail`
- ✅ `PUT /bigmodel/api/updateDocument/:id` → `mockModifyDocumentLib`
- ✅ `DELETE /bigmodel/api/delDocument/:id` → `mockDeleteDocumentLib`
- ✅ `POST /bigmodel/api/uploadDocument/:knowledgeId` → `mockUploadDocument`
- ✅ `GET /bigmodel/api/documentSetting/:id` → `mockFetchDocumentSetting`
- ✅ `PUT /bigmodel/api/updateDocumentSetting/:id` → `mockModifyDocumentSetting`

**切片管理 API:**
- ✅ `POST /bigmodel/api/getSliceList` → `mockFetchSliceList`
- ✅ `GET /bigmodel/api/getSliceDetail/:sliceId/:knowledgeId` → `mockFetchSliceDetail`
- ✅ `POST /bigmodel/api/add/slice` → `mockAddSlice`
- ✅ `PUT /bigmodel/api/updateSliceInfo` → `mockModifySlice`
- ✅ `DELETE /bigmodel/api/deleteSlice/:sliceId/:knowledgeId/:documentId` → `mockDeleteSlice`

**修订工具 API:**
- ✅ `GET /deepseek/revise/pageList` → `mockFetchReviseToolList`
- ✅ `GET /deepseek/revise/list` → `mockFetchReviseToolAllList`
- ✅ `GET /deepseek/revise/sliceList` → `mockFetchReviseToolSliceList`
- ✅ `PUT /deepseek/revise/reviseSlice` → `mockSubmitReviseSlice`
- ✅ `GET /deepseek/revise/reviseHistoryList` → `mockFetchReviseHistoryList`

**字典数据 API:**
- ✅ `GET /deepseek/api/standard_classification` → `mockFetchTakaiAppTypeList`
- ✅ `GET /deepseek/api/parsing_type` → `mockFetchTakaiAppTypeList`
- ✅ `GET /deepseek/api/splitting_type` → `mockFetchTakaiAppTypeList`
- ✅ `GET /deepseek/api/revision_status` → `mockFetchTakaiAppTypeList`

**聊天记录 API:**
- ✅ `POST /bigmodel/api/chatHistory/list` → `mockFetchChatHistoryList`
- ✅ `POST /bigmodel/api/dialog/export/:id` → `mockExportChatHistory`

#### 2. Mock 数据文件 - `src/mock/knowledgeApi.ts`
包含所有知识库相关 Mock 数据和 API 实现:
- `mockKnowledgeLibList` - 知识库列表 (8 条)
- `mockDocumentList` - 文档列表 (5 条)
- `mockSliceList` - 切片列表 (5 条)
- `mockReviseToolList` - 修订工具列表 (3 条)
- `mockChatHistoryList` - 聊天记录 (2 条)

#### 3. Mock 数据文件 - `src/mock/index.ts`
全局 Mock 数据管理:
- ✅ `mockAppList` - 应用卡片数据
- ✅ `mockCurrentUser` - 当前登录用户
- ✅ `getAppsByPageType()` - 按页面类型获取应用
- ✅ `getPageConfig()` - 获取页面配置

### ⚠️ 需要补充的 Mock 数据

#### 1. 首页相关 API (未实现)
| 接口 | 方法 | 当前状态 | 优先级 |
|------|------|---------|--------|
| `/deepseek/overview/topData` | GET | ❌ 未实现 | 高 |
| `/deepseek/overview/onlineUserData` | GET | ❌ 未实现 | 中 |
| `/deepseek/overview/conversationData` | GET | ❌ 未实现 | 中 |
| `/deepseek/overview/conversationDetailData` | GET | ❌ 未实现 | 低 |
| `/deepseek/overview/overviewTokenData` | GET | ❌ 未实现 | 低 |
| `/deepseek/overview/overviewAppData` | GET | ❌ 未实现 | 中 |
| `/deepseek/overview/overviewKnowledgeData` | GET | ❌ 未实现 | 中 |

#### 2. 应用相关 API (未实现)
| 接口 | 方法 | 当前状态 | 优先级 |
|------|------|---------|--------|
| `/bigmodel/api/getApplicationList` | POST | ⚠️ 需要添加 Mock | 高 |
| `/bigmodel/api/selectApplication/:id` | GET | ❌ 未实现 | 中 |
| `/bigmodel/api/createApplication` | POST | ❌ 未实现 | 中 |
| `/bigmodel/api/updateApplication/:id` | PUT | ❌ 未实现 | 低 |
| `/bigmodel/api/delApplication/:id` | DELETE | ❌ 未实现 | 低 |

#### 3. 数据集和评测 API (未实现)
| 接口 | 方法 | 当前状态 | 优先级 |
|------|------|---------|--------|
| `/deepseek/dataset/pageList` | GET | ❌ 未实现 | 中 |
| `/deepseek/dataset/create` | POST | ❌ 未实现 | 低 |
| `/deepseek/evaluation/pageList` | GET | ❌ 未实现 | 低 |

#### 4. 审核相关 API (部分实现)
| 接口 | 方法 | 当前状态 | 优先级 |
|------|------|---------|--------|
| `/deepseek/api/app/audit/list` | POST | ⚠️ 需要添加 Mock | 高 |
| `/deepseek/api/app/auditHistory/list` | POST | ❌ 未实现 | 中 |

#### 5. 用户和系统 API (部分实现)
| 接口 | 方法 | 当前状态 | 优先级 |
|------|------|---------|--------|
| `/system/user/getInfo` | GET | ⚠️ 需要添加 Mock | 高 |
| `/auth/login` | POST | ⚠️ 已配置加密但无 Mock | 高 |
| `/auth/code` | GET | ❌ 未实现 | 中 |

### 📋 Mock 数据优先级计划

**第一阶段 - 核心页面 (必须):**
1. 登录 API (`/auth/login`, `/auth/code`)
2. 首页统计 API (`/deepseek/overview/topData`)
3. 应用列表 API (`/bigmodel/api/getApplicationList`)
4. 知识库列表 API (✅ 已完成)

**第二阶段 - 主要功能:**
5. 用户信息 API (`/system/user/getInfo`)
6. 审核列表 API (`/deepseek/api/app/audit/list`)
7. 应用详情 API (`/bigmodel/api/selectApplication/:id`)

**第三阶段 - 辅助功能:**
8. 数据集管理 API
9. 评测任务 API
10. 其他统计图表数据

## Git 操作规范

### 1. 提交前检查
- 确认所有必要的文件已存在或已删除
- 避免误删重要组件文件
- 备份关键配置文件

### 2. 分支管理
- 主分支：`master`
- 开发分支：当前分支 (如 `zy`)
- 不要直接 push 到 master

## 页面路由规范

### 1. 标准列表页结构
```tsx
<div className="page-container">
    <div className="list-header">...</div>
    <GuideTips />  {/* 可选 */}
    <FilterBar />  {/* 可选 */}
    <div className="content-section">...</div>
</div>
```

### 2. 卡片网格页结构
```tsx
<div className="page-container">
    <div className="list-header">...</div>
    <FilterBar />
    <div className="app-card-grid">...</div>
    <div className="pagination-container">...</div>
</div>
```

## 技术栈版本
- React: 18.2.0
- TypeScript: 5.7.0
- Vite: 7.1.11
- Ant Design: 5.23.0
- Zustand: 5.0.12
- Less: 4.2.0

## 启动命令
```bash
npm run start:demo      # Demo 模式（静态）
npm run start           # 开发模式（带 API）
npm run build:demo      # 构建 Demo 版本
```