Plan: Documentación completa de OmniBuy — Docusaurus
Contexto
El proyecto tiene 157 archivos .md en el docs-site, pero:
- 28 archivos son stubs (< 50 líneas) — necesitan contenido real
- 15+ dominios de API no tienen documentación alguna
- Secciones enteras del admin panel no están documentadas
- No hay guía de deployment, arquitectura general, ni onboarding de desarrolladores
Fase 1: Contenido faltante crítico (PR 1)
1.1 Nuevos archivos de API — 15 dominios sin documentar
Crear en docs-site/docs/api/:
| # | Archivo | Fuente | Endpoints |
|---|---|---|---|
| 1 | checkout/checkout.md | internal/checkout/adapters/inbound/http/router.go | 11 endpoints (carts + checkouts) |
| 2 | fulfillment/fulfillment.md | internal/fulfillment/adapters/inbound/http/router.go | 15 endpoints (shipments, split, returns) |
| 3 | pos/pos.md | internal/pos/adapters/inbound/http/pos_handler.go | 16 endpoints (sessions, sales, printers) |
| 4 | marketplace/marketplace.md | internal/marketplace/adapters/inbound/http/ | 14 endpoints (vendors, products, payouts) |
| 5 | blog/blog.md | internal/blog/adapters/inbound/http/router.go | 7 endpoints |
| 6 | content/pages.md | internal/content/adapters/inbound/http/router.go | 7 endpoints |
| 7 | fx/fx.md | internal/fx/adapters/inbound/http/fx_handler.go | 3 endpoints |
| 8 | feature-flags/feature-flags.md | internal/featureflags/adapters/inbound/http/router.go | 5 endpoints |
| 9 | imports/imports.md | internal/imports/adapters/inbound/http/router.go | 4 endpoints |
| 10 | tenants/tenants.md | internal/tenants/adapters/inbound/http/router.go | 6 endpoints |
| 11 | partners/partners.md | internal/partners/adapters/inbound/http/router.go | 4 endpoints |
| 12 | theme-store/theme-store.md | internal/themestore/adapters/inbound/http/ | 5 endpoints |
| 13 | attribution/attribution.md | internal/attribution/adapters/inbound/http/ | 1 endpoint |
| 14 | invoices/invoices.md | internal/invoices/adapters/inbound/http/ | 1 endpoint |
| 15 | webhooks-management/webhooks.md | internal/webhooks/adapters/inbound/http/router.go | 3 endpoints |
Cada archivo: descripción, endpoints HTTP, request/response JSON, errores, ejemplos curl.
1.2 Integraciones — expandir 5 stubs
| Archivo | Líneas actuales | Contenido a agregar |
|---|---|---|
integrations/index.md | 25 | Flujo completo, tabla de compatibilidad, arquitectura de sync |
integrations/hubspot.md | 40 | Configuración completa, campos mapeados, sync bidireccional |
integrations/salesforce.md | 35 | Configuración, mapeo, sync contacts/opportunities/products |
integrations/sap.md | 35 | Configuración, mapeo, sync orders/products/contacts |
integrations/sso.md | 30 | SAML 2.0 completo, proveedores, flujo de auth |
1.3 Stubs críticos a expandir
| Archivo | Líneas | Contenido a agregar |
|---|---|---|
guides/authentication.md | 45 | JWT completo, refresh tokens, MFA/TOTP, sesiones, impersonation |
guides/rate-limiting.md | 25 | Headers, límites por plan, manejo de 429 |
guides/idempotency.md | 16 | Header Idempotency-Key, cuándo usarlo, ejemplos |
webhooks/retries.md | 18 | Política de reintentos, backoff, dead letter queue |
api/addons/abandoned-carts.md | 30 | Flujo completo de recuperación, endpoints, eventos |
design-system/overview.md | 25 | Visión general, arquitectura de tokens, stacks soportados |
crm/index.md | 35 | Overview completo, módulos, flujo de trabajo |
1.4 Nuevas guías
| Archivo | Contenido |
|---|---|
guides/deployment.md | Docker Compose, VPS, Terraform, env vars, DB, object storage |
guides/admin-architecture.md | Stack HTMX, middleware pipeline, templates, RBAC, i18n |
guides/attribution.md | UTM tracking, canales, dashboard, export |
guides/pos.md | Sesiones, terminal, impresora, sync offline |
1.5 Nuevo: Storefront Architecture
Crear themes/conceptos/storefront-architecture.md:
- SSR 100%, Alpine.js mínimo, responsive images, performance budget, WCAG 2.1 AA
- SEO (JSON-LD, meta tags), account pages, localization
1.6 Nuevo: Template Functions Reference
Crear themes/fluid-engine/template-functions.md:
- Todas las 40+ funciones del FuncMap del renderer con ejemplos
Fase 2: Theme docs (PR 2)
2.1 Expandir 13 stubs de módulos de theme
Módulos con < 50 líneas → expandir con settings, variantes, ejemplos de código.
2.2 Nuevos: Docs por tema individual
Crear themes/temas/ con dawn.md, cielo.md, olive-luxe.md, minimal.md, bold.md
2.3 Nuevas referencias
| Archivo | Contenido |
|---|---|
themes/fluid-engine/settings-schema.md | Tipos de campo, grupos, presets |
themes/conceptos/css-architecture.md | Módulos CSS, concatenación, variables, dark mode |
themes/conceptos/section-manifest.md | sections.json, registry, cómo agregar secciones |
Fase 3: Admin + expandir existentes (PR 3)
3.1 Guía de usuario admin panel
Crear guides/admin-panel.md cubriendo todos los módulos del admin.
3.2 Expandir inbox, KB, guides existentes
inbox/templates.mdyinbox/routing.md- Nuevo
crm/knowledge-base.md - Expandir getting-started, tutorials
Verificación por PR
cd docs-site && npm run build