ecommerce-workspace

このリポジトリは、単なるデータダッシュボードではなく、実務経営向けのEC作業プラットフォームである。システムは内販、貿易、サプライチェーン、在庫、物流、財務、月次決算を同時に担い、統一された業務データと財務事項の基盤を通じて各モジュールを連携させる。 主要な作業入口は三つに分かれる。内販ワークベンチ（経営概覧、販売センター、基礎商品、在庫センター、サプライチェーンセンター、速達物流、財務センター）、貿易ワークベンチ（貿易概覧、貿易注文、B2B顧客とディーラー、チャネル管理、海外SKUマッピング、国際出荷Shipment、貿易財務、Alsvid業務）、そして独立した財務センターである。 財務センターは会社主体を第一の軸、業務範囲を第二の軸とし、デフォルト主体は浙江公司で、オーストリア、ドイツ、香港などの主体拡張を予め想定しており、財務システムを作り直す必要はない。中核モデルはFinanceEntryであり、会社主体、業務範囲、ソースモジュールと伝票番号、財務カテゴリ、収支、通貨、金額と税額、予定と実績、決済状態、請求書状態、会計期間、および現金と利益に影響するかどうかなどの次元を網羅する。現金と利益は分けて処理される。例えば、控除可能な輸入VATは現金に影響するが利益には直接影響せず、Shipmentの商品コストは利益に影響するが仕入支払の現金を重複計算しない。 業務チェーンについて、内販では販売注文、アフターセールス返金、売上原価、仕入入庫買掛金、速達物流の見積と実績請求の消込を統一的にFinanceEntryへ集約する。貿易では貿易注文、Shipment出荷伝票、中国輸出、国際輸送、EU輸入通関、海外末端配送、財務事項、月次決算の順に流れる。Shipmentは輸出と輸入の会社主体、輸入責任者、船荷証券・コンテナ番号Tracking、輸出と輸入の通関、通常関税、アンチダンピング税、相殺関税、輸入VAT、通関港雑費と末端配送、輸出還付、および予定と実績コストを記録できる。輸入税費は、当方主体が輸入責任を負う場合にのみ該当主体の財務に計上される。 月次決算センターは会社主体ごとに切り替え、業務データベースを直接読み取り、業務データ完全性チェック、売上金額とコストチェック、銀行取引明細と受領証、無票収入、貿易財務集計、月次ZIPパッケージ、財務へのメール送信、および過去バージョンのアーカイブを提供する。販売SKUに仕入入庫コストが欠けている場合、システムは欠落SKUを明確に提示し、架空のコストで誤った利益を生成しない。 外部データソースは現在、吉客云、1688、浙江農信ファイルインポート、税務請求書リスト、SMTP財務メール、および貿易チャネルとShopifyの後続接続をサポートまたは予定している。未設定の外部システムは正直に未設定と表示し、模擬データで実接続を偽装しない。 技術スタックは、バックエンドがPython 3.12、FastAPI、SQLAlchemy 2、Alembic、Pydantic、PostgreSQL、CeleryとRedis。フロントエンドはNext.js 16、React 19、Tailwind CSS 4で、静的エクスポートをFastAPIが同一ポートでホストし、デフォルトサービスポートは127.0.0.1:8000、PostgreSQLとRedisは公網に開放しない。現在の主要な開発・検収環境はMacローカルネイティブ実行で、NASと極空間のデプロイは保留、コンテナ化とリリース設定は保持している。 開発フローは直提モードを採用し、日常の変更は直接developへコミット・プッシュ、CIはpushでトリガーされ、mainが正式リリースの主線である。リポジトリは状態確認、再起動、フロントエンド再ビルド、Alembicマイグレーション、バックエンドテスト、フロントエンド型チェック、ローカル完全検収、バックアップ用のmakeコマンドを提供する。永続化原則はコード、データベース、業務ファイル、バックアップ、ログの分離を強調し、PERSIST_ROOT、DATA_DIR、BACKUP_DIR、LOG_DIRの設定を通じて、Git更新やブランチ切替が業務データを上書きするのを防ぐ。 安全原則には、.envをGitにコミットしない、データベースとキャッシュを公網に開放しない、開発段階で8000ポートを公網に露出しない、1688は既に発生した仕入のみ同期し自動発注・支払はしない、原始財務資料はバージョンを保持する、データベース構造変更は必ずAlembicを通す、比較的大きな構造調整の前にバックアップを取ることが含まれる。システム更新はネイティブモードとコンテナリリースの身元識別をサポートし、Gitブランチとリモート、ワークスペース状態、PythonとNode環境、Alembic、バックアップ能力、フロントエンド成果物、ヘルスチェック、ディスク容量を検査する。