liufumingren e6198a4334 web 端权限收紧:业务数据接口与菜单仅主体管理员
后端
- 新增 middleware/subject_admin.js:在 subjectAuth 之后校验「创建者 或 role=1」,否则 403
  { status: subject_forbidden, message: 只有主体管理员可以查看该数据(请联系主体管理员) }
- 挂到全部业务数据接口:/api/web/devices*、/records、/nvrs*(含 credential)、/cameras*、
  /workstations*、/workstation-scan-channels
- 有意不拦:/api/web/stats(首页概览)、/api/web/pack-query(桌面端打包查询,工位日常要用)

前端
- 路由加 meta.adminOnly(设备/录像机/摄像头/工作台/扫码记录,dev 的测试页同样),
  守卫里非管理员直接回首页 ?denied=1
- AppLayout 菜单按 isSubjectAdmin 过滤,成员只看到 首页 / 主体·成员 / 个人中心
- 首页对成员改成说明卡片(不再请求 stats、不显示设备/通道/记录数),被挡回时给出提示

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-21 17:00:09 +08:00

云仓视频溯源系统

前后端分离 + 一个浏览器扩展 + 一个 Windows 本机软件(WPF)+ 一个微信小程序 + 一个 Android 设备端,六个目录:

packService/
├── backend/     # Egg.js 3(纯 API;MySQL + Redis)
├── frontend/    # Vite + Vue3 + TypeScript(用户端 SPA)
├── miniprogram/ # uni-app + Vue3 + TypeScript(微信小程序:抽屉登录(个人中心为整页登录)/ 协议弹窗 / 首页统计 / 扫码记录 / 我的)
├── extension/   # Chrome MV3 扩展:注入第三方 WMS 页面,把运单号加工成溯源入口
├── desktop/     # WPF 本机软件:HTTP 17300(查询/唤起/下载)+ WS 17301(拉通道/预览/云台)+ yuncang:// 启动协议
└── AndroidStation/ # Android 设备端:UDP 48899 被桌面端发现 + TCP 8087 推送 USB 扫码结果

端口约定(⚠️ 本机项目多,不要用 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
小程序 H5 预览(可选) 7304 cd miniprogram && npm run dev:h5
本机软件(WPF,只监听 loopback) 17300(HTTP)/ 17301(WebSocket) 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)。
  • 上线:前端构建产物发布到 deployRoot/frontend,由 nginx 直接托管(静态资源 + SPA fallback);/api/*、/health 由 nginx 反代到 Egg,/download/* 由 nginx 直接托管安装包目录。发布走 cd backend && npm run deploy(双实例蓝绿发布,详见 backend/README.md「发布到服务器」)。
  • 安装包分发(/download/ 由 nginx 直接托管):桌面端 MSI 在 /download/desktop/、Android APK 在 /download/android_client/, 版本信息分别是 /download/version.json(桌面端自动更新读这个地址,不能改)和 /download/android_client/version.json。 单独发版:cd backend && npm run desktop:publish / npm run android:publish(都只构建+上传,不动后端)。
  • 生产强制 HTTPS:站点 vhost 对 HTTP 一律 301 到 HTTPS,HSTS 由 front.conf 各 location 声明;后端 config.proxy = true,SITE_URL / desktopBaseUrl 均为 https://,桌面端安装包内嵌地址也是 HTTPS。
  • AndroidStation 设备端不用这些开发端口:它在局域网上监听 TCP 8087(桌面端读扫码结果)和 UDP 48899(被桌面端发现),详见 AndroidStation/README.md。

身份与通讯约定

调用方 令牌 典型接口
前端 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/*
  • 小程序脚手架 miniprogram/(uni-app + Vue3 + TS):微信一键登录(code2Session)+ 账号登录双 tab / 首页统计 / 扫码记录 / 个人中心;登录前需阅读并同意协议(版本落库);不强制登录(启动不弹窗,点功能或 401 才提示,符合小程序审核)
  • 浏览器扩展 extension/(MV3,零构建):注入第三方 WMS 页面,在运单号旁边渲染「查看打包视频」按钮 → 点按钮打开溯源页
  • 后端去掉服务端渲染:删除 app/controller/page/、app/view/、app/lib/page.js、nunjucks / session / CSRF 配置与依赖,后端只剩 JSON 接口
  • 页面全部迁移到前端:登录 / 注册 / 找回密码 / 扫码 / 扫码确认 / 首页统计 / 设备管理 / 扫码记录 / 个人中心 / 测试页(仅开发构建,生产不打包)
  • 后端 dev 反代前端(app/middleware/frontend.js);生产由 nginx 直接托管前端构建产物(Egg 只提供 API)
  • 运维接口加鉴权:app/controller/admin/ → internal/,统一挂 middleware.internalAuth()
  • 新增用户端接口:/api/web/{stats,devices*,records,test/*}(范围一律限定在令牌对应的那个用户)
  • 扩展:目标地址换成真实打包视频页(现在指向百度占位)—— 在扩展「设置」里改「目标地址模板」即可,需要真实地址

后端接口细节见 backend/README.md,扩展用法见 extension/README.md,小程序用法见 miniprogram/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),点元素中心会落空;
  • 注册字段顺序固定:用户名 → 邮箱 → 邮箱验证码(右侧「获取验证码」按钮,同一行 .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/,发布时由 nginx 直接托管)

常用环境变量

变量 默认值 作用
PORT 7300 后端监听端口
FRONTEND_DEV_SERVER http://127.0.0.1:7301 开发时把页面请求反代到哪里
FRONTEND_DIST frontend/dist 仅当让 Egg 托管前端时使用(默认由 nginx 托管,FRONTEND_ENABLE=false)
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
No description provided
Readme 24 MiB
Languages
JavaScript 39.9%
C# 36.6%
Vue 11.4%
Java 3.9%
TypeScript 3.3%
Other 4.9%