WMS_PDA/README.md
zm2000 db90efa0cb chore: 版本升至 1.0.123,商品图片维护回滚逻辑优化,新增发布上传配置
商品图片编辑/维护(edit.vue、itemMaint.vue):
- 图片未变化时直接放行返回,不再每次返回都发 ReferenceFile 请求(修复需点两次返回)
- 返回键/返回按钮先拦截,回滚完成后再 navigateBack,避免页面提前销毁导致回滚中断、图片停留在删除后状态
- navigateBack 增加 success/fail 均未触发的静默失效重试兜底
- 保存成功后同步初始快照,避免保存后返回被误回滚到保存前图片
- itemMaint 图片查询支持多候选 id 兜底(查询页传入 id/stock_id 优先),修复按条码重查不到商品时图片不显示

商品查询页(query.vue):
- 跳转维护页时附带 id/stock_id 参数,供图片查询兜底
- 图片缩略图增加 :key 强制刷新

发布上传(config/deploy.json、deploy.example.json):
- 新增部署配置,打包结束后自动生成 latest.json 并用 scp 上传 APK + 版本清单
- config/README.md 补充 deploy.json 字段说明

测试包构建脚本(dev-adb.cjs):
- 不注入地址时(--prod-api / 未配置开发地址)显式删除继承的环境变量,避免终端残留 VUE_APP_API_BASE_OVERRIDE/URL 把开发地址带进包

文档(README.md):
- 更新测试包命令用法,说明 npm 10 下 -- 参数会被吞、需直接用 node 调用脚本

其他:
- package.json、manifest.json 版本号 1.0.122 → 1.0.123
- 新增 scripts/_argtest.cjs(打印 argv,调试用)
2026-10-06 19:30:29 +08:00

164 lines
9.4 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.

天豹云仓的WMS_PDA项目
## 文件说明
- `day.log`:日报记录文件,用于按天填写工作内容(今日完成、进行中、明日计划、问题与风险、备注)。
## API接口文档
- `http://192.168.11.56:6060/api/docs/system/raw`
## 接口文档与登录接口关系
### 1)接口文档(后端)
- 接口文档定义了后端可调用的 method、参数和返回结构。
- 前端并不直接写死所有 URL,而是通过本地接口映射表进行统一管理。
### 2)本地接口映射(前端“接口文档”)
- 文件:`core/request/apis.js`
- 作用:把业务别名映射为请求配置(`path/url`、`method`、`auth`)
登录相关映射:
- `user.login`
- `path: "user.login"`
- 用于账号密码登录
- `user.loginByUuid`
- `url: "https://ye4s.wms.gztbyc.com/index/wms/wms/loginByUuid"`
- 用于扫码/工牌 UUID 登录
- `user.info`
- `path: "user.info"`
- 用于拿登录后的用户信息
### 3)请求封装与实际调用关系
#### 3.1 请求入口
- 文件:`core/request/index.js`
- 统一入口:`http('user.login', data)` / `http('user.loginByUuid', data)`
#### 3.2 URL组装规则
- 文件:`core/request/request.js`
- 若配置中有 `path`:实际请求变为 `API_URL?method={path}&v=1.0&timestamp=...`
- 若配置中有完整 `url`:直接请求该 URL(如 `loginByUuid`)
#### 3.3 公共请求头
- 文件:`core/request/request.js`
- 默认头包含:
- `platform: pda`
- `project: warehouse`
> 注意:若后端提示 `project 不支持`,优先检查这里的 `project` 与业务参数中的 `project` 是否一致。
### 4)登录调用链(账号密码)
1. 页面发起:`pages/login/index.vue` -> `this.$store.dispatch('login', loginForm)`
2. 状态层处理:`core/store/modules/user.js` -> `actions.login`
3. 接口调用:`http('user.login', { username, password, device, project })`
4. 返回处理:从响应拿 `token`,调用 `setToken(token)` 写入本地
5. 页面跳转:登录页切换到 `/pages/index/index`
### 5)登录调用链(扫码/工牌)
1. 页面监听广播:`pages/login/index.vue`(`broadcast/setCallbacks` + `onResult`)
2. 获取扫码结果:`result.data`(通常是 UUID 或包含 UUID 的编码串)
3. 点击确认登录:调用 `loginByUuid(uuid)`
4. 接口调用:`http('user.loginByUuid', { uuid })`
5. 返回处理:提取 token 后 `setToken(token)`
6. 页面跳转:切换到 `/pages/index/index`
### 6)常见错误与关系定位
- 报错:`project 不支持`
- 关联:`core/request/request.js` 默认请求头 + `core/store/modules/user.js` 的 `state.app.project`
- 报错:`登录成功但未返回token`
- 关联:后端返回结构与前端 token 提取逻辑不一致
- 报错:`用户信息加载失败`
- 关联:`user.info` 接口失败、token 无效或参数不匹配
### 7)建议的排查顺序
1. 先看 `apis.js` 映射是否正确(`path/url`)
2. 再看请求头和业务参数中的 `project/device` 是否与后端一致
3. 再看接口返回结构是否包含 token
4. 最后看登录后是否成功调用 `user.info`
## 构建与运行(uni-app Vue2 CLI 工程)
> 本项目已从 HBuilderX 工程迁移为 `@vue/cli` 脚手架工程(2026-10-02):
> 业务源码全部位于 `src/`,H5 模板由 `public/index.html` 提供(即原根目录的 `template.h5.html`)。
### 命令
| 命令 | 作用 | 产物 |
| --- | --- | --- |
| `npm run dev:h5` | H5 开发服务器(默认 http://localhost:8080) | 内存编译 |
| `npm run build:h5` | H5 生产构建 | `dist/build/h5` |
| `npm run dev:app-plus` | App 资源监听编译 | `dist/dev/app-plus` |
| `npm run build:app-plus` | App 生产构建 | `dist/build/app-plus` |
| `npm run build:apk` | Android **发行包**(生产地址 + 产物地址校验) | `release/android/wms-pda_v*.apk` |
| `npm run dev:adb` | Android **测试包**(注入开发地址)→ 装机 → 启动 | `release/android/dev/wms-pda_v*_dev.apk` |
| `npm run android:pack:raw` | 仅打包(用现有 `dist/build/app-plus`,不重编前端) | 同上 |
| `npm run check:env` | 手动校验产物接口地址 | - |
| `npm run lint` | ESLint 自动修复 | - |
### App 端如何选择接口环境(测试模式)
| 场景 | 命令 | 接口地址来源 |
| --- | --- | --- |
| 发行包 | `npm run build:apk` | `src/env.js` 的 `PROD_API_BASE`(固定),构建后强制校验产物不含内网地址 |
| 测试包 | `npm run dev:adb` | 默认 `.env.development.local` 的 `VUE_APP_API_BASE_URL` |
| 测试包(指定后端) | `node scripts/dev-adb.cjs --api=http://x.x.x.x:6060` | 显式注入指定地址(优先级最高) |
| 测试包(与发行一致) | `node scripts/dev-adb.cjs --prod-api` | 不注入,指向生产(用于排查线上问题) |
> ⚠️ 带参数时请直接用 `node scripts/dev-adb.cjs <参数>`:Windows + npm 10 下 `npm run dev:adb -- <参数>` 的 `--` 参数会被 npm 吞掉、不传给脚本(`--prod-api` 会因此失效并回落到开发地址)。不带参数的 `npm run dev:adb` 不受影响。
- 注入方式:编译期命令行环境变量 `VUE_APP_API_BASE_OVERRIDE`(**不写入任何 .env 文件、不落盘**),在 `src/env.js` 中优先级最高。与工作台项目的 `VITE_API_BASE_OVERRIDE` 是同一套思路。
- 测试包产物单独放 `release/android/dev/` 且文件名带 `_dev`,**不会覆盖发行包**,也不会触发发布上传(自动加 `-Dev -NoUpload`)。
- 设备选择:命令行 `--serial=` > 上次选择的设备(记在 `.dev-adb.local.json`,不提交)> 只有一台时自动选中 > 多台时交互选择。示例:`node scripts/dev-adb.cjs --prod-api --serial=4235737`。
- 若在 cmd / 默认代码页(936)的窗口里运行看到中文乱码:先执行 `chcp 65001`(VS Code 内置终端、Windows Terminal 默认无需处理)。
- 两道校验方向相反:发行包**反向**校验(产物中不得出现 `192.168.x.x`/`127.0.0.1`);测试包**正向**校验(产物中必须出现注入的地址,否则中止,避免装成生产包却以为在测开发环境)。
- 真机 JS 日志:**离线 release 包默认不会把 `console.log` 输出到 logcat**(HBuilderX「运行到手机」靠的是 debug 基座)。测试包由 `src/core/utils/dev-log.js` 用 `plus.android` 桥接 `android.util.Log`,把 console 转发到 logcat 的 `jsLog` tag(`dev:adb` 会自动注入开关并实时跟随打印):
```powershell
& "$env:ANDROID_HOME\platform-tools\adb.exe" -s <序列号> logcat jsLog:V UniConsole:V UniViewConsole:V *:S
```
### App 端调试与打包
- CLI 不提供「运行到手机」:`build:app-plus` 只产出 App 资源,用 HBuilderX 导入 `dist/build/app-plus` 运行(或使用自定义基座、离线打包)。
- 正式云打包仍建议走 HBuilderX;`src/manifest.json` 中的 appid、模块、权限配置均保持原样。
### 注意事项
- **Node 版本**:当前在 Node 24 下构建,依赖两个脚本内开关——`--openssl-legacy-provider`(webpack 4 需要)与 `--require=./scripts/node-compat.cjs`(补回 Node 23+ 移除的 `util.isRegExp` 等历史 API)。若改用 Node 16/18,这两项会自动变成无害的空操作。
- **`ROUTES` 常量**:由根目录 `vue.config.js`(`uni-read-pages` + DefinePlugin)注入,`uni-simple-router` 内部依赖它;缺失会在运行时抛 `ReferenceError: ROUTES is not defined`,请勿删除该配置。
- **@dcloudio 版本必须整体一致**:当前锁定 `2.0.2-5020620260917001`(Vue2 线),升级时需全量同版本替换。
- **依赖镜像**:`.npmrc` 指向 `registry.npmmirror.com`。
- `src/pages/componentsA|B|C` 是 uView 官方示例页(含 67 个 `.nvue` 文件),未被 `pages.json` 注册、不参与编译,可按需删除。
### 接口地址与环境变量(防呆)
| 场景 | 地址来源 | 命令 |
| --- | --- | --- |
| 发布构建(H5 / App) | `src/env.js` 的 `PROD_API_BASE`(固定,不采用 .env 文件里的地址) | `npm run build:h5` / `build:app-plus` |
| 本地开发 | `.env.development.local` 的 `VUE_APP_API_BASE_URL`(git 不跟踪) | `npm run dev:h5` / `dev:app-plus` |
| 临时指向指定后端 | 命令行显式注入 `VUE_APP_API_BASE_OVERRIDE`(不落盘) | 见下 |
- 首次拉取代码后:复制 `.env.example` 为 `.env.development.local` 并填写内网地址。
- 临时改后端(不写任何文件):`npx cross-env UNI_PLATFORM=h5 NODE_ENV=development VUE_APP_API_BASE_OVERRIDE=http://192.168.1.10:6060 vue-cli-service uni-serve`
- **两道防线**:
1. 生产构建只认 `PROD_API_BASE`,源码里也不再保留任何内网地址字面量;
2. `npm run build:h5` / `build:app-plus` 结束后自动执行 `scripts/check-build-env.cjs`,产物中出现 `192.168.x.x` / `127.0.0.1`,或缺少生产域名 `qimen.wms.gztbyc.com`,即**构建失败**。手动校验:`npm run check:env`。
- ⚠️ 开发地址**不要**写进 `.env.local`:该文件在 production 模式同样会被加载,并会被构建工具注入到客户端代码里(会被上面的校验拦下,但没必要绕这一圈)。
- 现场排查设备连的是哪个后端:可用 `pages/settings/networkTest` 页面查看/测试接口地址。
### 回退方式
原 HBuilderX 工程完整备份在 `d:\WMS_PDA_bak_20261002-1936`(含 `node_modules`、`.hbuilderx`、`template.h5.html`、`vue.config.js`、`package.json`、`package-lock.json`)。需要回退时,把备份内容覆盖回项目根目录即可。