Hooke / data-table

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
22aa2f5c 1 parent 0325483b

docs: 为LangChain Agent添加完整的表单配置文档集 

添加详细的文档集，为LangChain Agent生成表单配置提供完整的参考指南。包括：
- 数据结构总览：核心FormField、ComponentProps、Option等结构定义
- 组件类型参考：30+种表单组件的详细说明和配置要点
- 配置规范：component_props的完整属性规范和数据提交格式
- LangChain Agent使用指南：自然语言到组件的映射、必填识别、选项提取规则
- 示例数据：20+个真实配置示例和完整表单模板
- 规则控制系统：字段显示/隐藏规则的详细实现机制
- API接口文档：表单管理和数据操作的所有接口说明
- 页面数据提取指南：从实际运行表单中提取配置的方法
Expand all
Inline Side-by-side
Showing 10 changed files with 1384 additions and 0 deletions
# 变更日志
记录项目开发过程中的重要变更和完成任务。
## 2026-03-16
### 16:54:40 - 完成任务
**影响文件**:
- `CLAUDE.md`
**变更摘要**:
- 无详细描述
# 数据结构总览
## 核心数据结构
### 1. 表单字段结构 (FormField)
每个表单字段都是一个对象，包含以下核心属性：
```typescript
interface FormField {
// 字段标识
key: string // 字段唯一标识，如 "field_1"
name: string // 表单验证用的名称，通常等于 key
// 字段值
value: any // 字段当前值
default?: any // 默认值
// 组件相关
component: Component // Vue 组件引用
component_props: ComponentProps // 组件属性配置
// 验证相关
required?: boolean // 是否必填
rules?: ValidationRule[] // 验证规则
type?: string // 表单输入类型（text/textarea等）
// 其他
index?: number // 字段排序索引
}
```
### 2. 组件属性结构 (ComponentProps)
```typescript
interface ComponentProps {
// 基础属性
tag: string // 组件类型标识（如 "input", "radio"）
name: string // 组件名称
label: string // 字段标签（显示名称）
placeholder?: string // 占位符文本
default?: any // 默认值
// 显示控制
disabled?: boolean // 是否隐藏
disabled_show?: boolean // 隐藏时是否显示图标
readonly?: boolean // 是否只读
required?: boolean // 是否必填
// 选项类组件
options?: Option[] // 选项列表（radio/checkbox/select）
// 样式相关
align?: string // 文本对齐方式（left/center/right）
direction?: string // 排列方向（vertical/horizontal）
background_color?: string // 背景色
// 高级功能
note?: string // 提示文本（支持HTML）
is_camera_scan?: boolean // 是否启用微信扫一扫
camera_scan_type?: string // 扫码类型（ALL_CODE/QR_CODE/BAR_CODE）
// 图片上传
max_count?: number // 最大上传数量
max_size?: number // 最大文件大小（MB）
// 评分
x_score?: number // 分数值
// 分组相关
is_field_group?: boolean // 是否是集合组
group_field_name?: string // 所属组字段名
}
```
### 3. 选项结构 (Option)
用于 Radio、Checkbox、Picker 等组件：
```typescript
interface Option {
// 基础
title: string // 选项显示文本
value: any // 选项值
checked?: boolean // 是否默认选中
// 样式
color?: string // 选项颜色
background_color?: string // 背景色
// 状态
disabled?: boolean // 是否禁用
// 描述信息
desc_text?: string // 描述文本
desc_type?: string // 描述类型（text/url）
desc_url?: string // 描述链接URL
desc_btn_name?: string // 描述按钮名称
// 补充信息
is_input?: boolean // 是否需要输入补充信息
input_required?: boolean // 补充信息是否必填
input_placeholder?: string // 补充信息占位符
affix?: string // 补充信息值
}
```
### 4. API 响应结构
```typescript
interface APIResponse<T = any> {
code: number // 状态码：1=成功，其他=失败
msg: string // 响应消息
data: T // 响应数据
show?: boolean // 是否显示错误提示
}
```
## 数据流转
### 1. 表单渲染流程
```
后端API → 表单配置数据 → createComponentType() → 动态组件渲染
```
### 2. 表单提交流程
```
用户输入 → 组件v-model → item.value → addFormDataAPI() → 后端保存
```
## 关键概念
### 1. 动态组件系统
项目使用 `component_props.tag` 属性决定渲染哪种组件：
- 系统通过 `src/hooks/useComponentType.js` 中的 `createComponentType()` 函数
- 根据 `tag` 值动态分配对应的 Vue 组件
- 支持 30+ 种组件类型
### 2. 验证系统
- 基于 Vant Form 的验证系统
- 通过 `rules` 数组配置验证规则
- 必填项自动添加 `{ required: true, message: 'xxx' }`
### 3. 规则系统
- 字段可以通过规则控制其他字段的显示/隐藏
- 通过 `emit("active")` 触发规则检查
- 规则组件：`RuleField`、`MultiRuleField`
### 4. Cookie 保存
- 未完成表单自动保存到 Cookie
- 格式：`{ form_code: { field_key: value } }`
- 过期时间：1 天
### 5. 周期选择
- 某些表单支持周期选择
- 通过 API `/srv/?a=cycle_list` 获取可用周期
- 周期选择后 URL 会携带 `x_cycle` 参数
# 表单字段组件类型
## 支持的组件类型列表
项目支持 **30+ 种** 动态表单字段组件，通过 `component_props.tag` 属性指定。
## 文本输入类
### 1. input - 单行文本输入
- **组件**: `TextField`
- **用途**: 短文本输入，如姓名、标题等
- **特殊功能**: 微信扫一扫（`is_camera_scan`）
### 2. textarea - 多行文本输入
- **组件**: `TextareaField`
- **用途**: 长文本输入，如备注、描述等
- **特性**: 自动高度（`autosize`）
### 3. number - 数字输入
- **组件**: `NumberField`
- **用途**: 数字类型输入，如年龄、数量等
## 选择类
### 4. radio - 单项选择
- **组件**: `RadioField`
- **用途**: 单选选项，如性别、是否等
- **数据结构**: `options` 数组
- **特殊功能**:
- 选项颜色（`color`, `background_color`）
- 补充信息输入（`is_input`）
- 描述信息（`desc_text`, `desc_url`）
### 5. checkbox - 多项选择
- **组件**: `CheckboxField`
- **用途**: 多选选项，如爱好、标签等
- **数据结构**: `options` 数组
- **排列方向**: `direction` (vertical/horizontal)
### 6. select - 单列选择器
- **组件**: `PickerField`
- **用途**: 下拉单选
- **数据结构**: `options` 数组
- **返回值**: 选中的 `value`
## 日期时间类
### 7. date - 日期选择器
- **组件**: `DatePickerField`
- **用途**: 选择日期
### 8. time - 时间选择器
- **组件**: `TimePickerField`
- **用途**: 选择时间
### 9. datetime - 日期时间选择器
- **组件**: `DateTimePickerField`
- **用途**: 选择日期和时间
### 10. calendar - 日历选择器
- **组件**: `CalendarField`
- **用途**: 日历形式选择日期
## 上传类
### 11. image_uploader - 图片上传
- **组件**: `ImageUploaderField`
- **用途**: 上传图片到七牛云
- **配置**:
- `max_count`: 最大数量
- `max_size`: 最大文件大小（MB）
- **返回值**: `[{ url, name }]`
### 12. file_uploader - 文件上传
- **组件**: `FileUploaderField`
- **用途**: 上传普通文件
## 特殊输入类
### 13. phone - 手机号输入
- **组件**: `PhoneField`
- **用途**: 手机号码输入和验证
- **验证**: 11位手机号格式
### 14. email - 邮箱输入
- **组件**: `EmailField`
- **用途**: 邮箱地址输入和验证
### 15. id_card - 身份证输入
- **组件**: `IdentityField`
- **用途**: 身份证号码输入和验证
### 16. name - 姓名输入
- **组件**: `NameField`
- **用途**: 中文姓名输入
### 17. gender - 性别选择
- **组件**: `GenderField`
- **用途**: 性别选择（男/女）
## 位置类
### 18. address - 地址选择器
- **组件**: `AreaPickerField`
- **用途**: 省/市/区三级联动选择
- **数据**: 使用 `@vant/area-data`
## 展示类
### 19. desc - 文字描述
- **组件**: `DesField`
- **用途**: 纯文字展示，不支持输入
### 20. divider - 分割线
- **组件**: `DividerField`
- **用途**: 视觉分割线
### 21. note - 富文本控件
- **组件**: `NoteField`
- **用途**: 富文本内容展示
### 22. marquee - 跑马灯
- **组件**: `MarqueeField`
- **用途**: 滚动公告文字
## 特殊功能类
### 23. sign - 电子签名
- **组件**: `SignField`
- **用途**: 手写签名板
- **依赖**: `vue-esign`
### 24. rate - 评分选择器
- **组件**: `RatePickerField`
- **用途**: 星级评分
### 25. appointment - 预约控件
- **组件**: `AppointmentField`
- **用途**: 时间段预约选择
- **数据结构**: 复杂的日期+时间段结构
### 26. rule - 活动规则控件
- **组件**: `RuleField`
- **用途**: 显示规则说明，支持弹窗
### 27. multi_rule - 活动规则控件（多选）
- **组件**: `MultiRuleField`
- **用途**: 多选规则选项
### 28. contact - 联系人控件
- **组件**: `ContactField`
- **用途**: 联系人信息输入
### 29. button - 按钮控件
- **组件**: `ButtonField`
- **用途**: 自定义按钮
### 30. custom - 自定义控件
- **组件**: `CustomField`
- **用途**: 完全自定义的组件
## 高级类
### 31. group - 组集合输入控件
- **组件**: `GroupField`
- **用途**: 将多个字段分组显示
- **配置**: `field_groups` 数组
### 32. org_picker - 树形选择控件
- **组件**: `OrgPickerField`
- **用途**: 组织架构树形选择
### 33. volunteer_group - 义工组别选择
- **组件**: `VolunteerGroupField`
- **用途**: 义工组别单选
### 34. table_editor - 表格编辑控件
- **组件**: `TableField`
- **用途**: 动态表格编辑，支持增删行
### 35. video - 视频控件
- **组件**: `VideoField`
- **状态**: 已注释，暂未使用
## 组件注册位置
所有组件在 `src/hooks/useComponentType.js` 中注册：
```javascript
export function createComponentType(data) {
_.each(data, (item, index) => {
// 统一名称
item.name = item.key
// 根据 tag 分配组件
if (item.component_props.tag === 'input') {
item.component = TextField;
}
if (item.component_props.tag === 'radio') {
item.component = RadioField;
}
// ... 更多组件
})
}
```
## 新增组件流程
1. 在 `src/components/` 下创建组件目录
2. 创建 `index.vue` 组件文件
3. 在 `src/hooks/useComponentType.js` 添加 if 判断分支
4. 组件必须支持以下 props：
- `item`: Object (包含 component_props 和 value)
- 必须通过 emit 发送 "active" 事件
# component_props 配置规范
## 通用属性
所有组件类型都支持的属性：
| 属性 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `tag` | string | ✅ | - | 组件类型标识，决定渲染哪个组件 |
| `name` | string | ✅ | - | 组件名称 |
| `label` | string | ✅ | - | 字段标签（显示名称） |
| `default` | any | ❌ | - | 默认值 |
| `placeholder` | string | ❌ | "请输入" | 占位符文本 |
| `required` | boolean | ❌ | false | 是否必填 |
| `disabled` | boolean | ❌ | false | 是否隐藏字段 |
| `disabled_show` | boolean | ❌ | false | 隐藏时是否显示闭眼图标 |
| `readonly` | boolean | ❌ | false | 是否只读 |
| `note` | string | ❌ | - | 提示文本（支持HTML） |
## 选项类组件属性
Radio、Checkbox、Picker 等组件额外支持：
| 属性 | 类型 | 说明 |
|------|------|------|
| `options` | Option[] | 选项列表数组 |
| `direction` | string | 排列方向：`vertical`（垂直）/ `horizontal`（水平） |
| `align` | string | 文本对齐：`left` / `center` / `right` |
### Option 结构
```typescript
interface Option {
title: string // 显示文本
value: any // 选项值
checked?: boolean // 默认选中
disabled?: boolean // 禁用状态
color?: string // 选项颜色
background_color?: string // 背景色
// 描述信息
desc_text?: string // 描述文本
desc_type?: string // "text" 或 "url"
desc_url?: string // 描述链接
desc_btn_name?: string // 描述按钮名称
// 补充信息
is_input?: boolean // 是否需要补充信息输入
input_required?: boolean // 补充信息是否必填
input_placeholder?: string // 补充信息占位符
affix?: string // 补充信息值
}
```
## 文本输入类属性
### input / textarea / number
| 属性 | 类型 | 说明 |
|------|------|------|
| `align` | string | 文本对齐方式 |
| `is_camera_scan` | boolean | 是否启用微信扫一扫 |
| `camera_scan_type` | string | 扫码类型：`ALL_CODE` / `QR_CODE` / `BAR_CODE` |
| `is_edit_camera_scan_result` | boolean | 是否允许编辑扫码结果 |
## 上传类属性
### image_uploader
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `max_count` | number | 9 | 最大上传数量 |
| `max_size` | number | 10 | 最大文件大小（MB） |
| `image_type` | string | "jpg/..." | 允许的图片类型 |
**返回值结构**:
```javascript
{
key: "image_uploader",
filed_name: "field_1",
value: [
{ url: "https://...", name: "image.jpg" }
]
}
```
### file_uploader
与 `image_uploader` 类似，用于普通文件上传。
## 日期时间类属性
### date / time / datetime / calendar
| 属性 | 类型 | 说明 |
|------|------|------|
| `min_date` | Date/Date[] | 最小可选日期 |
| `max_date` | Date/Date[] | 最大可选日期 |
| `formatter` | Function | 格式化函数 |
## 预约控件属性
### appointment
**复杂配置结构**:
```javascript
{
tag: "appointment",
label: "预约时间",
appointment_title: "选择入寺时间",
options: [
{
title: "03月27日", // 日期标题
placeholder: "剩余余量 9878", // 提示信息
disabled: false, // 是否禁用该日期
columns: [ // 时间段列表
{
checked: false,
disabled: false,
value: "1",
text: "16:00-17:30 余1399"
}
]
}
]
}
```
## 规则控件属性
### rule / multi_rule
| 属性 | 类型 | 说明 |
|------|------|------|
| `desc_text` | string | 规则内容（支持 `\n` 换行） |
| `desc_type` | string | `text`（弹窗）或 `url`（跳转） |
| `desc_url` | string | 规则详情链接 |
| `desc_btn_name` | string | 按钮名称，如"查看详情" |
## 组集合控件属性
### group
```javascript
{
tag: "group",
label: "物品详情",
field_groups: [
{
tag: "input",
label: "物品描述",
field_name: "field_10",
group_field_name: "field_4", // 所属组字段
// ... 其他属性
}
]
}
```
## 评分控件属性
### rate
| 属性 | 类型 | 说明 |
|------|------|------|
| `x_score` | number | 显示分值（会显示在标签旁） |
## 表格控件属性
### table_editor
| 属性 | 类型 | 说明 |
|------|------|------|
| `default` | string/html | 默认表格内容（HTML格式） |
## 特殊功能属性
### 微信扫码
仅 `input` 类型支持：
```javascript
{
tag: "input",
is_camera_scan: true,
camera_scan_type: "ALL_CODE" // ALL_CODE | QR_CODE | BAR_CODE
}
```
### 补充信息
Radio、Checkbox 支持选择后输入补充信息：
```javascript
options: [
{
title: "其他",
value: "other",
is_input: true, // 启用补充输入
input_required: true, // 补充信息必填
input_placeholder: "请输入补充信息",
affix: "" // 补充信息值
}
]
```
### 显示隐藏控制
通过规则动态控制字段显示/隐藏：
```javascript
{
tag: "input",
disabled: false // true=隐藏，false=显示
}
```
## 样式属性
### 对齐方式
```javascript
{
align: "left" // left | center | right
}
```
### 颜色
选项类组件支持单独配置颜色：
```javascript
options: [
{
title: "重要",
value: "important",
color: "#ff0000", // 文字颜色
background_color: "#fff0f0" // 背景色
}
]
```
## 数据提交格式
### 普通字段
```javascript
{
key: "field_1",
value: "用户输入的值"
}
```
### 选项类字段（Radio）
```javascript
{
key: "field_1",
value: "选项值",
affix: "补充信息: xxx", // 如果有补充信息
type: "radio"
}
```
### 选项类字段（Checkbox）
```javascript
{
key: "field_1",
value: ["值1", "值2"], // 数组
type: "checkbox"
}
```
### 图片上传
```javascript
{
key: "field_1",
filed_name: "field_1",
value: [
{ url: "https://...", name: "image.jpg" }
],
type: "image_uploader"
}
```
# API 接口文档
## 基础配置
### 请求基础配置
所有请求默认携带参数：
```javascript
{
f: 'custom_form' // 固定参数
}
```
### 响应格式
```typescript
interface APIResponse<T = any> {
code: number // 1=成功，其他=失败
msg: string // 响应消息
data: T // 响应数据
show?: boolean // 是否显示错误提示（code !== 1 时）
}
```
### 请求封装
```javascript
import { fn, fetch } from '@/api/fn';
// GET 请求
fn(fetch.get('/srv/?a=xxx', params))
// POST 请求
fn(fetch.post('/srv/?a=xxx', params))
```
## 表单管理接口
### 1. 新增表单
**接口**: `/srv/?a=add_form`
**方法**: POST
**参数**:
```javascript
{
client_id: string, // 主体客户id
name: string, // 表单名称
note: string // 表单描述
}
```
### 2. 查询表单配置（字段和规则）
**接口**: `/srv/?a=query_form_all_field`
**方法**: GET
**参数**:
```javascript
{
f: "custom_form", // 固定参数
form_code: string, // 表单唯一标识（必填）
page_type: string, // 页面类型：add/edit/view（可选）
data_id: string, // 数据ID（编辑时使用）
flow_node_code: string // 流程节点代码（可选）
}
```
**返回**:
```javascript
{
code: 1,
msg: "OK",
data: {
id: 835950,
code: "nxqkbf",
name: "表单名称",
table_name: "customize_35697_nxqkbf",
max_field_num: 3,
field_list: [
{
tag: "input", // 组件类型
field_name: "field_1", // 字段名
label: "姓名", // 显示标签
required: true, // 是否必填
data_type: "text", // 数据类型
placeholder: "请输入",
disabled: false,
readonly: false
}
],
rule_list: [ // 字段显示/隐藏规则
{
field_names: ["field_2"],
mode: "SHOW",
logical_op: "OR",
expr_list: [...]
}
],
flow_process_list: null // 工作流流程列表
}
}
```
**调用示例**:
```bash
curl "https://oa-dev.onwall.cn/srv/?a=query_form_all_field&f=custom_form&form_code=nxqkbf"
```
---
### 2.1. 查询表单设置（表单级配置）
**接口**: `/srv/?a=query_form_setting`
**方法**: GET
**参数**:
```javascript
{
f: "custom_form", // 固定参数
form_code: string // 表单唯一标识（必填）
}
```
**返回**:
```javascript
{
code: 1,
msg: "OK",
data: [{
id: 835950,
code: "nxqkbf",
name: "表单名称",
max_field_num: 3, // 最大字段数
data_count: 7, // 已提交数据条数
extend: {
server_time: "2026-03-16 17:15:40",
is_back_user: false // 是否后台用户
},
property_list: {
sjsj_enable: 1, // 是否启用数据收集
commit_action: "text", // 提交动作类型
commit_text_type: "default",
commit_text_template: "提交成功", // 提交文本模板
edit_commit_action: "text",
edit_commit_text_type: "default",
edit_commit_text_template: "提交成功"
}
}]
}
```
**调用示例**:
```bash
curl "https://oa-dev.onwall.cn/srv/?a=query_form_setting&f=custom_form&form_code=nxqkbf"
```
---
### 2.2. 两个接口的区别
| 接口 | 获取内容 | 用途 |
|------|---------|------|
| `query_form_all_field` | 字段列表、规则列表 | 渲染表单结构 |
| `query_form_setting` | 表单配置、提交设置 | 获取表单级属性 |
### 3. 添加表单字段
**接口**: `/srv/?a=add_form_field`
**方法**: POST
**参数**:
```javascript
{
form_code: string, // 表单唯一标识
component_code: string // 组件标识
}
```
### 4. 添加表单字段属性设置
**接口**: `/srv/?a=add_form_setting`
**方法**: POST
**参数**:
```javascript
{
form_code: string, // 表单唯一标识
field_name: string, // 表单字段名（表单级属性可为空）
component_code: string, // 组件标识
property_code: string, // 属性标识
setting_value: string // 属性值（JSON数组字符串）
}
```
### 5. 查询表单设置
**接口**: `/srv/?a=query_form_setting`
**方法**: GET
**参数**:
```javascript
{
form_code: string // 表单唯一标识
}
```
**返回**:
```javascript
{
enable: number, // 0=停止表单，1=开启表单
is_time_range: number, // 0=不设定，1=设定
is_count_down: number, // 0=不显示，1=显示
begin_time: string, // 开启时间
end_time: string // 停止时间
}
```
### 6. 验证便当密码
**接口**: `/srv/?a=verify_password`
**方法**: POST
**参数**:
```javascript
{
form_code: string, // 表单唯一标识
mmtx_password: string // 用户输入的密码
}
```
### 7. 义工组长查询义工信息
**接口**: `/srv/?a=volunteer_source_leader`
**方法**: GET
**参数**:
```javascript
{
form_code: string, // 表单唯一标识
page_type: string, // 页面类型
force_back: string, // 是否强制后台账号模式检查
volunteer_source: string, // 报名渠道：self/leader
volunteer_phone: string // 义工手机号
}
```
## 数据管理接口
### 1. 添加表单数据
**接口**: `/srv/?a=add_formdata`
**方法**: POST
**参数**:
```javascript
{
form_code: string, // 表单唯一标识
data: object // 待添加的数据（JSON对象）
}
```
**示例**:
```javascript
{
form_code: "form_001",
data: {
field_1: "张三",
field_2: "13800138000",
field_3: ["选项1", "选项2"]
}
}
```
### 2. 查询表单数据
**接口**: `/srv/?a=query_formdata`
**方法**: GET
**参数**:
```javascript
{
form_code: string, // 表单唯一标识
id: string // 数据ID
}
```
### 3. 修改表单数据
**接口**: `/srv/?a=modi_formdata`
**方法**: POST
**参数**:
```javascript
{
form_code: string, // 表单唯一标识
id: string, // 数据ID
data: object // 待修改的数据（JSON对象）
}
```
### 4. 流程表单数据
**接口**: `/srv/?a=flow_formdata`
**方法**: POST
**参数**:
```javascript
{
form_code: string, // 表单唯一标识
data_id: string, // 数据ID
data: object, // 表单数据
flow_node_code: string, // 流程节点
flow_node_action_id: string, // 流程节点按钮ID
flow_content: string // 流程审批意见
}
```
## 组件接口
### 1. 查询组件
**接口**: `/srv/?a=query_component`
**方法**: GET
**参数**:
```javascript
{
group_code: string, // 分组标识
component_code: string, // 组件标识
name: string // 组件名称（模糊查询）
}
```
### 2. 查询部门列表
**接口**: `/srv/?a=flow_setting&t=flow_dept_list`
**方法**: GET
**参数**:
```javascript
{
form_code: string // 表单code
}
```
**请求头建议**:
```javascript
{
headers: {
"only-data": true, // 去重
"keep-data": true // 缓存
}
}
```
### 3. 查询角色列表
**接口**: `/srv/?a=flow_setting&t=flow_role_list`
**方法**: GET
**参数**:
```javascript
{
form_code: string // 表单code
}
```
### 4. 搜索用户部门角色
**接口**: `/srv/?a=flow_setting&t=search_user_dept_role`
**方法**: GET
**参数**:
```javascript
{
form_code: string, // 表单code
word: string // 搜索内容
}
```
## 通用接口
### 1. 发送验证码
**接口**: `/srv/?a=sms`
**方法**: POST
**参数**:
```javascript
{
phone: string // 手机号码
}
```
### 2. 获取七牛上传 Token
**接口**: `/srv/?a=upload`
**方法**: POST
**参数**:
```javascript
qs.stringify({
name: string, // 文件名
hash: string // 文件哈希（ETag）
})
```
### 3. 保存文件
**接口**: `/srv/?a=upload&t=save_file`
**方法**: POST
**参数**:
```javascript
qs.stringify({
format: string, // 图片格式
hash: string, // 文件哈希
height: number, // 图片高度
width: number, // 图片宽度
filekey: string // 七牛返回的文件key
})
```
## 周期接口
### 1. 获取周期列表
**接口**: `/srv/?a=cycle_list`
**方法**: GET
**参数**:
```javascript
{
form_code: string // 表单唯一标识
}
```
**返回**:
```javascript
{
is_cycle: boolean, // 是否需要周期选择
cycle_list: [ // 周期列表
{
cycle_id: string,
cycle_name: string,
start_date: string,
end_date: string
}
]
}
```
## HTTP 请求缓存控制
### 请求去重（only-data）
避免短时间内重复请求：
```javascript
fn(fetch.get('/api/xxx', params, {
headers: { "only-data": true }
}))
```
### 持久化缓存（keep-data）
缓存请求结果（30秒，最多50条）：
```javascript
fn(fetch.get('/api/xxx', params, {
headers: { "keep-data": true }
}))
```
### 同时使用
```javascript
fn(fetch.get('/api/xxx', params, {
headers: {
"only-data": true,
"keep-data": true
}
}))
```
## 错误处理
### 特殊错误码
| 错误码 | 说明 | 处理 |
|--------|------|------|
| 402 | 未授权/登录失效 | 跳转登录页，show=false |
| 其他 | 业务错误 | 显示错误提示 |
### 402 处理示例
```javascript
if (response.data.code === 402) {
response.data.show = false; // 不显示默认错误
showToast({
message: '登录失效！将跳转到登录页面',
duration: 1500,
onClose: () => {
window.location.href = location.origin + '/admin/';
}
})
}
```
This diff is collapsed. Click to expand it.
This diff is collapsed. Click to expand it.
This diff is collapsed. Click to expand it.
This diff is collapsed. Click to expand it.
# docs 文档索引
本文档目录为 LangChain Agent 设计表单生成功能提供完整的项目架构和数据结构参考。
## 文档列表
### 00-数据结构总览.md
**用途**：了解项目的核心数据结构
**内容**：
- 表单字段结构 (FormField)
- 组件属性结构 (ComponentProps)
- 选项结构 (Option)
- API 响应结构
- 数据流转流程
**适合**：Agent 需要理解整体数据模型时
---
### 01-表单字段组件类型.md
**用途**：了解所有支持的组件类型
**内容**：
- 30+ 种组件类型完整列表
- 每种组件的用途和配置要点
- 组件注册位置
- 新增组件流程
**适合**：Agent 需要选择合适的组件类型时
---
### 02-component_props-配置规范.md
**用途**：了解组件属性的详细配置
**内容**：
- 通用属性（所有组件）
- 各类组件专属属性
- Option 结构详解
- 数据提交格式
- 样式属性
**适合**：Agent 生成具体组件配置时
---
### 03-API-接口文档.md
**用途**：了解后端 API 接口
**内容**：
- 表单管理接口（增删改查）
- 数据管理接口
- 组件接口
- 通用接口（上传、验证码等）
- HTTP 缓存控制
**适合**：Agent 需要与后端交互时
---
### 04-示例数据.md
**用途**：提供各类组件的配置示例
**内容**：
- 20+ 个真实配置示例
- 完整表单配置示例
- 数据提交格式示例
- LangChain Prompt 模板
**适合**：Few-shot Learning、Prompt 模板构建
---
### 05-LangChain-Agent-使用指南.md
**用途**：Agent 开发指南
**内容**：
- 自然语言到组件映射表
- 必填/数量/选项识别规则
- 复杂需求处理
- Prompt 模板
- LangChain 代码示例
- 验证和错误处理
**适合**：**开发 LangChain Agent 的主要参考文档**
---
### 06-规则控制系统.md
**用途**：表单字段显示/隐藏规则系统
**内容**：
- 规则系统概述（SHOW/HIDE 模式、AND/OR 逻辑）
- 规则数据结构（rule_list、Rule、RuleExpr）
- 核心函数分析（checkRules、evaluateMultipleRules、evaluateRuleCondition、handleCascadeHiding）
- 触发机制（@active 事件）
- 实际示例（简单/复杂/多规则/级联隐藏）
- LangChain Agent 集成要点
**适合**：Agent 需要生成规则配置或理解字段间依赖关系时
---
### 07-页面数据提取指南.md
**用途**：从实际运行的表单页面中提取配置数据
**内容**：
- Pinia Store 数据存储结构
- 数据提取方法（Chrome DevTools MCP / Vue DevTools API / 直接 API）
- 完整提取流程（打开页面 → 等待加载 → 提取数据 → 解析配置）
- 数据提取模板和代码示例
- 数据转换和验证
**适合**：用户提供表单 URL 时，需要从页面提取完整配置
---
## 快速查找指南
### 按场景查找
| 场景 | 推荐文档 |
|------|----------|
| 理解项目架构 | 00-数据结构总览 |
| 选择组件类型 | 01-表单字段组件类型、05-LangChain-Agent-使用指南 |
| 生成配置 | 02-component_props-配置规范、04-示例数据 |
| Few-shot 示例 | 04-示例数据 |
| 开发 Agent | 05-LangChain-Agent-使用指南 |
| 生成规则配置 | 06-规则控制系统 |
| 理解字段依赖 | 06-规则控制系统 |
| **从 URL 提取表单** | **07-页面数据提取指南** |
### 按组件类型查找
| 组件类别 | 文档位置 |
|----------|----------|
| 文本输入类 | 01-表单字段组件类型（文档输入类） |
| 选择类 | 01-表单字段组件类型（选择类）、04-示例数据（示例4-6） |
| 日期时间类 | 01-表单字段组件类型（日期时间类）、04-示例数据（示例8） |
| 上传类 | 01-表单字段组件类型（上传类）、04-示例数据（示例9） |
| 特殊功能类 | 01-表单字段组件类型（特殊功能类）、04-示例数据（示例11-20） |
### 按属性查找
| 属性 | 文档位置 |
|------|----------|
| 通用属性 | 02-component_props-配置规范（通用属性） |
| options 配置 | 02-component_props-配置规范（选项类组件属性） |
| 图片上传配置 | 02-component_props-配置规范（上传类属性） |
| 样式属性 | 02-component_props-配置规范（样式属性） |
| 规则配置 | 06-规则控制系统（数据结构、触发机制） |
| 字段显示/隐藏 | 06-规则控制系统（SHOW/HIDE 模式） |
| 级联隐藏 | 06-规则控制系统（级联隐藏逻辑） |
## Agent 开发建议
### 1. 先读顺序
1. **05-LangChain-Agent-使用指南** - 了解 Agent 设计要点
2. **01-表单字段组件类型** - 了解可用的组件
3. **04-示例数据** - 获取 Few-shot 示例
4. **02-component_props-配置规范** - 深入了解配置细节
5. **06-规则控制系统** - 了解字段显示/隐藏规则（如需动态表单）
### 2. 关键数据结构
Agent 必须正确理解的核心结构：
```typescript
// 最核心的结构
FormField {
key: string
value: any
component_props: {
tag: string // 决定组件类型
label: string // 显示名称
required: boolean
// ... 其他属性
}
}
```
### 3. 组件类型映射表
直接参考 `05-LangChain-Agent-使用指南` 中的映射表，建立用户描述 → 组件类型的映射。
### 4. Few-shot 示例使用
从 `04-示例数据.md` 中提取典型示例作为 Prompt 的一部分，提高输出质量。
### 5. 验证策略
生成配置后，验证以下内容：
- [ ] tag 值是否有效（参考 01 文档的组件列表）
- [ ] required 是否为布尔值
- [ ] 选项类组件是否有 options 数组
- [ ] 上传类组件是否有合理的数量限制
## 数据流转图
```
用户自然语言
↓
[Agent 解析]
↓
意图识别 + 实体提取
↓
组件类型选择 + 配置生成
↓
[验证输出]
↓
表单字段配置 JSON
↓
createComponentType()
↓
动态表单渲染
```
## 联系方式
如有问题或需要补充文档，请查阅：
- 项目源码：`src/hooks/useComponentType.js`
- 组件目录：`src/components/`
- API 目录：`src/api/`