Skip to content

Documentación Jean d'Arc

Convenciones de Código

Principios Generales

Claridad sobre brevedad — Código legible > código corto
Consistencia — Seguir patrones existentes
Explícito > Implícito — Nombrar claramente, evitar magia
Fail fast — Validar temprano, fallar con mensajes claros

TypeScript (Orchestrator)

Naming

Elemento	Convención	Ejemplo
Archivos	PascalCase para clases, camelCase para utils	`PayrollService.ts`, `dateUtils.ts`
Clases	PascalCase	`ContractRepository`
Interfaces	PascalCase con prefijo I opcional	`ServiceContext` o `IServiceContext`
Funciones	camelCase	`calculateGrossPay()`
Constantes	UPPER_SNAKE_CASE	`MAX_RETRIES`
Variables	camelCase	`totalAmount`

Estructura de Servicios

// Patrón estándar de servicio
export class ExampleService extends BaseService {
  constructor(
    protected readonly repo: ExampleRepository,
    protected readonly logger: Logger,
  ) {
    super();
  }

  async execute(ctx: ServiceContext): Promise<ServiceResult<T>> {
    // 1. Validación
    // 2. Lógica de negocio
    // 3. Retorno estandarizado
  }
}

Imports

// Orden de imports:
// 1. Node.js built-ins
import { Pool } from "pg";

// 2. Dependencias externas
import express from "express";

// 3. Alias internos (@/)
import { getTenantPool } from "@/lib/db";

// 4. Imports relativos
import { ExampleRepository } from "./ExampleRepository";

SQL / PostgreSQL

Naming

Elemento	Convención	Ejemplo
Tablas	snake_case, plural	`contratos`, `empleados`
Columnas	snake_case	`fecha_inicio`, `monto_bruto`
Schemas	snake_case con prefijo	`tenant_empresa`, `parametros`
Índices	`idx_tabla_columna`	`idx_contratos_empleado_id`
Foreign Keys	`fk_tabla_referencia`	`fk_contratos_empleados`

Queries

-- Usar aliases descriptivos
SELECT
    c.id,
    c.fecha_inicio,
    e.nombres
FROM contratos c
INNER JOIN empleados e ON e.id = c.empleado_id
WHERE c.activo = true;

Frontend (Sevastopol)

Componentes

Tipo	Ubicación	Naming
Layouts	`src/layouts/`	`BaseLayout.astro`
Pages	`src/pages/`	`index.astro`, `[slug].astro`
Islands	`src/islands/`	`PayrollIsland.tsx`
UI Components	`src/components/ui/`	`Button.tsx`, `Modal.tsx`

Islands (SolidJS)

// Patrón de ViewIsland
export function ExampleIsland() {
  const [data, setData] = createSignal<T[]>([]);
  const [loading, setLoading] = createSignal(true);

  onMount(async () => {
    const result = await fetchData();
    setData(result);
    setLoading(false);
  });

  return (
    <Show when={!loading()} fallback={<Spinner />}>
      <DataTable data={data()} />
    </Show>
  );
}

Git

Commits

<tipo>(<scope>): <descripción corta>

[cuerpo opcional]

[footer opcional]

Tipo	Uso
`feat`	Nueva funcionalidad
`fix`	Corrección de bug
`docs`	Documentación
`refactor`	Refactorización sin cambio funcional
`test`	Tests
`chore`	Mantenimiento, deps, config

Ejemplo:

feat(payroll): add vacation calculation to gross pay

- Implements vacation proportional calculation
- Adds unit tests for edge cases

Closes #123

Branches

Patrón	Uso
`main`	Producción
`develop`	Integración
`feature/<nombre>`	Nueva funcionalidad
`fix/<nombre>`	Corrección
`docs/<nombre>`	Documentación

Documentación (Jean d’Arc)

Frontmatter Obligatorio

---
title: Título de la Página
description: Descripción breve para SEO
sidebar:
  label: Label en sidebar
  order: 1
updated: 2026-01-18
---

Headings

Usar ## como heading principal (nunca #)
Jerarquía: ## → ### → ####

Componentes

Usar componentes Starlight cuando sea apropiado:

<Aside> para notas, tips, warnings
<Tabs> para alternativas
<Steps> para procedimientos
<CardGrid> para navegación