diff --git a/docs/用户偏好配置-排序与跨设备同步设计.md b/docs/用户偏好配置-排序与跨设备同步设计.md new file mode 100644 index 00000000..e9d8a4b6 --- /dev/null +++ b/docs/用户偏好配置-排序与跨设备同步设计.md @@ -0,0 +1,417 @@ +# 用户偏好配置:每账号每页面自定义排序(纯浏览器本地保存方案) + +- 状态:**已决策** —— 接口方案已废弃,正式采用纯浏览器本地保存(方案B,见 §8) +- 决策日期:2026-09-01 +- 版本:v2.0(方案B 为正式方案;§2~§6 接口方案存档仅参考) + +## 读者导航 + +| 角色 | 重点阅读 | +|------|---------| +| **前端(实现设计)** | §8 正式方案(纯浏览器保存)、§7 前端设计(复用 store 抽象与接入模板) | +| **后端** | 无需开发接口;如需了解已废弃方案可参考 §2~§6(勿按此实现) | + +--- + +## 0. 方案决策(2026-09-01) + +> **接口方案(方案A,§2~§6 的 `user.preference.*`)已废弃**,不再开发后端接口。 +> 正式方案为 **§8 纯浏览器本地保存(localStorage)**:零后端依赖、每账号按 user_id 隔离、同设备跨刷新/会话生效。 +> **已放弃「跨设备同步」**:浏览器数据不经过服务端,无法跨设备。若将来需跨设备,再评估是否恢复接口方案。 +> 前端实现只需关注 §8、§7(store 抽象 / 接入模板 / 兜底);§2~§6 仅存档参考。 + +--- + +## 1. 背景与目标 + +订单管理 `order/orderManagement` 各 tab(待审核订单、待处理订单、待处理异常订单、配送单等)当前排序由用户本次操作决定,刷新/换设备后丢失。需要: + +1. 每个 tab 页可配置自定义排序(排序字段 + 排序方向)。 +2. 排序配置**绑定账号**(同设备内按 user_id 隔离保存)。 +3. **刷新/重新登录后自动应用**已保存配置。 + +> 说明:原「跨设备同步」目标因采用纯浏览器方案(§8)而**放弃**(浏览器数据不经过服务端,见 §0 决策)。 + +该机制设计为**模块无关**:除订单模块外,`order/waveOrder`、`setting/basicManagement` 等页面均可复用(按同一 key 规范注册即可)。 + +### 非目标(本期不做) + +- **不做跨设备同步**(纯浏览器方案的固有取舍,见 §0)。 +- 不要求"不刷新页面也实时同步"(浏览器本地保存天然即时生效,无需轮询)。 +- 不做多用户/角色的差异化权限(配置仅按 user_id 隔离)。 +- 不做复杂多级排序 UI(数据结构预留 `secondary`,UI 本期只做单字段)。 + +--- + +## 2. 通用约定(前后端共用)【已废弃:接口方案存档】 + +> ⚠️ 本节及 §3~§6 为**已废弃的接口方案(方案A)存档**,仅供将来可能恢复时参考;当前实现**不采用**,勿按此开发接口。正式方案见 §8。 + +### 2.1 接口风格 + +- 全部走统一系统接口:`POST /system` +- URL Query:`method` / `v`(=1.0)/ `timestamp` +- 请求体:`data`(业务参数,JSON) +- 请求头:`Authorization: Bearer `,`platform: web`,`project: all` + +### 2.2 认证与用户隔离 + +- 所有接口需登录(`isNeedAuth=false`、`isNeedLogin=true` 口径与 `order.export` 一致)。 +- `user_id` **一律由服务端从 token 解析**,接口不接受前端传 user_id(安全边界)。 + +### 2.3 scope 命名规范 + +统一格式:`<模块>.<能力>.<页面标识>`,全小写,`.` 分隔。示例:`order.sort.pending`。 + +### 2.4 value 即不透明 JSON + +- `value` 对接口层是**不透明 JSON**:后端只做白名单校验 + 存储 + 体积校验,不解析业务结构;业务结构由前端各页面定义与校验(见 §6.3)。 +- 这样保证"新增一个功能 = 新增一个 scope",后端接口零改动。 + +--- + +## 3. 通用响应封装 + +```jsonc +// 成功 +{ "code": 200, "flag": "success", "message": "ok", "data": { ... } } +// 失败 +{ "code": 40007, "flag": "fail", "message": "scope 未在白名单内", "data": null } +``` + +- 成功码:`200 / 20000 / 1 / 0`(前端 `request.ts` 统一判定)。 +- `code !== 成功码` 时,前端优先展示 `message`,并可按 code 做分支处理(见 §4)。 + +--- + +## 4. 错误码表(后端按此实现) + +> 建议码段,后端可对齐现有 `ERROR_CODE_MAP` 惯例后调整,但**前端会按这些语义分支**,请保持语义一致。 + +| code | 含义 | 前端行为 | +|------|------|---------| +| 200 / 20000 / 1 / 0 | 成功 | - | +| 40007 | `scope` 未在白名单 / 格式非法 | 提示错误,不写入、不覆盖本地 | +| 40008 | `value` 超过体积上限(>4KB) | 提示错误,不写入 | +| 40009 | 乐观锁冲突(`base_updated_at` 与服务端 `updated_at` 不一致) | 弹窗提示「该配置已在其他设备更新」,提供「以本地为准覆盖」或「放弃」 | +| 40010 | 参数缺失 / 类型错误(如缺 `scope`、`value` 非对象) | 提示错误 | +| 401 / 50008 / 50012 / 50014 | 未登录 / 登录失效 | 跳转登录 | +| 403 / 40005 / 40006 | 无操作权限 | 提示无权限 | + +--- + +## 5. 接口契约(后端按此开发)【已废弃:接口方案存档】 + +### 5.1 `user.preference.get` — 获取偏好 + +**请求** + +| 项 | 值 | +|----|----| +| method | `user.preference.get` | +| 入参(data) | 见下表 | + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| scope | string | 否 | 指定时只返回该 scope;缺省返回该用户**全部**偏好 | +| scope[](扩展,待确认) | array<string> | 否 | 可选支持批量查询(见 §11-2) | + +**响应 `data`** + +``` +data: { + [scope: string]: { + value: object, // 该 scope 的配置内容(不透明 JSON) + updated_at: number // 毫秒时间戳,写入/乐观锁使用 + } +} +``` + +- 未注册的 `scope`(不在白名单):**返回空对象,不报错**(幂等友好)。 +- 该用户无任何配置:`data = {}`。 + +**成功示例** + +```jsonc +// 请求 +POST /system?method=user.preference.get&v=1.0×tamp=... +{ "scope": "order.sort.pending" } + +// 响应 +{ + "code": 200, + "flag": "success", + "message": "ok", + "data": { + "order.sort.pending": { + "value": { "field": "create_at", "order": "desc", "secondary": [{ "field": "id", "order": "asc" }] }, + "updated_at": 1720000000000 + } + } +} +``` + +--- + +### 5.2 `user.preference.set` — 保存偏好 + +**请求** + +| 项 | 值 | +|----|----| +| method | `user.preference.set` | +| 入参(data) | 见下表 | + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| scope | string | 是 | 必须命中白名单,否则返回 `40007` | +| value | object | 是 | 可 JSON 序列化对象;非对象返回 `40010`;序列化后 >4KB 返回 `40008`;传 `{}` 视为**清空/重置该 scope**(后端删除该行) | +| base_updated_at | number | 否 | 乐观锁:不传 = 强制覆盖(首次写入用);传入后与服务端当前 `updated_at` 不一致 → 返回 `40009` 冲突,不写入 | + +**响应 `data`** + +``` +data: { + scope: string, // 写入的 scope + updated_at: number // 本次写入后的最新毫秒时间戳(后续 set 用其作为 base_updated_at) +} +``` + +**成功示例** + +```jsonc +// 请求 +POST /system?method=user.preference.set&v=1.0×tamp=... +{ + "scope": "order.sort.pending", + "value": { "field": "create_at", "order": "desc" }, + "base_updated_at": 1720000000000 +} + +// 响应 +{ "code": 200, "flag": "success", "message": "ok", "data": { "scope": "order.sort.pending", "updated_at": 1720000100000 } } +``` + +**冲突示例(40009)** + +```jsonc +// 请求(base_updated_at 与服务端已不一致) +{ "scope": "order.sort.pending", "value": { "field": "id", "order": "asc" }, "base_updated_at": 1720000000000 } + +// 响应 +{ "code": 40009, "flag": "fail", "message": "配置已在其他设备更新", "data": { "current_updated_at": 1720000200000 } } +``` + +> 冲突时建议后端在 `data` 返回 `current_updated_at`,供前端展示/提示「以本地为准覆盖」时使用。 + +--- + +## 6. 数据模型与 scope 注册表 + +### 6.1 存储模型(后端) + +**关系表方案(推荐)** + +```sql +CREATE TABLE `user_preferences` ( + `user_id` BIGINT NOT NULL COMMENT '用户ID(服务端从 token 取)', + `scope` VARCHAR(128) NOT NULL COMMENT '命名空间 key:<模块>.<能力>.<页面标识>', + `value` JSON NOT NULL COMMENT '配置内容(不透明 JSON,前端各页定义结构)', + `updated_at` BIGINT NOT NULL COMMENT '毫秒时间戳,用于乐观锁与跨设备同步探测', + PRIMARY KEY (`user_id`, `scope`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户偏好配置'; +``` + +**Redis 方案(可选)**:`user_prefs:{userId}` Hash,field=scope,value=JSON;另存 `updated_at` 字段于同一 hash(或 `user_prefs_ver:{userId}`)。 + +### 6.2 scope 注册表(前后端共享白名单) + +> 后端以此表做 `set` 白名单校验;前端以此表注册各页消费。新增功能 = 在此表加一行。 + +**本期(排序)** + +| scope | 含义 | +|-------|------| +| `order.sort.review` | 待审核订单排序 | +| `order.sort.pending` | 待处理订单排序 | +| `order.sort.pendingException` | 待处理异常订单排序 | +| `order.sort.delivery` | 配送单排序 | +| `order.sort.archive` | 归档单排序 | +| `order.sort.outbound` | 出库单排序 | + +**预留(后续功能直接注册,后端接口零改动)** + +| scope | 含义 | +|-------|------| +| `order.columns.` | 列显隐/顺序 | +| `order.filter.preset.` | 筛选条件预设 | +| `order.table.` | pageSize / 表格密度 | +| `setting.*` | 基础管理设置类页面偏好(按 `模块.能力.页面` 命名) | + +### 6.3 排序 value 结构(排序类 scope 的约定结构) + +> 接口层不感知此结构(§2.4);下表是**前端各排序页面统一遵守**的 value 约定,便于跨页复用与后端抽查时理解。 + +```jsonc +{ + "field": "create_at", // string:排序字段名,须命中各页 sort 白名单(前端校验) + "order": "desc", // 'asc' | 'desc' + "secondary": [ // 可选:多级排序预留(数组顺序=优先级) + { "field": "id", "order": "asc" } + ] +} +``` + +- 消费时主排序取 `field/order`,转各列表接口的 `{ sortField, sortOrder }`(如 `order.list`)。 +- 若后端列表接口暂只支持单字段排序,本期只透传主排序(见 §11-3)。 + +--- + +## 7. 前端设计(前端按此实现)【接口方案版;方案B 复用其中 store 抽象、接入模板与兜底思路】 + +### 7.1 `userPreference` store 职责 + +新建 `src/stores/modules/userPreference.ts`(Pinia): + +- `load()`:调 `user.preference.get`(不传 scope)拉取全部偏好 → 写内存 + localStorage(key 含 user_id,如 `user_prefs_{userId}`)。 +- `get(scope)`:内存 → localStorage → 默认值,逐级兜底。 +- `set(scope, value)`:本地立即生效 + 防抖写回 `user.preference.set`(带 `base_updated_at`)。 +- `reset(scope)`:`set(scope, {})` 清空该 scope。 +- `isLoaded` / `lastLoadedAt`:避免会话内重复全量拉取。 + +### 7.2 拉取时机(核心) + +| 触发点 | 行为 | +|--------|------| +| 登录成功 / 整页刷新(`permission.ts` 守卫走 `userStore.getInfo()` 成功后) | 调 `preferenceStore.load()` 一次 | +| SPA 内部切换 tab(`hasGetUserInfo` 早退分支) | **不**重复拉取(避免高频请求) | +| 切到某 tab 时 | 读对应 `order.sort.`,填充 `currentSort` | + +> 关键:`load()` 挂在 `getInfo` 成功路径之后,天然覆盖「登录」与「整页刷新」两种场景,满足跨设备刷新同步。 + +### 7.3 跨设备刷新同步机制 + +```mermaid +sequenceDiagram + participant A as 设备A(订单页) + participant S as 服务端 + participant B as 设备B(另一台登录设备) + A->>S: user.preference.set(order.sort.pending, 新排序) + S-->>A: ok(updated_at) + Note over B: 用户在设备B 刷新页面 + B->>S: getInfo(认证) → user.preference.get + S-->>B: 返回最新配置 + B->>B: 填充 currentSort → 重新拉列表(带新排序) +``` + +- 刷新即最新(每次刷新重新 `getInfo` + `preference.get`)。 +- 可选增强(非本期必需):`user.preference.version` 轻量探测 + 前端定时轮询,实现"不刷新也近实时"。 + +### 7.4 写回与乐观锁冲突处理 + +- 排序变更(`@sort-change`)→ 更新本地 `currentSort` → 防抖 500ms → `preference.set({ scope, value, base_updated_at })`。 +- `base_updated_at` = 最近一次 `get` 返回的该 scope `updated_at`。 +- 收到 `40009` 冲突:弹窗「该配置已在其他设备更新」→ 用户选择「以本地为准覆盖」(用 `data.current_updated_at` 作为新 base 重试 set)或「放弃本次修改」(用服务端最新值回填本地)。 +- 写回失败(网络/后端故障):不回滚本地排序,保留 `dirty` 标记,下次 `@sort-change` 或进入页面时重试。 + +### 7.5 排序消费(各页接入模板) + +订单各子页(`reviewOrder/pendingOrder/pendingException/...`)、`waveOrder`、`basicManagement` 均已具备 `currentSort` → 列表 `sort` 参数链路,接入只需: + +1. 定义 `tabKey`(稳定标识,如 `'pending'`,勿用易变路由 path)。 +2. 挂载时:`currentSort = normalizeSort(preferenceStore.get('order.sort.' + tabKey)) ?? 默认`。 +3. `@sort-change`:更新 `currentSort` 后 `preferenceStore.set('order.sort.' + tabKey, { field, order })`。 +4. 默认值来源:各页既有默认(如 `created_at desc`),无配置时行为与现在一致。 + +> 建议抽通用 composable `usePageSortPreference(tabKey, { whitelist, defaultSort })`,收敛多页重复代码。 + +### 7.6 兜底与降级 + +| 场景 | 行为 | +|------|------| +| `get` 失败(超时/报错/后端故障) | **不抛出、不阻塞**登录与路由;优先级:localStorage 缓存(记 `lastLoadedAt`)→ 各页默认配置;`console.warn` 一次 | +| 响应结构异常(缺 data、scope 值非对象、value 非法) | 视为该 scope 无配置,走默认值,不让单条坏数据拖垮整包 | +| `set` 失败(40008/40010/网络) | 提示错误;不回滚本地,保留 `dirty` 待重试 | +| `set` 冲突(40009) | 见 §7.4 弹窗处理 | + +--- + +## 8. 正式方案:纯浏览器本地保存(不使用接口) + +> 本章为**正式方案(方案B)**:不新增任何后端接口,仅用浏览器存储保存配置。零后端依赖、每账号按 user_id 隔离、同设备跨刷新/会话生效;代价是**放弃跨设备同步**(§0 决策)。 + +### 8.1 定位与关键限制 + +- **零后端开发、零接口依赖**,纯前端实现。 +- **关键限制**:纯浏览器方案**无法实现「跨设备同步」**——数据不经过服务端,仅在同一设备、同一浏览器的跨刷新/跨会话内生效。若将来需要跨设备同步,再评估恢复接口方案(见 §0)。 + +### 8.2 实现 + +- **存储**:`localStorage`(key=`user_prefs_{userId}`,JSON 对象);配置体量增大或接近 5MB 上限时改用 IndexedDB。 +- **结构**:与接口方案保持一致(`{ [scope]: { value, updated_at } }`),便于将来无痛切换数据源。 +- **读写**:`userPreference` store 改为纯本地读写,无网络请求。 +- **每账号隔离**:key 含 user_id;登出不清除(保留账号配置),登录时按 user_id 读取。 +- **校验**:无服务端白名单,由前端自校验 scope / 结构 / 体积(仍建议单 scope ≤ 4KB)。 +- **写回**:直接写 localStorage;无网络开销,可即时写,也可防抖合并写入降低 IO。 + +### 8.3 与接口方案对比 + +| 能力 | 方案B(纯浏览器) | 方案A(接口) | +|------|------------------|--------------| +| 每账号绑定 | ✅ 同设备按 user_id 分 key | ✅ 服务端隔离 | +| 刷新页面保留 | ✅ | ✅ | +| **跨设备同步** | ❌ 无法 | ✅ | +| 登录后自动获取 | ✅ 读本地 | ✅ 接口拉取 | +| 后端开发量 | 零 | 需开发 get/set + 存储 | +| 多端并发 / 乐观锁 | 不涉及(单端) | 需要(base_updated_at) | +| 数据迁移 | 手动导出/导入 JSON | 天然同步 | +| 安全 / 容量 | 前端自管,约 5MB/域名 | 服务端校验 + 体积上限 | + +### 8.4 适用场景与建议 + +- 「跨设备同步」为硬需求 → **必须用接口方案**;纯浏览器方案仅作为其 **localStorage 兜底层**(即 §7.6 已有内容)。 +- 后端暂未排期、以单设备为主、可接受手动迁移 → 可先用方案B快速上线。 +- **推荐组合**:接口方案为正式形态;前端 store 将数据源抽象为「本地 / 服务端」两层,接口就绪前用本地层,就绪后切服务端层,**页面接入代码不变**(§7.5 的 `usePageSortPreference` 不感知数据源)。 + +### 8.5 从方案B平滑升级到方案A + +1. store 定义统一读写接口:`load()` / `get(scope)` / `set(scope, value)`(页面只调这些,不关心数据源)。 +2. 本地层:读写 localStorage;服务端层:调 `user.preference.get/set`。 +3. 接口就绪后,将 store 数据源实现替换为服务端层,同时保留 localStorage 作为缓存/降级(§7.6)。 +4. scope 与 value 结构两端保持一致,无需迁移数据格式。 + +--- + +## 9. 扩展性设计 + +**新增一个功能 = 新增一个 scope**,与既有数据、登录接口、前端 store 互不干扰: + +- 列配置 `order.columns.`:存 `{ visible, order }`,前端列表列渲染消费。 +- 筛选预设 `order.filter.preset.`:存 `{ name, where }`。 +- 其他模块 `report.*` / `storage.*` / `setting.*` 按同一命名规范注册即可。 +- 数据结构升级:每个 scope 可带 `schema_version`,前端按版本做 normalize 迁移。 + +因此可支撑 tab 数量增加与其他功能扩展,且**登录接口载荷恒定**(偏好不经过 getInfo)。 + +--- + +## 10. 里程碑 + +| 阶段 | 内容 | 验收 | +|------|------|------| +| M1 服务端 | `user_preferences` 存储 + `user.preference.get/set` + scope 白名单 + 体积/乐观锁 | 接口联调通过 | +| M2 前端基础 | `userPreference` store + 登录/刷新拉取 + localStorage 缓存 | 登录后控制台可见偏好已加载 | +| M3 排序落地 | 订单各 tab(+waveOrder/basicManagement)挂载读取 + `@sort-change` 防抖写回 | 双设备刷新互相同步通过 | +| M4 扩展 | 列配置/筛选预设等新 scope 接入 | 新功能走同一套机制上线 | + +--- + +## 11. 待确认事项(评审时与后端对齐) + +1. 服务端存储选型:关系表 vs Redis。 +2. `user.preference.get` 是否支持 `scope` 批量(`scope[]`),还是先只支持缺省全量。 +3. 多级排序 `secondary` 本期是否透传到列表接口(取决于 `order.list` 是否支持多字段 sort;不支持则本期只用主排序)。 +4. 是否本期就做 `user.preference.version` 轮询增强,还是先做"刷新即同步"。 +5. 错误码段(§4)是否与现有后端错误码体系合并/调整。 +6. `value = {}` 表示清空该 scope 的约定是否可接受(后端需实现删除语义)。 + diff --git a/docs/用户偏好配置-浏览器本地保存方案.md b/docs/用户偏好配置-浏览器本地保存方案.md new file mode 100644 index 00000000..3c165d55 --- /dev/null +++ b/docs/用户偏好配置-浏览器本地保存方案.md @@ -0,0 +1,193 @@ +# 用户偏好配置:每账号每页面自定义配置(浏览器本地保存方案) + +- 状态:**已决策(正式方案)** +- 日期:2026-09-01 +- 版本:v1.1 +- 说明:原「接口方案」已废弃(存档见 `docs/用户偏好配置-排序与跨设备同步设计.md`,不再使用)。**本文档为正式落地方案的唯一依据。** +- 本期实现:**订单管理多标签页自定义排序**(v1.0 曾规划「列排序」,已按需求更正为「标签页顺序」,见 §3.3/§3.4/§4.5)。 + +--- + +## 1. 背景与目标 + +订单管理 `order/orderManagement` 顶部多标签页(待审核订单、待处理订单、待处理异常订单、配送单等)的显示顺序固定,部分账号希望把常用页签(如「待处理订单」)排到更靠前的位置。需要: + +1. 可自定义**多标签页的显示顺序**(如把「待处理订单」拖到「待审核订单」前面)。 +2. 配置**绑定账号**(同设备内按 user_id 隔离保存)。 +3. **刷新 / 重新登录后自动应用**已保存配置。 + +> 取舍说明:本方案**不做「跨设备同步」**——数据保存在浏览器本地,不经过服务端,无法跨设备;仅同设备、同浏览器内跨刷新/跨会话生效。若将来需要跨设备同步,再评估是否引入接口方案。 + +方案设计为**模块无关**:除订单模块外,`order/waveOrder`、`setting/basicManagement` 等页面均可复用(按同一 key 规范注册即可)。 + +### 非目标(本期不做) + +- 不做跨设备同步。 +- 不做多用户/角色的差异化权限(配置仅按 user_id 隔离)。 +- 不做列表数据列排序(如按订单ID/发货单号排序列表)——本期仅做**标签页顺序**,列排序留待后续按需接入。 + +--- + +## 2. 方案总览(纯浏览器本地保存) + +- **存储**:`localStorage`,key = `user_prefs_{userId}`(JSON 对象);配置体量增大或接近 5MB 上限时改用 IndexedDB。 +- **每账号隔离**:key 含 user_id;登出**不清除**(保留账号配置),登录时按 user_id 读取。 +- **读写**:通过 `userPreference` store 统一读写,页面不直接操作 localStorage。 +- **即时生效**:标签顺序变更直接写本地,刷新/重登自动读取。 + +```mermaid +flowchart LR + A[标签排序弹窗拖拽] -->|保存| B[userPreference store] + B --> C[(localStorage
user_prefs_{userId})] + D[登录/整页刷新] --> E[store.load 读取本地] + E --> F[index.vue 按已存顺序重排 tabs] +``` + +--- + +## 3. 数据与命名规范 + +### 3.1 存储结构 + +```jsonc +// localStorage key: user_prefs_{userId} +{ + "order.tabs.order": { + "value": ["pendingOrder", "reviewOrder", "exceptionOrder", "outboundOrder", "entrustWarehouse", "deliveryOrder", "deliveryException", "archiveOrder"], + "updated_at": 1720000000000 // 毫秒时间戳,用于脏标记/冲突识别(预留) + } +} +``` + +- 预留 `updated_at` 是为了将来接入接口方案时无需迁移格式(§6)。 +- 单 scope `value` 仍建议 ≤ 4KB。 + +### 3.2 key 命名规范(scope) + +统一格式:`<模块>.<能力>.<页面标识>`,全小写,`.` 分隔。 + +### 3.3 本期 scope 表(标签排序) + +| scope | 含义 | +|-------|------| +| `order.tabs.order` | 订单管理多标签页显示顺序 | +| `order.wave.tabs.order` | 波次管理(waveOrder)标签顺序 | +| `stock.tabs.order` | 商品管理(stock/stockManagement)标签顺序 | +| `setting.basicManagement.tabs.order` | 基础设置(basicManagement/newview)标签顺序 | +| `order.sort.` | 各 tab 列表列排序(预留,v1.0 曾规划) | + +预留(后续功能直接注册新 key): + +| scope | 含义 | +|-------|------| +| `order.columns.` | 列显隐/顺序 | +| `order.filter.preset.` | 筛选条件预设 | +| `order.table.` | pageSize / 表格密度 | + +### 3.4 标签顺序 value 结构(`order.tabs.order`) + +```jsonc +// value = tab.name 数组,数组顺序即标签页显示顺序 +{ + "order": ["pendingOrder", "reviewOrder", "exceptionOrder", "outboundOrder", "entrustWarehouse", "deliveryOrder", "deliveryException", "archiveOrder"] +} +``` + +- 消费时按数组顺序重排 `index.vue` 的 `tabs`(`applyTabOrder`);缺失/非法 tab 名自动剔除,新增 tab 自动补在末尾。 +- 未配置时使用默认顺序(`ORDER_TAB_LIST` 定义的顺序)。 + +--- + +## 4. 前端实现 + +### 4.1 `userPreference` store + +新建 `src/stores/modules/userPreference.ts`(Pinia): + +| 方法 | 行为 | +|------|------| +| `load()` | 按当前 user_id 从 localStorage 读取全部偏好 → 写内存;无缓存则置空 | +| `get(scope)` | 内存 → 默认值,逐级兜底 | +| `set(scope, value)` | 本地立即生效(写内存 + localStorage) | +| `reset(scope)` | 删除该 scope(`localStorage` 中移除该 key) | +| `isLoaded` / `lastLoadedAt` | 会话内加载状态标记 | + +- `load()` 在 `src/permission.ts` 路由守卫 `userStore.getInfo()` 成功后调用一次(覆盖登录 + 整页刷新);SPA 内部切 tab 不重复调用。 +- `set()` 写回本地即时生效,无需网络;可防抖合并(500ms)减少 IO。 + +### 4.2 加载时机 + +| 触发点 | 行为 | +|--------|------| +| 登录成功 / 整页刷新(`getInfo` 成功后) | `preferenceStore.load()` 一次 | +| SPA 内部切换 tab | 不重复 load | +| orderManagement 挂载时 | 读 `order.tabs.order` 重排 tabs(`applySavedTabOrder`) | + +### 4.3 写回 + +- 标签排序弹窗点「保存」→ `preferenceStore.set('order.tabs.order', tab.name 数组)` → 本地即时生效 + 持久化;父级按新顺序重排 tabs。 + +### 4.4 兜底与边界 + +| 场景 | 行为 | +|------|------| +| 无缓存 / 首次使用 | 用各页默认排序,不报错 | +| localStorage 不可用/满(抛异常) | try/catch 兜底,降级为内存态,不阻塞页面 | +| 结构异常(value 非对象等) | 视为该 scope 无配置,走默认值 | +| 登出 | 不清除 localStorage(保留账号配置),重新登录按 user_id 读取 | + +### 4.5 标签排序接入(本期已实现) + +已接入页面(弹窗为**共享组件** `src/components/SortSettingDialog.vue`,props 传 `tabs`(默认顺序)+ `scope`(存储 key),各页只做入口 + 应用顺序): + +1. **订单管理** `order/orderManagement`:配置 `ORDER_TAB_LIST`(`config/order-common-config.ts`),scope=`order.tabs.order`。 +2. **波次管理** `order/waveOrder`:inline tabs(5 个),scope=`order.wave.tabs.order`。 +3. **商品管理** `stock/stockManagement`:inline tabs(2 个),scope=`stock.tabs.order`。 +4. **基础设置** `setting/basicManagement`(newview):`tabPages` 配置驱动,scope=`setting.basicManagement.tabs.order`;`TabArea.vue` 增加 `headerLeftInset` 给入口按钮让位。 + +每页接入模式: + +1. 入口:tab 区域左侧「标签排序」按钮(`.sort-entry-btn`)→ 打开 `SortSettingDialog`。 +2. 弹窗:`VueDraggable` 拖拽重排默认 tab 列表,点「保存」→ `preferenceStore.set(scope, names)` + `emit('saved', names)`。 +3. `index.vue`:`handleSortSaved(order)` → `applyTabOrder(order)` 重排 tabs;挂载时 `applySavedTabOrder()` 读取已存顺序。 +4. 无配置时保持默认顺序;非法/缺失项自动处理(缺失 tab 补末尾)。 + +--- + +## 5. 扩展性 + +**新增一个功能 = 新增一个 scope key**,store 与页面接入模板不变: + +- 列配置 `order.columns.`:存 `{ visible, order }`。 +- 筛选预设 `order.filter.preset.`:存 `{ name, where }`。 +- 其他模块 `report.*` / `storage.*` / `setting.*` 按同一命名规范注册。 + +数据结构升级:每个 scope 可带 `schema_version`,前端按版本做 normalize 迁移。 + +--- + +## 6. 升级路径(将来如需跨设备同步) + +1. store 保持统一读写接口 `load()/get(scope)/set(scope,value)/reset(scope)`,页面不感知数据源。 +2. 增加「服务端数据源」实现(`user.preference.get/set`),与本地层并存。 +3. 接口就绪后切换数据源,localStorage 降级为缓存/兜底。 +4. 数据结构(§3.1)两端保持一致,无需迁移格式。 + +--- + +## 7. 里程碑 + +| 阶段 | 内容 | 验收 | +|------|------|------| +| M1 store | `userPreference` store + 登录/刷新 load + localStorage 读写 | 登录后控制台可见偏好已加载 | +| M2 标签排序落地 | orderManagement 标签排序弹窗 + 保存 + 挂载恢复 | 刷新/重登后标签顺序保持 | +| M2.5 扩展页 | waveOrder / stockManagement / basicManagement 接入共享弹窗 | 4 页均可拖拽排序并持久化 | +| M3 扩展 | 列配置/筛选预设等新 scope 接入 | 新功能走同一套机制上线 | + +--- + +## 8. 遗留 / 待确认 + +1. 是否把标签排序扩展到其他多标签模块(如 `setting/encoding`、`express/waybill` 等,同机制注册新 scope)。 +2. 列表列排序(`order.sort.`)是否按需接入(本期仅做标签顺序)。 +3. 跨设备同步暂不做;若业务上出现强需求,再走 §6 升级路径。 diff --git a/src/api/afterSale/index.ts b/src/api/aftersale/index.ts similarity index 100% rename from src/api/afterSale/index.ts rename to src/api/aftersale/index.ts diff --git a/src/api/order.deliveryOrder/orderdeliveryOrder.ts b/src/api/order.deliveryorder/orderdeliveryOrder.ts similarity index 100% rename from src/api/order.deliveryOrder/orderdeliveryOrder.ts rename to src/api/order.deliveryorder/orderdeliveryOrder.ts diff --git a/src/api/order.outboundOrder/orderoutboundOrder.ts b/src/api/order.outboundorder/orderoutboundOrder.ts similarity index 100% rename from src/api/order.outboundOrder/orderoutboundOrder.ts rename to src/api/order.outboundorder/orderoutboundOrder.ts diff --git a/src/api/order.pendingOrder/orderpendingOrder.ts b/src/api/order.pendingorder/orderpendingOrder.ts similarity index 100% rename from src/api/order.pendingOrder/orderpendingOrder.ts rename to src/api/order.pendingorder/orderpendingOrder.ts diff --git a/src/api/order.reviewOrder/orderreviewOrder.ts b/src/api/order.revieworder/orderreviewOrder.ts similarity index 100% rename from src/api/order.reviewOrder/orderreviewOrder.ts rename to src/api/order.revieworder/orderreviewOrder.ts diff --git a/src/api/returnReceived/index.ts b/src/api/returnreceived/index.ts similarity index 50% rename from src/api/returnReceived/index.ts rename to src/api/returnreceived/index.ts index e2e3935e..652384c0 100644 --- a/src/api/returnReceived/index.ts +++ b/src/api/returnreceived/index.ts @@ -119,11 +119,114 @@ export function returnReceivedDelete(data: ReturnReceivedDeleteParams): Promise< } as any) } +// ============ returnReceived.export ============ + +/** returnReceived.export 请求参数(where/sort 语义与 returnReceived.list 一致) */ +export type ReturnReceivedExportParams = { + /** 查询条件,语义与 returnReceived.list 的 where 一致;禁止传 warehouse_id/warehouseId(服务端注入) */ + where?: Record + /** 排序参数,语义与 returnReceived.list 的 sort 一致 */ + sort?: { + sortField?: string + sortOrder?: string + } +} + +/** returnReceived.export 响应(提交成功即返回任务受理信息) */ +export type ReturnReceivedExportResponse = { + /** 任务 ID(后端生成,格式 return_received_export_{warehouseId}_{timestamp}_{random}) */ + task_id: string + /** 任务状态:submitted/running/success/failed/not_found(提交成功时为 submitted) */ + status: string + /** 当前进度百分比(0-100),提交时返回 0 */ + progress: number + /** 当前已处理记录数(登记记录条数) */ + current_count: number + /** 总记录数 */ + total_count: number + /** 任务提示信息 */ + message: string + /** 任务执行结果(提交时为 null;完成后为上传信息对象) */ + result: Record | null + /** 失败时的错误信息 */ + error: string + /** 任务更新时间(Unix 毫秒时间戳) */ + update_time: number + code?: number +} + +/** returnReceived.export:提交退回收到登记导出任务(异步,返回 task_id) */ +export function returnReceivedExport(data: ReturnReceivedExportParams = {}): Promise { + return request({ + url: '/system', + method: 'post', + params: { + method: 'returnReceived.export', + v, + timestamp: new Date().getTime() + }, + data, + isSystemApi: true + } as any) +} + +// ============ returnReceived.exportTaskProgress ============ + +/** returnReceived.exportTaskProgress 请求参数 */ +export type ReturnReceivedExportTaskProgressParams = { + /** 任务 ID(下划线写法,兼容) */ + task_id?: string + /** 任务 ID(驼峰写法,兼容) */ + taskId?: string +} + +/** returnReceived.exportTaskProgress 响应 */ +export type ReturnReceivedExportTaskProgressResponse = { + /** 任务 ID(缺失时为空字符串,status=not_found) */ + task_id: string + /** 任务状态:submitted/running/success/failed/not_found */ + status: string + /** 进度百分比(0-100) */ + progress: number + /** 当前已处理记录数(登记记录条数) */ + current_count: number + /** 总记录数 */ + total_count: number + /** 任务提示信息 */ + message: string + /** 任务执行结果对象(完成后含 filename/url/fileKey/cdnUrl/cosUrl 等) */ + result: Record | null + /** 失败时的错误信息 */ + error: string + /** 任务完成后下载链接;未完成或不存在时为空字符串 */ + download_url: string + /** 最近一次状态更新时间(Unix 毫秒时间戳) */ + update_time: number + code?: number +} + +/** returnReceived.exportTaskProgress:按 task_id 查询退回收到导出任务进度 */ +export function returnReceivedExportTaskProgress(data: ReturnReceivedExportTaskProgressParams): Promise { + return request({ + url: '/system', + method: 'post', + params: { + method: 'returnReceived.exportTaskProgress', + v, + timestamp: new Date().getTime() + }, + data, + isSystemApi: true + } as any) +} + // ============ 模块导出 ============ export const returnReceivedModule = { create: returnReceivedCreate, list: returnReceivedList, detail: returnReceivedDetail, - delete: returnReceivedDelete + delete: returnReceivedDelete, + export: returnReceivedExport, + exportTaskProgress: returnReceivedExportTaskProgress } diff --git a/src/api/stock/stock.ts b/src/api/stock/stock.ts index 7ad10184..b9523ce5 100644 --- a/src/api/stock/stock.ts +++ b/src/api/stock/stock.ts @@ -435,10 +435,69 @@ export function backData(data: any) { } as any) } +/** stock.warehouse.getStockDetail 库存明细行(storageList 元素) */ +export type StockWarehouseStorageItem = { + /** 明细ID */ + id?: number + /** 库位ID */ + space_id?: number + /** 库位名称 */ + space_name?: string + /** 批次号(group_by_batch=false 按库位合并时为 null) */ + batch_no?: string | null + /** 生产日期(按库位合并时为 null) */ + production_date?: string | null + /** 到期日期(按库位合并时为 null) */ + expiry_date?: string | null + /** 入库时间(按库位合并时为 null) */ + inbound_time?: string | null + /** 入库单号(按库位合并时为 null) */ + inbound_order_no?: string | null + /** 供应商批次号(按库位合并时为 null) */ + supplier_batch_no?: string | null + /** 数量 */ + quantity?: number + /** 锁定数量 */ + locked_quantity?: number + /** 拦截锁定数量(按库位合并明细,默认 0) */ + intercept_locked_quantity?: number + /** 可用数量 = quantity - locked_quantity - intercept_locked_quantity */ + available_quantity?: number + [key: string]: any +} + +/** stock.warehouse.getStockDetail 响应 */ +export type StockWarehouseDetailResponse = { + code?: number + message?: string + /** 响应数据 */ + data?: { + /** 商品概要,包含 id、item_code、item_name、sku_property、stock_unit、quantity、locked_quantity 等 */ + stockItem?: { + id?: number + item_code?: string + item_name?: string + sku_property?: string + stock_unit?: string + quantity?: number + locked_quantity?: number + [key: string]: any + } + /** 库存明细数组;group_by_batch=true 返回 wms_storage 明细,false 按库位合并 */ + storageList?: StockWarehouseStorageItem[] + /** 分页信息 */ + pagination?: { + page: number + pageSize: number + total: number + } + } +} + export function getStockDetail( stock_id: number, options?: { page?: number; pageSize?: number; group_by_batch?: boolean } -) { +): Promise { const data: Record = { stock_id } if (options?.group_by_batch !== undefined) { data.group_by_batch = options.group_by_batch diff --git a/src/api/storeWarehouse.store/storeWarehouse.ts b/src/api/storewarehouse.store/storeWarehouse.ts similarity index 100% rename from src/api/storeWarehouse.store/storeWarehouse.ts rename to src/api/storewarehouse.store/storeWarehouse.ts diff --git a/src/components/ScanBox/index.vue b/src/components/ScanBox/index.vue index 6717f358..ec5a8d79 100644 --- a/src/components/ScanBox/index.vue +++ b/src/components/ScanBox/index.vue @@ -523,6 +523,7 @@ 无需填值