weekly-2026-W44

周报 · 2026年第44周(10月26日-11月01日)

姓名: 邓星星(dengxingxing) 项目: hoolihome-project 分支: production 提交数: 29 个(功能/修复 27 个 + 合并 4 个分支,含合并带入提交)


📋 本周工作汇总

按日期统计

日期 提交数 主要内容
10/26 周一 6 租期规则与客户端展示体系重构(5 个提交,含旧版 App 兼容)+ 钱包提现规则文案优化
10/27 周二 4 订单查询批量中文/拼音姓名输入、旧接口废弃标注、房屋佣金分页参数兼容、生产容器内存配置
10/28 周三 10 企微拆分分配与收款单关联(核心)、拆分类型筛选、交易流水号搜索、到账登记实收合计、可开票订单筛选、邮件模版类型
10/29 周四 7 到账流水字段放宽校验、到账账单关键字搜索、订单集成企微群组、实拍素材关键词搜索、租期规则映射同步、房屋佣金状态修正
10/30 周五 2 企业/合作方业务量统计接口、到账流水录入人为空兼容
10/31 周六 0 —
11/01 周日 0 —

按模块统计

模块 提交数
财务/收款/到账开票 11
房源/租期规则 6
CRM/查询/统计 6
搜索/素材 2
佣金/房屋政策 1
邮件模版 1
钱包 1
系统同步/基础设施 1

合并分支

合并提交 分支 带入提交数
3b025c30cb3f dev_v2_filter 5(租期规则与旧版 App 兼容)
7bf7225291b5 dev_v2_inovice 2(到账登记实收合计、可开票订单筛选)
7338e028652d dev_v2_xxskd 6(企微拆分分配、收款单重构、拆分筛选与测试)
930fc86162f3 hotfix/wallet-withdrawal-rules-20261026 1(钱包提现规则文案)

🛠 详细工作内容

一、租期规则与客户端展示体系重构(10/26)

1. feat(client-lease): 改进客户端租期展示和序列化逻辑

  • 提交: 45e0b417ca0b(2026-10-26)
  • 涉及文件(6 个,+298/-26): ClientRoomController.java、ClientRoomRentAttrVo.java(client + house 两处同名类)、ClientLeaseSupport.java、RoomRentRules.java、ClientLeaseDisplayTest.java(新增 155 行)、hoollihome-house-api/build.gradle
  • 改动说明:
  • 新增 RentAttrDisplay 包装类,内部用 @JSONField(unwrapped = true) 平铺原有的 Map<String,Object> 字段,保证对客户端的 JSON 结构完全不变;同时把 totalPrice(BigDecimal)与 rentDurationDescription(String)提为独立字段并配置 SerializerFeature.WriteMapNullValue,解决"值为 null 时整个 key 消失"导致前端拿到 undefined 的问题。
  • 构造器中统一调用 RoomRentRules.totalPrice(attr) 计算总价并透出时长说明,控制器不再散落 set 逻辑。
  • 在 gradle 中新增 testClientLeaseDisplay 任务,走 JUnit Platform 且固定 user.timezone=Asia/Shanghai,该测试不连接数据库或外部服务,只验证真实响应序列化结果。
  • 代码片段: java @Getter public static class RentAttrDisplay { @JSONField(unwrapped = true) private final Map<String, Object> fields; @JSONField(serialzeFeatures = SerializerFeature.WriteMapNullValue) private final BigDecimal totalPrice; @JSONField(serialzeFeatures = SerializerFeature.WriteMapNullValue) private final String rentDurationDescription; }

2. refactor(lease): 简化并优化租期默认值计算与接口数据结构

  • 提交: 347974a19b0b(2026-10-26)
  • 涉及文件(6 个,+221/-125): ClientRoomController.java、ClientRoomRentAttrVo.java(两处)、ClientLeaseSupport.java、ClientLeaseSupportTest.java、ClientLeaseDisplayTest.java
  • 改动说明:
  • 客户端 VO 从"输出十几种租期规则编码字段 + 数值字段"改为"只输出服务端解析好的两个默认日期"。删掉的字段包括 rentNumType、leasePlanType、rentEndMode、rentDurationMode、rentExtraDays、rentNumMin/Max、rentTimeUnit、leasePlanTypeText 等。
  • rentTimeStart / rentTimeEnd 使用 WriteMapNullValue 保证 null 也下发(无法确定默认日期时明确返回 null,而不是缺字段),语义注释写明"由 API 计算,无法确定时为 null"。
  • 控制器中原先逐字段 attrVo.set(...) 的十几次调用收敛为构造 VO,一次性计算起止日期。

3. fix(client-lease): 优化租期截止时间显示和计算逻辑

  • 提交: 0149cfa763c7(2026-10-26)
  • 涉及文件(4 个,+36/-16): ClientLeaseSupport.java、ClientRoomRentAttrVo.java、两个测试类
  • 改动说明:
  • 计算优先级重写为:固定结束日优先 → 其次按固定/最短/区间最小时长推算候选 → 可协商起始或时长时回退到"最晚可结束日"。 java Long latest = Objects.equals(endMode, 2) ? positiveDate(attr.getRentTimeEnd()) : null; if (start == null) return latest; if (!Objects.equals(endMode, 2) && !Objects.equals(endMode, 3) && !Objects.equals(endMode, 4)) return null; else return Objects.equals(mode, 4) ? latest : null;
  • 展示文案去掉"(推算)"/" (estimated)"后缀——推算与否不该由后端在日期字符串里塞中文括号,而是通过"最晚2027/08/31"这类前缀表达可协商语义,避免中英文两套后缀逻辑。
  • 测试用例从"断言含推算后缀"改为"断言纯日期",并新增 lease6933486UsesLatestEndForPrefillAndKeepsLatestDisplayText 覆盖"可协商起始 + 固定最晚结束日"的组合场景(同时校验预填值与展示文案一致、totalPrice 为 null 时仍输出)。

4. refactor(compatibility): 兼容旧版 App 租期字段的支持与校验

  • 提交: 1570ef47b0a6(2026-10-26)
  • 涉及文件(5 个,+286/-9): ClientRoomController.java、ClientRoomRentAttrVo.java(两处)、测试类
  • 改动说明:
  • 上一提交删掉的规则字段以 @Deprecated 形式加回 VO:leasePlanType、rentStartMode、rentNum、rentStartFrom、rentStartTo、rentTimeUnit、validation(固定 0),每个字段 Javadoc 统一标注"已过期,仅兼容旧版 App;新客户端直接使用展示文案和默认日期,旧版退役后删除"。
  • 用 WriteMapNullValue 保证这些旧字段即便为 null 也照常下发,旧版 App 的日期计算逻辑不会因为字段缺失而报错。
  • 这是典型的"新旧客户端平滑过渡"策略:规则解释权收归服务端,但旧 App 的自计算所需数据继续供应,直至旧版退役。

5. feat(room-rent): 新增租期时长说明字段及相关支持

  • 提交: dbe249e66fd7(2026-10-26)
  • 涉及文件(13 个,+111/-8): room_rent_duration_description.sql(新增)、RoomRentAttr.java、RoomRentAttrParam.java、RoomRentAttrBizService.java、RoomController.java、RoomService.java、ClientRoomController.java、两个 VO、RoomRentRulesPersistenceTest.java、RoomRentRulesV4Test.java
  • 改动说明:
  • room_rent_attr 表新增 rent_duration_description TEXT NULL COMMENT '租期时长说明,非必填纯文本,可清空',DDL 独立成脚本且脚本开头先 SELECT information_schema.COLUMNS 核对目标库与字段存在性,明确"不回填历史内容、不修改其他租期字段"。
  • Param 层用 rentDurationDescriptionUpdated 标志位(@JsonIgnore + fastjson serialize=false)区分三种语义:未提交 = 保持原值;显式传 null = 清空;空字符串 = 原样保存。配套 setRentDurationDescription()(置位)与 preserveRentDurationDescription()(未置位时回填旧值)两个方法。
  • 旧版房型接口的覆盖保护同步扩展:原先只判断"存在新租期规则或总价",现在也把"存在时长说明"纳入,提示改用房型 V2 接口编辑,避免旧接口把新字段覆盖掉。
  • RoomRentAttrParam 的整体提交判断(hasRules || totalPrice != null)也加入 rentDurationDescription != null。

6. fix(wallet): 优化钱包提现规则描述

  • 提交: 7a9cc7a2f9a6(2026-10-26)
  • 涉及文件(1 个,+8/-4): WalletController.java
  • 改动说明:
  • 提现规则文案从 4 条扩写为 8 条,补齐用户最容易产生争议与客服咨询成本的四项:可提现额度以提现页展示为准且不设最低金额、单笔不得超过可提现额度;提现窗口每月 1 日至 10 日开放;同一时间仅可发起一笔提现、前一笔打款完成后才可再次发起;审核通过后财务统一打款预计次月中到账、遇节假日顺延。
  • 原有"返现/推荐奖励发放时间、汇率折算、代扣个税、最终解释权"四条保留并细化表述。

二、收款单与企微拆分分配体系(10/28)

7. feat(fee): 支持企微拆分分配及收款单申请关联回显

  • 提交: 94fa4ecfd47c(2026-10-28)
  • 涉及文件(36 个,+1155/-492): CrmFeeOrderService.java(+211/-)、FeeOrderController.java、HomeFeeOrderAllocation.java(新增实体)、HomeFeeOrderAllocationMapper.java(新增)、OrderCommissionService.java、QywxReceiptAllocation.java(新增)、QywxReceiptReconcileService.java(+150/-)、HomeFeeOrderServiceImpl.java、多个 VO/Mapper、两个 SQL 脚本,以及 5 个测试文件(约 600 行)
  • 改动说明:
  • 核心是引入 home_fee_order_allocation 关联表,把"一张收款单 ↔ 多个企微申请单"的拆分关系从收款单上的冗余字段迁移到独立关联表(fee_order_id / form_id / amount / refund_amount / create_user_id / create_time)。
  • 新增 QywxReceiptAllocation 负责拆分关系的装配,新增 QywxReceiptReconcileService 负责企微流水与收款单的核对(+150 行),OrderCommissionService 改为按 allocation 维度聚合佣金金额。
  • 回填脚本 qywx_receipt_allocation_backfill.sql 设计上非常审慎:先做只读统计(按收款方式分组计数与金额合计、抽样 20 条、统计无 form_id 的数量),再建 home_fee_allocation_backfill_backup 备份表,然后用存储过程 backfill_fee_order_allocations() 在事务内执行,遇到"历史金额异常"(amount 为空/非正、退款额为负或大于收款额)直接 SIGNAL SQLSTATE '45000' 中止,回填后再校验"无遗漏分配"与"现有分配总额不超收款额",全部通过才 COMMIT。
  • 测试覆盖:QywxReceiptSplitTransactionTest(264 行)验证拆分的事务原子性、QywxReceiptAllocationTest(61 行)、ReceiptAllocationBackfillTest、ReceiptPaymentCallbackTest、OrderReceiptAssociationTest。
  • 代码片段(回填中止条件): sql IF EXISTS(SELECT 1 FROM home_fee_order f WHERE f.form_id>0 AND NOT EXISTS(SELECT 1 FROM home_fee_order_allocation a WHERE a.fee_order_id=f.id) AND (amount IS NULL OR amount<=0 OR COALESCE(refund_amount,0)<0 OR COALESCE(refund_amount,0)>amount)) THEN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='Invalid legacy receipt amounts; inspect samples before backfill'; END IF;

8. refactor(fee): 优化收款单业务逻辑移除旧有分配结构

  • 提交: cf3215c3337f(2026-10-28)
  • 涉及文件(34 个,+657/-858): CrmFeeOrderService.java(-180 余行)、FeeOrderController.java、QywxReceiptReconcileService.java、HomeFeeOrderServiceImpl.java、多个 VO/Mapper/实体,以及 3 个 SQL 脚本
  • 改动说明:
  • 在同一周内主动收敛上一提交引入的关联表方案:当前方案退回"一张收款单对应一个申请;同一企微流水需要拆分时,每次新建一张收款单",并删除 HomeFeeOrderAllocation 实体的冗余字段、HomeFeeOrderAllocationMapper、OrderCommissionReceipt PO 及相关 VO 字段(净减约 200 行)。
  • 删除上一提交新增的回填脚本 qywx_receipt_allocation_backfill.sql,qywx_receipt_split.sql 相应精简(84 行 → 48 行)。
  • 体现的是对线上数据迁移风险的判断:关联表方案虽然更灵活,但需要停写窗口与数据回填,在本期选择了更低风险的等价实现。

9. feat(feeOrder): 新增拆分类型筛选功能

  • 提交: 4bcdfeed8bac5(2026-10-28)
  • 涉及文件(3 个,+7): FeeOrderController.java、FeeOrderPageQuery.java、HomeFeeOrder.java
  • 改动说明:
  • FeeOrderPageQuery 新增 splitType(0 = 不拆分含线上,1 = 拆分;不传/null 不筛选),HomeFeeOrder 新增 SPLIT_TYPE = "split_type" 列常量。
  • Controller 层显式校验取值范围:if (query.getSplitType() != null && query.getSplitType() != 0 && query.getSplitType() != 1) return R.error("是否拆分仅支持0或1")。
  • SQL 条件用 .eq(query.getSplitType() != null, ...) 而非 .eq(boolean, ...),确保显式传 0 时不会被当成"未传"而忽略——这是 MyBatis-Plus 条件构造器最常见的坑。

10. test(feeOrder): 添加拆单过滤条件单元测试

  • 提交: d9065434e48e(2026-10-28)
  • 涉及文件(3 个,+68/-1): build.gradle(新增 testFeeOrderSplitFilter 任务)、FeeOrderPageQuery.java(注释修正为"申请表ID")、FeeOrderSplitFilterTest.java(新增 65 行)
  • 改动说明:
  • 测试用 MockMvc 走真实 JSON → Controller → MyBatis QueryWrapper 生成 SQL → 在本地 H2(MODE=MySQL)执行的完整链路,通过正则把 #{} 占位符替换为 ? 再绑定参数执行,验证的是真实 SQL 语义而非 mock 行为。
  • 覆盖 5 个关键用例:不传不筛选、显式 null 不筛选、0 值不被忽略且包含线上单、1 只返回拆单、拆分筛选与线下收款方式组合筛选。

11. feat(feeOrder): 支持交易流水号搜索和完善拆分筛选测试

  • 提交: 51934e5561e1(2026-10-28)
  • 涉及文件(3 个,+13/-5): FeeOrderController.java、FeeOrderPageQuery.java、FeeOrderSplitFilterTest.java
  • 改动说明:
  • 搜索关键词从只匹配收款单号扩展为三路 OR:收款单号 fee_code、已支付单据的支付单号 pay_order_code、交易流水号 pay_code。 java }).or().like(HomeFeeOrder.FEE_CODE, query.getCode()) .or().like(HomeFeeOrder.PAY_CODE, query.getCode());
  • 测试表结构相应扩展(新增 pay_status / fee_code / pay_order_code / pay_code 列),验证"同一支付流水的多张拆单都能被搜到"(TXN-SHARED 命中 3、4)、"交易流水搜索不绕过拆分筛选"、"未支付单据不匹配支付单号(保留既有排除逻辑)",以及注入串 ' OR 1=1 -- 被当作字面量。

12. test(fee): 增加退款金额更新的事务测试

  • 提交: eec1c70d78be(2026-10-28)
  • 涉及文件(1 个,+3): QywxReceiptSplitTransactionTest.java
  • 改动说明:
  • 在事务中更新收款单的 refund_amount 后,断言佣金回显侧的 allocation.refundAmount 同步为更新值,保证退款金额在两张表之间不脱节。

三、到账流水与 Invoice 开票链路(10/28-10/30)

13. refactor(arrival-ledger): 放宽到账流水业务字段校验与更新逻辑

  • 提交: 6695e2d293b2(2026-10-29)
  • 涉及文件(17 个,+346/-254): 两份 SQL 建表脚本、MdySyncService.java、CommissionArrivalLedgerController.java、ArrivalLedgerParam.java、ArrivalLedgerUpdateParam.java、CommissionArrivalLedgerService.java(+134/-)、CommissionInvoiceService.java、5 个测试类
  • 改动说明:
  • 数据库层: 新增 DDL 把 commission_arrival_ledger 的 6 个业务字段由 NOT NULL 改为 DEFAULT NULL:payment_receiver_id、arrival_date、money_unit、arrival_amount(并把注释从"必须大于0"改为"可空,允许0及负数")、payer_name、bank_reference。脚本开头注明"仅准备,尚未在测试/生产执行",并给出执行前核对项(DATABASE()、@@server_uuid、SHOW CREATE TABLE)与执行后核对项(6 列 IS_NULLABLE=YES、COLUMN_DEFAULT=NULL、索引不变),同时强调 DDL 隐式提交不能按事务回滚处理。
  • 应用层: 校验策略从"必填 + 金额必须大于0 + 币种枚举校验 + 收款账户存在性校验"改为"全部业务字段可省略或显式传 null 清空":null 写入 NULL,字符串空串/空白原样保留,日期空串/空白转为空;不校验必填、金额正数、币种枚举与账户存在性,非空日期仍需可解析。币种一律以接口传入为准,不再从收款账户反查。
  • 参数语义文档同步更新(新增/编辑/删除/下拉四类参数各自说明"新增均可省略")。
  • MdySyncService 中被注释掉的 throw new RuntimeException(e) 改为 log.error("发送明道同步消息失败,workSheetId={}, hooliId={}, action={}", ...),异常不再静默吞掉。

14. feat(invoice): 支持到账登记时主动传入实收合计金额

  • 提交: e6fa22983f7a(2026-10-28)
  • 涉及文件(4 个,+120/-7): CommissionInvoiceController.java、InvoiceMarkArrivalParam.java、CommissionInvoiceService.java、CommissionInvoiceServiceMarkArrivalTest.java(+92)
  • 改动说明:
  • InvoiceMarkArrivalParam 新增可选 totalActualCommission:传入时优先作为 Invoice 实收合计(允许 0,范围 0~9999999999.99,四舍五入保留两位小数),未传或为 null 时回退为按全部正常关联明细的 actual_commission 合计。
  • 汇总刷新逻辑改为带参版本 recomputeTotals(invoiceId, totalActualCommission),原无参重载保留并委托给 recomputeTotals(invoiceId, null)。
  • 语义边界明确:仅影响 Invoice 汇总字段与少到账金额(shortage_received_amount)计算,不改变逐单到账金额与订单累计实收。
  • 测试用 @CsvSource 参数化覆盖:未传 → 75.01(明细合计)、显式 null → 75.01、120.455 → 120.46(HALF_UP)、0 → 0.00、9999999999.994 → 9999999999.99。

15. feat(commission-invoice): 优化可开票订单筛选及到账标记逻辑

  • 提交: 6785468d2bd6(2026-10-28)
  • 涉及文件(6 个,+291/-13): InvoiceCandidateSearchParam.java、InvoiceMarkArrivalItem.java、CommissionInvoiceService.java(+67)、CommissionInvoiceServiceMarkArrivalTest.java(+79)、InvoiceCandidateQueryTest.java(+142)、InvoiceNotificationTest.java
  • 改动说明:
  • 可开票订单筛选放宽: 原逻辑硬编码只查"待结案 + 部分结案",现改为默认不限订单状态,可通过 orderStatusList 多选主动筛选(枚举含 0=待提交审核),传入无效状态直接抛异常。
  • 到账标记状态语义修正: 原实现只允许 30/40 两种结案状态,现改为校验"是否为合法订单状态",且仅当目标状态为已结案(40)时才写 financial_closing_time 与 case_financial_id,其他状态保留这两个字段原值。
  • 排序列白名单: 新增 CANDIDATE_SORT_COLUMNS(Map.ofEntries)共 23 项映射,列名与 SQL 表达式分离(如 issuedAmount → ROUND(COALESCE(landlord_receivable_commission,0) - COALESCE(landlord_actual_commission,0), 2)、cityName → 关联地址表子查询),由后端维护,防止前端传任意列名。

16. feat(commission): 优化到账账单关键字搜索及佣金标题清理逻辑

  • 提交: 320e0ffbc4c3(2026-10-29)
  • 涉及文件(9 个,+250/-14): 三个查询 Param、CommissionArrivalLedgerService.java(+12)、CommissionArrivalLedgerKeywordTest.java(新增 163 行)、tools/commission_title_cleanup.py(+42)、tools/test_commission_title_cleanup.py(+34)
  • 改动说明:
  • 到账流水关键字匹配字段从 4 个扩展到 10 个:流水编号、付款方名称、银行流水号、银行交易摘要、款项类型、备注、收款账户名称、关联 Invoice 编号、创建人姓名、最后修改人姓名,去除首尾空白后 OR 模糊匹配。
  • 关联字段一律走 IN 子查询而非 JOIN,代码注释写明原因:"关联字段通过 IN 子查询参与同一个 OR 组,避免一对多 Invoice 关联放大分页和统计笔数";且"与 VO 展示一致,保留停用/软删除账户及历史操作人的名称,不额外限制关联记录状态"。 java .or().apply("id in (select rel.arrival_ledger_id from commission_arrival_ledger_invoice_rel rel " + "join commission_invoice invoice on invoice.id = rel.invoice_id where invoice.invoice_code like {0})", "%" + kw + "%") .or().apply("create_user_id in (" + matchingUsers + ")", "%" + kw + "%")
  • 同步新增 Python 侧的佣金标题清理脚本及其单元测试,用于批量清洗存量标题数据。

17. fix(invoice): 兼容到账流水录入人及修改人为空

  • 提交: 1856904fff73(2026-10-30)
  • 涉及文件(3 个,+96/-2): hoolihome-crm-api/build.gradle、ArrivalLedgerVoBuilder.java、CommissionArrivalLedgerVoBuilderTest.java(新增 93 行)
  • 改动说明:
  • VO 构建时取录入人/修改人姓名,先判 ID 非空再查 map,避免 adviserMap.get(null) 抛 NPE: java vo.setCreateUser(ledger.getCreateUserId() == null ? null : adviserMap.get(ledger.getCreateUserId())); vo.setUpdateUser(ledger.getUpdateUserId() == null ? null : adviserMap.get(ledger.getUpdateUserId()));
  • 配套 93 行 MockMvc 测试(Mockito 隔离 ICommissionArrivalLedgerService / UserResolveProvider 等依赖),覆盖空 ID 场景。

四、渠道/合作方与业务量统计(10/29-10/30)

18. feat(distributor): 新增企业/合作方业务量统计及相关批量查询支持

  • 提交: 2c2bfaaf6859(2026-10-30)
  • 涉及文件(10 个,+393/-5): DistributorBusinessStatisticsController.java(新增)、DistributorBusinessStatisticsParam.java(新增)、DistributorBusinessStatisticsService.java(新增 92 行)、DistributorBusinessStatisticsVo.java(新增)、OrderPageQuery.java、OrderPageQueryService.java、build.gradle、两个测试类(含 179 行专项测试)
  • 改动说明:
  • 新增 POST /distributor/business-statistics 接口,返回企业/合作方维度下的商机、订单、申请三类业务量统计。
  • 参数校验严格:companyId 与 distributorId 必须且只能传一个(互斥);创建时间起止必传;ID 必须为正数;无操作权限直接拒绝。
  • 统计口径按"记录保存时的来源归属"计算,不通过合作方当前所属企业反推历史业务——避免合作方换签后历史业绩被错误归属到新企业。
  • 三类记录的时间字段类型不同:商机是毫秒时间戳,订单与申请是 datetime,因此分别调用 dates(...) 时传不同的布尔标志。
  • excludeCancelled 开关默认 false,且不影响商机统计(取消只对订单与申请生效)。
  • 接入 DataPermissionProvider 与 ReportRelationProvider 做数据权限与报表关联校验。
  • 顺带给 OrderPageQuery 增加 batchEmail(批量邮箱文本,与 emailList 合并去重)。
  • 代码片段: java if ((p.getCompanyId() == null) == (p.getDistributorId() == null)) { throw new IllegalArgumentException("企业ID与合作方ID必须且只能传一个"); } if (StrUtil.isBlank(p.getCreateTimeFrom()) || StrUtil.isBlank(p.getCreateTimeTo())) { throw new IllegalArgumentException("创建时间起止时间必传"); }

19. feat(order): 集成企业微信群组信息并更新订单响应结构

  • 提交: a1abffc6f0ba(2026-10-29)
  • 涉及文件(5 个,+246/-8): OrderController.java、OrderService.java(+27)、OrderCommentResponseTest.java、OrderQywxGroupResponseTest.java(新增 99 行)、OrderListQywxGroupTest.java(新增 113 行)
  • 改动说明:
  • 订单详情与列表响应新增三个字段:qywxGroupId、qywxGroupName、qywxGroupInfo(企微群组完整信息对象)。有 leads 时填 commonService.getGroupNameByGroupId(...) 与 qywxGroupService.getGroupVo(...),无 leads 时留空。
  • 列表接口消除 N+1 查询:原先对每条订单调用 leadsService.getById(...),现改为先收集 leadsId 集合 → 一次性 listByIds → 再批量取群组 Map → 逐条从 Map 回填;空列表直接 return List.of() 短路。 java var leads = orderInfo.getLeadsId() == null ? null : leadsById.get(orderInfo.getLeadsId()); var groupId = leads.getQywxGroupId(); var groupInfo = StrUtil.isBlank(groupId) ? Dict.create() : groupsById.getOrDefault(groupId, Dict.create());
  • 顺带修正测试环境 profile 解析:原先硬编码 profile.equals("pro"),现读取 spring.profiles.active 并区分 pro / beta / test 三个环境的基础 URL。

五、搜索、CRM 与基础设施(10/27-10/29)

20. feat(liveshot): 增加实拍素材关键词模糊搜索支持

  • 提交: cb85d6edc330(2026-10-29)
  • 涉及文件(5 个,+110/-8): LiveShotMaterialPageParam.java、HouseLiveShotMaterialService.java(+17)、LiveShotPageQueryTest.java(+65)、OrderCommentUploadTest.java、OrderCommentUploadStorage.java
  • 改动说明:
  • LiveShotMaterialPageParam 新增 keyword:模糊搜索实拍标题、备注或当前关联的图片/视频附件文件名,任一命中即可;未传/null/空白时不筛选。
  • 附件归属规则与列表保持一致——评价实拍(data_type = 2)用评价 ID,其他实拍用素材 ID,通过 CASE WHEN 在 SQL 内切换;关键字一律用 LIKE {0} 绑定参数。

21. fix(service): 优化关键词查询时附件文件名匹配逻辑

  • 提交: 278bf171fd59(2026-10-29)
  • 涉及文件(2 个,+19/-13): HouseLiveShotMaterialService.java、LiveShotPageQueryTest.java
  • 改动说明:
  • 把上一提交的 EXISTS 子查询改为先物化"文件名命中的归属 ID"再 IN: java // DISTINCT 阻止派生表合并:先物化文件名命中的归属 ID,避免 OR 内的 IN 被改写为逐实拍扫描附件表。 private static final String MATCHED_ATTACHMENT_DATA_IDS = "(SELECT matched.data_id FROM (SELECT DISTINCT file_ref.data_id ... WHERE ... LIKE {0}) matched)"; 原因是 OR 条件里的 IN 子查询容易被优化器改写成逐行扫描附件表,产生严重的行放大;用派生表 + DISTINCT 物化后只扫一次附件表。
  • 同时用 or(r -> r...) 分组,保证"评价实拍"与"其他实拍"两个分支各自绑定各自的 data_type/data_sub_type,且 OR 组不会绕过 houseId 等其他筛选条件。
  • 测试补齐"非评价素材"(data_type≠2)的边界用例以及 ' OR 1=1 -- 注入串用例。

22. feat(api-lease): 优化租期规则映射与同步逻辑

  • 提交: 8ba12e675c70(2026-10-29)
  • 涉及文件(18 个,+516/-100): ApiLeaseMapping.java(+210/-)、ApiLeaseDiff.java、ApiLeaseSyncResult.java、ApiRoomRentSyncService.java、SyncService.java、UnilodgeLeaseMapping.java、IQSyncService.java、SturentsSyncService.java、UniteSyncService.java、2 个 Controller/Service、6 个测试类
  • 改动说明:
  • 租期去重 key 从旧结构切换为显式规则:RoomRentRules.planType(a) / endMode(a) / durationMode(a) + rentNum + rentExtraDays,并额外把 rentEndMode、rentDurationMode、rentNumType 与总报价(金额归一化后)纳入 key,保证语义相同但报价不同的租期不会被误判为同一记录而丢弃。
  • 供应商报价优先于日期差:"iQ 等供应商明确提供的报价周数优先,不能以日期差覆盖报价时长"——只有 rentNum 为空/非正或单位不是周时才用日期差换算周数与余天。
  • 未提供总报价 ≠ 清空人工确认的报价:next.getTotalPrice() == null && RoomRentRules.definiteDuration(next) 时保留 previous.getTotalPrice(),且禁止从周价自动重算总价。
  • 申请列表默认排序改为 create_time + id 稳定排序(orderByDesc(CREATE_TIME, ID)),旧的 ApplicationFormPageQueryService 默认排序字段同步从 id 改为 createTime,避免相同创建时间下分页顺序抖动。

23. fix(house-commission): 修正仅返回状态为 1 的关联佣金并按 ID 降序排序

  • 提交: b997b16ce9ee(2026-10-29)
  • 涉及文件(4 个,+57/-5): invoice_room_number_255.sql(新增)、建表.sql、HouseV2Service.java、HouseDetailCommissionPolicyTest.java
  • 改动说明:
  • 关联佣金的过滤条件由 status <> 127(排除已删除)改为 status = 1(仅返回生效佣金),语义从"排除法"变为"白名单法",避免中间态佣金混入展示。
  • 排序改为按佣金 ID 降序,保证展示顺序稳定。
  • 测试用 H2 造了 7 条不同 status / expiration_date 的佣金数据(含 NULL status、status=0/1/2/127 与跨房源关联),断言最终只返回 [16, 10] 且全部 status=1。
  • 同步提交 commission_invoice_order_rel.room_number 由 varchar(64) 扩长到 varchar(255) 的 DDL(保留原字符集 utf8mb4 / 排序规则 utf8mb4_0900_ai_ci / 可空性 / 默认值 / 注释,使用 ALGORITHM=INPLACE, LOCK=NONE,脚本要求执行前核对生产库身份与列定义、执行后与备份逐行核对原值)。

24. refactor(api): 标记部分接口为废弃,提示使用新版本接口

  • 提交: 27114ceaf12d(2026-10-27)
  • 涉及文件(6 个,+20/-5): ApplicationFormController.java、FeeOrderController.java、LeadsController.java、MediaLeadController.java、HouseController.java、RoomController.java
  • 改动说明:
  • 六个 Controller 中的旧接口统一补 @Deprecated 注解与注释指向 v2 接口路径(如"后台已停用,请使用 list/v2"、"后台已停用,房源选择使用 page/list,主列表使用 page/list/v2"、"后台已停用,请使用 add/v2 / update/v2 / info/v2")。
  • 顺带修正两处注释错误:LeadsController 的编辑线索接口被误标废弃,改为"当前后台使用此接口";线索状态更新接口的废弃注释改为"内部复用增量更新"。

25. feat(application-mail): 支持邮件模版类型区分与校验

  • 提交: fefab980ed1c(2026-10-28)
  • 涉及文件(9 个,+216): application_mail_template_type.sql(新增)、ApplicationMailController.java、ApplicationMailTemplateLog.java、ApplicationMailTemplateLogBuilder.java、ApplicationMailTemplatePage.java、ApplicationMailService.java、MailTemplateType.java(新增枚举)、MailTemplateTypeTest.java(新增 152 行)、ApplicationMailTemplate.java
  • 改动说明:
  • 新增枚举 MailTemplateType:1 = 申请邮件模版、2 = invoice 邮件模版,与"邮件发送方式"及"Invoice 文档模版类型"相互独立。
  • application_mail_template 表新增 type tinyint NOT NULL DEFAULT 1,DDL 注明"历史记录兼容为申请邮件模版,不根据标题推断 Invoice 类型",且必须在字段不存在时执行一次。
  • 查询、新增、更新三处均调用 MailTemplateType.validate() 校验,非法值抛"邮件模版类型只能为1(申请邮件模版)或2(invoice邮件模版)";新增时未指定类型默认 APPLICATION。
  • 列表与日志返回 type 与 typeText,日志侧通过 @LogFieldMate(fieldName = "类型") 记录类型文案。

26. fix(query): 修正查询排序字段为 id

  • 提交: 0ed01303e9b7(2026-10-28)
  • 涉及文件(1 个,+1/-1): ApplicationFormPageQueryService.java
  • 改动说明: 默认排序字段由 createTime 改回 id(sort(q, p, SORT_COLUMNS, "id")),与第 22 项 ApiLeaseMapping 中的默认排序调整配套——申请列表在明确指定排序时以 id 为准以保证稳定分页。

27. test(houseCommission): 添加房屋佣金分页过滤参数兼容及测试

  • 提交: d913ca81e1b1(2026-10-27)
  • 涉及文件(7 个,+183/-6): OrderPageQuery.java、OrderPageQueryService.java、HouseCommissionPageParam.java、HouseCommissionService.java、两个公共测试类、HouseCommissionBatchTest.java(新增 74 行)
  • 改动说明:
  • 单选参数兼容旧调用: 租期类型、学年两个单值参数原实现只接受 JSON 数组字符串,现改为 filterValues() 统一处理——空白返回空列表不筛选;是 JSON 数组则解析;否则当作单值包成单元素列表,兼容新旧两种前端调用方式。
  • 订单姓名条件拆分: 原 cnNameList 注释为"客户名称精确多选;与包含条件同时传时取交集",现明确为"中文姓名精确多选;与其他字段同时传时取交集",并新增独立的 userNameList(拼音姓名,完整姓名中的空格保留)与 cnNameList 两个参数,查询服务分别 in(...) 到 USER_NAME 与 CN_NAME 两列。

28. feat(query): 支持订单查询批量中文及拼音姓名文本输入

  • 提交: 1f209eec429d(2026-10-27)
  • 涉及文件(4 个,+73/-4): OrderPageQuery.java、OrderPageQueryService.java、OrdinaryPageQueryTest.java(+51)、OrdinaryQueryHttpTest.java
  • 改动说明:
  • 新增 batchCnName / batchUserName 两个多行文本参数:每行一个完整姓名,忽略空行、首尾空白与重复项,保留姓名内部空格("ZHANG SAN" 不会被拆成两个 token)。
  • 与旧的多选参数(cnNameList / userNameList)合并去重,用 LinkedHashSet 保持顺序: java private Set<String> batchNames(String text, List<String> selected) { var names = new LinkedHashSet<String>(); if (selected != null) names.addAll(selected); var lines = ParamUtils.strToList(text); if (lines != null) names.addAll(lines); return names; }
  • 参数化测试覆盖 14 种输入,包括:仅换行分隔可匹配、逗号/分号分隔不被误拆(返回空)、拼音含空格不被拆分、单字"张"不匹配、注入串 ' OR 1=1 -- 被当字面量、与旧多选参数合并去重、与 keyword/订单号等其他条件取交集。

29. chore(docker): 优化生产环境容器内存配置

  • 提交: fdf7484fe603(2026-10-27)
  • 涉及文件(1 个,+5/-3): hoolihome-data-cron/docker-compose-prod.yml
  • 改动说明:
  • JVM -XX:MaxMetaspaceSize 由 180m 提升到 384m,注释写明原因:"Cron 的任务与 SDK 共用 JVM;180m 已在线上触发 Metaspace OOM,需保留类加载余量"。
  • 容器 memory 上限由 2000M 提升到 2500M,注释说明"上限同时覆盖 1GB 堆、元空间、线程栈、代码缓存和其他本地内存"——堆上限不变而容器上限上调,避免 OOM kill。

📊 本周工作总结

【核心成果】

  • 完成租期规则与客户端展示体系重构:租期规则统一由服务端解析,客户端只消费解析好的起止日期;通过 JSON 平铺序列化与 @Deprecated 字段保留实现新旧 App 平滑过渡;新增租期时长说明字段(可显式更新或清空)并补全钱包提现规则中额度、次数、提现窗口与到账时间等争议点说明。
  • 收敛收款单与企微申请关系模型:落地企微拆分分配与收款单申请关联回显,佣金改按分摊维度计算,配套事务回滚、退款回写、回调幂等与组合筛选测试;随后主动收敛为"一张收款单一个申请"的低风险等价实现,删除冗余实体与回填脚本。
  • 完善到账流水与 Invoice 开票链路:6 个流水业务字段由必填改为可省略/可清空(配套独立 DDL 与核对清单),开票到账支持主动指定实收合计,可开票订单筛选、状态语义、排序列白名单与关键字查询全部增加边界保护与参数化绑定。
  • 扩展渠道与运营能力:新增企业/合作方业务量统计接口(按记录保存时的来源归属统计),订单响应集成企微群组信息并消除 N+1 查询,订单查询支持批量中文/拼音姓名文本输入,实拍素材支持标题、备注与附件文件名模糊搜索。

【技术亮点】

  • 以兼容演进替代客户端一次性升级:用 @JSONField(unwrapped=true) 保证旧字段协议不变,用 @Deprecated 暂留旧版 App 必需字段,并用"未提交保持、显式 null 清空"的更新语义(rentDurationDescriptionUpdated 标志位)避免数据被误覆盖。
  • 重构企微分账数据结构并配套事务一致性保障:拆分关系从订单冗余字段迁移到独立表,对账与佣金计算按 allocation 聚合;回填脚本内建备份表、只读预检、SIGNAL SQLSTATE 中止与回填后逐项核对,异常数据宁可整体中止也不自动跳过。
  • 优化高频查询与批量回填性能:订单群组信息由逐行 getById 改为批量取 Map 回填;实拍附件匹配由 EXISTS 改为主物化归属 ID 后 IN 查询,避免 OR 条件引发行放大;到账账单关联字段一律用 IN 子查询而非 JOIN,防止一对多放大分页与统计笔数;排序字段收敛为 23 项后端白名单,杜绝任意列名注入。
  • 建立较完整的自动化验证边界:租期 JSON 序列化、收款拆分事务、退款同步、流水字段更新、账单筛选、统计权限、姓名批量输入与佣金有效性均增加专项测试(本期新增/扩展测试约 1500 行);所有关键字走绑定参数,配合 H2 + 真实 JSON + 真实 SQL 的链路级验证,替代以往只断言 mock 行为的写法。

【业务价值】

  • 降低租期与提现的理解成本:客户端不再自行解释多套租期规则,租期截止时间与金额展示口径统一,且"可协商"语义通过文案而非后缀表达;提现限制与到账预期补全后,可显著减少客服咨询与用户误解。
  • 提升收款、企微分账与佣金核算的可追溯性:拆分金额、退款金额与企微流水关系均可独立核对;拆单可按类型筛选,并支持通过收款单号、支付单号或交易流水号定位同一支付流水下的多张拆单。
  • 增强到账与开票环节的数据处理灵活性:支持部分到账、主动登记实收合计与字段清空,Invoice 汇总与少到账金额计算更贴近实际,同时保持逐单到账金额与订单累计实收口径不变,财务侧可少做人工调平。
  • 支撑渠道经营分析与运营提效:业务量按记录发生时保存的来源归属统计,不依赖合作方当前所属企业,历史业绩不会被换签操作错误改写;订单批量姓名检索、企微群组信息与素材模糊搜索进一步提升运营查找效率。

报告生成时间:2026-10-30 数据来源:production 分支 git 三路合并(merge 带入提交 + 分支直提),共 29 个提交