# 云泉智配小程序

uni-app Vue 3 + TypeScript，微信小程序为主要交付端，同时提供 H5 页面预览。页面依据 `D:\水后台UI\mobile\M01.png`–`M18.png`，接口以 `../server/docs/openapi/water-mini-v1.json` 为准。

## 本机预览

构建并发布本机 H5 后打开 <http://127.0.0.1:8787/water-mini/index.html>。默认复用当前后端服务，不另起接口代理。首页和套餐公开可浏览；个人、企业、司机及代理数据需要登录及授权。可以使用下述明确隔离的本地测试账号，业务读写仍走真实接口和身份权限。

## 测试手机号登录

页面上的“手机验证码登录”同时支持测试账号与正式手机号。三个指定测试号仅输入手机号，调用 `/auth/test-phone`，无需验证码；其余号码调用 `/auth/send-sms` 获取随机六位短信码，再通过 `/auth/phone-login` 登录。短信验证码两分钟有效，过期必须重新获取，重发后旧码作废。发送间隔60秒与验证码有效期120秒是两个独立规则。

手机号入口在 `capabilities.sms_login` 或 `capabilities.test_phone_login` 任一开启时显示，但各自独立控制对应登录方式。测试号只走测试接口，不会因为测试能力关闭而改走短信。获取短信无需先勾选协议，提交登录仍需同意协议。正式手机号沿用后台预绑定已有账号的规则。

在后端 `.env` 设置 `MINI_TEST_PHONE_LOGIN=true`，执行 `php -d extension=mbstring scripts/seed_mini_test_phone.php --apply` 并重载后端。按用户要求，测试登录不限制 `APP_ENV` 或客户端 IP，开发者工具和真机均可使用；测试账号无需验证码，不发送短信。每个测试账号只绑定一种身份，登录后直接进入对应页面：

| 角色 | 测试手机号 | 登录后页面 |
| --- | --- | --- |
| 企业管理员 | `13012345678` | 企业首页 |
| 配送员 | `13012345679` | 配送工作台 |
| 代理商 | `13012345680` | 代理工作台 |

初始化脚本仅绑定指定的既有测试档案（科技园配送测试、地图配送员-KJY、测试商贸），并停用原企业测试号上的司机、代理授权；不新增订单、库存或收款。重复运行不恢复被管理员停用的账号或身份。关闭开关并重载后端后，既有测试 Token 同时失效。开启后，知道测试凭据的人可访问对应测试账号，因此开关默认关闭，开启时使用测试业务档案；账号停用、权限和登录限流仍生效。真实短信服务的配置、手机号绑定及迁移说明见 `../server/docs/WATER_MINI_API.md` 的“短信验证码登录”。

## 安装与运行

```powershell
cd D:\phpstudy_pro\WWW\water\water-mini
npm ci
npm run dev:mp-weixin
```

在微信开发者工具导入 `dist/dev/mp-weixin`；发布构建运行 `npm run build:mp-weixin`，导入 `dist/build/mp-weixin`。也可以在 HBuilderX 中打开项目，通过终端使用上述命令。

遇到“项目根目录未找到 app.json”，说明导入目录未指向编译产物。现在也可直接导入 `water-mini`：根目录 `project.config.json` 已设置 `miniprogramRoot=dist/build/mp-weixin/`，须先构建。该入口使用游客 AppID 并关闭本机域名校验，供测试手机号登录使用；微信登录需真实 AppID。正式发布应导入构建目录，并配置真实 AppID 及 HTTPS 合法域名。

1. 在 `src/manifest.json` 的 `mp-weixin.appid` 填写自己的微信小程序 AppID。当前留空以避免编造项目身份；Secret 绝不能放入前端。
2. 复制 `.env.example` 为 `.env.local`，设置 `VITE_API_BASE_URL`。默认微信本机调试地址为 `http://127.0.0.1:8787/api/mini/v1`，真机必须配置实际可访问的 HTTPS 域名及小程序 request/downloadFile 合法域名。修改后重新编译。
3. 后端配置与该小程序匹配的 `MINI_WECHAT_APPID` / `MINI_WECHAT_SECRET`，并配置隐私、购水协议和客服电话。首次登录后，将用户编号交给后台超级管理员绑定企业、司机或代理身份。
4. 微信后台应按真实用途配置隐私保护指引及位置、相机/相册相关能力；定位用于到达打卡和履约照片。网页内的协议/活动地址需配置微信业务域名。

网页开发与本机静态预览：

```powershell
npm run dev:h5
# http://127.0.0.1:5174/water-mini/
npm run build:h5
npm run preview:publish
# http://127.0.0.1:8787/water-mini/index.html
```

H5 在未配置 `VITE_API_BASE_URL` 时使用同源 `/api/mini/v1`。开发服务器将该路径代理至8787并使用已允许的本机 Origin；静态预览与接口同源。指定跨域 API 时，需要后端 `MINI_ALLOWED_ORIGINS` 放行精确的网页来源。微信 `wx.login` 只在微信小程序内调用，H5 的微信登录按钮保持不可用。

浏览器定位要求安全上下文：本机可使用上述 `127.0.0.1` 地址；其他电脑或手机通过局域网 IP 访问时需配置 HTTPS，并在浏览器和系统中允许位置访问。普通 `http://192.168...` 页面无法获取定位。

## 已实现页面

| 设计图      | 页面与能力                                                                  |
| ----------- | --------------------------------------------------------------------------- |
| M01         | 企业首页、内容轮播、用水与权益摘要、精选套餐；未登录可浏览公开套餐          |
| M02/M03/M05 | 套餐列表/详情、本地组合订单、服务器报价、待支付订单详情、企业余额支付与取消 |
| M04         | 企业供水地址展示、管理员完整电话编辑及 revision 冲突处理                    |
| M06/M07     | 配送订单/待支付意向/真实收款分开查询，配送进度、私有照片和待调度预约取消    |
| M08         | 按企业+水品汇总的权益、流水、预约配送                                       |
| M09         | 设备列表、真实上报用量、7日趋势；未知数据展示“—”                            |
| M10/M11     | 推广能力状态、个人中心、客服、登录、账号待开通状态与退出                    |
| M12/M13     | 司机工作台、任务筛选、路线站点、出发、打卡、拨号、地图、异常上报            |
| M14         | 扫码或手输 SN，核对已绑定设备的企业归属                                     |
| M15         | 拍照/选图、位置记录、选择1–4张照片、暂存、实际签收/空桶/拒收原因            |
| M16–M18     | 代理首页、7日收款趋势、客户筛选及客户收款记录、佣金未开放状态               |

28个页面包括必要的登录、详情与辅助页面。购物车为当前运行期本地状态，金额以服务器报价为准；历史草稿从司机任务记录恢复。页面不将参考图中的示例金额、佣金比例、定位、ETA、分卡有效期或活动优惠写成真实业务。

## 结构与公共逻辑

- `src/api/client.ts`：统一 JSON 请求、Bearer Token、HTTP/业务错误；不自动重试写请求。
- `src/api/schema.ts`：由 `npm run api:types` 从64个 OpenAPI Schema 生成，禁止手改。
- `src/stores/state.ts` / `session.ts`：会话与账号唯一业务身份；退出/401/账号变更会使旧请求失效并清空私有页面数据。
- `src/composables`：页面加载、分页、提交状态与幂等重试。写请求在发出前保存完整参数与 request_key；网络/5xx保留原请求，明确业务拒绝释放记录，用户重试复用原参数。
- `src/components`：导航、权限提示、套餐/订单/任务卡片、数量输入、趋势图和私有照片读取。
- `src/pages`：按企业、司机和代理职责分目录，页面调用既有 API。

幂等记录按用户+操作路径隔离。未确认结果时不能直接改内容另发请求，页面提供“重试上次提交”。照片采用JSON base64；为保证微信本地保存重试请求不超过单键容量，前端压缩后限制为约600KB、最长边4096及800万像素；服务器仍按自身上限校验。私有照片通过带Token的下载请求获取临时文件，退出/页面销毁清除展示路径和已下载临时文件；Token不拼到照片URL中。

## 验证与边界

```powershell
npm run api:types
npm run type-check
npm test
npm run build:mp-weixin
npm run build:h5
```

测试覆盖重复点击、超时重试、页面重建后的原请求、身份切换旧响应、401清理、私有数据清理和分页竞争。测试使用受控网络替身，不创建真实业务数据。

微信外部登录及设备实机端到端验收需真实 AppID、后端凭据和业务身份。手机号已提供固定验证码测试登录及真实短信登录，两种方式按上述规则分流。企业余额支付已实现，接口 `capabilities.balance_payment` 公布是否可用；订单明细保存报价快照，余额扣款、流水和权益同事务提交。正式企业余额充值与退款尚未形成业务闭环，不能使用旧租赁个人钱包替代企业余额。真实微信支付、开票、独立水卡有效期、佣金结算、提现、现金邀请奖励、设备绑定和实时GPS仍未开放。

2026-10-09 接续检查：小程序21项测试、两端类型检查、后台道路规划与套餐删除脚本通过；后台和H5入口及主资源哈希与现有构建一致。浏览器工具因本机沙箱初始化失败未能启动，实际点击及真机验收仍未完成。详细记录见 `../server/docs/ADMIN_MINI_REPAIR_RESULTS.md`。

回退仅移除独立 `water-mini` 项目及本次生成的 `server/public/water-mini` 预览目录；无需数据库回滚，不影响既有小程序接口和后台项目。


## 企业推广赠水（2026-10-19）

“我的 → 奖励与推广”已接入真实邀请码、首购前绑定、分页邀请及赠水记录。微信版可分享邀请页面，H5可复制邀请码。需在后台“财务结算中心 → 推广赠水奖励”配置赠水规格及桶数后开启；默认关闭。赠水须首购后签收并经人工核实审核，不能提现。接口、迁移及限制见 [WATER_PROMOTION.md](../server/docs/WATER_PROMOTION.md)。