WMS 仓库管理主题（wms-2592）项目交接详细说明
一、项目概述
· 主题名称：wms-2592（基于 WordPress 自研仓库管理系统主题）
· 当前状态：已上线使用，功能相对完善，持续优化中
· 核心目标：实现产品管理、出入库记录、库存实时计算、预警、批量导入导出、二维码打印、用户权限、删除审批、库存盘点等功能。
二、文件结构
```
wms-2592/
├── style.css # 前端全部样式（白灰主题、响应式表格、打印样式）
├── functions.php # 核心功能：注册CPT/分类、库存事务、日志、性能缓存、加载inc模块
├── header.php # 导航栏（含用户登录状态）
├── footer.php # 页脚
├── inc/ # 模块目录
│ ├── export-templates.php # 导出模板及字段定义
│ ├── export-csv.php # CSV导出处理（支持日期筛选）
│ ├── settings.php # 仓库设置（登录Logo、访问控制、开放查看记录）
│ ├── user-permissions.php # 用户权限管理（出入库/查看记录/审批权限）
│ ├── import-products.php # 产品导入（含逐字段覆盖预览确认）
│ ├── table-settings.php # 前端表格列自定义（全局+用户个人）
│ ├── delete-requests.php # 删除申请审批（含库存恢复）
│ ├── user-center.php # 用户中心相关钩子（模板加载、保存列设置等）
│ ├── scan-stock.php # 扫码出入库页面注册
│ ├── qr-print-export.php # 二维码批量打印/导出（支持批量名称筛选）
│ ├── admin-product-list.php # 后台产品列表增强（列、筛选、排序）
│ └── inventory-check.php # 库存盘点（导入易飞CSV对比）
└── page-templates/ # 页面模板
├── products.php # 产品列表（搜索、筛选、排序、分页、CSV导出）
├── inbound-records.php # 入库记录（同产品列表功能）
├── outbound-records.php # 出库记录（同产品列表功能）
├── stock-alerts.php # 库存预警（使用缓存低库存ID）
├── warehouse-home.php # 今日汇总（统计卡片+最近记录）
├── product-detail.php # 产品详情（出入库操作、图片上传、二维码打印）
├── user-center.php # 用户中心（个人操作记录、删除申请、自定义列）
└── scan-stock.php # 扫码出入库（产品二维码列表）
```
三、自定义文章类型（CPT）与分类法
CPT
· wh_product：产品（支持标题、编辑器、缩略图，库存等 meta）
· wh_inbound：入库记录（禁止前端手动创建）
· wh_outbound：出库记录（禁止前端手动创建）
· wh_log：操作日志（无菜单，专用页面查看）
· wh_delete_request：删除申请（无菜单，审批用）
分类法
· product_cat：产品分类（层级）
· storage_location：存放位置（标签，用于产品）
· inbound_location：入库位置（标签，用于入库记录）
· outbound_location：出库位置（标签，用于出库记录）
四、关键 Meta 字段
产品 (wh_product)
· _wms_stock：当前库存（整数，默认0）
· _wms_low_stock_threshold：预警阈值（默认5）
· _wms_spec：产品规格（文本）
· _wms_product_code：产品编码（用于盘点匹配）
· _wms_signature：签名图片URL（可选）
· _wms_doc_image：单据图片URL（可选）
· _wms_location2：库位（备用字段）
出入库记录 (wh_inbound/wh_outbound)
· _wms_product_id：关联产品ID
· _wms_quantity：数量（正数）
· _wms_operator：操作人用户名
· _wms_date：操作时间戳
· _wms_balance：操作后结存
· _wms_note：备注
· _wms_customer_note：客户备注（仅入库）
· _wms_customer_note_image：客户备注图片（仅入库）
· _wms_signature / _wms_doc_image：图片
· _wms_location2：库位
操作日志 (wh_log)
· _wms_log_user_id、_wms_log_username
· _wms_log_action、_wms_log_description
· _wms_log_time
· _wms_log_product_id、_wms_log_quantity、_wms_log_balance
· _wms_log_record_id：关联的出入库记录ID（用于删除申请）
五、核心函数索引（重要）
functions.php
· wms_register_post_types() / wms_register_taxonomies()
· wms_get_product_stock() / wms_update_product_stock()
· wms_get_low_stock_threshold()
· wms_add_log()：写日志
· wms_handle_stock_forms()：处理出入库表单（使用事务和行锁）
· wms_recalculate_product_balances($product_id)：重算产品所有记录的结存（删除记录后调用）
· wms_get_low_stock_product_ids()：性能优化，使用SQL直接查询低库存产品ID，带缓存
· wms_ensure_stock_meta_exists()：确保产品库存meta存在
inc/export-csv.php
· wms_export_csv()：导出CSV，支持 inbound、outbound、products 类型，已修复日期筛选
inc/import-products.php
· 导入产品：支持字段级覆盖，预览后勾选确认，已修复缓存问题
inc/delete-requests.php
· wms_process_delete_request()：审批删除，已修复库存恢复和结存更新
inc/admin-product-list.php
· 后台产品列表添加列：库存、分类、规格、编码、日期，库存状态筛选
inc/inventory-check.php
· 库存盘点：上传易飞CSV，对比系统库存，勾选调整
六、重要设计要点
1. 并发安全
· 在 wms_handle_stock_forms() 中，使用 START TRANSACTION + SELECT ... FOR UPDATE 锁定产品库存行，防止超卖。
· 所有库存更新前检查 _wms_stock 行是否存在，确保新产品初始化。
2. 删除记录后的数据一致性
· 永久删除（before_delete_post）或审批删除（wms_process_delete_request）后，调用 wms_recalculate_product_balances($product_id) 重新计算所有记录的结存，并更新产品当前库存。
· 该函数按时间顺序累加/扣减，确保结存正确。
3. 二维码保持不变
· 绝对不能修改 wms_get_qr_image_url() 函数中的 $qr_data 生成逻辑。
· 二维码内容 = product-detail 页面链接 + ?product_id=产品ID
· 已打印的二维码继续有效。
4. 性能优化
· wms_get_low_stock_product_ids() 使用SQL直接比较两个meta字段，避免循环所有产品。
· 产品库存和阈值有对象缓存（wp_cache）。
· 导入时使用 wp_suspend_cache_invalidation(true) + 定期 wp_cache_flush()，提高大批量导入速度。
5. CSV导出
· 导出链接携带当前表格列（fields 参数），CSV列与页面显示一致。
· 支持日期范围、分类、排序等筛选条件。
6. 用户权限
· 后台仅管理员可访问（wms_restrict_admin_access）。
· 前端用户权限通过 user_meta 控制：wms_permissions（数组，可能包含 inbound/outbound）、wms_approve_permission、wms_view_inbound_permission、wms_view_outbound_permission。
七、已实现但可能需优化的点
1. 分类筛选性能：在出入库记录页面，按产品分类筛选时先用 get_posts 获取该分类下所有产品ID，再用于 meta_query，产品数量大时可能较慢。可考虑使用SQL JOIN。
2. 二维码导出PDF：仍是HTML预览方式，用户通过浏览器打印另存为PDF。没有真正的PDF生成库。
3. 用户中心“删除记录”标签：用户只能申请删除，无法直接查看自己已删除的记录（回收站中的记录）。未实现。
4. 后台产品列表库存筛选：已使用 posts_where 钩子实现低库存/正常/零库存筛选，可测试是否正常。
5. 移动端导航：导航栏在小屏幕可能拥挤，可添加汉堡菜单。
6. 数据备份：无自动备份机制，建议定期手动备份数据库和文件。
八、下一步工作建议（按优先级）
1. 继续修复用户反馈的具体问题（如导出、分页、筛选等）。
2. 实现用户中心“删除的记录”标签，展示已删除记录（含审批信息）。
3. 优化分类筛选性能（使用自定义SQL或缓存产品分类关系）。
4. 集成真正的PDF生成库（如 Dompdf / TCPDF）用于二维码PDF导出。
5. 增加报表统计图表（如每日出入库趋势）。
6. 完善移动端体验。
九、对接注意事项
· 请务必保留二维码生成逻辑不变。
· 修改任何文件后，建议测试导入、导出、出入库、删除审批、盘点等关键流程。
· 注意缓存清理：更新产品库存后需清除 product_stock_ 和 wms_low_stock_ids 缓存。
· 所有后台新增子菜单均挂在 edit.php?post_type=wh_product 下。
十、当前未完成但用户曾提及的需求
· 用户中心增加“删除的记录”标签，可查看自己删除的记录及审批状态。
· 库存盘点功能已添加，但用户可能未看到菜单（需确认 functions.php 已加载 inc/inventory-check.php）。
· 后台产品列表已增强，但筛选功能可能需进一步调整。
---
以上是完整的项目交接文档，新窗口对话时，请直接粘贴此文档，并告知要处理的具体问题，我将立即继续协助。
文章末尾固定信息
