云仓视频溯源系统
前后端分离 + 一个浏览器扩展 + 一个 Windows 本机软件(WPF),四个目录:
packService/
├── backend/ # Egg.js 3(纯 API;MySQL + Redis)
├── frontend/ # Vite + Vue3 + TypeScript(用户端 SPA)
├── extension/ # Chrome MV3 扩展:注入第三方 WMS 页面,把运单号加工成溯源入口
└── desktop/ # WPF 本机软件:本机 HTTP 服务(127.0.0.1:17300)+ yuncang:// 启动协议
端口约定(⚠️ 本机项目多,不要用 Vite 默认的 5173)
| 用途 | 端口 | 启动方式 |
|---|---|---|
| 前端 dev(Vite) | 7301 | cd frontend && npm run dev |
| 前端 preview(dist) | 7302 | cd frontend && npm run preview |
| 后端 dev | 7300 | cd backend && npm run dev |
| 本机软件(WPF,只监听 loopback) | 17300 | cd desktop && dotnet run(详见 desktop/README.md) |
| 扩展自测页(可选) | 7310 | npx --yes http-server extension/test -p 7310 |
- 前端端口可用
VITE_PORT=7303 npm run dev覆盖;strictPort: true→ 端口被占用时直接报错,不会偷偷换端口(否则代理会对不上)。 - 后端端口可用
PORT=7400 npm run dev覆盖(默认 7300,配置在backend/config/config.default.js的config.cluster.listen.port)。 - 前端调接口走同源代理:Vite 把
/api、/health反代到后端(默认127.0.0.1:7300,用VITE_BACKEND覆盖)。 - 联调更方便的做法:直接开后端
:7300,由后端(dev)把/反代到前端 dev server(FRONTEND_DEV_SERVER,默认http://127.0.0.1:7301)。 - 上线:后端托管
frontend/dist(静态资源 + SPA fallback),/出前端、/api/*出 JSON。
身份与通讯约定
| 调用方 | 令牌 | 典型接口 |
|---|---|---|
| 前端 SPA(用户端,toC:用户只管自己的设备/记录) | Authorization: Bearer <user JWT>(typ=user) |
/api/web/*(登录/资料/设备/记录) |
| 设备(扫描枪、中控) | Authorization: Bearer <device JWT>(typ=scanner) |
/api/device/login、/api/scanner/*、/api/scan/* |
| 公开 | 无 | /api/wechat/{login,status,qrcode.svg}、/api/web/auth/* |
前端不用 cookie/session:令牌存本地、放 header,所以没有跨域 cookie 与 CSRF 的问题
(JWT 用 typ 声明隔离:用户令牌调设备接口一律 401)。
当前进度
- 目录拆分为
backend/+frontend/ - 前端脚手架(Vite + Vue3 + TS)跑通,登录页走通
/api/web/auth/* - 浏览器扩展
extension/(MV3,零构建):注入第三方 WMS 页面,在运单号旁边渲染「查看打包视频」按钮 → 点按钮打开溯源页 - 后端去掉服务端渲染:删除
app/controller/page/、app/view/、app/lib/page.js、nunjucks / session / CSRF 配置与依赖,后端只剩 JSON 接口 - 页面全部迁移到前端:登录 / 注册 / 找回密码 / 扫码 / 扫码确认 / 首页统计 / 设备管理 / 扫码记录 / 个人中心 / 测试页
- 后端 dev 反代前端(
app/middleware/frontend.js)+ 生产托管frontend/dist(SPA 深链回退) - 运维接口加鉴权:
app/controller/admin/→internal/,统一挂middleware.internalAuth() - 新增用户端接口:
/api/web/{stats,devices*,records,test/*}(范围一律限定在令牌对应的那个用户) - 扩展:目标地址换成真实打包视频页(现在指向百度占位)—— 在扩展「设置」里改「目标地址模板」即可,需要真实地址
后端接口细节见 backend/README.md,扩展用法见 extension/README.md。
前端页面风格约定(frontend/)
页面的样式规则集中在 frontend/src/styles/main.css,各页只写自己的局部样式。新增页面请照下面这套来(都是前端迁移时逐条定下来的):
- 登录 / 注册 / 找回密码 / 重置密码 / 扫码确认这类「裸页」:居中卡片(
.bare-page+.bare-card,宽 360px)。- ⚠️ 外层不要用
align-items: center:卡片比视口高时顶部会被裁掉且滚不上去 —— 用.bare-card { margin: auto }让它在容器里自己居中,overflow-y: auto兜底;
- ⚠️ 外层不要用
- 表单字段不用
<label>(会把卡片撑高):字段名写进placeholder,「必填 + 说明」用悬浮气泡.field-plain > .tip(position: absolute+opacity/visibility,hover 或聚焦时才显示,不参与布局,所以显不显示都不改变页面高度); - 登录页版面:登录 ⇄ 注册用表单底部的文字链接互换(不放按钮);扫码面板由右上角三角形
.corner-toggle切换,且只在登录 ↔ 扫码之间(注册面板不显示三角);三角形挂在卡片上(.card.bare-card设position: relative+overflow: hidden,让它的直角被卡片圆角裁掉),.panel-switch.is-login/.is-wechat给padding-top: 18px+min-height: 282px(卡片自身 padding 20 + 18 = 38,正好让开三角)→ 登录与扫码同高、同位置,来回切不跳;扫码面板只有二维码 + **「使用微信扫码登录」**一行字;- 扫码面板只放二维码 + 返回入口,不要写说明文字;二维码是后端本地画的 SVG(
/api/wechat/qrcode.svg?code=…,没有任何外链资源); - 三角形只在自己那块折角区域可点(
clip-path把命中区一起裁了)→ 自动化点击要点在折角内(如 right-10 / top+10),点元素中心会落空;
- 扫码面板只放二维码 + 返回入口,不要写说明文字;二维码是后端本地画的 SVG(
- 注册字段顺序固定:用户名 → 邮箱 → 邮箱验证码(右侧「获取验证码」按钮,同一行
.input-row)→ 密码 → 重复密码;单列排布、没有步骤小标题、不收昵称/手机号; - 后台页(测试页 / 个人中心)的表单保留
label + placeholder的写法(字段多、需要一直可见),列表页与表单页共用.card(卡片间距由.card + .card统一); - 列表页(设备管理 / 扫码记录)用
<AppLayout fill>:内容区不滚动、卡片吃掉剩余高度、只有.table-wrap内部滚动(表头position: sticky吸顶、分页条贴在卡片底部);表单/详情页不传fill,滚动落在内容区,侧边栏底部始终可见; - 接口调用一律走
api/client.ts(自动带Authorization: Bearer、401 自动清令牌)+api/web.ts;不用 cookie/session,也就不需要 CSRF; - 扫码头像期:前端要自己设客户端超时(服务端挂 60s,客户端 70s),切走面板 / 离开页面(
pagehide)时要abort()长轮询 —— 后端会立刻停止等待(见backend/README.md长轮询一节)。
前端常用命令
cd frontend
npm run dev # 7301(VITE_PORT 可覆盖)
npm run typecheck # vue-tsc --noEmit
npm run build # typecheck + vite build(产物 dist/,后端生产模式托管)
常用环境变量
| 变量 | 默认值 | 作用 |
|---|---|---|
PORT |
7300 |
后端监听端口 |
FRONTEND_DEV_SERVER |
http://127.0.0.1:7301 |
开发时把页面请求反代到哪里 |
FRONTEND_DIST |
frontend/dist |
生产托管的前端构建产物目录 |
FRONTEND_ENABLE |
true |
关掉后后端不管页面(纯接口模式) |
INTERNAL_TOKEN |
空 | 运维接口的静态令牌(header X-Internal-Token);不配就只能靠白名单账号的 user JWT |
INTERNAL_ADMIN_IDS |
1 |
哪些用户 id 能调运维接口(逗号分隔) |
SITE_URL |
空 | 二维码 / 邮件里链接用的绝对域名(不配则用请求的 host) |
VITE_PORT / VITE_BACKEND |
7301 / http://127.0.0.1:7300 |
前端 dev 端口 / 代理目标 |
⚠️ 运维接口的默认白名单是内置管理员(id=1):上线前请配
INTERNAL_TOKEN,或把真正的管理员 id 写进INTERNAL_ADMIN_IDS。
Description
Languages
JavaScript
39.9%
C#
36.6%
Vue
11.4%
Java
3.9%
TypeScript
3.3%
Other
4.9%