docs: 添加仓库协作指南文档
添加 AGENTS.md 文档,详细说明项目结构、构建命令、编码规范、测试要求和提交规范。为项目新成员提供清晰的协作指引,统一团队开发流程。
Showing
1 changed file
with
28 additions
and
0 deletions
AGENTS.md
0 → 100644
| 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 时请提供变更摘要、影响的页面或字段类型、验证步骤;若涉及界面调整,附上移动端截图或录屏;若影响部署脚本或环境配置,需在说明中单独标出。 |
-
Please register or login to post a comment