# rcapi

Squelette d'API HTTP versionnée pour la migration de `rcws`.

## Structure

- `api/v1/index.php` : point d'entrée HTTP.
- `api/src/` : noyau minimal `Request`, `Response`, `Router`, `Auth`, erreurs.
- `api/src/Service/UserService.php` : service métier `serveruser` commun aux routes REST et legacy.
- `api/src/Repository/UserRepository.php` : accès PDO/SQLite aux tables `user`, `domaine`, `profil`, `pdu`.
- `api/src/Legacy/LegacyMethodMap.php` : mapping temporaire des méthodes RPC vers les routes REST.
- `var/db/` : emplacement local ignoré pour la base SQLite `serveruser`.
- `openapi.yaml` : contrat initial.
- `config/api.example.env` : exemple de configuration sans secret réel.
- `MIGRATION_RCWS.md` : plan détaillé d'import et de migration méthode par méthode.

## Exécution locale

```bash
RCWS_API_KEYS='facts:<VOTRE_CLE_API>' \
RCWS_SERVERUSER_DB_PATH='./var/db/base_user.db' \
RCWS_LOG_PATH='./var/log/rcapi.log' \
php -S 127.0.0.1:8080 -t .
```

Tests manuels REST :

```bash
curl -i http://127.0.0.1:8080/api/v1/health

curl -i \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <VOTRE_CLE_API>' \
  http://127.0.0.1:8080/api/v1/domains

curl -i \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <VOTRE_CLE_API>' \
  http://127.0.0.1:8080/api/v1/domains/1/users
```

Appel legacy compatible avec les clients actuels :

```bash
curl -i \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'methode=getUsersByDomain' \
  --data-urlencode 'param={"domaine_id":1}' \
  --data-urlencode 'apikey=<VOTRE_CLE_API>' \
  http://127.0.0.1:8080/serveruser/index.php
```

Le format legacy conserve les clés historiques `param1`, `param2`, `param3` pour `getUsersByDomain`.

## Logs applicatifs

Par défaut, l'API écrit ses traces applicatives dans :

```text
var/log/rcapi.log
```

La cible peut être surchargée avec :

```bash
RCWS_LOG_PATH='/var/log/rcapi/rcapi.log'
```

Le logger trace les exceptions serveur, les erreurs PHP fatales et les usages
de l'API legacy. Les clés API, tokens, mots de passe, headers
d'authentification et payloads complets ne sont pas journalisés.

### Mode debug facts -> rcapi

Le debug peut être activé sans configuration Apache/PHP-FPM :

```text
http://beta.tnk/facts/html?debug=1
```

Le JavaScript conserve alors le mode debug dans `localStorage` et dans un
cookie `facts_debug`, puis le contrôleur `/libs/controller/sessioncontroller.php`
propage `debug=1` vers `rcapi`.

Pour désactiver :

```text
http://beta.tnk/facts/html?debug=0
```

Activation serveur persistante possible par fichier :

```bash
touch /mnt/One/web/beta/rcapi/var/debug.enabled
touch /mnt/One/web/beta/libs/config/debug.enabled
```

Logs à suivre :

```bash
tail -f /mnt/One/web/beta/log/sessions/$(date +%F)-session.log
tail -f /mnt/One/web/beta/rcapi/var/log/rcapi.log
```

## Données serveruser

La base SQLite n'est pas versionnée. En local, copier la base issue de `rcws/serveruser` vers :

```text
var/db/base_user.db
```

ou renseigner explicitement :

```bash
RCWS_SERVERUSER_DB_PATH='/chemin/vers/base_user.db'
```

Les champs sensibles `salt` et `password_requested_at` ne sont pas exposés par les services publics. Le champ `password` est remplacé par le placeholder `*******` dans les objets d'édition legacy.

## Exemples d'appel

### Depuis `libs/controller/sessioncontroller.php`

Pour tester la nouvelle API sans passer par l'endpoint legacy
`/serveruser/index.php`, le contrôleur de session doit appeler directement
`/api/v1` avec l'en-tête `X-API-Key`.

Configuration côté client `libs` :

```ini
[general]
apikey = "<VOTRE_CLE_API>"

[servers]
api[default] = "http://beta.tnk/rcapi/api/v1"
```

Configuration côté `rcapi` :

```bash
RCWS_API_KEYS='facts:<VOTRE_CLE_API>'
```

Si `RCWS_API_KEYS` n'est pas fourni par Apache/PHP-FPM, `rcapi` reprend en
fallback la clé `general.apikey` de `/mnt/One/web/beta/libs/config/config.ini`
pour le client `facts`. Ce fallback évite de dupliquer le secret dans le dépôt
pendant la migration.

Un exemple complet de contrôleur compatible avec le frontend actuel est
maintenu dans `docs/sessioncontroller-rest.md`.

### PHP

```php
<?php

$ch = curl_init('http://127.0.0.1:8080/api/v1/domains/1/users');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: <VOTRE_CLE_API>',
    ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}

curl_close($ch);

$response = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

if ($status >= 400) {
    throw new RuntimeException($response['error']['message'] ?? 'Erreur API RCWS');
}

print_r($response['data']);
```

### JavaScript

```javascript
const response = await fetch('http://127.0.0.1:8080/api/v1/domains/1/users', {
  headers: {
    Accept: 'application/json',
    'X-API-Key': '<VOTRE_CLE_API>',
  },
});

const payload = await response.json();

if (!response.ok) {
  throw new Error(payload.error?.message ?? 'Erreur API RCWS');
}

console.log(payload.data);
```

Le premier lot `serveruser` est branché sur la base SQLite migrée et expose les mêmes opérations en REST et en legacy.

## Migration RCWS

Le plan détaillé est maintenu dans `MIGRATION_RCWS.md`. Il décrit l'import du code historique, la compatibilité legacy, l'extraction vers les services, les repositories, les tests et le décommissionnement progressif des anciens endpoints.