ShiErFeng/readmeupdate.md

智链云枢 Web 端改版 · 修改记录

本文记录在提交 80a71b4（添加前后端筛选导出excel按钮权限）之后所做、尚未提交的全部改动，说明每项改了什么、为什么改。

• 改动范围：后端 shierfeng-fastapi-backend、前端 shierfeng-fastapi-frontend。
• 未改动：小程序 shierfeng-fastapi-app、登录页 src/views/login.vue 及 Logo 资源、shierfeng-fastapi-backend/.env.dev（该文件的改动是原有的，不属于本次工作）。
• 总原则：后端只新增只读查询、扩展列表和详情的返回字段；所有写接口、托盘状态机和幂等键规则都没有改。新增的关联查询都沿用原接口的数据范围（仓库 / 现场授权），并受同一测试批次范围约束。没有新增权限标识，也不需要改菜单。
• 规模：已跟踪文件 85 个改动（约 +14,400 / −2,500 行），新增文件 37 个（不含本文件）。

改动分几轮完成，顺序如下：

轮次	内容
1	全局外壳与导航、工作台、托盘档案、各页统一页头
2	发货出库页、侧边栏用户卡片、托盘追溯入口
3	基础资料维护：托盘、客户、仓库、导入、分配用户，以及菌种、现场、产线、隧道
4	客户、仓库指标条；7 个新增 / 编辑对话框
5	业务管理：共用部分（第 0 步）、仓库入库
6	退回仓库
7	工厂装填（同时修复入库页扫码反馈不显示的问题）
8	客户现场使用

---

一、后端（shierfeng-fastapi-backend）

1. 新增接口一览

全部为 GET、只读。

接口	权限	用途
/master/site/customer-options	master:site:list	新增 / 编辑现场时选择所属客户
/master/line/site-options	master:line:list	新增 / 编辑产线时选择所属现场
/master/tunnel/site-options	master:tunnel:list	新增 / 编辑隧道时选择所属现场
/business/inbound/summary	business:inbound:list	入库页指标：草稿单数与托数、本月入库、待首次入库托盘、各仓库空托盘
/business/return/summary	business:return:list	退回页指标：待核对单数与托数、退回中带料托数与包数、本月确认与回仓去向、平均确认耗时
/business/return/site-options	business:return:list	退回页的来源现场筛选与名称显示
/business/filling/summary	business:filling:list	装填页指标：今日与本月装填、可装填空托盘、14 天内到期仍在仓的托盘
/business/filling/batches	business:filling:list	按「菌种 + 生产批次」汇总装填（分页，最近装填的在前）
/business/filling/batches/detail	business:filling:query	批次详情：托盘当前去向分布与最近 10 条装填
/business/usage/site-options	business:usage:list	现场使用页的现场选择器（附隧道数、产线数）
/business/usage/site-board?siteId=	business:usage:query	现场看板：库存、今日用量、隧道在用情况、跳过先到次数（不返回内部溯源号）
/business/usage-fifo/queue?siteId=	business:usage:query	现场待使用托盘按菌种分组，顺序与先到先用建议一致

另外，基础资料的各个导入接口新增参数 preview=true，表示「只校验、不写入」，权限不变。

2. 扩展的已有接口

返回结构只增加字段，不删除、不改名。

接口	新增内容	目的
基础资料各列表（菌种 / 客户 / 现场 / 产线 / 隧道 / 仓库 / 托盘）	名称、统计数、分配用户等汇总字段	页面显示名称而不是 ID，并提供指标数字
客户详情	现场树：产线、隧道、各状态托盘数、分配用户	客户页右侧详情面板
托盘列表	flowGroup 参数（未入库 / 仓库 / 在途 / 现场 / 退回中）；托盘号参数同时精确匹配二维码标识	托盘页的状态页签，以及扫码枪搜索
托盘详情	最近流转记录	托盘侧边面板
发货列表	keyword、receiptState 参数；仓库、现场、客户、创建人名称，托盘数、包数、菌种构成	发货页的统一搜索、状态页签和路线显示
发货详情	明细补托盘号、菌种、批次	详情面板；也修复了编辑对话框只显示 #123 的问题
入库列表 / 详情	仓库、创建人、确认人名称，托盘数；明细补托盘号和当前状态	入库页列表与详情面板
退回列表 / 详情	keyword 参数（单号、托盘号、现场、客户、仓库）；来源现场、客户、目标仓库、申请人、确认人名称，托盘数、余量包数、带料托数；明细补托盘号和隧道名称	退回页列表、详情和到仓核对
装填列表	keyword 参数（装填单号、托盘号、批次）；托盘号、仓库、操作人名称	装填明细视图
使用记录列表	keyword（记录号、托盘号）、fifoSkipped 参数；托盘、现场、隧道、产线、操作人名称，以及被跳过的先到托盘号（取自写入时已保存的先到先用快照）	使用记录表和「只看跳过先到」开关

3. 按文件说明

新增文件

文件	说明
dao/master_summary_dao.py、service/master_summary_service.py、entity/vo/master_summary_vo.py	基础资料列表汇总、客户现场树、托盘最近流转、上级资料选项、导入预览模型
dao/shipment_summary_dao.py	发货列表名称、托盘数、包数与菌种构成
dao/inbound_summary_dao.py	入库列表名称与托盘数、明细托盘号与状态、页面概况
dao/return_summary_dao.py	退回列表汇总、明细托盘号与隧道、来源现场选项、页面概况
dao/filling_summary_dao.py	装填列表名称、批次汇总与详情、页面概况
dao/usage_summary_dao.py	使用记录名称、现场选项、现场看板

修改文件

文件	修改内容
controller/*_controller.py（菌种、客户、现场、产线、隧道、仓库、托盘）	列表和详情改用带汇总的返回模型；现场、产线、隧道新增上级选项路由，单独注册并排在 /{id} 详情路由之前，避免被详情路由误匹配
controller/master_excel_controller.py、service/master_excel_service.py	导入支持 preview：执行与真实导入相同的校验后整体回滚，返回逐行的新增 / 更新 / 跳过 / 错误结果
dao/master_dao.py、entity/vo/master_vo.py	托盘列表的 flowGroup 过滤与二维码精确匹配
controller/shipment_controller.py、service/shipment_service.py	发货列表汇总与筛选、详情明细补充字段
controller/inbound_controller.py、service/inbound_service.py	入库列表与详情补充字段，新增 /summary
controller/return_controller.py、service/return_service.py	退回列表与详情补充字段，新增 /summary、/site-options
controller/filling_controller.py、service/filling_service.py	装填列表补充字段，新增 /summary、/batches、/batches/detail
controller/usage_controller.py、service/usage_service.py	使用记录列表补充字段，新增 /site-options、/site-board
controller/usage_fifo_controller.py、service/usage_fifo_service.py	新增 /queue。原来权限写在路由组上，现改为每个接口各自声明（同为 business:usage:query），以符合「每个接口一个权限声明」的契约测试，实际效果不变
dao/usage_fifo_dao.py	把先到先用的候选条件、关联和排序抽成公共方法，供建议和队列共用，保证两边顺序一致。已逐条比对：改动前后建议查询（含写入时的加锁复核）在 12 种参数组合下生成的 SQL 完全相同
dao/operation_dao.py	发货、退回、装填、使用记录列表的 keyword 等筛选条件。原排序（按 ID 从旧到新）未改
entity/vo/operation_vo.py、entity/vo/usage_fifo_vo.py	上述列表行、概况、看板、队列等新模型；查询模型新增 keyword、fifoSkipped 等字段

4. 测试（tests/module_business）

• 新增：test_master_summary.py、test_shipment_list_summary.py、test_inbound_summary.py、test_return_summary.py、test_filling_summary.py、test_usage_summary.py；另在 test_usage_fifo.py 增加 3 条待使用队列测试（内存数据库，实际执行查询）。覆盖内容为数据范围、测试批次隔离、SQL 条件，以及返回字段的驼峰命名。
• 同步更新（接口变更是有意为之）：
  • test_api_permission_contract.py：登记新路由、权限映射、静态路由在详情路由之前、查询参数，路由权限条目从 119 条增至 131 条；
  • test_vo_contract.py：新模型和新字段；
  • 各 test_*_service.py：路由列表、返回模型，以及对新汇总查询的模拟。
• 结果：PYTHONPATH=. python -m unittest 运行 tests/module_business 下全部用例，共 843 条，全部通过（2 条跳过）。

---

二、前端（shierfeng-fastapi-frontend）

1. 全局外壳与导航

文件	修改内容与目的
layout/index.vue、layout/components/AppMain.vue、Navbar.vue、TagsView/index.vue	新版外壳：内容区为白色内嵌面板，顶栏更简洁；手机宽度可用
layout/components/Sidebar/index.vue、SidebarItem.vue、Logo.vue	浅色侧边栏、分组菜单、统一图标，使用官方 Sylvan Logo
layout/components/Sidebar/UserCard.vue（新增）	侧边栏左下角显示当前用户的头像、姓名、部门 · 角色，点击打开 个人中心 / 布局设置 / 退出登录；侧边栏折叠时只显示头像
layout/components/CommandPalette/index.vue（新增）	Ctrl / ⌘K 搜索面板：输入页面名称直接跳转，输入托盘号打开托盘档案
layout/components/TestModeBanner/index.vue（新增）	测试数据模式下页面顶部显示琥珀色提示条，可直接退出测试批次
assets/styles/sf-shell.scss（新增）、index.scss、sidebar.scss、variables.module.scss	设计令牌（颜色、圆角、阴影），深色模式有单独配色；全屏作业区、分段切换、批量操作栏等共用样式
settings.js	默认浅色侧边栏、默认关闭页签栏。已保存过「布局设置」的用户仍沿用自己的设置
store/modules/user.js	读取部门名和角色名，供用户卡片使用
router/index.js、components/Breadcrumb/index.vue	「首页」改称「工作台」；新增托盘档案路由 /pallet/passport，需要托盘追溯权限
main.js	全局注册 PageHeader、PalletCodeLink、DocNo

2. 新增的共用组件与工具

文件	用途
components/PageHeader（含 descriptions.js）	统一页头：标题、页面说明、右侧操作区；业务页用 flow 属性显示托盘流程条
components/FlowStepper	托盘流程 1 入库 → 2 装填 → 3 发货 → 4 现场使用 → 5 退回，高亮当前环节；没有菜单权限的环节只显示、不能点
components/ScanFeedback	扫码结果条，分成功、提醒、拒绝、等待等状态，屏幕阅读器会播报
components/DocNo、utils/docNo.js	长单号缩短显示（如 SH-9F2C…E41B），鼠标悬停显示完整单号
components/PalletCodeLink	托盘号链接到托盘档案；没有权限时显示为纯文本
components/SfIcon（含 icons.js）	统一线性图标，路径只取自本地常量表
components/MasterRefSelect	可搜索的上级资料选择框（所属客户 / 所属现场）
assets/styles/sf-master.scss	指标条、状态页签、筛选行、列表加详情面板、时间线、状态胶囊等样式，基础资料页和业务页共用
utils/masterDisplay.js	数字格式化、天数计算、状态胶囊样式、按路由末段查找菜单路径
utils/masterRouteIntent.js	基础资料页之间的跳转意图（如从客户详情跳到现场页并带上所属客户）；一次性意图处理后从地址栏移除，刷新不会重复触发
utils/palletPassport.js	托盘流转状态的中文名称与阶段分组
utils/palletRanges.js	把连续托盘号合并成编号段；解析批量粘贴的内容，支持 10512-10518 这类区间写法

3. 工作台、托盘档案、托盘追溯

• views/dashboard/index.vue 工作台：扫码 / 搜索栏、4 个关键指标、托盘 8 种状态的流转看板（点击某个状态可查看托盘）、装填与发货对比图、待办、临期托盘、仓库库存、最近动态。全部数据来自已有接口。同时修复了「最近出库单」实际显示的是最早单据的问题（后端列表按从旧到新排序）。
• views/pallet/passport/index.vue 托盘档案（新增）：当前状态、位置、余量、有效期，本轮流转进度条，所有变动的时间线（往轮折叠），以及同一溯源号的其他托盘。
• views/report/palletTrace/index.vue 托盘追溯：顶部新增「查看单个托盘档案」入口，下方保留原来的跨托盘流转明细查询。
• 其余 5 个报表页：加统一页头，托盘号可点击打开托盘档案；查询逻辑没变。

4. 基础资料维护页

页面	修改内容
托盘资料 master/pallet	指标条；状态页签带数量；搜索框也支持扫码；每行显示当前位置、余量和周转次数；侧边面板含二维码标签、最近流转、打印 / 编辑 / 停用；勾选多行后可批量打印标签或停用
客户资料 master/customer	客户列表加详情面板，每个现场展开后显示产线、隧道、各状态托盘数和分配用户；「新增现场 / 分配」等按钮跳到对应页面并带好上级
仓库资料 master/warehouse	卡片 / 列表切换；显示库存、今日装填与发货、待处理单据、7 天内到期托盘、分配用户
菌种、现场、产线、隧道	显示名称而不是 ID，加指标条（多数指标只统计当前页，会标「本页」）和近期使用情况
7 个新增 / 编辑对话框	统一布局；状态做成两张说明卡，写明选择后的影响（已与后端校验逐条核对）；所属客户 / 现场改为可搜索列表，只列启用的上级，加载失败时退回原来的 ID 输入；托盘容量固定显示 100 包；编辑托盘时托盘号和二维码标识只读
components/MasterExcelActions 批量导入	改为三步：选择文件 → 校验预览（逐行显示新增 / 更新 / 跳过 / 错误，错误行可下载 CSV）→ 正式导入。导入请求现在会带上测试批次请求头（原来的上传绕开了统一请求层，不会带）
components/BusinessUserAssignDialog 分配用户	支持筛选和头像，用户旁标注「将新增 / 将移除」，并汇总本次变化
api/master/site.js、line.js、tunnel.js	新增上级选项接口的调用

5. 业务管理页

各页都只改界面和读取方式。写入流程原样保留：提交前的复核、幂等键、防串单的请求代次、确认前重新读取详情等。

发货出库 business/shipment

• 状态页签带数量：全部 / 草稿 / 待收货 / 已收货 / 历史单据。
• 一个搜索框覆盖单号、仓库、客户和现场，另加创建时间筛选；原来的仓库ID、现场ID 输入框去掉。
• 列表显示路线名称（成品一仓 → 金禾菌业 · 南厂）、托盘数与包数、菌种构成，超过 48 小时未收货会标出。
• 点一行打开详情面板：打印标签、编辑、确认发货，以及 创建 → 确认 → 收货核对 的进度线。
• 「发货单 / 收货核对」改为页头切换；扫码在全屏作业区进行。

仓库入库 business/inbound

• 指标条，全部 / 草稿 / 已确认 页签，按仓库和创建时间筛选，草稿等待 2 天以上会标出。
• 详情面板：时间线、编号段、托盘当前状态。
• 批量确认：逐张确认，每张用自己的幂等键，中途失败就停下。
• 作业区可切换「逐个扫码 / 批量粘贴」，粘贴支持区间写法，按编号段汇总便于核对实物，被拒托盘写明原因；确认后显示结果和「去工厂装填」链接。
• 修复：作业区扫码反馈条之前一直不显示（见下方「测试脚本」中的说明）。

工厂装填 business/filling

• 指标条；「按生产批次 / 装填明细」两种视图。
• 批次视图显示有效期剩余天数；批次面板显示托盘去向分布、最近装填，可「沿用此批参数继续装填」，有效期剩余不超过 14 天时禁用。
• 全屏装填工位：
  • 先填写并锁定本批参数，锁定后才能扫码；有效期提供 +30 / +45 / +60 天快捷按钮，每托固定 100 包；
  • 「扫码后确认 / 扫码即装填」两种模式；
  • 「本班装填」列表和未装填的扫码记录；结束本班后显示结果和「去发货出库」链接。
• 每次扫码都先清空上一托的提交内容和幂等键，锁定的批次参数另外保存，扫码成功后再带入。

客户现场使用 business/usage

• 页头：现场选择器（按账号记住上次选择，只在主动切换时保存）和「开始现场作业」按钮。
• 看板：4 个指标；隧道卡片（点击按隧道筛选记录，再点取消）；按菌种分页签的待使用队列，第一托标「建议优先」，并注明未登记到场时间的托数。
• 记录表：按关键字、隧道、产线、时间筛选，有「只看跳过先到」开关；显示被跳过的托盘号和原因；原来的现场ID、隧道ID、产线ID 输入框去掉。
• 全屏作业区分 4 步：扫码 → 确认托盘 · 入隧 → 登记用量 → 完成。
  • 第 2 步：有更早到场的托盘时可一键「改用」它，或选择跳过原因快捷项再补充说明；隧道用卡片选择。
  • 第 3 步：快捷包数 10 / 20 / 50 / 全部，实时显示提交后余量；托盘已绑定产线时产线锁定。
  • 完成后可扫描下一托或继续使用这一托；托盘用完时给出退回仓库的链接。
  • 有未确认的操作时，第 1 步显示恢复卡片并锁住扫码，页顶横幅也保留。
• 步骤只是从现有状态推导出来的。原有 34 个函数中 33 个一字未改，只有 resetQuery 增加了清空日期筛选。待确认记录的本机存储键和格式、恢复重试、人工解除、先到先用拒绝的处理都保持原样。
• 页面不显示内部溯源号：原有测试规定作业页不能出现溯源号，溯源号只在托盘追溯报表里查看。

退回仓库 business/return

• 去掉页面顶部的两张操作卡。页头放「发起退回申请」，待确认的行和详情面板放「到仓核对」。
• 指标条，全部 / 待确认 / 已确认 页签，按关键字、来源现场、目标仓库、申请时间筛选。
• 列表显示「现场 → 仓库」和「托数 · 余量」；详情面板显示确认后去向（几托带料回有料库存、几托成为空托）。
• 到仓核对作业区：进度 n/N、方块网格（扫到一托亮一格，可撤销），非本单托盘单独列出；全部对上之前「确认退回」按钮不能点。
• 发起申请作业区：来源现场由第一个托盘锁定并显示名称；被拒托盘写明后端原因。

业务 API：api/business/inbound.js、return.js、filling.js、usage.js 增加上述新接口的调用。

6. 测试脚本（scripts/）

• 新增：pallet-ranges.test.mjs（8 条）、return-behavior.test.mjs（7 条）、filling-behavior.test.mjs（7 条）。后两个在 Node 中加载真实页面，只替换网络层。
• usage-behavior.test.mjs：
  • 补充新组件的替身和新只读接口的默认响应。看板默认不带隧道，避免它的隧道名称让摘要断言白白通过。
  • 新增 6 条测试：现场偏好、看板权限、隧道筛选、作业步骤、快捷包数、先到先用快捷原因。
  • 有一条原断言用「最后一个请求」去找扫码请求；页面启动后还会读看板，所以改为按路径取最近一次扫码请求，对编码后地址的精确比对没变。
• filling-dates.test.mjs：只为页面启动时新增的读取接口补了替身，断言没动。
• verify-business-contract.mjs：
  • 登记新接口，请求总数 74 → 86，并更新各页的 API 名称清单；
  • 新增检查「导入的组件不被同名状态变量遮蔽」。原因：入库页曾有变量 scanFeedback 与组件 ScanFeedback 同名，模板编译时选中了变量，导致扫码反馈条一直不显示。这个问题已修复，此检查防止再出现。
• verify-dashboard-contract.mjs：工作台文案变了，更新了必需文案列表；接口和路由检查不变。
• package.json：test:business 加入 pallet-ranges.test.mjs。
• 结果：npm run test:business 共 278 条，通过 260 条。失败的 18 条在本次改动之前就存在，与本次无关：
  • 17 条是小程序测试，shierfeng-fastapi-app 未安装依赖，报找不到 vue；
  • 1 条版权检查要求公司名为 "Shierfeng"，而已提交的 settings.js 中是 "Sylvan"。
• npm run build:prod（即 vite build）通过。

---

三、其他

开发库演示数据（不在代码仓库内）

为便于查看页面效果，在开发库中写入了一批演示数据：

• 数据性质：正式数据（test_batch_id 为空），切换模式后也能直接看到。
• 生成方式：调用真实业务服务生成，模拟时间为 2026-09-01 至 2026-10-17。
• 主数据：
  • 菌种 6 个（T09 停用）；
  • 仓库 3 个：成品一仓、成品二仓、周转仓；
  • 客户 4 个，现场 4 个：金禾菌业 南厂、北厂，绿源农业 一号基地，丰登食用菌合作社 东区；
  • 产线 9 条，隧道 12 条；
  • 托盘 TP-10401–TP-10720（TP-10720 停用）。
• 业务单据：
  • 入库单 8 张（6 张已确认、2 张草稿）；
  • 装填记录 309 条，分属 15 个批次；
  • 发货单 14 张：11 张已收货、2 张在途、1 张草稿；
  • 入隧 152 次，使用记录 496 条，其中 13 条跳过先到；
  • 退回单 8 张：5 张已确认、3 张待确认。
• 账号授权调整：
  • niangao（id 2）：成品一仓、成品二仓、南厂、北厂；
  • test（id 102）：成品二仓、周转仓、一号基地、东区。
• 注意：生成脚本放在临时目录，不在仓库中，重复运行会重复生成业务单据；如需清除，只能手工执行 SQL。

设计稿

各页面的设计稿在：https://claude.ai/artifact/2aJi4pKkw9vMnepsNLFax9

与设计稿或计划不同之处

• 导出按钮：业务页都没有「导出 Excel」，因为契约测试不允许业务页出现导入 / 导出按钮。
• 现场使用页的溯源号：不显示，原因见上文。
• 新建的入库草稿不能在作业区一步确认：新增接口不返回单据 ID。目前是保存后在草稿页签里确认；编辑已有草稿时有「保存并确认」。
• 装填：本班列表不显示装填单号（新增接口不返回）；沿用批次只带入参数，不自动锁定。
• 待使用队列：只按 siteId 查询，一次返回该现场所有菌种的分组。
• 字体：使用系统字体。Geist 字体包未安装（当时无法访问 npm 源），以后安装 @fontsource-variable/geist 即可生效。

待确认事项

1. 入库新增接口是否返回新单据 ID：返回后新建草稿就能一步确认，但这需要改写接口。
2. 列表排序是否改为新的在前：入库、退回、装填明细、使用记录等列表目前从旧到新排列，新单据会落在最后一页。
3. 手工验收：页面只用自动化测试和本地模拟接口验证过，尚未用真实账号在浏览器里逐页走查。建议走查：
   • 草稿到确认；
   • 扫码被拒；
   • 断网后重试不重复扣减（装填、现场使用、退回确认）；
   • 测试批次数据隔离；
   • 无权限账号看不到对应按钮。