# AGENTS.md - Development Guidelines

This file contains essential information for AI agents working on this codebase.

## Project Overview

PHP website for "Harmonie de Montpellier-Jacou" (music band) with a Vue.js 2 frontend for score management.
- **Backend**: PHP with MySQL (legacy codebase)
- **Frontend**: Vue.js 2 + Bootstrap Vue (in `frontend/score/`)
- **API**: RESTful PHP API in `api/` directory

## Build Commands

### Frontend (Vue.js)
```bash
cd frontend/score
npm install
npm run serve      # Development server
npm run build      # Production build
npm run lint       # ESLint check
```

### PHP
No build step required. Deploy to PHP-enabled web server.

## Testing

**No test framework configured.**

To add tests:
- **PHP**: Consider PHPUnit
- **Vue**: Add Jest or Vitest via Vue CLI

Run single test (when configured):
```bash
# Example for Jest (not yet configured)
npm test -- --testNamePattern="test name"
```

## Code Style Guidelines

### PHP
- Use `<?php` opening tags (avoid short `<?` tags for consistency)
- Classes: PascalCase (e.g., `Score`, `Database`)
- Methods: camelCase (e.g., `readScore`, `getEntryName`)
- Variables: snake_case or camelCase (be consistent within files)
- Indent: 3 spaces (legacy style) - maintain consistency with surrounding code
- Place opening braces on same line as class/function declaration
- Use `include_once` for required files
- **Note**: Uses legacy MySQL functions (consider upgrading to PDO/MySQLi)

### JavaScript/Vue
- ESLint configuration in `package.json`:
  - Extends: `plugin:vue/essential`, `eslint:recommended`
  - Parser: `babel-eslint`
- Use ES6+ features (async/await, arrow functions)
- Components: PascalCase
- Data properties: camelCase
- Use 2-space indentation
- Semicolons required

### General
- UTF-8 encoding for all files
- French language for user-facing content
- Maintain GPL v2 license headers in PHP files

## File Organization

```
/
├── api/              # REST API endpoints
│   ├── config/       # Database configuration
│   ├── objects/      # Data models
│   └── score/        # API endpoints
├── frontend/score/   # Vue.js application
│   ├── src/          # Source code
│   └── public/       # Static assets
├── Scripts/          # PHP page controllers
├── fpdf/             # PDF generation library
├── Imgs/             # Image assets
├── Textes/           # Text content files
└── index.php         # Main entry point
```

## Database

MySQL database connection configured in `api/config/database.php`:
- Uses legacy `mysql_*` functions
- Database name: `ohmj2`
- Tables: `repertoire` (for scores)

## Error Handling

- PHP: Uses `@` error suppression operator in some places
- Vue: Uses try/catch with console.log for errors
- Return HTTP 200 on success in API responses

## Security Notes

- API uses `Access-Control-Allow-Origin: *` (CORS enabled for all)
- SQL queries use string concatenation (vulnerable to SQL injection)
- Database credentials stored in plain text in `api/config/database.php`
- Sanitize user inputs before database queries

## Git

- No CI/CD configured
- Commit to main branch
- Standard `.gitignore` for Node.js projects

## Dependencies

### Frontend
- Vue 2.6.11
- Bootstrap Vue 2.17.3
- Axios 0.21.0
- Vue CLI 4.5.0

### PHP
- FPDF library for PDF generation
- MySQL extension (legacy)

## Important Notes

- **No external CDN dependencies allowed** - All assets must be local (fonts, JS libraries, etc.)
- Use local copies in `static/` folder instead of CDN

## Notes

- This is a legacy codebase with mixed coding styles
- Prefer consistency with existing code over strict style enforcement
- Site targets French-speaking users
- Production URL: `ohmj2.free.fr`

## Design Guidelines

- **Style**: Clean, sober, and modern
- **Icons**: Use SVG icons instead of emojis for better consistency
- **Buttons**: Integrate related actions (view + download) in a single row with consistent styling
- **Hide unnecessary labels**: Don't show "Piece 1" or "Version 1" when there's only one
- **Visual hierarchy**: Use spacing, subtle borders, and hover effects for interactivity

## Temporary Work Files

- Use `_builds/` directory for temporary scripts and working files
- Only `scripts/convert_final_v2.js` should be kept in the scripts folder (committed to git)
- CSV output files belong in `_builds/`

## Authentication

- **Login**: Use `apiService.login('admin', 'password')` from frontend
- **API calls**: Include token in Authorization header:
  ```
  Authorization: Bearer <token>
  ```
- **Token format**: JWT (HS256) - see `api/lib/Auth.php`
- **Frontend**: Token stored in localStorage, auto-attached to API requests via axios interceptor
- **Test**: http://localhost:5173 - login with admin/password
- **API base URL**: http://localhost:8000/api/

## Current Tech Stack (2024)

- **Frontend**: SvelteKit (NOT Vue.js 2) in `/partitions/`
- **Backend**: PHP API in `/api/`
- **Scores storage**: `/legacy/Scores/` (directory-based, not MySQL)