# Claude Project Rules - jk-rag-platform

**项目名称**: 建科小智开放平台
**版本**: v4.0
**更新日期**: 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. SCSS 语法规范

**所有 SCSS 文件必须在第一行导入变量**：

```scss
@use '@/styles/variables.scss' as *;
@use 'sass:color';  // 如需使用颜色函数
```

- `@use` 规则必须在文件最前面，不能有任何注释或代码在其之前
- 使用 `as *` 避免命名空间前缀
- 颜色函数（如 `darken`）改用 `color.adjust($var, $lightness: -10%)`

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

- **必须使用** `src/styles/variables.scss` 中定义的变量
- **禁止硬编码** 颜色值、间距值、圆角值等

```scss
// ✅ 正确
.my-component {
    color: $text-primary;
    padding: $spacing-4;
    border-radius: $radius-lg;
}

// ❌ 错误
.my-component {
    color: #1F2937;  // 硬编码
    padding: 16px;   // 硬编码
}
```

### 3. Ant Design 组件样式覆盖原则

**优先使用全局主题定制**：
- Ant Design 组件样式统一在 `src/styles/global.scss` 中定义
- 组件文件中不要重复定义 Ant Design 覆盖样式
- 能使用 Ant Design 官方 props 实现的（如 `size`, `type`, `color`），不要写自定义样式

**换色优先，少用覆盖**：
- ✅ 正确：使用全局变量换色（如 `$primary-color`, `$radius-lg`）
- ❌ 错误：大量 `!important` 覆盖 Ant Design 默认行为

**全局已定义的组件样式**：
- `.ant-btn` - 按钮（圆角、颜色、悬停效果）
- `.ant-input`, `.ant-select` - 输入框和下拉选择
- `.ant-table` - 表格（圆角、表头背景、悬停效果）
- `.ant-card` - 卡片（圆角、边框、阴影）
- `.ant-tag` - 标签（圆角、颜色）
- `.ant-modal`, `.ant-drawer` - 模态框和抽屉
- `.ant-tooltip`, `.ant-popover` - 提示框
- `.ant-picker` - 日期选择器
- `.ant-form-item` - 表单项
- `.ant-radio`, `.ant-checkbox` - 单选和复选框
- `.ant-steps` - 步骤条
- `.ant-upload` - 上传组件

### 4. 色彩系统 (v3.2 企业品牌色)

主色调（基于 favicon #005D80）：
| 变量 | 值 | 用途 |
|------|------|------|
| `$primary-color` | #005D80 | 企业主色 (WCAG AAA) |
| `$primary-light` | #007A99 | 悬停/强调 |
| `$primary-dark` | #004060 | 点击/激活 |
| `$primary-gradient-start` | #00A0CA | 渐变起点 |
| `$primary-gradient-end` | #005D80 | 渐变终点 |

功能性颜色：
| 变量 | 值 | 用途 |
|------|------|------|
| `$success-color` | #059669 | 成功 |
| `$warning-color` | #F59E0B | 警告 |
| `$error-color` | #DC2626 | 错误 |
| `$info-color` | #00A0C7 | 信息 |

文字色：
| 变量 | 值 | 用途 |
|------|------|------|
| `$text-primary` | #1F2937 | 主文字 |
| `$text-secondary` | #6B7280 | 次要文字 |
| `$text-hint` | #9CA3AF | 提示文字 |
| `$text-disabled` | #D1D5DB | 禁用文字 |

背景色：
| 变量 | 值 | 用途 |
|------|------|------|
| `$bg-primary` | #F9FAFB | 主背景 |
| `$bg-secondary` | #FFFFFF | 次背景 |
| `$bg-tertiary` | #F3F4F6 | 第三背景 |
| `$bg-hover` | #F9FAFB | 悬停背景 |

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

### 5. 间距系统 (4px 基准)

| 变量 | 值 | 用途 |
|------|------|------|
| `$spacing-1` | 4px | 最小间距 |
| `$spacing-2` | 8px | 小间距 |
| `$spacing-3` | 12px | 中等间距 |
| `$spacing-4` | 16px | 标准间距 |
| `$spacing-5` | 20px | 大间距 |
| `$spacing-6` | 24px | 加大间距 |
| `$spacing-8` | 32px | 特大间距 |


快捷别名：
```scss
$spacing-xs: $spacing-1;
$spacing-sm: $spacing-2;
$spacing-md: $spacing-3;
$spacing-lg: $spacing-4;
$spacing-xl: $spacing-6;
$spacing-2xl: $spacing-8;
```

### 6. 圆角系统

| 变量 | 值 | 用途 |
|------|------|------|
| `$radius-sm` | 4px | 标签、徽章 |
| `$radius-md` | 6px | 小按钮 |
| `$radius-lg` | 8px | 按钮、输入框 |
| `$radius-xl` | 12px | 卡片 |
| `$radius-2xl` | 16px | 模态框、大卡片 |
| `$radius-full` | 9999px | 圆形 |

### 7. 布局容器规范

#### 页面容器
```scss
.page-container {
    padding: $spacing-4 $spacing-6;  // 16px / 24px
    min-height: calc(100vh - $header-height);
    background: $bg-primary;
}
```

#### 内容区块
```scss
.content-section {
    margin-bottom: $spacing-4;  // 16px
    padding: $spacing-3;        // 12px
    background: $bg-secondary;
    border-radius: $radius-lg;
}
```

#### 列表头部
```scss
.list-header {
    display: flex;
    justify-content: space-between;
    align-items: flex-end;
    margin-bottom: $spacing-4;
    padding-bottom: $spacing-3;
    border-bottom: 1px solid $border-base;

    &.with-tips {
        margin-bottom: $spacing-3;  // 与 GuideTips 间距
    }

    &.with-back {
        align-items: center;
    }
}
```

#### 卡片网格
```scss
.app-card-grid {
    display: grid;
    grid-template-columns: repeat(4, 1fr);
    gap: $spacing-4;  // 16px

    @media (max-width: $screen-xl) {
        grid-template-columns: repeat(3, 1fr);
    }

    @media (max-width: $screen-lg) {
        grid-template-columns: repeat(2, 1fr);
    }

    @media (max-width: $screen-md) {
        grid-template-columns: 1fr;
    }
}
```

### 8. 响应式断点

| 变量 | 值 | 说明 |
|------|------|------|
| `$screen-sm` | 640px | 手机横屏 |
| `$screen-md` | 768px | 平板竖屏 |
| `$screen-lg` | 1024px | 平板横屏 |
| `$screen-xl` | 1280px | 桌面小屏 |
| `$screen-2xl` | 1536px | 桌面大屏 |

---

## 组件规范

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

```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>
```

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

```tsx
<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>
```

### 3. Header 尺寸规范

```scss
$header-height: 64px;
$sidebar-width: 240px;  // 紧凑布局
$sidebar-collapsed-width: 80px;
$logo-size: 40px;
$search-height: 40px;
```

---

## 路由配置

### 业务路由 (`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` | 应用审核 |

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

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

---

## Mock 数据规范

### Mock 配置位置

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

### 已完成的 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`

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

#### 切片管理
- `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`

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

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

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

#### 审核管理
- `POST /deepseek/api/app/audit/list`
- `POST /deepseek/api/app/audit/apply`
- `GET /deepseek/overview/topData`

---

## Git 操作规范

### 分支管理

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

### 重要规则

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

### 常用命令

```bash
# 查看状态
git status
git diff HEAD --stat

# 提交
git add -A
git commit -m "type: description"
```

---

## 技术栈版本

| 技术 | 版本 |
|------|------|
| 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      # 构建生产版
```

---

## 相关文件

- `README.md` - 项目说明
- `src/styles/variables.scss` - 全局样式变量
- `src/styles/global.scss` - 全局样式
- `docs/API.md` - API 接口文档