WMS_PDA/README.md
liufumingren ba33f9c59a fix(env): 生产地址防呆,避免开发地址打进正式包
- src/env.js:生产构建固定 PROD_API_BASE,开发地址只从 .env.development.local 注入,源码不再保留内网地址字面量
- 新增 scripts/check-build-env.cjs:扫描产物含内网地址或缺生产域名即中止构建,已挂到 build:h5 / build:app-plus,另有 npm run check:env
- 新增 .env.example 模板;开发变量改用 mode 专属的 .env.development.local(.env.local 在 production 模式也会被加载并注入客户端代码)
- README 补充接口地址与环境变量防呆说明
2026-10-02 20:17:23 +08:00

139 lines
6.6 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 lint` | ESLint 自动修复 | - |
### 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`)。需要回退时,把备份内容覆盖回项目根目录即可。