first commit
This commit is contained in:
277
docs/03-api.md
Normal file
277
docs/03-api.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 3. API
|
||||
|
||||
API GraphQL en `/graphql` (HTTP para queries y mutations, WebSocket `graphql-ws` para subscriptions) más unos pocos
|
||||
endpoints REST bajo `/api`. El esquema completo se genera en `apps/api/schema.gql`.
|
||||
|
||||
## 3.1 Modelo de dominio (contexto `tracker`)
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Project {
|
||||
key: "TS"
|
||||
name
|
||||
members: (userId, role)[]
|
||||
addMember() changeMemberRole() removeMember() updateDetails()
|
||||
}
|
||||
class Issue {
|
||||
key: "TS-42"
|
||||
type · area · priority · status
|
||||
assigneeId · releaseId · labels · figmaUrl
|
||||
links: (type, target)[]
|
||||
changeStatus() assign() linkTo() unlink() setRelease() updateDetails()
|
||||
}
|
||||
class Comment {
|
||||
body · authorId
|
||||
edit() delete()
|
||||
}
|
||||
class Release {
|
||||
name · status · targetDate
|
||||
update() ship() archive()
|
||||
}
|
||||
Project "1" --> "*" Issue
|
||||
Issue "1" --> "*" Comment
|
||||
Project "1" --> "*" Release
|
||||
Release "0..1" <-- "*" Issue
|
||||
Issue "*" --> "*" Issue : links
|
||||
```
|
||||
|
||||
### Roles por proyecto
|
||||
|
||||
| Rol | Ver | Crear/modificar tickets, comentar | Gestionar miembros y releases |
|
||||
| -------------------------------- | --- | --------------------------------- | -------------------------------------------- |
|
||||
| `OWNER` (quien crea el proyecto) | ✅ | ✅ | ✅ (no se le puede quitar ni cambiar el rol) |
|
||||
| `ADMIN` | ✅ | ✅ | ✅ |
|
||||
| `MEMBER` | ✅ | ✅ | ❌ |
|
||||
| `VIEWER` | ✅ | ❌ | ❌ |
|
||||
|
||||
Cualquiera puede salir de un proyecto (salvo el propietario). Los no miembros reciben _not found_, para no revelar que
|
||||
el proyecto existe.
|
||||
|
||||
### Workflow de un ticket
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> BACKLOG
|
||||
BACKLOG --> TODO
|
||||
BACKLOG --> IN_PROGRESS
|
||||
BACKLOG --> CANCELLED
|
||||
TODO --> BACKLOG
|
||||
TODO --> IN_PROGRESS
|
||||
TODO --> CANCELLED
|
||||
IN_PROGRESS --> TODO
|
||||
IN_PROGRESS --> IN_REVIEW
|
||||
IN_PROGRESS --> READY_FOR_QA
|
||||
IN_PROGRESS --> CANCELLED
|
||||
IN_REVIEW --> IN_PROGRESS
|
||||
IN_REVIEW --> READY_FOR_QA
|
||||
IN_REVIEW --> DONE
|
||||
READY_FOR_QA --> IN_QA
|
||||
READY_FOR_QA --> IN_PROGRESS
|
||||
IN_QA --> DONE
|
||||
IN_QA --> QA_FAILED
|
||||
QA_FAILED --> IN_PROGRESS
|
||||
QA_FAILED --> TODO
|
||||
DONE --> TODO
|
||||
DONE --> IN_PROGRESS
|
||||
CANCELLED --> BACKLOG
|
||||
```
|
||||
|
||||
- `QA_FAILED` y `CANCELLED` exigen un **motivo**, que queda en el historial.
|
||||
- No se puede pasar a `DONE` saltándose QA salvo desde `IN_REVIEW` (cambios que no requieren QA).
|
||||
- `Issue.allowedTransitions` en GraphQL devuelve los estados permitidos desde el actual.
|
||||
|
||||
### Otras reglas
|
||||
|
||||
- **Proyecto**: clave de 2 a 10 caracteres alfanuméricos que empieza por letra y es única (los tickets se numeran
|
||||
`CLAVE-1`, `CLAVE-2`…).
|
||||
- **Asignación**: solo a miembros del proyecto. Para añadir miembros, el usuario debe existir y estar activo en Pireon.
|
||||
- **Relaciones**: nunca consigo mismo ni duplicadas; pueden cruzar proyectos si el actor puede ver el destino. Se
|
||||
muestran en los dos tickets (`OUTWARD` en el origen, `INWARD` en el destino).
|
||||
- **Releases**: solo las `PLANNED` aceptan o pierden tickets; publicar con tickets sin terminar exige `force: true`.
|
||||
- **Comentarios**: solo el autor edita; borra el autor o un admin del proyecto.
|
||||
- **Cambios de UI**: `figmaUrl` debe ser un enlace `https://…figma.com/…`.
|
||||
|
||||
### Eventos de dominio
|
||||
|
||||
Todo cambio es un evento guardado en el event store (stream = id del agregado). Llevan `actorId`, `occurredAt`,
|
||||
`aggregateId`, `projectId` y `aggregateVersion` (la posición en el stream).
|
||||
|
||||
| Agregado | Eventos |
|
||||
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Project | `ProjectCreatedEvent`, `ProjectUpdatedEvent`, `ProjectMemberAddedEvent`, `ProjectMemberRoleChangedEvent`, `ProjectMemberRemovedEvent` |
|
||||
| Issue | `IssueCreatedEvent`, `IssueUpdatedEvent`, `IssueStatusChangedEvent`, `IssueAssignedEvent`, `IssueLinkedEvent`, `IssueUnlinkedEvent`, `IssueReleaseChangedEvent` |
|
||||
| Comment | `CommentAddedEvent`, `CommentEditedEvent`, `CommentDeletedEvent` |
|
||||
| Release | `ReleaseCreatedEvent`, `ReleaseUpdatedEvent`, `ReleaseShippedEvent`, `ReleaseArchivedEvent` |
|
||||
|
||||
## 3.2 GraphQL
|
||||
|
||||
Todas las operaciones requieren `Authorization: Bearer <token de Pireon>` (en subscriptions, en el `connection_init`).
|
||||
|
||||
### Queries
|
||||
|
||||
| Query | Devuelve |
|
||||
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `me` | El usuario autenticado, con sus roles en Pireon |
|
||||
| `users(search, limit)` | Usuarios de Pireon (para asignar o añadir miembros) |
|
||||
| `user(id)` | Un usuario |
|
||||
| `myProjects` | Proyectos de los que soy miembro |
|
||||
| `project(idOrKey)` | Un proyecto. Campos calculados: `board(releaseId, assigneeId, area, perColumn)`, `stats`, `releases` |
|
||||
| `issues(filter, limit, offset)` | Búsqueda de tickets (estado, tipo, área, prioridad, persona, release, etiquetas, texto) |
|
||||
| `issue(idOrKey)` | Un ticket. Campos calculados: `allowedTransitions`, `linkedIssues`, `comments`, `history` |
|
||||
| `release(id)` | Una release. Campos calculados: `progress`, `issues` |
|
||||
| `activity(projectId, issueId?, limit, before?)` | Feed de actividad, del más reciente al más antiguo |
|
||||
|
||||
### Mutations
|
||||
|
||||
Todas devuelven `CommandResult { id, key, version }`.
|
||||
|
||||
| Ámbito | Mutations |
|
||||
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| Proyectos | `createProject`, `updateProject`, `addProjectMember`, `changeProjectMemberRole`, `removeProjectMember` |
|
||||
| Tickets | `createIssue`, `updateIssue`, `changeIssueStatus`, `assignIssue`, `linkIssues`, `unlinkIssues`, `setIssueRelease` |
|
||||
| Comentarios | `addComment`, `editComment`, `deleteComment` |
|
||||
| Releases | `createRelease`, `updateRelease`, `publishRelease(force)`, `archiveRelease` |
|
||||
|
||||
### Subscriptions
|
||||
|
||||
| Subscription | Se emite cuando |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `issueChanged(projectId)` | Se crea o cambia cualquier ticket del proyecto (incluye el ticket completo y `action` = nombre del evento) |
|
||||
| `commentChanged(issueId)` | Se añade, edita o borra un comentario (`comment` es `null` al borrar) |
|
||||
| `activityAdded(projectId)` | Hay una nueva entrada en el feed |
|
||||
| `releaseChanged(projectId)` | Cambia una release |
|
||||
| `projectChanged(projectId)` | Cambian los datos o los miembros del proyecto |
|
||||
| `myProjectsChanged` | Me añaden a un proyecto o me quitan de uno |
|
||||
|
||||
Solo los miembros pueden suscribirse a un proyecto; las conexiones sin token válido se cierran con el código 4403.
|
||||
|
||||
### Ejemplos
|
||||
|
||||
```graphql
|
||||
mutation {
|
||||
createProject(input: { key: "SHOP", name: "Checkout revamp" }) {
|
||||
id
|
||||
key
|
||||
version
|
||||
}
|
||||
}
|
||||
|
||||
mutation {
|
||||
createIssue(input: { projectId: "…", type: BUG, title: "El botón de pagar no responde en Safari", area: FRONTEND, priority: CRITICAL, assigneeId: "102", labels: ["safari"] }) {
|
||||
id
|
||||
key
|
||||
version
|
||||
}
|
||||
}
|
||||
|
||||
mutation {
|
||||
changeIssueStatus(input: { issueId: "…", status: QA_FAILED, reason: "Sigue fallando en Safari 17" }) {
|
||||
version
|
||||
}
|
||||
}
|
||||
|
||||
mutation {
|
||||
linkIssues(input: { issueId: "<FE>", type: DEPENDS_ON, targetIssueId: "<BE>" }) {
|
||||
version
|
||||
}
|
||||
}
|
||||
|
||||
query {
|
||||
project(idOrKey: "SHOP") {
|
||||
stats {
|
||||
total
|
||||
open
|
||||
byStatus {
|
||||
key
|
||||
count
|
||||
}
|
||||
byAssignee {
|
||||
user {
|
||||
name
|
||||
}
|
||||
count
|
||||
}
|
||||
}
|
||||
board {
|
||||
status
|
||||
total
|
||||
issues {
|
||||
key
|
||||
title
|
||||
assignee {
|
||||
name
|
||||
}
|
||||
}
|
||||
}
|
||||
releases {
|
||||
name
|
||||
status
|
||||
progress {
|
||||
percent
|
||||
}
|
||||
}
|
||||
}
|
||||
issue(idOrKey: "SHOP-1") {
|
||||
status
|
||||
allowedTransitions
|
||||
links {
|
||||
type
|
||||
direction
|
||||
issueKey
|
||||
}
|
||||
comments {
|
||||
items {
|
||||
author {
|
||||
name
|
||||
}
|
||||
body
|
||||
}
|
||||
}
|
||||
history {
|
||||
summary
|
||||
occurredAt
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
import { createClient } from 'graphql-ws';
|
||||
|
||||
const client = createClient({
|
||||
url: 'ws://localhost:3000/graphql',
|
||||
connectionParams: { authorization: `Bearer ${token}` },
|
||||
});
|
||||
|
||||
client.subscribe(
|
||||
{
|
||||
query: 'subscription($p: ID!) { issueChanged(projectId: $p) { action version issue { key status } } }',
|
||||
variables: { p: projectId },
|
||||
},
|
||||
{ next: console.log, error: console.error, complete: () => {} },
|
||||
);
|
||||
```
|
||||
|
||||
### Errores
|
||||
|
||||
Los errores de dominio llegan como errores GraphQL con `extensions.code`:
|
||||
|
||||
| Código | Significado |
|
||||
| ----------------- | -------------------------------------------------------------- |
|
||||
| `UNAUTHENTICATED` | Falta el token o Pireon lo rechaza |
|
||||
| `NOT_FOUND` | No existe o no eres miembro |
|
||||
| `FORBIDDEN` | No tienes permiso (p. ej. un `VIEWER` modificando) |
|
||||
| `VALIDATION` | Datos inválidos (clave de proyecto, URL de Figma…) |
|
||||
| `BUSINESS_RULE` | Regla de negocio (transición no permitida, release bloqueada…) |
|
||||
| `CONFLICT` | Otro cambio llegó antes (concurrencia optimista): reintenta |
|
||||
|
||||
## 3.3 REST
|
||||
|
||||
| Endpoint | Uso |
|
||||
| --------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `GET /api/health` | Estado de PostgreSQL, MongoDB y Redis (público) |
|
||||
| `GET /api/auth/config` | Configuración para iniciar sesión con Pireon desde el navegador (público) |
|
||||
| `POST /api/auth/token` | Proxy de `/oauth/token` de Pireon: `authorization_code`, `password` y `refresh_token` (público) |
|
||||
| `POST /api/webhooks/pireon` | Webhooks de Pireon firmados con HMAC (`user.deactivated`, `token.revoked`) |
|
||||
|
||||
Ver [Autenticación](05-autenticacion.md).
|
||||
Reference in New Issue
Block a user