# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

BattlefieldExplorationSystem (formerly CasualtySightPlus) is a Qt 5.15 C++ comprehensive battlefield intelligence and exploration system. It integrates unmanned aerial vehicles (UAVs/drones) and ground robots (robot dogs) to provide real-time battlefield reconnaissance, enemy detection, and tactical intelligence gathering capabilities through desktop GUI, web-based mapping, and QML interfaces.

## Build Commands

### Standard Build
```bash
qmake BattlefieldExplorationSystem.pro
make
```

### Clean Build
```bash
make clean
qmake BattlefieldExplorationSystem.pro
make
```

### Install
```bash
make install  # Installs to /opt/BattlefieldExplorationSystem/bin/
```

## Architecture Overview

### Functional Modules

#### 1. Device Management Module 🤖
- **Device Registration**: Add UAVs and robot dogs with name, IP address, and GPS coordinates (longitude/latitude)
- **Device Inventory**: List and manage all existing unmanned devices in the system
- **Device Status Monitoring**: Real-time status tracking including connectivity, battery level, and signal strength

#### 2. Map Display Module 🗺️
- **Campus Map Integration**: Display current school location using web-based mapping (AMap integration)
- **Device Positioning**: Show real-time device locations on the interactive map
- **Geographic Visualization**: Coordinate-based positioning system for tactical awareness

#### 3. Battlefield Exploration Module 🎯
**Robot Dog Capabilities**:
- **Autonomous Mapping (SLAM)**: Simultaneous Localization and Mapping for terrain exploration
- **Navigation & Obstacle Avoidance**: Intelligent pathfinding and collision avoidance systems

**UAV/Drone Capabilities**:
- **Real-time Photo Transmission**: Stream captured images from drone cameras
- **AI-Powered Person Recognition**: Automated person detection and identification in captured images
- **Enemy Position Marking**: Automatically mark detected enemy positions on the tactical map

#### 4. Intelligence Communication Module 📡
- **Voice Communication**: Audio transmission capabilities through robot dogs for friendly force communication
- **Real-time Tactical Coordination**: Voice-based information sharing and coordination

#### 5. Enemy Intelligence Analysis Module 📊
- **Enemy Position Visualization**: Display all detected enemy positions on the tactical map
- **Intelligence Dashboard**: Visual analytics and statistical overview of reconnaissance data
- **AI-Powered Analysis**: Integration with large language models for automated enemy situation analysis and tactical recommendations

### Database Layer
Unified device management with MySQL backend:
- **devices**: Unified table for UAVs and robot dogs (device_type: 'uav'/'dog')
- **exploration_tasks**: Mission planning and task management
- **device_operation_logs**: Comprehensive operation logging
- **system_config**: System configuration management

### UI Architecture
- **Modular Structure**: Organized in `src/ui/` with main, components, dialogs, and exploration modules
- **MainWindow**: Central control interface (formerly GuidingUI) for unified device management
- **QML Integration**: Modern map interfaces (MAP.qml, MAP2.qml, MAP3.qml) for interactive visualization
- **Web Integration**: HTML/AMap-based mapping (res/html/map.html) for geographic display
- **Component-Based Design**: Reusable UI components for device cards, status panels, and controls

## Key Technologies

### Qt Modules Used
- Core modules: `core gui sql charts` - Foundation and database integration
- Location: `positioning location quickwidgets` - GPS and mapping support
- Web: `webenginewidgets webchannel` - Map integration and web-based visualization
- Media: `multimedia multimediawidgets` - Audio communication and image processing

### External Dependencies
- **AMap (高德地图)**: Chinese mapping service for campus/battlefield visualization
- **AI/ML Services**: Person recognition and image analysis capabilities
- **Voice Communication**: Audio transmission through robot dogs
- **Qt Charts**: Statistical visualization for intelligence analysis
- **MySQL**: Database backend (Client database) for unified device management
- **Large Language Models**: AI-powered enemy situation analysis (integration ready)

## Resource Management

Assets are managed through Qt Resource System:
- **Images**: `/image` prefix - military icons, UI elements, status indicators
- **QML**: `/qml` prefix - interactive map components
- **Web**: `/html` prefix - HTML mapping interfaces

## Code Standards

Code in this project follows the coding standards defined in `/home/hzk/Software_Architecture/src/Client/代码规范.md`. All new code must adhere to:

- **Qt C++ Naming Conventions**: PascalCase for classes, camelCase for functions, m_ prefix for member variables
- **File Structure**: Proper header guards, include order (system → third-party → project internal)
- **Documentation**: Comprehensive Doxygen-style comments for all public interfaces
- **Code Formatting**: 4-space indentation, Qt-style brace placement, 100-character line limit
- **Qt-Specific Standards**: Proper Q_OBJECT usage, new-style signal-slot connections, parent-child memory management
- **Error Handling**: Comprehensive parameter validation, proper logging with QLoggingCategory
- **Performance**: Const reference passing, smart pointer usage, container optimization

Please reference the complete coding standards document before contributing code to ensure consistency and maintainability.

## Development Notes

### File Structure
**Modular Organization (Post-Refactor)**:
- **Source Files**: Organized in `src/` with modular structure
  - `src/core/database/` - Database management classes
  - `src/ui/main/` - Main interface (MainWindow)
  - `src/ui/dialogs/` - Dialog components
  - `src/ui/components/` - Reusable UI components
  - `src/utils/` - Utility classes
- **Header Files**: Mirror structure in `include/` directory
- **UI Forms**: Organized in `forms/` directory by functional modules
- **Build Artifacts**: All generated files in `build/` directory
- **Resources**: `res.qrc` contains all embedded assets (images, icons, QML, HTML)
- **Documentation**: All project documents in `doc/` directory - organized by category
- **Generated Files**: `moc_*.cpp`, `ui_*.h`, and object files auto-generated in `build/`

### Database Pattern
- **Unified Device Management**: Single `devices` table for both UAVs and robot dogs
- **Device Type Differentiation**: `device_type` field ('uav'/'dog') for type distinction
- **Backward Compatibility**: Views (uavdatabase/dogdatabase) maintain compatibility with legacy code
- **Singleton Pattern**: Database managers follow singleton pattern with static instance access

### Coordinate System
Application uses longitude/latitude coordinates throughout for precise geographic positioning:
- **Campus-based**: Centered around school location for tactical exercises
- **Real-time Tracking**: Continuous GPS coordinate updates for device positioning
- **Map Integration**: Both QML and web components expect WGS84 geographic coordinates

### Build Artifacts
- **Object Files**: `.o` files generated during compilation
- **MOC Files**: `moc_*.cpp` files for Qt meta-object system
- **UI Headers**: `ui_*.h` files generated from `.ui` files
- **Resource Code**: `qrc_*.cpp` generated from `.qrc` files

## Testing

**Current Testing Strategy**:
- Manual testing through GUI interaction and device simulation
- Database connectivity and CRUD operation validation
- Map integration and coordinate system verification
- **Future**: Unit testing framework integration planned for device management modules

## Deployment

Application configured for:
- **Primary**: Linux x86_64 desktop environment
- **Secondary**: Android deployment capability (AndroidManifest.xml present)
- **Installation**: System-wide deployment to `/opt/BattlefieldExplorationSystem/`
- **Target Environment**: Campus-based tactical training and simulation

## Documentation Management Strategy

### Document Organization Structure

All project documentation is organized in the `doc/` directory with the following categorization:

```
doc/
├── README.md                 # Documentation index and navigation
├── planning/                 # Project planning and requirements
│   ├── task.md              # Task breakdown and progress tracking
│   ├── project_structure_plan.md
│   ├── refactor_impact_assessment.md
│   └── [future planning docs]
├── technical/               # Technical implementation details
│   ├── api_documentation.md
│   ├── component_design.md
│   ├── coding_standards.md
│   └── [future technical docs]
├── database/               # Database design and scripts
│   ├── database_schema.sql
│   ├── migration_scripts/
│   └── [future database docs]
├── reports/                # Progress and analysis reports
│   ├── phase1_completion_report.md
│   ├── phase2_completion_report.md
│   └── [future reports]
└── git/                    # Version control and workflow
    ├── git_branch_strategy.md
    ├── code_review_guidelines.md
    └── [future git docs]
```

### Documentation Guidelines for Claude

#### When Creating New Documents:
1. **Determine Category**: Place documents in appropriate subdirectory based on content type
2. **Follow Naming Convention**: Use lowercase with underscores (`document_name.md`)
3. **Update Index**: Add reference to new document in `doc/README.md`
4. **Include Metadata**: Add creation date, author, and version if applicable

#### Document Categories:

- **planning/**: Requirements, architecture design, project planning, impact assessments
- **technical/**: API docs, component designs, coding standards, build instructions  
- **database/**: Schema definitions, migration scripts, database design docs
- **reports/**: Phase completion reports, testing reports, performance analyses
- **git/**: Branch strategies, code review guidelines, release processes

#### Document Placement Examples:
- New component design → `doc/technical/component_name_design.md`
- Database migration script → `doc/database/migration_scripts/v2.0_migration.sql`
- Phase completion report → `doc/reports/phaseN_completion_report.md`
- Code review guidelines → `doc/git/code_review_guidelines.md`
- Requirements specification → `doc/planning/requirements_specification.md`

#### Maintenance Requirements:
1. Keep `doc/README.md` updated with new documents
2. Use consistent Markdown formatting
3. Include table of contents for long documents
4. Update documents when related code changes
5. Archive outdated documents rather than deleting them
6. **Proactively maintain project documentation**: When completing tasks or phases, immediately update relevant documents (such as `task.md`, completion reports, and progress tracking documents) to ensure documentation accuracy and project transparency

#### Documentation Update Strategy:
**"Timely Documentation Completion"** - Whenever working on a task or completing a phase:
- Update task status in relevant planning documents
- Create completion reports for major milestones
- Maintain real-time project progress tracking
- Ensure all stakeholders have access to current project status

This organization ensures all project knowledge is systematically captured and easily accessible for team members and future development phases.