仓库协作指南

项目结构与模块组织

本仓库是基于 Vue 3 + Vite 的移动端动态表单系统，主要代码位于 src/。字段组件集中在 src/components/，例如 TextField、PaginationField、ImageUploaderField，通常采用“PascalCase 目录 + index.vue 入口”结构。页面放在 src/views/，路由相关代码位于 src/router/ 和 src/route.js，公共逻辑分布在 src/composables/、src/hooks/、src/utils/、src/api/。静态资源位于 public/ 与 src/assets/，业务说明文档位于 docs/agent/。

构建、测试与开发命令

请使用 package.json 中声明的 Node 18.13.x。

• npm install：安装依赖。
• npm run dev：启动本地开发服务。
• npm run start：以 0.0.0.0 启动，便于手机或局域网设备联调。
• npm run build：执行生产构建。
• npm run build-ts：先执行 vue-tsc --noEmit，再进行构建。
• npm run serve：本地预览构建产物。
• npm run cypress:open：打开 Cypress 进行浏览器测试。

npm run dev_upload、npm run oa_upload 等脚本会打包 front/ 并上传到指定环境，属于发布操作，不应作为日常调试命令。

编码风格与命名约定

遵循 prettier.config.js：2 空格缩进、使用分号、单引号、保留尾随逗号、printWidth: 100。遵循 .eslintrc.js 的 Vue 3 规则。组件目录使用 PascalCase，例如 AreaPickerField/；组合式函数使用 useXxx.js；导入优先使用 vite.config.js 中定义的别名，如 @、@components、@api、@utils。

所有新增说明文字、文档内容、代码注释默认使用中文。提交的代码需要带必要注释，尤其是分页、校验、动态渲染、路由分支、兼容性处理等不直观逻辑；注释应简洁，直接说明目的和约束，避免无意义注释。

测试要求

仓库当前没有固定的 tests/ 或已提交的 Cypress 用例目录，因此每次改动至少要通过 npm run build，并在 npm run dev 或 npm run start 下完成手动冒烟验证。重点检查 src/views/index.vue 相关流程，包括动态表单渲染、校验、分页切换、上传组件、路由参数驱动行为等。若新增 Cypress 用例，建议按用户流程命名，例如 pagination.cy.js。

提交与合并请求规范

近期提交信息采用约定式前缀，可带作用域，例如 feat(分页): ...、refactor(分页): ...、fix: ...、docs: ...。提交标题应简短、直接、体现动作。发起 PR 时请提供变更摘要、影响的页面或字段类型、验证步骤；若涉及界面调整，附上移动端截图或录屏；若影响部署脚本或环境配置，需在说明中单独标出。