Sobre o projeto

Este repositório é uma plataforma de trabalho de e-commerce voltada à operação real, e não apenas um painel de dados. O sistema suporta simultaneamente vendas internas, comércio exterior, cadeia de suprimentos, estoque, logística, finanças e fechamento mensal, e conecta os módulos por meio de uma base unificada de dados de negócios e itens financeiros. As principais entradas de trabalho estão divididas em três partes: mesa de trabalho de vendas internas (visão geral operacional, central de vendas, mercadorias básicas, central de estoque, central de cadeia de suprimentos, logística de entrega expressa, central financeira), mesa de trabalho de comércio exterior (visão geral de comércio exterior, pedidos de comércio exterior, clientes e distribuidores B2B, gestão de canais, mapeamento de SKU no exterior, embarque internacional Shipment, finanças de comércio exterior, negócios Alsvid) e uma central financeira independente. A central financeira usa a entidade da empresa como primeira dimensão e o escopo de negócios como segunda dimensão. A entidade padrão é a empresa de Zhejiang, com extensões reservadas para entidades da Áustria, Alemanha e Hong Kong, sem necessidade de refazer o sistema financeiro. O modelo central é FinanceEntry, que abrange entidade da empresa, escopo de negócios, módulo de origem e número do documento, categoria financeira, receitas e despesas, moeda, valor e imposto, previsto e real, status de liquidação, status de fatura, período contábil, além de dimensões como impacto no caixa e no lucro. Caixa e lucro são tratados separadamente; por exemplo, o IVA de importação dedutível afeta o caixa, mas não afeta diretamente o lucro, e o custo das mercadorias do Shipment afeta o lucro, mas não duplica o cálculo do caixa de pagamento de compras. Em relação aos fluxos de negócios, as vendas internas consolidam pedidos de venda, reembolsos pós-venda, custo de vendas, contas a pagar de entrada de compras, estimativas de logística de entrega expressa e reconciliação de faturas reais no FinanceEntry; o comércio exterior flui na ordem de pedidos de comércio exterior, documentos de embarque Shipment, exportação da China, transporte internacional, desembaraço de importação na UE, entrega final no exterior, itens financeiros e fechamento mensal. O Shipment pode registrar entidades de exportação e importação, responsável pela importação, número de rastreamento do contêiner no conhecimento de embarque, desembaraço de exportação e importação, tarifas normais, direitos antidumping, direitos compensatórios, IVA de importação, taxas portuárias de desembaraço e entrega final, restituição de impostos de exportação e custos previstos e reais. As taxas de importação entram nas finanças da entidade correspondente somente quando a entidade da nossa parte assume a responsabilidade pela importação. A central de fechamento mensal alterna por entidade da empresa, lê diretamente o banco de dados de negócios e oferece verificação de integridade dos dados de negócios, verificação de valores de vendas e custos, detalhes e comprovantes de transações bancárias, receita sem fatura, resumo financeiro de comércio exterior, empacotamento ZIP mensal, envio de e-mail financeiro e arquivamento de versões históricas. Se um SKU de venda não tiver custo de entrada de compra, o sistema indica claramente o SKU ausente, em vez de gerar lucro incorreto com custos fictícios. As fontes de dados externas atualmente suportadas ou reservadas incluem Jikeyun, 1688, importação de arquivos do Zhejiang Rural Credit, listas de faturas fiscais, e-mail financeiro via SMTP, além de canais de comércio exterior e integração futura com Shopify; sistemas externos não configurados são exibidos fielmente como não configurados, sem usar dados simulados para fingir conexões reais. A pilha técnica do backend é Python 3.12, FastAPI, SQLAlchemy 2, Alembic, Pydantic, PostgreSQL, Celery e Redis; o frontend é Next.js 16, React 19, Tailwind CSS 4, com exportação estática e hospedagem na mesma porta do FastAPI. A porta de serviço padrão é 127.0.0.1:8000, e PostgreSQL e Redis não ficam expostos à internet pública. O principal ambiente de desenvolvimento e aceitação atual é execução nativa local em Mac; a implantação em NAS e Zspace está adiada, e as configurações de conteinerização e publicação são mantidas. O fluxo de desenvolvimento adota o modo de commit direto: alterações diárias são enviadas e publicadas diretamente na develop, a CI é acionada por push e a main é a linha principal de lançamento formal. O repositório fornece comandos make para verificação de status, reinicialização, reconstrução do frontend, migrações Alembic, testes do backend, verificação de tipos do frontend, aceitação completa local e backup. O princípio de persistência enfatiza a separação entre código, banco de dados, arquivos de negócios, backups e logs, por meio das configurações PERSIST_ROOT, DATA_DIR, BACKUP_DIR e LOG_DIR, para evitar que atualizações do Git ou trocas de branch sobrescrevam dados de negócios. Os princípios de segurança incluem não enviar .env ao Git, não expor banco de dados e cache à internet pública, não expor a porta 8000 à internet pública durante o desenvolvimento, sincronizar no 1688 apenas compras já realizadas sem fazer pedidos ou pagamentos automáticos, manter versões dos materiais financeiros originais, exigir Alembic para alterações na estrutura do banco de dados e fazer backup antes de ajustes estruturais maiores. A atualização do sistema suporta modo nativo e identificação de identidade de lançamento em contêiner, verificando branch do Git e remoto, estado da área de trabalho, ambiente Python e Node, Alembic, capacidade de backup, artefatos do frontend, verificação de saúde e espaço em disco.