ecommerce-workspace

This repository is an e-commerce work platform built for real operations, not merely a data dashboard. The system simultaneously supports domestic sales, foreign trade, supply chain, inventory, logistics, finance, and month-end closing, and connects all modules through a unified business data and financial entry foundation. There are three main work entry points: the domestic sales workbench (business overview, sales center, basic goods, inventory center, supply chain center, express logistics, finance center), the foreign trade workbench (foreign trade overview, foreign trade orders, B2B customers and distributors, channel management, overseas SKU mapping, international shipment, foreign trade finance, Alsvid business), and a standalone finance center. The finance center uses company entity as the first dimension and business scope as the second dimension. The default entity is the Zhejiang company, with reserved expansion for Austria, Germany, Hong Kong, and other entities, without the need to rebuild the financial system. The core model is FinanceEntry, covering company entity, business scope, source module and document number, financial category, income and expense, currency, amount and tax, estimated and actual, settlement status, invoice status, accounting period, and whether it affects cash and profit. Cash and profit are handled separately. For example, deductible import VAT affects cash but does not directly affect profit, while shipment goods cost affects profit but does not double-count purchase payment cash. In terms of business flows, domestic sales consolidate sales orders, after-sale refunds, sales costs, purchase receipt payables, express logistics estimates, and actual bill reconciliation into FinanceEntry. Foreign trade flows in the order of foreign trade orders, shipment documents, China export, international transport, EU import customs clearance, overseas last-mile delivery, financial entries, and month-end closing. Shipment can record export and import company entities, import responsible party, bill of lading container tracking number, export and import customs declarations, ordinary tariffs, anti-dumping duties, countervailing duties, import VAT, customs clearance port charges and last-mile delivery, export tax rebates, and estimated and actual costs. Import taxes and fees enter the corresponding entity's finance only when our entity bears import responsibility. The month-end closing center switches by company entity, reads the business database directly, and provides business data completeness checks, sales amount and cost checks, bank transaction details and receipts, uninvoiced revenue, foreign trade finance summaries, monthly ZIP packaging, email sending of finance, and historical version archiving. If a sales SKU lacks purchase receipt cost, the system clearly prompts the missing SKU and does not generate incorrect profit using fabricated costs. External data sources currently support or reserve Jikeyun, 1688, Zhejiang Rural Credit file import, tax invoice lists, SMTP finance email, and future integration with foreign trade channels and Shopify. Unconfigured external systems are truthfully displayed as unconfigured, without using simulated data to fake real connections. The backend technology stack is Python 3.12, FastAPI, SQLAlchemy 2, Alembic, Pydantic, PostgreSQL, Celery, and Redis. The frontend is Next.js 16, React 19, and Tailwind CSS 4, using static export and hosted by FastAPI on the same port. The default service port is 127.0.0.1:8000, and PostgreSQL and Redis are not exposed to the public network. The current main development and acceptance environment is native local operation on Mac. NAS and ZSpace deployment are postponed, while containerization and release configuration are retained. The development process uses a direct commit model. Daily changes are committed and pushed directly to develop, CI is triggered by push, and main serves as the official release line. The repository provides make commands for status viewing, restart, frontend rebuild, Alembic migration, backend testing, frontend type checking, local full acceptance, and backup. The persistence principle emphasizes separation of code, database, business files, backups, and logs through PERSIST_ROOT, DATA_DIR, BACKUP_DIR, and LOG_DIR configuration, avoiding Git updates or branch switching overwriting business data. Security principles include not committing .env to Git, not exposing the database and cache to the public network, not exposing port 8000 to the public network during development, 1688 only syncing purchases that have already occurred without automatic ordering or payment, preserving versions of original financial materials, requiring Alembic for database structure changes, and making backups before larger structural adjustments. System updates support native mode and container release identity recognition, checking Git branch and remote, workspace status, Python and Node environments, Alembic, backup capability, frontend artifacts, health checks, and disk space.