# saiadmin-artd 项目记忆 ## 2026-09-17 菜单管理导航入口 - 用户要求把菜单操作加到导航；按添加“菜单管理”入口实现。原系统菜单id8及core:menu:index/read/save/update/destroy早已存在，供水mergeWaterMenus原先隐藏全部旧系统导航，导致入口不可见。 - router/modules/water.ts从服务端已授权菜单树提取/system/menu，保留原Menu路由名称、组件、可见标记与权限，放在角色与权限后、操作审计前，移除原树重复节点；其他旧菜单仍隐藏但保留路由。无授权不创建入口，不更改数据库菜单、角色授权或业务数据。 - views/index/index.vue让/system/menu沿用供水外观。复用现有system/menu页面及CRUD接口，原新增/编辑/删除按钮权限不变；补货阈值策略现有权限仍是water:alerts:write（菜单名称“管理补货预警”）。 - Prettier/ESLint/vue-tsc通过；导航运行验证覆盖排序、原始树不变、未授权不补发、无重复、无供水菜单回退；真实HTTP确认/core/system/menu返回唯一可见Menu页面，/core/menu/index包含全部既有菜单操作权限。浏览器仍有已知apikey认证阻塞，未做点击验收。 - Vite3335模块生产构建通过，dist更新；4173首页和包含导航修改的主JS资源SHA256一致。 ## 2026-09-17 平台阈值策略编辑 - 恢复预警页AlertPolicyDialog入口，由alerts:write控制；编辑平台统一alert_qty、days_per_barrel、urgent_qty，默认5/3/2。打开时GET alerts/policy读取持久值，提交带revision，保存成功刷新看板。不存在逐企业阈值编辑，默认值不是写死的算法常量。 - 列表理由、统计卡片及规则说明使用当前接口policy；企业编辑/详情和共享模块去掉固定5桶/3天说明，统一引用平台策略。企业人数可空，未知人数只计算数量型预警，预计用量不扣实物库存。 - 全局策略43项、预警118项、业务64项、企业68项共293项后端检查通过；前端Prettier/ESLint/Stylelint/vue-tsc通过，详情见父项目server/docs/WATER_ALERTS.md。浏览器仍有既有apikey认证故障，未做点击/截图验收。 - 生产构建成功（3335模块），dist已更新；4173首页与含“保存并生效”的策略资源SHA256一致。仅保留既有system/menu导入警告。 ## 2026-09-17 首页内容配置独立页面 - `views/water/content` 改为参考图列表+手机双栏布局，分离 `ContentEditor/ContentPhone/ContentPreviewDialog`，接口类型在 `api/water/content.ts`。搜索状态筛选、8条分页、全量上线统计、选中素材/草稿预览、按身份区域模拟预览均接入后端。 - 新建/编辑保存原POST content，人群/区域/有效期/排序/启停、HTTP(S)图片和活动链接可配置。手机套餐为真实启用商品，空态不伪造；后台快捷入口仅供展示，实际小程序/App未接入。 - 状态和受众判断以服务端为准，权限校验content:read/write。源码检查已通过；完整契约及测试见父项目 `server/docs/WATER_CONTENT.md`。浏览器仍受既有工具认证故障限制。 - Vite3331模块构建通过，dist已更新，4173预览首页及内容页资源与本次产物一致。 ## 2026-09-17 待审核提现测试展示 - 财务API新增独立 `withdrawal_demo`（list/total/amount_cents），待审核区显示4条持久化测试申请，测试卡片合计12360元；名称/状态/说明明确模拟，无真实余额或打款。按月份、all/demo显示，regular隐藏；正式提现权限能力及按钮仍未开通。 - 测试表、种子及接口验证详见父项目 `server/docs/WATER_FINANCE.md`；原收款汇总、流水与导出不混入测试提现。 ## 2026-09-17 财务结算独立页面 - `/water-finance` 使用 `api/water/finance.ts` 与 `views/water/finance/{index.vue,ReceiptDialog.vue,finance.scss}`，已完成参考图四卡/趋势/月汇总/提现占位/流水布局。月份、测试范围、搜索、8条分页、详情、全量匹配XLSX导出接入真实供水接口。 - 收款复用 `saveWater('finance',{action:'purchase',...})`，企业和套餐远程选项、金额权益预览、凭据校验与核对勾选、提交锁和失败保留输入。后端凭据幂等，不重复发放权益。按钮校验 finance:write。 - 今日卡片固定今天，月趋势与汇总不受流水关键词和分页影响。未知退款/佣金/提现为“—/未开通”，审核按钮禁用；不引用旧租赁财务。测试范围与对账语义见父项目 `server/docs/WATER_FINANCE.md`。 - vue-tsc、相关ESLint/Prettier/Stylelint、Vite3323模块构建通过，dist更新。浏览器仍因工具 `unsupported Codex auth method: apikey` 不能点击或截图验收；接口及后端测试已通过。 ## 2026-09-11 代理商区域选图 - `catalog.ts`代理商region使用新`region-map`字段类型，`WaterWorkspace`交由`WaterRegionField`显示只读区域、地图选择、清空；已有值原样保留，选图确认后回填，代理商保存才提交。 - 共享`WaterLocationPicker.vue`支持点坐标和行政区名称模式；原`DispatchLocationPicker`为兼容包装，配送调用不变。`findMapRegion`使用高德逆地理编码，去重直辖市省/市并兼容空city；没有识别结果或失败时禁止确认。 - `node scripts/test-water-region.mjs`覆盖行政区、直辖市、缺区县、空结果和配额错误；原道路规划脚本、ESLint/vue-tsc及Vite构建验证。未修改既有代理商数据和数据库结构，浏览器实际选图验收仍未完成。 ## 2026-09-11 公共导航样式归属 - 供水导航深色样式改由 `src/views/index/index.vue` 导入同目录 `water-layout.scss`。此前依赖业务页懒加载，直接刷新独立设备/库存页会显示默认白色，访问总览后才恢复。 - `src/views/water/modules/water.scss` 仅保留业务页规则；以后独立页面无需为导航导入该文件。布局仍按原 `/water-` 路由范围应用品牌主题。 - Prettier/ESLint/vue-tsc及Vite3291模块构建通过，构建清单确认导航CSS包含在布局静态依赖中，与业务页面访问顺序无关。 ## 2026-09-11 配送履约闭环 - 配送页新增独立 `FulfillmentDialog.vue`（实收/部分签收/拒收、退回核对、关联重送、返仓结算）及 `DeliveryHistory.vue` 履约记录。任务展示实收数量、异常、父子重送编号和结算时间，新增待退回/已退回筛选；总览同步异常统计。 - 顶部“返仓结算”展示所选日期及以前全部未结算路线，不受任务池关键词/片区过滤。仓库动作同时检查 dispatch:write 和 inventory:write；表单失败保留输入，阻止重复提交，实物数量和差异需明确核对。对话框开启时暂停焦点刷新。 - 库存列表增加破损隔离满桶及累计空桶损失。具体状态、账务及迁移合同见父项目 `server/docs/WATER_FULFILLMENT.md`。当前为后台人工确认，未接入配送员移动端或客户电子签名。本轮浏览器工具运行时启动失败，未做视觉验收。 - 最终vue-tsc、相关ESLint/Prettier和Vite构建通过（3268 modules），4173预览已提供最新产物；实际HTTP闭环由父项目测试完成。任务池支持当天完成签收/退回的旧任务，避免核对后无法找到重送入口。 > 项目：`D:\phpstudy_pro\WWW\saiadmin6.x\saiadmin-artd` > > 记录日期：2026-08-25 > > 本文件只记录该前端子项目。父项目 `saiadmin6.x` 的记忆仍单独保存在父目录，不要混用。 ## 1. 项目定位 这是 SaiAdmin 6.x 配套的管理后台前端，当前与父项目中的 Webman 后端配套使用。项目包含登录、动态菜单权限、系统管理、商户管理、设备、订单、资金、运营管理、小程序和后台维护等页面。 当前重点业务已于 2026-09-09 调整为云泉智配企业供水：企业档案、套餐权益、库存、补货与配送。旧商户管理页面及数据保留。 ### 2026-09-09 供水业务合并 - 新页面 `src/views/water`，共享表单/列表 `modules/WaterWorkspace.vue`，总览单独实现；API `src/api/water`。 - 后端动态菜单新增 12 个入口，`src/router/modules/water.ts` 根据已授权菜单调整显示顺序并隐藏旧一级导航，不主动补发新业务权限。`src/store/modules/menu.ts` 优先将已授权 `/water-overview` 设为首页。 - 页面使用真实接口和空数据状态，无设计图示例经营数据。详情/盘点/签收表单接入后端基础事务；代理、角色、审计入口复用现有页面。 - 新配色限于 `.water-layout` 和 `.water-page`，品牌名为“云泉智配”，保留用户其他页面设置。 - 本轮尚未包含地图智能合单、设备饮水遥测、线上支付退款、自动佣金提现、移动端内容投放；功能边界见父项目 `server/docs/WATER_MERGE.md`。 - 验证：vue-tsc、相关 ESLint、Vite build 通过（3245 modules）；浏览器已验证总览真实零数据、12 个新菜单、企业表单必填校验、库存及旧审计页面。 ## 2. 技术栈与运行 ### 2026-09-10 补货预警接续 - 为验证15条演示预警分页，`WaterWorkspace.vue` 将补货模块页大小及API的limit统一为10，其他模块保持20。新增10家不同名称企业及东/西/南/北区域、山泉水/纯净水规格供筛选；数据脚本见父项目 `server/scripts/seed_water_alert_search_demo.php`。 - 补货搜索实际按企业名称/区域/规格模糊查询。用户反馈无效时已复现名称查询返回1条；搜索“1”会命中全部0910/18.9演示数据。页面已校正提示、增加重置及无匹配文案，并限制120字、去除首尾空格。 - 搜索调整通过vue-tsc、ESLint及Vite构建；浏览器验证名称查询1条、回车无匹配0条、重置恢复5条。 - `WaterWorkspace.vue` 增加仅预警/全部启用账户切换、数量阈值编辑、预警桶数列及当前页多选；切换查询清空选择，已建单或无可用权益账户不能批量选择。 - `modules/BatchDeliveryDialog.vue` 独立维护逐条配送数量和确认过程，列出地址、权益与现场满桶；未填数量不能提交，错误时保留表单，提交期间阻止重复提交或关闭。 - 策略保存使用 `saveWater('alerts',{action:'policy',id,threshold_qty})`；批量保存使用 `saveWater('dispatch',{action:'batch_create',items:[{account_id,quantity}]})`。按钮分别检查已有 alerts/dispatch write 权限。 - vue-tsc、相关 ESLint、Prettier 和 Vite production build 通过（3247 modules）；4173 浏览器确认入口、列和零数据布局。后端 69 项事务回滚检查通过；未在浏览器创建实际业务数据，非空弹窗仍待实际数据验收。 - Vue 3 + TypeScript + Vite 7 - Element Plus、Pinia、Vue Router 4、Axios、VueUse、Vue I18n - ECharts 6、Tailwind CSS 4、WangEditor、XLSX、FileSaver - 包管理器：pnpm - Node 要求：`>=20.19.0`；已知本机 Node：`v22.21.0` - 项目依赖目录 `node_modules` 已存在；如果 pnpm 未加入 PATH，可直接使用 `node_modules/.bin` 中的工具 常用命令： ```bash pnpm dev # 开发服务器，默认端口 3006 pnpm build # vue-tsc --noEmit 后执行 vite build pnpm lint # ESLint pnpm serve # 预览构建结果 ``` 已知验证结果： - `vue-tsc --noEmit` 已通过 - Vite 生产构建已通过，约 3152 个模块转换成功 ## 3. 环境变量与后端连接 环境文件：`.env`、`.env.development`、`.env.production`。不要把密钥值写入项目记忆。 关键变量： - `VITE_ACCESS_MODE=backend`：当前使用后端菜单模式 - `VITE_API_URL`：Axios 的 baseURL；开发环境为 `/api` - `VITE_API_PROXY_URL`：开发代理目标，当前为 `http://127.0.0.1:8787` - `VITE_BASE_URL`：当前为 `/` - `VITE_PORT`：当前开发端口为 `3006` - `VITE_WITH_CREDENTIALS`：是否携带 Cookie - `VITE_VERSION`、`VITE_DROP_CONSOLE`、`VITE_OPEN_ROUTE_INFO` - `VITE_LOCK_ENCRYPT_KEY`：锁屏相关密钥，仅使用环境文件中的值，不复制到记忆 `vite.config.ts` 将 `/api` 代理到 Webman 后端 `127.0.0.1:8787`，并去除 `/api` 前缀。生产环境默认直接访问 `http://127.0.0.1:8787`，部署时需按实际后端地址调整环境配置。 ## 4. 入口和目录结构 - `src/main.ts`：创建 App，初始化 Pinia、Router、语言、指令和错误处理 - `src/App.vue`：Element Plus 配置、主题、存储兼容性和系统升级检查 - `src/api/`：按业务拆分的 Axios API 封装（当前约 31 个文件） - `src/views/`：页面组件（当前约 132 个文件） - `src/components/core/`：通用后台布局、表单、表格、图表和基础组件 - `src/components/sai/`：项目业务组件，例如 `SaSearchBar`、`SaDict`、上传和导入导出组件 - `src/store/`：Pinia store - `src/router/`：静态路由、动态路由、守卫和路由转换核心 - `src/locales/`：多语言资源 - `src/config/`：系统名称、主题、布局和头部配置 - `src/types/`：API、路由、组件、配置和 store 类型 - `src/assets/`：图片、SVG 和样式 页面通常按 `src/views/<业务>/<页面>/index.vue` 组织，复杂页面的子组件放在同级 `modules/` 目录。API 按业务放在 `src/api/<业务>/`，例如 `src/api/merchant/merchant.ts`。 Vite 别名：`@` 指向 `src`，另有 `@views`、`@imgs`、`@icons`、`@utils`、`@stores`、`@styles`。 ## 5. 路由、菜单和权限 - `src/router/index.ts` 使用 `createWebHashHistory()`，因此访问地址形如 `/#/merchant/statistics?id=73` - `src/router/routes/staticRoutes.ts` 注册登录、注册、忘记密码、403、404、500 和 iframe 等静态路由 - `src/router/routes/asyncRoutes.ts` 汇总前端模块路由 - `src/router/modules/` 保存 dashboard、system、merchant、mini-program、operations 等模块路由 - 登录后，`src/router/guards/beforeEach.ts` 并行获取用户信息、字典和菜单，然后注册动态路由 - `src/router/core/MenuProcessor.ts` 根据 `VITE_ACCESS_MODE` 在前端菜单和后端菜单之间切换；当前是 backend 模式，通过 `/core/system/menu` 获取菜单 - 后端菜单路径会被规范化为完整路径，并补充/合并前端维护的 MiniProgram、Merchant、Device、Agent 菜单项（用于兼容后端菜单尚未同步的情况） - `RouteRegistry` 负责注册/移除动态路由；`RouteTransformer` 负责 Layout、iframe、全屏页和普通组件转换 - `ComponentLoader` 使用 `import.meta.glob('../../views/**/*.vue')` 按需懒加载页面，组件字段通常写成 `/merchant/my-merchant` 这类视图路径 - `RoutePermissionValidator` 负责路径、动态参数和菜单前缀权限匹配 - 登出或 401 后会清理动态路由、菜单和 iframe 路由缓存，再回到登录页 修改后端菜单时要特别注意：后端返回的 path、name、component、children、meta 必须符合 `AppRouteRecord` 和 `RouteValidator` 规则；二级及以下菜单不要错误使用 Layout 作为 component。 ## 6. HTTP 请求和认证约定 统一请求封装在 `src/utils/http/index.ts`： - Axios 默认超时 15 秒，baseURL 读取 `VITE_API_URL` - 请求会从 `useUserStore().accessToken` 读取令牌，并添加 `Authorization: Bearer ` - 非 FormData 请求会自动设置 JSON 请求头并序列化 data - POST/PUT 如果调用方只传 `params` 且没有 `data`，封装层会把 params 转成请求体 - 后端成功响应必须是 `{ code: 200, message: string, data: T }`；封装层最终返回 `data` - 非 200 业务 code 会转成 `HttpError`；401 会防抖提示、清理登录状态并跳转登录 - 当前 `MAX_RETRIES=0`，虽然保留了可配置重试逻辑，但默认不会自动重试 - `responseType: 'blob'` 时直接返回二进制响应，用于导出文件 认证 API 在 `src/api/auth.ts`： - 验证码：`GET /core/captcha` - 登录：`POST /core/login` - 用户信息：`GET /core/system/user` - 字典：`GET /core/system/dictAll` - 后端菜单：`GET /core/system/menu` 登录页 `src/views/auth/login/index.vue` 在挂载和登录失败后刷新验证码，保存 `uuid` 和 `image`；验证码接口需要避免浏览器缓存时应在请求层增加时间戳参数或正确的缓存响应头。 ## 7. 状态管理和持久化 `src/store/index.ts` 创建 Pinia，并通过 `pinia-plugin-persistedstate` 使用 localStorage 持久化。主要 store： - `user`：登录状态、用户信息、access/refresh token、语言、锁屏和搜索历史 - `menu`：后端菜单、首页路径、动态路由移除函数 - `dict`：全局字典缓存 - `setting`：菜单布局、主题、工作台、界面开关等 - `worktab`：工作台标签和 keep-alive 状态 - `table`：表格相关状态 持久化 key 由 `StorageKeyManager` 版本化管理，修改字段或版本时要考虑旧 localStorage 数据兼容。登出逻辑会清理 token、用户信息、动态路由和 iframe 缓存，但按设计保留部分工作台标签，下一次登录会根据用户 ID判断是否清理。 ## 8. 商户模块现状 路由定义在 `src/router/modules/merchant.ts`，当前包括： - `/merchant/my-merchant`：我的商户 - `/merchant/subordinate-merchant`：下级商户，复用 `my-merchant/index.vue`，通过 `subordinate` prop 切换查询范围 - `/merchant/add-merchant`：新增商户 - `/merchant/statistics`：商户数据统计，通常通过 query `id` 进入 API 在 `src/api/merchant/merchant.ts`，主要接口： - `GET /core/merchant/index`：商户分页列表；`scope` 支持 `own` / `subordinate`，并支持名称、电话、分配状态、状态、分润方式、设备类别、代理类型等筛选 - `GET /core/merchant/read` - `POST /core/merchant/save` - `PUT /core/merchant/update` - `DELETE /core/merchant/destroy` - `POST /core/merchant/password` - `GET /core/merchant/devices` - `POST /core/merchant/device/bind` - `POST /core/merchant/device/unbind` - `GET/PUT /core/merchant/withdrawal-setting` - `GET /core/merchant/statistics` - `POST /core/merchant/statistics/export`：Blob 导出 商户列表返回分页结构 `current_page/data/per_page/total`，并包含分类统计 `summary`：`all`、`city-partner`、`agent`、`salesperson`。统计接口返回商户信息、日期范围、汇总、支付方式和每日数据。 已验证的业务结果： - `/merchant/statistics?id=73` 可以正常加载统计页面并与后端交互 - `/merchant/subordinate-merchant` 可以加载后端列表 - 下级商户分类示例：全部 65、城市合伙人 22、代理商 22、业务员 21 - 商户名称搜索可以过滤到单条结果 近期新增/修改的商户相关文件包括： - `src/router/modules/merchant.ts` - `src/router/modules/index.ts` - `src/router/core/MenuProcessor.ts` - `src/api/merchant/merchant.ts` - `src/views/merchant/my-merchant/index.vue` - `src/views/merchant/subordinate-merchant/index.vue` - `src/views/merchant/statistics/index.vue` ## 9. 代理与设备分配模块现状 - `src/api/agent/agent.ts` 提供代理分页、导出、当前账号可分配设备、分配、回收和分配流水 API。 - `src/views/agent/components/AgentList.vue` 已从静态演示数据切换为真实 API，支持筛选、后端分页、导出，并接入设备分配和分配记录弹窗。 - `DeviceAssignmentDialog.vue` 支持库存勾选与手工/扫码 SN 合并，单次最多 100 台，并分别展示成功、已在目标、非当前管理、已铺货和未找到结果。 - `AssignmentRecordsDialog.vue` 支持按操作、设备类型和 SN 查询流水，并可从历史分配记录发起回收；后端仍会复核设备当前管理人和铺货状态。 - `/device/assign` 是隐藏的去分配页面；“我的设备”勾选未铺货设备后进入该页面会通过 `sns` query 预填待分配 SN。 - 2026-08-27 验证：代理分配相关文件通过 ESLint，`vue-tsc --noEmit` 通过；Vite production build 通过（3173 modules），仅有既有 system menu 动静态导入警告；真实 HTTP 分配、流水查询和回收闭环通过。 - `src/views/agent/edit-agent/index.vue` 是真实代理修改页，通过 `/agent/edit-agent?id=...` 进入；运营产品控制对应分润输入，开通类型只读，重置恢复接口加载快照，页面不修改密码或登录账号。 - `src/api/agent/agent.ts` 已增加 `AgentProfile` / `AgentUpdatePayload` 类型，以及 `GET /core/agent/read`、`PUT /core/agent/update` 封装。 - 代理列表“更多设置”使用点击下拉菜单展示合同管理、设备绑定、删除代理；合同管理已跳转 `/agent/contract?id=...` 并接入真实读写，设备绑定和删除代理仍显示未接入提示，不执行危险操作。 - 2026-08-27 验证：代理修改及更多设置相关文件通过 Prettier、ESLint、`vue-tsc --noEmit`；Vite production build 通过（3177 modules），只有既有 system menu 动静态导入警告；真实 HTTP 修改、读取和恢复闭环通过。 - `src/views/agent/contract/index.vue` 使用 `SaImageUpload` 维护合同照片、身份信息和其他信息，每组最多 20 张；API 为 `GET/PUT /core/agent/contract`，后端持久化到 `sa_agent_contract`。 - 2026-08-27 验证：合同页相关文件通过 Prettier、ESLint、`vue-tsc --noEmit`；Vite production build 通过（3180 modules）。浏览器实际加载 `/agent/contract?id=101`，代理信息、三组上传区和提交按钮渲染正常。 ## 10. 资金管理会员开通记录 - `src/views/fund-management/member-activation-records/index.vue` 已从占位页切换为真实列表，支持来源、卡类型、设备类型、用户、开通日期筛选，以及汇总、分页、重置和 Excel 导出。 - 前端 API 位于 `src/api/fundManagement/memberActivationRecord.ts`，列表和导出接口分别为 `GET /core/fund-management/member-activation-records/index`、`POST /core/fund-management/member-activation-records/export`。 - 后端使用 `sa_member_activation_record` 保存会员开通/续费业务快照，不从普通租借订单推测历史会员数据；数据按当前管理员及递归下级范围隔离。 - 2026-09-05 验证：ESLint、`vue-tsc --noEmit`、PHP 语法检查和 Vite production build 通过；本地数据库、API、筛选、重置和 Excel 导出闭环通过，测试数据为 3 条。 ## 11. 当前注意事项和后续检查 - 工作树中有大量业务新增和修改文件，均视为用户现有工作；不要 reset、checkout、清理未跟踪文件或覆盖无关改动 - `pnpm build` 已通过，但修改路由、API 类型或页面后仍应至少重新执行 `pnpm build` - 开发环境前端端口是 3006；用户之前使用的 `http://localhost:4173` 属于其他预览/开发实例，排查时先确认当前实际启动端口和 Vite 进程 - 验证码问题要同时检查 `/api/core/captcha` 的代理、后端 `/core/captcha` 响应格式、浏览器缓存以及 `image` 是否为完整 data URL - 若出现 304、无法登录或页面跳 404，优先检查 Network 中请求 URL、响应 `{ code, message, data }` 结构、Authorization、动态菜单初始化和路由 component 路径 - 商户页面必须使用真实 API 请求，不要用静态数组替代后端数据；筛选、分页、统计日期和导出都要保持接口参数与后端一致 ## 12. 记忆更新规则 后续修改该子项目后，在本文件追加或更新：变更文件、接口/路由约定、已验证命令、已知问题和未完成事项。只记录已经从代码、接口或实际运行结果确认的信息；敏感环境变量值、token、密码和用户隐私不要写入。 ## 2026-09-10 库存流水查询与导出 - 库存管理的“查看库存流水”使用独立组件 `WaterLedgerDrawer.vue`，不再限制最近 100 条；默认每页 10 条，可选 20/50/100 条，支持页码跳转、关键词、操作类型、起止日期、重置和空结果提示。 - `WaterLedger` 服务统一列表/导出筛选口径：企业名、商品名、关联凭据、说明，日期包含结束日全天；操作类型及中文名称由后端提供。保留原库存/配送九种流水，档案、收款等其他审计不混入。 - `GET /core/water/ledger` 返回分页及 `kinds`，`POST /core/water/ledger/export` 接收相同筛选，导出当前已查询条件的全部 XLSX（忽略 page/limit），超过 50,000 条明确拒绝。两接口均要求库存读取权限；临时文件位于系统临时目录，响应生成后删除。 - 验证：PHP lint、ESLint、vue-tsc、Vite build（3250 modules）通过；`php tests/water_ledger_test.php` 30 项、原 `water_business_test.php` 69 项通过，测试数据全部回滚。浏览器现有 20 条流水分成两页；第二页搜索星河返回第一页 1 条，下载 XLSX 解析确认 1 条星河数据加表头，空结果禁用导出，重置恢复 20 条。 - 2026-09-10：库存流水开始日期、结束日期改为两个独立的单日期选择框，可只填一端或选择跨日范围；查询前提示开始晚于结束，列表与导出继续复用 start_date/end_date。 - 日期拆分验证：ESLint、vue-tsc、Vite build 通过；浏览器分别选择 2026-09-01 和 2026-09-10 后查询成功，两个日期保持独立。 ## 2026-09-10 配送调度中心 - `/water-dispatch` 已从 WaterWorkspace 普通列表换为独立调度看板：真实片区任务池、日期/关键词/片区筛选、配送员状态、站点地图、路线摘要/完整路线、任务状态分页及当前页 Excel 导出。原企业/库存/预警页面保持共享组件，调度详情跳转带入关键词。 - 后端新增 `WaterDispatch.php`：看板、配送员档案、每日排班、车辆容量、待派单任务日期/时限/位置、区域和时限优先合单预览及原子确认。任务、库存、权益仍复用 WaterBusiness；完整路线单独查询，避免关键词/日期过滤漏站。 - 已执行可重入增量迁移 `php scripts/migrate_water_dispatch.php --apply`：新增 driver/driver_shift/route 三张表，企业经纬度和配送计划/路线字段。旧任务姓名电话关联到 2 位既有测试配送员，未推断排班，当前容量使用可编辑默认 100 桶；3 单 24 桶、待派单 1/配送中 2 的状态未改变。 - `GET /core/water/dispatch/board`、`GET /core/water/dispatch/route` 需要配送读取权限，`GET /core/water/dispatch/plan` 和 POST dispatch 新 action 需要管理权限。合单按容量及相同片区校验，原始自由文本 HTTP 派单不再使用，单笔派单也生成经校验的路线。 - 地图使用现有高德配置，仅展示登记过的坐标和站序连线。当前模拟企业无坐标，显示真实空状态；没有道路优化、预计到达时间、GPS轨迹或配送员在线心跳。之前“地图合单未实现”的描述由本条取代：区域/容量/时限合单和坐标地图已实现，道路导航优化仍未接入。 - 后端41项调度测试、69项供水业务、30项库存流水、30项设备接入共170项通过，新增测试记录全部回滚；ESLint、vue-tsc、Vite构建通过。浏览器确认3单24桶，搜索智配办公后任务池/路线/明细同为1单6桶，排班档案和新增表单可用，无候选方案禁用合单确认。细节与回退见 `server/docs/WATER_DISPATCH.md`。 - 最终浏览器补充验证：配送员新增表单包含姓名、电话、片区、车辆容量；任务详情跳转补货预警自动带入智配办公，显示1条账户且关联已有配送。最终页面保持原供水侧栏样式，显示当日未排班2人和当前页Excel导出入口。 ## 2026-09-10 高德地图实际接入 - 配送地图不再因无任务坐标提前退出：始终初始化真实高德底图，无坐标默认全国视野，有坐标按路线展示编号站点及顺序连线，含比例尺、缩放、查看全部站点、点选任务和失败重试。 - `src/utils/waterAmap.ts` 统一供水地图和选点弹窗的脚本/插件加载，复用既有高德脚本标识与本地 VITE_AMAP_KEY/VITE_AMAP_SECURITY_CODE，配置值不记入文档。 - `DispatchLocationPicker.vue` 为配送计划增加地址搜索及地图选点，确认回填后保存才写入配送任务坐标；保存后切换到对应任务组展示。后端沿用已有 schedule 校验，企业地址和库存/权益不受影响。 - 浏览器实际确认全国高德底图、比例尺/缩放正常；上海市浦东新区世纪大道1号地址解析和标记正常，坐标回填成功；验证后取消计划，未把验证坐标保存进模拟任务。不存在道路导航或实时GPS轨迹接入。 - 最终 ESLint、vue-tsc 和 Vite production build 均通过；已刷新4173预览加载高德地图版本。 ## 2026-09-10 深圳地图测试坐标 - 用户要求以南油第四工业区4栋出发、送往中洲大厦；目的地按南山区海德一道中洲控股中心处理（已询问具体大厦，当前按此默认）。两个地址经项目高德 Geocoder 查询：出发 GCJ-02 113.924140,22.522806；送达 113.935124,22.516070。 - 已执行 `php scripts/seed_water_shenzhen_coordinates.php --apply`，仅给任务9/10/11及其对应3个【测试0910】企业更新地址、深圳南山区片区和坐标；任务新增 origin_address/origin_longitude/origin_latitude 记录出发点，结构由原 dispatch 增量迁移扩展。 - 三条测试任务使用同一出发点及目的地，保留原8/6/10桶、待派单/配送中/配送中状态，未额外建单或修改库存、权益、收款。脚本事务内校验业务表和非位置字段保持一致，固定批次标记复跑不覆盖后续用户修改；原测试行快照位于 server/runtime/water-shenzhen-map-before.json。 - 地图新增橙色“起”标记，单任务起点至送达点及同路线按站序绘制示意连线；路线卡和详情显示出发地址。未调用道路导航服务。 - 脚本 PHP lint 和41项配送回归检查通过，脚本已复跑确认 replayed=true。 - 深圳坐标最终验证：ESLint、vue-tsc、Vite构建通过；浏览器确认深圳南山区3单24桶、橙色起点与蓝色送达点均显示，起止示意连线及出发地址正常。 ## 2026-09-10 高德驾车线路规划 - 已替换 DispatchMap 的直线示意：单任务或同一真实路线具有唯一出发点及完整送达坐标时，通过 AMap.Driving 按既有站序绘制实际道路，显示预计公里/分钟（不含配送停留），支持重新规划。此前“未接入道路导航”的记录由本条更新；尚无实时GPS及各站承诺到达时间。 - waterAmap.ts 独立加载驾车插件，每次最多16个途经点，超长路线分段并汇总，保留全部站序；连续重复位置去重，部分失败不展示不完整线路。缺坐标、多起点、未成路线的多任务组明确提示；切换时丢弃旧结果，真实路线等待完整站点接口后才规划。 - 验证：ESLint、vue-tsc、Vite build 通过；node scripts/test-water-driving.mjs 覆盖分段不漏站、汇总、重复坐标、旧请求及服务失败。浏览器实测南油第四工业区4栋至中洲控股中心道路约2.0公里，初次11分钟、重新规划10分钟，用时随路况变化。本次未更改订单或库存等业务数据。 ## 2026-09-11 智能设备看板 - 设备测试数据已添加：`seed_water_device_dashboard_demo.php --apply`固定批次12台【测试0911】设备（ID26–37）、四区各3台、298条模拟用水日记录。写入时6在线/2离线/2告警/2未接入，每页8条分两页；版本三种测试版本及未登记。心跳15分钟后自然离线，脚本复跑不覆盖用户修改。原库存、权益、订单和配送未变。 - `src/views/water/devices/index.vue` 按用户图片重做，拆分卡片、编辑弹窗、版本弹窗、分析图表、展示函数和 `useDeviceDashboard`；接口类型在 `src/api/water/devices.ts`。 - 新增可复用 `WaterMetricCards.vue`、`useWaterOptions.ts`、`utils/waterDownload.ts`；远程选项保留原选择、防旧请求覆盖，导出校验XLSX和错误响应。设备编辑继续走原写入接口/权限。 - 四种互斥状态由后端统一，卡片显示真实用量/上报；查询只影响8条分页列表及全量导出，统计和图表保持全量。未接入不算离线，缺失用量显示—。 - 固件入口为版本分布与档案维护，无OTA；趋势依赖新日累计表，无历史数据显示空状态，异常表显示当前实际故障/离线而非虚构24小时统计。 - 45项新看板及30项接入检查通过、全部夹具回滚；前端Prettier/ESLint/vue-tsc与Vite3290模块构建通过。浏览器工具启动os error3，视觉验收未完成。详见 `../server/docs/WATER_DEVICE_DASHBOARD.md`。 ## 2026-09-11 库存看板 - `src/views/water/inventory/index.vue` 替换共享工作台入口，布局按用户参考图：四张卡、左侧规格表/七日趋势、右侧库存构成；新增 `InventoryForm.vue` 和页面限定 `inventory.scss`，保留 `WaterLedgerDrawer`。 - `getWaterInventory` / `exportWaterInventory` 接真实后端读模型；统计全量，表格搜索分页，导出全部匹配规格。路由 keyword 变化同步查询，窗口回焦刷新但避开正在操作的弹窗，失败显示明确错误。 - 规格详情保留破损、空桶损失；入库/盘点走原写接口，盘点对象变更清空实际数量，提交中禁用编辑。读写权限入口沿用库存权限。 - 库存50项（含HTTP）及原业务69项验证通过，事务测试数据回滚；ESLint、vue-tsc、Vite构建通过。浏览器工具启动报 os error 3，本次未做视觉验收；详见 `../server/docs/WATER_INVENTORY.md`。 ## 2026-09-10 配送优化策略与Eloquent模型 - 用户明确要求最短距离、最快送达、时限优先，以及模型数据访问。本次供水业务整体切换Eloquent：model/water独立模型及关联，WaterBusiness/WaterDispatch/WaterLedger/WaterRoutePlanning、供水权限与选项读取、设备报告均不再使用Think ORM或Db::table；框架原登录和其他模块不迁移。测试及调用业务服务的种子脚本统一Eloquent事务连接。 - service/routing 的 RouteStrategy 与三个具体策略，以有向高德道路矩阵计算固定批次站序；最多8站穷举，固定共同出发点、不返仓。最短距离按总里程，最快送达按总完成用时，时限策略按超时站数→超时总秒数→总用时。含可配置每站配送停留，无时限时按用时比较，不代表跨车队全局最优或未来路况预测。 - 配送页面新增“线路优化”，合单预览各批新增“选择策略并优化”；可查看优化前后指标、每站到达/完成时间、超时和道路地图。仅尚未出库的已派单路线可应用；待派单批次在合单确认时应用。配送计划补齐出发地址与坐标选点。 - POST dispatch新增 optimize / optimize_apply，plan_commit各组支持optimization_token。后端重新读取模型校验坐标并执行策略，预览绑定操作员、任务指纹，10分钟过期；保存时再次校验状态、站序、日期，行锁及原库存/权益逻辑保持一致，重复提交幂等。路线optimization保存策略及估计，地图以保存策略重新调用高德。 - 已执行 scripts/migrate_water_routing.php --apply，仅新增sa_water_route.optimization和sa_water_route_preview。道路成本由浏览器JS API提供，后端校验格式与任务匹配，不独立核验高德来源；仅作为调度估计，不驱动扣款或库存数量。 - 本机PHP需原生mbstring。Windows supervisor已用项目脚本重启并启用扩展；scripts/start_water.ps1及windows.php向子进程传递config/php/mbstring.ini，不修改全局php.ini。CLI回归使用php -d extension=mbstring tests/文件名。 - 194项后端回归通过（业务69、调度41、流水30、设备30、策略/模型24），测试数据全部回滚；前端ESLint、vue-tsc、道路矩阵与取消/配额错误测试通过。浏览器实测三种策略并给生态园测试路线14保存时限优先，仍5单34桶，状态不变。现有测试路线为单站，多站不同排序由三站集成测试覆盖。详细契约及限制见server/docs/WATER_ROUTING_STRATEGIES.md。 - 最终Vite构建通过，浏览器刷新后显示路线14已保存“时限优先”，仍5单34桶；策略选择框宽度及优化预览地图高度已调整。