- backend/:Egg 3 纯 JSON 接口服务(MySQL 8 + Redis),全部走 header 令牌鉴权; 已彻底去掉服务端渲染(删除 page 控制器 / app/view / nunjucks / session / CSRF), 开发时把页面请求反代到前端 dev server,生产托管 frontend/dist(SPA 回退)。 单测 91 个通过(不需要本机数据库)。 - frontend/:Vite + Vue3 + TypeScript 的 SPA(登录 / 注册 / 找回密码 / 扫码登录与确认 / 首页统计 / 设备管理 / 扫码记录 / 个人中心 / 测试页),vue-tsc 类型检查与构建通过。 - extension/:MV3 浏览器扩展(零构建),注入第三方 WMS 页面识别运单号并打开溯源页。 - 忽略规则统一放根 .gitignore:node_modules、dist、logs / logs-*、run、typings、 .env*、config.local.js(含本机数据库与 Redis 密码,绝不入库)。
66 lines
4.3 KiB
Markdown
66 lines
4.3 KiB
Markdown
# 云仓视频溯源系统
|
||
|
||
前后端分离 + 一个浏览器扩展,三个目录:
|
||
|
||
```
|
||
packService/
|
||
├── backend/ # Egg.js 3(纯 API;MySQL + Redis)
|
||
├── frontend/ # Vite + Vue3 + TypeScript(用户端 SPA)
|
||
└── extension/ # Chrome MV3 扩展:注入第三方 WMS 页面,把运单号加工成溯源入口
|
||
```
|
||
|
||
## 端口约定(⚠️ 本机项目多,不要用 Vite 默认的 5173)
|
||
|
||
| 用途 | 端口 | 启动方式 |
|
||
| --- | --- | --- |
|
||
| 前端 dev(Vite) | **7301** | `cd frontend && npm run dev` |
|
||
| 前端 preview(dist) | **7302** | `cd frontend && npm run preview` |
|
||
| 后端 dev | **7001** | `cd backend && npm run dev` |
|
||
| 后端 dev:test(与 7001 并存) | **7300** | `cd backend && $env:LOG_DIR='logs-test'; npm run dev:test` |
|
||
| 扩展自测页(可选) | **7310** | `npx --yes http-server extension/test -p 7310` |
|
||
|
||
- 前端端口可用 `VITE_PORT=7303 npm run dev` 覆盖;`strictPort: true` → 端口被占用时**直接报错**,不会偷偷换端口(否则代理会对不上)。
|
||
- 前端调接口走**同源代理**:Vite 把 `/api`、`/health` 反代到后端(默认 `127.0.0.1:7001`,用 `VITE_BACKEND` 覆盖)。
|
||
- 联调更方便的做法:直接开后端 `:7001`,由后端(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)。
|
||
|
||
## 当前进度
|
||
|
||
- [x] 目录拆分为 `backend/` + `frontend/`
|
||
- [x] 前端脚手架(Vite + Vue3 + TS)跑通,登录页走通 `/api/web/auth/*`
|
||
- [x] 浏览器扩展 `extension/`(MV3,零构建):注入第三方 WMS 页面识别运单号 → 点击打开溯源页
|
||
- [x] **后端去掉服务端渲染**:删除 `app/controller/page/`、`app/view/`、`app/lib/page.js`、nunjucks / session / CSRF 配置与依赖,后端只剩 JSON 接口
|
||
- [x] 页面全部迁移到前端:登录 / 注册 / 找回密码 / 扫码 / 扫码确认 / 首页统计 / 设备管理 / 扫码记录 / 个人中心 / 测试页
|
||
- [x] 后端 dev 反代前端(`app/middleware/frontend.js`)+ 生产托管 `frontend/dist`(SPA 深链回退)
|
||
- [x] 运维接口加鉴权:`app/controller/admin/` → `internal/`,统一挂 `middleware.internalAuth()`
|
||
- [x] 新增用户端接口:`/api/web/{stats,devices*,records,test/*}`(范围一律限定在令牌对应的那个用户)
|
||
- [ ] 扩展:目标地址换成真实打包视频页(现在指向百度占位)—— 在扩展「设置」里改「目标地址模板」即可,需要真实地址
|
||
|
||
后端接口细节见 [`backend/README.md`](backend/README.md),扩展用法见 [`extension/README.md`](extension/README.md)。
|
||
|
||
## 常用环境变量
|
||
|
||
| 变量 | 默认值 | 作用 |
|
||
| --- | --- | --- |
|
||
| `PORT` | `7001` | 后端监听端口 |
|
||
| `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:7001` | 前端 dev 端口 / 代理目标 |
|
||
|
||
> ⚠️ 运维接口的默认白名单是**内置管理员(id=1)**:上线前请配 `INTERNAL_TOKEN`,或把真正的管理员 id 写进 `INTERNAL_ADMIN_IDS`。
|