grocy 3.1.3 版本更新详解库存过滤与到期日增强、家务合并与 API 变更实战指南【免费下载链接】grocyERP beyond your fridge - Grocy is a web-based self-hosted groceries household management solution for your home项目地址: https://gitcode.com/GitHub_Trending/gr/grocy本指南围绕 grocy 3.1.32021-11-14 发布的官方更新日志changelog/65_3.1.3_2021-11-14.md展开逐条解读本次版本在库存管理、购物清单、家务Chores与 API 层面的功能增强与缺陷修复并结合当前仓库源码给出实现层面的佐证。读完本文你将掌握 3.1.3 中每一项新能力的界面入口、配置含义与底层调用链便于升级后立即上手使用或在二次开发时定位对应实现。版本定位3.1.x 维护分支的一次功能与修复双修3.1.3 是 grocy 3.1 系列的第三个补丁版本定位为在保持 API 兼容的前提下对库存、购物清单、家务与用户界面体验进行集中打磨。本次更新没有引入破坏性变更但有一处API 请求体参数重命名print_stock_label→stock_label_type需要调用方留意详见下文API 变更一节。整体改动可归纳为四条主线库存概览与到期日逻辑增强、购物清单可用性提升、家务数据合并能力、以及一批覆盖标签打印、夜间模式与登录流程的缺陷修复。库存概览页Stock Overview三项增强1. Below min. stock amount 过滤器扩展到期产品变更内容库存概览页上的 Below min. stock amount低于最小库存量过滤器此前只筛选库存量低于最小库存阈值的产品本次更新后该过滤器同时包含即将到期due soon、已逾期overdue或已过期expired的产品即筛选口径从仅数量维度扩展为数量 保质期紧迫度双维度。实现佐证在库存视图中到期/过期与缺货分别对应两条查询路径。services/StockService.php 中的GetDueProducts(int $days 5, bool $excludeOverdue false)通过best_before_date date(now, $days days)检索临期产品GetExpiredProducts()则通过best_before_date date()检索已过期产品而过滤器选项本身定义在库存概览视图 views/stockoverview.blade.php 的option valuebelowminstockamount中。3.1.3 的改动即是在该过滤器的计算逻辑中把到期状态纳入判断范围使一个过滤器即可同时覆盖需要补货和需要尽快消耗/处理两类关注点。2. 新增产品平均价格列默认隐藏变更内容库存概览页新增**产品平均价格average price**列该列默认隐藏用户可在列配置中自行开启。启用后每行会显示该产品的平均采购单价并按库存单位stock quantity unit与价格单位price quantity unit分别换算展示。实现佐证列渲染逻辑位于 views/stockoverview.blade.php。该列受GROCY_FEATURE_FLAG_STOCK_PRICE_TRACKING特性开关控制开关关闭时整列通过d-none隐藏单元格内同时输出排序用原始值{{$currentStockEntry-average_price}}custom-sort隐藏 span展示值按库存单位显示average_price按价格单位显示average_price * product_qu_factor_price_to_stock即用数量单位换算系数折算到价格单位并带 tooltip。对应的数据来源可在GetProductDetails的返回结构中找到services/StockService.php 将avg_price $detailsRow-average_price暴露给视图即最后一次采购以来所有采购记录的平均单价。这一列对家庭预算管理与某商品买贵了/买便宜了的复盘非常实用。3. 新产品默认到期天数预设Presets for new products变更内容库存设置Stock settings中新增Presets for new products分组可配置新建产品时的Default due days默认到期天数选项。即当用户手工创建新产品时默认到期天数字段会按预设值自动填充减少每次录入时的重复输入。背景说明grocy 中每个产品可以设置默认到期天数在购买该产品时系统据此自动计算最佳食用日期best-before date。3.1.3 之前该默认值仅在创建产品时手工填写本次将其提升为可配置的全局预设属于纯 UI/配置层增强。该项设置与下述冷冻到期日逻辑配合构成了完整的到期日默认值体系。4. 冷冻直入库存时到期日预填优化变更内容当购买purchase一个设置了 Default due days after freezing冷冻后默认到期天数的产品并且直接将入库位置指定为冷冻库freezer location时新增库存条目stock entry的到期日现在会优先按该冷冻默认值预填而不再使用常规的 Default due days。使用场景肉类、面团等冷冻保存周期远长于冷藏的商品在购买后直接入冷冻库时其真实到期日应基于冷冻保存时长计算。3.1.3 前购买表单一律按常规默认天数预填到期日需要手工改本次更新让系统根据目标位置自动选择正确的默认值减少操作步骤与误填风险。购物清单默认清单可重命名 流程缺陷修复默认购物清单现在可以重命名变更内容默认购物清单界面默认名称为 Shopping list且随界面语言本地化此前名称固定不可修改3.1.3 起用户可以对它进行重命名方便与家庭中实际使用的清单名称如周末采购保持一致。实现佐证grocy 的购物清单数据由shopping_list表承载相关聚合逻辑见 services/StockService.php 中过期产品自动加入购物清单的实现清单名称维护走通用实体GenericEntity编辑通道。本次改动本质上是放开对内置默认清单的写权限其余编辑、排序、条目管理流程不变。修复Add as new product 流程结束后清单错乱变更内容从购物清单条目表单启动的Add as new product另存为新商品选择器流程此前在流程结束时总会错误地跳回/选中默认购物清单3.1.3 修复了该问题流程结束后会正确回到用户发起操作时所在的购物清单不再串清单。家务Chores新增合并功能界面入口变更内容家务列表页的上下文菜单/更多菜单context-/more-menu中新增Merge合并操作。用户选择要保留的家务与要合并掉的家务后系统会将后者的执行历史chores_log全部转移到前者名下并删除被合并的家务记录。这特别适合处理重复创建的家务或因改名/改周期而产生的冗余条目。新 API 端点合并功能同时暴露为 REST APIPOST /chores/{choreIdToKeep}/merge/{choreIdToRemove}。路径中两个参数的含义为参数含义choreIdToKeep合并后保留的家务 ID接收执行历史的一方choreIdToRemove被合并并从家务列表删除的家务 ID实现佐证端点处理器位于 controllers/Api/ChoresApiController.php其要点如下首先执行User::CheckPermission($request, User::PERMISSION_MASTER_DATA_EDIT)即需要主数据编辑权限普通只读用户不可调用对两个路径参数用FILTER_VALIDATE_INT校验非整数时抛出Provided {choreIdToKeep} or {choreIdToRemove} is not a valid integer校验通过后委托ChoresService::GetInstance()-MergeChores(...)执行核心逻辑。底层数据操作在 services/ChoresService.php 中实现体现了清晰的防御性与事务性设计public function MergeChores(int $choreIdToKeep, int $choreIdToRemove) { if (!$this-ChoreExists($choreIdToKeep)) { throw ... } // 保留方必须存在且有效 if (!$this-ChoreExists($choreIdToRemove)) { throw ... } // 被合并方必须存在且有效 if ($choreIdToKeep $choreIdToRemove) { throw ... } // 两个 ID 不能相同 // 事务开始 UPDATE chores_log SET chore_id {choreIdToKeep} WHERE chore_id {choreIdToRemove}; DELETE FROM chores WHERE id {choreIdToRemove}; // 提交任一失败则回滚并重新抛出 }具体而言逻辑等价于源码中的 SQL 语句先通过UPDATE chores_log SET chore_id choreIdToKeep WHERE chore_id choreIdToRemove把被合并家务的全部执行日志重定向到保留家务随后DELETE FROM chores WHERE id choreIdToRemove删除冗余家务。整个过程包裹在数据库事务中beginTransaction/commit/ 异常时rollback保证日志转移 记录删除要么全部成功、要么全部回滚不会出现历史数据丢失或悬挂引用。本次修复的缺陷清单3.1.3 除上述功能外还修复了一批影响日常使用的缺陷按模块归纳如下库存 / 标签每单位一个标签Label per unit打印不唯一购买时按每单位生成的库存条目标签stock entry label此前在单位数大于 1 时标签内容彼此相同、无法区分本次修复后每个单位对应的标签具有唯一标识扫描任一标签都能定位到对应的具体库存批次。撤销已打开产品事务时到期日丢失当产品设置了 Default due days after opened开封后默认到期天数时若执行了打开产品操作又将其撤销原始到期日此前无法恢复本次修复保证撤销后到期日正确还原。家务 / 日历Track date only 家务到期日当天误报逾期仅跟踪日期不跟踪时间的家务在到期日当天会被家务概览页错误标记为已逾期本次修复后当天不再误报只有真正超过当天才显示逾期。界面与交互列重排后表格下拉过滤器失效对表格列进行重新排序后部分下拉过滤器无法正常过滤已修复列排序与过滤器状态的联动问题。自动夜间模式跨午夜失效自动切换的夜间模式在跨过午夜0 点时并不总是生效已修复时间判断逻辑。夜间模式下上下文菜单标签不可读夜间模式Night Mode下上下文/更多菜单的标签文字对比度不足、难以阅读感谢贡献者 corbolais已修复配色。登录页 Remember Me 复选框无效此前勾选 Remember Me记住我不产生任何实际效果会话仍按普通会话处理本次修复后勾选即可获得持久化会话感谢贡献者 0。API 变更汇总1.print_stock_label参数重命名为stock_label_type需调用方跟进变更内容库存新增端点/stock/products/{productId}/add的可选请求体参数print_stock_label更名为stock_label_type。调用方如需在购买时打印库存标签应改用新参数名旧参数名将不再生效。实现佐证controllers/Api/StockApiController.php 中AddProduct方法读取请求体时使用$stockLabelType 0; if (array_key_exists(stock_label_type, $requestBody) is_numeric($requestBody[stock_label_type])) { $stockLabelType $requestBody[stock_label_type]; }即参数为可选数值类型缺省值为0不打印标签传入数值时作为标签类型标识传给StockService::AddProduct(...)。同一模式下盘点接口InventoryProductcontrollers/Api/StockApiController.php也使用stock_label_type读取相同语义参数。建议所有调用方将请求体字段同步改为stock_label_type并传入0不打印或其他合法的标签类型数值。2. 查询过滤器支持反斜杠变更内容修复了 API 查询过滤器query filters中**不允许出现反斜杠\**的问题。此前在过滤条件中传入含\的字符串如 Windows 风格路径、转义字符会报错或过滤失败3.1.3 起反斜杠可作为普通字符参与过滤适用于按名称/备注/条形码等字段做包含式筛选的场景。3. 新增家务合并端点即上文所述的POST /chores/{choreIdToKeep}/merge/{choreIdToRemove}需要主数据编辑权限此处不再赘述——注意它与本版本的界面Merge菜单使用完全相同的服务层实现因此通过 API 合并与通过界面合并的行为完全一致。升级与使用建议API 调用方优先行动若你的自动化脚本或第三方客户端调用了/stock/products/{productId}/add且使用了print_stock_label请升级后立即改为stock_label_type并测试缺省0与打印两种取值。善用新过滤口径升级后Below min. stock amount 过滤器的结果集会比之前更大新增临期/过期产品在做补货清单时请结合到期日排序确认避免把过期产品当作单纯缺货处理。合并家务前确认方向合并操作是单向且不可逆的日志转移后原家务被删除调用/merge端点或界面操作前请确认choreIdToKeep确实是想要保留历史记录的那一方。预期行为变化Track date only 家务的逾期判定、冻结直入的到期日预填均属行为修正升级后若观察到与旧版本不同的展示结果属于预期改动可对照 changelog/65_3.1.3_2021-11-14.md 复核。总结grocy 3.1.3 是一次典型的体验型小版本升级它没有重构架构却密集改善了库存到期日管理、购物清单、家务合并与夜间模式等高频使用场景并通过新增POST /chores/{choreIdToKeep}/merge/{choreIdToRemove}端点与stock_label_type参数重命名为 API 用户提供了数据合并能力与更清晰的参数语义。对于家庭库存管理实践者本次更新的冷冻到期日预填、平均价格列与低于最小库存过滤器扩展三件套直接降低了日常采购与保质期跟踪的心智负担对于开发者合并家务的事务实现services/ChoresService.php与标签参数的数值校验controllers/Api/StockApiController.php都是值得参考的既有模式。【免费下载链接】grocyERP beyond your fridge - Grocy is a web-based self-hosted groceries household management solution for your home项目地址: https://gitcode.com/GitHub_Trending/gr/grocy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考