设置

这页是系统的「总开关房 + 保险丝盒」：管「谁能登入系统、跟四个电商平台对接的钥匙、要不要真的把库存和价格推上平台、以及一堆系统数字旋钮」。6/21 第一次连真实平台测试前，最该先搞懂这页「安全」分页里的两个总开关——它们是「先空跑、确认没问题再真的动平台」的安全绳。

谁会用到：管理员（admin）为主——新增/改使用者、增删改平台连接、切只读/推送模式、改系统参数，后端全部只允许管理员。操作员（operator）能进来看、按「测试连接」、查待推数量和 Makro 会话倒数，但改不了上述设定。

🧠 这一页的原理（白话）

这页分四个分页（使用者 / 平台连接 / 安全 / 系统参数），点到哪个分页才去后端抓那一块资料（懒加载＝用到才载，第一次打开会短暂出现「加载中…」）。每个写入动作（增删改使用者、停用连接、切只读/推送模式、改参数、测试连接）后端都会写进操作纪录（audit_log＝谁、何时、改了什么、原值→新值、IP），可追溯。最关键的原理：整个系统真正「写到线上平台」的库存推送只有一条路（程式里叫 executePlatformPush，platform-push.ts），这条路上有三道保险——①从没上传过任何 WMS 库存就一律禁推（防把全新 SKU 算成 0 推上去等于下架，独立于任何开关）；②「全局只读模式」开着就只记录不推；③一批推送失败率超过设定（预设 20%）就自动停手。本页「安全」分页的两个开关就是控制第②道，外加一层人工闸（手动推送）。密码存的是搅烂的乱码（bcrypt cost 12），API Key 存的是密文（AES-256-GCM），连管理员都看不到原文。

🖱️ 画面上的东西（分页 / 按钮 / 栏位）

类型	名称	是什么	点了 / 用了会怎样	⚠️ 注意
tab	使用者	列出能登入系统的人：使用者(头像+显示名+登入帐号)、角色(管理员蓝/操作员灰徽章)、所在地(南非UTC+2/中国UTC+8)、最近登录、状态(启用绿/停用灰)。右上「＋新增使用者」钮。预设打开的就是这个分页。	点了切到使用者分页，去后端抓使用者清单(api.listUsers→GET /api/users，后端故意不回传密码) GET /api/users
button	＋新增使用者	使用者分页右上角的钮	弹出「新增使用者」弹窗，填用户名/显示名称/密码/角色/所在地后建立帐号；新帐号预设为启用 POST /api/users (限admin)	密码规则严格：至少12字符，且须同时含大写、小写、数字、特殊符号，缺一项被挡
button	铅笔图示（编辑使用者）	使用者每行最后第一个小钮	打开「编辑使用者」弹窗，可改显示名称/角色/所在地；密码栏留空＝不改密码，填了新密码＝重设并自动解锁(若之前因输错太多次被锁会一并解开)。用户名(登入帐号)不可改 PUT /api/users/:id (限admin)
button	垃圾桶图示（使用者行）	使用者每行最后第二个小钮	这不是删除！是「启用/停用切换」，点一下把这个人从启用改成停用(或反过来)，画面没有二次确认、直接生效。停用后该人无法登入 PUT /api/users/:id 带 active:0 (软删除，资料不删，可复原)	图示长得像删除，其实是停用切换且无确认；停用的人不能登入。后端会挡住停用/删除你自己正在登入的帐号(避免把自己锁在门外)
modal	新增使用者 / 编辑使用者 弹窗	用户名(仅新增时出现，提示3-32位字母/数字/下划线)、显示名称(必填，留空报「显示名称为必填」)、密码(编辑时标「留空则不修改」)、角色下拉(操作员/管理员)、所在地下拉(南非UTC+2/中国UTC+8)。底部「取消」+「新增」(编辑时为「保存变更」，送出变「保存中…」)	填完按右下钮送出；出错时钮左侧出红字(如「用户名和密码为必填」「新增失败」「网络错误，请重试」) createUser / updateUser
tab	平台连接	四张平台卡(Takealot/Amazon/Makro/Temu)。每张显示该平台已连的帐号清单(帐号名、接口网址、添加日期、状态徽章)。Temu卡标灰色「未启用·API暂未开放」且没有新增钮。某平台无帐号时显示灰字「暂无帐号—点击新增帐号添加」	点了切到平台连接分页，抓连接清单(后端只回非机密栏位，绝不回API Key) GET /api/connector
button	＋新增帐号	每张平台卡(Temu除外)右上的钮	打开「新增/更新平台连接」弹窗并预选该平台 打开弹窗→POST /api/connector
button	▶ 播放图示（测试连接）	每个已连帐号那一行的第一个小钮，title「测试连接」	真的去连一次该平台测健康度。测试中图示转圈、钮禁用；测完该行左侧显示结果：成功绿字「✓ 几ms」(毫秒=回应快慢)，失败红字「✗ 错误原因」(拿不到原因显示「连接失败」)。绿色才算连通 POST /api/connector/:platform/:account/health (任何登入者可按)
button	铅笔图示（编辑连接）	每个已连帐号那一行的第二个小钮，title「编辑连接」	打开同一个连接弹窗、带入这个帐号去改(平台与帐号名锁住不可改，凭证须重新输入才更新) POST /api/connector (限admin)
button	垃圾桶图示（连接行）	每个已连帐号那一行的最后一个小钮	会跳浏览器确认框「确认停用 平台/帐号？」，按确定才把这条连接停用(后端标记disabled、软删除资料还在，但系统不再用它拉单/推送)，该帐号从清单消失 DELETE /api/connector/:platform/:account (限admin)	破坏性：把某平台帐号停用＝那个平台不再收订单、不再同步库存，若该平台还在卖可能造成库存不同步甚至超卖。停用前想清楚
badge	影子模式 / 已连接（连接状态徽章）	每个已连帐号行的状态：勾了Shadow Mode显示橘色「影子模式」(只记录不真推)；否则绿色「已连接」	纯显示，标示这个帐号会不会真的推库存到平台
modal	新增 / 更新平台连接 弹窗	会依平台动态变换栏位。共同：平台下拉(编辑时锁)、帐号名称(可留空＝default，编辑时锁)、Base URL、核取框「Shadow Mode(只记录，不实际推送)」、底部「取消」+「保存连接」。凭证栏依平台不同：Takealot/Temu一个「API Key」框；Amazon三个框(LWA Client ID/Client Secret/Refresh Token，三项必填)；Makro一个大文字框贴「登入Session JSON(由CC提供)」+两个选填框(Makro API Key/Secret，Phase2推送才用、现在不会写出去)。Amazon与Makro的Base URL锁住并标「系统已内置正确网址，忽略此栏」	按平台填完→保存。后端把凭证用AES-256-GCM加密后存，按「平台+帐号」做upsert(有就更新没有就新增)。校验：Base URL空报「Base URL为必填项」、Amazon缺三件套报「Amazon需填写client_id、client_secret与refresh_token三项」、Makro Session格式不对报「Makro Session格式错误」或缺字段报「缺少T/connect.sid/sellerId」 POST /api/connector (upsert，限admin)	凭证传输后不可查看(连储存的钥匙都是密文)；不同Amazon帐号可属不同开发者App
tab	安全	四个区块：①全局只读模式(总开关)②推送模式(auto/manual开关+待推数量+立即推送)③Makro登入会话倒数(纯显示)④密码策略/加密·密钥(两张纯展示卡)。这是上线测试最关键的一页	点了切到安全分页，同时抓只读状态、推送模式、待推数量、Makro会话到期 GET /api/settings/read-only · GET /api/settings/push-mode · GET /api/push/pending · GET /api/connector/makro/session-expiry
button	开启只读模式 / 关闭只读模式（恢复推送）	「全局只读模式(安全模式)」卡片的切换钮。状态徽章：橘色「只读模式已开启·不推送平台」或绿色「正常模式·推送已启用」。切换时变「切换中…」	全系统级总开关。开启＝从此系统读取一切正常(收订单、算库存照常)，但绝不向任何平台推送库存/价格(手动与排程两条线同时锁死)；关闭＝恢复推送。无二次确认但会写操作纪录。成功后顶部提示对应文字。这道闸在唯一的生产推送咽喉点生效，开启时只把「本来会推什么」记进push_log供核对、绝不调用任何平台写入API PUT /api/settings/read-only (限admin)；闸点 platform-push.ts isGlobalReadOnly	直接关系6/21上线测试要不要真写平台。测试期想完全不写出去就把这个开着。注意它是「全系统所有平台」一起停推，跟单一帐号的「影子模式」是两个不同层级
button	切换为手动推送 / 切回自动推送	「推送模式」卡片的切换钮。状态徽章：橘色「手动推送·变动累积待确认」或绿色「自动推送·变动即时送出」。切换时变「切换中…」	控制「库存变动什么时候推到平台」。auto(预设)＝算完马上推；manual＝算完先攒着、变动累积成待推清单、等人点「立即推送」才一次送出。切换不影响拉订单与重算库存(那两件事照常每5分钟自动跑) PUT /api/settings/push-mode (限admin)
field	待推送变动：N 个 SKU	仅在「手动推送」模式下，推送模式卡片底部出现的一行文字(载入中显示…)	纯显示。N＝后端算出来、库存值跟上次推上平台的值不一致的商品数(算出来的broadcast_qty≠上次推的last_pushed_qty且未冻结) GET /api/push/pending
button	立即推送	仅手动推送模式下、待推那一行右侧的钮(上传图示)。N=0或推送中时禁用，推送时变「推送中…」	把所有累积的待推变动排进推送队列。成功后顶部提示「已排入推送N个SKU」并重抓待推数字。仍走同一个推送咽喉点，所以「全局只读」和「未上传库存禁推」两道闸照样生效，手动推不会绕过保险 POST /api/push/flush (限admin)	会真的触发对平台的库存推送(除非全局只读开着——只读会把推送拦住只记录)
badge	距 Makro 重新登入剩 N 天	「Makro登入会话」卡片，纯显示无按钮。依状态：未连Makro显示「未连接Makro，暂无会话」；没记到期日显示「会话没有记录到期日—重新登入Makro后会自动记录」；正常显示徽章「距Makro重新登入剩N天」+灰字「到期日YYYY-MM-DD·重新登入需一次OTP」。剩≤30天徽章变红	纯显示。Makro没有官方订单API，靠登入会话(cookie)拉单，约1.5年到期。到期没重登＝订单同步静默中断(不报错、悄悄不收单)＝超卖风险 GET /api/connector/makro/session-expiry	剩30天内顶部铃铛也会出红色告警，看到就尽快重登(需一次手机OTP)。运维坑：Nate本人登入Makro后台会把系统正在用的会话踢掉，导致系统抓不到单，需重新提供会话
badge	密码策略 / 加密·密钥（两张展示卡）	密码策略：最小长度12字符、失败锁定5次/锁15分钟、强制更换每60天、会话超时4小时无操作。加密/密钥：API Key加密AES-256-GCM、密码hash bcrypt(cost12)、HTTPS强制(Cloudflare TLS 1.3)、2FA未启用(Phase2)	纯展示牌、写死的文字、没有后端，点不动。改这里的数字不会改变后端真实行为(真正的密码校验在程式别处)
tab	系统参数	两张并排卡「同步策略」「告警与提醒」，各放若干行可编辑参数。每行：左边标签+说明、中间输入框、右边保存图示钮	点了切到系统参数分页，抓参数(后端把资料库的值和预设值合并，没设过的显示预设值) GET /api/settings/params
field	默认 Safety Buffer	同步策略卡，说明「可对单SKU覆写」，预设值0	每个商品预留不上架的安全库存件数。填越大上架越保守、越不会超卖但可能少卖。绝不可在程式码写死、必须从这里读(系统铁则) PUT /api/settings/params/safety_buffer_default (限admin)
field	Delta Sync 阈值	同步策略卡，说明「变0件跳过」，预设值1	库存变动小于此值就跳过推送(省流量；13000+SKU×3平台若每次全量推会撞平台限流) PUT /api/settings/params/delta_sync_threshold (限admin)
field	对账差异阈值 (件)	同步策略卡，说明「超阈值自动freeze」，预设值5	对账差异超过这个件数会自动冻结(freeze)那个SKU的推送以防出错。不要随便调大——调大等于放宽防呆 PUT /api/settings/params/recon_diff_threshold (限admin)
field	批次失败保护 (%) / 重试间隔 (秒)	同步策略卡。批次失败保护预设20(单批推送失败率超此值就暂停)、重试间隔预设30(推送失败后多久重试)	分别保存 PUT /api/settings/params/batch_failure_rate · retry_interval_secs (限admin)
field	AWS 免费期到期日	同步策略卡，说明「YYYY-MM-DD，首页倒数提醒」，预设值2026-12-10	首页横幅倒数；到期没升级，Amazon即时通道(FBM秒级接单)会停。要填YYYY-MM-DD格式 PUT /api/settings/params/aws_free_tier_expiry (限admin)	日期格式要照规矩，乱填格式系统可能读不懂
field	告警与提醒卡（WMS未更新提醒/Amazon FBM cutoff/覆写到期提醒/告警渠道/日志保留）	WMS未更新提醒(小时，预设48)、Amazon FBM cutoff(出货截止时间，预设12:00)、覆写到期提醒(小时前，预设24)、告警渠道(dashboard,email逗号分隔)、日志保留(天，预设30)	这些多是提醒时机，填错只影响提醒早晚不影响安全。逐项保存 PUT /api/settings/params/:key (限admin)
button	保存图示钮（系统参数每一行）	每行参数右边的小铅笔图示钮	一格一存。改了输入框内容这颗钮才变亮可按(没改时淡灰、禁用、title「已是最新」)；改了title变「保存」，按下去单独存这一格、存时图示转圈。切走分页/关页面没存的就丢了 PUT /api/settings/params/:key (限admin，白名单内才可改、值不可空)	改了不按保存等于没改；不在白名单的参数后端拒绝；空值被挡报「value不能为空」

⚠️ 注意事项 / 别踩的坑

• 使用者行的「垃圾桶」其实是「启用/停用切换」不是删除，且画面无二次确认、点一下直接生效——停用的人无法登入。要彻底分清这跟平台连接行的垃圾桶不一样
• 平台连接行的「垃圾桶」会停用整条平台连接(有浏览器确认框)，停用＝那个平台不再收单/不再同步库存，若该平台还在卖可能造成库存不同步甚至超卖
• 「全局只读模式」(整个系统所有平台一起停推、一个总开关)和「Shadow Mode影子模式」(新增/编辑单一帐号时勾的小框、只挡那一个帐号)是两个不同层级，别搞混；上线测试建议用全局只读当大保险更直觉
• 「安全」分页底部两张卡「密码策略」「加密/密钥」是纯展示牌(写死文字、没后端)，点不动；改不了，看看就好
• 系统参数是「一格一存」，每行右边铅笔钮要改了才变亮，按下去才保存这一格；切走分页或关页面没存的就丢了。后端只允许改白名单内的参数、值不可空、且只限管理员
• 密码规则严格：至少12字符且须同时含大写、小写、数字、特殊符号，缺一项被挡(为通过Amazon安全审查不能放宽)；编辑使用者时密码留空=不改、填了=重设并自动解锁
• 没有「邮件找回密码」(Phase1未做)。操作员忘密码只能由管理员进来手动重设，所以至少要有一个你记得住的管理员帐号否则全员被锁
• Makro登入会话约1.5年到期，到期没重登=订单同步静默中断(不报错)=超卖风险；剩30天内徽章变红+顶部铃铛红色告警。运维坑：Nate本人登入Makro后台会把系统正在用的会话踢掉导致抓不到单，需重新提供会话(重登需一次手机OTP)
• 系统参数UI上Amazon FBM cutoff的提示写「11:00起警告」，但后端这一项的实际预设值是12:00；提示文字仅供参考，真正生效的是输入框里的值
• 新增使用者后端只允许管理员；测试连接任何登入者都能按，但增删改连接、切只读/推送模式、改参数全部只限管理员

✅ 怎么操作（步骤）

1. 【上线测试第一件事·6/21开演练保险】进「设置」→点「安全」分页→看最上面「全局只读模式」卡片状态(绿色「正常模式」代表会真的推平台)→点「开启只读模式」钮(眼睛图示)→钮变「切换中…」后状态转橘色「只读模式已开启·不推送平台」、顶部出现绿色提示「已开启全局只读模式」。完成：现在不管谁、不管排程都不会真推库存/价格上平台，只会记日志，可放心去连真key做验证。全部验证OK要正式上线时回这张卡点「关闭只读模式(恢复推送)」即可
2. 【连一个平台真实API key】(建议先做完上一步开只读)进「设置」→「平台连接」分页→在要连的平台卡右上点「＋新增帐号」→照弹窗灰字提示填(Takealot：帐号名可留空default+API Key；Amazon：帐号名填Seller ID(A3…开头)+三件套LWA Client ID/Secret/Refresh Token；Makro：大框贴CC帮你抓好的session JSON，下方官方Key/Secret选填可不填)→(可选保险)勾「Shadow Mode」让这个帐号也单独停推→点「保存连接」→成功提示后卡片下方出现这个帐号一行
3. 【测试连接是否通】在该帐号那一行点▶(播放图示，title测试连接)→等图示转圈结束→看该行左侧：绿色「✓ 123ms」=连通，红色「✗ 错误原因」=没通。绿色才算成功
4. 【改成手动推送(想先攒变动人工确认再送)】「安全」分页→「推送模式」卡片→点「切换为手动推送」→状态变橘色「手动推送·变动累积待确认」并出现一行「待推送变动：N个SKU」→之后库存有变动不自动送、会累积→想送时点「立即推送」(上传图示)、提示「已排入推送N个SKU」(N=0时钮不可点)→想恢复即时推送点「切回自动推送」
5. 【新增/编辑使用者】「使用者」分页→右上「＋新增使用者」→填用户名(3-32位字母/数字/下划线、建立后不可改)、显示名称、密码(至少12字符且须含大小写+数字+特殊符号)、角色(操作员/管理员)、所在地→点「新增」(新使用者预设启用)。编辑：点该行铅笔图示，可改显示名称/角色/所在地，密码留空=不改、填了=重设并解锁。停用/启用：点该行垃圾桶图示切换(不是真删)
6. 【改系统参数】「系统参数」分页→在某行输入框改数字→该行右边铅笔钮变亮→点它保存这一格(图示转圈代表存中)。注意一格一存、改了不按保存等于没改；不确定一格干嘛的就别动它、保持预设最安全

与 6/21 上线测试有关

6/21第一次连真平台测试，安全顺序：①先到「设置」→「安全」把「全局只读模式」打开当演练(系统照常收单算库存，但绝不向任何平台推库存/价格，只把「本来要推什么」记进push_log供核对)→②到「平台连接」填真实key/Makro session、按▶测试连接确认绿色✓→③观察系统收单、算库存对不对、push_log里「本来要推什么」符合预期→④一切OK再回安全分页关掉只读、最好先用「手动推送」一笔笔放出去(立即推送)、确认无误最后才切回自动。整个系统真会写到线上平台的库存推送只有一条路，路上有三道保险：①从没上传过任何WMS库存就一律禁推(独立于任何开关，防把全新SKU推0等于下架)②全局只读开着只记录不推③一批失败率超过设定(预设20%)自动停手。这三道保险+「全局只读」和「手动推送」两个开关，就是不会一次把库存推爆/改错价的底气。比价改价同理：只读开着时改价也只记录不真改。Temu是预留平台、API未开放、连不了，测试期不用管。