Offline Amazon marketplace intelligence console for turning ads, sales, cost, SKU, and ASIN exports into operator-ready reports, action queues, and review workflows.
This public repository is a clean demo snapshot. It shows the architecture, report workflow, and local operating console without exposing private store data, historical outputs, browser profiles, cookies, sessions, or real cost/SKU configuration files.
Release note: public releases should be prepared from this public branch or from a fresh sanitized export. Do not merge a private operations branch into the public repository, because private Git history can retain removed SKU, ASIN, cost, and report artifacts.
This repo is intended for three uses:
- Review the reporting and decision-workflow architecture.
- Run a local demo with generated synthetic Amazon-style data.
- Adapt the pipeline to your own Amazon marketplace exports.
It is not a hosted SaaS product, a managed Amazon API integration, or a plug-and-play decision engine. Real operating decisions require your own clean exports, cost tables, SKU/ASIN mapping, and marketplace-specific validation.
This public demo is designed for local macOS and Windows basic end-to-end verification.
- Core report generation is plain Python and does not require a browser.
- Python 3.13 is supported through the
legacy-cgicompatibility dependency used by the local upload service. - Windows launchers are included for daily report generation, local report buttons, and frontend retry sessions.
- The GitHub Actions badge reflects the public demo smoke contract. Private business validation remains a separate local responsibility.
- Live browser frontend checks remain optional. Amazon can still block or challenge browser reads, so browser evidence is never required for demo report generation.
- Parses Amazon ads CSV files and ERP sales workbooks.
- Joins data by
marketplace + sku + asin. - Computes rolling product and search-term metrics.
- Produces HTML, JSON, Markdown, and Excel reports.
- Builds an operations workbench for ad actions, low-budget keyword tests, frontend evidence, and review queues.
- Includes the public-safe version of the current operations workflow: market evidence completeness checks, SellerSprite-style enrichment hooks, action review, keyword review, and daily update validation.
- Keeps optional Amazon frontend checks as best-effort enrichment, not a hard dependency.
- Includes a local demo data generator so the project can run after clone.
- Keeps SellerSprite-style market research as offline demo fixtures in the public release. Public demo data covers reverse-ASIN keywords, competitor discovery, and history snapshots without bundling a SellerSprite account, login cookie, browser profile, or live scraping session.
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/setup_demo_data.py
.venv/bin/python scripts/run_report_window.py --workflow daily$env:PYTHONUTF8="1"
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe scripts\setup_demo_data.py
run_today_report.batThe default demo starts the local button service, runs the daily report workflow, and opens:
http://127.0.0.1:8765/report/latest_recommendations.html
Keep the terminal window open while using report buttons. Generated demo reports are written under:
data/output/
After installing dependencies and creating demo data, the root launchers can be used for a local operator-style session. This is the default demo path because it matches the formal operations console and enables local page buttons.
| Platform | Daily report with local buttons | Start button service only | Retry frontend checks |
|---|---|---|---|
| macOS | run_today_report.command |
start_report_action_server.command |
retry_frontend_checks.command |
| Windows | run_today_report.bat |
start_report_action_server.bat |
retry_frontend_checks.bat |
The default daily workflow uses no-browser frontend checks with cache fallback. To try live Chrome CDP checks, set AMAZON_OPS_ENABLE_BROWSER_FRONTEND=1. On Windows, set AMAZON_OPS_CHROME_PATH if Chrome is not installed at:
C:\Program Files\Google\Chrome\Application\chrome.exe
scripts/setup_demo_data.py creates synthetic runtime inputs:
config/product_cost_config.xlsx
config/sku_alias_map.xlsx
data/raw_ads/ads_report_all.csv
data/raw_erp/sales_report_all.xlsx
data/raw_amazon_custom/<MARKET>/traffic_sales_*.xlsx
data/raw_amazon_custom/<MARKET>/search_query_performance_*.xlsx
data/output/frontend_check_results.json
data/output/sellersprite_reverse_asin_results.json
data/output/sellersprite_competitor_discovery_results.json
data/output/sellersprite_history_snapshots.jsonl
data/output/autoopt_feedback_input.json
These files are ignored by Git. The script refuses to overwrite existing files unless --force is passed.
The generated demo data is synthetic. It covers the public report path for ads, ERP sales, cost mapping, Seller Central custom analytics, frontend evidence cache, SellerSprite-style enrichment, competitor discovery, history trend snapshots, and executed feedback review.
The demo products use public Amazon sample ASINs with synthetic ads, ERP, cost, SellerSprite-style, frontend cache, competitor, history, and feedback data. They are validation fixtures only and should not be treated as market research, product recommendations, or live Amazon evidence.
SellerSprite-related demo outputs are cached synthetic fixtures. A public clone can display and validate the market research workflow without a SellerSprite login. Real SellerSprite collection, if enabled in a private workspace, must use the operator's own account and must keep cookies, sessions, exported research files, and browser profiles out of Git.
The demo can run immediately after clone. Real store operation requires your own exported files and mapping tables:
config/product_cost_config.xlsx
config/sku_alias_map.xlsx
config/sku_asin_map.xlsx
config/product_keyword_rules.csv
data/raw_ads/
data/raw_erp/
Start from the examples in config/templates/, then keep real store files out of Git. Report quality depends on correct cost, SKU, ASIN, and marketplace mapping. If those inputs are incomplete, the generated recommendations should be treated as basic pipeline output instead of an operating decision.
Typical private inputs are:
- Amazon ads report exports.
- ERP sales exports.
- Seller Central custom analytics exports.
- Product cost configuration.
- SKU alias and SKU/ASIN mapping tables.
- Marketplace location settings for optional frontend evidence.
The public GitHub Actions workflow runs on macOS and Windows with Python 3.13. Its release gate is intentionally scoped to the public demo:
- Install dependencies.
- Generate synthetic demo inputs with
scripts/setup_demo_data.py. - Run
main.py --marketplace ALL --safe-run. - Validate generated public demo outputs with
scripts/validate_public_demo_smoke.py. - Run the public smoke tests for launchers, demo data setup, missing-report handling, and public-ASIN panel regression.
- Confirm generated demo artifacts stay ignored by Git.
This scope proves that a clean public clone can generate the demo console without private exports, browser sessions, cookies, local databases, or real SKU/ASIN configuration files.
Run the test suite:
.venv/bin/python -m pytestWindows PowerShell:
$env:PYTHONUTF8="1"
.\.venv\Scripts\python.exe -m pytestRun a report generation safe-run check:
.venv/bin/python main.py --marketplace ALL --safe-run
.venv/bin/python scripts/validate_public_demo_smoke.pyWindows PowerShell:
$env:PYTHONUTF8="1"
.\.venv\Scripts\python.exe main.py --marketplace ALL --safe-run
.\.venv\Scripts\python.exe scripts\validate_public_demo_smoke.pyRun the full showcase validation when you are changing report logic, HTML presentation, persistence, feedback review, frontend evidence, or business decision rules:
.venv/bin/python scripts/validate_showcase_mvp.pyWindows PowerShell:
$env:PYTHONUTF8="1"
.\.venv\Scripts\python.exe scripts\validate_showcase_mvp.pyImportant
真实运营前必须先替换 demo 配置。配置表会影响 SKU/ASIN 合并、利润判断、target ACOS、库存风险、SKU 别名归一和前台检查地区。
| 配置文件 | 用途 | 最小必填 |
|---|---|---|
config/product_cost_config.xlsx |
产品、成本、价格、利润、target ACOS、库存口径 | marketplace、sku、asin、product_name、currency |
config/sku_asin_map.xlsx |
SKU/ASIN/站点基础映射 | marketplace、sku、asin、product_name、currency |
config/sku_alias_map.xlsx |
把广告或 ERP 里的别名 SKU 归一到正式 SKU | marketplace、source_sku、canonical_sku、asin |
config/product_line_keywords.json |
产品线关键词分层，影响搜索词相关性和否词判断 | product_lines、keyword_levels |
config/frontend_locations.json |
UK/US/DE 前台检查使用的邮编和地区口径 | 站点键 + postcode |
product_cost_config.xlsx 字段说明
Sheet 名必须是 product_cost_config。模板字段：
marketplace currency sku asin product_name source_row selling_price exchange_rate purchase_cost_rmb purchase_cost_local first_leg_cost_rmb first_leg_cost_local packaging_cost_local_input referral_fee digital_tax vat storage_fee_estimate return_fee_estimate fba_fee ad_fee_10pct amazon_fees_excl_ads landed_cost_excl_amazon total_cost_before_ads profit_before_ads break_even_acos suggested_target_acos profit_after_10pct_ads profit_margin_after_10pct_ads roi_after_10pct_ads chargeable_weight_g volumetric_weight_g actual_weight_g length_cm width_cm height_cm current_inventory sea_inventory inventory_note mapping_status mapping_note cost_status
关键判断：
marketplace + sku + asin是核心合并键，不能随意换口径。selling_price、purchase_cost_local、first_leg_cost_local、fba_fee、referral_fee会影响利润和 break-even ACOS。suggested_target_acos会影响广告放量、降竞价和成本风险判断。填 0 或缺失会导致系统收紧建议。current_inventory、sea_inventory、inventory_note会影响补货和库存风险提示。
sku_asin_map.xlsx 字段说明
模板字段：
marketplace sku asin product_name currency
判断依据：
- 系统按
marketplace + sku + asin合并广告、ERP、成本和历史数据。 product_name用于报告展示和产品线识别。currency用于金额展示和站点口径。
sku_alias_map.xlsx 字段说明
模板字段：
marketplace source_sku canonical_sku asin reason
使用规则：
source_sku是广告或 ERP 原始导出里出现的 SKU。canonical_sku是正式配置表里的标准 SKU。- 同一
marketplace + source_sku + asin出现多行时，系统保留最后一条。 reason建议写清楚来源，例如 FBA SKU、ERP SKU、历史别名。
product_line_keywords.json 和关键词 CSV 模板
product_line_keywords.json 使用五层关键词：
| 层级 | 用途 |
|---|---|
核心词 |
高相关购买意图词，优先控竞价和查 Listing，不能轻易否定 |
可测词 |
相关长尾或相邻词，适合小预算测试 |
泛词 |
大类词，未验证前低竞价保守跑 |
低质词 |
弱相关或语义模糊词，观察或低价 |
禁词 |
明显不相关词，达到点击或花费阈值后可否定精准 |
CSV 模板 config/templates/product_keyword_rules.example.csv 字段：
product_line level keyword notes
frontend_locations.json 字段说明
模板结构：
{
"UK": {"postcode": "SW1A 1AA", "location_label": "London demo location"},
"US": {"postcode": "10001", "location_label": "New York demo location"},
"DE": {"postcode": "10115", "location_label": "Berlin demo location"}
}风险判断：
- 邮编会影响 Amazon 前台价格、配送、Buy Box 和竞品展示。
- 前台检查是辅助证据，不能替代广告、ERP、成本和产品级窗口指标。
- 真实运营时应换成对应站点的目标配送地区。
Important
后台自定义广告报表列时，先保证 10 个必选字段。缺少必选字段会影响导入；缺少搜索词、ASIN 定向和点击归因字段，会降低广告动作判断质量。
| 口径 | 字段 |
|---|---|
| 必选字段 | 日期、广告活动名称、推广的商品 SKU、推广的商品编号、推广的商品站点、展示量、点击量、总成本、购买量（所有浏览次数）、销售额 |
| 建议范围 | 30 个尺寸列 + 25 个指标列 |
| 判断依据 | src/parse_ads_report.py 的 REQUIRED_ADS_COLUMNS、ADS_FIELD_SPECS、ATTRIBUTION_FIELDS |
最小可用表头
日期 广告活动名称 推广的商品 SKU 推广的商品编号 推广的商品站点 展示量 点击量 总成本 购买量（所有浏览次数） 销售额
完整推荐表头，可复制到 Excel 第一行
日期 广告产品 预算货币 广告活动编号 广告活动名称 广告活动投放状态 广告活动预算金额 广告活动预算类型 广告活动竞价方案 广告活动成本类型 投放广告活动的国家/地区 广告组合编号 广告组合名称 推广的商品编号 推广的商品 SKU 推广的商品站点 广告组编号 广告组名称 广告组投放状态 广告组计费模式 广告 ID 广告名称 广告投放状态 搜索词 匹配的目标 投放值 投放匹配类型 广告位名称 广告位分类 展示量 点击量 总点击量 点击率 CPC 总成本 ROAS 购买量（所有浏览次数） 销量（所有浏览次数） 已售商品数量（所有浏览次数） 购买率（所有浏览次数） 销售额 归因于点击的购买量 归因于点击的销售额 归因于点击的 ROAS 归因于点击的单次购买成本 归因于点击的购买量（推广的商品） 归因于点击的销售额（推广的商品） 由浏览产生的销售额（推广的商品） 归因于点击的购买量（光环） 归因于点击的销售额（品牌光环） 归因于点击的已售商品数量（品牌光环） 无效展示率 无效点击
后台勾选清单
| 类型 | 建议勾选 |
|---|---|
| 尺寸列 | 日期、广告产品、预算货币、广告活动编号、广告活动名称、广告活动预算金额、广告活动预算类型、广告活动投放状态、广告活动开始日期、广告活动竞价方案、广告活动成本类型、投放广告活动的国家/地区、广告组合编号、广告组合名称、推广的商品编号、推广的商品 SKU、推广的商品站点、广告组编号、广告组名称、广告组投放状态、广告组计费模式、广告 ID、广告名称、广告投放状态、搜索词、匹配的目标、投放值、投放匹配类型、广告位名称、广告位分类 |
| 指标列 | 展示量、点击量、无效展示率、无效点击、总点击量、点击率、CPC、广告库存成本、总成本、ROAS、购买量（所有浏览次数）、销量（所有浏览次数）、已售商品数量（所有浏览次数）、购买率（所有浏览次数）、销售额、归因于点击的购买量、归因于点击的销售额、归因于点击的 ROAS、归因于点击的单次购买成本、归因于点击的购买量（推广的商品）、归因于点击的销售额（推广的商品）、由浏览产生的销售额（推广的商品）、归因于点击的购买量（光环）、归因于点击的销售额（品牌光环）、归因于点击的已售商品数量（品牌光环） |
广告后台定制列截图
风险说明
广告库存成本和总成本都建议保留。系统当前把总成本作为核心成本字段，同时也把广告库存成本识别为成本来源。搜索词、匹配的目标、投放值、投放匹配类型缺失时，产品级报表还能跑，但搜索词和 ASIN 定向动作会明显变弱。- 点击归因字段缺失时，系统会按 0 兜底。风险是推广 SKU 订单和光环订单无法拆分，容易把光环成交误判成投放对象有效。
由浏览产生的销售额（推广的商品）当前核心解析不依赖，但历史字段审计里出现过该列，保留它可以降低后续归因口径变化风险。- 当前代码只检查
bid或keyword_bid这类字段名。中文后台里的目标竞价即使导出，当前版本也未必会被识别为具体竞价字段。影响是报告可以给降竞价比例，但不能稳定给具体新 bid。
This public demo is intended to contain source code, documentation, tests, launchers, and sanitized templates only.
| Category | Public repo policy |
|---|---|
| Store exports | Real advertising, ERP, Seller Central, cost, SKU, and ASIN exports are excluded. |
| Generated outputs | Report HTML, JSON, Excel, SQLite, cache, archive, and log files are excluded. |
| Private configuration | Real config/*.xlsx and config/*.csv files are excluded. Only sanitized examples under config/templates/ are tracked. |
| Browser state | Browser profiles, cookies, sessions, and frontend cache state are excluded. |
| Credentials | Tokens, passwords, API keys, authorization headers, and environment secrets are excluded. |
Recommended public-release checks:
git status --short data database logs config
git grep -n -I -E "AKIA[0-9A-Z]{16}|(token|secret|password|cookie)[[:space:]]*[=:][[:space:]]*['\\\"][^'\\\"]{12,}|Authorization:[[:space:]]+|Bearer[[:space:]]+[A-Za-z0-9._-]{20,}" -- ':!README.md'
git ls-files | grep -E "data/|database/|logs/|\\.env$|\\.sqlite$|\\.db$|\\.html$|\\.xlsx$|\\.csv$"Expected output from the first two commands is empty. Expected tracked spreadsheet or CSV files in the third command are limited to sanitized templates such as config/templates/*.example.xlsx and config/templates/*.example.csv.
Copyright (c) 2026 zero7k7. All rights reserved.
This repository is source-available for review, evaluation, and local demo use with the included synthetic data. It is not released under an open-source license.
Allowed public use:
- Clone and run the project locally for evaluation.
- Review the architecture, tests, templates, and demo workflow.
- Generate demo reports from the included synthetic fixtures.
Restricted use without written permission:
- Commercial use, resale, hosted service use, or SaaS deployment.
- Redistribution, sublicensing, or republishing under another project name.
- Incorporating the code into another commercial product.
- Using public demo fixtures as live market research, Amazon evidence, or SellerSprite evidence.
Third-party dependencies, Amazon, Seller Central, SellerSprite, and other service names remain subject to their own licenses, trademarks, and platform terms.
- Frontend checks are optional enrichment. Report generation does not require a browser.
- Live browser checks are disabled by default in daily workflows to avoid local permission prompts.
- Lingxing MCP support is optional and requires user-provided environment variables.