MONOLINK 运营平台 亚马逊日本站运营管理系统 · v1.0
本系统用于管理旗下各品牌在亚马逊日本（Amazon.co.jp）的日常运营，包括商品数据管理、库存预警、销售分析、广告监控、利润核算、AI智能分析和补货决策。
适用范围： 支持多品牌、多 SKU 的店铺统一管理，品牌与商品数据由系统自动同步
数据来源： Amazon SP-API（商品信息/FBA库存/FBA费用）、自有 ERP（成本/FBM库存）
部署环境： 飞牛NAS（FnOS/Debian） · Docker · 访问地址：100.88.178.102:1000
快速入门： 首次使用请先在「系统设置」中配置 Amazon SP-API 凭证，然后在「商品主数据」页面点击「手动同步」，等待数据拉取完成。
⊞ 运营看板
整体业务概览，汇总关键指标和可视化图表，是每天打开系统的第一个页面。
KPI 卡片
销量 选定日期范围内的订单数量
收入 订单总金额（日元）
毛利润 收入 − 产品成本
净利润 收入 − 全部费用（含FBA运费/佣金/积分/广告费）
毛利润率 / 净利润率 分别为毛利润/净利润占收入的百分比
ACOS 广告花费占收入的百分比
涨跌标识 与上期对比，上升显示绿色药丸标签（▲），下降显示红色药丸标签（▼）
图表区域
利润构成瀑布图 可视化分解收入到净利润的各项费用扣除
分组利润排行 按商品分组排列利润贡献，前10名彩色横条对比
利润趋势图 支持多指标多选（收入/毛利润/净利润/销量），悬停查看详情
看板数据在切换到该页面时自动加载最新数据。快捷日期按钮支持快速切换时间范围。
系统自动产生的运营待办事项，需人工确认和跟进处理。
任务类型
每天08:00库存检测后自动生成，汇总所有需补仓/补货的商品 为一张报告卡片，包含补仓清单和补货清单两个表格，支持一键复制仓库指令。每天只生成1张，旧报告自动归档。
亚马逊重测尺寸导致FBA配送费发生变化，每天03:00检测。逐条推送，需逐个确认处理。运费上涨≥¥100时飞书推送。
（规划中）广告 ACOS 超出熔断线时自动创建。
每日补货报告详解
每天08:00检测库存后，系统将所有需行动的商品汇总为1张报告，不再逐商品推送卡片。
补仓清单（日本仓 → FBA）：
•
•
•
补货清单（需从中国采购）：
•
补仓/补货建议数量计算
补仓建议数 = 日均销量 × 30天 − 入库中数量
上限为日本仓实际可用库存（不超发）
补货建议数 = 日均销量 × 90天 − 全部库存合计（FBA+入库中+日本仓）
向上取整到MOQ的倍数
组合商品处理
• 组合商品在报表中以蓝色背景 高亮显示，并标注「组合」标签
• 子商品展开显示在父商品下方，包含各子商品的ERP条码 和对应数量
• 日本仓库存按瓶颈原则计算（最少可组套数）
• 补仓/补货数量按套数计算，子商品自动乘以单套用量
示例： 组合商品A = 洗面奶(8001)×1 + 化妆水(8002)×1。建议补仓40套 → 仓库需备：洗面奶(8001)×40、化妆水(8002)×40。
仓库指令一键复制
• 点击报告卡片上的「
• 自动生成格式化文本，包含商品名、ERP条码、数量
• 组合商品自动展开为子商品条码+数量
• 复制后可直接发送给仓库执行
不推送到任务中心的状态
•
•
•
•
飞书推送
补货报告 每天08:00检测后推送1条汇总消息，包含各状态商品数量。无需行动商品时不推送。
FBA运费变动 运费上涨≥¥100时推送，下降不推送。
状态流转
待处理 → 点击「标记已处理」→ 已处理
待处理 → 点击「忽略」→ 已忽略
待处理 → 次日新报告生成 → 旧报告自动归档
已处理/已忽略 → 点击「↩ 返回待处理」→ 待处理（防误操作）
历史报告保留可回溯。已处理/已忽略的任务变为半透明。
FBA运费变动处理方法
点击任务中的 ASIN 链接，在亚马逊商品页面确认
登录亚马逊卖家后台 → 联系卖家支持 → 申请重新测量商品尺寸/重量
若亚马逊测量有误，提交实际尺寸数据，申请恢复原运费
处理完成后在任务中心点击「标记已处理」
检测时间
FBA运费变动 每天 03:00（JST）检测
日均销量更新 每天 06:00（JST）同步，重算可售天数
每日补货报告 每天 08:00（JST）FBA库存同步后，生成补货报告+飞书推送
手动触发： 在库存管理页面点击「同步FBA库存」按钮，同步完成后会立即执行一次预警检测并生成补货报告，无需等到08:00。
筛选与分页
状态筛选 待处理 / 全部 / 已处理 / 已忽略
类型筛选 每日补货报告 / FBA运费变动 / 广告异常
排列方式 补货报告全宽显示，其他任务2列卡片布局
每页数量 20条，底部分页导航
导航栏红色角标显示当前待处理任务总数，切换到任务中心时自动更新。
所有在售商品的主数据管理，汇聚 Amazon SP-API 与自有ERP的数据。
核心字段
ASIN Amazon 标准商品编号，唯一标识
商品名称 日语名称（name_ja）+ 中文名称（name_zh）
品牌 商品所属品牌，用于筛选与分组统计
当前售价 日元含税价（price_jpy），来自 My Price API BuyingPrice，用于计算 FBA 配送费和毛利
定价 商家定价（reference_price_jpy），来自 Catalog API purchasable_offer（我们设定的出品价格），仅展示参考，不参与毛利计算
FBA配送费 亚马逊 Product Fees API 查询结果（日元/件）
销售佣金 亚马逊 Product Fees API 中的 ReferralFee（日元/件，约售价8%）
积分费用 默认按售价 1% 计算（日元/件），可手动修改
毛利空间 售价 − 采购单价 − FBA配送费 − 销售佣金 − 积分（实时计算，不存库）
BSR排名 Amazon 该类目排名，含类目名称，从 Catalog API 抓取
重量/尺寸 从 Amazon Catalog API 获取，单位：克/毫米
采购单价 来自自有ERP，用于利润计算
商品主图 Amazon CDN 图片URL，自动抓取
重点商品 标记后触发 AI 日报分析，普通商品仅收集数据
数据抓取接口与频率
当前售価（price_jpy） My Price API BuyingPrice → 兜底 Competitive Pricing API（每日01:00 + 13:00 同步两次）
定价（reference_price_jpy） Catalog API purchasable_offer（商家定价，每日01:00 + 13:00 同步两次）
BSR排名/类目 Catalog Items API classificationRanks/displayGroupRanks（每日01:00链式同步 Step 1）
FBA配送费 + 销售佣金 Product Fees API（0.1 req/s），每日01:00链式同步 Step 2（依赖Step 1最新售价）
名称/图片/尺寸/重量 Catalog Items API（约2 req/s），每周日02:30批量刷新
采购成本/FBM库存 自有ERP API，每日01:00链式同步 Step 0
手动同步 新建商品自动触发；商品详情「↻ 同步数据」；工具栏「同步全部商品数据」触发全量链式同步
注意： FBA配送费受商品实测尺寸影响，系统每日链式同步自动轮转检查，发现变动会在任务中心创建任务并推送飞书。
三仓合并库存视图：Amazon FBA + 日本自有仓 + 在途货物。
仓储架构
中国工厂 →（海运约20天）→ 日本自有仓 →（国内配送3-5天）→ Amazon FBA仓
关键指标
近7天销量 Amazon Sales API 近7天总销售件数，同步后显示原始件数及日均
近30天销量 Amazon Sales API 近30天总销售件数
本周销售额 近7天销售额（日元），来自 Sales API totalSales
日均销量 = ⌈近7天总量 ÷ 7⌉，向上取整，避免低销量商品显示0
FBA可售天数 = (FBA可售 + 待调仓 + 处理中) ÷ max(7天日均, 30天日均)
综合可售天数 = (FBA可售 + 待调仓 + 处理中 + 入库中 + FBM库存) ÷ max(7天日均, 30天日均)
销售数据同步
数据来源 Amazon Sales API（/sales/v1/orderMetrics），速率 0.5 req/s
定时同步 每天 06:00 JST 自动同步所有商品销量
手动同步 商品详情点「↻ 同步数据」；或系统设置「立即同步销量」
商品列表状态标识（8级）
状态按优先级从高到低判断，命中即停止。补仓 = 从日本仓转发至FBA仓库；补货 = 整体库存不足，需从中国采购。
全线缺货 条件： FBA有效库存 + 入库中 = 0，且 FBM = 0需立即联系工厂紧急补货。
断货·需补仓 条件： FBA有效库存 + 入库中 = 0，但 FBM > 0需立即从日本仓转发至FBA （到仓约3~5天）。
断货·补仓中 条件： FBA有效库存 = 0，但入库中 > 0无需操作，等待亚马逊上架。
紧张·补仓中 Xd 条件： FBA天数 ≤ 14天，且 FBA天数 + 入库中天数 > 14天无需操作，等待到仓即可。
紧张·需补仓 Xd 条件： FBA天数 ≤ 14天（且入库中不足以覆盖）需尽快从日本仓转发至FBA，同时评估是否需要从中国补货。
关注需补货 Xd 条件： 综合可售天数 < 60天需安排从中国采购补货。
充足 Xd 条件： 综合可售天数 ≥ 60天
颜色语义：
FBA有效库存： FBA可售数量 + 待调仓数量（亚马逊仓间调拨中）+ FC处理中数量（已到仓待上架）。这三项都算FBA有效库存，因为待调仓和FC处理中的货物通常1~3天即可变为可售。
天数计算公式： FBA天数 = FBA有效库存 ÷ 日均销量；综合天数 = (FBA有效 + 入库中 + FBM) ÷ 日均销量；入库中天数 = 入库中数量 ÷ 日均销量。
三仓说明： FBA仓（亚马逊管理）、入库中（发往FBA途中）、FBM仓（日本自有仓库，由自有ERP管理）。
按期间对比销售、利润、销量数据，支持自定义分组和多期间叠加分析。
页面结构
KPI看板（上方） 7个指标卡片：销量、收入、毛利润、净利润、毛利润率、净利润率、ACOS，每个卡片带涨跌颜色标识（绿色=上升、红色=下降）
利润构成瀑布图 收入 → 各项扣除（产品成本/FBA运费/平台佣金/积分/广告费）→ 净利润的可视化分解
分组利润排行 按商品分组展示利润贡献排名，前10名+其余合并显示，彩色横条对比
利润趋势图 多指标折线图，支持收入/毛利润/净利润/销量多选叠加，不同颜色区分。金额和销量同时选中时自动启用双Y轴（左轴¥、右轴件）
期间对比表 按分组展开的商品明细表，含商品图片、ASIN、售价、单件利润率、各期间数据列
期间管理
快捷日期 今日 / 昨日 / 近3天 / 近7天 / 近14天 / 近30天 / 本月 / 上月
自定义日期 选择开始和结束日期后点击「添加期间」
多期间叠加 可同时添加多个时间段进行对比，每个期间以不同颜色标签显示
删除期间 点击期间标签右侧
商品分组
创建分组 点击「管理分组」→「新建分组」，输入名称，搜索并添加商品
编辑分组 在分组列表中点击编辑，可修改名称、添加/移出商品
防重机制 数据库唯一约束保证同一商品不会重复加入同一分组
表格展示 分组行可折叠/展开，折叠时显示分组汇总数据和迷你走势图
走势图弹窗（Sparkline）
悬停预览 鼠标悬停在商品名/分组名右侧的迷你走势图上，显示快速预览
点击固定 点击走势图可固定弹窗在页面中央，带半透明遮罩层
交互式悬停 固定模式下，鼠标在图表上移动可查看每日详细数据（日期、净利润、销量）
汇总信息 弹窗顶部显示合计利润、日均利润、总销量、涨跌幅
利润趋势多选指标
颜色 #0984e3，订单收入总额
颜色 #00b894，收入 − 产品成本
颜色 #6c5ce7，收入 − 全部费用（默认选中）
颜色 #e17055，订单数量（件）
多选操作 点击按钮切换选中/取消，至少保留一个指标。选中时按钮填充对应颜色
双Y轴 同时选中金额指标和销量时，左轴显示金额（¥），右轴显示数量（件）
数据来源
数据来源 Amazon SP-API 订单接口（直连），每3分钟增量同步
时区 Asia/Tokyo（JST，UTC+9）
金额单位 日元（整数）
趋势图补零 选定日期范围内无订单的日期自动补零显示，确保趋势图连续完整
完整管理 SP/SB/SD 广告活动 — 直接调用 Amazon Ads API V3 调出价/状态/预算/创意等。URL 子路径支持 #ads/<tab> 直达。
7 个核心 Tab
看板 KPI 总览 / 错过销售预警 / 今日异常 / 趋势图 / 归因窗口对比 / Top5 关键词·搜索词·商品
结构层 Campaign 列表 + 详情：广告组 → 关键词 → 商品广告 → 否定词 → 商品定向 全打通
搜索词 24K+ 搜索词数据 + AI 建议（该否定/提精准）+ 范围筛选 + 批量否定
广告位 Top of Search / PDP / Other 3 卡片 + Campaign×Placement 明细表
商品广告 ASIN × Campaign 矩阵 + 表现分级筛选
规则引擎 自定义自动规则（出价/预算/状态/否定），CRUD + 预览匹配 + 每小时评估
操作中心 4 子 Tab：待审批 / 已执行 / 可撤销 / 历史归档 + 批量 CSV 导入
数据来源（Amazon Ads V3 API）
spCampaigns Campaign 维度日报：花费/销售/订单/点击/曝光/CTR/CPC/TOS IS（顶位展示份额）
spAdvertisedProduct ASIN×Campaign×AdGroup 维度日报：商品级精确归集
spKeywords 关键词维度日报：仅手动 KW，自动定向不在此
spSearchTerm 搜索词维度日报：含多归因窗口（1d/7d/14d/30d）
spPlacement 广告位维度日报：Top/PDP/Other
Amazon Marketing Stream SQS 推送实时小时级数据（店铺级别，1-15 分钟延迟）
看板 Tab 重点功能
8 KPI 卡 + sparkline 花费/广告销售/ACOS/ROAS/点击/订单/曝光/新客订单 NTB — 每卡含 7 天迷你趋势线 + 同比环比
错过销售预警 找今日花费 ≥85% 预算的 Campaign，用近 7 天日均销售 × 剩余小时比例估算损失（±30% 容差）
今日异常 3 卡 ACOS 突增 / 零转化高花费 / 预算耗尽
多指标叠加趋势图 9 个 metric chip：花费/销售/点击/订单/曝光/ACOS/ROAS/CTR/CVR — 任意勾选叠加；金额走左轴，率走右轴
归因窗口对比 1d / 7d / 14d / 30d 销售归因数据并排显示
AI 早报 每天 02:30 自动生成 3-5 句运营建议（DeepSeek V4 Pro）
结构层 Tab 重点功能
日期范围 sticky 顶部全局日期栏 sticky 固定，与看板共用；切日期不刷新页面，原地更新数据
快捷场景 chip 一键应用：
Campaign 列表 含搜索 / 状态/类型 segmented / 7 种排序 / TOS IS 份额 / 日均预算消耗条
Campaign 详情 6 KPI + 设置项折叠摘要 + AdGroup 展开树 + 关键词表 + 商品广告卡 + 否定词区
关键词表 含状态徽章 + 状态筛选 + 行内 bid 编辑 + 启停按钮 + ACOS/ROAS 双色分级
商品广告卡 72×72 商品图 + ASIN/SKU 复制 + 售价 + 6 列 stat + 状态筛选 + 启停按钮
否定词区 Campaign 级 + AdGroup 级分开显示；搜索过滤 + 默认折叠
AI 深度分析（Campaign 详情）
点击 Campaign 详情顶部「[AI] 深度分析 」按钮，传 Campaign 7 天数据（指标 + Top 10 关键词 + 零转化高花费搜索词）给 AI，返回：
整体评价 含 A/B/C/D/F 评级 + 2-3 句总结
关键词建议 最多 5 条：建议降价/提价/暂停/转精准 + 推荐 bid 值
搜索词建议 最多 5 条：建议否定/提精准
策略建议 最多 5 条：预算/竞价策略/广告位加价调整
右下角 AI 对话框（ChatBot）
默认模型 DeepSeek V4 Pro / Flash（OpenAI 兼容协议）
16 个工具 health / snapshot / orders / ads / inventory / reviews / store_overview / search_terms / ad_placements / profit_pnl / profit_products / profit_alerts （2026-05-22 新增 4 个）等可调
流式输出 SSE 实时显示，工具调用进度可视化
会话管理 多会话切换 + 历史 90 天保留 + 一键删除
消费显示 每次响应显示 token + USD/JPY 双币成本
操作中心 — 批量 CSV 导入
操作中心顶部「
type,id,field,value
支持类型：keyword (bid/state) · campaign (budget/state)。上传后预览 + 错误标注，确认后逐行执行真后端 API。
广告操作 — 安全限制
单次出价变动 最大 ±40%，超出限制弹窗警告
单次预算变动 最大 ±50%，超出限制弹窗警告
日花费上限熔断 ¥60,000 / 天，超出自动暂停所有广告 + 飞书通知
小时 ACOS 上限 ACOS > 80% 触发熔断
撤销窗口 操作后 30 分钟内可一键撤销（在操作中心「可撤销」Tab）
操作日志 所有操作（手动/AI/规则/熔断）写入 ad_operations 表，含变动前后对比 + 来源标识
规则引擎
用户自定义规则自动评估，每小时 :15 跑一次。支持范围：
作用范围 全部 SP / 全部 Campaign / 指定 Campaign / AdGroup / 品牌 / ASIN
条件 ACOS / 花费 / 订单 / CTR / CVR 等指标的 >/</= 阈值，时间窗 1d-30d
动作 降低出价/提高出价/暂停/降低预算/提高预算/添加否定词
执行模式 auto（直接执行）/ suggest（生成待审批建议进操作中心）
预览匹配 保存前可预览当前规则匹配到的 Campaign / KW，避免误操作
数据准确性说明： 商品广告卡花费数据基于 spAdvertisedProduct V3 报表（按 ASIN×Campaign×AdGroup 精确归集）。AdGroup 头部花费优先从 spKeywords 报表聚合，自动定向 AdGroup 若是 Campaign 唯一广告组则 fallback 到 Campaign 总数。这些数据 T+1 延迟（亚马逊后端聚合限制）。
注意： 广告操作前会弹出确认窗口显示变动前后对比，所有操作均记录在操作日志中，可追溯。
基于真实成本的精确利润核算，支持按时间段和商品查看。
利润计算公式
单品毛利（商品详情页实时显示）
毛利空间 = 当前售价 （My Price API BuyingPrice）
− 采购单价（自有ERP）
− FBA配送费（Product Fees API）
− 销售佣金（Product Fees API · ReferralFee）
− 积分费用（默认售价 × 1%，可手动修改）
定价 （purchasable_offer 商家定价）仅在商品详情页展示参考，不参与利润计算。当前售价与定价的差异通常由优惠券、促销活动等导致。
净利润（利润报表）
净利润 = 销售额
− 货品成本（自有ERP · 实际采购价 × 销量）
− 平台佣金（亚马逊结算明细）
− FBA配送费（亚马逊结算明细）
− FBA仓储费（亚马逊结算明细）
− 广告费（广告API）
− 头程运费（自有ERP）
− 退货损耗（亚马逊结算明细）
货品成本来自自有ERP的实际采购单价。订单中的采购成本采用「快照锁定」机制：首次写入后不再随后续ERP价格变动而改变，确保历史利润数据准确反映下单时的真实成本。详见「采购成本锁定」章节。
订单售价： 待处理订单（Pending）尚未获取到亚马逊真实成交价时，系统自动使用商品的当前售价 （My Price API BuyingPrice）× 数量 作为预估售价。当订单状态更新后获取到真实成交价会自动覆盖。
佣金费率优先级： ① Product Fees API 实测反推（referral_fee_jpy ÷ 定价/售价）→ ② Catalog API productType 类目查表（如 BICYCLE_LIGHTS=15%、SOAP=10%、ELECTRONICS=8%）→ ③ 默认 10%。费率由 get_referral_rate() 计算，商品详情「销售佣金」行会显示当前费率和来源。
前端 3 Tab UI（2026-05-22 新增）
月度损益表 11 列表格：月份/销量/销售额/货品成本/FBA费/佣金/积分/广告费/净利润 /净利率/环比 ▲▼。顶部 4 个 KPI 卡（总销售额/毛利润/广告费/净利润）。可调区间（默认近 6 个月）。
商品利润排行 按 ASIN 聚合，10 列指标，支持按净利润/净利率/销售额/销量/广告费/毛利润 6 种排序。前端搜索 ASIN/SKU/商品名。日期快捷：本月/上月/近 7 天/近 30 天。
利润率预警 本月 vs 上月，净利率下滑超过阈值（默认 5pp）的商品卡片列表。带本月/上月销售额、广告费对比，可直观看出是不是广告费上升导致下滑。最小销售额过滤去噪声。
3 个端点 /profit/pnl / /profit/products / /profit/alerts 复用 sales.py 同口径，避免数据打架。ChatBot 也能调这 3 个工具回答利润相关问题。
⚠ 估算 vs 已确认 数据标识（2026-05-22 新增）
背景： Amazon SP-API 对 Pending（等待付款验证）状态订单不返回 ItemPrice 字段（保护买家信用卡信息）。系统在 Pending 期间以商品吊牌价 × 数量作为兜底，偏高 10-15%（不含订购省/Coupon 等订单级折扣）。订单变 Shipped 后自动同步真实价。
受影响字段 订单金额、平台费、利润、利润率（均基于 item_price 算出）
不受影响字段 商品成本（自有ERP）、FBA费（按 ASIN 拉，不依赖订单）、积分（SP-API 即使 Pending 也返回 PointsGranted）
UI 体现 运营看板「今日销售额」和「今日净利润」KPI 卡显示 ● 已确认 + ● 待付款 ⚠ 估算 拆分。订单详情 Pending 单时 4 个受影响卡片显示黄色边框 + ⚠ 估算 标识，hover 有 tooltip 详解。
自动恢复机制 每 30 分钟「Pending 订单刷新」定时任务自动扫描所有 Pending/Unshipped 订单，重新拉 SP-API 同步真实价。订单付款验证完后（通常几分钟~1 天）会变 Shipped 状态，下次刷新自动覆盖估算值。
基于 Claude API 的智能分析，分日报（Haiku）和周报（Sonnet）两个频率。
分析频率与费用
每日 08:00 Haiku 日报：ACOS异常、库存预警、今日广告调整建议、行动清单（约 $0.018/次）
每周一 08:00 Sonnet 周报：深度广告优化、搜索词挖掘、竞品分析、补货量建议（约 $0.15/次）
月度 Token 上限 $12，超出后暂停 AI 分析，规则引擎继续运行
重点商品机制
只有在「商品主数据」中被标记为「重点商品」的 SKU 才会触发 AI 日分析。普通商品仅收集数据，不触发分析，以节省 Token 用量。
基于三仓库存和销售数据的补货决策支持。
补货决策逻辑
综合可售天数 = (FBA可售 + 待调仓 + 处理中 + 入库中 + FBM) ÷ max(7天日均, 30天日均)综合可售天数 < 30天 → 触发补货建议
FBA可售天数 < 14天 且 FBM仓有货 → 建议立即FBM仓转发FBA（3-5天到仓）
采购周期：生产（约30天）+ 海运（约20天）= 总计约 50天
⭐ 评价监控
自动抓取 Amazon.co.jp 商品评价，差评实时推送飞书，支持 AI 分析。
功能概述
评价抓取 自动抓取监控商品的全部评价（评分、标题、正文、作者、日期）
差评预警 新差评（≤设定阈值）实时推送飞书通知
评分趋势 每日记录评分快照，30天趋势图可视化
AI 分析 一键分析差评共性，Claude Haiku 生成改善建议
定时同步 每天 09:30 JST 自动同步全部监控商品的评价
使用方法
1. 开启监控 在「商品管理」中打开商品详情，勾选「监控评价」开关
2. 登录 Amazon 评价页底部「Amazon 帐号登录」输入帐号密码，点击登录。服务器会自动从 NAS 登录亚马逊获取 Cookie
3. 同步评价 点击「同步评价」按钮手动触发，或等待每天 09:30 自动同步
4. 查看评价 评价列表支持按商品、星级、日期筛选，点击表头可排序
5. AI 分析 选择商品后点击「AI 分析差评」，分析结果显示在列表上方
Amazon 帐号登录
为什么需要 Amazon 评价页（全部评价）需要登录才能访问，且 Cookie 绑定 IP。因此需要从服务器（NAS）登录
帐号要求 建议使用专门的普通买家帐号（非卖家帐号），避免影响主帐号安全
登录方式 支持手机号+密码、邮箱+密码、手机号+OTP验证码
验证码处理 如遇验证码，页面会弹出黄色输入框，输入后自动继续
Cookie 有效期 登录后 Cookie 自动保存，有效期通常数天到数周。过期后需重新登录
抓取原理
技术方案 Playwright 无头 Chromium 浏览器，模拟真实用户操作
抓取流程 商品页（评分+总数+8条）→ 点击「レビューをすべて見る」→ 评价页 → 反复点击「さらにN件のレビューを表示」加载全部 → 展开「続きを読む」获取完整正文
降级策略 如评价页无法访问（Cookie 过期），自动回退到商品页的 8 条 Top Reviews
每页间隔 随机 2~5 秒延迟，模拟人类浏览速度
推送设置
差评阈值 ≤2星 或 ≤3星，低于等于此星级的评价触发推送
推送模式 即时推送（发现差评立即通知）或 每日汇总（当天统一推送）
推送频道 飞书「预警小D」频道，类别为 review_alert
提示： 评价同步较耗时（每商品约 15~30 秒），监控商品不宜过多。建议只监控主力 SKU。
配置各接口凭证，修改后实时生效，无需重启容器。
Amazon SP-API 凭证
LWA Client ID 亚马逊开发者账号的 Client ID
LWA Client Secret 亚马逊开发者账号的 Client Secret
LWA Refresh Token 授权令牌，用于获取访问 token
Marketplace ID 日本站固定值：A1VC38T7YXB528
自有ERP 集成
接口URL 自有ERP的API根地址
用户名/密码 ERP系统登录凭证
日本仓库名称 用于匹配库存数据的仓库标识
飞书推送
Webhook URL 飞书自定义机器人的 Webhook 地址，用于接收运营通知
所有凭证加密存储在数据库中，密码字段默认显示为掩码，点击眼睛图标可临时查看明文。
系统后台定时任务一览（时区：Asia/Tokyo，JST）。所有每日任务按依赖链串行执行，确保数据一致性。
执行时间
任务名称
说明
每天 01:00链式同步 Step 0: ERP采购成本
同步所有商品的采购单价（R_Cost）、中文名、FBM库存。逐条码查询自有ERP。
Step 1: 售价/BSR
全量同步所有商品的当前售价（My Price API BuyingPrice）、定价（purchasable_offer 商家定价）和BSR排名。逐条写入，中途崩溃不丢失已同步数据。
Step 2: FBA费+佣金
用 Step 1 刚更新的售价，全量同步FBA配送费和销售佣金。Product Fees API（0.1 req/s）。
Step 3: 订单费用重算
用 Step 0~2 的最新数据重算近7天所有订单的费用和利润。纯数据库操作，几秒完成。
每天 03:00如果01:00链式同步的 Step 2 已成功执行，此任务自动跳过。仅在链式同步失败时作为保底运行。发现费用变动时创建任务中心任务 + 飞书通知。
每天 06:00通过 Amazon Sales API 同步近7天和30天日均销量，重新计算所有商品的FBA可售天数和综合可售天数。
每天 08:00①全量同步FBA库存（可售/待调仓/处理中/入库中）；②8级库存预警检测，生成每日补货报告；③飞书推送汇总消息。
每天 13:00与01:00链式同步的 Step 1 相同逻辑，确保当前售价和定价每天更新两次。独立运行，不触发费用/订单重算。
每3分钟从 SP-API 拉取新增/更新的订单，自动关联商品主数据计算费用和利润。采购成本按快照锁定（详见「采购成本锁定」章节）。
每 30 分钟扫描所有 Pending/Unshipped 订单，逐条调 SP-API 重拉最新状态 + OrderItems（含真实 ItemPrice/ItemTax/PromotionDiscount/PointsGranted）。关键任务 ：删除此任务会导致销售额 + 利润数据系统性偏高 10-15%（已发生过事故，详见 2026-05-22 更新记录）。
每周日 02:30更新商品名称（name_ja）、主图、重量、尺寸等低频变化字段。使用 Catalog Items batch API（20个/批）。仅更新空值或有变化的字段。
每 40 分钟Amazon Ads V3 报表 5 个并发拉取（仅今日）：spCampaigns + spAdvertisedProduct + spKeywords + spSearchTerm + spPlacement。单次耗时 10-25 分钟，40 分钟间隔保证不重叠。
每天 02:30调 chat_assistant Agent（默认 DeepSeek V4 Pro）生成 3-5 句运营建议，缓存到 system_settings.ad_ai_brief_<date>。看板页自动读取。
每天 04:30拉取所有 SP Campaign 的 KW / Target / ProductAd / NegKW 列表（list 接口，非报表），保证结构层数据完整。
每天 05:00同 40 分钟任务，但拉昨日+今日 2 天。兜底保证全天数据完整（防 40 分钟任务被中断）。
每 6 小时同步 Campaign 状态/预算/竞价策略等元数据。
每小时 :15遍历所有启用规则，按 freq + last_run_at 决定是否真跑。匹配则执行（auto）或生成待审批建议（suggest）。
实时Amazon Marketing Stream → SQS Consumer 实时推送，写入 ad_stream_hourly（店铺级别小时数据，1-15 分钟延迟）。看板 24h 热力图用此数据源。
广告数据时效性说明
为什么 40 分钟 V3 报表本身是异步生成（1-15 分钟），加 5 个报表并发约耗 10-25 分钟。40 分钟间隔确保完成+缓冲，且不会被 API 配额限流
为什么不更快 ① 报表生成本身有冷却 60 秒；② 数据本身有亚马逊后端聚合延迟（1-3 小时），更频繁也拿不到新数据
如何即时查看 ① 看板 KPI / 趋势图 → 用 AMS 实时流（店铺级别）；② Campaign/商品级别 → 等下次 40 分钟同步
数据正确性 所有 V3 报表用 ASIN×Campaign×AdGroup 4 维度严格归集，不再有跨 Campaign 累加错误
手动触发
同步全部商品数据 商品页「↻ 同步」下拉菜单第一项。等同于链式同步全流程（ERP→售价→费用→订单重算），后台串行执行
同步ERP数据 商品页「↻ 同步」下拉菜单。仅同步采购价+中文名+FBM库存
同步FBA库存 库存管理页面按钮。同步完成后自动执行预警检测
单品同步 商品详情页「↻ 同步数据」按钮。同时触发Amazon + ERP单品同步（含售价/费用/库存）
订单同步 订单页「↻ 同步」按钮。立即拉取最新订单
重算费用 订单页「
断电/断网恢复机制
所有每日任务设置 12小时宽限期 。断电或断网恢复后，系统启动时自动检查今天的链式同步是否已执行：
读取 sync_task_log 表中各步骤的最后成功时间
如果今天 01:00 之后没有成功记录 → 立即串行补跑整条链
补跑严格按依赖顺序（ERP→售价→费用→重算），不跳步
12小时内重启都会自动补执行，不会遗漏
并发防护
系统使用 6组模块级锁 （erp / price / fees / inventory / orders / chain）防止手动按钮和定时任务同时操作同一数据：
手动点击「同步全部商品数据」时，如果链式同步正在运行 → 自动跳过，不重复执行
单品同步和批量同步共享锁，互斥不冲突
Product Fees API 限速 0.1 req/s，两个并发调用会触发限流 → 锁机制避免此问题
同步方式说明
增量 订单同步记录上次同步时间戳，只拉取之后新增/更新的数据
逐SKU FBA库存遍历所有在售商品，逐个SKU查询最新FBA库存
逐条码 ERP同步遍历有条码的商品，逐个条码查询ERP采购价和FBM库存
逐ASIN 售价/BSR遍历所有在售商品，逐个ASIN查询Catalog API获取售价和BSR排名
轮转+填充 FBA费/佣金优先填充fba_fee或referral_fee为空的商品，然后按最久未检查排序轮转
商品主数据各字段之间存在计算依赖关系，必须按正确顺序同步才能保证数据一致。
为什么需要链式同步
商品数据存在依赖链：售价 → FBA费/佣金 → 订单利润 。FBA配送费和销售佣金的计算需要传入当前售价，如果售价还没有更新就去算费用，得到的就是基于旧售价的错误结果。同理，订单利润依赖最新的费用数据。
依赖链与执行顺序
Step 0: ERP采购成本 （无依赖）
→ 采购单价、中文名、FBM库存
Step 1: 售价/BSR （无依赖）
→ price_jpy（当前售价 / BuyingPrice）、reference_price_jpy（定价 / 商家定价）、BSR排名
Step 2: FBA费+佣金 （依赖 Step 1 的最新售价）
→ fba_fee_jpy、referral_fee_jpy
Step 3: 订单费用重算 （依赖 Step 0+1+2 的全部最新数据）
→ 近7天订单的费用和利润
字段数据来源与同步频率
字段
数据来源
自动同步
手动触发
当前售价 (price_jpy) My Price API BuyingPrice → Competitive Pricing 兜底 01:00 + 13:00 同步全部 / 单品同步 定价 (reference_price_jpy) Catalog API purchasable_offer（商家定价，不参与利润计算） 01:00 + 13:00 同步全部 / 单品同步 BSR排名 Catalog API salesRanks 每天01:00 同步全部 / 单品同步 FBA配送费 Product Fees API · FBAFees 每天01:00 同步全部 / 单品同步 销售佣金 Product Fees API · ReferralFee 每天01:00 同步全部 / 单品同步 采购单价 自有ERP · R_Cost 每天01:00 同步ERP / 同步全部 / 单品同步 FBM库存 自有ERP · Orderable 每天01:00 同步ERP / 同步全部 / 单品同步 FBA库存（6项细分） FBA Inventory API 每天08:00 同步FBA库存 / 单品同步 日均销量 Amazon Sales API 每天06:00 单品同步 商品名/图片/尺寸/重量 Catalog Items API 每周日02:30 单品同步
排除规则
组合商品 is_bundle=true 的商品无独立ASIN，跳过Amazon同步（仅同步ERP成本，按子件汇总）
父ASIN is_parent_asin=true 的虚拟变体容器不可购买，跳过售价/费用同步，节省API配额
订单中的采购单价必须以订单时间节点的采购单价记录，不能因后续采购价变动而改变。
设计原理
采购成本频繁变动（不同批次进价不同），如果所有订单都用当前最新采购价计算利润，历史订单的利润数据就会失真。例如采购价从100涨到150，旧订单的利润不应该因此变少。
因此每个订单项增加了 unit_cost_snapshot_jpy（采购单价快照）字段，一旦记录就永不覆盖 。
锁定规则
场景
行为
新订单，商品已有采购价 立即锁定当前采购单价到快照 → 永不变更 新订单，商品暂无采购价 快照留空，等ERP同步到采购价后由「订单费用重算」首次填入并锁定 重算订单，快照已有值 不覆盖 ，继续用快照计算（即使当前采购价已变）重算订单，快照为空 用当前最新采购价首次填入并锁定 采购价从100涨到150 旧订单保持100，新订单锁定150
不锁定的字段
FBA配送费 和销售佣金 始终用最新商品主数据更新，不做快照锁定。原因：这两项由亚马逊决定，可能随时调整费率，应该反映最新实际成本。只有采购成本是自有ERP的历史数据，需要锁定在订单时间点。
注意： 如需修正某个订单的采购成本（如录入错误），需直接在数据库中修改 unit_cost_snapshot_jpy 字段，系统不提供UI修改入口以防误操作。
当前系统各模块的数据接口说明。
Catalog Items API 商品名称、图片、BSR排名、类目、尺寸、重量（每日链式同步 + 每周低频刷新）
Product Fees API FBA配送费 + 销售佣金（ReferralFee），每日链式同步轮转检查
Competitive Pricing API 售价兜底：当 Catalog API 无 list_price 时，从竞争价格接口获取售价
FBA Inventory API FBA库存明细（可售/预留/入库中），逐SKU查询
Orders API 订单增量同步（每3分钟），含订单明细和费用
Sales API 近7/30天销量、本周销售额（每天06:00同步）
自有ERP API 货品采购成本、FBM库存数量、头程运费（每日01:00链式同步）
亚马逊广告API 广告活动数据、出价/预算直接操作（接入中）
已停用 领星ERP API — 商品/库存/销售同步（2026-03-31 停用）
FBA配送费的计算依据和变动检测原理详解。
费用计算依据
亚马逊根据商品的实测尺寸 和重量 确定配送费档位。当亚马逊对仓库内商品进行重新测量后，若测量结果与原记录不同，会自动调整配送费，且不主动通知卖家。
系统检测逻辑
每日 01:00 链式同步 Step 2：对所有商品调用 Product Fees API，同时获取 FBA配送费 + 销售佣金（ReferralFee）
优先处理「填充模式」：FBA费或佣金为空的商品先批量填充，再轮转检查已有费用的商品
按「最久未检查」顺序轮转（非随机抽查），确保所有商品定期覆盖
差异超过 5% 且 ≥ ¥10 时判定为有效变动（过滤微小波动）
发现变动 → 更新数据库 → 任务中心创建任务 → 飞书推送通知
每日 03:00 有备份同步任务：若链式同步 fees 步骤当日已成功，备份任务自动跳过
API速率限制
Product Fees API 0.1 req/s（每次请求后等待约10秒），每批处理10件
Catalog Items API 约2 req/s（较快），用于抓取图片/尺寸数据
通过飞书自定义机器人 Webhook 分频道接收运营提醒，不同类型的通知推送到不同的飞书群。
频道与分类
系统预设 3 个默认频道，每个频道绑定不同的通知类别：
广告熔断、库存紧急、系统异常 → 推送到告警群
每日报告、AI分析报告、FBA运费变动 → 推送到日报群
操作日志 → 推送到日志群
7 种通知类别
ad_fuse
stock_urgent
system_error
daily_report
ai_report
fba_fee_change
operation_log
推送逻辑
系统调用 send_notification(text, category) 发起推送
在 notification_channels 表中查找 enabled=True 且 categories 包含该 category 的频道
匹配到多个频道 → 同时推送到所有匹配频道
没有匹配 → 兜底发到第一个有 Webhook URL 的频道
没有任何频道 → 回退到旧 feishu_webhook_url 配置
每次推送都记录到推送日志（notification_logs 表）
配置方法
进入「系统设置」→ 飞书推送通知 区域
点击「初始化默认频道」创建 3 个默认频道
为每个频道填入对应飞书群的 Webhook URL
可自由添加/编辑/删除频道，调整类别绑定
点击「测试」按钮验证推送是否正常
统一查看系统运行过程中产生的各类日志，便于问题排查和运营监控。
日志分类
飞书推送记录（成功/失败/内容）
数据同步记录（链式同步/FBA库存/FBA费用等）
订单增量同步记录
广告API调用记录
API异常、未处理错误等系统级事件
用户操作记录（修改设置等）
⏰ 定时任务 APScheduler 定时任务执行记录
日志级别
INFO 正常运行信息（同步完成、推送成功等）
WARNING 警告信息（推送失败、非关键错误）
ERROR 错误信息（同步异常、API调用失败）
CRITICAL 严重错误（系统级异常）
功能说明
统计卡片 ：显示过去24小时的总日志数、错误数、推送数、同步数筛选 ：支持按分类、级别筛选，支持关键词搜索和日期范围详情展开 ：点击表格中的行可展开查看完整日志内容错误高亮 ：ERROR/CRITICAL 级别的行自动红色高亮自动捕获 ：全局异常中间件自动捕获未处理的API错误并写入日志