feat(config): 新增用户前端访问开关

新增 `frontend_enable` 配置并接入后台站点设置，
用于控制用户首页、订阅入口及用户侧 API 是否对外开放。

开关关闭时相关用户入口统一返回空 404，
同时保留节点 API、管理后台与外部回调接口可访问。

补充特性测试覆盖默认开启、关闭隐藏与节点接口白名单场景

.helloagents/modules/_index.md

@@ -10,3 +10,4 @@
 | [order-payment](order-payment.md) | 订单支付成功快照、第三方回调元信息透传与后台支付成功信息展示 | 2026-04-25 |
 | [queue-mail](queue-mail.md) | 邮件发送队列、SMTP 运行时配置、Horizon 超时与失败重试边界 | 2026-04-28 |
 | [subscription-protocols](subscription-protocols.md) | 用户订阅导出入口、协议适配器与 Stash / Clash 系列兼容过滤 | 2026-04-24 |
+| [user-frontend-access](user-frontend-access.md) | 用户前端访问开关、用户侧 API 隐藏边界与节点 API 白名单 | 2026-04-29 |

.helloagents/modules/admin-frontend.md

@@ -70,6 +70,7 @@
 - 优惠券编辑弹窗支持金额/比例两种优惠类型、有效期范围、批量生成、自定义券码、指定周期与指定订阅限制
 - 系统管理新增独立“系统管理”侧边栏分组，当前已完整实现 `#/system/config`、`#/system/themes`、`#/system/plugins`、`#/system/notices`、`#/system/payments` 与 `#/system/knowledge`
 - 系统配置页使用真实后端 `config/fetch`、`config/save`、`config/testSendMail` 与 `config/setTelegramWebhook`，并按站点、安全、订阅、邀请佣金、节点、邮件、Telegram、APP、订阅模板 9 个分组组织长表单
+- 系统配置页的站点设置包含“开放用户前端”开关；关闭后由后端让用户首页和用户侧 API 返回空 404，节点 API 与管理后台不受影响
 - 主题管理页使用真实后端 `theme/getThemes`、`theme/getThemeConfig`、`theme/saveThemeConfig`、`theme/upload`，并通过 `config/save(frontend_theme)` 完成当前主题切换
 - 主题配置抽屉按后端返回的动态 schema 渲染 `input / textarea / select` 字段，不在前端猜测额外配置项
 - 插件管理页使用真实后端 `plugin/types`、`plugin/getPlugins`、`plugin/upload`、`plugin/install`、`plugin/uninstall`、`plugin/enable`、`plugin/disable`、`plugin/config` 与 `plugin/upgrade`

.helloagents/modules/user-frontend-access.md

@@ -0,0 +1,27 @@
+# user-frontend-access
+
+## 职责
+
+- 控制用户前端网页、用户登录注册、用户中心 API、客户端订阅 API 和公开用户展示接口是否对外开放
+- 保留节点通信 API、管理后台页面、管理 API 和外部回调接口的原有访问边界
+- 为后台系统配置提供 `frontend_enable` 开关，默认开启以兼容已有部署
+
+## 行为规范
+
+- `frontend_enable` 存储在 `v2_settings`，通过 `admin_setting('frontend_enable', 1)` 读取；缺省值为开启
+- `EnsureUserFrontendEnabled` 关闭时返回空 404，不渲染用户主题，不输出 `app_name`、站点描述、主题标题或其他站点识别信息
+- `routes/web.php` 的 `/` 和 `/{subscribe_path}/{token}` 挂载 `user.frontend`，关闭时不会进入主题渲染和订阅控制器
+- `/api/v1/passport/*`、`/api/v1/user/*`、`/api/v2/user/*`、`/api/v1/client/*`、`/api/v2/client/*` 挂载 `user.frontend`
+- `/api/v1/guest/plan/fetch` 与 `/api/v1/guest/comm/config` 挂载 `user.frontend`
+- `/api/v1/guest/payment/notify/*` 与 `/api/v1/guest/telegram/webhook` 保持开放，避免影响支付和 Telegram 回调
+- `/api/v1/server/*` 与 `/api/v2/server/*` 不挂载 `user.frontend`，确保 mi-node 拉配置、上报在线和上报流量不受用户前端开关影响
+- 管理后台路由和管理 API 不受 `frontend_enable` 控制；管理后台自身继续依赖 `secure_path` 与既有后台鉴权
+
+## 依赖关系
+
+- 依赖 `app/Http/Middleware/EnsureUserFrontendEnabled.php` 执行访问控制
+- 依赖 `app/Http/Kernel.php` 注册 `user.frontend` 路由中间件别名
+- 依赖 `app/Http/Controllers/V2/Admin/ConfigController.php` 在 `site` 配置组返回 `frontend_enable`
+- 依赖 `app/Http/Requests/Admin/ConfigSave.php` 校验并保存 `frontend_enable`
+- 依赖 `admin-frontend/src/utils/systemConfig.ts` 在站点设置中渲染“开放用户前端”开关
+- 依赖 `tests/Feature/UserFrontendAccessToggleTest.php` 验证默认开启、关闭隐藏和节点 API 不被误拦截