MoShiro/web/README.md

前端

两个独立的 Vite + React + TypeScript 工程，共享 shared/（主题令牌、API 客户端与类型、图表、通用组件）。

目录	内容	访问
display/	展示端：Agent 卡片总览（线路质量 + 主机资源占用，实时刷新）、线路详情（延迟、丢包、抖动、TCP、UDP、评分、历史）、线路对比	/，匿名可看；站点没有公开时提示登录
admin/	管理端：Agent（添加、审批、启停、接管、删除、加入令牌）、线路画板（节点拖动、画布平移缩放、有向连接状态、方向开关与重试）、任务、按需测试、系统（设置、版本与更新、API 令牌、用户、事件、原始数据、分析）	/admin/，要登录
shared/	theme/（「纸墨」主题令牌和基础样式）、api/（客户端、从 OpenAPI 生成的类型）、charts/（uPlot 封装）、ui/（通用组件）

npm install                    # 在 web/ 下一次装好两个工程的依赖（npm workspaces）
npm run dev                                            # 两个一起启动：展示端 http://localhost:5173/ ，管理端 http://localhost:5173/admin/（也可以直接开 5175）
BACKEND_URL=https://mo.oeo.one npm run dev:display     # http://127.0.0.1:5173/
BACKEND_URL=https://mo.oeo.one npm run dev:admin       # http://127.0.0.1:5175/admin/
# 或者把 .env.example 复制成 .env.local，写好 BACKEND_URL，之后直接 npm run dev:display
npm run build                  # 各自输出到 display/dist 和 admin/dist
npm run gen:api                # 后端接口变了之后，重新生成 shared/api/schema.ts
npm run lint:css               # 颜色只能写在 shared/theme/tokens.css，其他样式一律引用令牌

连别的后端（本机跑前端、连线上的）：登录页左边选后端（这个页面自己所在的、保存过的，或者「添加后端」），右边都是用户名和密码；添加后端填地址、用户名、密码，登录成功才保存。跨域用不了 Cookie，所以登录时后端会返回会话令牌（return_session），前端存在浏览器里、之后每个请求带上，12 小时过期、退出登录即作废；用户看不到也不需要管它。后端需要放行这个页面的来源（MoShiro__CorsOrigins）。展示端和管理端侧栏的插头图标是同一个切换器。

约定：

• 总览、线路详情、对比和管理端按需测试均可切换 IPv4 / IPv6；查询和测试结果独立。管理端 Agent 编辑页分别配置 IPv4、IPv6 地址，IPv6 留空只采 IPv4。展示端只显示地址族，不显示 IP。
• 展示端能拿到的主机数据只有汇总的数字（CPU、内存、磁盘占用，网卡累计流量与瞬时网速，运行时长），没有 CPU 型号、主机名、网卡名，也没有任何 IP——后端的公开接口不返回它们，Agent 也根本不采集。展示端不显示 节点的来源地址（这些只在管理端）。
• 线路详情页：先选哪一天（前一天 / 后一天 / 日期选择，URL 的 day=YYYY-MM-DD），下面是这一天的丢包缩略图，上面有可拖动的选区（拖空白处新建、拖两边调长短、拖中间平移；URL 的 at=起_止，单位是从选中那天 0 点算起的分钟，可以是负数或超过 1440）。缩略图的刻度缺省是 48 小时（连续两天，选区可以跨零点，比如晚高峰 20:00 到凌晨 02:00），也可以切成 24 小时（只看一天；URL 的 span=24，选区跨零点时自动用 48 小时）。刻度下方是选区长度：30 分钟、1 小时、3 小时、6 小时、12 小时、整天，点一下把选区设成这么长——今天且选区到现在为止的，继续看「最近一段」（实时刷新），否则保持选区的起点往后取。刻度上每小时一根短线，48 小时刻度每 3 小时标一个钟点（24 小时刻度每 2 小时），零点标日期；鼠标移到缩略图上会标出那个位置的时间；点一下空白处或者刻度下面的钟点：离那里近的端点（左端或右端）贴过去，另一个端点不动。鼠标停在轴上或刻度上时，会动的那个端点变色，它到目标位置之间染色：扩大是橙色，收缩是灰色。往日默认是整天；「整天」是本地时区的自然日。时间的文字不写「次日」，跨零点两头都写日期（2026年10月5日 21:06 – 2026年10月6日 02:31）。
• 图表上方有 EWMA 平滑开关（关、轻 α=0.3、中 α=0.1、重 α=0.03；URL 的 ewma=low|mid|high）：开了之后每条线画成指数加权移动平均，原始数据以淡线垫在后面，缺口处断开；只在浏览器里算，不影响汇总的指标数字。
• 图表在数据刷新（轮询、实时）时原地更新，不重建；拖选区时只在本地更新，松手才取数。
• 总览是卡片，Agent 主机状态通过 SSE（/api/public/live?topics=hosts）实时更新，其余每 10 秒刷新。
• 生产部署时，把 display/dist 放在站点根、admin/dist 放在 /admin/ 下（同源，Cookie 和 CSRF 才能工作）。

管理端线路画板：拖动 Agent 卡片调整位置，拖动空白处平移，滚轮或工具栏缩放；「显示全部节点」恢复可见范围，「重置布局」恢复默认排布。点击带箭头的连线，在右侧面板调整当前方向的开关、恢复自动或立即重试。节点位置按后端地址保存在浏览器中；节点聚焦后可用方向键移动。Agent 详情中的拨出连接继续使用紧凑表格。