更新统一使用 PHPDoc + PSR-19 标准注释

app/service/bootstrap/SystemBootstrapService.php

@@ -4,8 +4,19 @@ namespace app\service\bootstrap;
 
 use app\common\base\BaseService;
 
+/**
+ * 系统引导服务。
+ *
+ * 用于提供前端启动时需要的菜单树和字典项数据。
+ */
 class SystemBootstrapService extends BaseService
 {
+    /**
+     * 获取指定面板的菜单树。
+     *
+     * @param string $panel 面板标识，通常为 `admin` 或 `merchant`
+     * @return array 菜单树
+     */
     public function getMenuTree(string $panel): array
     {
         $roles = $panel === 'merchant' ? ['common'] : ['admin'];
@@ -14,6 +25,14 @@ class SystemBootstrapService extends BaseService
         return $this->normalizeRedirects($this->buildTree($nodes));
     }
 
+    /**
+     * 获取字典项。
+     *
+     * 支持一次获取全部字典，也支持按逗号分隔的 code 过滤。
+     *
+     * @param string|null $code 字典编码
+     * @return array 字典数据
+     */
     public function getDictItems(?string $code = null): array
     {
         $items = $this->dictItems();
@@ -34,16 +53,33 @@ class SystemBootstrapService extends BaseService
         return array_values(array_intersect_key($items, array_flip($codes)));
     }
 
+    /**
+     * 获取面板菜单配置原始节点。
+     *
+     * @param string $panel 面板标识
+     * @return array 原始节点
+     */
     protected function menuNodes(string $panel): array
     {
         return (array) config("menu.$panel", config('menu.admin', []));
     }
 
+    /**
+     * 获取系统字典原始配置。
+     *
+     * @return array 原始字典配置
+     */
     protected function dictItems(): array
     {
         return $this->normalizeDictItems((array) config('dict', []));
     }
 
+    /**
+     * 将系统字典配置标准化为 code 索引结构。
+     *
+     * @param array $items 原始配置
+     * @return array 标准化后的字典项
+     */
     protected function normalizeDictItems(array $items): array
     {
         $normalized = [];
@@ -80,6 +116,13 @@ class SystemBootstrapService extends BaseService
         return $normalized;
     }
 
+    /**
+     * 按角色过滤菜单节点。
+     *
+     * @param array $nodes 菜单节点
+     * @param array $roles 角色集合
+     * @return array 过滤后的节点
+     */
     protected function filterByRoles(array $nodes, array $roles): array
     {
         return array_values(array_filter($nodes, function (array $node) use ($roles): bool {
@@ -96,6 +139,12 @@ class SystemBootstrapService extends BaseService
         }));
     }
 
+    /**
+     * 将扁平菜单节点构造成树。
+     *
+     * @param array $nodes 菜单节点
+     * @return array 树结构
+     */
     protected function buildTree(array $nodes): array
     {
         $grouped = [];
@@ -127,6 +176,12 @@ class SystemBootstrapService extends BaseService
         return $build('0');
     }
 
+    /**
+     * 为有子节点的菜单补充默认重定向路径。
+     *
+     * @param array $tree 菜单树
+     * @return array 处理后的菜单树
+     */
     protected function normalizeRedirects(array $tree): array
     {
         foreach ($tree as &$node) {
@@ -142,6 +197,12 @@ class SystemBootstrapService extends BaseService
         return $tree;
     }
 
+    /**
+     * 获取首个可渲染路径。
+     *
+     * @param array $nodes 菜单节点
+     * @return string|null 路径
+     */
     protected function firstRenderablePath(array $nodes): ?string
     {
         foreach ($nodes as $node) {
@@ -155,3 +216,8 @@ class SystemBootstrapService extends BaseService
     }
 }
 
+
+
+
+
+