docs: 添加 CLAUDE.md 项目指南

- 项目概述和快速开始命令
- 核心架构说明（动态表单系统、路由、缓存）
- 30+ 表单字段组件类型列表
- 开发规范和常见陷阱说明

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

+# 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+ 种类型的表单字段组件。
+
+## 快速开始
+
+```bash
+# 安装依赖
+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` 属性决定渲染哪种组件：
+
+```javascript
+// 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 检查)
+
+```javascript
+// src/router.js
+// 关键逻辑：404 → 动态路由加载 → 周期选择 → 表单检查 → 目标页面
+```
+
+### HTTP 请求缓存
+
+Axios 封装实现了两种缓存机制：
+- **only-data**: 请求去重，避免重复请求
+- **keep-data**: 持久化缓存（30秒，最多50条）
+
+```javascript
+// src/utils/axios.js
+// 通过请求头控制
+headers: {
+  'only-data': true,  // 去重
+  'keep-data': true   // 缓存
+}
+```
+
+## 关键约定
+
+### 组件开发规范
+
+1. **所有表单字段组件必须**：
+   - 使用 `v-model` 绑定值
+   - 通过 `component_props` 接收配置
+   - 支持 `placeholder` 属性
+   - 支持 `required` 验证
+
+2. **组件命名规范**：
+   - 目录名：PascalCase（如 `TextField`）
+   - 文件名：`index.vue`
+
+### API 调用规范
+
+```javascript
+// 所有 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*