Sobre el proyecto

Este repositorio es una plataforma de trabajo de comercio electrónico orientada a la operación real, no un simple panel de visualización de datos. El sistema soporta simultáneamente ventas nacionales, comercio exterior, cadena de suministro, inventario, logística, finanzas y cierre mensual, y conecta los distintos módulos mediante una base unificada de datos de negocio y asientos financieros. Las principales entradas de trabajo se dividen en tres partes: el espacio de trabajo de ventas nacionales (resumen de operación, centro de ventas, productos básicos, centro de inventario, centro de cadena de suministro, logística de mensajería, centro financiero), el espacio de trabajo de comercio exterior (resumen de comercio exterior, pedidos de comercio exterior, clientes y distribuidores B2B, gestión de canales, mapeo de SKU en el extranjero, envíos internacionales Shipment, finanzas de comercio exterior, negocio Alsvid) y un centro financiero independiente. El centro financiero toma la entidad de la empresa como primera dimensión y el ámbito de negocio como segunda dimensión. La entidad predeterminada es la empresa de Zhejiang, con extensiones reservadas para entidades de Austria, Alemania y Hong Kong, sin necesidad de rehacer el sistema financiero. El modelo central es FinanceEntry, que abarca la entidad de la empresa, el ámbito de negocio, el módulo de origen y el número de documento, la categoría financiera, ingresos y gastos, moneda, importe e impuestos, valores estimados y reales, estado de liquidación, estado de factura, período contable, así como dimensiones sobre si afecta al efectivo y al beneficio. El efectivo y el beneficio se tratan por separado; por ejemplo, el IVA de importación deducible afecta al efectivo pero no directamente al beneficio, y el coste de las mercancías del Shipment afecta al beneficio pero no duplica el cálculo del efectivo de pago de compras. En cuanto a las cadenas de negocio, las ventas nacionales integran en FinanceEntry los pedidos de venta, reembolsos por devoluciones, costes de venta, cuentas por pagar de entradas de compras, facturas estimadas de logística de mensajería y conciliación de facturas reales; el comercio exterior fluye en el orden de pedidos de comercio exterior, documentos de envío Shipment, exportación desde China, transporte internacional, despacho de importación en la UE, entrega final en el extranjero, asientos financieros y cierre mensual. El Shipment puede registrar las entidades de la empresa de exportación e importación, la parte responsable de la importación, el número de contenedor y seguimiento del conocimiento de embarque, los despachos de exportación e importación, aranceles ordinarios, derechos antidumping, derechos compensatorios, IVA de importación, gastos portuarios de despacho y entrega final, devolución de impuestos a la exportación y costes estimados y reales. Los impuestos de importación solo entran en las finanzas de la entidad correspondiente cuando nuestra entidad asume la responsabilidad de la importación. El centro de cierre mensual cambia según la entidad de la empresa, lee directamente la base de datos de negocio y ofrece verificación de integridad de los datos de negocio, comprobación de importes de venta y costes, detalles y comprobantes de transacciones bancarias, ingresos sin factura, resumen financiero de comercio exterior, empaquetado ZIP mensual, envío de correos financieros y archivado de versiones históricas. Si un SKU de venta carece de coste de entrada de compra, el sistema indica claramente los SKU faltantes en lugar de generar beneficios erróneos con costes ficticios. Las fuentes de datos externas actualmente soportadas o reservadas incluyen Jikeyun, 1688, importación de archivos de Zhejiang Rural Credit, listas de facturas fiscales, correo financiero SMTP, así como la futura integración de canales de comercio exterior y Shopify; los sistemas externos no configurados se muestran fielmente como no configurados, sin usar datos simulados para fingir conexiones reales. La pila tecnológica del backend es Python 3.12, FastAPI, SQLAlchemy 2, Alembic, Pydantic, PostgreSQL, Celery y Redis; el frontend es Next.js 16, React 19, Tailwind CSS 4, con exportación estática y alojado por FastAPI en el mismo puerto. El puerto de servicio predeterminado es 127.0.0.1:8000, y PostgreSQL y Redis no están expuestos a la red pública. El entorno principal de desarrollo y aceptación actual es la ejecución nativa local en Mac; el despliegue en NAS y Zspace está temporalmente en pausa, y se conservan la configuración de contenedores y publicación. El flujo de desarrollo adopta el modo de envío directo: los cambios diarios se confirman y envían directamente a develop, la CI se activa mediante push y main es la línea principal de publicación formal. El repositorio proporciona comandos make para ver el estado, reiniciar, reconstruir el frontend, migraciones de Alembic, pruebas del backend, comprobación de tipos del frontend, aceptación completa local y copias de seguridad. El principio de persistencia enfatiza la separación entre código, base de datos, archivos de negocio, copias de seguridad y registros, configurados mediante PERSIST_ROOT, DATA_DIR, BACKUP_DIR y LOG_DIR, para evitar que las actualizaciones de Git o los cambios de rama sobrescriban los datos de negocio. Los principios de seguridad incluyen no confirmar .env en Git, no abrir la base de datos y la caché a la red pública, no exponer el puerto 8000 a la red pública durante el desarrollo, sincronizar 1688 solo para compras ya realizadas sin realizar pedidos ni pagos automáticos, conservar versiones de los materiales financieros originales, realizar los cambios de estructura de la base de datos obligatoriamente mediante Alembic y hacer copias de seguridad antes de ajustes estructurales importantes. La actualización del sistema admite el modo nativo y la identificación de publicación en contenedores, y comprueba la rama de Git y el remoto, el estado del espacio de trabajo, los entornos de Python y Node, Alembic, la capacidad de copia de seguridad, los artefactos del frontend, las comprobaciones de salud y el espacio en disco.