docs: ledger de contrato al día con B2B 1.5.0 / admin 1.1.0 - #1
Open
LucasLeguizamo wants to merge 1 commit into
Open
docs: ledger de contrato al día con B2B 1.5.0 / admin 1.1.0#1LucasLeguizamo wants to merge 1 commit into
LucasLeguizamo wants to merge 1 commit into
Conversation
PR Summary by QodoUpdate CONTRACT-GAPS ledger for B2B 1.5.0 and Admin 1.1.0
AI Description
Diagram
High-Level Assessment
Files changed (1)
|
Code Review by Qodo
1. CONTRACT-GAPS.md not in English
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+33
to
+34
| | Update endpoints sin `requestBody` en el spec — el mcp no podía tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedaban fuera de la Ola B. **Resuelto en el contrato 1.5.0**: los cinco schemas existen y el mcp los expone (v0.12.0) | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate` | B2B | mcp ✓ | — | shipped | | ||
| | API key de servicio self-service — un cron server-side (Vercel) no puede usar el device flow interactivo, y no había forma de acuñar una `ft_live_…` sin entrar al backend | `GET/POST/DELETE /api-keys` (scope `read`/`write`, `expiresAt`, el plano solo en la respuesta de creación) | B2B | cli ✓ (`ft api-keys`), mcp ✓ (solo list) | [freeticket-cli#29](https://github.com/AppFreeticket/freeticket-cli/issues/29) | shipped | |
There was a problem hiding this comment.
1. contract-gaps.md not in english 📘 Rule violation ⚙ Maintainability
The PR adds/updates technical documentation content in Spanish, but repository documentation must be written in English. This breaks the repo’s documentation language/locale convention and reduces consistency for the intended audience.
Agent Prompt
## Issue description
Technical documentation updates in `CONTRACT-GAPS.md` are written in Spanish, but repo documentation must be in English.
## Issue Context
Per the documentation language/locale convention, technical documentation should be English (end-user copy may be neutral Spanish).
## Fix Focus Areas
- CONTRACT-GAPS.md[33-39]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
|
|
||
| | Authorization server OAuth 2.1 para el MCP remoto — claude.ai exige OAuth para connectors con credenciales. Resuelto **embebiendo el AS en el propio mcp** (v0.10.0): tokens stateless que sellan API key + workspace + sesión admin; no requirió endpoint nuevo en free-admin. `FT_OAUTH_ISSUER` permite delegar a un AS de free-admin si algún día existe | `/.well-known/oauth-authorization-server` (RFC 8414), dynamic client registration (RFC 7591), `/authorize` + `/token` con PKCE y página de consentimiento — todo servido por el mcp | B2B | mcp ✓ | — | shipped | | ||
| | Update endpoints sin `requestBody` en el spec — el mcp no puede tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedan fuera de la Ola B | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — declarar `requestBody` (schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate`) | B2B | mcp | — | identified | | ||
| | Update endpoints sin `requestBody` en el spec — el mcp no podía tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedaban fuera de la Ola B. **Resuelto en el contrato 1.5.0**: los cinco schemas existen y el mcp los expone (v0.12.0) | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate` | B2B | mcp ✓ | — | shipped | |
There was a problem hiding this comment.
2. Roadmap quedó desactualizado 🐞 Bug ⚙ Maintainability
CONTRACT-GAPS.md marca como shipped el gap de updates sin requestBody, pero ROADMAP-AI-FIRST.md todavía deja event_dates_create/update, ticket_types_update, plans_update y venues_update como pendientes por ese mismo gap. Esto introduce drift de documentación y puede llevar a trabajo duplicado o a creer que la Ola B sigue bloqueada.
Agent Prompt
### Issue description
El roadmap sigue afirmando que varios tools están bloqueados por el gap “sin requestBody”, pero el ledger ya lo marcó `shipped`.
### Issue Context
El PR cambia el estado del gap a `shipped` en `CONTRACT-GAPS.md`, pero no actualiza el roadmap donde esos items figuran como pendientes.
### Fix Focus Areas
- ROADMAP-AI-FIRST.md[75-103]
- CONTRACT-GAPS.md[33-33]
### Suggested change
- Marcar como completados (`[x]`) los items `event_dates_create`, `event_dates_update`, `ticket_types_update`, `plans_update`, `venues_update`.
- Remover la nota “hueco de contrato (sin requestBody)” o reemplazarla por una nota histórica (opcional) que apunte al contrato 1.5.0.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| | Update endpoints sin `requestBody` en el spec — el mcp no puede tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedan fuera de la Ola B | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — declarar `requestBody` (schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate`) | B2B | mcp | — | identified | | ||
| | Update endpoints sin `requestBody` en el spec — el mcp no podía tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedaban fuera de la Ola B. **Resuelto en el contrato 1.5.0**: los cinco schemas existen y el mcp los expone (v0.12.0) | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate` | B2B | mcp ✓ | — | shipped | | ||
| | API key de servicio self-service — un cron server-side (Vercel) no puede usar el device flow interactivo, y no había forma de acuñar una `ft_live_…` sin entrar al backend | `GET/POST/DELETE /api-keys` (scope `read`/`write`, `expiresAt`, el plano solo en la respuesta de creación) | B2B | cli ✓ (`ft api-keys`), mcp ✓ (solo list) | [freeticket-cli#29](https://github.com/AppFreeticket/freeticket-cli/issues/29) | shipped | | ||
| | Service token de plataforma para `ft admin` headless — el superadmin solo tenía la cookie de sesión del browser | `GET/POST/DELETE /api/admin/tokens` | Admin | cli ✓ (`ft admin tokens`), mcp ✓ (solo list) | — | shipped | |
There was a problem hiding this comment.
3. Paths admin con prefijo mixto 🐞 Bug ⚙ Maintainability
En el ledger se documentan endpoints admin con prefijo /api/admin mientras el resto de docs usa
paths relativos al contrato (p.ej. /workspaces/{id}). Esta mezcla hace ambiguo si se está listando
el path del spec o la URL completa del backend.
Agent Prompt
### Issue description
El ledger mezcla notación de paths: algunas filas admin usan `/api/admin/...` y otras docs (roadmap) usan `/...` relativo al spec.
### Issue Context
Para evitar confusiones (especialmente al pedir endpoints vía `endpoint-requester`), conviene tener una única convención: o siempre paths relativos al contrato, o siempre URLs con prefijo.
### Fix Focus Areas
- CONTRACT-GAPS.md[35-39]
- ROADMAP-AI-FIRST.md[137-141]
### Suggested change
- Elegir una convención y aplicarla consistentemente:
- **Opción A (recomendada):** paths relativos al contrato (sin `/api/admin`), ej. `GET/POST/DELETE /tokens`, `PATCH /workspaces/{id}`, `POST /workspaces/{id}/plan`.
- **Opción B:** mantener prefijo en todas las filas admin y documentar explícitamente la base (`/api/admin`) en el encabezado/nota del ledger.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| | Authorization server OAuth 2.1 para el MCP remoto — claude.ai exige OAuth para connectors con credenciales. Resuelto **embebiendo el AS en el propio mcp** (v0.10.0): tokens stateless que sellan API key + workspace + sesión admin; no requirió endpoint nuevo en free-admin. `FT_OAUTH_ISSUER` permite delegar a un AS de free-admin si algún día existe | `/.well-known/oauth-authorization-server` (RFC 8414), dynamic client registration (RFC 7591), `/authorize` + `/token` con PKCE y página de consentimiento — todo servido por el mcp | B2B | mcp ✓ | — | shipped | | ||
| | Update endpoints sin `requestBody` en el spec — el mcp no puede tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedan fuera de la Ola B | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — declarar `requestBody` (schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate`) | B2B | mcp | — | identified | | ||
| | Update endpoints sin `requestBody` en el spec — el mcp no podía tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedaban fuera de la Ola B. **Resuelto en el contrato 1.5.0**: los cinco schemas existen y el mcp los expone (v0.12.0) | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate` | B2B | mcp ✓ | — | shipped | | ||
| | API key de servicio self-service — un cron server-side (Vercel) no puede usar el device flow interactivo, y no había forma de acuñar una `ft_live_…` sin entrar al backend | `GET/POST/DELETE /api-keys` (scope `read`/`write`, `expiresAt`, el plano solo en la respuesta de creación) | B2B | cli ✓ (`ft api-keys`), mcp ✓ (solo list) | [freeticket-cli#29](https://github.com/AppFreeticket/freeticket-cli/issues/29) | shipped | |
There was a problem hiding this comment.
4. Columna de issues ambigua 🐞 Bug ⚙ Maintainability
La tabla define la 5ª columna como “Issue free-admin”, pero se agregaron filas que enlazan issues de freeticket-cli en esa columna. Esto rompe la semántica declarada del ledger y el workflow descrito por endpoint-requester (gap ↔ issue en free-admin).
Agent Prompt
### Issue description
La columna “Issue free-admin” ahora contiene links a issues de otros repos (p.ej. freeticket-cli), lo que vuelve el ledger ambiguo para el proceso de `endpoint-requester`.
### Issue Context
`endpoint-requester` documenta explícitamente la tabla con la columna “Issue free-admin” y el cruce de enlaces con issues en `AppFreeticket/free-admin`.
### Fix Focus Areas
- CONTRACT-GAPS.md[15-16]
- CONTRACT-GAPS.md[34-38]
- .claude/agents/endpoint-requester.md[76-84]
### Suggested change
- **Opción A (mínimo cambio):** mantener la columna como “Issue free-admin” y mover los links de CLI a la columna “Cliente” o al texto de “Funcionalidad”, dejando `—` en la columna de free-admin cuando no aplique.
- **Opción B (más claro):** renombrar la columna a “Issue/Tracking” (o agregar una columna adicional para “Issue cliente”) y actualizar la plantilla en `endpoint-requester.md` para reflejar la nueva estructura.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Shipped: los 5 updates que no declaraban requestBody (desbloquean la Ola B del
mcp), api-keys self-service, tokens de plataforma, y liquidaciones
(/settlements + /reports/financials).
Nuevos huecos anotados, los tres verificados contra el spec en vivo:
- PDF de comprobante de liquidación: hay hasDocument y fileName, no URL de
descarga. El archivo sigue siendo solo del panel.
- GET /staff sin batch cross-workspace: N+1 real; el fan-out del mcp tapa el
síntoma pero siguen siendo N round trips.
- Onboarding enterprise: PATCH /api/admin/workspaces/{id} no acepta webTemplate
ni customDomain, y no existe la asignación manual de plan.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
LucasLeguizamo
force-pushed
the
docs/contract-gaps-1.5
branch
from
August 3, 2026 23:01
860c7c4 to
fa0972c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Revisión del contrato en vivo contra lo que tenían commiteado los clientes. Cuatro filas pasan a
shippedy se anotan tres huecos nuevos, los tres verificados contra el spec (no supuestos).Shipped
requestBodyPOST/PATCH /events/{id}/dates,PATCH /ticket-types/{id},/membership-plans/{id},/venues/{id}GET/POST/DELETE /api-keysft api-keys(ya en 0.8.0) — cierra cli#29GET/POST/DELETE /api/admin/tokensft admin tokens— saca aft adminde pasear la cookie de sesiónGET /settlements,GET /reports/financialsft settlements list,ft reports financials— avanza cli#32Huecos nuevos
hasDocumenty losfileName, pero no una URL de descarga — la propia descripción del endpoint dice que los archivos se bajan del panel. Bloquea archivar el comprobante junto al resto de la documentación financiera.GET /staffsin batch cross-workspace. Sigue aceptando sololimit/cursory scopeando porX-Workspace-Id: N workspaces = N round trips. El modo global del mcp (workspace: "all") tapa el síntoma orquestando el fan-out, pero el costo de red no cambia — que es justo lo que duele en cold start serverless.AdminWorkspaceUpdatesigue enname/slug/type/isPublished; no haywebTemplate,customDomainni asignación manual de plan.ft admin enterpriseno se puede construir sin inventar contrato, así que no se construye.Los punteros de submódulo se actualizan cuando mergeen los PRs de cli/mcp/skills.
🤖 Generated with Claude Code