c1881f58e6
Inclui console handoff Desk↔Console (Spec 019), melhorias DNS Viewer (037), OpenPanel/Nextcloud/VM116 deploy notes, contracts stack e sidebar actualizado. Co-authored-by: Cursor <cursoragent@cursor.com>
173 lines
3.1 KiB
Markdown
173 lines
3.1 KiB
Markdown
# Contrato — Nextcloud Provisioning + Desk API (Spec 034)
|
|
|
|
**Versão:** 0.1 draft
|
|
**Auth Nextcloud OCS:** Basic (admin app password) ou token de serviço
|
|
**Auth Desk:** Bearer session (RBAC Spec 027)
|
|
|
|
---
|
|
|
|
## 1. Nextcloud OCS — utilizador (Wizard VM112)
|
|
|
|
### Criar utilizador
|
|
|
|
```http
|
|
POST /ocs/v1.php/cloud/users
|
|
Authorization: Basic {admin}:{app_password}
|
|
OCS-APIRequest: true
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
userid=admin%40empresa.com.br&password=***&displayName=Admin+Empresa
|
|
```
|
|
|
|
**Resposta 200:**
|
|
|
|
```xml
|
|
<ocs>
|
|
<meta><status>ok</status></meta>
|
|
<data/>
|
|
</ocs>
|
|
```
|
|
|
|
### Definir quota Files
|
|
|
|
```http
|
|
PUT /ocs/v1.php/cloud/users/{userid}
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
key=quota&value=25GB
|
|
```
|
|
|
|
### Apagar utilizador (purge)
|
|
|
|
```http
|
|
DELETE /ocs/v1.php/cloud/users/{userid}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Wizard VM112 — evento interno
|
|
|
|
Após provision OK:
|
|
|
|
```json
|
|
{
|
|
"event": "onboarding.nextcloud.provisioned",
|
|
"domain": "empresa.com.br",
|
|
"email": "admin@empresa.com.br",
|
|
"nextcloud_userid": "admin@empresa.com.br",
|
|
"files_url": "https://files.empresa.com.br",
|
|
"quota_files": "25GB",
|
|
"carbonio_quota_gb": 5,
|
|
"session_id": "uuid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Desk API — health
|
|
|
|
### GET `/api/v1/nextcloud/health`
|
|
|
|
**Roles:** `super_admin`, `ops_lead`, `technician`, `noc`
|
|
|
|
**Resposta 200:**
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"vm116": {
|
|
"reachable": true,
|
|
"nextcloud_version": "30.0.0",
|
|
"disk_used_pct": 12,
|
|
"url": "https://cloud.ligbox.com.br"
|
|
},
|
|
"carbonio_vm112": {
|
|
"reachable": true,
|
|
"disk_used_pct": 22
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Desk API — status domínio
|
|
|
|
### GET `/api/v1/nextcloud/domains/{domain}/status`
|
|
|
|
**Roles:** `super_admin`, `ops_lead`, `technician`
|
|
|
|
**Resposta 200:**
|
|
|
|
```json
|
|
{
|
|
"domain": "empresa.com.br",
|
|
"carbonio": {
|
|
"accounts": 3,
|
|
"domain_quota_gb": 30,
|
|
"domain_used_gb": 8.2,
|
|
"mail_host": "mail.empresa.com.br"
|
|
},
|
|
"nextcloud": {
|
|
"enabled": true,
|
|
"users": 3,
|
|
"files_url": "https://files.empresa.com.br",
|
|
"total_quota_gb": 75,
|
|
"total_used_gb": 12.1
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Desk API — provision manual
|
|
|
|
### POST `/api/v1/nextcloud/domains/{domain}/users`
|
|
|
|
**Roles:** `super_admin`, `ops_lead`
|
|
|
|
**Body:**
|
|
|
|
```json
|
|
{
|
|
"email": "vendas@empresa.com.br",
|
|
"display_name": "Vendas",
|
|
"quota_files": "25GB",
|
|
"sync_password": true,
|
|
"password": "********"
|
|
}
|
|
```
|
|
|
|
**Resposta 201:**
|
|
|
|
```json
|
|
{
|
|
"userid": "vendas@empresa.com.br",
|
|
"files_url": "https://files.empresa.com.br",
|
|
"provisioned_at": "2026-06-20T22:00:00Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Erros standard
|
|
|
|
| HTTP | code | Descrição |
|
|
|------|------|-----------|
|
|
| 404 | `domain_not_found` | Domínio não orquestrado VM112 |
|
|
| 409 | `user_exists` | User NC ou Carbonio já existe |
|
|
| 502 | `nextcloud_unreachable` | VM124 down |
|
|
| 503 | `feature_disabled` | `NEXTCLOUD_INTEGRATION=0` |
|
|
|
|
---
|
|
|
|
## 7. Variáveis ambiente (Wizard VM112)
|
|
|
|
```env
|
|
NEXTCLOUD_INTEGRATION=0
|
|
NEXTCLOUD_OCS_URL=https://10.10.10.124
|
|
NEXTCLOUD_ADMIN_USER=ligbox-provisioner
|
|
NEXTCLOUD_ADMIN_APP_PASSWORD=***
|
|
NEXTCLOUD_DEFAULT_QUOTA=25GB
|
|
NEXTCLOUD_FILES_URL_TEMPLATE=https://files.{domain}
|
|
CARBONIO_DEFAULT_QUOTA_GB=5
|
|
```
|