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 文件必须在第一行导入变量：

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

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

2. 全局变量优先原则

必须使用 src/styles/variables.scss 中定义的变量

禁止硬编码 颜色值、间距值、圆角值等

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

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

3. 色彩系统 (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 | 悬停背景 |

规范：

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

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

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

快捷别名：

$spacing-xs: $spacing-1;
$spacing-sm: $spacing-2;
$spacing-md: $spacing-3;
$spacing-lg: $spacing-4;
$spacing-xl: $spacing-6;
$spacing-2xl: $spacing-8;

5. 圆角系统

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

6. 布局容器规范

页面容器

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

内容区块

.content-section {
    margin-bottom: $spacing-4;  // 16px
    padding: $spacing-3;        // 12px
    background: $bg-secondary;
    border-radius: $radius-lg;
}

列表头部

.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;
    }
}

卡片网格

.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;
    }
}

7. 响应式断点

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

组件规范

1. 标准列表页结构

<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. 卡片网格页结构

<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 尺寸规范

$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

常用命令

# 查看状态
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

启动命令

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

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

.claude-rules.md 11 KB

Історія Запис

Claude Project Rules - jk-rag-platform

项目概述

目录结构

样式规范

1. SCSS 语法规范

2. 全局变量优先原则

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

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

5. 圆角系统

6. 布局容器规范

页面容器

内容区块

列表头部

卡片网格

7. 响应式断点

组件规范

1. 标准列表页结构

2. 卡片网格页结构

3. Header 尺寸规范

路由配置

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

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

Mock 数据规范

Mock 配置位置

已完成的 Mock API

知识库管理

文档管理

切片管理

修订工具

字典数据

聊天记录

审核管理

Git 操作规范

分支管理

重要规则

常用命令

技术栈版本

启动命令

相关文件

.claude-rules.md 11 KB Історія Запис

Claude Project Rules - jk-rag-platform

项目概述

目录结构

样式规范

1. SCSS 语法规范

2. 全局变量优先原则

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

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

5. 圆角系统

6. 布局容器规范

页面容器

内容区块

列表头部

卡片网格

7. 响应式断点

组件规范

1. 标准列表页结构

2. 卡片网格页结构

3. Header 尺寸规范

路由配置

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

公共路由 (src/router.tsx)

Mock 数据规范

Mock 配置位置

已完成的 Mock API

知识库管理

文档管理

切片管理

修订工具

字典数据

聊天记录

审核管理

Git 操作规范

分支管理

重要规则

常用命令

技术栈版本

启动命令

相关文件

.claude-rules.md 11 KB

Історія Запис

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

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