> ## Documentation Index
> Fetch the complete documentation index at: https://help.agatabo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rapport des Parts

> Voir la répartition de la participation des membres selon les soldes d'épargne

## Aperçu

Le **Rapport des Parts** affiche le solde d'épargne de chaque membre et son pourcentage de participation dans le total de l'épargne des membres, ce qui fournit une vue claire de la répartition des capitaux dans l'organisation.

<Note>
  **Autorisation requise** : `reports:read`

  Ce rapport est généré à partir des comptes du grand livre SAVINGS des membres et montre la répartition de la participation à une date précise.
</Note>

***

## Point d'Accès API

**Obtenir le rapport des parts :**

```http theme={null}
GET /reports/shares-report?asOfDate={date}
Headers:
  x-organization-id: {organizationId}
```

**Paramètres de requête :**

| Paramètre  | Type              | Obligatoire | Description                                                           |
| ---------- | ----------------- | ----------- | --------------------------------------------------------------------- |
| `asOfDate` | string (date ISO) | Non         | Date instantanée pour le calcul des parts. Par défaut, date actuelle. |

**Exemple de requête :**

```bash theme={null}
curl -X GET "https://api.agatabo.com/reports/shares-report?asOfDate=2026-06-30" \
  -H "x-organization-id: org-abc123" \
  -H "Authorization: Bearer {token}"
```

***

## Structure de Réponse

```json theme={null}
{
  "asOfDate": "2026-06-30T00:00:00.000Z",
  "totalShares": 10000000.00,
  "rows": [
    {
      "organizationUserId": "orguser-123",
      "name": "John Doe",
      "accountNumber": "SAV-001",
      "amount": 1200000.00,
      "percentage": 12.00
    },
    {
      "organizationUserId": "orguser-456",
      "name": "Jane Smith",
      "accountNumber": "SAV-002",
      "amount": 1000000.00,
      "percentage": 10.00
    },
    {
      "organizationUserId": "orguser-789",
      "name": "Peter Kalisa",
      "accountNumber": "SAV-003",
      "amount": 800000.00,
      "percentage": 8.00
    }
    // ... more rows
  ]
}
```

**Champs de réponse :**

| Champ                       | Type                  | Description                                                                   |
| --------------------------- | --------------------- | ----------------------------------------------------------------------------- |
| `asOfDate`                  | string (datetime ISO) | Date instantanée du rapport                                                   |
| `totalShares`               | number                | Total de tous les soldes d'épargne des membres                                |
| `rows`                      | array                 | Enregistrements individuels des parts membres (triés par montant décroissant) |
| `rows[].organizationUserId` | string                | ID utilisateur de l'organisation                                              |
| `rows[].name`               | string                | Nom du membre                                                                 |
| `rows[].accountNumber`      | string                | Numéro du compte d'épargne                                                    |
| `rows[].amount`             | number                | Solde d'épargne du membre                                                     |
| `rows[].percentage`         | number                | Pourcentage de participation (amount ÷ totalShares × 100)                     |

**Notes importantes :**

* **Trié par montant** : Les lignes sont ordonnées par solde d'épargne, du plus élevé au plus faible
* **Soldes positifs uniquement** : Les membres avec soldes nuls ou négatifs sont exclus
* **Soldes actuels** : Calculés à partir de toutes les écritures comptables publiées jusqu'à `asOfDate`
* **Comptes SAVINGS** : Les données viennent des comptes du grand livre avec le rôle `SAVINGS` et la portée `organizationUser:{id}`

***

## Qu'est-ce qu'une Part ?

Dans le modèle de tontine d'Agatabo :

**Part** = Solde total d'épargne du membre

**Pourcentage de part** = (Épargne du membre ÷ Total de toute l'épargne des membres) × 100

**Exemple** :

```
Total épargne membres : 10 000 000 RWF
Épargne de Jane :          500 000 RWF
Part de Jane :                5,00 %
```

Ce pourcentage détermine :

* L'allocation des dividendes (si distribution selon la contribution)
* La participation dans les capitaux de l'organisation
* L'intérêt proportionnel dans les actifs de l'organisation

***

## Fonctionnement

Le rapport des parts :

1. **Trouve tous les comptes SAVINGS des membres**
   * Requête : `SELECT * FROM ledger_accounts WHERE role = 'SAVINGS'`
   * Chaque membre a un compte SAVINGS (portée : `organizationUser:{id}`)

2. **Calcule le solde jusqu'à asOfDate**
   * Additionne toutes les lignes d'écritures comptables pour chaque compte
   * SAVINGS est de type LIABILITY : CREDIT augmente le solde, DEBIT diminue le solde
   * Formule : `balance += (side === 'CREDIT' ? amount : -amount)`
   * Inclut uniquement les écritures comptables POSTED jusqu'à `asOfDate` inclus

3. **Filtre les soldes positifs**
   * Exclut les comptes avec soldes nuls ou négatifs
   * Affiche uniquement les membres actifs avec épargne

4. **Calcule les pourcentages**
   * Additionne tous les soldes pour obtenir `totalShares`
   * Pour chaque membre : `percentage = (amount / totalShares) × 100`
   * Arrondi à 2 décimales

5. **Trie par montant**
   * Lignes ordonnées par `amount` décroissant
   * Les plus grands détenteurs de parts apparaissent en premier

***

## Cas d'Utilisation

### Planification de Distribution de Dividendes

**Prévisualiser l'allocation des dividendes avant distribution :**

```http theme={null}
GET /reports/shares-report?asOfDate=2026-06-30
```

Si 500 000 RWF de bénéfice sont distribués selon la contribution :

* John Doe (12,00 %) : 60 000 RWF
* Jane Smith (10,00 %) : 50 000 RWF
* Peter Kalisa (8,00 %) : 40 000 RWF

Voir : [Dividendes par Contribution](/fr/tontines/dividends/overview)

***

### Suivi des Capitaux des Membres

**Montrer aux membres leur participation :**

À l'Assemblée Générale Annuelle, présentez le rapport des parts pour démontrer :

* Le solde d'épargne actuel de chaque membre
* Le pourcentage de participation dans l'épargne totale de l'organisation
* Comment la participation a changé sur l'année (comparaison au rapport de l'année précédente)

***

### Transparence Financière

**Répondre aux questions "Combien est-ce que je possède ?" :**

Le rapport des parts fournit des réponses claires et auditables :

* "Vous avez 500 000 RWF d'épargne"
* "Cela représente 5,00 % de participation"
* "Si nous distribuions toute l'épargne aujourd'hui, vous recevriez 5 % du total"

***

### Rapport au Conseil

**Présenter la structure de participation pendant les réunions :**

Utilisez le rapport des parts pour montrer :

* **Concentration de la participation** : L'épargne est-elle répartie équitablement ou concentrée ?
* **Engagement des membres** : Combien de membres contribuent activement ?
* **Tendances de croissance** : Comparer le total des parts aux périodes précédentes

***

## Comprendre les Changements de Parts

**Les parts augmentent quand :**

* Le membre effectue des dépôts
* Des intérêts sont crédités à l'épargne (si applicable)
* Des dividendes sont ajoutés à l'épargne

**Les parts diminuent quand :**

* Le membre effectue des retraits (si autorisé par les règles de l'organisation)
* Des frais sont déduits de l'épargne

**Le pourcentage de part change quand :**

Même si votre solde reste identique, votre pourcentage peut changer :

**Exemple** :

```
Mois 1 :
  Jane :   500 000 RWF sur 10 000 000 total = 5,00 %

Mois 2 (Jane dépose 100 000 RWF) :
  Jane :   600 000 RWF
  Autres membres déposent 2 000 000 RWF
  Nouveau total : 12 100 000 RWF
  Nouveau pourcentage de Jane : 4,96 % (diminué malgré un solde plus élevé !)
```

**Pourquoi ?** Parce que les dépôts des autres membres ont augmenté le fonds total, diluant le pourcentage de Jane.

***

## Comparer les Périodes

**Suivre les changements de participation dans le temps :**

```http theme={null}
# Prior month
GET /reports/shares-report?asOfDate=2026-05-31

# Current month
GET /reports/shares-report?asOfDate=2026-06-30
```

**Ce qu'il faut comparer :**

* Variation des soldes individuels des membres
* Variation des pourcentages de parts
* Total des parts (croissance de l'organisation)
* Nouveaux membres ajoutés
* Membres qui ont retiré ou quitté (plus dans le rapport)

**Exemple d'analyse :**

| Membre       | Solde Mai | % Mai   | Solde Juin | % Juin  | Variation |
| ------------ | --------- | ------- | ---------- | ------- | --------- |
| John Doe     | 1 100 000 | 11,00 % | 1 200 000  | 12,00 % | +1,00 %   |
| Jane Smith   | 1 000 000 | 10,00 % | 1 000 000  | 10,00 % | 0,00 %    |
| Peter Kalisa | 750 000   | 7,50 %  | 800 000    | 8,00 %  | +0,50 %   |

**Insights :**

* John Doe a augmenté son épargne et son pourcentage de participation (dépôt de 100 000 RWF)
* Le solde et le pourcentage de Jane Smith sont inchangés (aucune activité)
* Peter Kalisa a augmenté son épargne et son pourcentage de participation (dépôt de 50 000 RWF)

***

## Indicateurs Clés

Calculer à partir des données du rapport des parts :

**Part moyenne par membre :**

```
Moyenne = totalShares ÷ nombre de lignes
```

**Concentration de la participation :**

```
Concentration top 10 % = (Somme des 10 % de membres principaux) ÷ totalShares × 100
```

**Cible** : Les organisations saines ont généralement 20-40 % de concentration dans les 10 % de membres principaux

**Participation des membres :**

```
Membres actifs = nombre de lignes du rapport
Taux de participation = (Membres actifs ÷ Total des membres enregistrés) × 100
```

**Cible** : >80 % des membres enregistrés épargnent activement

***

## Relation avec les Autres Rapports

**Bilan :**

* Total des parts = passif "Épargne des Membres" au Bilan
* Le rapport des parts détaille ce total par membre individuel

**Exemple de rapprochement :**

```
Bilan (au 30 juin 2026) :
  PASSIFS
    Épargne Membres : 10 000 000 RWF

Rapport des Parts (au 30 juin 2026) :
  Total des Parts : 10 000 000 RWF ✓ (doit correspondre)
```

**Dividendes :**

* Lors d'une distribution de dividendes "par contribution", le rapport des parts montre la base
* Chaque membre reçoit : (Total dividende × pourcentage du membre)

***

## Source de Données

**Le rapport des parts est généré à partir de :**

**Comptes du grand livre SAVINGS :**

```sql theme={null}
SELECT * FROM ledger_accounts
WHERE organization_id = {orgId}
  AND role_definition.role = 'SAVINGS'
  AND scope_key LIKE 'organizationUser:%'
```

**Lignes d'écritures comptables :**

```sql theme={null}
SELECT * FROM journal_entry_lines
WHERE ledger_account_id IN (savings_account_ids)
  AND journal_entry.status = 'POSTED'
  AND journal_entry.posted_at <= {asOfDate}
```

**Calcul du solde (SAVINGS est LIABILITY) :**

```typescript theme={null}
let balance = 0;
for (const line of journalLines) {
  // CREDIT increases liability (deposits)
  // DEBIT decreases liability (withdrawals)
  balance += line.side === 'CREDIT' ? line.amount : -line.amount;
}
```

***

## Bonnes Pratiques

<Note>
  **Génération des rapports de parts :**

  **Calendrier :**

  * ✅ Générer après clôture de période pour des instantanés historiques exacts
  * ✅ Exécuter avant la distribution de dividendes pour calculer les allocations
  * ✅ Examiner trimestriellement pour suivre les tendances de participation
  * ✅ Présenter aux Assemblées Générales Annuelles pour la transparence

  **Exactitude :**

  * ✅ S'assurer que tous les dépôts et retraits sont publiés avant génération
  * ✅ Vérifier que `totalShares` correspond à "Épargne Membres" au Bilan
  * ✅ Contrôler par sondage les soldes membres avec les relevés individuels
  * ✅ Investiguer tout changement de pourcentage inattendu

  **Analyse :**

  * ✅ Comparer à la période précédente pour identifier les tendances
  * ✅ Calculer la part moyenne pour comprendre l'épargne typique des membres
  * ✅ Surveiller la concentration de participation pour la répartition équitable
  * ✅ Suivre le taux de participation des membres (épargnants actifs ÷ total membres)

  **Communication :**

  * ✅ Partager le rapport avec les membres pendant les réunions trimestrielles
  * ✅ Expliquer comment les pourcentages sont calculés
  * ✅ Montrer la relation avec la distribution de dividendes
  * ✅ Répondre ouvertement aux questions sur les changements de parts
</Note>

***

## Questions Fréquentes

**Q : Pourquoi les parts ne correspondent-elles pas au total des contributions ?**

R : Parts = **solde actuel**, pas **total des contributions**. Le solde peut différer à cause de :

* Retraits effectués (réduit le solde)
* Intérêts crédités à l'épargne (augmente le solde)
* Dividendes ajoutés à l'épargne (augmente le solde)
* Frais déduits (réduit le solde)

**Q : Le pourcentage de part affecte-t-il les droits de vote ?**

R : Cela dépend des statuts de votre organisation :

* **Un membre, une voix** : Le pourcentage de part n'a pas d'importance pour le vote
* **Vote pondéré** : Votes proportionnels au pourcentage de participation

Vérifiez les règles de gouvernance de votre organisation.

**Q : Les pourcentages peuvent-ils ne pas totaliser exactement 100 % ?**

R : L'arrondi à 2 décimales peut créer de légers écarts. Le backend calcule les pourcentages exacts ; les valeurs affichées sont arrondies pour la lisibilité. Le total doit être très proche de 100,00 %.

**Q : Pourquoi un membre manque-t-il dans le rapport ?**

R : Les membres avec soldes d'épargne nuls ou négatifs sont exclus. Raisons possibles :

* Nouveau membre qui n'a pas encore déposé
* Membre qui a retiré toute son épargne
* Erreur de saisie (vérifier les relevés membres)

**Q : Les membres peuvent-ils voir les parts des autres membres ?**

R : Cela dépend de la configuration des autorisations :

* Les utilisateurs avec l'autorisation `reports:read` peuvent voir les parts de tous les membres
* Généralement : Administrateurs, Comptables, Trésoriers, Membres du Conseil
* Membres ordinaires : Peuvent seulement voir leur propre solde (via les relevés membres)

Vérifiez auprès de l'administrateur la politique d'accès.

***

## Exemple : Analyse Trimestrielle

**Scénario** : Comparer les parts du T1 et du T2 pour identifier les tendances

**Appels API :**

```bash theme={null}
# Q1 (end of March)
curl -X GET "https://api.agatabo.com/reports/shares-report?asOfDate=2026-03-31" \
  -H "x-organization-id: org-abc123"

# Q2 (end of June)
curl -X GET "https://api.agatabo.com/reports/shares-report?asOfDate=2026-06-30" \
  -H "x-organization-id: org-abc123"
```

**Analyse :**

| Indicateur        | T1 (31 mars)        | T2 (30 juin)        | Variation |
| ----------------- | ------------------- | ------------------- | --------- |
| Total Parts       | 9 500 000           | 10 000 000          | +5,26 %   |
| Nombre de Membres | 24                  | 25                  | +1 membre |
| Part Moyenne      | 395 833             | 400 000             | +1,05 %   |
| Plus Grande Part  | 1 150 000 (12,11 %) | 1 200 000 (12,00 %) | +50 000   |

**Insights :**

* L'organisation a augmenté son épargne de 500 000 RWF (croissance saine)
* Un nouveau membre a rejoint
* La part moyenne par membre a augmenté (les membres existants épargnent davantage)
* Le plus grand détenteur a augmenté son solde mais son pourcentage a légèrement diminué (bon signe - moins de concentration)

***

## Sujets Connexes

<CardGroup cols={2}>
  <Card title="Dividendes" icon="hand-coins" href="/fr/tontines/dividends/overview">
    Distribuer les bénéfices selon le pourcentage de participation
  </Card>

  <Card title="Dépôts et Épargne" icon="money-bill-wave" href="/fr/tontines/deposits/overview">
    Suivre les contributions d'épargne des membres
  </Card>

  <Card title="Bilan" icon="scale-balanced" href="/fr/tontines/reports/balance-sheet">
    Total parts = passif Épargne Membres
  </Card>

  <Card title="Relevés Membres" icon="file-invoice" href="/fr/tontines/reports/member-statements">
    Activité et soldes de comptes individuels
  </Card>
</CardGroup>