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. 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	特大间距

快捷别名：

$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. 布局容器规范

页面容器

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

8. 响应式断点

变量	值	说明
`$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 12 KB История Исходник