style(header): 统一核心契约缓存和测试文件格式

- 按 PHP-CS-Fixer 规则补齐核心契约、异常、缓存和 XML 工具文件头。

- 规范导入、PHPDoc 类型顺序与注释格式，保持项目头信息不丢失。

- 同步整理缓存键、缓存实现、XML 编解码相关测试和 bootstrap 格式。

src/Contract/ConfigInterface.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 平台配置契约。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Contract;

src/Contract/StoreCacheInterface.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * SDK 运行态缓存契约。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Contract;

src/Contract/StoreTokenInterface.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 微信服务平台授权方 Token 存储契约。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Contract;

src/Exception/ApiException.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 平台接口请求异常。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Exception;

src/Exception/SignatureException.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 签名与验签异常。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Exception;

src/Exception/WechatException.php

@@ -1,22 +1,21 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * SDK 基础异常。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Exception;
 
-use RuntimeException;
-use Throwable;
-
 /**
  * SDK 基础异常。
  *
  * 通过 context() 暴露平台响应、验签明细等上下文，便于业务侧记录日志和排查问题。
  */
-class WechatException extends RuntimeException
+class WechatException extends \RuntimeException
 {
     /**
      * 创建 SDK 异常并保存可选上下文。
@@ -26,7 +25,7 @@ class WechatException extends RuntimeException
     public function __construct(
         string $message,
         int $code = 0,
-        ?Throwable $previous = null,
+        ?\Throwable $previous = null,
         private readonly array $context = []
     ) {
         parent::__construct($message, $code, $previous);

src/Support/CacheKey.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 缓存键生成工具。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Support;
@@ -18,9 +20,9 @@ final class CacheKey
     /**
      * 组合缓存完整键。
      *
-     * @param string $prefix 根 Client 通用命名段，不得为空，用于区分部署、租户或应用。
+     * @param string $prefix 根 Client 通用命名段，不得为空，用于区分部署、租户或应用
      * @param string $channel 通道段，如 `wechat.platform`，必须与 Client 通道标识一致。
-     * @param string $logicalKey 业务逻辑键，如 TokenCacheKey 生成的 access_token 键。
+     * @param string $logicalKey 业务逻辑键，如 TokenCacheKey 生成的 access_token 键
      */
     public static function compose(string $prefix, string $channel, string $logicalKey): string
     {

src/Support/FileCacheStore.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 本地文件缓存实现。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Support;
@@ -60,7 +62,7 @@ final class FileCacheStore implements StoreCacheInterface
             return $default;
         }
 
-        /** @var array{expires_at?:int,value?:mixed}|null $payload */
+        /** @var null|array{expires_at?:int,value?:mixed} $payload */
         $payload = json_decode($raw, true);
         if (!is_array($payload) || !array_key_exists('expires_at', $payload) || !array_key_exists('value', $payload)) {
             return $default;

src/Support/NullCacheStore.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 空缓存实现。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Support;

src/Support/PsrSimpleCacheStore.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * PSR-16 缓存适配器。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Support;

src/Support/TokenCacheKey.php

@@ -1,18 +1,22 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 平台接口调用凭据缓存逻辑键生成工具。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Support;
 
+use We\Client;
+
 /**
  * 微信接口调用凭据缓存逻辑键统一按「微信侧 appid 优先」分段，便于 Redis 等存储按应用前缀扫描和清理。
  *
  * 约定前缀：`wechat:app:{appid}:...`；若 Config 带 `storageScope`（业务隔离），追加 `:scope:{值}`。
- * 经根 {@see \We\Client} 与各通道写入存储时，作为第三段与通用前缀、平台段经 {@see CacheKey::compose} 拼成固定三段键。
+ * 经根 {@see Client} 与各通道写入存储时，作为第三段与通用前缀、平台段经 {@see CacheKey::compose} 拼成固定三段键。
  */
 final class TokenCacheKey
 {

src/Support/Xml.php

@@ -1,14 +1,15 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 微信 XML 编解码工具。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Support;
 
-use SimpleXMLElement;
 use We\Exception\WechatException;
 
 /**
@@ -31,9 +32,9 @@ final class Xml
         }
 
         $previous = libxml_use_internal_errors(true);
-        $element = simplexml_load_string($xml, SimpleXMLElement::class, LIBXML_NOCDATA);
+        $element = simplexml_load_string($xml, \SimpleXMLElement::class, LIBXML_NOCDATA);
         libxml_use_internal_errors($previous);
-        if (!$element instanceof SimpleXMLElement) {
+        if (!$element instanceof \SimpleXMLElement) {
             throw new WechatException('微信 XML 格式无效');
         }
 
@@ -89,7 +90,7 @@ final class Xml
      *
      * @return array<string,mixed>
      */
-    private static function normalize(SimpleXMLElement $element): array
+    private static function normalize(\SimpleXMLElement $element): array
     {
         $result = [];
         foreach ($element->children() as $key => $value) {

tests/CacheKeyTest.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * SDK 缓存键生成规则测试。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Tests;
@@ -16,6 +18,7 @@ use We\Support\TokenCacheKey;
 
 /**
  * SDK 缓存键生成规则测试用例。
+ * @internal
  */
 #[CoversClass(CacheKey::class)]
 final class CacheKeyTest extends TestCase

tests/CacheStoreTest.php

@@ -1,14 +1,15 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * SDK 缓存存储实现测试。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Tests;
 
-use DateInterval;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\TestCase;
 use Psr\SimpleCache\CacheInterface;
@@ -19,6 +20,7 @@ use We\Support\PsrSimpleCacheStore;
 
 /**
  * SDK 缓存存储实现测试用例。
+ * @internal
  */
 #[CoversClass(FileCacheStore::class)]
 #[CoversClass(NullCacheStore::class)]
@@ -146,7 +148,7 @@ final class ArraySimpleCache implements CacheInterface
     /**
      * 写入缓存值。
      */
-    public function set(string $key, mixed $value, null|int|DateInterval $ttl = null): bool
+    public function set(string $key, mixed $value, \DateInterval|int|null $ttl = null): bool
     {
         $this->values[$key] = $value;
 
@@ -186,7 +188,7 @@ final class ArraySimpleCache implements CacheInterface
     /**
      * 批量写入测试缓存值。
      */
-    public function setMultiple(iterable $values, null|int|DateInterval $ttl = null): bool
+    public function setMultiple(iterable $values, \DateInterval|int|null $ttl = null): bool
     {
         foreach ($values as $key => $value) {
             $this->set((string)$key, $value, $ttl);

tests/XmlTest.php

@@ -1,9 +1,11 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * 微信 XML 编解码工具测试。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
 
 namespace We\Tests;
@@ -14,6 +16,7 @@ use We\Support\Xml;
 
 /**
  * 微信 XML 编解码工具测试用例。
+ * @internal
  */
 #[CoversClass(Xml::class)]
 final class XmlTest extends TestCase

tests/bootstrap.php

@@ -1,11 +1,12 @@
 <?php
 
 declare(strict_types=1);
-
 /**
- * PHPUnit 测试启动文件。
+ * This file is part of HyperfAdmin.
+ *
+ * @Link https://thinkadmin.top
+ * @Author Anyon<zoujingli@qq.com>
  */
-
 $autoloadCandidates = [
     dirname(__DIR__) . '/vendor/autoload.php',
     dirname(__DIR__, 2) . '/vendor/autoload.php',