PhoneHub + Pulse Phone — 安装指南

该版本整合了 Pulse Phone、PhoneHub 建筑、定制的 PhoneHub OS、3D 手机自助终端、维修工作台，以及员工库存/配送系统。它是与仅手机版分开的产品。请同时安装手机和门店资源。不要运行两份 phone，也不要运行两个版本的 PhoneHub 地图。

1. 安装之前

• 备份你现有的手机资源、地图资源、配置和数据库。
• 使用 OneSync 和 2699 或更新的 GTA 游戏版本。
• 先启动数据库、框架、背包、语音资源和 screenshot-basic。
• 资源名称必须严格保持为 phone 和 zerodev_phonehub_mlo。
• 从当前使用的资源目录中移除之前的 PhoneHub 资源，并删除重复的 ensure 行。备份请存放在该目录之外。
• 保持替换同一栋 Portola Drive 建筑的其他任何地图处于禁用状态。
• 替换地图文件之前，请完全关闭 FiveM 并停止服务器。先启动服务器，再重新打开 FiveM。替换或重启这个流式加载的 MLO 之前，请断开客户端连接。已连接的客户端即使远离建筑也可能保留该地图；热重启它可能导致该客户端崩溃。

本安装包不包含服务器授权密钥、框架、背包或付费第三方脚本。Keymaster 处理完成后，服务器密钥必须属于拥有这个新合并资源授权的账户。拥有旧的仅手机版授权并不会获得这个新版本。

2. 复制资源

把本次下载中的 phone 和 zerodev_phonehub_mlo 文件夹复制到服务器的 resources 目录中。可以放在任何分类文件夹里；文件夹名称必须完全保持不变。

screenshot-basic。相机需要 screenshot-basic 在 phone 之前启动；标准资源即可。下载中还附带一个更轻量的版本（只在拍照时绘制游戏画面，名称、导出函数和事件都相同）。切换到它是可选的：把旧文件夹作为备份放在 resources 之外，测试会截图的脚本，如果有任何变化就把旧文件夹放回去。Pulse Phone 快速入门第 6 步有具体步骤；改动的文件列在 screenshot-basic/ZERODEV-CHANGES.md 中。

在 server.cfg 中现有依赖之后添加以下几行：

ensure phone
ensure zerodev_phonehub_mlo

不要把旧的手机引擎或 UI 复制到新安装包中。升级时，把你需要的设置迁移到新的配置文件中。保留你的数据库、资源 KVP 存储、media 和 ownermedia 目录。新的 phone/config/phonehub_business.lua 包含仅手机版没有的配送设置。

已配置的商店柜台位于 -749.541, -216.952224, 36.256562，朝向 210。在全新的整合版中，门店位置已经配置好。PhoneHub 是该版本中唯一的手机店：仅手机版安装包中的 Legion Square 商店不包含在内。沿用 1.4.4 或更早版本的 config.lua 仍会列出 Legion Square；该条目会被跳过，控制台会提示一次。在店内自助终端、维修台、服务柜台或屋顶控制点按 PhoneHub 键（默认 E），或使用 /phonehub，即可打开 PhoneHub 终端。自助终端打开 Shop，维修台打开 Repair。按键可以在 FiveM 按键绑定中修改。该命令与按键要求相同的距离；员工操作仍需要服务器权限。

3. 框架、背包和其他脚本

从 Config.Framework = 'auto' 和 phone/config/config.lua 中的自动提供方设置开始。手机的启动健康报告会显示它实际选择的提供方。在进行购买测试之前，请先检查这份报告。

背包适配器涵盖 ox_inventory、受支持的框架背包函数，以及 phone/guides/integrations.md（或你的手机版本附带的集成指南）中列出的第三方提供方。每个提供方都需要其真实的物品定义和兼容的 API 版本。缺失的物品会由手机健康检查报告；不要屏蔽这些错误。物品设置示例在 phone/config/items/ 下。

手机可编辑的桥接涵盖语音、社团账户、银行、车库、房产、调度及其他集成。每项功能只保留一个选定的提供方。通过 Config.ResourceNames 固定改了名的资源；用 Config.Providers 明确选择提供方。任意第三方导出函数并不会自动兼容：当你的脚本不在列表中时，请实现有文档说明的自定义桥接。框架适配器和自动化契约测试并不代表每个第三方版本都经过了实机测试。

本版本的实测环境：ESX Legacy、ox_inventory、oxmysql 和 pma-voice。在其他框架上，请在开店之前运行第 7 节中的首次运行检查。

4. 公共商店或玩家经营的企业

在服务器控制台中运行以下任一命令：

phonehubmode public
phonehubmode business

所选模式在重启后保持不变。公共模式保留普通购物。企业模式会对在 PhoneHub 柜台进行的购买应用持久库存和预订。企业模式会禁用柜台以旧换新。同一套手机结账流程会校验价格、付款和物品交付。

在 phone/config/phonehub_business.lua 中设置职业名称和等级：

使用你框架常规的管理工具分配职业。在手机上打开 Services → My Work → PhoneHub → Staff and account 进行公司管理。它使用所选框架受支持的员工/社团函数。合并版还支持持久的玩家所有权，可通过 Business 标签页中的游戏内购买，或下方介绍的管理员分配命令获得。所有所有权价格都是游戏内货币金额。

对于使用 esx_addonaccount 的 ESX，还要在启动账户资源之前导入 zerodev_phonehub_mlo/setup/phonehub_esx_society.sql，然后重启服务器。这会创建余额为零的 society_phonehub 公司账户，不会替换已有的余额。如果你重命名了职业，请相应更新账户后缀。其他银行提供方需要为所配置的职业进行常规的公司账户设置。开业之前，请在 Company 中验证一笔小额存款和取款。

运营预算是一个单独的内部进货账本。销售会增加它；供应商订单会从中扣除。它不会自动成为社团银行账户，也不是玩家可提取的现金余额。

5. 供应商订单和库存配送

在服务柜台按 E 打开 PhoneHub 终端，然后进入 Stock。选择产品、配置和数量。服务器会计算供应商报价，并检查员工的等级、距离和运营预算。

默认配送需要 120 秒。重启期间保持运输中状态。到达后，员工在终端选择 Receive delivery。默认的 destination='stock' 会把货物加入门店库存账本，供结账消耗，与买家所用的玩家背包提供方无关。重复的签收请求不会让同一批货被加两次。经理可以取消尚未签收的货物，预算只退还一次。

配置：

delivery = {
    seconds = 120,
    autoReceive = false,
    destination = 'stock',
    resource = '',
    export = '',
}

对于自定义仓库/储物箱，设置 destination='custom' 并指定一个服务端导出函数。它会收到 (shipment, source)，并且必须把 shipment.id 用作持久的去重键。只有当每一行都成功存储时才返回 true。在该适配器中配置你背包的物品/SKU 映射。自定义配送不会同时把物品加入内部销售账本；请明确对接你的仓库销售流程，以避免库存重复。不预设任何通用的储物箱适配器。

不确定的外部交接会被挂起等待审核，绝不会盲目重试。检查目标背包后，使用：

phonehubdelivery <shipment-id> delivered
phonehubdelivery <shipment-id> retry

对于不确定的顾客结账预订，请先检查付款和背包记录，再使用 phonehubresolve <reservation-id> returned|delivered。

6. 门店控制

在服务控制点或屋顶控制台附近按 E。

• Space：前门和屋顶门锁、店内灯光、休息区显示屏、露台顶棚（雨雪天自动关闭，或手动开/关）、露台取暖器或通风、露台电源，以及 15 秒的喷淋测试。
• Cameras：Entrance overview、Showroom overview 和 Service counter。返回终端会关闭摄像头；Escape 退出。
• Stock 和 Business：供应商订单、配送、营业收入、销售和维修账本，以及团队权限。

建筑控制需要 PhoneHub 职业或已配置的员工/管理员 ACE。露台的公共控制权限在 systems_config.lua 中单独配置。只把 phonehub.admin 授予你受信任的管理员 principal；绝不要授予所有人。在 MLO 系统配置中设置 phoneResource='phone'。

自动门在解锁时使用接近感应。其移动的门扇必须保持实体碰撞，打开时也不例外。家具、玻璃和灯光都是制作好的地图资源；并不是每个装饰物都有游戏交互。

7. 首次运行验收

1. 启动服务器并运行 phone:health。确认框架、背包、数据库和语音提供方符合预期，且没有缺少必需的物品。
2. 正常进入服务器并前往门店。在关闭穿墙（noclip）的情况下，从人行道走过两组入口、上下楼梯并穿过屋顶门口。
3. 打开和关闭顶棚。它的八块面板在每个位置都必须保持在导轨内对齐。单独测试雨雪天自动关闭。
4. 打开每个 CCTV 视角，在它们之间切换并退出。画面必须可见，且必须恢复正常的玩家视角/焦点。
5. 用员工账户锁上两组门。从两侧检查碰撞。解锁后再次确认接近感应的开门动画。
6. 检查白天/夜晚的灯光、显示屏开/关、玻璃、招牌、座椅和所有边缘。走路和开车靠近/远离建筑，检查流式加载的过渡。
7. 在公共模式下购买一部手机/配件。在企业模式下，检查库存扣减、员工订货、到货/签收、资金不足和未授权访问。
8. 重启服务器，确认商店模式、库存和待处理的配送都已保留。重复一次签收/取消操作；不应出现重复的货物或退款。确认多名玩家看到的门店状态相同。

在客户端 F8 控制台中运行 phonehubcheck 会报告顶棚的实际对齐情况；每块面板的对齐值应接近 1。它是一个诊断工具，不能证明视觉质量或碰撞是正确的。自动化检查无法保证每个镜头角度或所有服务器组合。

8. 故障排查和更新

端口 30120 被占用：已经有另一个服务器实例在运行。请通过你的 txAdmin（或主机面板）停止它，而不是再启动第二个 FXServer。

控制选项缺失：确认两个资源都已启动、名称没有改动，且玩家位于控制点。检查客户端 F8 和服务器错误。

没有员工权限：检查配置的职业、数字等级、与服务柜台的距离以及所选的职业提供方。公共商店模式不会授予员工权限。

旧地图/旧界面仍然存在：删除重复的资源/ensure 条目。完全关闭 FiveM，停止服务器，替换文件，然后启动服务器并重新打开 FiveM。仅重新连接可能会保留过期的流式资源。客户端连接期间不要热重载 MLO，即使离建筑很远也不行。

回滚：停止这些资源，恢复备份的资源文件夹和配置，然后用你现有的 txAdmin 重启。除非是有意恢复一致的数据备份，否则请保留数据库/KVP 存储。

请保留随附的版本哈希文件（SHA256.json），以便申请支持时使用。

PhoneHub OS 和所有权

Config.PhoneHubOS（位于 phone/config/phonehub_business.lua）控制该版本。ownership='both' 允许游戏内购买和管理员分配两种方式。设为 'admin' 或 'purchase' 则只允许其中一种。purchasePrice 是游戏内货币金额。管理员使用 phonehubowner <online player id>，可在服务器控制台中运行，或凭借 phonehub.admin ACE 运行。有购买付款待处理时，无法进行分配。店主按框架的角色标识符保存，绝不会使用临时的玩家 source 编号。获得所有权后，会启用现有的持久库存和运营预算系统。

店主可以在 Business 标签页中添加附近的员工或经理。这些独立角色通过框架身份桥接运作；它们不会改变玩家的主职业。现有的 PhoneHub 职业角色和已配置的管理权限仍然有效。默认情况下，经理可以订购物资，员工可以签收已到达的货物。在购买或供应商配送确认之前，库存保持预留状态。

service='hybrid' 同时允许协助式和自助式的结账与维修。'self' 允许直接服务；'staff' 要求在本店由顾客批准员工提出的报价。单独的产品保留其现有的购物系统。

走近店内自助终端并按 E。Shop 标签页会加载真实的受保护 Pulse 模型，支持拖动旋转、正反面查看、缩放和所选外观。价格由手机服务器给出。付款需要确认，并使用已配置的背包、金钱和盒装手机交付。超时并不代表扣款失败；再次尝试之前，请先检查背包和付款记录。

顾客在 Help 标签页中请求销售或维修帮助，并获得一个排队号。员工在 Counter 标签页中选择附近的顾客并准备报价；只有该顾客可以批准并付款。双方都必须留在同一家店、同一个 routing bucket 中。维修批准会绑定所选的唯一设备及其报价。更换设备会使其失效。

对于协助式维修，技术员在空闲的维修台打开终端，准备顾客的维修报价，并留在原地等待接受。维修台在付款前就会被预留。付费维修成功后，会以该玩家作为技术员播放组装流程；自助维修则使用店内技术员。手机引擎负责设备维修，并会在服务器会话中断后恢复已付费的维修。客户端道具永远不会创建或替换背包中的手机。

在屋顶和柜台控制点的 Space 标签页可以控制顶棚、空调、门锁、灯光和显示屏。已完成 MLO 中的几何结构、防风雨、地面和座椅都会保留。