Repository Guidelines

项目结构与模块组织

本仓库是一个基于 Vue 3 与 Vite 的地图项目。核心代码位于 src/：views/ 放页面级地图与打卡流程，components/ 放可复用组件，api/ 放接口封装，common/ 与 utils/ 放共享工具。静态资源主要在 src/assets/ 和顶层 images/。构建与接口辅助脚本位于 scripts/。现有测试样例主要放在 src/test/，多入口示例位于 src/packages/mono1 和 src/packages/mono2。

构建、测试与开发命令

• 运行环境：进入仓库后先执行 source "$HOME/.nvm/nvm.sh" && nvm use 18.13.0，当前确认版本为 node v18.13.0、npm v8.19.3。
• npm run dev：启动本地 Vite 开发服务。
• npm run start：以 0.0.0.0 暴露开发服务，便于真机联调。
• npm run build：按当前 .env 配置生成生产构建。
• npm run build-ts：先执行 vue-tsc --noEmit，再进行构建。
• npm run serve：本地预览最新构建产物。
• npm run api:generate：执行 scripts/generateApiFromOpenAPI.js 重新生成接口代码。
• npm run cypress:open：打开 Cypress，进行手动界面测试。

build_tar、dev_upload、xys_upload 等部署脚本依赖 SSH 权限和目标环境信息，只有在确认具备发布条件时再使用。

代码风格与命名规范

遵循现有 Prettier 配置：2 空格缩进、保留分号、使用单引号、单行不超过 100 字符，并在合法位置保留尾随逗号。src/components/ 下的 Vue 单文件组件通常使用 PascalCase 命名，如 InfoPopup.vue；路由页面文件则大量沿用小写命名，如 src/views/checkin/map.vue。工具函数与接口模块优先使用 camelCase。新增文件时先参考所在目录已有风格，避免引入新的命名体系。

测试说明

当前仓库还没有统一的 npm test 入口。轻量级单元测试可参考 src/test/mocha/，例如运行 npx mocha src/test/mocha/test.js。界面流程测试使用 npm run cypress:open。新增测试建议放在对应功能附近或 src/test/ 下，文件名尽量清晰，例如 map-marker.spec.js。

提交与 Pull Request 规范

最近提交基本遵循 Conventional Commit，并可附带作用域，例如 feat(checkin): ...、fix(map): ...。建议继续使用 type(scope): summary 格式，保证一次提交只做一类改动。提交 PR 时应说明用户可见的变化、是否影响环境变量或接口、关联任务或 issue；涉及地图或界面改动时，附上截图或简短录屏。

安全与配置提示

不要提交真实凭据，也不要把环境专属配置直接写入 .env*。keys/、部署主机信息和上传脚本都应视为敏感运维资源。修改 vite.config.js 中的代理、基础路径或输出目录前，先确认不会影响现有部署流程。