water/water-mini

云泉智配小程序

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。默认复用当前后端服务，不另起接口代理。首页和套餐公开可浏览；个人、企业、司机及代理数据需要登录及授权。可以使用下述明确隔离的本地测试账号，业务读写仍走真实接口和身份权限。

本地测试手机号登录

在后端 .env 设置 APP_ENV=local 和 MINI_TEST_PHONE_LOGIN=true，执行 php -d extension=mbstring scripts/seed_mini_test_phone.php --apply 并重启后端。本地固定验证码均为 66666，不发送短信。每个测试账号只绑定一种身份，登录后直接进入对应页面：

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

初始化脚本仅绑定指定的既有测试档案（科技园配送测试、地图配送员-KJY、测试商贸），并停用原企业测试号上的司机、代理授权；不新增订单、库存或收款。重复运行不恢复被管理员停用的账号或身份。关闭开关并重启后端后，既有测试 Token 同时失效。正式部署保持 APP_ENV=production、MINI_TEST_PHONE_LOGIN=false。真实手机号短信登录仍待接入短信服务。

安装与运行

cd D:\phpstudy_pro\WWW\saiadmin6.x\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. 微信后台应按真实用途配置隐私保护指引及位置、相机/相册相关能力；定位用于到达打卡和履约照片。网页内的协议/活动地址需配置微信业务域名。

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

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中。

验证与边界

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。