water/water-mini/PROJECT_CONTEXT.md

Project Context

2026-10-19 真实企业推广赠水

• rewards.vue 改接真实邀请与水权益；支持企业管理员获取唯一邀请码、复制、微信页面分享、首购前确认绑定和分页记录。分享参数只保留公开邀请码，不自动绑定；复用useCommand持久化幂等payload，未知结果禁止换邀请人。身份切换清空旧分享数据。
• 个人中心推广奖励单位改桶数，权益明细新增 promotion_reward。旧测试二维码及模拟奖励不再作为当前业务展示；现金字段仍为null，不支持提现。活动默认关闭，后台“财务结算中心 → 推广赠水奖励”配置；业务说明见 ../server/docs/WATER_PROMOTION.md。
• OpenAPI生成类型共69个Schema；小程序25项测试通过（新增4项实际组件测试），类型检查、H5及微信构建通过。H5本机预览已发布，入口及3个资源哈希一致；未上传微信、未真机验收。
• 全项目旧身份测试与当前单身份限制存在不一致，详见 ../server/docs/WATER_PROMOTION_RESULTS.md，不为通过旧测试放宽认证。

2026-10-09 一致性修复接续验收

• 复核10-08修复：套餐列表按接口公布的分类显示，不按名称推断；每次进入刷新。购物车提交 quote_revision，报价失败禁止提交；付款按订单快照发放权益。代码入口为 src/pages/packages/index.vue、src/pages/packages/cart.vue、src/components/PackageCard.vue。
• 本机 /api/mini/v1/config 返回 balance_payment=true、test_phone_login=true、wechat_login=false、payment=false；正式企业余额充值/退款仍待业务定义，真实微信支付和开票未开放。README 已修正旧能力说明；OpenAPI 当前64个Schema。
• 小程序21项测试和类型检查、后台类型检查及道路/删除脚本通过；8787 H5与4173后台的入口HTML和主JS/CSS哈希与当前构建一致。本轮未重新构建或发布。
• 浏览器工具启动返回 windows sandbox failed: orchestrator_helper_exit_nonzero，点击/截图/真机验收仍未完成。后续完整状态优先参考本节及父项目 server/docs/ADMIN_MINI_REPAIR_RESULTS.md；下面09-23记录为历史状态。

2026-09-23 继续验收记录

• 复核当前后端 GET /api/mini/v1/config 返回正常（HTTP 200）；当前能力状态为微信登录未配置、测试手机号登录开启，其余真实支付/余额/佣金/提现/奖励/设备绑定能力仍关闭，未发现异常业务响应。
• 使用现有代码运行 npm run type-check、npm test、npm run build:h5、npm run build:mp-weixin，均通过；自动化测试仍为12项全部通过，H5和微信构建均生成成功。PowerShell 调用 npm.ps1 会额外输出一次 Test-Path Access is denied 环境警告，但不影响 npm 子命令结果；后续可优先使用 npm.cmd 消除噪声。
• 静态预览入口 http://127.0.0.1:8787/water-mini/index.html 当前 HTTP 200。浏览器/桌面自动化复测仍被工具侧 unsupported Codex auth method: apikey 阻塞，因此浏览器点击、截图和窄屏视觉验收仍未完成，不能标记为通过。
• 未修改业务代码、数据库、Redis、凭据或外部平台配置；下一步若继续实现，应先选择需要真实产品决策的事项（短信服务、微信 AppID/Secret、高德 Key/域名白名单或套餐元数据字段），再做对应联调或迁移。

Identity

• Name: water-mini
• Purpose: uni-app Vue 3 + TypeScript mini-program/H5 client for enterprise water supply, delivery, agent, package, order, and driver workflows.
• Root: D:\phpstudy_pro\WWW\saiadmin6.x\water-mini
• Status: Active development; transaction/catalog fixes were completed on 2026-10-08 and regression-checked on 2026-10-09. Browser interaction and device acceptance remain outstanding.

Stack and commands

• Runtime: Node.js; uni-app/Vue 3; TypeScript.
• Package manager: npm (package-lock.json).
• Development: npm run dev:h5; WeChat DevTools imports dist/build/mp-weixin after a build.
• Build: npm run build:h5, npm run build:mp-weixin.
• Preview publish: npm run preview:publish copies H5 output to server/public/water-mini.
• Verification: npm run type-check, npm test.

Structure and entry points

• src/pages.json: page routing and navigation titles.
• src/api/client.ts: API base URL and authenticated uni.request transport.
• src/api/schema.ts: generated API types.
• src/stores/session.ts / src/stores/state.ts: session and active identity state.
• src/stores/cart.ts: local package cart; server quote/checkout validates the final amount.
• src/pages/packages/index.vue: package catalog, category tabs, package cards, and fixed cart summary.
• src/components/PackageCard.vue: package card visual and add-to-cart action.
• src/pages/agent/customers.vue: subordinate-user page matching the supplied mobile reference.
• src/pages/common/map.vue: shared single-location and route map page.
• src/utils/location.ts: routes existing map actions to the shared map page.
• src/utils/amap.ts: H5 AMap JS API loader.

Architecture and integrations

• Package data comes from public GET /api/mini/v1/packages; checkout quote and submission remain server-authoritative.
• The current package API advertises category_filter=false and publishes only the all tab; the UI uses the returned categories without package-name or device-flag guesses. Category, validity, and device-service metadata currently return null.
• H5 map pages load AMap JS API using VITE_AMAP_KEY and optional VITE_AMAP_SECURITY_CODE from ignored .env.local.
• H5 route maps call AMap Driving with the driver route origin and stop coordinates; long routes are split into chunks of up to 18 points.
• WeChat builds use the native <map> component and uni.openLocation; AMap Web JS cannot run directly inside a mini-program page.
• The development API default is http://192.168.110.245:8787/api/mini/v1; production should use an HTTPS domain and WeChat legal-domain configuration.

Conventions and constraints

• Do not invent business success for unavailable payment, commission, GPS, or map data; show the unavailable state.
• Preserve server pagination, identity guards, idempotent command flows, and generated API schema boundaries.
• Keep local credentials in .env.local; never record keys or secrets in this context file.
• project.private.config.json/src/manifest.json currently disable WeChat URL checking for local LAN development. Re-enable it for release builds.

Known issues and follow-ups

• The current backend package model exposes no managed category, validity, or original-price fields; the UI uses safe fallbacks until those fields are added to the admin/API contract.
• H5 AMap requires a valid JS API key, security code, and allowed domain. If the map reports a Key/domain error, inspect water-mini/.env.local and the AMap console.
• For WeChat route display, native map markers are shown and the user can open the native map; road-level AMap route drawing is H5-only.
• If a rebuilt page is not visible, rebuild the target (h5 or mp-weixin) and recompile/reimport the corresponding output directory.

Decisions and change notes

• 2026-09-22: Reworked package catalog/card UI to match the supplied screenshot while retaining real backend catalog and cart/checkout logic.
• 2026-09-22: Added shared map page, H5 AMap loader, route-map entry from driver routes, and native WeChat map fallback.
• 2026-09-22: Switched local mini-program API default from loopback to LAN host 192.168.110.245 for device testing.

Verification

• Last checked: 2026-10-09.
• Result: npm run type-check and 21 npm test checks passed; H5 preview HTML and entry asset hashes match the current build. No new build/publish was performed; browser/device acceptance remains outstanding.