天豹云仓的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×tamp=...` - 若配置中有完整 `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`;可用 `--api=http://x.x.x.x:6060` 指定 | | 测试包(与发行一致) | `npm run dev:adb -- --prod-api` | 不注入,指向生产(用于排查线上问题) | - 注入方式:编译期命令行环境变量 `VUE_APP_API_BASE_OVERRIDE`(**不写入任何 .env 文件、不落盘**),在 `src/env.js` 中优先级最高。与工作台项目的 `VITE_API_BASE_OVERRIDE` 是同一套思路。 - 测试包产物单独放 `release/android/dev/` 且文件名带 `_dev`,**不会覆盖发行包**,也不会触发发布上传(自动加 `-Dev -NoUpload`)。 - 设备选择:命令行 `--serial=` > 上次选择的设备(记在 `.dev-adb.local.json`,不提交)> 只有一台时自动选中 > 多台时交互选择。 - 若在 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`)。需要回退时,把备份内容覆盖回项目根目录即可。