xiaozhi/jk-rag-platform/.claude-rules.md

Claude Project Rules - jk-rag-platform

项目概述

建科小智开放平台 - React + TypeScript + Vite + Ant Design

样式修改规范

1. 全局变量优先原则

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

2. 间距控制规范

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

3. 色彩使用规范 (v3.6)

• 主色: @primary-color: #005D80 (企业蓝，WCAG AAA)
• 渐变仅用于背景 - 不得用于文字
• 文字必须使用纯色 - 确保对比度安全

4. 组件样式结构

// src/components/xxx/index.less
@import '@/styles/variables.less';

.xxx-component {
    // 使用全局变量
    padding: @spacing-4;
    background: @bg-secondary;
}

Mock 数据规范

1. Mock 数据位置

• 主文件：src/mock/index.ts
• API 特定 Mock: src/mock/{apiName}.ts

2. Mock 数据类型

• 应用列表 (mockAppList)
• 知识库列表 (mockKnowledgeLibList)
• 系统管理数据
• 用户数据 (mockCurrentUser)

3. 启用/禁用 Mock

在 src/apis/api.ts 中修改：

const USE_MOCK = true;  // 启用 Mock

Git 操作规范

1. 提交前检查

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

2. 分支管理

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

页面路由规范

1. 标准列表页结构

<div className="page-container">
    <div className="list-header">...</div>
    <GuideTips />  {/* 可选 */}
    <FilterBar />  {/* 可选 */}
    <div className="content-section">...</div>
</div>

2. 卡片网格页结构

<div className="page-container">
    <div className="list-header">...</div>
    <FilterBar />
    <div className="app-card-grid">...</div>
    <div className="pagination-container">...</div>
</div>

技术栈版本

• React: 18.2.0
• TypeScript: 5.7.0
• Vite: 7.1.11
• Ant Design: 5.23.0
• Zustand: 5.0.12
• Less: 4.2.0

Mock 数据实现状态

✅ 已完成的 Mock 配置

1. API 拦截器 - src/apis/api.ts (USE_MOCK = true)

Mock 处理器映射 (mockHandlerMap) 包含以下接口：

知识库管理 API:

• ✅ POST /bigmodel/api/knowledgeList → mockFetchKnowledgeLibList
• ✅ GET /bigmodel/api/detailKnowledge/:id → mockFetchKnowledgeLibDetail
• ✅ POST /bigmodel/api/createKnowledge → mockCreateKnowledgeLib
• ✅ PUT /bigmodel/api/updateKnowledge/:id → mockModifyKnowledgeLib
• ✅ DELETE /bigmodel/api/delKnowledge/:id → mockDeleteKnowledgeLib
• ✅ GET /bigmodel/api/embedding → mockFetchEmbeddingList

文档管理 API:

• ✅ POST /bigmodel/api/documentList → mockFetchDocumentLibList
• ✅ GET /bigmodel/api/documentDetail/:id → mockFetchDocumentLibDetail
• ✅ PUT /bigmodel/api/updateDocument/:id → mockModifyDocumentLib
• ✅ DELETE /bigmodel/api/delDocument/:id → mockDeleteDocumentLib
• ✅ POST /bigmodel/api/uploadDocument/:knowledgeId → mockUploadDocument
• ✅ GET /bigmodel/api/documentSetting/:id → mockFetchDocumentSetting
• ✅ PUT /bigmodel/api/updateDocumentSetting/:id → mockModifyDocumentSetting

切片管理 API:

• ✅ POST /bigmodel/api/getSliceList → mockFetchSliceList
• ✅ GET /bigmodel/api/getSliceDetail/:sliceId/:knowledgeId → mockFetchSliceDetail
• ✅ POST /bigmodel/api/add/slice → mockAddSlice
• ✅ PUT /bigmodel/api/updateSliceInfo → mockModifySlice
• ✅ DELETE /bigmodel/api/deleteSlice/:sliceId/:knowledgeId/:documentId → mockDeleteSlice

修订工具 API:

• ✅ GET /deepseek/revise/pageList → mockFetchReviseToolList
• ✅ GET /deepseek/revise/list → mockFetchReviseToolAllList
• ✅ GET /deepseek/revise/sliceList → mockFetchReviseToolSliceList
• ✅ PUT /deepseek/revise/reviseSlice → mockSubmitReviseSlice
• ✅ GET /deepseek/revise/reviseHistoryList → mockFetchReviseHistoryList

字典数据 API:

• ✅ GET /deepseek/api/standard_classification → mockFetchTakaiAppTypeList
• ✅ GET /deepseek/api/parsing_type → mockFetchTakaiAppTypeList
• ✅ GET /deepseek/api/splitting_type → mockFetchTakaiAppTypeList
• ✅ GET /deepseek/api/revision_status → mockFetchTakaiAppTypeList

聊天记录 API:

• ✅ POST /bigmodel/api/chatHistory/list → mockFetchChatHistoryList
• ✅ POST /bigmodel/api/dialog/export/:id → mockExportChatHistory

2. Mock 数据文件 - src/mock/knowledgeApi.ts

包含所有知识库相关 Mock 数据和 API 实现:

• mockKnowledgeLibList - 知识库列表 (8 条)
• mockDocumentList - 文档列表 (5 条)
• mockSliceList - 切片列表 (5 条)
• mockReviseToolList - 修订工具列表 (3 条)
• mockChatHistoryList - 聊天记录 (2 条)

3. Mock 数据文件 - src/mock/index.ts

全局 Mock 数据管理:

• ✅ mockAppList - 应用卡片数据
• ✅ mockCurrentUser - 当前登录用户
• ✅ getAppsByPageType() - 按页面类型获取应用
• ✅ getPageConfig() - 获取页面配置

⚠️ 需要补充的 Mock 数据

1. 首页相关 API (未实现)

接口	方法	当前状态	优先级
/deepseek/overview/topData	GET	❌ 未实现	高
/deepseek/overview/onlineUserData	GET	❌ 未实现	中
/deepseek/overview/conversationData	GET	❌ 未实现	中
/deepseek/overview/conversationDetailData	GET	❌ 未实现	低
/deepseek/overview/overviewTokenData	GET	❌ 未实现	低
/deepseek/overview/overviewAppData	GET	❌ 未实现	中
/deepseek/overview/overviewKnowledgeData	GET	❌ 未实现	中

2. 应用相关 API (未实现)

接口	方法	当前状态	优先级
/bigmodel/api/getApplicationList	POST	⚠️ 需要添加 Mock	高
/bigmodel/api/selectApplication/:id	GET	❌ 未实现	中
/bigmodel/api/createApplication	POST	❌ 未实现	中
/bigmodel/api/updateApplication/:id	PUT	❌ 未实现	低
/bigmodel/api/delApplication/:id	DELETE	❌ 未实现	低

3. 数据集和评测 API (未实现)

接口	方法	当前状态	优先级
/deepseek/dataset/pageList	GET	❌ 未实现	中
/deepseek/dataset/create	POST	❌ 未实现	低
/deepseek/evaluation/pageList	GET	❌ 未实现	低

4. 审核相关 API (部分实现)

接口	方法	当前状态	优先级
/deepseek/api/app/audit/list	POST	⚠️ 需要添加 Mock	高
/deepseek/api/app/auditHistory/list	POST	❌ 未实现	中

5. 用户和系统 API (部分实现)

接口	方法	当前状态	优先级
/system/user/getInfo	GET	⚠️ 需要添加 Mock	高
/auth/login	POST	⚠️ 已配置加密但无 Mock	高
/auth/code	GET	❌ 未实现	中

📋 Mock 数据优先级计划

第一阶段 - 核心页面 (必须):

1. 登录 API (/auth/login, /auth/code)
2. 首页统计 API (/deepseek/overview/topData)
3. 应用列表 API (/bigmodel/api/getApplicationList)
4. 知识库列表 API (✅ 已完成)

第二阶段 - 主要功能:

1. 用户信息 API (/system/user/getInfo)
2. 审核列表 API (/deepseek/api/app/audit/list)
3. 应用详情 API (/bigmodel/api/selectApplication/:id)

第三阶段 - 辅助功能:

1. 数据集管理 API
2. 评测任务 API
3. 其他统计图表数据

Git 操作规范

1. 提交前检查

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

2. 分支管理

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

页面路由规范

1. 标准列表页结构

<div className="page-container">
    <div className="list-header">...</div>
    <GuideTips />  {/* 可选 */}
    <FilterBar />  {/* 可选 */}
    <div className="content-section">...</div>
</div>

2. 卡片网格页结构

<div className="page-container">
    <div className="list-header">...</div>
    <FilterBar />
    <div className="app-card-grid">...</div>
    <div className="pagination-container">...</div>
</div>

技术栈版本

• React: 18.2.0
• TypeScript: 5.7.0
• Vite: 7.1.11
• Ant Design: 5.23.0
• Zustand: 5.0.12
• Less: 4.2.0

启动命令

npm run start:demo      # Demo 模式（静态）
npm run start           # 开发模式（带 API）
npm run build:demo      # 构建 Demo 版本