# 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.