packServer/README.md
liufumingren bd2363bf00 chore: 初始化仓库(backend / frontend / extension 三块)
- 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 密码,绝不入库)。
2026-10-17 08:50:32 +08:00

66 lines
4.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 云仓视频溯源系统
前后端分离 + 一个浏览器扩展,三个目录:
```
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`。