zkxw/docs/superpowers/specs/2026-06-17-storage-facility-node-code-design.md

库位层级编号与储物格完整编号设计文档

日期: 2026-06-17
状态: 已确认
范围: 后端 + web-admin + SQL 迁移
关联模块: 库位管理、细胞产品库、生产任务、出库放行

1. 背景

1.1 现状

库位管理由两张表组成（见 docs/superpowers/specs/2026-05-22-storage-slot-occupancy-design.md）：

• biz_storage_facility：树形结构（液氮罐 → 层 → 盒），字段含 node_name、node_type、is_leaf，无编号字段
• biz_storage_facility_slot：叶子节点下的储物格，slot_code 仅存盒内坐标（如 1-3）

业务展示时，储物格位置拼接为 名称路径 + 本地编码：

液氮罐A / 第1层 / 盒01 / 1-3

名称路径用 / 分隔（buildTreePathLabelFromFlat / _build_facility_path_label）。

1.2 客户新需求

• 树形库位 每一层 都有独立 编号
• 储物格 完整编号 = 从根到叶所有层级编号 + 储物格本地编号，段间用 - 连接
• 示例：罐 1 → 层 2 → 盒 03 → 格 1-3 → 完整编号 1-2-03-1-3

1.3 需求确认

维度	决策
节点编号格式	单段，不含 -（字母或数字，如 1、03、A）
格子本地编码	保持 行-列（如 1-3）
完整编号生成	动态计算（节点存 node_code，格子存本地 slot_code）
编号修改策略	允许修改；修改后 批量刷新关联快照
名称 vs 编号	分离：node_name 继续用于名称路径；node_code 用于编号路径

2. 方案选型

方案	描述	结论
A（采用）	节点新增 node_code；slot_code 存本地坐标；API 返回 fullSlotCode	✅ 推荐
B	slot_code 直接存完整编号	❌ 父级改编号需批量改格子；字段冗余
C	双字段 slot_code + full_slot_code 冗余存储	❌ 同步成本高

2.1 编号修改策略选型

方案	描述	结论
A	允许改，快照不更新	❌
B	有子节点/格子后禁止改	❌
C（采用）	允许改，并批量更新关联快照	✅

3. 数据模型

3.1 biz_storage_facility 新增字段

ALTER TABLE biz_storage_facility
  ADD COLUMN node_code VARCHAR(32) NOT NULL DEFAULT '' COMMENT '节点编号（单段，不含连字符）'
  AFTER node_name;

约束与校验（应用层 + 可选 DB）：

规则	说明
格式	/^[A-Za-z0-9]+$/，禁止 -
兄弟唯一	同一 parent_id + tenant_no 下 node_code 不可重复
必填	新建节点必填；迁移后存量须补全
根节点	同样必须有 node_code

索引建议：

CREATE INDEX idx_sf_parent_code ON biz_storage_facility (parent_id, tenant_no, node_code, del_flag);

3.2 biz_storage_facility_slot 不变

• slot_code 仍存盒内本地坐标（{row}-{col}）
• 不新增 full_slot_code 列

3.3 完整编号计算规则

def build_node_code_path(node_id: str, facility_by_id: dict) -> str:
    """从根到当前节点的 node_code，用 '-' 连接。例：'1-2-03'"""

def build_full_slot_code(facility_node_id: str, slot_code: str, facility_by_id: dict) -> str:
    """例：build_node_code_path(...) + '-' + slot_code → '1-2-03-1-3'"""

• facility_node_id：格子所属叶子节点 ID
• slot_code：本地 行-列
• 若 slot_code 为空，仅返回节点路径编号（一般不应出现在叶子格子上）

租户内完整编号唯一性： 由树结构 + 兄弟唯一 node_code + 叶子内 slot_code 唯一共同保证；叶子内 slot_code 在同一 facility_node_id 下应已有业务约束（批量生成不重复）。

3.4 字段长度

完整编号示例：1-2-03-1-3（约 10 字符）。深层树或长编号预估 ≤ 64 字符，当前 slot_code VARCHAR(64) 足够存储本地坐标；fullSlotCode 仅 API 返回，不入库。

4. 编号变更级联（策略 C）

4.1 触发时机

update_facility 当 node_code 发生变化时，在同一事务内执行级联刷新。

4.2 影响范围计算

1. 收集被修改节点及其 所有后代 节点 ID
2. 找出这些节点下所有 叶子节点（is_leaf=1）
3. 查出这些叶子下全部未删除的 biz_storage_facility_slot
4. 对每个 slot 重新计算 fullSlotCode

4.3 快照表刷新

当前持久化 storage_slot_name 的表：

表	字段	刷新方式
biz_outbound_release_cell	storage_slot_name	按 cell_product_id → biz_cell_product.storage_slot_id 匹配受影响 slot，更新为新 fullSlotCode

运行时计算、无 DB 快照的模块（改编号后自动生效，无需刷表）：

• biz_cell_product 列表/详情中的 storageSlotName（_enrich_product_dicts 动态拼接）
• 生产任务产出/原材料展示（join 细胞产品 enrich）
• 库位占用弹窗标题
• 储物格下拉选项（storage-slot-options.ts）

4.4 级联服务伪代码

def cascade_refresh_slot_name_snapshots(db, *, changed_node_ids: list[str], tenant_no: str):
    affected_slot_ids = collect_slot_ids_under_nodes(db, changed_node_ids, tenant_no)
    if not affected_slot_ids:
        return 0
    facility_by_id = load_all_facilities_map(db, tenant_no)
    slot_full_map = {
        sid: build_full_slot_code(slot.facility_node_id, slot.slot_code, facility_by_id)
        for sid, slot in load_slots_by_ids(db, affected_slot_ids)
    }
    # 刷新 outbound_release_cell 快照
    updated = refresh_outbound_release_cell_slot_names(db, slot_full_map, tenant_no)
    return updated

4.5 格子本地编码变更

update_slot 当 slot_code 变化时，同样触发上述快照刷新（仅该 slot ID 范围）。

5. 后端 API

5.1 设施节点

方法	路径	变更
GET	/storage-facilities	返回增加 nodeCode
POST	/storage-facilities	请求体增加 nodeCode（必填）
PUT	/storage-facilities/{id}	可改 nodeCode；变更时级联刷新快照

CreateBody / UpdateBody 新增：

node_code: str = Field(..., alias="nodeCode", min_length=1, max_length=32)

校验错误文案：

• 格式非法：节点编号只能包含字母和数字，不能包含连字符
• 兄弟重复：同级节点编号已存在

5.2 储物格

方法	路径	变更
GET	/storage-facility-slots	每条增加 fullSlotCode
POST	/storage-facility-slots	响应含 fullSlotCode；slot_code 仍为本地坐标
PUT	/storage-facility-slots/{id}	同上；改 slot_code 时刷新快照
POST	/storage-facility-slots/batch	移除 codePrefix；本地编码 {row}-{col}

5.3 统一展示字段

_slot_to_dict 增加：

"fullSlotCode": build_full_slot_code(...)

_enrich_product_dicts 中 storageSlotName 由：

{node_name_path} / {slot_code}

改为：

{fullSlotCode}

可选：保留 storageSlotPath（名称路径）供 tooltip，非必须。

6. 前端（web-admin）

6.1 库位管理页

文件： web-admin/src/views/operations/storage-facility/index.vue

区域	变更
节点弹窗	新增「节点编号」表单项（必填）；hint：单段字母/数字，不含 -
左侧树	展示 [nodeCode] nodeName 或 nodeCode · nodeName
格子卡片	主文案显示 fullSlotCode（替代当前列序号 cellIndex+1）
批量生成	移除「编码前缀」；预览示例完整编号
格子编辑/占用弹窗	展示完整编号；本地坐标可编辑时仍编辑 slotCode（行-列）

货架行分组： 继续使用本地 slotCode 调用 parseSlotCode，不要对 fullSlotCode 做行/列解析。

6.2 储物格下拉

文件： web-admin/src/utils/storage-slot-options.ts

• mapSlotsToSelectOptions：name 改为 fullSlotCode
• 可选副标题：nodePath 作 title/tooltip

6.3 关联页面（只读展示同步）

以下页面无需改交互，随 API storageSlotName / 下拉 name 变更自动显示新格式：

• 细胞产品库 cell-product/index.vue
• 生产任务产出/原材料相关组件
• 出库放行物料选择

7. 历史数据迁移

文件： docs/sql/migrations/2026-06-17-storage-facility-node-code.sql

-- 1. 加字段（允许 DEFAULT '' 过渡）
ALTER TABLE biz_storage_facility
  ADD COLUMN node_code VARCHAR(32) NOT NULL DEFAULT '' COMMENT '节点编号（单段，不含连字符）'
  AFTER node_name;

-- 2. 存量补编号（需按租户人工确认后执行，示例按 order_num）
-- UPDATE biz_storage_facility SET node_code = LPAD(CAST(order_num + 1 AS CHAR), 2, '0') WHERE node_code = '' AND del_flag = 0;

-- 3. 补编号完成后，业务侧应禁止 node_code 为空的新增/编辑

-- 4. 刷新 outbound_release_cell 快照（部署后由后端脚本或一次性 SQL 执行，依赖新编号已补全）

迁移注意：

• 存量 slot_code 无需修改
• 补全 node_code 后，运行一次性脚本刷新 biz_outbound_release_cell.storage_slot_name
• 若某节点无法自动补编号，库位管理页编辑补录后再统一刷新

8. 校验与测试

8.1 单元/集成测试点

#	场景	期望
1	新建节点缺 nodeCode	400
2	nodeCode 含 -	400
3	同级重复 nodeCode	400
4	批量生成 4×6	fullSlotCode 为 {祖先}-{row}-{col}
5	修改层编号 2→5	其下所有 slot 的 fullSlotCode 前缀变化
6	修改层编号后	biz_outbound_release_cell.storage_slot_name 同步更新
7	修改格子 slot_code	关联 outbound 快照更新
8	细胞产品列表	storageSlotName 显示 fullSlotCode
9	下拉选格	选项文案为 fullSlotCode

8.2 回归页面

• /#/operations/storage-facility — 树、节点 CRUD、批量生成、格子展示
• 细胞产品库 — 储物格列、选格下拉
• 生产任务执行 — 产出选格
• 出库放行 — 储物格快照列

9. 不在范围

• 小程序端库位展示（若未来有）
• 生产物料库 storage_location 纯文本字段（不关联库位主数据）
• 物理标签重打流程（系统只保证数据一致，线下标签由业务自行处理）
• 将名称路径改为 - 分隔（名称路径仍用 /）

10. 实施文件清单

层级	文件	操作
SQL	docs/sql/migrations/2026-06-17-storage-facility-node-code.sql	新增
Model	backend/app/models/models.py	修改
Service	backend/app/services/storage_facility_code.py（或 crud 内）	新增
CRUD	backend/app/crud/storage_facility.py	修改
CRUD	backend/app/crud/cell_product.py	修改 _enrich 拼接
CRUD	backend/app/crud/outbound_release_material.py	可选：抽取共用刷新
API	backend/app/api/operations.py	修改 schema
前端	web-admin/src/views/operations/storage-facility/index.vue	修改
前端	web-admin/src/utils/storage-slot-options.ts	修改
前端	web-admin/src/api/admin.ts	类型字段补充

---

评审确认项： 若本设计无异议，下一步编写实施计划（docs/superpowers/plans/2026-06-17-storage-facility-node-code.md）并开始开发。