# 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` 中的默认路径与日志位置。