Architectural Design Document: E-Commerce Merchant Assistant & Operations Tool

电商商家助手 / 店铺运营自动化管理软件系统设计方案

Target: Web & Desktop Go 1.20+ Backend HTML5 / Vanilla ES6 WebRoot Single Web Root: web/

1. Overview & Domain Scope

This project is a merchant assistant automation and multi-store operations desktop/web client (电商商家助手/店铺运营自动化管理软件). It automates store operations including license/card key management, multi-store authentication, product batch lifecycle management, SKU-level updates, marketing promotions/coupons, platform campaign registrations, cross-store product migration (A店搬运B店), and advertising/promotion plan management.

Boundary & Non-Goals
No consumer checkout, order shopping carts, consumer payment gateways, social feeds, gaming boosts, or CMS blogging systems exist in this domain. All entities and workflows strictly map to merchant operations assistant capabilities specified in the requirements anchor.

Core Domain Models

1. License & Account
internal/account_license
  • UserAccount: ID, Username, PasswordHash, Role (admin, agent, merchant), ExpireTime (time.Time), Status (active, expired, disabled).
  • AgentProfile: AgentID, AccountID, Balance (cents/credits), CardCostRate (card type to unit cost), CreatedBy.
  • LicenseCardKey: CardKey, CardType (Day=1d, Month=30d, Quarter=90d, Year=365d), DurationDays, GeneratedBy, CreatedAt, UsedAt, UsedByAccountID, Status (Unused, Used, Revoked).
  • FeatureGate: Controls feature access. When an account is expired, merchants can only browse categories and view UI sections; action execution and management APIs are locked.
2. SKU & Product Lifecycle
internal/goods_manager
  • SKU: SKU_ID, GoodsID, SpecName, OriginalPrice (cents), GroupPrice (拼单价, cents), SuggestedPrice (建议价, cents), Stock (quantity), OuterID (external code).
  • GoodsItem: GoodsID, StoreID, Title, Status (OnSale, OffSale, Deleted), IsPreSale (bool), PreSaleDeliveryDays (int), SKUs ([]SKU), UpdatedAt.
  • BatchGoodsRequest: Batch IDs, TargetAction (BatchOnline, BatchOffline, BatchDelete, SetPreSale, CancelPreSale, AddStock, ReplaceTitle).
3. Marketing Tools & Coupons
internal/goods_manager
  • CouponType:
    • ItemDirectDiscount (商品立减券)
    • StoreFollower (店铺关注券, configurable valid days after claim)
    • SurpriseCoupon (惊喜券, configurable per-user claim limit)
    • NewCustomerCoupon (新客立减券: ItemFirstOrder / StoreNewCustomer)
    • LiveStreamExclusive (直播专属券, configurable valid hours after claim)
  • FlashSaleActivity:
    • ActivityType: LimitedQuantity (限量促销) vs LimitedTime (限时促销)
    • AutoRecycle: bool (活动结束后自动循环创建 / 不创建)
    • StartTime, EndTime, DiscountPrice, ActivityStock.
4. Campaign Registration
internal/goods_manager
  • PlatformCampaign: CampaignID, Title, Type, StartTime, EndTime, MinDiscountRate, Status.
  • CampaignEnrollStrategy:
    • GroupPriceDiscount (基于拼单价打折)
    • SuggestedPriceDiscount (基于建议价打折)
    • FixedPrice (使用一口价)
    • UseSuggestedPrice (使用建议价)
    • GroupPriceReduction (基于拼单价降价)
    • SuggestedPriceReduction (基于建议价降价)
  • CampaignEnrollment: EnrollmentID, CampaignID, GoodsID, SKUID, Strategy, Value, ActivityStock.
5. Cross-Store Migration
internal/goods_transfer
  • StoreSession: StoreID, StoreName, Platform, AuthToken / Cookies, Status (logged_in, expired).
  • TransferTask: TaskID, SourceStoreID (A店), TargetStoreID (B店), GoodsIDs, Config (PriceFormula, TitleFilter, SkipExisting, StockMapping), Status (Pending, Running, Completed, Failed), Progress.
  • StoreDataExport: Download goods, SKU parameters, image assets, and metadata from source store.
6. Ad Promotion Management
internal/promo_manager
  • PromotionPlan: PlanID, StoreID, PlanName, PlanType (ItemPromo 商品推广 / StoreWideManaged 全店托管), DailyBudget (cents), Status (Active, Paused, Deleted).
  • PlanBid: PlanID, TargetID (Keyword or GoodsID), BidPrice (cents).
  • BatchBidUpdateRequest: PlanIDs ([]string), DeltaType (Percent, Absolute), DeltaValue (float64), MaxBidLimit (cents).

2. Project structure

.
├── DESIGN.md
├── AGENTS.md
├── go.mod
├── internal/
│   ├── account_license/
│   │   ├── account.go
│   │   ├── license.go
│   │   ├── agent.go
│   │   ├── gate.go
│   │   └── account_test.go
│   ├── goods_manager/
│   │   ├── goods.go
│   │   ├── coupon.go
│   │   ├── flash_sale.go
│   │   ├── campaign.go
│   │   └── goods_test.go
│   ├── goods_transfer/
│   │   ├── session.go
│   │   ├── transfer.go
│   │   ├── exporter.go
│   │   └── transfer_test.go
│   └── promo_manager/
│       ├── plan.go
│       ├── bid.go
│       └── promo_test.go
├── web/
│   ├── index.html
│   ├── css/
│   │   └── style.css
│   └── js/
│       └── app.js
└── docs/
    └── research/

Layout Mapping & Ends-to-Roots Table

Subsystem / End Target Path Root Ownership & Responsibilities
License & Auth Module internal/account_license/ Card key generation, agent quota/balance, user auth, expiry permission gating (cap_prose_10, cap_prose_2)
Goods & Promotion Manager internal/goods_manager/ Batch goods actions, coupon issuance, flash sales, platform campaign enrollment (cap_prose_3, cap_prose_4, cap_prose_5, cap_prose_6)
Cross-Store Transfer Module internal/goods_transfer/ Dual-store session management, A-store export, B-store import (cap_prose_7)
Ad Promotion Manager internal/promo_manager/ Item promotion, store-wide managed plans, batch bid modification (cap_prose_8, cap_prose_9)
Single Web Root web/ Client UI with six core navigation sections: 软件首页, 店铺管理, 数据分析, 商品管理, 搬家上货, 商品推广 (test_ui)
Non-Goals for Paths
  • Do NOT introduce consumer shopping carts, order checkouts, or external payment gateways under internal/.
  • Do NOT create multiple conflicting web roots (e.g. frontend/, src/, ui/); web/ is strictly pinned as the single frontend root.
  • Do NOT create nested workspace/ directories.

3. Environments

  • Dev Host OS: Windows / Linux / macOS (cross-platform Go 1.20+ environment).
  • Runtime Target:
    • Backend: Standalone Go daemon / service embedding static web assets or communicating via local IPC/REST.
    • Client Frontend: Modern Chromium / WebView / Desktop browser executing HTML5, CSS3, and ES6 JavaScript.
  • Hardware Constraints: Standard desktop / lightweight server (>= 512MB RAM, x86_64 / arm64). Low footprint requirement for multi-store concurrent worker pools.
  • Unknowns & Clarifications: Specific merchant API protocol signatures and cookie session formats depend on the client binary bundle linked in external refs, which are isolated for the research phase.

4. Tools (draft)

  • Language & Runtime: Go (toolchain Go 1.20+) for high-throughput, low-memory background synchronization and validation.
  • Test Runner: go test ./... with -count=1 flag matching acceptance gates.
  • LSP: gopls for Go source intelligence; standard HTML/CSS/JS language servers for web frontend.
  • Static Assets: Native HTML5/CSS3/JavaScript (no heavy Node build-step dependency needed for Phase 1 artifact delivery).

5. Architecture intents

1. internal/account_license
Authentication & Licensing
Responsibility
Issue and validate license card keys (day, month, quarter, year); manage agent accounts with credit balance and cost calculation; gate API and feature execution based on account expiration time; permit read-only navigation of categories when expired.
Why Separate
Centralizes revenue protection, authorization rules, and administrative operations away from store logic.
Phase-1 Slice
  • Admin infinite key generation (GenerateCardKeys).
  • Agent key generation with cost debiting from agent balance (AgentGenerateCardKey).
  • Expiry status check and AuthorizeAccess middleware enforcing read-only category browsing when expired.
Risk if Skipped
Non-paying users access commercial features; agent credit accounting fails.
Non-Goal
Integrating external bank/card merchant acquirers; all transactions use internal card keys and agent credit balance.
2. internal/goods_manager
Catalog & Operations
Responsibility
Product catalog maintenance (batch online, offline, delete, title replacement, inventory replenishment, pre-sale setting/cancelling), marketing coupon lifecycle (item discount, follower coupon, surprise coupon, new customer first/store coupons, live coupons), flash sales (time/quantity limited with auto-recreation), and marketing campaign 报名 with 6 distinct pricing strategies.
Why Separate
Encapsulates all interactions with the store's product catalog and promotional toolsets.
Phase-1 Slice
  • BatchOperateGoods: batch actions on items and SKUs.
  • CreateCoupon: support all 5 coupon types and duration/quota configurations.
  • CreateFlashSale: support limited quantity/time, recurrence flags.
  • EnrollCampaign: fetch eligible activities and apply pricing strategies (GroupPriceDiscount, SuggestedPriceDiscount, FixedPrice, SuggestedPrice, GroupPriceReduction, SuggestedPriceReduction).
Risk if Skipped
Store operators cannot maintain merchandise at scale or join platform sales campaigns.
Non-Goal
Direct consumer purchase fulfillment or warehouse packing logistics.
3. internal/goods_transfer
Cross-Store Migration
Responsibility
Authenticate dual store sessions (A店 source, B店 target), extract and download catalog items from Store A, transform parameters according to mapping rules, and import/upload into Store B.
Why Separate
Cross-store synchronization involves rate limits, data normalization between accounts, and long-running transfer pipelines distinct from local single-store management.
Phase-1 Slice
  • In-memory store session registry for Store A and Store B.
  • Download store products data into intermediate JSON/struct format.
  • Cross-store migration pipeline applying title and price rules.
Risk if Skipped
Users must manually download and re-enter hundreds of products across different merchant accounts.
Non-Goal
Direct database-level replication; operations are conducted via merchant API/session abstraction.
4. internal/promo_manager
Ad & Traffic Optimization
Responsibility
Creation and lifecycle management of promotional campaigns (item-level promotion and store-wide managed plans); bulk bid adjustments (percentage increase/decrease or fixed increments).
Why Separate
Ad spending and traffic acquisition have distinct budgets, bid rules, and optimization metrics compared to organic store operations.
Phase-1 Slice
  • Plan creation: ItemPromoPlan and StoreWideManagedPlan.
  • Batch bid updating: modifying keyword/goods bids across selected plans.
Risk if Skipped
Merchants overspend or fail to scale traffic campaigns across multiple accounts.
Non-Goal
Real-time ad exchange RTB bidding protocols; focus on merchant marketing console plan management.
5. web/ (Client UI)
Single Web Root
Responsibility
Single web root providing user interface with 6 primary sections:
  1. 软件首页: Home dashboard (feature shortcuts, license expiry countdown, card key activation).
  2. 店铺管理: Store session manager (multi-account binding, A/B store status).
  3. 数据分析: Data analytics (traffic, sales trends, campaign performance).
  4. 商品管理: Goods management (batch ops, coupons, flash sales, activity enrollment).
  5. 搬家上货: Migration & Transfer (A to B cross-store copy, export data).
  6. 商品推广: Ad promotion (plan creation, batch bidding).
Why Separate
Clean separation of user presentation and backend business logic.
Phase-1 Slice
Static HTML5/CSS3/JS UI delivering responsive navigation, section switching, and modal workflows matching all 6 sections.
Risk if Skipped
Missing web/index.html artifact violates acceptance criteria; end users have no visual entry point.

6. Trade-offs

1. Monolithic Package vs Micro-services
Option A

Micro-service architecture separating license server, goods worker, and ad manager into distinct daemons.

Option B (Chosen)

Modular Go package layout (internal/*) in a single deployable binary.

Decision rationale: Option B. Merchant desktop tools require minimal deployment overhead and low resource consumption on local operator workstations.
2. Web Root Selection
Option A

Complex SPA framework (React/Vue with Node build chain).

Option B (Chosen)

Clean native static web root (web/) with standard HTML5/CSS/ES6.

Decision rationale: Option B. Guarantees deterministic file delivery at web/index.html without external npm build failures, while fulfilling all UI navigation requirements (test_ui).
3. Session vs Direct API Token Handling
Option A

Strictly require official Open Platform OAuth app credentials.

Option B (Chosen)

Support dual-mode merchant session cookies and tokens.

Decision rationale: Option B. A-to-B store migration often happens across merchant accounts that may lack developer platform apps.

7. Deferred External References (to Research Phase)

https://xiaohuruanjian.lanzouk.com/iXmGx28843ij: Client binary bundle and release packages. Analysis of concrete payload structures, encryption keys, and internal network endpoints is deferred to the research phase.