# Claude Project Rules - jk-rag-platform

**项目名称**: 建科小智开放平台
**版本**: v3.8
**更新日期**: 2026-04-02
**技术栈**: React 18 + TypeScript + Vite + Ant Design + SCSS + Zustand

---

## 项目概述

建科小智开放平台 - 基于 RAG 技术的知识库管理与应用开发平台

### 目录结构

```
src/
├── apis/              # API 接口配置 (api.ts, config.ts, index.ts)
├── assets/            # 静态资源
├── components/        # 公共组件
│   ├── 404/           # 404 页面
│   ├── chat/          # 聊天组件
│   ├── common/        # 通用组件
│   │   ├── FilterBar/     # 筛选栏
│   │   ├── FilterDrawer/  # 筛选抽屉
│   │   ├── AppCard/       # 应用卡片
│   │   ├── GuideTips/     # 引导提示
│   │   ├── HeroBanner/    # 横幅
│   │   ├── PageLayout/    # 页面布局
│   │   └── StatsGrid/     # 统计卡片
│   └── step/          # 步骤条
├── config/            # 配置文件
├── mock/              # Mock 数据
│   ├── index.ts           # 全局 Mock 数据
│   └── knowledgeApi.ts    # 知识库 Mock API
├── pages/             # 页面组件
│   ├── appCenter/         # 应用中心
│   ├── home/              # 首页/概览
│   ├── knowledgeLib/      # 知识库管理
│   ├── layout/            # 布局组件
│   ├── login/             # 登录
│   ├── questionAnswer/    # 问答应用
│   ├── system/            # 系统管理
│   └── universalChat/     # 智能问答
├── store/             # 状态管理 (Zustand + route.tsx)
├── styles/            # 全局样式
│   ├── variables.scss     # SCSS 变量
│   └── global.scss        # 全局样式
├── typings/           # 类型定义
├── utils/             # 工具函数
├── App.tsx
├── main.tsx
├── router.tsx         # 路由配置
└── LocalStorage.ts    # 本地存储封装
```

---

## 样式修改规范

### 1. 全局变量优先原则

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

```scss
// 文件顶部必须导入
@import '@/styles/variables.scss';

.my-component {
    // ✅ 使用变量
    color: $text-primary;
    padding: $spacing-4;
    border-radius: $radius-lg;

    // ❌ 禁止硬编码
    color: #1F2937;
    padding: 16px;
}
```

### 2. 间距控制规范

- 使用 `$spacing-*` 系列变量（4px 基准）
- 页面容器：`.page-container { padding: $spacing-4 $spacing-6 }`
- 内容区块：`.content-section { margin-bottom: $spacing-4; padding: $spacing-3 }`

间距变量定义：
- `$spacing-1`: 4px - 最小间距
- `$spacing-2`: 8px - 小间距
- `$spacing-3`: 12px - 中等间距
- `$spacing-4`: 16px - 标准间距
- `$spacing-5`: 20px - 大间距
- `$spacing-6`: 24px - 加大间距

### 3. 色彩使用规范 (v3.2 企业品牌色)

主色调：
- `$primary-color`: #005D80 - 企业主色 (WCAG AAA)
- `$primary-light`: #007A99 - 悬停/强调
- `$primary-dark`: #004060 - 点击/激活

文字色：
- `$text-primary`: #1F2937 - 主文字色
- `$text-secondary`: #6B7280 - 次要文字色

规范：
- **渐变仅用于背景** - 不得用于文字
- **文字必须使用纯色** - 确保对比度安全

### 4. 圆角系统

- `$radius-sm`: 4px
- `$radius-md`: 6px
- `$radius-lg`: 8px
- `$radius-xl`: 12px
- `$radius-2xl`: 16px
- `$radius-full`: 9999px

---

## Mock 数据规范

### 1. Mock 数据位置

- 主文件：`src/mock/index.ts`
- API 特定 Mock: `src/mock/{apiName}.ts`
- 启用/禁用：在 `src/apis/api.ts` 中修改 `const USE_MOCK = true/false`

### 2. 已完成的 Mock 配置

#### 知识库管理 API
- `POST /bigmodel/api/knowledgeList`
- `GET /bigmodel/api/detailKnowledge/:id`
- `POST /bigmodel/api/createKnowledge`
- `PUT /bigmodel/api/updateKnowledge/:id`
- `DELETE /bigmodel/api/delKnowledge/:id`
- `GET /bigmodel/api/embedding`

#### 文档管理 API
- `POST /bigmodel/api/documentList`
- `GET /bigmodel/api/documentDetail/:id`
- `PUT /bigmodel/api/updateDocument/:id`
- `DELETE /bigmodel/api/delDocument/:id`
- `POST /bigmodel/api/uploadDocument/:knowledgeId`
- `GET /bigmodel/api/documentSetting/:id`
- `PUT /bigmodel/api/updateDocumentSetting/:id`

#### 切片管理 API
- `POST /bigmodel/api/getSliceList`
- `GET /bigmodel/api/getSliceDetail/:sliceId/:knowledgeId`
- `POST /bigmodel/api/add/slice`
- `PUT /bigmodel/api/updateSliceInfo`
- `DELETE /bigmodel/api/deleteSlice/:sliceId/:knowledgeId/:documentId`

#### 修订工具 API
- `GET /deepseek/revise/pageList`
- `GET /deepseek/revise/list`
- `GET /deepseek/revise/sliceList`
- `PUT /deepseek/revise/reviseSlice`
- `GET /deepseek/revise/reviseHistoryList`

#### 字典数据 API
- `GET /deepseek/api/standard_classification`
- `GET /deepseek/api/parsing_type`
- `GET /deepseek/api/splitting_type`
- `GET /deepseek/api/revision_status`

#### 聊天记录 API
- `POST /bigmodel/api/chatHistory/list`
- `POST /bigmodel/api/dialog/export/:id`

### 3. 需要补充的 Mock 数据

#### 高优先级
- `/auth/login` (POST) - 用户登录
- `/auth/code` (GET) - 获取验证码
- `/system/user/getInfo` (GET) - 获取用户信息
- `/deepseek/overview/topData` (GET) - 首页统计数据
- `/bigmodel/api/getApplicationList` (POST) - 获取应用列表
- `/deepseek/api/app/audit/list` (POST) - 审核列表

#### 中优先级
- `/bigmodel/api/selectApplication/:id` (GET) - 应用详情
- `/deepseek/overview/onlineUserData` (GET) - 在线用户数据
- `/deepseek/overview/conversationData` (GET) - 会话数据
- `/deepseek/dataset/pageList` (GET) - 数据集列表

---

## 页面路由规范

### 1. 路由配置

**业务路由** (`src/store/route.tsx`):

- `/overview` - `home/index` - 概览/首页
- `/appCenter` - `appPlazaList/index` - 应用中心
- `/appCenter/questionAnswer` - `questionAnswer/list` - 我创建的应用
- `/appCenter/questionAnswer/create` - `questionAnswer/form/index` - 创建应用
- `/knowledge/knowledgeLib` - `knowledgeLib/list` - 知识库列表
- `/knowledge/knowledgeLib/:id/:createBy` - `knowledgeLib/detail/index` - 知识库详情
- `/knowledge/revisionTool` - `revisionTool/list` - 修订工具
- `/system/apiKey` - `apiKey/index` - API Key 管理
- `/system/audit` - `audit/index.placeholder` - 应用审核 (待实现)

**公共路由** (`src/router.tsx`):

- `/login` - 登录页
- `/universalChat` - 智能问答 (独立)
- `/mobile-test` - H5 测试
- `/404` - 404 页面

### 2. 标准列表页结构

```tsx
<div className="page-container">
    <div className="list-header">
        <div className="list-header-title">
            <h1>页面标题</h1>
            <p>页面描述</p>
        </div>
        <div className="list-header-actions">
            <Button type="primary">创建</Button>
        </div>
    </div>

    <GuideTips visible={true} title="提示" steps={[]} />
    <FilterBar tabs={[]} searchValue="" />

    <div className="content-section">
        {/* 表格/卡片内容 */}
    </div>
</div>
```

### 3. 卡片网格页结构

```text
<div className="page-container">
    <div className="list-header">...</div>
    <FilterBar tabs={[]} />
    <div className="app-card-grid">
        <AppCard ... />
    </div>
    <div className="pagination-container">
        <Pagination ... />
    </div>
</div>
```

---

## Git 操作规范

### 1. 提交前检查

- 确认所有必要的文件已存在或已删除
- 避免误删重要组件文件
- 备份关键配置文件

### 2. 分支管理

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

### 3. 当前状态

```bash
# 查看修改
git status
git diff HEAD --stat
```

### 4. 重要规则

- **每次修改功能模块之前必须先提交 git** - 确保当前修改已保存后再开始新任务
- 提交时使用清晰的 commit message
- 修改完成后自动执行 git commit

---

## TODO List

### P0 - 紧急且重要

- [ ] **补充核心 API Mock 数据**
  - [ ] 登录 API (`/auth/login`, `/auth/code`)
  - [ ] 首页统计 API (`/deepseek/overview/topData`)
  - [ ] 应用列表 API (`/bigmodel/api/getApplicationList`)
  - [ ] 审核列表 API (`/deepseek/api/app/audit/list`)

- [ ] **完成审核页面实现**
  - 当前使用 `audit/index.placeholder.tsx`
  - 需要实现完整的审核功能

### P1 - 重要不紧急

- [ ] **统一样式变量使用**
  - [ ] 检查所有 `.scss` 文件是否导入 `variables.scss`
  - [ ] 移除硬编码的颜色值和间距值
  - [ ] 确保使用 `$spacing-*` 系列变量

- [ ] **补充应用管理 API Mock**
  - [ ] 应用详情 API
  - [ ] 创建应用 API
  - [ ] 更新应用 API
  - [ ] 删除应用 API

- [ ] **完善文档**
  - [ ] 更新 README.md
  - [ ] 补充 API 接口文档

### P2 - 可选优化

- [ ] 响应式布局优化
- [ ] 主题切换功能 (dark/light)
- [ ] 性能优化 (代码分割、图片压缩)

---

## 技术栈版本

- React: 18.2.0
- TypeScript: 5.7.0
- Vite: 7.1.11
- Ant Design: 5.23.0
- Zustand: 5.0.12
- React Router: 7.1.0
- TailwindCSS: 4.1.17
- SCSS (Sass): 1.98.0

---

## 启动命令

```bash
# 开发
npm run start:demo      # Demo 模式（静态 + Mock）
npm run start           # 开发模式（带 API）

# 构建
npm run build:demo      # 构建 Demo 版
npm run build:prod      # 构建生产版
```

---

## 登录认证

### SSO 认证地址

`http://esc.sribs.com.cn:8080/esc-sso/oauth2.0/authorize?client_id=e97f94cf93761f4d69e8&response_type=code`

### Token 验证

在 `src/router.tsx` 中实现：
- Token 登录验证
- Code 换 Token 流程
- 白名单路由 (`/login`)

---

## 相关文件

- `README.md` - 项目说明
- `页面布局与间距控制规范.md` - 布局规范
- `知识库路由和 Mock 数据说明.md` - Mock 数据说明

---

**最后更新**: 2026-04-02