chore(release): 1.0.0-beta.11

- 添加 EnvConfiguration 接口，定义开发和生产环境常量
- 添加 ServiceProviderConfiguration 接口，继承环境和站点配置接口
- 添加 SiteConfiguration接口，定义中国和北美站点常量

Signed-off-by: 李东云 <dongyu.li@luxcreo.ai>

.devcontainer/devcontainer.json

@@ -0,0 +1,49 @@
+{
+    "name": "Hyperf Development Kit Core Dev Container",
+    "image": "harbor.luxcreo.cn/library/hyperf:8.1-swoole",
+    // 基础配置
+    "workspaceFolder": "/srv/www", // 对应 --workdir
+    "workspaceMount": "source=${localWorkspaceFolder},target=/srv/www,type=bind", // 主工作区挂载
+    // 附加挂载
+    "mounts": [
+        "source=${env:HOME}/.ssh,target=/root/.ssh,type=bind", // SSH 密钥挂载
+        "source=${env:HOME}/.gitconfig,target=/root/.gitconfig,type=bind" // SSH 密钥挂载
+    ],
+    // 容器生命周期
+    "shutdownAction": "stopContainer", // 类似 --rm 的清理行为
+    "updateRemoteUserUID": true, // 确保用户 ID 同步
+    // 保留的必要 runArgs
+    "runArgs": [
+        "--pull=always", // 强制拉取最新镜像
+        "--name=hdk-core" // 容器命名（需保持唯一性）
+    ],
+    // 初始化命令
+    "postCreateCommand": "echo 'Container initialized!'",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "rid9.datetime",
+                "MS-CEINTL.vscode-language-pack-zh-hans",
+                "ms-azuretools.vscode-docker",
+                "janisdd.vscode-edit-csv",
+                "onecentlin.laravel-blade",
+                "DavidWang.ini-for-vscode",
+                "bmewburn.vscode-intelephense-client",
+                "mechatroner.rainbow-csv",
+                "Alibaba-Cloud.tongyi-lingma",
+                "atommaterial.a-file-icon-vscode",
+                "ParthR2031.colorful-comments",
+                "vincaslt.highlight-matching-tag",
+                "xabikos.JavaScriptSnippets",
+                "shufo.vscode-blade-formatter",
+                "dansysanalyst.pest-snippets",
+                "m1guelpf.better-pest",
+                "xoronic.pestfile",
+                "xdebug.php-debug",
+                "golang.go",
+                "cweijan.vscode-typora",
+                "ciceroisback.loam"
+            ]
+        }
+    }
+}

.idea/HDK-Core.iml

@@ -185,6 +185,11 @@
       <excludeFolder url="file://$MODULE_DIR$/vendor/react/event-loop" />
       <excludeFolder url="file://$MODULE_DIR$/vendor/react/socket" />
       <excludeFolder url="file://$MODULE_DIR$/vendor/react/stream" />
+      <excludeFolder url="file://$MODULE_DIR$/vendor/phpspec/php-diff" />
+      <excludeFolder url="file://$MODULE_DIR$/vendor/phpspec/phpspec" />
+      <excludeFolder url="file://$MODULE_DIR$/vendor/phpspec/prophecy" />
+      <excludeFolder url="file://$MODULE_DIR$/vendor/symfony/polyfill-php84" />
+      <excludeFolder url="file://$MODULE_DIR$/vendor/symfony/yaml" />
     </content>
     <orderEntry type="inheritedJdk" />
     <orderEntry type="sourceFolder" forTests="false" />

.idea/jsonSchemas.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JsonSchemaMappingsProjectConfiguration">
+    <state>
+      <map>
+        <entry key="composer.json">
+          <value>
+            <SchemaInfo>
+              <option name="name" value="composer.json" />
+              <option name="relativePathToSchema" value="https://getcomposer.org/schema.json" />
+              <option name="applicationDefined" value="true" />
+              <option name="patterns">
+                <list>
+                  <Item>
+                    <option name="path" value="composer.json" />
+                  </Item>
+                </list>
+              </option>
+            </SchemaInfo>
+          </value>
+        </entry>
+      </map>
+    </state>
+  </component>
+</project>

.idea/php-test-framework.xml

@@ -2,6 +2,13 @@
 <project version="4">
   <component name="PhpTestFrameworkSettings">
     <test_tools>
+      <tool tool_name="PHPSpec">
+        <settings>
+          <configurations>
+            <local_configuration executable_path="$PROJECT_DIR$/vendor/phpspec/phpspec/bin/phpspec" />
+          </configurations>
+        </settings>
+      </tool>
       <tool tool_name="Pest">
         <settings>
           <configurations>

.idea/php.xml

@@ -200,6 +200,12 @@
       <path value="$PROJECT_DIR$/vendor/react/stream" />
       <path value="$PROJECT_DIR$/vendor/react/event-loop" />
       <path value="$PROJECT_DIR$/vendor/react/socket" />
+      <path value="$PROJECT_DIR$/vendor/symfony/polyfill-php72" />
+      <path value="$PROJECT_DIR$/vendor/symfony/polyfill-php84" />
+      <path value="$PROJECT_DIR$/vendor/symfony/yaml" />
+      <path value="$PROJECT_DIR$/vendor/phpspec/phpspec" />
+      <path value="$PROJECT_DIR$/vendor/phpspec/php-diff" />
+      <path value="$PROJECT_DIR$/vendor/phpspec/prophecy" />
     </include_path>
   </component>
   <component name="PhpProjectSharedConfiguration" php_language_level="8.1" />

CHANGELOG.md

@@ -1,4 +1,56 @@
 # 版本更新日志
+## [1.0.0-beta.11](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.10...v1.0.0-beta.11) (2025-07-11)
+
+
+### ✨ Features | 新功能
+
+* 新增SP相关配置的枚举 ([bf40c6e](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/bf40c6e681cb1ff37a8fc331a3cd0cdb495e6ff1))
+
+## [1.0.0-beta.10](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.9...v1.0.0-beta.10) (2025-07-09)
+
+
+### ✨ Features | 新功能
+
+* **core:** 添加 X-SP-ID 解析中间件 ([c6ab9db](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/c6ab9db69810bcd395c52cc304dffa54978d6e84))
+
+## [1.0.0-beta.9](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.8...v1.0.0-beta.9) (2025-07-07)
+
+
+### 📦‍ Build System | 打包构建
+
+* **deps:** 更新依赖并添加 PHPSpec 支持 ([c8b4545](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/c8b454540d2c4371c72f6cb79b5f65b97e7b92f2))
+
+## [1.0.0-beta.8](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.7...v1.0.0-beta.8) (2025-03-04)
+
+
+### ✨ Features | 新功能
+
+* **email:** 添加邮件附件功能 ([3b3502f](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/3b3502f7634b48c31c3e7689cdcfe1f4b504b968))
+
+
+### 📦‍ Build System | 打包构建
+
+* **composer:** Update Dependencies ([b4dcd01](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/b4dcd01e8d1fcd2c1fa211ef2a54512593500780))
+
+## [1.0.0-beta.7](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.6...v1.0.0-beta.7) (2025-03-03)
+
+
+### 📦‍ Build System | 打包构建
+
+* **devcontainer:** 添加 Hyperf 开发套件核心配置文件 ([aaa4382](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/aaa4382ff2c5105bc362777f62156b8383b67ed8))
+
+
+### ✨ Features | 新功能
+
+* **EmailService:** 添加邮件附件功能并更新单元测试 ([225bded](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/225bdedd23b1655d5fb7260838fc8c60db5d8f9f))
+
+## [1.0.0-beta.6](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.5...v1.0.0-beta.6) (2024-12-06)
+
+
+### 🐛 Bug Fixes | Bug 修复
+
+* **exceptions:** 处理 HTTP 客户端和服务器异常 ([2dace65](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/commit/2dace65933d7361c1124f8c5c125a507894584fb))
+
 ## [1.0.0-beta.5](http://124.126.16.154:8888/singularity/HyperfDevelopmentKitCore/compare/v1.0.0-beta.4...v1.0.0-beta.5) (2024-09-12)
 
 

VERSION_TRACKER.txt

@@ -1 +1 @@
-1.0.0-beta.5
+1.0.0-beta.11

composer.json

@@ -43,6 +43,7 @@
     "symfony/polyfill-php81": "^1.28",
     "symfony/polyfill-php82": "^1.28",
     "symfony/polyfill-php83": "^1.28",
+    "symfony/polyfill-php84": "^1.28",
     "teapot/status-code": "^1.1.2"
   },
   "require-dev": {
@@ -59,8 +60,9 @@
     "hyperf/testing": "^3.1",
     "hyperf/validation": "3.1.*",
     "pestphp/pest": "^2.23",
+    "phpspec/phpspec": "^7.5",
     "phpstan/phpstan": "^1.10.49",
-    "rector/rector": "^0.15.25",
+    "rector/rector": "*",
     "roave/security-advisories": "dev-latest",
     "spatie/pest-plugin-test-time": "^2.0",
     "swoole/ide-helper": "*",
@@ -107,7 +109,7 @@
       "phpunit.xml"
     ]
   },
-  "minimum-stability": "dev",
+  "minimum-stability": "beta",
   "prefer-stable": true,
   "scripts": {
     "post-root-package-install": [],
@@ -125,10 +127,14 @@
     ]
   },
   "repositories": {
+    "nest": {
+      "type": "composer",
+      "url": "https://nest.doylee.cn/api/packages/HDK/composer"
+    },
     "packagist": {
       "type": "composer",
       "url": "https://mirrors.aliyun.com/composer/"
     }
   },
-  "version": "1.0.0-beta.5"
+  "version": "1.0.0-beta.11"
 }

src/Enumerations/Sp/EnvConfiguration.php

@@ -0,0 +1,16 @@
+<?php
+/**
+ * EnvConfiguration.php@Core
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/7/11
+ */
+
+namespace Singularity\HDK\Core\Enumerations\Sp;
+
+interface EnvConfiguration
+{
+    public const DEVELOPMENT = 'development';
+    public const PRODUCTION = 'production';
+}

src/Enumerations/Sp/ServiceProviderConfiguration.php

@@ -0,0 +1,12 @@
+<?php
+/**
+ * ServiceProviderConfiguration.php@Core
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/7/11
+ */
+
+namespace Singularity\HDK\Core\Enumerations\Sp;
+
+interface ServiceProviderConfiguration extends EnvConfiguration, SiteConfiguration {}

src/Enumerations/Sp/SiteConfiguration.php

@@ -0,0 +1,16 @@
+<?php
+/**
+ * SiteConfigration.php@Core
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/7/11
+ */
+
+namespace Singularity\HDK\Core\Enumerations\Sp;
+
+interface SiteConfiguration
+{
+    public const CN = 'CN';
+    public const NA = 'NA';
+}

src/Events/EmailWillSent.php

@@ -1,4 +1,5 @@
 <?php
+
 /**
  * EmailWillSent.php@HDK-Core
  *
@@ -10,6 +11,7 @@
 namespace Singularity\HDK\Core\Events;
 
 use Singularity\HDK\Core\Service\EmailService;
+use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Email;
 
 /**
@@ -25,9 +27,9 @@ class EmailWillSent
 {
     public function __construct(
         /**
-         * @var string|string[] $target
+         * @var Address|string|string[]|Address[] $target
          */
-        public string|array $target,
+        public Address|string|array $target,
 
         /**
          * @var non-empty-string $subject
@@ -68,6 +70,17 @@ class EmailWillSent
          * @var EmailService|null
          */
         public ?EmailService $sender = null,
-    ) {
-    }
+
+        /**
+         * 附件路径集合、含附件路径、文件名、文件类型的数组集合
+         * @var string[]|array{'path': string, 'name': string, 'mimeType': string}[] $attachmentPaths
+         */
+        public array $attachmentPaths = [],
+
+        /**
+         * 附件内容集合、含附件内容、文件名、文件类型的数组集合
+         * @var string[]|array{'content': string, 'name': string, 'mimeType': string}[] $attachments
+         */
+        public array $attachments = [],
+    ) {}
 }

src/Exceptions/Handler/CommonHandler.php

@@ -13,6 +13,8 @@ declare(strict_types=1);
 namespace Singularity\HDK\Core\Exceptions\Handler;
 
 use Carbon\Carbon;
+use GuzzleHttp\Exception\ClientException;
+use GuzzleHttp\Exception\ServerException;
 use Hyperf\Codec\Json;
 use Hyperf\Database\Exception\QueryException;
 use Hyperf\Database\Model\ModelNotFoundException;
@@ -93,6 +95,26 @@ class CommonHandler extends ExceptionHandler
                 $data['details'] = ['sql' => $throwable->getSql(), 'error' => $throwable->getMessage()];
             }
         }
+        if ($throwable instanceof ClientException) {
+            $content = $throwable->getResponse()->getBody()->getContents();
+
+            ['errorCode' => $code, 'errorMsg' => $msg] = Json::decode($content);
+            $data = [
+                $code_name => $code,
+                $message_name => $msg,
+            ];
+            $status_code = 400;
+        }
+        if ($throwable instanceof ServerException) {
+            $content = $throwable->getResponse()->getBody()->getContents();
+
+            ['errorCode' => $code, 'errorMsg' => $msg] = Json::decode($content);
+            $data = [
+                $code_name => $code,
+                $message_name => $msg,
+            ];
+            $status_code = 500;
+        }
         // 101 请求方式错误
         if ($throwable instanceof MethodNotAllowedHttpException) {
             $message = explode(': ', $throwable->getMessage());

src/Listener/EmailWillSentListener.php

@@ -1,4 +1,5 @@
 <?php
+
 /**
  * EmailWillSentListener.php@HDK-Core
  *
@@ -64,7 +65,9 @@ class EmailWillSentListener implements ListenerInterface
                     subject: $event->subject,
                     html: $event->content,
                     cc: $event->cc,
-                bcc: $event->bcc,
+                    bcc: $event->bcc,
+                    attachmentPaths: $event->attachmentPaths,
+                    attachments: $event->attachments,
                     priority: $event->priority
                 )
                 : $emailService->sendText(
@@ -72,7 +75,9 @@ class EmailWillSentListener implements ListenerInterface
                     subject: $event->subject,
                     text: $event->content,
                     cc: $event->cc,
-                bcc: $event->bcc,
+                    bcc: $event->bcc,
+                    attachmentPaths: $event->attachmentPaths,
+                    attachments: $event->attachments,
                     priority: $event->priority
                 );
 

src/Middleware/SpParseMiddleware.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * SpParseMiddleware.php@Core
+ *
+ * @author 李东云 <Dongyun.Li@LuxCreo.Ai>
+ * Powered by PhpStorm
+ * Created on 2025/7/9
+ */
+declare(strict_types=1);
+
+namespace Singularity\HDK\Core\Middleware;
+
+use Hyperf\Context\Context;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+final class SpParseMiddleware implements MiddlewareInterface
+{
+
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
+    {
+        $sp = $request->getHeaderLine('X-SP-ID');
+        if (!empty($sp)) {
+            Context::set('sp', $sp);
+        }
+
+        return $handler->handle($request);
+    }
+}

src/Service/EmailService.php

@@ -79,7 +79,7 @@ class EmailService
     }
 
     /**
-     * @param string|array<string> $target
+     * @param Address|string|array<string|Address> $target
      * @param string        $subject
      * @param string        $text
      * @param array<string> $cc
@@ -90,11 +90,13 @@ class EmailService
      * @throws TransportExceptionInterface
      */
     public function sendText(
-        string|array $target,
+        Address|string|array $target,
         string $subject,
         string $text,
         array $cc = [],
         array $bcc = [],
+        array $attachmentPaths = [],
+        array $attachments = [],
         int $priority = Email::PRIORITY_NORMAL
     ): bool {
         $email = (new Email())
@@ -106,6 +108,22 @@ class EmailService
             ->subject($subject)
             ->text($text);
 
+        foreach ($attachmentPaths as $attachmentPath) {
+            if (is_string($attachmentPath)) {
+                $email = $email->attachFromPath($attachmentPath);
+            } else {
+                $email = $email->attachFromPath($attachmentPath['path'], $attachmentPath['name'] ?? null, $attachmentPath['mimeType'] ?? null);
+            }
+        }
+
+        foreach ($attachments as $attachment) {
+            if (is_string($attachment)) {
+                $email = $email->attach($attachment);
+            } else {
+                $email = $email->attach($attachment['content'], $attachment['name'] ?? null, $attachment['mimeType'] ?? null);
+            }
+        }
+
         $this->mailer->send($email);
 
         return true;
@@ -114,7 +132,7 @@ class EmailService
     /**
      * 以 HTML 格式发送邮件
      *
-     * @param string|array<string> $target
+     * @param Address|string|array<string|Address> $target
      * @param string        $subject
      * @param string        $html
      * @param array<string> $cc
@@ -125,11 +143,13 @@ class EmailService
      * @throws TransportExceptionInterface
      */
     public function sendHtml(
-        string|array $target,
+        Address|string|array $target,
         string $subject,
         string $html,
         array $cc = [],
         array $bcc = [],
+        array $attachmentPaths = [],
+        array $attachments = [],
         int $priority = Email::PRIORITY_NORMAL
     ): bool {
         $email = (new Email())
@@ -141,6 +161,22 @@ class EmailService
             ->subject($subject)
             ->html($html);
 
+        foreach ($attachmentPaths as $attachmentPath) {
+            if (is_string($attachmentPath)) {
+                $email = $email->attachFromPath($attachmentPath);
+            } else {
+                $email = $email->attachFromPath($attachmentPath['path'], $attachmentPath['name'] ?? null, $attachmentPath['mimeType'] ?? null);
+            }
+        }
+
+        foreach ($attachments as $attachment) {
+            if (is_string($attachment)) {
+                $email = $email->attach($attachment);
+            } else {
+                $email = $email->attach($attachment['content'], $attachment['name'] ?? null, $attachment['mimeType'] ?? null);
+            }
+        }
+
         $this->mailer->send($email);
 
         return true;

tests/Unit/EmailServiceTest.php

@@ -1,4 +1,5 @@
 <?php
+
 /**
  * EmailServiceTest.php@HDK-Core
  *
@@ -9,15 +10,19 @@
 
 namespace Singularity\HDK\Test\Core\Service;
 
+use PharIo\Manifest\Email;
 use Singularity\HDK\Core\Service\EmailService;
 use Symfony\Component\Mailer\Exception\TransportException;
 
-$dsn = 'smtp://account@luxcreo.ai:Qfsd8866@smtp.qiye.aliyun.com:465';
-$mail_sender_name = 'LuxCreo';
-$mail_sender = 'account@luxcreo.ai';
-$email = new EmailService($dsn, $mail_sender_name, $mail_sender);
+use function Hyperf\Support\make;
 
-it('assertions that send HTML is available', function () use ($email) {
+
+it('assertions that send HTML is available', function () {
+    $dsn = 'smtp://account@luxcreo.ai:Qfsd8866@smtp.qiye.aliyun.com:465';
+    $mail_sender_name = 'LuxCreo';
+    $mail_sender = 'account@luxcreo.ai';
+    // $email = new EmailService($dsn, $mail_sender_name, $mail_sender);
+    $email = make(EmailService::class, ['dsn' => $dsn, 'mailSenderName' => $mail_sender_name, 'mailSender' => $mail_sender]);
     $result = $email->sendHtml(
         'dongyun.li@luxcreo.ai',
         'HDK Unit Test HTML',
@@ -26,9 +31,15 @@ it('assertions that send HTML is available', function () use ($email) {
 HTML
     );
     expect($result)->toBeTrue();
-})->skip();
+});
+
+it('assertions that send Text is available', function () {
+    $dsn = 'smtp://account@luxcreo.ai:Qfsd8866@smtp.qiye.aliyun.com:465';
+    $mail_sender_name = 'LuxCreo';
+    $mail_sender = 'account@luxcreo.ai';
+    // $email = new EmailService($dsn, $mail_sender_name, $mail_sender);
+    $email = make(EmailService::class, ['dsn' => $dsn, 'mailSenderName' => $mail_sender_name, 'mailSender' => $mail_sender]);
 
-it('assertions that send Text is available', function () use ($email) {
     $result = $email->sendText(
         'dongyun.li@luxcreo.ai',
         'HDK Unit Test Text',
@@ -37,9 +48,15 @@ it('assertions that send Text is available', function () use ($email) {
 Text
     );
     expect($result)->toBeTrue();
-})->skip();
+});
+
+it('assertions Error Receiver can be catch', function () {
+    $dsn = 'smtp://account@luxcreo.ai:Qfsd8866@smtp.qiye.aliyun.com:465';
+    $mail_sender_name = 'LuxCreo';
+    $mail_sender = 'account@luxcreo.ai';
+    // $email = new EmailService($dsn, $mail_sender_name, $mail_sender);
+    $email = make(EmailService::class, ['dsn' => $dsn, 'mailSenderName' => $mail_sender_name, 'mailSender' => $mail_sender]);
 
-it('assertions Error Receiver can be catch', function () use ($email) {
     try {
         $email->sendHtml(
             'unknown@luxcreo.ai',
@@ -62,4 +79,30 @@ Text
     } catch (TransportException $t) {
         expect($t->getCode())->toBe(554);
     }
-})->skip('会报错必须运行在协程环境下');
+});
+
+it('should can contain attachment', function () {
+    $dsn = 'smtp://account@luxcreo.ai:Qfsd8866@smtp.qiye.aliyun.com:465';
+    $mail_sender_name = 'LuxCreo';
+    $mail_sender = 'account@luxcreo.ai';
+    // $email = new EmailService($dsn, $mail_sender_name, $mail_sender);
+    $email = make(EmailService::class, ['dsn' => $dsn, 'mailSenderName' => $mail_sender_name, 'mailSender' => $mail_sender]);
+
+    $email->sendHtml(
+        'dongyun.li@luxcreo.ai',
+        'HDK Unit Test HTML',
+        <<<HTML
+<h1>Hello, World!</h1>
+HTML,
+        [],
+        [],
+        [
+            [
+                'path' => __DIR__ . '/../../README.md',
+                'name' => 'README.md',
+                'mimeType' => 'text/markdown',
+            ],
+        ],
+        []
+    );
+})->only();