feat: add full project - backend, frontend, docker, specs and configs

.specify/features/006-client-area/contracts/admin.md

@@ -0,0 +1,143 @@
+# Contract: Admin Endpoints
+
+**Blueprint**: `admin_bp` — prefix `/api/v1/admin`
+**Auth**: JWT Bearer — `require_auth` — MVP: qualquer ClientUser autenticado
+**Dívida Técnica**: Verificação de role admin adiada para feature pós-MVP (ver Constitution Check no plan.md)
+
+---
+
+# POST /api/v1/admin/boletos
+
+Cria um boleto para um cliente, opcionalmente vinculado a um imóvel.
+
+## Request
+
+```
+POST /api/v1/admin/boletos
+Authorization: Bearer <jwt_token>
+Content-Type: application/json
+
+{
+  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "property_id": "4gb96g75-6828-5673-c4gd-3d074g77bg33",
+  "description": "Aluguel referente a Maio/2026",
+  "amount": 3500.00,
+  "due_date": "2026-05-10",
+  "url": "https://boleto.banco.com.br/abc123"
+}
+```
+
+Campos obrigatórios: `user_id`, `description`, `amount`, `due_date`.
+Campos opcionais: `property_id`, `url`.
+
+---
+
+## Response 201 Created
+
+```json
+{
+  "id": "d5be07h8-9012-6784-d5he-4e185h88ch33",
+  "description": "Aluguel referente a Maio/2026",
+  "amount": "3500.00",
+  "due_date": "2026-05-10",
+  "status": "pending",
+  "url": "https://boleto.banco.com.br/abc123"
+}
+```
+
+---
+
+## Response 404 Not Found
+
+```json
+{ "error": "Cliente não encontrado" }
+```
+
+Quando `user_id` não corresponde a nenhum `ClientUser` existente.
+
+---
+
+## Response 422 Unprocessable Entity
+
+```json
+{
+  "error": "Dados inválidos",
+  "details": ["user_id: field required", "amount: field required"]
+}
+```
+
+---
+
+## Response 401 Unauthorized
+
+```json
+{ "error": "Token inválido ou ausente" }
+```
+
+---
+
+# PUT /api/v1/admin/visits/<id>/status
+
+Atualiza o status de uma VisitRequest e opcionalmente define a data/hora agendada.
+
+## Request
+
+```
+PUT /api/v1/admin/visits/b3fc85f6-1234-4562-b3fc-2c963f66af11/status
+Authorization: Bearer <jwt_token>
+Content-Type: application/json
+
+{
+  "status": "confirmed",
+  "scheduled_at": "2026-05-01T10:00:00"
+}
+```
+
+`status` obrigatório: `"pending"` | `"confirmed"` | `"cancelled"` | `"completed"`
+`scheduled_at` opcional: ISO 8601 datetime string.
+
+---
+
+## Response 200 OK
+
+```json
+{
+  "id": "b3fc85f6-1234-4562-b3fc-2c963f66af11",
+  "property": {
+    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "title": "Apartamento 3 quartos Jardins",
+    "slug": "apartamento-3-quartos-jardins"
+  },
+  "message": "Gostaria de visitar no final de semana.",
+  "status": "confirmed",
+  "scheduled_at": "2026-05-01T10:00:00Z",
+  "created_at": "2026-04-13T10:00:00Z"
+}
+```
+
+---
+
+## Response 404 Not Found
+
+```json
+{ "error": "Visita não encontrada" }
+```
+
+---
+
+## Response 422 Unprocessable Entity
+
+```json
+{
+  "error": "Dados inválidos",
+  "details": ["status: value is not a valid enumeration member"]
+}
+```
+
+---
+
+## Response 401 Unauthorized
+
+```json
+{ "error": "Token inválido ou ausente" }
+```