Files

lizhuoran 29f72eb65e docs: 添加管理后台功能增强规格文档

- requirements.md: 需求文档
- design.md: 设计文档
- tasks.md: 任务列表
- validation-rules-summary.md: 验证规则总结

阶段二（系统设置与操作日志功能）已完成 ✓

2026-03-09 10:09:28 +08:00

6.2 KiB

Raw Blame History

表单验证规则总结

任务 5.1.5 - 表单验证规则实施完成

SystemSettingResource 验证规则

基本信息字段

key (配置键)
- ✅ required - 必填
- ✅ unique - 唯一性验证（忽略当前记录）
- ✅ maxLength(255) - 最大长度255字符
- ✅ minLength(3) - 最小长度3字符
- ✅ regex('/^[a-z0-9_.]+$/') - 格式验证（只允许小写字母、数字、下划线和点）
group (配置分组)
- ✅ required - 必填
- ✅ 预定义选项：embedding, chunking, system, search
description (配置说明)
- ✅ maxLength(65535) - 最大长度
- ✅ minLength(5) - 最小长度5字符
is_public (公开配置)
- ✅ boolean - 布尔类型
- ✅ default(false) - 默认值
value (配置值)
- ✅ required - 必填
- ✅ KeyValue组件 - 键值对格式
- ✅ reorderable(false) - 禁用重排序

ManageSystemSettings 验证规则

1. 嵌入模型配置 (Embedding)

模型基础配置：

embedding.model_name (模型名称)
- ✅ required - 必填
- ✅ maxLength(255) - 最大长度
- ✅ minLength(3) - 最小长度
embedding.api_key (API密钥)
- ✅ required - 必填
- ✅ password - 密码字段（可显示）
- ✅ maxLength(255) - 最大长度
- ✅ minLength(20) - 最小长度
embedding.endpoint_url (API端点URL)
- ✅ required - 必填
- ✅ url() - URL格式验证
- ✅ maxLength(500) - 最大长度
- ✅ prefix('https://') - URL前缀提示

模型参数配置：

embedding.dimensions (向量维度)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(1) - 最小值1
- ✅ maxValue(4096) - 最大值4096
embedding.batch_size (批量处理大小)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(1) - 最小值1
- ✅ maxValue(1000) - 最大值1000

2. 分块参数配置 (Chunking)

分块基础参数：

chunking.chunk_size (分块大小)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(100) - 最小值100
- ✅ maxValue(10000) - 最大值10000
- ✅ default(1000) - 默认值1000
chunking.chunk_overlap (分块重叠大小)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(0) - 最小值0
- ✅ maxValue(1000) - 最大值1000
- ✅ default(200) - 默认值200
chunking.min_chunk_size (最小分块大小)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(10) - 最小值10
- ✅ maxValue(1000) - 最大值1000
- ✅ default(100) - 默认值100

分块高级参数：

chunking.separator (分块分隔符)
- ✅ maxLength(100) - 最大长度100

3. 系统全局配置 (System)

系统基础信息：

system.name (系统名称)
- ✅ required - 必填
- ✅ maxLength(255) - 最大长度
- ✅ default('知识库管理系统') - 默认值

系统运行参数：

system.timeout (请求超时时间)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(10) - 最小值10秒
- ✅ maxValue(300) - 最大值300秒
- ✅ default(60) - 默认值60秒
system.max_retries (最大重试次数)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(0) - 最小值0
- ✅ maxValue(10) - 最大值10
- ✅ default(3) - 默认值3次

文件上传配置：

system.max_upload_size (最大上传大小)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(1048576) - 最小值1MB
- ✅ maxValue(104857600) - 最大值100MB
- ✅ default(10485760) - 默认值10MB
system.allowed_file_types (允许的文件类型)
- ✅ required - 必填
- ✅ TagsInput - 标签输入组件
- ✅ default(['pdf', 'docx', 'txt', 'md']) - 默认值

4. 搜索配置 (Search)

搜索参数：

search.top_k (最大结果数)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(1) - 最小值1
- ✅ maxValue(100) - 最大值100
- ✅ default(10) - 默认值10
search.similarity_threshold (相似度阈值)
- ✅ required - 必填
- ✅ numeric - 数值类型
- ✅ minValue(0) - 最小值0
- ✅ maxValue(1) - 最大值1
- ✅ step(0.01) - 步进值0.01
- ✅ default(0.7) - 默认值0.7
search.enable_rerank (启用重排序)
- ✅ boolean - 布尔类型
- ✅ Toggle组件
- ✅ default(false) - 默认值

测试覆盖

已创建测试文件

tests/Feature/SystemSettingsTest.php - 系统设置基础功能测试
tests/Feature/SystemSettingValidationTest.php - 验证规则测试

测试用例

✅ 必填字段验证 ✅ 唯一性验证 ✅ 数值范围验证（嵌入维度） ✅ 数值范围验证（分块参数） ✅ URL格式验证 ✅ 超时时间范围验证 ✅ 相似度阈值范围验证 ✅ 数组类型验证 ✅ 布尔类型验证 ✅ 最大长度限制验证

测试结果

所有测试通过 ✅
总计：13个测试，113个断言
执行时间：< 1秒

验证规则实施总结

完成的工作

✅ 为 SystemSettingResource 添加了完整的表单验证规则
✅ 为 ManageSystemSettings 页面的所有字段添加了验证规则
✅ 添加了合理的默认值
✅ 添加了数值范围限制
✅ 添加了格式验证（URL、正则表达式）
✅ 添加了长度限制（最小/最大）
✅ 创建了完整的测试套件
✅ 所有测试通过

验证规则特点

必填字段：所有关键配置项都标记为 required
数值范围：所有数值字段都有 minValue/maxValue 限制
URL验证：endpoint_url 字段使用 url() 验证
唯一性：key 字段有 unique() 验证
格式验证：key 字段有正则表达式格式验证
默认值：所有字段都配置了合理的默认值
用户友好：所有字段都有清晰的 helperText 说明

符合需求文档

根据需求文档 1.3 验收标准：

✅ 配置保存和验证功能
✅ 表单验证提供清晰的错误提示
✅ 所有操作需要身份验证
✅ 关键功能需要单元测试

下一步建议

任务 5.1.5 已完成，建议继续执行：

任务 5.2：创建 SystemSettingService
任务 5.3：创建系统设置页面
任务 5.4：测试系统设置功能

6.2 KiB Raw Blame History Unescape Escape