AG Convocation System (Issue #88)

Overview

Automatic generation and sending of general assembly (AG) invitations with strict compliance to Belgian copropriété law deadlines.

Belgian Legal Requirements

Article 577-6 §2 of the Belgian Civil Code mandates minimum notice periods for general assembly convocations:

The system automatically calculates the minimum_send_date based on the meeting date and type, and blocks sending if the legal deadline would not be respected.

Workflow

Draft → Scheduled → Sent → (Cancelled)

Features

Legal deadline validation: Prevents sending too late
Email tracking: sent_at, opened_at (tracking pixel), failed (bounce)
Reminder automation: J-3 automatic reminders for unopened emails
Attendance tracking: Pending → WillAttend/WillNotAttend → Attended/DidNotAttend
Proxy delegation: Belgian “procuration” support
Multi-language: FR/NL/DE/EN PDF generation
Bulk operations: Atomic creation of all recipients

Recipient Tracking

Each recipient has individual tracking:

email_sent_at: When the convocation email was sent
email_opened_at: When the email was opened (tracking pixel)
email_failed: Whether delivery failed (bounce)
reminder_sent_at: When the J-3 reminder was sent
attendance_status: Current attendance status
proxy_owner_id: Delegate for vote proxy

Tracking Summary provides aggregate statistics:

Total recipients, opened count, will_attend count
Opening rate, attendance rate

API Endpoints (14)

POST /convocations - Create with legal deadline validation
GET /convocations/:id - Get details
GET /convocations/meeting/:meeting_id - By meeting
GET /buildings/:id/convocations - Building convocations
PUT /convocations/:id/schedule - Schedule send date
POST /convocations/:id/send - Send to all owners
PUT /convocations/:id/cancel - Cancel
GET /convocations/:id/recipients - List recipients
GET /convocations/:id/tracking-summary - Aggregate stats
PUT /convocation-recipients/:id/email-opened - Mark opened
PUT /convocation-recipients/:id/attendance - Update attendance
PUT /convocation-recipients/:id/proxy - Set proxy
POST /convocations/:id/reminders - Send J-3 reminders
DELETE /convocations/:id - Delete

Architecture

Domain: convocation.rs (440 lines), convocation_recipient.rs (260 lines)
Use Cases: convocation_use_cases.rs (21 methods)
Migration: 20251119000000_create_convocations.sql
BDD Tests: convocations.feature (13 scenarios)
Total: ~3,650 lines of code