atelier-kyo-manager 技術仕様

最終更新: 2026-05-26 関連: 経営者判断 — 手数料率・関税率・利益計算の前提条件はこちらを参照状態: Phase 2 完了・実戦投入待ち

1. 全体データフロー

[海外公式サイト] --スクレイピング/手動--> [(商品DB: Product)]
      ↓
[(商品DB)] --利益計算(FR-005)--> [出品候補リスト(FR-007)]
      ↓
[出品候補] --パイプライン(FR-002/003)--> [出品データ]
      ↓
[出品データ] --半自動出品(CSV)--> [BUYMA]
      ↓
[BUYMA注文] --> [発注管理(FR-006)] --> [仕入れ先発注]
      ↓
[発送追跡] --> [18日ルール管理]

2. FR-001 / FR-005 利益計算エンジン

簡易計算 (FR-001 / 実装済み)

実装場所: app/utils/pricing_calculator.py (旧版)
FR-005の実ベース計算に発展的解消

実ベース計算 (FR-005 / 実装済み)

実装場所: app/core/pricing/calculator.py
テスト: 13テスト
入力: 仕入れ価格、通貨、転送倉庫送料、商品カテゴリ、BUYMA手数料(7.7%)

計算式:

課税価格 = 仕入れ価格(円換算) + 転送送料(円換算)
関税 = 0                        (課税価格 ≦ 10,000円)
関税 = 課税価格 × 関税率(10-20%) (課税価格 > 10,000円)
総コスト = 課税価格 + 関税
BUYMA手数料 = 販売価格 × 7.7%
利益額 = 販売価格 - 総コスト - BUYMA手数料
最低販売価格 = 総コスト / (1 - 0.077)
推奨販売価格 = 最低販売価格 × 目標マークアップ(1.3)

3. FR-006 18日ルール管理（実装済み）

実装場所: app/models/order.py, app/routes/orders.py
テスト: 17テスト
入力: BUYMA注文ID、注文日、支払い方法
出力: 発送期限日、残り日数、延長申請可否・上限、ステータス

延長上限

支払い方法	延長上限
クレジットカード / 楽天Pay	45日
d払い / au PAY / ペイディ	25日
コンビニ振込 / 銀行振込	90日

アラート段階

残り日数	レベル	表示色	メッセージ
4日以上	注意	黄色	発送準備をお願いします
2日	警告	オレンジ	期限が近づいています。延長申請を検討してください
0日	危険	赤色	本日が期限です。至急発送または延長申請を
-1日以下	キャンセル	黒	期限切れ。キャンセル発生の可能性

4. FR-002 / FR-003 画像・説明文パイプライン（実装済み）

処理フロー

[商品URL入力]
    │
    ▼
[Selenium画像収集] ← ai_image_crawler.py
    │
    ├── 成功 → 画像URLリスト取得
    └── 失敗 → [手動アップロード] ← フォールバック
                    │
                    ▼
[画像ダウンロード] ← image_service.py
    │
    ▼
[背景除去] ← ai_background_remover.py (rembg)
    │
    ▼
[説明文生成] ← ai_generate_descriptions.py (LLM API)
    │
    ▼
[出品テキスト生成] ← template_service.py
    │
    ▼
[結果保存] → Product (pipeline_status更新)

PipelineService仕様

5ステップを順次実行するオーケストレータ:

CrawlerService.search_and_collect_images()
ImageService.download_images()
ImageService.remove_backgrounds()
DescriptionGenerator.generate()
template_service.generate_listing_text()

pipeline_status 状態遷移

pending → running → success
                  → partial (一部ステップ失敗)
                  → failed  (全ステップ失敗)

手動アップロードフォールバック

Seleniumによる自動画像収集が失敗した場合、ユーザーが手動で画像をアップロード可能。パイプラインは自動収集ステップをスキップして続きから再開。

5. FR-004 BUYMA価格調査（部分実装）

実装場所: app/services/price_scraper.py
Issue: #8
処理: Bright Data経由でBUYMA検索結果をスクレイピング
出力: 価格分布（最安・中央・最高）、出品者数
フォールバック: ブロック（403/503）時 → 手動入力モードに切替

6. FR-007 出品候補リスト生成（実装済み）

実装場所: app/routes/products.py (listing_candidates)
CSV出力: app/utils/csv_handler.py
判定基準: 利益率閾値、在庫状況、pipeline_status

7. Phase 2機能の仕様概要

FR-008 パイプライン一括実行・バックグラウンド化 (Issue #15)

現在1品ずつ同期実行 → 複数商品のCeleryバッチ処理
進捗はDB/Redisで管理、完了通知

FR-009 AI自動発注 & Slack通知 (Issue #18)

価格・在庫監視 → 自動発注判定 → Slack Webhook通知
在庫切れ・サイト仕様変更 → 即座にSlackアラート → 手動エスカレーション

FR-010 AI ChatBot（顧客対応） (Issue #19)

BUYMA問い合わせ → LLM API応答生成 → 自動返答
クレーム・未知の質問 → 人間へエスカレーション

FR-012 発送通知API連携 (Issue #17)

基盤: app/routes/warehouse_webhook.py 実装済み
Buyandship Webhook → Order更新 → BUYMA発送通知

FR-017 BUYMA出品CSV拡張 (Issue #16)

FR-007のCSV出力をBUYMA一括出品フォーマットに拡張
画像・説明文込みのCSV生成