hookehuyr

docs: 添加仓库协作指南文档

添加 AGENTS.md 文档,详细说明项目结构、构建命令、编码规范、测试要求和提交规范。为项目新成员提供清晰的协作指引,统一团队开发流程。
Showing 1 changed file with 28 additions and 0 deletions
1 +# 仓库协作指南
2 +
3 +## 项目结构与模块组织
4 +本仓库是基于 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/`
5 +
6 +## 构建、测试与开发命令
7 +请使用 `package.json` 中声明的 Node `18.13.x`
8 +
9 +- `npm install`:安装依赖。
10 +- `npm run dev`:启动本地开发服务。
11 +- `npm run start`:以 `0.0.0.0` 启动,便于手机或局域网设备联调。
12 +- `npm run build`:执行生产构建。
13 +- `npm run build-ts`:先执行 `vue-tsc --noEmit`,再进行构建。
14 +- `npm run serve`:本地预览构建产物。
15 +- `npm run cypress:open`:打开 Cypress 进行浏览器测试。
16 +
17 +`npm run dev_upload``npm run oa_upload` 等脚本会打包 `front/` 并上传到指定环境,属于发布操作,不应作为日常调试命令。
18 +
19 +## 编码风格与命名约定
20 +遵循 `prettier.config.js`:2 空格缩进、使用分号、单引号、保留尾随逗号、`printWidth: 100`。遵循 `.eslintrc.js` 的 Vue 3 规则。组件目录使用 PascalCase,例如 `AreaPickerField/`;组合式函数使用 `useXxx.js`;导入优先使用 `vite.config.js` 中定义的别名,如 `@``@components``@api``@utils`
21 +
22 +所有新增说明文字、文档内容、代码注释默认使用中文。提交的代码需要带必要注释,尤其是分页、校验、动态渲染、路由分支、兼容性处理等不直观逻辑;注释应简洁,直接说明目的和约束,避免无意义注释。
23 +
24 +## 测试要求
25 +仓库当前没有固定的 `tests/` 或已提交的 Cypress 用例目录,因此每次改动至少要通过 `npm run build`,并在 `npm run dev``npm run start` 下完成手动冒烟验证。重点检查 `src/views/index.vue` 相关流程,包括动态表单渲染、校验、分页切换、上传组件、路由参数驱动行为等。若新增 Cypress 用例,建议按用户流程命名,例如 `pagination.cy.js`
26 +
27 +## 提交与合并请求规范
28 +近期提交信息采用约定式前缀,可带作用域,例如 `feat(分页): ...``refactor(分页): ...``fix: ...``docs: ...`。提交标题应简短、直接、体现动作。发起 PR 时请提供变更摘要、影响的页面或字段类型、验证步骤;若涉及界面调整,附上移动端截图或录屏;若影响部署脚本或环境配置,需在说明中单独标出。