265 lines
7.9 KiB
Markdown
265 lines
7.9 KiB
Markdown
|
# 参考Setting项目架构分析
|
||
|
|
|
||
|
|
## 项目概述
|
||
|
|
|
||
|
|
参考项目位于 `rag_web_core/src/pages/dataset/setting`，采用了基于 `react-hook-form` 和 `zod` 的现代表单管理架构，实现了高度模块化和可扩展的配置页面。
|
||
|
|
|
||
|
|
## 文件结构
|
||
|
|
|
||
|
|
```
|
||
|
|
setting/
|
||
|
|
├── index.tsx # 主页面入口
|
||
|
|
├── form-schema.ts # 表单数据结构定义
|
||
|
|
├── general-form.tsx # 通用表单组件
|
||
|
|
├── chunk-method-form.tsx # 动态解析方法表单
|
||
|
|
├── configuration-form-container.tsx # 表单容器组件
|
||
|
|
├── hooks.ts # 数据获取和状态管理
|
||
|
|
├── saving-button.tsx # 保存按钮组件
|
||
|
|
├── permission-form-field.tsx # 权限表单字段
|
||
|
|
├── tag-item.tsx # 标签项组件
|
||
|
|
├── configuration/ # 配置组件目录
|
||
|
|
│ ├── common-item.tsx # 通用配置项
|
||
|
|
│ ├── naive.tsx # 通用解析配置
|
||
|
|
│ ├── qa.tsx # Q&A解析配置
|
||
|
|
│ ├── paper.tsx # 论文解析配置
|
||
|
|
│ ├── book.tsx # 书籍解析配置
|
||
|
|
│ ├── table.tsx # 表格解析配置
|
||
|
|
│ ├── audio.tsx # 音频解析配置
|
||
|
|
│ ├── email.tsx # 邮件解析配置
|
||
|
|
│ ├── laws.tsx # 法律解析配置
|
||
|
|
│ ├── manual.tsx # 手册解析配置
|
||
|
|
│ ├── one.tsx # One解析配置
|
||
|
|
│ ├── picture.tsx # 图片解析配置
|
||
|
|
│ ├── presentation.tsx # 演示文稿解析配置
|
||
|
|
│ ├── resume.tsx # 简历解析配置
|
||
|
|
│ ├── knowledge-graph.tsx # 知识图谱配置
|
||
|
|
│ └── tag.tsx # 标签配置
|
||
|
|
└── tag-table/ # 标签表格相关组件
|
||
|
|
└── ...
|
||
|
|
```
|
||
|
|
|
||
|
|
## 核心架构模式
|
||
|
|
|
||
|
|
### 1. 主从架构模式 (Master-Slave)
|
||
|
|
- **主控制器**: `index.tsx` 作为主页面，管理整体状态和表单实例
|
||
|
|
- **从组件**: `general-form.tsx` 和 `chunk-method-form.tsx` 作为子表单组件
|
||
|
|
|
||
|
|
### 2. 策略模式 (Strategy Pattern)
|
||
|
|
- **配置映射**: `ConfigurationComponentMap` 根据 `parser_id` 动态选择配置组件
|
||
|
|
- **组件策略**: 每个解析类型对应一个独立的配置组件
|
||
|
|
|
||
|
|
### 3. 模块化设计
|
||
|
|
- **功能分离**: 通用配置与特定解析配置分离
|
||
|
|
- **组件复用**: 通过 `configuration-form-container.tsx` 提供统一的布局容器
|
||
|
|
|
||
|
|
## 关键技术实现
|
||
|
|
|
||
|
|
### 1. 表单管理系统
|
||
|
|
|
||
|
|
#### 数据结构 (form-schema.ts)
|
||
|
|
```typescript
|
||
|
|
export const formSchema = z.object({
|
||
|
|
name: z.string().min(1),
|
||
|
|
description: z.string().min(2),
|
||
|
|
avatar: z.any().nullish(),
|
||
|
|
permission: z.string().optional(),
|
||
|
|
parser_id: z.string(),
|
||
|
|
embd_id: z.string(),
|
||
|
|
parser_config: z.object({
|
||
|
|
layout_recognize: z.string(),
|
||
|
|
chunk_token_num: z.number(),
|
||
|
|
delimiter: z.string(),
|
||
|
|
auto_keywords: z.number().optional(),
|
||
|
|
auto_questions: z.number().optional(),
|
||
|
|
html4excel: z.boolean(),
|
||
|
|
raptor: z.object({...}),
|
||
|
|
graphrag: z.object({...}),
|
||
|
|
}).optional(),
|
||
|
|
pagerank: z.number(),
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 表单初始化
|
||
|
|
```typescript
|
||
|
|
const form = useForm<z.infer<typeof formSchema>>({
|
||
|
|
resolver: zodResolver(formSchema),
|
||
|
|
defaultValues: {
|
||
|
|
name: '',
|
||
|
|
parser_id: DocumentParserType.Naive,
|
||
|
|
permission: PermissionRole.Me,
|
||
|
|
parser_config: {
|
||
|
|
layout_recognize: DocumentType.DeepDOC,
|
||
|
|
chunk_token_num: 512,
|
||
|
|
delimiter: `\n`,
|
||
|
|
// ... 其他默认值
|
||
|
|
},
|
||
|
|
},
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. 动态表单系统
|
||
|
|
|
||
|
|
#### 配置组件映射
|
||
|
|
```typescript
|
||
|
|
const ConfigurationComponentMap = {
|
||
|
|
[DocumentParserType.Naive]: NaiveConfiguration,
|
||
|
|
[DocumentParserType.Qa]: QAConfiguration,
|
||
|
|
[DocumentParserType.Resume]: ResumeConfiguration,
|
||
|
|
// ... 其他映射
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 动态组件渲染
|
||
|
|
```typescript
|
||
|
|
const ConfigurationComponent = useMemo(() => {
|
||
|
|
return finalParserId
|
||
|
|
? ConfigurationComponentMap[finalParserId]
|
||
|
|
: EmptyComponent;
|
||
|
|
}, [finalParserId]);
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. 状态管理
|
||
|
|
|
||
|
|
#### 表单上下文共享
|
||
|
|
- 使用 `useFormContext()` 在子组件中访问表单实例
|
||
|
|
- 通过 `useWatch()` 监听特定字段变化
|
||
|
|
|
||
|
|
#### 数据获取钩子
|
||
|
|
```typescript
|
||
|
|
// hooks.ts
|
||
|
|
export function useFetchKnowledgeConfigurationOnMount(form) {
|
||
|
|
// 获取知识库配置并初始化表单
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 4. 页面布局结构
|
||
|
|
|
||
|
|
#### 主页面布局 (index.tsx)
|
||
|
|
```typescript
|
||
|
|
<section className="p-5 h-full flex flex-col">
|
||
|
|
<TopTitle />
|
||
|
|
<div className="flex gap-14 flex-1 min-h-0">
|
||
|
|
<Form {...form}>
|
||
|
|
<form className="space-y-6 flex-1">
|
||
|
|
<Tabs>
|
||
|
|
<TabsList>
|
||
|
|
<TabsTrigger value="generalForm">通用</TabsTrigger>
|
||
|
|
<TabsTrigger value="chunkMethodForm">解析方法</TabsTrigger>
|
||
|
|
</TabsList>
|
||
|
|
<TabsContent value="generalForm">
|
||
|
|
<GeneralForm />
|
||
|
|
</TabsContent>
|
||
|
|
<TabsContent value="chunkMethodForm">
|
||
|
|
<ChunkMethodForm />
|
||
|
|
</TabsContent>
|
||
|
|
</Tabs>
|
||
|
|
</form>
|
||
|
|
</Form>
|
||
|
|
<ChunkMethodLearnMore />
|
||
|
|
</div>
|
||
|
|
</section>
|
||
|
|
```
|
||
|
|
|
||
|
|
#### 表单容器组件
|
||
|
|
```typescript
|
||
|
|
// configuration-form-container.tsx
|
||
|
|
export function ConfigurationFormContainer({ children, className }) {
|
||
|
|
return (
|
||
|
|
<FormContainer className={cn('p-10', className)}>
|
||
|
|
{children}
|
||
|
|
</FormContainer>
|
||
|
|
);
|
||
|
|
}
|
||
|
|
|
||
|
|
export function MainContainer({ children }) {
|
||
|
|
return <section className="space-y-5">{children}</section>;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## 组件设计模式
|
||
|
|
|
||
|
|
### 1. 通用表单组件 (general-form.tsx)
|
||
|
|
- 使用 `FormField` 组件统一表单字段样式
|
||
|
|
- 采用 1/4 和 3/4 的标签与输入框布局比例
|
||
|
|
- 集成头像上传、权限选择等通用功能
|
||
|
|
|
||
|
|
### 2. 配置组件模式
|
||
|
|
每个配置组件遵循统一的结构：
|
||
|
|
```typescript
|
||
|
|
export function NaiveConfiguration() {
|
||
|
|
return (
|
||
|
|
<ConfigurationFormContainer>
|
||
|
|
<MainContainer>
|
||
|
|
<LayoutRecognizeFormField />
|
||
|
|
<MaxTokenNumberFormField />
|
||
|
|
<DelimiterFormField />
|
||
|
|
<AutoKeywordsFormField />
|
||
|
|
<AutoQuestionsFormField />
|
||
|
|
<TagItems />
|
||
|
|
</MainContainer>
|
||
|
|
</ConfigurationFormContainer>
|
||
|
|
);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. 表单字段组件
|
||
|
|
- 统一的 `FormField` 包装器
|
||
|
|
- 一致的错误处理和验证显示
|
||
|
|
- 响应式布局设计
|
||
|
|
|
||
|
|
## 技术特色
|
||
|
|
|
||
|
|
### 1. 类型安全
|
||
|
|
- 使用 TypeScript 和 Zod 确保类型安全
|
||
|
|
- 表单数据结构与后端API对齐
|
||
|
|
|
||
|
|
### 2. 性能优化
|
||
|
|
- 使用 `useMemo` 优化动态组件渲染
|
||
|
|
- `useWatch` 精确监听字段变化，避免不必要的重渲染
|
||
|
|
|
||
|
|
### 3. 可扩展性
|
||
|
|
- 新增解析类型只需添加配置组件和映射关系
|
||
|
|
- 模块化设计便于功能扩展
|
||
|
|
|
||
|
|
### 4. 用户体验
|
||
|
|
- Tab切换提供清晰的功能分区
|
||
|
|
- 右侧学习面板提供上下文帮助
|
||
|
|
- 统一的保存和重置操作
|
||
|
|
|
||
|
|
## 与用户项目的对比
|
||
|
|
|
||
|
|
### 用户当前架构
|
||
|
|
- 使用 Material-UI 组件库
|
||
|
|
- 基于 `react-hook-form` 但结构相对简单
|
||
|
|
- 单一的 Accordion 布局
|
||
|
|
- 配置逻辑集中在一个组件中
|
||
|
|
|
||
|
|
### 参考项目优势
|
||
|
|
- 更清晰的模块化分离
|
||
|
|
- 动态配置组件系统
|
||
|
|
- 更好的代码组织和可维护性
|
||
|
|
- 统一的设计语言和布局模式
|
||
|
|
|
||
|
|
## 适配建议
|
||
|
|
|
||
|
|
### 1. 保持现有样式
|
||
|
|
- 继续使用 Material-UI 组件
|
||
|
|
- 保持 Accordion 布局风格
|
||
|
|
- 适配现有的主题和设计规范
|
||
|
|
|
||
|
|
### 2. 采用核心架构
|
||
|
|
- 引入动态配置组件映射机制
|
||
|
|
- 分离通用配置和特定解析配置
|
||
|
|
- 使用 `useFormContext` 实现组件间状态共享
|
||
|
|
|
||
|
|
### 3. 数据结构对齐
|
||
|
|
- 参考 `form-schema.ts` 调整数据结构
|
||
|
|
- 使用 Zod 进行数据验证
|
||
|
|
- 统一默认值设置
|
||
|
|
|
||
|
|
### 4. 状态管理优化
|
||
|
|
- 使用 `useWatch` 监听字段变化
|
||
|
|
- 实现数据获取钩子
|
||
|
|
- 优化表单重置和提交逻辑
|
||
|
|
|
||
|
|
这种架构设计为大型表单应用提供了良好的可维护性和扩展性基础，值得在用户项目中借鉴和应用。
|