被控端（仓库管理系统）开发文档

1. 架构总览

┌─────────────┐        授权 / 公告 / 版本更新        ┌──────────────────┐
│  主控端       │  ───────────────────────────────▶  │  被控端（仓库）    │
│ （平台 / 管控）│  ◀───────────────────────────────  │  （业务 / 仓储）   │
└─────────────┘   版本上报 / 反馈上报 / 升级日志       └──────────────────┘

• 主控端：负责“管控面”——授权签发、版本发布与逐级下发、公告多系统下发、意见反馈归集。对外提供标准 HTTP 接口（如 api/version.php）。
• 被控端：负责“业务面”——物料、库存、盘点、统计大屏等仓储作业，以及本地业务数据。通过接口与主控协同，支持在线逐级更新。

关键契约

• 被控端 api/check_update.php 上报 from=当前版本，主控仅返回“下一级”版本。
• 被控端 api/do_update.php 下载、校验、复制补丁并写入新版本号，可一次请求内逐级循环到最新。
• 补丁包内含 manifest.json，其 from_version 做跳版本硬校验（不允许跨版本直更）。

2. 技术栈与运行环境

3. 目录结构

被控端/
├─ index.php              入口（前端页面路由）
├─ login.php / logout.php 登录登出
├─ dashboard.php          首页仪表盘（含「物料 0 库存」KPI）
├─ statistics.php         统计大屏 / 概览
├─ settings.php           系统设置（主控接入、开发者模式）
├─ feedback.php           意见反馈
├─ install.php / install.sql   安装向导与建表脚本
├─ _router.php            php -S 开发路由（仅开发用）
├─ api/
│  ├─ check_update.php    检查更新（上报 from=当前版本）
│  ├─ do_update.php       在线更新（逐级循环升级引擎）
│  ├─ feedback_*.php      反馈提交/回复/删除/同步
│  └─ master_guard.php    主控接入守卫
├─ includes/
│  ├─ config.php          ⚠️ 数据库凭据与环境配置（受保护，更新不下发）
│  ├─ defs.php            ✅ 应用级常量/函数（可随更新下发）
│  └─ ...
├─ warehouse/             仓储业务（导入导出依赖 vendor/autoload.php）
├─ users/                 用户/员工
├─ storage/               运行时：上传、日志、更新备份（不上发、不发布）
├─ uploads/               运行时上传目录
├─ vendor/                第三方依赖（必须保留）
└─ manifest.json         当前版本清单（由发布脚本生成）

两个配置文件的分工（非常重要）

4. 配置系统

includes/config.php 关键常量：

define('DB_HOST', '127.0.0.1');
define('DB_USER', 'wg_app1');
define('DB_PASS', 'App1#2026');
define('DB_NAME', 'wg_app1');
define('DB_PORT', 3306);

define('SITE_NAME',     '出入库管理系统');
define('SITE_VERSION', '1.3.5');

define('STORAGE_DRIVER',   'local');   // local | cos
define('LOCAL_UPLOAD_DIR', __DIR__ . '/../uploads');
define('LOCAL_UPLOAD_URL', '/uploads');

• 支持 config_override.php（若存在则被 require_once，用于环境差异覆盖）。
• 文件末尾 require_once __DIR__ . '/defs.php'; 引入应用级定义。
• 版本号有两个来源：SITE_VERSION 常量（代码内置）与 app_version() 设置项（数据库，更新成功后由 save_setting('app_version', …) 写入）。显示/更新判断以设置项为准；若设置项缺失则回退常量。

5. 在线更新机制（核心）

5.1 角色

5.2 被控端 do_update.php 主流程（逐级循环）

POST api/do_update.php（仅超级管理员）
  └─ while 未到最新 且 步数 < 上限:
       1. 拼装更新源地址（与 check_update 一致），追加 from=当前版本
       2. fetch version.php → 得到下一级 {version, download_url, from_version}
       3. 下载 zip → 解压到临时目录
       4. 读取 manifest.json，硬校验 manifest.from_version === 当前版本
          （不等 → 拒绝“跳版本”，返回友好提示）
       5. 遍历文件复制（带备份），跳过 $block 受保护文件
       6. save_setting('app_version', 下一级版本) → 写日志 → 上报主控升级日志
       7. 当前版本 = 下一级，进入下一轮循环
  └─ 返回：{ok:true, steps, path:[...], version:最新}

5.3 受保护文件（$block）

更新复制阶段不会覆盖以下文件（避免冲掉环境与凭据）：

$block = [
  'includes/config.php',
  'includes/config_override.php',
  'install.lock',
  '.env',
  'composer.lock',
];

5.4 补丁包 manifest.json 示例

{
  "version": "1.3.5",
  "from_version": "1.3.4",
  "changelog": "新增物料 0 库存统计（首页/统计大屏/概览）。",
  "generated_at": "2026-07-30"
}

6. 发布补丁流程

补丁构建脚本：发布包/build_chain.php，产出 发布包/chain_x.x.x_to_y.y.y/。

6.1 两种补丁类型

• 桥接补丁（如 1.3.0→1.3.1）：仅含“链式三件套” includes/defs.php + api/do_update.php + api/check_update.php + manifest.json。用于让旧版本获得逐级升级能力并推进版本号。
• 完整树补丁（如 1.3.3→1.3.4、1.3.4→1.3.5）：完整程序树（排除 storage/vendor 运行缓存等）+ 叠加三件套。保证到达该版本时为完整且正确的程序状态。

6.2 文件命名

补丁 zip 使用 ASCII 文件名（如 slave_1.3.0_to_1.3.1.zip）。部分服务器对中文名 zip 下载会返回 0 字节 / 404，务必避免中文名。

6.3 校验

• 发布包/lint_chain.php：自包含 PHP（ZipArchive 解压 + php -l）对全部补丁内 php 文件做语法检查。
• 发布包/verify_chain.php：校验各 manifest 与文件名一致、链式引擎存在、模拟 version.php 链无跳版、关键特性（如 0 库存 KPI）就位、无混淆残留。

6.4 发布到主控

1. 将 5 个补丁 zip 上传到主控 uploads/。
2. 后台「产品更新 / 版本」依次新建已发布记录：版本号 name 与下载文件 file（指向 uploads/slave_*_to_*.zip）。
3. 修复版 api/version.php 已使无 from 兜底返回最低已发布版本（旧客户端自举必需）。

7. 接口契约（摘要）

8. 部署

8.1 全新安装

1. 将完整安装包解压到 Web 根（保留 vendor/）。
2. 确保 storage/、uploads/ 可写。
3. 浏览器访问 install.php → 按向导填写数据库信息（建库后用 install.sql 建表；导入前 SET FOREIGN_KEY_CHECKS=0 避免外键顺序报错）。
4. 安装完成生成 install.lock。

8.2 多实例（同机多仓库）

每个被控端实例使用独立端口 / 独立库 / 独立用户 / 独立 Session 目录，避免串号：

php -S 127.0.0.1:8083 -d session.save_path=/tmp/sess_wg_app1 _router.php
php -S 127.0.0.1:8084 -d session.save_path=/tmp/sess_wg_app2 _router.php
# 各自 includes/config.php 指向独立库 wg_app1 / wg_app2 ...

8.3 在线更新（用户侧）

后台「系统设置 → 检查更新」→ 显示可升到的下一级 → 「立即更新」。新引擎下一次请求内自动逐级走到最新。

9. 二次开发指南

9.1 新增一个业务页面

1. 在根目录或业务目录新建 xxx.php，顶部 require_once 公共头（含 config.php/defs.php 与登录校验）。
2. 复用现有 requireLogin() / requirePermission() 做权限控制（定义在 includes/config.php）。
3. 模板风格参考 dashboard.php / statistics.php。

9.2 新增一个 API

1. 在 api/ 下新建 api/xxx.php，开头 requireLogin() + 角色校验。
2. 返回 JSON 时统一 header('Content-Type: application/json; charset=utf-8'); echo json_encode(..., JSON_UNESCAPED_UNICODE);。

9.3 新增应用级常量 / 函数

• 必须放入 includes/defs.php（或新建独立可下发文件并在各处 require_once），切勿写入 config.php。
• defs.php 顶部有 if (defined('DEFAULT_MASTER_URL')) return; 防御重复加载，新增定义无需重复该守卫。

9.4 资源与静态文件

• 上传文件走 LOCAL_UPLOAD_DIR（本地）或 COS（配置 STORAGE_DRIVER='cos'）。
• 不要在被下发文件中引用会被 $block 排除的路径（config.php 等）。

10. 常见问题