Convenciones de ingeniería

Estructura fuente

Utilice identificadores, comentarios, documentación y mensajes de confirmación en inglés. Los proyectos de TypeScript utilizan una verificación estricta; Las interfaces públicas deben preservar tipos explícitos y decodificar valores externos en lugar de propagar datos no verificados. Los manifiestos de paquete exponen puntos de entrada de origen y los módulos de aplicación utilizan importaciones relativas apropiadas para su herramienta de compilación.

Las funciones de escritorio agrupan pantallas, componentes, tiendas y ayudantes en apps/desktop/src/features. Los adaptadores de ruta permanecen en src/pages, mientras que el shell de la aplicación y la configuración del cliente residen en src/app. La geometría central permanece independiente del estado de la interfaz de usuario y del acceso a la base de datos.

Geometría y unidades de salida.

La geometría de entidades analíticas y vectores centrales utiliza milímetros y radianes. La ubicación de escenas, los controles de funciones y los campos de eje giratorio CAM tienen convenciones de ángulos específicas del contrato, incluidos los grados. Siga cada esquema al adaptarse entre ellos. La conversión de visualización de la interfaz de usuario pertenece al límite de visualización. Las operaciones de mecanizado utilizan además parámetros de avance, husillo, profundidad y espacio libre con significados definidos por sus esquemas; un número simple nunca debería adquirir una unidad implícita solo a partir de una etiqueta.

G-code publica su propia conversión de salida y formato de números específicos del controlador. El emisor compartido expone formatNumber, redondea al recuento decimal solicitado, normaliza el cero negativo y realiza un seguimiento de la posición emitida. El formato del feed puede omitir una parte fraccionaria para valores integrales. Utilice el emisor en lugar de formatear de forma independiente las palabras de movimiento en cada interlocutor.

Mantenga distintas la evidencia del modelo y la geometría de visualización aproximada. Una superficie teselada es útil para renderizado y análisis, pero en sí misma no demuestra que una operación B-rep exacta haya sido exitosa.

Servicios de efectos

Ampliación de servicios Context.Service y exponer métodos escritos de devolución de efectos. Una capa construye la implementación y proporciona sus dependencias. apps/sidecar/src/layers.ts es el punto de integración para repositorios, servicios, controladores, autorización y configuración de tiempo de ejecución.

Los recursos con una vida útil, como los identificadores de SQLite, se adquieren y liberan dentro del alcance de la capa propietaria. Usar Effect.try o Effect.tryPromise traducir excepciones extranjeras en errores significativos. Los nombres de operación estables en errores y seguimiento hacen que las fallas se puedan diagnosticar sin acoplar a las personas que llaman a un controlador de almacenamiento.

La composición de las capas es importante: las capas hermanas fusionadas no se proporcionan servicios entre sí automáticamente. El registro de pasos del flujo de trabajo de Sidecar se coloca en capas después del corredor que necesita; el paso de IA se registra donde el servicio de IA está disponible.

Validación y errores

Las entradas y salidas HTTP se declaran en packages/api/src/groups. Valide entradas desconocidas en esos límites. El contrato incluye errores de mensajes simples, sobres de éxito/error y algunos cuerpos de error con clave; preservar el estado declarado del punto final y la representación de la respuesta.

Los errores orientados a HTTP utilizan esquemas de efectos y anotaciones de estado. Por ejemplo, BadRequest, Unauthorized, NotFound, y Conflict están declarados en packages/api/src/errors.ts. Las fallas internas de la base de datos conllevan una operación y causan en DatabaseError. Asigne fallas internas en el límite HTTP en lugar de exponer los detalles del controlador a los clientes.

Regenerar clientes después de un cambio de contrato con bun run generate. Verifique la salida comprometida con bun run generate:check. Las carpetas generadas son salidas; La generación excluye explícitamente los puntos finales que un objetivo no puede representar.

Persistencia y configuración

Los repositorios de aplicaciones utilizan el Database servicio de @cadcamfun/db y su query(operation, run) ayudante. Cambiar packages/db/src/schema.ts antes de generar migraciones. Revisar el SQL y los metadatos generados juntos; No ejecute un experimento de esquema destructivo en la base de datos de un usuario.

El sidecar lee la configuración en apps/sidecar/src/config.ts y lo pasa por AppConfigService. Las credenciales utilizan valores redactados cuando el servicio los requiere. Mantenga los valores secretos de token y proveedor fuera de los registros, la documentación y los resultados de solución de problemas. El shell nativo proporciona su propio token de lanzamiento y rutas de almacenamiento.

La documentación Studio es una herramienta local separada con su propia selección de ruta en packages/web/script/studio-server.ts. No asuma que la ruta de su base de datos o la sesión de inicio de sesión coinciden con el escritorio en ejecución.

Verificación

bun test packages/core
bun run --filter @cadcamfun/core typecheck
bun run generate:check

# Documentation content and build
bun test packages/web/test
bun run --filter @cadcamfun/web typecheck
bun run --filter @cadcamfun/web build

Elija controles que ejerzan el límite afectado. Los cambios puros del núcleo necesitan casos de regresión numérica y geométrica. Los cambios HTTP necesitan cobertura de esquema y controlador. Los cambios en la documentación necesitan rutas válidas, anclajes, ejemplos y una construcción exitosa del sitio. Una ejecución de prueba completa del espacio de trabajo es bun run test, que incluye paquetes, aplicaciones y scripts.

Campos opcionales, nulos y valores de transporte

Se puede omitir un campo opcional. Un campo que acepta valores NULL puede contener explícitamente null. Son propiedades separadas: el contrato del proyecto exige description en las filas devueltas mientras se permite nulo, y una solicitud de creación permite la omisión de ese campo. Conserve esas distinciones al crear clientes o parchear documentos guardados.

La validación del transporte también es distinta de la validación comercial. La carga útil de creación del proyecto permite omitir un nombre en el nivel de esquema, pero el controlador devuelve 400 con Project name is required si falta o está vacío. Un tipo generado por sí solo no puede establecer que se admitirá una operación para un recurso o cuenta corriente existente.

Los parámetros de consulta HTTP son texto codificado. Utilice los campos de consulta declarados por el cliente o la codificación de URL en lugar de concatenar entradas arbitrarias del usuario en una URL. Codifique una clave o un identificador de proyecto como un segmento de ruta único y envíe tokens de portador en encabezados en lugar de enlaces copiados.

El referencia de API de proyectos muestra estos campos y códigos de estado; el recorrido capturado demuestra el resultado de la validación del controlador.

Mantener documentación ejecutable.

Escriba un ejemplo frente a la superficie pública exacta que nombra. El SDK de Promise y el cliente Effect basado en contratos completos tienen diferentes métodos/formas de entrada y cobertura. Una solicitud de generador basada en configuraciones es diferente de una solicitud de kernel nativa, y un programa generado es diferente de un registro de trayectoria de herramienta guardado.

La instantánea de referencia de API se genera a partir del contrato de aplicación. Después de cambiar un punto final, regenerarlo dentro del espacio de trabajo web con bun run generate:api-reference. Correr bun run check:api-reference para compararlo con la fuente actual. La agrupación de recursos, el texto del artículo, la navegación y la recuperación del asistente aún deben describir ese contrato fielmente.

Al documentar una respuesta capturada de una ejecución aislada, identifique cualquier ID normalizado, marcas de tiempo o campos omitidos. Etiquete las plantillas de solicitud como plantillas. No presente un identificador inventado o un ejemplo de esquema no ejecutado como una respuesta de producción observada.

Patrones de efectos utilizados en todas partes.

import { Context, Data, Effect, Layer } from "effect"
import { AppConfigService } from "../config.ts"

export class StorageError extends Data.TaggedError("StorageError")<{
  readonly operation: string
  readonly cause: unknown
}> {}

export class Storage extends Context.Service<Storage, {
  readonly read: (key: string) => Effect.Effect<Uint8Array, StorageError>
}>()("cadcamfun/Storage") {
  static readonly layer = Layer.effect(Storage, Effect.gen(function* () {
    const config = yield* AppConfigService       // dependencies come from the context
    return Storage.of({
      read: (key) => Effect.tryPromise({
        try: () => Bun.file(`${config.dataDir}/storage/${key}`).bytes(),
        catch: (cause) => new StorageError({ operation: "read", cause }),
      }),
    })
  }))
}

• Las claves de servicio tienen espacios de nombres: "cadcamfun/Database", "cadcamfun/AppConfig", "cadcamfun/ApiClient".
• Los errores son Data.TaggedError servicios internos y Schema.TaggedError con un httpApiStatus en el límite HTTP. Los controladores asignan el primero al segundo.
• Recursos con un uso de por vida Effect.acquireRelease por lo que se cierran cuando se cierra el alcance de la capa.
• Uso de funciones nombradas Effect.fn("area.name") por lo que las trazas llevan un nombre de intervalo legible, por ejemplo cam.runKernelRequest.
• La configuración se lee una vez, en AppConfigService; ningún otro módulo lee process.env en el sidecar.

Reglas de nomenclatura y diseño

En 3D