Repository Guidelines

项目结构与模块组织

本仓库是 AGV 智能巡检系统，后端、前端、ROS2 启动链路分目录维护。agv_app/ 是 Flask 后端，包含 API、模板、静态资源与 data/*.json 持久化配置；agv_app/utils/ 放置 AGV、Nav2、机械臂、二维码与任务执行逻辑。arm_server/ 是机械臂端 TCP/摄像头服务及 systemd 配置。scan_fixer/ 提供生产链路中的 ROS2 时间戳修正工具。public-frontend/ 是 Next.js 平板端，源码在 src/app、src/components、src/services、src/store、src/types。scripts/ 与 Makefile 负责本地开发、生产启动和停止流程，docs/ 存放技术文档。

构建、测试与开发命令

make install：执行 uv sync 并安装前端 npm 依赖。
make dev：显示本地开发启动说明。
make dev-backend：以 Mock 硬件模式启动 Flask 后端。
make dev-frontend：启动 Next.js 开发服务器。
make prod：在 AGV 上启动 ROS2、Nav2、scan fixer 与 Flask 完整生产链路。
cd public-frontend && npm run build：构建前端。
cd public-frontend && npm run lint && npm run typecheck：执行前端 lint 与 TypeScript 检查。

编码风格与命名约定

Python 目标版本为 3.10，依赖由根目录 pyproject.toml 和 uv.lock 管理。保持模块职责清晰，配置集中放在 agv_app/config.py，复用硬件抽象时优先放入 agv_app/utils/。前端使用 TypeScript、React、Next.js App Router 与 Ant Design；组件使用 PascalCase，例如 CameraFrame.tsx，服务和工具使用 camelCase，例如 apiClient.ts。新增代码应自解释命名，避免魔术值，必要注释只说明业务背景或非常规取舍。

测试指南

当前仓库未配置独立单元测试框架。提交前至少运行相关静态检查：前端改动运行 npm run lint 和 npm run typecheck，后端改动用 make dev-backend 做 Flask 启动与关键接口冒烟验证。涉及硬件、ROS2 或生产脚本的改动，应说明是否已在真实 AGV 或 Mock 模式验证。

提交与 Pull Request 规范

历史提交主要使用英文祈使句式，例如 Improve camera status and production startup、Refactor ROS startup scripts、Fix shell compatibility issues in prod-backend.sh。继续使用简短英文提交信息，避免无意义占位。PR 应包含变更摘要、验证命令、硬件/环境影响、相关 issue；前端界面变化需附截图或录屏，生产启动链路变化需列出影响的脚本和服务。

安全与配置提示

不要提交新的密钥、令牌、设备私有地址或本地日志。环境示例放在 .env.example，运行时覆盖优先使用环境变量，例如 BACKEND_URL、MOCK_HARDWARE、AGV_PROJECT_DIR。涉及 AGV、机械臂或 ROS2 生产配置时，先核对 scripts/README.md 中的默认路径与日志位置。

2.9 KiB Raw Blame History