diff --git a/changelogs-v2/2026-09/28_frontend_房务订单列表改常规与团期两页签-前端优化-管理后台.md b/changelogs-v2/2026-09/28_frontend_房务订单列表改常规与团期两页签-前端优化-管理后台.md new file mode 100644 index 00000000..4041d71c --- /dev/null +++ b/changelogs-v2/2026-09/28_frontend_房务订单列表改常规与团期两页签-前端优化-管理后台.md @@ -0,0 +1,194 @@ +--- +schema: "hl-changelog/v2" +ticket: "frontend" +title: "房务订单列表产品维度改「常规订单 / 团期订单」两页签(取代 09-27 交接件的三页签口径)" +consumer: "admin" +author: "wx(GIT)" +change_type: "前端优化" +backend_status: "not_required" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "本条取代 2026-09-27 交接件《房务订单列表「类型」改页签 + 「小蒙马」改「团期」文案 + 菜单改名后页面名同步》第二章的页签集合定义:页签数由三个(核心/定制/团期)改为两个(常规订单/团期订单),该章「去掉全部、默认 CORE」作废。该章其余要点(toolbar 左侧、@update:value 绑定、端点不变、?groupBatchId= 自动切团期、注释同步)全部继续有效。后端零改动:两个页签直接对应两个已上线的现成端点。" +updated_at: "2026-09-28" +base: "dev-v3" +--- + +# 前端优化:房务订单列表产品维度改「常规订单 / 团期订单」两页签 + +## ⚠️ 关键变化 + +**这是对 2026-09-27 交接件的口径修改,不是一个新需求。** + +2026-09-27 发出的 `27_frontend_房务订单列表类型页签改造-小蒙马改团期全局文案-菜单改名同步-前端优化-管理后台.md` +(下称「09-27 交接件」,`frontend_status: pending`,尚未实施)第二章要求把房务订单列表的「类型」由下拉**改回页签**, +并定为**三个**页签「核心 / 定制 / 团期」、**去掉「全部」、默认 `CORE`**。 + +wx 2026-09-28 把口径改成**两个**页签: + +| | 09-27 交接件第二章 | **本条(最新口径)** | +|---|---|---| +| 页签数 | 3 个 | **2 个** | +| 页签 | 核心 / 定制 / 团期 | **常规订单 / 团期订单** | +| 「全部」 | 去掉 | **保留,改名为「常规订单」** | +| `orderTab` 初值 | 改成 `ref('CORE')` | **保持 `ref('all')` 不动** | + +wx 原话两句:「房务也变成 tab 形式 也是 普通订单 团期订单 定制+核心就是普通订单」(2026-09-27 需求沟通)、 +「也改成常规订单 团期订单」(2026-09-28,最终文案取这句,**用「常规订单」不用「普通订单」**)。 + +**09-27 交接件第二章的其余要点全部继续有效**(见下文「四、09-27 交接件中继续有效的要点」), +只有页签集合与初值这两处被本条取代。第三章(「小蒙马」→「团期」文案替换)、 +第四章(菜单改名后页面名同步)**完全不受影响,照原样执行**。 + +--- + +## 一、背景 + +房务订单列表的产品维度在最近两天内被反复改过方向,这里按时间把事实列清,避免再次返工: + +1. 该位置原本是**页签**; +2. **2026-09-27 当天**被改成 `n-select` 下拉(`index.vue:34` 的注释自述「2026-09-27 由页签改为搜索条件下拉」); +3. 同日后端发出 09-27 交接件,按 wx 要求**改回页签**,定为三个(核心/定制/团期)——mmg 尚未实施; +4. **2026-09-28** wx 把口径定为两个页签(常规订单 / 团期订单),即本条。 + +因为第 3 步还没动工,所以第 4 步不是二次返工,而是**在同一次改造里换一个页签集合**—— +直接按本条实施即可,不需要先做成三个再改成两个。 + +--- + +## 二、现状(ref `gitea/v2.1` origin/v2.1,逐行核过) + +**文件**:`src/views/housekeeper/orders/index.vue` + +- **搜索区** `:34-45`:「类型」为 `n-select` 下拉,宽 120px,`:value="orderTab"` + `@update:value="onOrderTabChange"` +- **状态变量** `:365`:`const orderTab = ref('all')` +- **选项定义** `:366-372`: + ```js + const orderTabOptions = [ + { value: 'all', label: '全部' }, + { value: 'CORE', label: '核心' }, + { value: 'CUSTOM', label: '定制' }, + { value: 'GROUP', label: '团期' }, + ] + ``` +- **团期判定** `:388`:`const isGroupTab = computed(() => orderTab.value === 'GROUP')` +- **端点切换** `:466`:`const fetcher = isGroupTab.value ? getHouseAllocationGroupBatches : getHouseAllocationHouseholds` +- **参数下推** `:457`:`p.productType = orderTab.value`,同行注释原文「GROUP 已被团期端点接管,户级端点拒收」 +- **两套状态桶** `:391-413`:户级 7 个桶、团期 3 个桶,两套桶不同 +- **两个表格组件**:同目录 `HouseholdTable.vue`(户级)、`GroupBatchTable.vue`(整团一行),**已经是分开的两个组件** + +--- + +## 三、改动要点 + +### 1. 页签集合:两个 + +```vue + + 常规订单 + 团期订单 + +``` + +- **`orderTab` 初值保持 `ref('all')`**(`:365` 不动)。09-27 交接件说的「改成 `ref('CORE')`」作废—— + 「全部」这个取值不是被删掉,而是被改名成「常规订单」。 +- `orderTabOptions`(`:366-372`)删除,改为两个 `n-tab`。 +- `:456` 的 `orderTab.value !== 'all'` 这类判断**保持原语义**(`all` 仍是合法且默认的取值), + 09-27 交接件里「按『默认 CORE、恒有值』改」的那句同样作废。 +- 同文件的 `scope`、`statusTab` 也有 `'all'` 取值,与本次无关,不要动。 + +### 2. 两个页签的取数(后端零改动,两个端点都已上线) + +| 页签 | `orderTab` | 端点 | `productType` 传值 | 一行代表 | +|---|---|---|---|---| +| **常规订单** | `all` | `GET /v3/admin/order/house-allocation/households` | **不传**(或空串) | 一户 | +| **团期订单** | `GROUP` | `GET /v3/admin/order/house-allocation/group-batches` | 不适用 | 一个团(整团一行) | + +- 「常规订单」= **核心 + 定制合并**,依据 wx 原话「定制+核心就是普通订单」。 + 不传 `productType` 时户级端点不下推该条件,返回的就是核心 + 定制。 +- 户级端点**结构性地不接受团期**:其入参 `productType` 声明为 + `@Pattern(regexp = "(CORE|CUSTOM)?")`(后端 `HouseAllocationHouseholdPageReqVO.java:41`, + 错误提示原文「productType 只能是 CORE 或 CUSTOM」),传 `GROUP` 会被参数校验直接拒掉。 + 所以团期**必须**走 `group-batches`,不能试图给 `households` 传 `GROUP`。 +- 现有的 `:388` `isGroupTab` 与 `:466` 的 `fetcher` 三元切换逻辑**原样保留即可**,两个页签正好对应它已有的两个分支。 +- `:457` 的 `p.productType = orderTab.value` 需要改:`all` 时不要把字符串 `'all'` 传给后端(它不是合法取值), + 按现有写法确认 `all` 分支是否已被 `:456` 的 `!== 'all'` 判断挡掉;若未挡掉,改成 `all` 时不带该参数。 + +### 3. 核心 / 定制细分怎么处理 + +wx **没有**要求在「常规订单」里保留核心/定制的细分。默认按不细分实施。 + +如果页面上仍然需要区分,**走搜索区的下拉,不要做成页签**——后端 `households` 端点照旧接受 +`productType=CORE` 与 `productType=CUSTOM`,契约不变,随时可加。 + +### 4. 🔴 切页签必须重置状态桶(两套桶不是同一套) + +- 常规订单(户级)是 **7 个状态桶**,团期订单是 **3 个状态桶**(`index.vue:391-413`),两套桶的取值与数量都不同。 +- 切换页签时必须重置 `statusTab`,否则会把上一个页签的状态值带到新页签上,查出空列表或报参数错。 +- 现有 `onOrderTabChange` 已经有这段重置逻辑,**改造时不要丢掉它**——这也是绑定必须用 `@update:value` + 而不能用 `v-model:value` 的原因(见下条)。 +- ⚠️ 这一点与**派单看板**的两个页签**相反**:派单看板的「普通订单 / 团期订单」两个页签**共用同一套派车状态桶**, + 切页签不需要重置状态。两个页面看起来是同一种改造,这里的行为不一样,别互相照抄。 + +--- + +## 四、09-27 交接件中继续有效的要点 + +以下来自 09-27 交接件第二章「改动要点」,**本条不推翻,照原样执行**: + +1. **样式与位置**:页签置于 ProTable toolbar 左侧,参考 `src/views/finance/settlement/index.vue:58-66`, + 结构 ``,页签用 ``, + 样式 `.product-tabs { width: 280px; }`(两个页签可按实际宽度调小)。 +2. **绑定方式**:`:value="orderTab"` + `@update:value="onOrderTabChange"`。 + **不能照抄核单列表的 `v-model:value`**,否则切换会绕过 `onOrderTabChange`,状态桶不重置。 +3. **通知链接**:`?groupBatchId=` 仍自动切到「团期订单」页签并精确定位;`?orderId=` 行为不变。 +4. **注释同步**:`:34-35`、`:297-308`、`:366` 的注释里关于「下拉 / 全部」的描述同步改成「页签 / 常规订单·团期订单」。 + +第三章(「小蒙马」→「团期」全局文案替换,5 个文件 8 处)与第四章(菜单改名后页面名同步)**与本条无关,照原样执行**。 + +--- + +## 五、验证检查清单 + +- [ ] 页面默认落在「常规订单」页签,列表走 `households` 且**不带** `productType` 参数(Network 里确认) +- [ ] 「常规订单」列表里同时能看到核心与定制的订单 + (2026-09-28 测试环境读数为核心 104 条、定制 1 条,仅供参考——这是夹具的当时状态、不是契约; + 定制只有 1 条,若它被别的验收清掉,改用「不带 productType 的结果条数 ≥ 带 CORE 的条数」来判) +- [ ] 切到「团期订单」,请求改为 `group-batches`,一个团一行,用 `GroupBatchTable.vue` 渲染 +- [ ] 切换页签时状态桶随之切换(7 桶 ↔ 3 桶),且状态筛选被重置,不带上一个页签的状态值 +- [ ] 任何情况下都没有把 `productType=all` 或 `productType=GROUP` 发给 `households` + (前者不是合法取值,后者会被 `@Pattern` 拒绝并返回参数校验错误) +- [ ] 带 `?groupBatchId=xxx` 打开页面,自动切到「团期订单」并定位到该团 +- [ ] 页签绑定用的是 `@update:value`,不是 `v-model:value` + +--- + +## 六、不影响范围 + +- **后端零改动**:两个端点都已上线,参数、响应、错误码一律不变。本条不需要等任何后端部署。 +- `HouseholdTable.vue` / `GroupBatchTable.vue` 两个表格组件的内部实现不变,本条只改外层的页签与取数分支选择。 +- 房务的其他筛选维度(`scope`、`statusTab`、酒店、日期等)不变。 +- 小程序端不涉及。 + +--- + +## 七、相关工单与文档 + +- 本条对应 wx 2026-09-27 / 2026-09-28 两次口径确认,属于 `wx/HL#8464`(派单看板与房务页签化)的前端部分; + #8464 的后端改动(派单看板加「普通/团期」过滤、删除「团期配车」菜单)另有交接件,与本条互不依赖。 +- 被本条部分取代:`changelogs-v2/2026-09/27_frontend_房务订单列表类型页签改造-小蒙马改团期全局文案-菜单改名同步-前端优化-管理后台.md` + (仅第二章的页签集合与初值两处;其余章节与要点继续有效) +- 后端端点入参约束出处:`hl-order-service-v3/src/main/java/com/hulalv/house/controller/admin/vo/allocation/HouseAllocationHouseholdPageReqVO.java:41` + +## 联系人 + +后端:wx(管理者会话)|前端:mmg