深色
连接监控
这页是 CC WMS 跟各电商平台（Takealot、Amazon、Makro，Temu 预留）之间的「电话线总机」：一眼看出每条连线还通不通、订单有没有正常进来、要不要你去处理。它只「看管道」和「设连线钥匙」，绝不碰货也不碰钱——没有任何按钮会改平台上的库存或价格（那是别页的事）。
谁会用到：业主 Nate / 管理员（admin）。导出报告与新增/编辑连线仅 admin 可成功。
🧠 这一页的原理（白话）
CC WMS 要替你管平台库存，前提是先「连得上」平台服务器（拉得到订单、之后能推库存）。每条连线靠一把「钥匙」（API Key／登入资讯）去平台后台读资料。这页把每条线的健康状况摊开：最上面那条彩色横幅是「自动帮你算好的总结」（绿=没事/黄=待关注/红=要处理），不发新请求，纯把下面已抓回的只读数据聚合成一句结论。钥匙都加密存进资料库，传出后看不到。所有写入动作都会留 audit log（谁在何时做了什么）。重点观念：状态药丸不是「此时此刻」的即时值，是「上次健检当下」的结果；想知道现在通不通，点测试钮重测最准。
🖱️ 画面上的东西（分页 / 按钮 / 栏位）
| 类型 | 名称 | 是什么 | 点了 / 用了会怎样 | ⚠️ 注意 |
|---|---|---|---|---|
| badge | 全系统健康横幅（绿/黄/红） | 一整条会变色的横幅，把所有平台状况浓缩成一句结论＋一个颜色：绿『系统连接正常』、黄『连接有待关注项』、红『连接异常，需立即处理』。后面一行灰色小字会指名道姓讲是哪个平台、什么原因（例『Makro 会话仅剩 2 天到期，请尽快续期』），照那句去处理就对了。 | 纯展示，不可点。系统前端自动算（不发新请求）。绿就安心关掉这页；黄/红读后面小字照办。 | 黄色多半是『30 分钟刚好没新单』这种正常起伏，不要一变黄就驚慌找工程师——先点该帐号的测试钮，回✓就是没事。 |
| badge | Makro 会话 N 天到期（横幅右侧膠囊） | 显示 Makro 登入凭证还有几天过期，≤3天红、≤14天黄、其余绿。只有设了 Makro 才出现。 | 纯展示，不可点。GET /connector/makro/session-expiry | Makro 靠『登入状态』抓单，过期没重登订单会悄悄断掉、不会自己叫——这颗倒数就是催你续期。看到剩 N 天要安排找工程师重抓登入。 |
| badge | 『14 天订单』迷你长条图 + 今日 N | 近 14 天每日订单量的小柱状图，最后标今天的订单笔数。滑鼠移上去提示『近 14 天每日订单量』。有数据才出现。 | 纯展示，不可点。可瞄一眼最近生意量有没有突然掉到 0（掉 0 常代表进单断了）。GET /orders/stats/summary | |
| button | 导出连接报告 | 标题列右侧按钮（下载图示）。下载一份 Excel 能开的 CSV（档名 connector-report.csv，中文回退『连接报告.csv』）：每个帐号的平台/帐号名/网址/状态/是否只读/上次健检时间/建立与更新时间。 | 点了向后端要 CSV 并自动下载。下载中按钮变『导出中…』且不可重复点；失败跳灰色提示『导出失败：…』。仅 admin。非破坏性（只读取）。GET /connector/export | 档案里『不含任何钥匙/密码』，可安心存档或寄出；它只是『我接了哪些平台、状态如何』的清单，不能拿去还原连线。 |
| button | 新增连接 | 标题列右侧蓝色主按钮（加号图示）。 | 点了弹出『新增 / 更新平台连接』弹窗。按钮本身不改数据，只开窗。 | |
| badge | 数字卡『连接帐号』 | 接的平台帐号总数，下方小字『N 在线 · M 只读』。『在线』=状态 active 的帐号数；『只读』=开了 Shadow Mode（只记录不推送）的帐号数。 | 纯展示，不可点。GET /connector | 『在线』与『只读』是不同维度、不互斥——一个帐号可以『既在线又只读』（连得上但只看不动），不是自相矛盾。 |
| badge | 数字卡『异常连接』 | 异常帐号数。>0 时黄色字『需关注』；=0 时灰色『全部正常』。 | 纯展示，不可点。 | |
| column | 『订单同步运行状况』卡 | 副标『各平台实际同步方式：实时优先（webhook），定时轮询补救』。每平台一行：状态药丸（绿『正常』/红『异常』/灰『从未运行』=这个定时任务还没跑过）＋该平台真实同步方式（写死对照：Takealot『Webhook 即时+5分钟轮询补救』、Amazon『Webhook 秒级(FBM)+5分钟轮询补救』、Makro『每 1 分钟轮询（无 webhook）』）＋本次拉单几笔＋上次执行时间。异常时显示红色错误短讯（截前 60 字）。只有拿到 poll 数据才显示。 | 整张卡纯展示，没有按钮。GET /connector/poll-status | Makro 一直『轮询』不是坏了——Makro 天生没有实时通知，本来就只能每 1 分钟自己去撈，显示『轮询』属正常运作。（webhook＝平台主动推订单给我们；轮询＝我们每隔几分钟主动去问平台有没有新单） |
| badge | Makro『下次抓单倒数』（蓝色 ⏱ 字） | 只有 Makro 会出现。一般显示『下次约 N 分钟后抓单』，快到时『即将抓单…』；若正在退避中（被平台挡、冷却中）优先显示『退避中 · 约 N 分钟后重试』。倒数每 20 秒自己递减一次（前端本地计时，不重打 API）。 | 纯展示，不可点。抓单时间故意加 3-10 分钟随机抖动，避免被反爬辨识出固定节奏。 | 看到『退避中 · 约 X 分钟后重试』代表平台暂时挡了我们、系统在禮貌性冷卻，会自己过一阵子再试，不用管它。 |
| column | 『实时推送 vs 补救撿回』卡 | 看订单是『平台秒级主动通知』进来的，还是『我们自己事后去撈』补回来的。每平台/泳道一行：有 webhook 的（Takealot、Amazon-FBM）显示『实时推送 N · 补救撿回 M』+药丸『漏接率 X%』（>20%红、>5%黄、否则绿）；Amazon FLEX 泳道显示『轮询覆盖 N 笔』+绿药丸『Amazon 不推送·轮询正常』；无 webhook 的 Makro 显示『轮询 N 笔（无 webhook，全靠轮询属正常）』；每行右侧『近 24 小时共 N 笔』。统计窗=最近 24 小时内下单的订单。无数据时显示空状态文字。 | 整张卡纯展示，无按钮。已有专属手冊（02），细节看那份。GET /settings/ingest-stats | 这是上线前最该看的一张卡——回答『平台的实时通知到底可不可靠？我那 5 分钟轮询补救够不够快？』。漏接率越低越好；且只有 Takealot/Amazon-FBM 才有意义，Makro 和 Amazon-FLEX 本来就全靠撈、没有漏接率可言，不该在那两列看到漏接率红字。 |
| tab | 筛选分页『全部 / 异常 / 在线 / 只读』（带数字徽章） | 全部=所有帐号；异常=状态 unhealthy；在线=状态 active；只读=开了 Shadow Mode。 | 点了只是切换下方清单的筛选，不改数据、不发请求（纯前端）。 | |
| field | 搜索框 | 占位字『搜索帐号 / 平台…』。 | 输入会即时过滤下方清单（比对帐号名或平台名，不分大小写）。纯前端筛选，不发请求。 | |
| badge | 帐号卡状态药丸 + 只读标签 | 每张帐号卡上：平台图示→帐号名（等宽字体）→状态药丸（绿『在线』=上次测试连得上 / 红『异常』=上次测试连不上 / 灰『停用』=连线被关掉）→蓝色『只读 (Shadow Mode)』标签（只有开了只读才出现，代表只看不动、绝不把库存或价格写回平台）→右侧网址。 | 纯展示，不可点。GET /connector | 状态不是此时此刻的即时值，是上次健检的结果；想知道现在通不通，点测试钮重测最准。 |
| badge | 帐号卡『最近成功拉单 X 分钟前』 | 粗体显示该帐号最近一次『成功拉单』是多久前（分钟/小时/天前）。这是『连线还活着』的真证据，刻意放大显示。超过 30 分钟没拉到会转黄色提醒；从无记录则灰色『尚无拉单记录』。下方更小灰字是『健检 时间』或『从未健检』（次要资讯）。 | 纯展示，不可点。GET /connector/sync-status | 这个时间比『健检时间』更重要——它才是连线活着的真证据。 |
| button | 测试连接（同步箭头钮） | 帐号卡右侧按钮，hover 提示『测试连接』。点测试后会出现即时字：成功『✓ 123ms』（绿，含延迟毫秒）/失败『✗ 异常』（红）。测试中按钮停用。 | 点了真的当场去敲该平台 API 做一次健康检查、量延迟（挑最省流量不写入的探针：Takealot GET /status、Amazon 空时间窗 GET orders、Makro GET get-locations）。POST /connector/:platform/:account/health | ⚠️会写入：结果会回写并改掉这个帐号的状态——通得过→标 active(在线)、通不过/401/403→标 unhealthy(异常)，让卡片状态药丸当场变色，并写一条 audit log（谁在何时把连线打成异常都有记录）。不是纯只读，但安全可点（不碰平台库存/价格），是你手动确认某条线还通不通的工具，排查时先点它。 |
| button | 编辑连接（齿轮钮） | 帐号卡右侧按钮，hover 提示『编辑连接』。 | 点了打开同一个弹窗的『编辑』模式（平台与帐号名锁定不可改，只能换钥匙/网址/只读开关）。开窗本身不改数据。 | 🚨 编辑时最大的坑：弹窗为了安全『不会把旧钥匙显示出来』（栏位是空的），所以一按『保存修改』就一定得把钥匙重新贴一次，否则会失败（『API Key 为必填项』）。若只想改网址却没钥匙可贴，先别按保存、直接取消，免得把好好的连线弄断。 |
| field | 弹窗：平台下拉 + 帐号名称 | 平台下拉 Takealot/Amazon/Makro/Temu（换平台会自动带入该平台预设网址）；帐号名称输入框占位『e.g. Miui / B2B / MAIN』，Amazon 时占位『e.g. A3JCE…（Seller ID）』、不填则为 default。 | 新增时可填；编辑模式下平台与帐号名称都锁定/唯读（变灰），要换平台或帐号得用『新增连接』开新的。 | |
| field | 弹窗：各平台钥匙栏（密码框） | 依平台不同：Takealot 单一『API Key』；Amazon 三件套『LWA Client ID / Client Secret / Refresh Token』（上方蓝灰说明 LWA 三件套、加密保存传输后不可查看）；Makro『登入 Session（JSON，由 CC 提供）』多行文字框（贴一整包含 sessionToken/connectSid/sellerId 的 JSON）＋选填『Makro API Key / Secret』（标注 Phase 2 推送用现在不启用）。 | 贴入钥匙。Amazon 三栏都要填，Makro 要贴工程师从浏览器抓好的整段 JSON。 | 格式错会在按钮旁显示红字，例『Makro Session 格式错误：请贴上 CC 提供的完整 JSON』『Makro Session 缺少 T / connect.sid / sellerId』『Amazon 需填写 client_id、client_secret 与 refresh_token 三项』。钥匙加密后存库、列表/导出永不回传、传输后不可查看。 |
| field | 弹窗：Base URL | 对接网址。Amazon / Makro 唯读且变灰（标『系统已内置正确网址，忽略此栏』），Takealot 可改。 | Takealot 可改；Amazon/Makro 不用动。 | |
| field | 弹窗：勾选框『Shadow Mode（只记录，不实际推送）』 | 勾起＝这条连线只读、不会真的把库存/价格写出去到平台（存了才生效，帐号卡上会显示蓝色『只读 (Shadow Mode)』标签）。 | 上线测试前/只想先读资料验证→勾（安全）；已跟工程师确认要正式开推→才不勾。 | ⚠️与 2026-06-21 上线测试直接相关：这是『拿真钥匙、但先不真的写出去』的安全保险丝。先勾着验证算出来的库存数对不对，确认无误、由工程师确认后才取消勾选让它真的推。不要由 Nate 自己提前在这页拿掉。 |
| button | 弹窗底部『取消』/『保存连接』『保存修改』 | 取消=关窗、清空已填内容、不保存。保存=蓝色 accent 按钮。 | 按保存通过校验后：把钥匙加密存进资料库（新增或覆盖同平台同帐号设定）、该帐号状态设为 active、写一条 audit log，成功跳绿色 toast『平台/帐号 连接已保存/更新』并关窗刷新清单。POST /connector | ⚠️会写入（真正的写入动作）：必填没填齐（Base URL、钥匙；Amazon 还要 client_id/secret）按钮会灰掉。仅 admin 可成功。注意：保存『本身不会立即去打平台』，只是存设定；真正连平台是后续『测试连接』或排程轮询时才发生。 |
| badge | 绿色成功提示条（toast） | 操作成功后短暂出现，例『✓ takealot/Miui 连接已保存』。 | 纯提示，会自己消失。 | |
| badge | 加载/空状态文字 | 载入时卡片显示『加载中…』；完全没设连线显示『尚未设置任何平台连接 — 点击「新增连接」添加』；有连线但筛选无结果显示『无符合条件的连接』。 | 纯展示。 |
⚠️ 注意事项 / 别踩的坑
- 这页『没有』任何删除/停用连线的按钮——帐号卡上只有『测试连接』和『编辑连接』两颗。后端虽有停用连线的能力（软删除 DELETE /connector/:platform/:account），但前端介面没接这颗按钮。教学里绝不要写『点 X 删除连线』之类不存在的操作。
- 这页也没有任何『立刻推库存/改价』的可点按钮——真实写入线上平台（推虚拟库存、比价改价）是别页的事，不会在连接监控页发生。可以放心点这页任何东西。
- 状态药丸（在线/异常/停用）不是『此时此刻』的即时值，是『上次健检当下』的结果。想知道现在到底通不通，点测试钮重新测一次最准。
- 编辑连接最容易踩的坑：弹窗不会显示旧钥匙（栏位空的），一按『保存修改』就必须把钥匙重贴一次，否则失败。若只想改网址却没钥匙可贴，先别按保存、直接取消，免得弄断好好的连线。编辑时平台和帐号名也锁死改不了。
- 『在线』与『只读』是正交两维、不互斥：active 是连得上、shadow_mode 是写不写，一个帐号可以既在线又只读。看到『N 在线 · M 只读』不是矛盾。
- 漏接率只对有 webhook 的平台（Takealot、Amazon-FBM）有意义；Makro 无 webhook（全靠轮询=正常）、Amazon FLEX Amazon 不推送（全靠轮询=正常），这两者不算漏接、不进漏接率计算，否则全是假警报。
- Makro 是静默超卖风险源：靠登入 cookie 拉单，到期没重登或被你（Nate）亲自登入 Makro 后台踢掉，订单同步会『悄悄中断、不会自己叫』，库存不减就会超卖——所以会话到期倒数同时出现在健康灯（红/黄）和右上角药丸，3 天内会变红催你续期。
- 导出报告的 CSV 不含任何钥匙/密码（后端 SQL 只选非密钥栏位），可安心传，但也别误会它能拿去还原连线——它只是一份状态清单。
✅ 怎么操作（步骤）
- 任务A（每天 30 秒巡田，最常做）：左侧选单点『连接监控』→只看最上面那条彩色横幅。绿→收工，这页不用再看；黄/红→读后面那行小字（它会讲哪个平台、什么事），照着做（多半是『点该帐号测试钮』或『安排续 Makro 登入』）。可顺便瞄一眼右边『今日 N』订单数有没有怪异掉到 0。
- 任务B（新增一条平台连线）：右上角『新增连接』→选平台→填帐号名称（不填自动叫 default；Amazon 建议填 Seller ID）→贴钥匙（Takealot 一把 API Key；Amazon 填三样 Client ID/Client Secret/Refresh Token；Makro 贴工程师从浏览器抓好的整段 JSON，下面官方 Key/Secret 现在用不到留空）→决定要不要勾 Shadow Mode（上线测试前或只想先读→勾，安全）→按『保存连接』，成功跳绿色『✓ … 连接已保存』→回清单找到新卡片，点测试钮确认显示『✓ 几毫秒』才算真的接通。
- 任务C（某平台变红/变黄，自己先查一轮）：横幅小字告诉你是哪个平台→下面筛选鈕点『异常』或直接找到那张卡→点该卡的测试钮：回『✓ 几毫秒』表示其实已经好了（刚才只是暂时的），不用驚动工程师；回『✗ 异常』表示确实断了——看是不是 Makro 登入过期（横幅会讲剩几天）→安排工程师重抓，其它平台多半是钥匙过期→用编辑钮换上新钥匙（记得钥匙要重贴整把）。自己处理不了就把横幅那行中文小字截图给工程师。
- 任务D（导出一份连接清单存档）：右上角点『导出连接报告』（按钮短暂变『导出中…』）→浏览器自动下载 connector-report.csv（Excel 打得开）→里面有平台/帐号/网址/状态/是否只读/上次健检时间，没有任何钥匙密码，可安心存档或寄出。
与 6/21 上线测试有关
2026-06-21 上线测试＝第一次让系统真的对线上平台写东西（推虚拟库存＋线上比价改价）。但这件事『不会在连接监控页发生』，这页全程只读管道或设连线钥匙。这页与上线测试唯一直接相关的元素是『Shadow Mode（只读）』：保持帐号卡上的蓝色『只读 (Shadow Mode)』标签＝系统连着真平台但『只看不动』，先验证算出来的库存数对不对、测资料流不会误伤线上。鐵则：上线测试前不要由 Nate 自己手癢去关掉任何 Shadow Mode——要正式开推时，是由工程师确认后才在对应帐号取消勾选。另：Makro 目前根本没有写出去的程式路径（Phase 1 天然安全），所以正式开推主要影响 Takealot 与 Amazon。『测试连接』钮会改写帐号状态(active↔unhealthy)并留 audit，但不碰平台库存/价格，上线前后都可安心点用来确认连线。