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 格式，导入全局变量

// 文件顶部必须导入
@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. 标准列表页结构

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

<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. 当前状态

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

4. 重要规则

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

TODO List

P0 - 紧急且重要

[x] 补充核心 API Mock 数据
- 登录 API (/auth/login, /auth/code) - 已完成于 src/mock/authApi.ts
- 首页统计 API (/deepseek/overview/topData) - 已完成于 src/mock/overviewApi.ts
- 应用列表 API (/bigmodel/api/getApplicationList) - 已完成于 src/mock/applicationApi.ts
- 审核列表 API (/deepseek/api/app/audit/list) - 已完成于 src/mock/auditApi.ts
[x] 完成审核页面实现
- 已完成审核列表、审核操作（通过/拒绝）、详情查看、统计数据功能
- 文件：src/pages/system/audit/index.tsx, src/pages/system/audit/store.ts

P1 - 重要不紧急

[x] 统一样式变量使用
- 检查所有 .scss 文件是否导入 variables.scss
- 移除硬编码的颜色值和间距值
- 确保使用 $spacing-* 系列变量
- 已修复文件：layout/style.scss, layout/components/sidebar.scss, system/audit/style.scss, styles/global.scss
[x] 补充应用管理 API Mock
- 应用列表 API
- 应用详情 API
- 创建应用 API
- 更新应用 API
- 删除应用 API
[x] 完善文档
- 更新 README.md
- 补充 API 接口文档 (docs/API.md)
- API 文档已参考 Dify 风格，保留：应用调用接口、知识库检索接口

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

启动命令

# 开发
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)

.claude-rules.md 10 KB

Historik Rå

Claude Project Rules - jk-rag-platform

项目概述

目录结构

样式修改规范

1. 全局变量优先原则

2. 间距控制规范

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

4. 圆角系统

Mock 数据规范

1. Mock 数据位置

2. 已完成的 Mock 配置

知识库管理 API

文档管理 API

切片管理 API

修订工具 API

字典数据 API

聊天记录 API

3. 需要补充的 Mock 数据

高优先级

中优先级

页面路由规范

1. 路由配置

2. 标准列表页结构

3. 卡片网格页结构

Git 操作规范

1. 提交前检查

2. 分支管理

3. 当前状态

4. 重要规则

TODO List

P0 - 紧急且重要

P1 - 重要不紧急

P2 - 可选优化 (待执行)

技术栈版本

启动命令

登录认证

SSO 认证地址

Token 验证

相关文件

.claude-rules.md 10 KB Historik Rå

Claude Project Rules - jk-rag-platform

项目概述

目录结构

样式修改规范

1. 全局变量优先原则

2. 间距控制规范

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

4. 圆角系统

Mock 数据规范

1. Mock 数据位置

2. 已完成的 Mock 配置

知识库管理 API

文档管理 API

切片管理 API

修订工具 API

字典数据 API

聊天记录 API

3. 需要补充的 Mock 数据

高优先级

中优先级

页面路由规范

1. 路由配置

2. 标准列表页结构

3. 卡片网格页结构

Git 操作规范

1. 提交前检查

2. 分支管理

3. 当前状态

4. 重要规则

TODO List

P0 - 紧急且重要

P1 - 重要不紧急

P2 - 可选优化 (待执行)

技术栈版本

启动命令

登录认证

SSO 认证地址

Token 验证

相关文件

.claude-rules.md 10 KB

Historik Rå