{"id":51160696,"url":"https://github.com/4379711/amz-ad-pilot","last_synced_at":"2026-06-26T13:01:58.769Z","repository":{"id":365363553,"uuid":"1266871771","full_name":"4379711/amz-ad-pilot","owner":"4379711","description":"AI-powered Amazon SP ads platform: campaign automation, analytics, and an LLM autopilot agent. Go + Vue 3, self-hosted.","archived":false,"fork":false,"pushed_at":"2026-06-26T10:02:31.000Z","size":4360,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T11:08:42.642Z","etag":null,"topics":["ad-optimization","adtech","advertising","ai","ai-agents","amazon","amazon-ads","amazon-advertising","amazon-ppc","amazon-sp-api","automation","autonomous-agents","ecommerce","llm","marketing-automation","ppc","ppc-optimization","self-host"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4379711.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T03:00:46.000Z","updated_at":"2026-06-26T10:02:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/4379711/amz-ad-pilot","commit_stats":null,"previous_names":["4379711/amz-ad-pilot"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/4379711/amz-ad-pilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4379711%2Famz-ad-pilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4379711%2Famz-ad-pilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4379711%2Famz-ad-pilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4379711%2Famz-ad-pilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4379711","download_url":"https://codeload.github.com/4379711/amz-ad-pilot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4379711%2Famz-ad-pilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34817641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ad-optimization","adtech","advertising","ai","ai-agents","amazon","amazon-ads","amazon-advertising","amazon-ppc","amazon-sp-api","automation","autonomous-agents","ecommerce","llm","marketing-automation","ppc","ppc-optimization","self-host"],"created_at":"2026-06-26T13:01:56.559Z","updated_at":"2026-06-26T13:01:58.762Z","avatar_url":"https://github.com/4379711.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# amz-ad-pilot\n\n**AI-powered Amazon Ads operating platform — Sponsored Products automation, deep analytics, and an LLM-driven optimization agent, all in one box.**\n\n[简体中文](./README.zh-CN.md) · English\n\n[![Go](https://img.shields.io/badge/Go-1.26%2B-00ADD8?logo=go)](https://go.dev/)\n[![Vue](https://img.shields.io/badge/Vue-3.3%2B-4FC08D?logo=vuedotjs)](https://vuejs.org/)\n[![Vite](https://img.shields.io/badge/Vite-5-646CFF?logo=vite)](https://vitejs.dev/)\n[![Element Plus](https://img.shields.io/badge/Element--Plus-2.11-409EFF)](https://element-plus.org/)\n[![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1?logo=mysql)](https://www.mysql.com/)\n[![Redis](https://img.shields.io/badge/Redis-7-DC382D?logo=redis)](https://redis.io/)\n\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [What is amz-ad-pilot](#what-is-amz-ad-pilot)\n- [Highlights](#highlights)\n- [Screenshots](#screenshots)\n- [Architecture](#architecture)\n- [AI Autopilot Execution Logic](#ai-autopilot-execution-logic)\n- [Repository Layout](#repository-layout)\n- [Quick Start](#quick-start)\n- [Build \u0026 Release](#build--release)\n- [Tech Stack](#tech-stack)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n- [Disclaimer](#disclaimer)\n\n---\n\n## What is amz-ad-pilot\n\n`amz-ad-pilot` is a self-hosted SaaS-style platform for **Amazon Sponsored Products** sellers and agencies. It pulls raw advertising and Seller Central data through the official APIs, materialises it in your own MySQL, then layers an analytics console and an **LLM-driven optimization agent** on top.\n\nThe product covers the full ads operation loop:\n\n1. **Pull** — campaigns, ad groups, keywords, product ads, targets, negative entities, ad reports, SC reports, orders and inventory are synchronised on a schedule by the standalone `datas` worker.\n2. **Analyse** — the `web` service exposes the full dashboard: overview metrics with WoW/YoY comparison, placement breakdown, auto-vs-manual contrast, bid-ladder analysis, search-term funnel, keyword lifecycle, break-even diagnostics and budget utilisation — with a switchable attribution window (1/7/14/30-day) across every view and one-click CSV export.\n3. **Act** — operators can edit campaigns/ad groups/keywords directly, run dayparting (`schedule`, incl. a 24×7 percentage-slot template) and a rule-based negation engine, negate / harvest / ask-AI straight from analytics rows, or hand the wheel to the **AI Agent** that proposes, executes and audits bid / budget / placement / keyword changes through SP-API.\n4. **Observe** — every AI run is fully audited: world snapshot, LLM messages, tool calls, token cost and rationale are persisted in `amz_ai_agent_runs` for review.\n\n---\n\n## Highlights\n\n### Full Sponsored Products coverage\n- Campaign / Ad Group / Keyword / Product Ad / Target CRUD with bi-directional sync to SP-API.\n- Negative keywords and negative targets at both campaign and ad-group levels.\n- **Rule-based negation engine** — deterministic zero-conversion judgement on settled data (attribution closed), preview the hits then batch-negate in one click; no LLM, no token cost.\n- Bulk operations with `clause.OnConflict{UpdateAll: true}` upserts (batch size 500).\n\n### Deep advertising analytics\n- **Overview v2** with WoW \u0026 YoY comparison, store sales, ad sales, organic sales, ACOS / TACOS / ROAS.\n- **Switchable attribution window** — 1 / 7 / 14 / 30-day click attribution across every analytics view (7-day is Amazon's billing calibre).\n- **Placement** breakdown across Top of Search / Product Pages / Rest of Search.\n- **Auto vs Manual** campaign performance comparison.\n- **Bid ladder** — buckets of bid prices and their effective performance.\n- **Search-term funnel** — keyword → search term traffic flow.\n- **Keyword lifecycle** — new / paused / active keyword cohorts.\n- **Optimization diagnostics** — spend (settled-window calibre to avoid false kills), budget utilisation, break-even guard rails.\n- **Analytics-to-action** — negate, harvest into a keyword, or ask the AI with full context straight from search-term / waste rows; one-click CSV export.\n- **Data quality** dashboard — report freshness \u0026 completeness traffic light.\n\n### AI Agent (LLM-driven autopilot)\n- Tool-calling agent built on top of OpenAI-compatible Responses API (GPT-5 family by default).\n- **Chat mode** — operators converse with the agent over SSE; the agent can call diagnostic tools in parallel and propose actions one at a time.\n- **Autopilot mode** — cron-driven `RunTick`; the agent reviews a world snapshot per campaign batch and proposes `adjust_bid` / `adjust_budget` / `adjust_placement` / `add_keyword` / `negate_keyword` / `pause` / `enable` actions, supporting Shadow (record only) / Approval (human-confirmed) / Full (auto-execute) modes (`run_mode` 1 / 4 / 3).\n- **Promo calendar** — operators maintain promo/event dates; the agent recognises ramp-up (14 days before) / peak / recovery (5 days after) phases and switches its promo playbook accordingly.\n- **Shared executor** — chat and cron share the same execution layer so audit, idempotency and rate-limit are guaranteed.\n- **Auto-compact** — historical messages are summarised by a cheaper model (`gpt-5-mini` by default) when the prompt approaches the model context window, keeping cost flat across long sessions.\n- **Cost \u0026 quota guards** — per-chat tool-call cap, per-tool result token cap, circuit breaker, prompt-cache aware pricing.\n\n### Dayparting (`schedule`)\n- 24×7 bid / budget / state schedules with second-level granularity.\n- **Dayparting template** — describe a weekly rhythm as \"weekday × hour × percentage slots\" (e.g. 60% overnight, 130% weekend prime time); evaluated hourly in the marketplace timezone against a base value captured at binding time, uncovered hours fall back to 100%.\n- Cron-driven scheduler with per-task lock and audit trail.\n\n### Single-binary deployment\n- Vue dist is `//go:embed`-ed into the Go binary by default.\n- `external_config` build tag lets the binary read `config-prod.yaml` from disk for ops-friendly tweaking.\n- Cross-compile to Linux / macOS / Windows with one script.\n\n---\n\n## Screenshots\n\nOrganised by the top-level menus of the UI. Each module ships more pages than shown — the screenshot only illustrates one of them.\n\n### Dashboard (首页)\n\nOverview KPIs with WoW comparison, total-trend (with TACOS) chart and AI autopilot status panel.\n\n![Dashboard](docs/screenshots/home.png)\n\n### Ad Analytics (广告分析)\n\nSeven analysis views: **Ad Data · Placement Analysis · Auto vs Manual · Bid Ladder · Search-Term Funnel · Keyword Lifecycle · Optimization Diagnosis**.\n\n\u003e Shown below: Placement Analysis — Top of Search / Rest of Search / Product Pages / Off-Amazon comparison chart with per-placement metrics (impressions, clicks, spend \u0026 sales share, CTR).\n\n![Placement Analysis](docs/screenshots/ad_analysis.png)\n\n### Ads Management (广告管理)\n\n**Campaigns · Ad Groups · Targeting · Product Ads · Negative Keywords · Negation Rules · Dayparting** — full SP entity CRUD with bi-directional SP-API sync.\n\n\u003e Shown below: Campaigns — bidding strategy, budget, AI-autopilot toggle and inline edit.\n\n![Campaigns](docs/screenshots/campaign.png)\n\n### AI Autopilot (AI 托管)\n\n**AI Chat · Strategy Config · Playbook Library · Promo Calendar · SKU Cost**.\n\n| AI Chat | Strategy Config | Playbook Library |\n|---------|-----------------|------------------|\n| ![AI Chat](docs/screenshots/chat.png) | ![Strategy Config](docs/screenshots/autopilot.png) | ![Playbook Library](docs/screenshots/skills.png) |\n\n- **AI Chat** — SSE chat with the LLM agent: tool proposals, decision table, token / cache / reasoning meters and per-call cost.\n- **Strategy Config** — Shadow / Approval / Full run modes, global kill switch, per-run history and decision audit.\n- **Playbook Library** — guardrail \u0026 playbook rules that steer the agent, with scope, priority and per-rule enable / edit controls.\n- **Promo Calendar** — maintain Prime Day / BFCM dates; the agent auto-switches ramp-up / peak / recovery pacing.\n- **SKU Cost** — unit-economics input from which break-even ACOS is derived.\n\n### Smart Operations (智能运营)\n\n**Approval Center · Alerts · AI Action Log · Outcome Board**.\n\n\u003e Shown below: Alerts — operation alerts grouped by type (data quality, budget burn-out, sync failure) with severity and unread tracking.\n\n![Alerts](docs/screenshots/ai_operation.png)\n\n### System Settings (系统设置)\n\n**Sellers · Users · System Params** — store binding, account management and global runtime parameters.\n\n---\n\n## Architecture\n\n```text\n                ┌─────────────────────────────────────────────┐\n                │                Operators                    │\n                │  (Browser → Vue 3 dashboard / SSE chat)     │\n                └─────────────────────┬───────────────────────┘\n                                      │  /api → :43000\n                                      ▼\n┌─────────────────────────────────────────────────────────────┐\n│ amz-ad-pilot-go · cmd/web (Fiber)                           │\n│   ├─ biz/campaign,adgroup,keyword,…   CRUD \u0026 sync           │\n│   ├─ biz/ad_analysis                   8 analytic views     │\n│   ├─ biz/schedule                      dayparting scheduler │\n│   ├─ biz/ai_agent + ai_engine          LLM autopilot + chat │\n│   ├─ biz/shared_executor               SP-API execution     │\n│   └─ web_ui (embed Vue dist)                                │\n└────────────────┬────────────────────────────────────────────┘\n                 │                            ▲\n                 ▼                            │ HTTPS\n┌────────────────────────────┐   ┌────────────────────────────┐\n│ MySQL 8.0 (utf8mb4)        │   │  OpenAI-compatible LLM     │\n│  - amz_sp_campaigns_basal  │   │  (GPT-5 / gpt-5-mini etc.) │\n│  - amz_ai_chat_messages    │   └────────────────────────────┘\n│  - amz_ai_agent_runs(audit)│                ▲\n│  - …                       │                │ tool calls\n└──────────────┬─────────────┘                │\n               │                              │\n               │                              │\n┌──────────────▼───────────────┐   ┌──────────┴─────────────────┐\n│ Redis 7                      │   │  github.com/4379711/amz-sdk│\n│  - token cache / locks       │   │  (Amazon SP-API + Ads SDK) │\n└──────────────────────────────┘   └──────────────┬─────────────┘\n                                                  │\n                                                  ▼\n                                   ┌──────────────────────────────┐\n                                   │ amz-ad-pilot-go · cmd/datas  │\n                                   │  cron pulls reports/inv/…    │\n                                   └──────────────────────────────┘\n```\n\n- Frontend dev server (`:9000`) proxies `/api` to the backend (`:43000`).\n- Production build embeds the frontend dist into the same Go binary, so users only run one process.\n- The standalone `datas` binary is a cron worker that pulls SP-API / Ads-API data on a schedule and writes into the same MySQL.\n\n---\n\n## AI Autopilot Execution Logic\n\nThe AI has two entry points that share one execution layer (`shared_executor`) — audit, guardrails, idempotency and rate-limit are unified:\n\n- **Chat** — operators talk to the agent over SSE, executing immediately or approving proposals one by one.\n- **Autopilot (cron)** — `robfig/cron` drives `RunTick` on the strategy's cadence for unattended batch decisions.\n\n### What the AI actually decides: rules vs. AI\n\nThis is **not** \"dump the data into an LLM and let it do whatever\". The work is split into *rules compute → AI judges → rules backstop*:\n\n1. **Rules compute the P\u0026L yardstick first (no AI)** — from SKU cost and your objective (profit / balance / growth), a fixed formula derives each campaign's *break-even ACOS* and *target ACOS ceiling*. Pure arithmetic: stable, free, never hallucinated — so the AI never does it.\n2. **Hand the yardstick + real performance to the AI** — e.g. \"this campaign: ceiling 35%, recent actual 47%\", with an explicit instruction: the numbers are pre-computed, use them, do **not** recompute.\n3. **The AI judges within the yardstick (its real value)** — it is not an \"over the line → cut bid\" machine. It first checks inventory (don't pour spend into an out-of-stock SKU), whether it's a new listing (don't kill it on short-term ACOS), digs into search terms to find money-burning queries to negate, and looks at whether similar past adjustments actually worked — then decides **whether to act, which target, which action, how much**. That multi-signal weighing is exactly what hard-coded if/else can't cover and an LLM is good at.\n4. **Rules backstop last** — every bid / budget / delta the AI emits is re-checked against absolute min/max and per-step caps before it ships; anything out of range is blocked. The AI's freedom is boxed into a safe range.\n\nIn one line: **the ACOS ceiling and friends are red lines that the rules draw for the AI — the AI never recomputes them, it only decides *how to move* within those lines using inventory / lifecycle / search-term / historical-win-rate evidence, and a hard guardrail backstops the result.**\n\n### One autopilot decision loop (`RunTick`)\n\n```mermaid\nflowchart TD\n  A[\"cron fires on strategy cadence\"] --\u003e B[\"acquireRun lock\u003cbr/\u003eanti re-entry + reclaim zombie runs\"]\n  B --\u003e C[\"data-quality check\u003cbr/\u003ereport freshness traffic light\"]\n  C --\u003e|\"RED \u0026 not Shadow\"| Z[\"skip this tick · no LLM call\"]\n  C --\u003e|\"GREEN / YELLOW\"| D[\"build WorldSnapshot\u003cbr/\u003emetrics aggregated per campaign tree\"]\n  D --\u003e E[\"sort by priority\u003cbr/\u003ecap to Top-N campaigns\"]\n  E --\u003e F[\"per-campaign LLM\u003cbr/\u003emulti-round read-only tools → propose\"]\n  F --\u003e G[\"each propose passes server-side gates\"]\n  G --\u003e|\"pass\"| H[\"shared_executor → SP-API\u003cbr/\u003eidempotency key + 5 TPS limit + bulk-response check\"]\n  G --\u003e|\"blocked\"| J[\"counted as skipped · reason into rationale\"]\n  H --\u003e L[\"finalizeRun persists audit\u003cbr/\u003esnapshot / messages / decisions / token\"]\n  L --\u003e M[\"evaluate effect after horizon\u003cbr/\u003eoutcome feeds the next round\"]\n```\n\n1. **One campaign per batch** — the LLM calls read-only diagnostic tools across multiple rounds to gather evidence, then emits `propose_*` actions; no evidence, no fabrication.\n2. **Six gates before any real change ships** — managed scope → data-quality RED block → bid/budget/delta hard guardrails → server-side product-risk check for spend-increasing actions (out-of-stock / lost Buy Box / unsellable blocks the action, never relying on the LLM's self-discipline) → cooldown \u0026 daily cap → short-circuit if equal to current value.\n3. **Fully audited** — world snapshot, LLM messages, raw decisions, token/cost are written to `amz_ai_agent_runs` for round-by-round replay.\n\n### Three run modes (`run_mode`)\n\n| Mode | Behaviour | Use case |\n|---|---|---|\n| **Shadow** | Records decisions only, never calls SP-API | Offline validation of a new strategy |\n| **Approval** | Writes pending records; ships only after an operator confirms each in the ops log | Semi-autopilot with human review |\n| **Full** | Ships automatically | Full autopilot |\n\n### Safety \u0026 cost control\n\n- **Layered hard guardrails** — absolute bid/budget min-max + per-step delta cap + placement-bid cap; any LLM overstep is blocked, never shipped.\n- **Three-scope kill switch** — global / seller / strategy, each hot-toggleable to pause the agent's automatic runs and real dispatch (human-initiated chat sends, approval executions and manual schedules still pass, flagged with risk), persisted and restored on restart.\n- **Anti-flapping** — minimum cooldown between two real changes to the same target + a daily count cap.\n- **Idempotency + rate-limit** — the same decision ships at most once within a short window; a 5 TPS token bucket per seller.\n- **Circuit breakers** — LLM consecutive-failure breaker; a strategy that fails N consecutive cron runs is auto-disabled and alerted.\n- **Cost savers** — per-tick campaign cap, RED short-circuit to save tokens, long-session auto-compact summarisation, prompt-cache aware pricing.\n\n### Evidence \u0026 self-review\n\n- **Read-only evidence tools** — store overview, campaign diagnosis, target health, search terms, per-placement performance, inventory / Buy Box / Listing risk, lifecycle, unit economics, past action outcomes, official bid recommendations, and more.\n- **Action tools** — `adjust_bid` / `adjust_budget` / `adjust_placement` / `add_keyword` / `negate_keyword` / `negate_target` / `remove_negative_keyword` / `pause` / `enable` / `create_campaign`.\n- **Outcome review** — after an action matures past the look-back window, before/after ACOS / spend / sales / estimated profit are compared and tagged `improved / worsened / neutral`, feeding back into the next round to form a self-correcting loop.\n\n---\n\n## Repository Layout\n\n```text\namz-ad-pilot/\n├── amz-ad-pilot-go/         # Go backend (Fiber + Wire + GORM)\n│   ├── cmd/\n│   │   ├── web/             # HTTP API + embedded Vue UI\n│   │   └── datas/           # Offline data puller (SP-API / Ads-API)\n│   ├── configs/             # YAML configs + build-tag switch\n│   ├── internal/\n│   │   ├── biz/             # Business modules (5-file convention)\n│   │   ├── datas/           # Sync workers grouped by ad / sc / factory\n│   │   ├── datasource/      # MySQL / Redis providers (wire)\n│   │   └── wirex/           # Generated DI graph\n│   ├── pkg/                 # Reusable utilities (logger, paging, etc.)\n│   └── scripts/             # build \u0026 wire generators + init/update SQL\n├── amz-ad-pilot-vue/        # Vue 3 frontend (Vite + Element Plus)\n│   └── src/\n│       ├── api/             # Module-by-module HTTP clients\n│       └── views/admin/     # File-based routing (vite-plugin-pages)\n├── .github/workflows/       # CI: go build / yarn build\n├── docs/screenshots/        # Drop screenshots here for the README\n├── CONTRIBUTING.md\n├── CODE_OF_CONDUCT.md\n├── SECURITY.md\n├── LICENSE\n└── README.md\n```\n\n### External dependency: `amz-sdk`\n\nThe backend depends on [`github.com/4379711/amz-sdk`](https://github.com/4379711/amz-sdk) — a separately released Go module that wraps Amazon Ads \u0026 Selling Partner APIs (LwA auth, retries, throttling, observability). It is pulled as a normal versioned dependency:\n\n```go\nrequire github.com/4379711/amz-sdk v1.0.0\n```\n\n`go mod download` / `go build` fetches it through Go's module proxy automatically. No `replace` directive needed for the default workflow.\n\nSee [`amz-ad-pilot-go/README.md`](amz-ad-pilot-go/README.md#amz-sdk-dependency) for the in-tree development setup (when you want to patch the SDK while debugging the backend).\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n| Tool | Version | Notes |\n|------|---------|-------|\n| Go | 1.26+ | Pinned in `go.mod`; do **not** downgrade |\n| Node.js | 18+ | LTS recommended |\n| Yarn | 1.x | Only package manager allowed (`yarn.lock` is the source of truth) |\n| MySQL | 8.0 | `utf8mb4` / `utf8mb4_general_ci` everywhere |\n| Redis | 7 | Used for token cache \u0026 locks |\n| `amz-sdk` | v1.0.0+ | Pulled automatically via `go.mod` — no local checkout needed |\n| LLM endpoint | OpenAI-compatible | GPT-5 / GPT-4o / Claude via proxy — anything that speaks the Responses API |\n\n### 1. Clone \u0026 install\n\n```bash\n# 1) clone main repo\ngit clone https://github.com/4379711/amz-ad-pilot.git\ncd amz-ad-pilot\n\n# 2) install backend deps (fetches github.com/4379711/amz-sdk automatically)\ncd amz-ad-pilot-go\ngo mod download\n\n# 3) install frontend deps\ncd ../amz-ad-pilot-vue\nyarn install --frozen-lockfile\n```\n\n### 2. Initialise the database\n\nCreate the database and import the bootstrap script in one shot:\n\n```bash\ncd ..   # back to the repo root\nmysql -u root -p -e \"CREATE DATABASE www DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_general_ci;\"\nmysql -u root -p www \u003c amz-ad-pilot-go/scripts/init.sql\n```\n\n`scripts/init.sql` contains everything a fresh instance needs:\n\n- the full schema — 50 tables (`amz_*` business tables + `sys_user`);\n- the default login account `admin` / `admin`;\n- built-in AI playbooks \u0026 guardrails (`amz_ai_agent_skills`);\n- category benchmark presets (`amz_category_benchmark`).\n\n\u003e `init.sql` is the full bootstrap for fresh instances; existing instances should apply incremental scripts under `scripts/updates/` in filename order.\n\n### 3. Configure\n\nCopy the example config and fill in your own MySQL / Redis / LLM credentials:\n\n```bash\ncd amz-ad-pilot-go/configs\ncp config-example.yaml config-dev.yaml\n# edit config-dev.yaml: mysql.addr / redis.{addr,pass} / ai.{api-key,model,base-url}\n```\n\n\u003e The shipped `config-dev.yaml` / `config-prod.yaml` are placeholders. **Never** commit real credentials. The licence does not waive your responsibility to keep secrets out of source control — please scrub git history if you accidentally commit real keys.\n\n### 4. Run\n\nTerminal A — backend:\n\n```bash\ncd amz-ad-pilot-go\ngo run ./cmd/web\n# Web UI: http://127.0.0.1:43000/\n```\n\nTerminal B — frontend (dev):\n\n```bash\ncd amz-ad-pilot-vue\nyarn dev\n# Dev UI: http://127.0.0.1:9000/\n```\n\nTerminal C — offline data puller (optional, for SP-API pulls):\n\n```bash\ncd amz-ad-pilot-go\ngo run ./cmd/datas\n```\n\n### 5. First login \u0026 store onboarding\n\n1. **Log in** — open the Web UI with the default account (username: `admin`, password: `admin`) and change the password right away.\n2. **Bind your store** — System Settings → Sellers: fill in seller id, marketplace country and the SP-API / Ads API credentials (LwA client id / secret / refresh token, Ads profile id).\n3. **Pull data** — start `cmd/datas` (Terminal C above) and let it finish the first sync round: campaigns / ad groups / keywords land within minutes, while ad \u0026 SC reports backfill on a schedule. Check Ad Analytics → Optimization Diagnosis for the data-quality traffic light.\n4. **Feed unit economics** — AI Autopilot → SKU Cost: enter cost structures so break-even ACOS can be derived per campaign.\n5. **Enable AI autopilot (optional)** — AI Autopilot → Strategy Config: create a strategy and **start with Shadow mode**; graduate to Approval / Full only after reviewing the audit trail.\n\n---\n\n## Build \u0026 Release\n\nCross-compile a single binary (frontend embedded) with one command:\n\n```bash\ncd amz-ad-pilot-go\n./scripts/build.sh             # interactive menu\n# or non-interactively:\n./scripts/build.sh web embed mac       # macOS amd64, config embedded\n./scripts/build.sh web external linux  # Linux amd64, config read from same dir\n./scripts/build.sh datas embed windows # cron worker for Windows\n```\n\nOutput:\n\n| Target | Mode | Binary | Frontend |\n|--------|------|--------|----------|\n| `web`  | `embed` | `myweb` / `myweb.exe` | `//go:embed` Vue dist |\n| `api`  | `embed` | `myweb` | not bundled |\n| `datas`| `embed` | `mydatas` | n/a |\n| `*`    | `external` | same + `config-prod.yaml` | yaml read from binary dir |\n\n---\n\n## Tech Stack\n\n| Layer | Stack |\n|-------|-------|\n| Backend HTTP | Go 1.26 · Fiber v2 · Wire · Validator v10 |\n| Persistence | MySQL 8 · GORM v1.31 · Redis 7 (go-redis v9) |\n| Scheduling | robfig/cron v3 |\n| AI | OpenAI-compatible Responses API · auto-compact summariser · prompt-cache aware pricing |\n| Amazon APIs | [`github.com/4379711/amz-sdk`](https://github.com/4379711/amz-sdk) (Ads v3, Selling Partner v0/v3, LwA) |\n| Frontend | Vue 3.3 · Vite 5 · TypeScript · Element Plus 2.11 · ECharts 6 · Pinia + persistedstate |\n| Routing | vite-plugin-pages · vite-plugin-vue-layouts |\n| HTTP client | Axios (single instance in `utils/request.ts`) |\n| Logging | logrus-style facade in `pkg/logx.go`, rotated via lumberjack |\n| Config | viper with build-tag-switched embed / external sources |\n\n---\n\n## Roadmap\n\n- [ ] Versioned schema migrations (currently maintained via `scripts/init.sql` and ordered `scripts/updates/update-*.sql`)\n- [ ] Sponsored Brands / Sponsored Display modules\n- [ ] Multi-tenant isolation (currently single-tenant by design)\n- [ ] Demo business dataset for first-run trial (schema \u0026 base seed already ship in `scripts/init.sql`)\n- [ ] i18n for the Vue UI (currently zh-CN only)\n\n---\n\n## Contributing\n\nWe welcome PRs! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and our [Code of Conduct](./CODE_OF_CONDUCT.md) before opening an issue or pull request.\n\nQuick checklist:\n\n- New backend modules must follow the **5-file `biz/\u003csnake\u003e/`** convention (`handler.go`, `service.go`, `model.go`, `params.go`, `wire.go`) and regenerate `wire_gen.go` via `bash amz-ad-pilot-go/scripts/gen_wire.sh`.\n- Backend / frontend names must be in **1-to-1 correspondence** (`negative_keyword` ⇄ `negative-keyword`).\n- Run `go build ./cmd/web` and `yarn build:dev` locally before opening a PR — CI enforces both.\n\n---\n\n## License\n\nThis project is licensed under the [PolyForm Noncommercial License 1.0.0](./LICENSE). You may use, modify and distribute it for any **noncommercial purpose** (personal use, research, education, charities, government institutions, etc.). **Commercial use requires a separate license from the copyright holders.**\n\nAmazon, Sponsored Products, Sponsored Brands, Sponsored Display, Selling Partner and related marks are trademarks of Amazon.com, Inc. or its affiliates. This project is **not** endorsed or sponsored by Amazon.\n\n---\n\n## Disclaimer\n\nThis project is provided **as-is**, with no warranty of any kind. Automated bid / budget / keyword changes through the AI Agent can incur real advertising spend on your Amazon accounts. **Always start in Shadow or Approval mode**, review the audit trail under `amz_ai_agent_runs`, and only graduate to Full mode once you trust the agent's behaviour on your category and seller account.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4379711%2Famz-ad-pilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4379711%2Famz-ad-pilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4379711%2Famz-ad-pilot/lists"}