fsm-saas-platform

Files (1)

• SKILL.md

SKILL.md (first lines)

# FSM SaaS Platform — Contexto Completo

Eres el agente de desarrollo de la plataforma FSM SaaS (SifAgent), una aplicación multi-tenant de gestión de servicios en campo y servicios en local, dirigida a PYMEs en Colombia.

**Usa este skill cuando trabajes en cualquier aspecto de la plataforma FSM:** frontend (Angular/Ionic), backend (Lambda/Node), infraestructura (CDK), diseño de UI, flujos de negocio, o cualquier decisión técnica relacionada.

---

## 1. Visión General

| Aspecto | Detalle |
|---------|---------|
| Producto | Plataforma SaaS de Field Service Management |
| Dominio | `app.sifagent.co` |
| Mercado | Colombia (COP, DIAN, Wompi) |
| Target | PYMEs de mantenimiento y servicios |
| Flujos | Campo (Field Service) + Local (In-House) |
| Estado backend | 100% implementado (32 Lambdas, 178 endpoints, 119 tests) |
| Estado frontend | Pendiente implementación |

---

## 2. Arquitectura Técnica

### Stack Backend (Implementado)
- **Runtime:** Node.js + TypeScript
- **API:** API Gateway HTTP (REST, `/v1/*`)
- **Auth:** AWS Cognito (4 Lambda triggers: pre-signup, post-confirmation, pre-token, custom-message)
- **DB:** 16 tablas DynamoDB + 30+ GSIs
- **Compute:** 32 Lambda functions
- **Eventos:** EventBridge (12 reglas) + 2 Step Functions
- **Storage:** S3 (media, frontend assets)
- **CDN:** CloudFront (2 distributions)
- **Email:** SES (domain identity + DKIM)
- **PDF:** @react-pdf/renderer via Step Function
- **Pagos:** Wompi (tokenized 3RI, cobro automático diario)
- **Facturación:** DIAN electrónica via Alegra/Siigo (multi-proveedor)
- **Notificaciones:** FCM push + WhatsApp Meta Cloud API + SES email
- **Infra como código:** 10 CDK stacks

### Stack Frontend (Por implementar)

| App | Framework | Puerto | Usuarios |
|-----|-----------|--------|----------|
| Web Admin (`fsm-web`) | Angular 18.2 + TailwindCSS 3.4 | 4200 | Admin, Coordinador |
| App Móvil (`fsm-mobile`) | Ionic 8.8 + Angular 18.2 + Capacitor 8.5 | 8100 | Técnico |
| Platform Admin (`fsm-platform-admin`) | Angular 18.2 + TailwindCSS 3.4 | 4300 | Super admin |
| Landing (`fsm-landing`) | Astro 4.16 + Preact + TailwindCSS 3.4 | 3000 | Público |

### Tecnologías Compartidas Frontend
- Auth: AWS Amplify 6.18 (Cognito)
- Validación: Zod 3.24
- Charts: chart.js + ng2-charts
- Testing: Vitest + Testing Library + vitest-axe (accesibilidad)
- Shared package: `@fsm/shared` (tipos, constantes, utils)

---

## 3. Roles del Sistema

| Rol | Plataforma | Permisos |
|-----|-----------|----------|
| `admin` | Web | Todo: configuración, equipo, reportes, finanzas |
| `coordinator` | Web | Crear OTs, asignar técnicos, seguimiento |
| `technician` | App Móvil | Recibir asignaciones, ejecutar, registrar evidencia |
| `platform_admin` | Platform Admin | Gestión cross-tenant, facturación, métricas globales |

---

## 4. Módulos y Endpoints

### Core (disponibles en todos los planes)

#### 4.1 Tenants — `tenant-handler` (15 endpoints)
- Config general: nombre, NIT, teléfono, plan, vertical
- Gestión de plan: Trial → Starter → Pro → Business
- VerticalConfig: checklistTemplates, reportTemplate, fieldDataSections (max 10 secciones, max 20 campos)
- Branding PDF: logo + firma empresa (presigned URL, S3)
- Execution Templates: CRUD completo + duplicado
- Suspensión/Reactivación (ADR-013)

| Método | Ruta | Roles |
|--------|------|-------|
| GET | `/v1/tenant/config` | admin, coordinator, technician |
| PUT | `/v1/tenant/config` | admin |
| PATCH | `/v1/tenant/suspend` | admin |
| PATCH | `/v1/tenant/reactivate` | admin |
| POST | `/v1/tenant/branding/logo/upload-url` | admin |
| POST | `/v1/tenant/branding/signature/upload-url` | admin |
| PUT | `/v1/tenant/branding` | admin |
| DELETE | `/v1/tenant/branding/logo` | admin |
| DELETE | `/v1/tenant/branding/signature` | admin |
| POST | `/v1/execution-templates` | admin |
| GET | `/v1/execution-templates` | admin, coordinator, technician |
| GET | `/v1/execution-templates/:templateId` | admin, coordinator |
| POST | `/v1/execution-templates/:templateId/duplicate` | admin |
| PUT | `/v1/execution-templates/:templateId` | admin |
| DELETE | `/v1/execution-templates/:templateId` | admin |

#### 4.2 Team & Technicians — `team-handler` (11 endpoints)
- Invitar usuarios por email con contraseña temporal (Cognito AdminCreateUser)
- Roles: admin, coordinator, technician
- Metadata técnico: especialidad, zona, certificación, whatsappOptIn, deviceToken
- Soft-delete (no permite si tiene OTs activas)
- Agenda por ejecutor (GSI technician-date-index)
- Comisiones (ADR-019): porcentaje, arriendo fijo, salario + comisión
- Límites: Trial 3 técnicos, Pro 10, Business ilimitado

| Método | Ruta | Roles |
|--------|------|-------|
| POST | `/v1/team/invite` | admin |
| GET | `/v1/team` | admin, coordinator |
| PUT | `/v1/team/:userId` | admin |
| DELETE | `/v1/team/:userId` | admin |
| POST | `/v1/technicians/:userId/metadata` | admin |
| GET | `/v1/technicians/:userId/metadata` | admin, coordinator |
| GET | `/v1/technicians` | admin, coordinator |
| GET | `/v1/technicians/:userId/schedule` | admin, coordinator, technician |
| PATCH | `/v1/technicians/:userId/whatsapp-optin` | admin, technician |

From holmart/hermesBackup, MIT.

More from holmart/hermesBackup