CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个移动端动态表单系统，基于 Vue 3 + Vite 构建，使用 Vant 4 作为 UI 组件库。系统支持通过配置动态生成 30+ 种类型的表单字段组件。

快速开始

# 安装依赖
npm install

# 开发（支持网络访问）
npm run dev
npm run start  # 监听 0.0.0.0

# 构建
npm run build

# 构建 + 打包 + 部署（一体化）
npm run {env}_upload  # env: dev, oa, mituo, guanzong, baorong, taishan, xys, zentea, behalo
npm run all_upload   # 部署到所有环境

技术栈

• 框架: Vue 3 (Composition API)
• 构建: Vite 2
• UI 库: Vant 4
• 状态管理: Pinia
• 路由: Vue Router 4 (Hash 模式)
• HTTP: Axios
• 语言: JavaScript/TypeScript 混合

核心架构

动态表单系统

项目的核心是动态表单字段组件系统，通过 component_props.tag 属性决定渲染哪种组件：

// src/hooks/useComponentType.js
// 支持的组件类型包括：
input, textarea, number, radio, checkbox, select, address,
date, time, datetime, image_uploader, file_uploader, phone,
email, sign, rate, calendar, id_card, desc, divider, marquee,
contact, rule, multi_rule, button, note, name, gender,
appointment, custom, group, org_picker, volunteer_group, table_editor

字段组件目录

src/components/
├── TextField/           # 单行文本
├── TextareaField/       # 多行文本
├── RadioField/          # 单选
├── CheckboxField/       # 多选
├── PickerField/         # 选择器
├── AreaPickerField/     # 地址选择
├── DatePickerField/     # 日期选择
├── ImageUploaderField/  # 图片上传
├── SignField/           # 电子签名
├── TableField/          # 表格编辑
└── ...（30+ 组件）

路由系统

动态路由加载：使用 import.meta.globEager 自动加载 src/router/routes/modules/ 下的路由模块。

关键路由流程：

1. 404 页面作为中转，动态加载异步路由
2. 周期选择检查 (checkCycleSelection)
3. 未完成表单恢复 (Cookie 检查)

// src/router.js
// 关键逻辑：404 → 动态路由加载 → 周期选择 → 表单检查 → 目标页面

HTTP 请求缓存

Axios 封装实现了两种缓存机制：

• only-data: 请求去重，避免重复请求
• keep-data: 持久化缓存（30秒，最多50条）

// src/utils/axios.js
// 通过请求头控制
headers: {
  'only-data': true,  // 去重
  'keep-data': true   // 缓存
}

关键约定

组件开发规范

1. 所有表单字段组件必须：

   • 使用 v-model 绑定值
   • 通过 component_props 接收配置
   • 支持 placeholder 属性
   • 支持 required 验证

2. 组件命名规范：

   • 目录名：PascalCase（如 TextField）
   • 文件名：index.vue

API 调用规范

// 所有 API 默认携带参数 f: 'custom_form'
// 使用封装的 fn() 处理响应
import { fn } from '@/api/fn';

路由参数规范

常用查询参数：

• code: 表单唯一标识
• page_type: 页面类型 (add/edit/view)
• model: 模式 (preview/正式)
• x_cycle: 跳过周期检查
• force_back: 强制后台模式

部署说明

项目使用 SCP + SSH 自动化部署到多个环境（dev、oa、mituo 等）。部署流程：

1. npm run build 构建
2. 打包为 dist.tar.gz
3. SCP 传输到目标服务器
4. SSH 解压到指定目录

常见陷阱

1. 动态路由刷新白屏

问题：动态路由刷新时 404 解决：路由守卫中 404 作为中转，延迟 1s 后加载动态路由

2. 表单字段组件未注册

问题：新增组件后未在 useComponentType.js 中注册 解决：在 src/hooks/useComponentType.js 添加对应的 if 判断分支

3. Vant 组件需手动注册

问题：某些 Vant 组件未全局注册 解决：在 src/main.js 中添加 app.use(ComponentName)

4. 路由周期检查死循环

问题：周期选择页面互相跳转 解决：检查 cycle_selected 参数和 sessionStorage 中的 skip_cycle_check_for_auth

5. 移动端兼容性

• 避免使用 PC 端特有的 API（如 window.location.href 赋值跳转，应使用 router.push）
• Vant 组件在小程序环境可能不兼容（项目为 H5 项目，无此问题）

外部文档

• Vant 4 文档: https://vant-ui.github.io/vant/#/zh-CN
• Vue Router 文档: https://router.vuejs.org/zh/
• Pinia 文档: https://pinia.vuejs.org/zh/
• Vite 文档: https://cn.vitejs.dev/

---

最后更新: 2026-03-16