README

Laravel Filament Store Locator

简体中文 | English

适用于 PHP 8.4+、Laravel 13、Filament 5 的门店管理与公开查询包，依赖 CMS Core 和 Qrcode。

功能与边界

能力	说明
门店管理	新增、编辑、删除、发布状态、权重排序
地理信息	国家、省市、地址、经纬度、邮编、地铁线路
联系方式与营业时间	网站、电话、邮箱、每周时间、例外日期及说明
门店媒体	Logo 和多张 Banner，使用 Filament 原生 FileUpload
公开 API	已发布门店列表和详情、分页、距离排序
CMS 集成	模块自登记、权限目录、中英文资源及租户数据范围

本包不提供地图服务、地址地理编码或“当前是否营业”的自动判断，也不包含旧 Nova 的自定义字段管理界面。后台部分表单标题仍使用英文，不代表界面已经完整本地化。

1. 安装

先在宿主 Composer 配置本私有包及所需 fayne/* 依赖的软件源：

composer require fayne/laravel-filament-store-locator
php artisan vendor:publish --tag=store-locator-config
php artisan cms:install

Laravel 自动发现服务提供者并加载迁移。cms:install 运行已注册迁移、初始化权限目录并发布 Filament 静态资源；生产自动部署使用 --force --no-interaction。已有 Core 项目也可运行 php artisan migrate 加载本包迁移，再重跑 Core 安装补齐权限。不要在已有业务数据的数据库上执行 migrate:fresh。

媒体磁盘默认使用 public，须确保其 URL 可访问，并按宿主配置创建存储链接。无需为了本包的上传控件额外安装文件选择器。

2. 接入后台与权限

本包通过自身 ServiceProvider 向 Core 的 ModuleRegistry 登记 store-locator。继承 Core AdminPanelProvider / TenantPanelProvider 的项目自动接入：单租户在普通后台管理，多租户在 workspace 管理。

完全自定义的 PanelProvider 在配置 CMS、middleware、guard、租户及显式插件后调用：

return app(\Fayne\CMS\Support\Modules\ModuleRegistry::class)->applyTo($panel);

如需手动接入，可配置 Fayne\StoreLocator\Filament\StoreLocatorPlugin::make()；同 ID 的显式插件会被保留，不要在自动接入之后重复注册。

权限定义在 resources/permissions.php，名称和分组翻译位于 resources/lang/{zh_CN,en}。安装不自动给已有角色增加授权；必须在对应范围分配门店权限。多租户账号还须具备有效成员资格，平台超级管理员不自动绕过租户归属。

3. 配置

发布后的文件是 config/store-locator.php：

return [
    'disk' => env('STORE_LOCATOR_DISK', 'public'),
    'routes' => [
        'enabled' => env('STORE_LOCATOR_ROUTE_ENABLED', true),
        'cached' => env('STORE_LOCATOR_ROUTE_CACHED', true),
        'max_age' => (int) env('STORE_LOCATOR_ROUTE_MAX_AGE', 3600),
    ],
];

enabled 控制公开路由，cached 控制列表服务端缓存，max_age 控制 HTTP Cache-Control。列表缓存使用 cache tags，启用时必须选择支持标签的缓存驱动；不支持时设 STORE_LOCATOR_ROUTE_CACHED=false。列表服务端缓存使用 rememberForever，不会按 max_age 自动到期；模型新增、更新、删除及后台排序会触发缓存失效。公开响应具有缓存头，多租户部署的代理/CDN 必须正确区分主机与请求 URL。

配置变更后按部署流程刷新配置/路由缓存，并重新加载长驻进程。

4. 公开 API

方法	路径	用途
GET	`/modules/store-locator/stores`	已发布门店分页列表
GET	`/modules/store-locator/stores/{store}`	已发布门店详情；未发布返回 404

列表默认每页 15 条，page_size 支持 1–100。距离排序示例：

GET /modules/store-locator/stores?order_by=distance&latitude=31.23&longitude=121.47&page_size=20

距离排序必须同时提交合法经纬度；纬度范围 -90–90，经度范围 -180–180。该查询依赖数据库三角函数，需在目标数据库验收。API 使用 Laravel Resource 输出，媒体由磁盘/路径转换，不能将上传的内部数据结构直接当作公开 URL。

单租户使用本站范围 0；多租户由 ResolvePublicTenant 根据请求主机解析租户，需要配置有效租户域名。后台语言与门店数据不是同一个概念，本包不提供门店内容翻译版本管理。

5. 程序使用

use Fayne\StoreLocator\Models\Store;

$stores = Store::query()->published()->orderBy('weight')->get();

模型自动限定当前站点/租户。多租户命令和队列中须显式设置 Core TenantContext；不能通过脱离上下文的查询跨租户读取。Logo 和 Banner 使用包内媒体 casts，营业时间、品牌等使用结构化属性；自定义写入入口仍须负责业务校验与授权。

6. 测试与上线

在本包目录执行：

composer install
composer test
composer format
composer analyse

上线至少验证：安装迁移、角色授权、CRUD 与排序、媒体上传和公开 URL、发布状态过滤、缓存失效、目标数据库距离排序；多租户另验域名解析及跨租户隔离。自动化测试不能代替真实文件存储、CDN 和浏览器验收。

合作与贡献

通过 Issue 描述需求或缺陷，附版本、复现步骤及预期行为。合并请求须包含相关测试和中英文文档更新，并说明未验证的环境；不要提交凭据、业务数据或 composer.lock。商业合作及授权请联系 Fayne Guo。

许可证

采用专有许可证，使用和分发须遵守授权限制；第三方依赖遵循各自许可证。

fayne / laravel-filament-store-locator

Package info

Security

Statistics