状态与依赖
 -> 功能目的和边界
 -> 影响文件、表、缓存、队列和外部服务
 -> 完整文件或明确的局部修改
 -> Migration / Model / Request / Service / Resource / Controller
 -> Middleware / Policy / Permission / Route / Job / Listener
 -> 自动测试
 -> 单行 PowerShell 验证命令
 -> ApiPost 完整请求
 -> 成功与失败预期
 -> 数据库、Redis、队列、Token、日志和 API 文档验证
 -> 为什么这样设计
 -> 完成清单

HTTP Request
  -> Middleware（请求上下文、认证、租户、权限）
  -> FormRequest（输入验证和标准化）
  -> Controller（HTTP 编排）
  -> Service / Action（业务用例和事务边界）
  -> Model / Repository / 外部 Client（数据和外部能力）
  -> JsonResource（输出字段）
  -> ApiResponse（统一响应信封）

$connection = $model->getConnection();

return $connection->transaction(function () use ($model, $data): Model {
    $model->fill($data)->save();

    return $model->refresh();
});

<?php

/**
 * @description 文件的单一职责
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

P00 工程宪法和学习规则
 -> P01 环境、依赖和配置
 -> P02 目录、分层和代码规范
 -> P03 API 契约、异常、验证和文档
 -> P04 中央/租户数据、事务和迁移
 -> P05 Request ID、日志、审计和安全
 -> P06 测试、Factory、Pint 和 CI
 -> P07 Redis Key、限流、锁和基础幂等
 -> P08 Event、Queue、afterCommit 和 Notification 基础
 -> P09 Identity 核心
 -> P10 Tenant 核心
 -> P11 Authorization Scope 和权限核心
 -> P12 Operator 和中央用户管理
 -> P13 模块、Edition 和按需平台能力
 -> P14 Chat、钉钉等业务模块
 -> P15 生产化和私有化交付

文件：app/Platform/Example/Services/ExampleService.php
操作：新建完整文件

文件：app/Platform/Identity/Services/AuthService.php
操作：局部修改
位置：AuthService 类内，revokeAllSessions() 方法之后
新增引入：use App\Platform\Audit\Services\AuditService;
替换范围：完整替换 login() 方法

功能状态：下一步实施 / 已实现待对齐 / 已实现并验证 / 规划草案
所属区域：Platform / Operator / Modules / External Service
数据归属：中央数据库 / 租户数据库 / 外部服务 / 无持久化
Edition：Cloud / Private / 指定模块
前置流程：Pxx、具体文件和已完成能力

Route
 -> Middleware
 -> FormRequest
 -> Controller
 -> Service/Action
 -> Model/Client
 -> Event/Audit/Queue
 -> Resource
 -> ApiResponse

认证 -> 租户初始化 -> 活跃成员 -> Permission -> Policy/资源归属

php -l app\完整路径\File.php

php artisan route:list --path=目标路径 -v

php artisan test --filter=目标测试类

php artisan test

.\vendor\bin\pint --test

Method：GET/POST/PATCH/DELETE
URL：http://demo.localhost:8000/api/完整路径
Header：
  Accept: application/json
  Authorization: Bearer <Access Token>
Query：无 / 完整参数
Path：无 / 完整参数
Body：无 / raw JSON 完整内容

执行阶段：P01
功能状态：已实现待复核
所属区域：工程基础设施
数据归属：无
前置流程：P00 工程宪法和学习规则

PHP：8.4.x
Laravel Framework：13.x
Composer：2.x
PostgreSQL：17.x
Redis Server：本地受控实例
Node.js：仅前端和 Laravel 资源构建需要

php -v; composer --version; php artisan --version; psql --version; redis-cli --version

php -m | Select-String 'bcmath|curl|fileinfo|mbstring|openssl|pdo_pgsql|pgsql|redis|sodium|tokenizer|xml|ctype|json'

php --ini

where.exe php; where.exe composer; composer diagnose

composer install --prefer-dist

composer show --direct; composer audit

APP_NAME=PShangSaaS
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000
APP_TIMEZONE=Asia/Shanghai

LOG_CHANNEL=stack
LOG_LEVEL=debug

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=ps_central
DB_USERNAME=ps_sass_user
DB_PASSWORD=

CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
REDIS_DB=0
REDIS_CACHE_DB=1

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=465
MAIL_USERNAME=no-reply@example.com
MAIL_PASSWORD=
MAIL_ENCRYPTION=ssl
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="${APP_NAME}"

'timezone' => env('APP_TIMEZONE', 'Asia/Shanghai'),

php artisan config:clear; php artisan config:show app.timezone

Test-NetConnection 127.0.0.1 -Port 5432; Test-NetConnection 127.0.0.1 -Port 6379

psql -h 127.0.0.1 -p 5432 -U ps_sass_user -d ps_central -c "SELECT current_database(), current_user, now();"

redis-cli -h 127.0.0.1 -p 6379 ping

php artisan about; php artisan config:show database.default; php artisan config:show cache.default; php artisan config:show queue.default

php artisan migrate:status

php artisan migrate

php artisan key:generate

php artisan passport:keys

php artisan config:clear; php artisan config:show mail.default

php artisan serve --host=127.0.0.1 --port=8000

php artisan queue:work --tries=3 --timeout=90

php artisan route:list --path=up; Invoke-RestMethod -Method Get -Uri 'http://127.0.0.1:8000/up'

执行阶段：P03
功能状态：已实现待对齐
所属区域：app/Support + Laravel bootstrap
数据归属：无
前置流程：P00、P01、P02

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

<?php

/**
 * @description API 统一业务错误码
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-02 12:30:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Enums;

enum ErrorCode: int
{
    case SUCCESS = 0;
    case BUSINESS_ERROR = 40000;
    case UNAUTHENTICATED = 40100;
    case TOKEN_EXPIRED = 40101;
    case REFRESH_TOKEN_INVALID = 40102;
    case CAPTCHA_INVALID = 40110;
    case ACCOUNT_LOCKED = 40120;
    case ACCOUNT_DISABLED = 40121;
    case FORBIDDEN = 40300;
    case NOT_FOUND = 40400;
    case VALIDATION_ERROR = 42200;
    case TOO_MANY_ATTEMPTS = 42900;
    case SERVER_ERROR = 50000;

    /** 获取错误码默认中文消息。 */
    public function message(): string
    {
        return match ($this) {
            self::SUCCESS => '操作成功',
            self::BUSINESS_ERROR => '业务处理失败',
            self::UNAUTHENTICATED => '未登录或登录已过期',
            self::TOKEN_EXPIRED => 'Token 已过期',
            self::REFRESH_TOKEN_INVALID => 'Refresh Token 无效',
            self::CAPTCHA_INVALID => '验证码错误',
            self::ACCOUNT_LOCKED => '账号已被锁定',
            self::ACCOUNT_DISABLED => '账号已被禁用',
            self::FORBIDDEN => '无权限执行此操作',
            self::NOT_FOUND => '资源不存在',
            self::VALIDATION_ERROR => '参数验证失败',
            self::TOO_MANY_ATTEMPTS => '请求过于频繁，请稍后再试',
            self::SERVER_ERROR => '系统内部错误',
        };
    }
}

<?php

/**
 * @description API 统一响应封装
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-02 12:29:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Support;

use App\Enums\ErrorCode;
use Illuminate\Http\JsonResponse;

final class ApiResponse
{
    /** 返回统一成功响应。 */
    public static function success(
        mixed $data = null,
        string $message = '操作成功',
        int $status = 200,
    ): JsonResponse {
        return response()->json([
            'code' => ErrorCode::SUCCESS->value,
            'message' => $message,
            'data' => $data,
        ], $status);
    }

    /** 返回统一错误响应。 */
    public static function error(
        ErrorCode $code,
        ?string $message = null,
        mixed $data = null,
        int $status = 400,
    ): JsonResponse {
        return response()->json([
            'code' => $code->value,
            'message' => $message ?? $code->message(),
            'data' => $data,
        ], $status);
    }
}

<?php

/**
 * @description 平台 API 参数请求基类
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Support\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

abstract class ApiRequest extends FormRequest
{
    /** 路由中间件和 Policy 负责授权，具体 Request 可按需覆盖。 */
    public function authorize(): bool
    {
        return true;
    }
}

 use App\Support\Http\Requests\ApiRequest;
-use Illuminate\Foundation\Http\FormRequest;

-final class LoginRequest extends FormRequest
+final class LoginRequest extends ApiRequest

<?php

/**
 * @description API 列表分页和排序基础请求
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Support\Http\Requests;

class PaginationRequest extends ApiRequest
{
    /** 获取通用分页参数规则。 */
    public function rules(): array
    {
        return [
            'page' => ['sometimes', 'integer', 'min:1'],
            'page_size' => ['sometimes', 'integer', 'min:1', 'max:100'],
            'keyword' => ['sometimes', 'nullable', 'string', 'max:255'],
            'sort_field' => ['sometimes', 'nullable', 'string', 'max:64'],
            'sort_order' => ['sometimes', 'nullable', 'in:asc,desc'],
        ];
    }

    /** 获取经过边界限制的每页数量。 */
    public function pageSize(): int
    {
        return (int) $this->validated('page_size', 20);
    }
}

use App\Support\ApiResponse;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->shouldRenderJsonWhen(
        fn (Request $request, Throwable $exception): bool =>
            $request->is('api/*') || $request->expectsJson(),
    );

    $exceptions->render(
        fn (AuthenticationException $exception, Request $request) =>
            $request->is('api/*')
                ? ApiResponse::error(
                    ErrorCode::UNAUTHENTICATED,
                    status: 401,
                )
                : null,
    );

    $exceptions->render(
        fn (AuthorizationException|UnauthorizedException $exception, Request $request) =>
            $request->is('api/*')
                ? ApiResponse::error(
                    ErrorCode::FORBIDDEN,
                    $exception->getMessage() ?: null,
                    status: 403,
                )
                : null,
    );

    $exceptions->render(
        fn (ModelNotFoundException|NotFoundHttpException $exception, Request $request) =>
            $request->is('api/*')
                ? ApiResponse::error(
                    ErrorCode::NOT_FOUND,
                    status: 404,
                )
                : null,
    );

    $exceptions->render(
        fn (ValidationException $exception, Request $request) =>
            $request->is('api/*')
                ? ApiResponse::error(
                    ErrorCode::VALIDATION_ERROR,
                    data: $exception->errors(),
                    status: 422,
                )
                : null,
    );

    $exceptions->render(function (Throwable $exception, Request $request) {
        if (! $request->is('api/*') || config('app.debug')) {
            return null;
        }

        report($exception);

        return ApiResponse::error(
            ErrorCode::SERVER_ERROR,
            status: 500,
        );
    });
})

return ApiResponse::success(data: [
    'items' => UserResource::collection($paginator->items()),
    'pagination' => [
        'current_page' => $paginator->currentPage(),
        'per_page' => $paginator->perPage(),
        'total' => $paginator->total(),
        'last_page' => $paginator->lastPage(),
    ],
]);

GET http://127.0.0.1:8000/docs/api
GET http://127.0.0.1:8000/docs/api.json

php -l app\Enums\ErrorCode.php; php -l app\Support\ApiResponse.php; php -l app\Support\Http\Requests\ApiRequest.php; php -l app\Support\Http\Requests\PaginationRequest.php; php -l bootstrap\app.php

php artisan test --filter=ApiContractTest; php artisan test; .\vendor\bin\pint --test

Method：GET
URL：http://127.0.0.1:8000/api/not-exists
Header：Accept: application/json
Body：无
预期：HTTP 404，code=40400

Method：GET
URL：http://127.0.0.1:8000/api/admin/auth/me
Header：Accept: application/json
Body：无
预期：HTTP 401，code=40100

执行阶段：P04
功能状态：已实现待对齐
所属区域：Platform 数据基础
数据归属：中央数据库 + 租户数据库
前置流程：P00-P03

表名：
业务所有者：Platform / Operator / Module
数据库：central / tenant / external
Edition：Cloud / Private / Module
主键：bigint / ULID / UUID
唯一约束：
索引：
外键：
删除策略：物理删除 / SoftDeletes / 归档
事务参与者：

<?php

/**
 * @description 中央示例数据模型
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Example\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Stancl\Tenancy\Database\Concerns\CentralConnection;

final class CentralExample extends Model
{
    use CentralConnection;
    use HasFactory;

    /** @var list<string> */
    protected $fillable = [
        'name',
        'status',
        'settings',
    ];

    /** 获取字段类型转换。 */
    protected function casts(): array
    {
        return [
            'settings' => 'array',
        ];
    }
}

<?php

/**
 * @description 租户示例业务模型
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Modules\Example\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Stancl\Tenancy\Database\Concerns\TenantConnection;

final class TenantExample extends Model
{
    use HasFactory;
    use TenantConnection;

    /** @var list<string> */
    protected $fillable = [
        'name',
        'status',
    ];
}

php artisan make:migration create_examples_table

php artisan make:migration create_examples_table --path=database/migrations/tenant

php artisan migrate; php artisan tenants:migrate

php artisan migrate:status; php artisan tenants:run migrate:status --tenants=demo --option=path=database/migrations/tenant

Rule::exists('users', 'id')

$connection = $membership->getConnection();

return $connection->transaction(function () use (
    $membership,
    $attributes,
): TenantMembership {
    $membership->fill($attributes)->save();

    return $membership->refresh();
});

$connection = Passport::token()->getConnection();

return $connection->transaction(function () use ($user): int {
    return $this->revokeAllSessionsWithinTransaction($user);
});

中央 provisioning 状态写入
 -> 创建租户数据库
 -> 执行租户 Migration
 -> 初始化数据
 -> 更新中央状态 active
失败 -> 状态 failed + error_code + retry_count + 可重试入口

Permission::query()->updateOrCreate(
    [
        'name' => 'tenant.members.view',
        'guard_name' => 'api',
    ],
    [],
);

protected static function newFactory(): UserFactory
{
    return UserFactory::new();
}

/** @var class-string<User> */
protected $model = User::class;

php artisan migrate:status; php artisan tenants:run migrate:status --tenants=demo --option=path=database/migrations/tenant; php artisan test --filter=Connection; php artisan test; .\vendor\bin\pint --test

执行阶段：P05
功能状态：部分实现待对齐
所属区域：app/Support + app/Platform/Audit
数据归属：中央审计表 + 日志系统
前置流程：P00-P04

<?php

/**
 * @description 为每个 HTTP 请求生成或透传安全的请求标识
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Support\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

final class AssignRequestId
{
    /** 生成请求上下文并把 Request ID 返回给调用方。 */
    public function handle(Request $request, Closure $next): Response
    {
        $requestId = $request->header('X-Request-ID');

        if (
            ! is_string($requestId)
            || ! preg_match('/^[A-Za-z0-9._-]{8,100}$/', $requestId)
        ) {
            $requestId = (string) Str::uuid();
        }

        $request->attributes->set('request_id', $requestId);

        Log::withContext([
            'request_id' => $requestId,
        ]);

        $response = $next($request);
        $response->headers->set('X-Request-ID', $requestId);

        return $response;
    }
}

use App\Support\Http\Middleware\AssignRequestId;

$middleware->prependToGroup('api', AssignRequestId::class);

<?php

/**
 * @description 对日志和审计上下文中的敏感字段进行递归脱敏
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Support\Logging;

use Illuminate\Support\Str;

final class SensitiveDataRedactor
{
    private const SENSITIVE_KEYS = [
        'password',
        'password_confirmation',
        'access_token',
        'refresh_token',
        'authorization',
        'cookie',
        'client_secret',
        'code',
        'code_verifier',
        'two_factor_secret',
        'two_factor_recovery_codes',
    ];

    /** 对任意嵌套日志上下文进行脱敏。 */
    public function redact(array $context): array
    {
        $redacted = [];

        foreach ($context as $key => $value) {
            if (
                is_string($key)
                && in_array(Str::lower($key), self::SENSITIVE_KEYS, true)
            ) {
                $redacted[$key] = '[REDACTED]';

                continue;
            }

            $redacted[$key] = is_array($value)
                ? $this->redact($value)
                : $value;
        }

        return $redacted;
    }
}

<?php

/**
 * @description 中央平台统一审计写入服务
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Audit\Services;

use App\Platform\Identity\Models\CentralActivity;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;

final class CentralAuditService
{
    /** 注入当前请求以补充 Request ID 和客户端上下文。 */
    public function __construct(
        private readonly Request $request,
    ) {}

    /**
     * 写入一条中央审计记录。
     *
     * @param string $logName 审计分类
     * @param string $event 稳定事件名称
     * @param string $description 中文描述
     * @param Model|null $causer 操作者
     * @param Model|null $subject 目标资源
     * @param array<string, mixed> $properties 已脱敏业务属性
     */
    public function record(
        string $logName,
        string $event,
        string $description,
        ?Model $causer,
        ?Model $subject,
        array $properties = [],
    ): CentralActivity {
        $activity = new CentralActivity;
        $activity->log_name = $logName;
        $activity->event = $event;
        $activity->description = $description;
        $activity->properties = [
            ...$properties,
            'request_id' => $this->request->attributes->get('request_id'),
            'ip_address' => $this->request->ip(),
        ];

        if ($causer !== null) {
            $activity->causer()->associate($causer);
        }

        if ($subject !== null) {
            $activity->subject()->associate($subject);
        }

        $activity->save();

        return $activity;
    }
}

return $target->getConnection()->transaction(function () use ($operator, $target): User {
    $target->save();

    $this->audit->record(
        logName: 'identity-security',
        event: 'account_status_changed',
        description: 'Operator 修改中央账号状态',
        causer: $operator,
        subject: $target,
        properties: ['status' => $target->status->value],
    );

    return $target->refresh();
});

<?php

/**
 * @description 为 HTTP 响应设置通用安全头
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Support\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

final class SecurityHeaders
{
    /** 设置不影响 OAuth 和 API 调试的基础安全头。 */
    public function handle(Request $request, Closure $next): Response
    {
        $response = $next($request);
        $response->headers->set('X-Content-Type-Options', 'nosniff');
        $response->headers->set('X-Frame-Options', 'DENY');
        $response->headers->set('Referrer-Policy', 'strict-origin-when-cross-origin');
        $response->headers->set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');

        if (app()->environment('production')) {
            $response->headers->set(
                'Strict-Transport-Security',
                'max-age=31536000; includeSubDomains',
            );
        }

        return $response;
    }
}

Method：GET
URL：http://127.0.0.1:8000/api/admin/auth/me
Header：
  Accept: application/json
  X-Request-ID: local-test-20260805
  Authorization: Bearer <Access Token>
Body：无
预期：响应 Header 原样返回 X-Request-ID

php -l app\Support\Http\Middleware\AssignRequestId.php; php -l app\Support\Logging\SensitiveDataRedactor.php; php -l app\Platform\Audit\Services\CentralAuditService.php; php -l app\Support\Http\Middleware\SecurityHeaders.php; php -l bootstrap\app.php

php artisan test --filter=RequestId; php artisan test --filter=Audit; php artisan test; .\vendor\bin\pint --test

执行阶段：P06
功能状态：本地测试已实现，集成环境和 CI 待完善
所属区域：工程质量基础设施
数据归属：隔离测试数据库
前置流程：P00-P05

<php>
    <env name="APP_ENV" value="testing"/>
    <env name="APP_DEBUG" value="true"/>
    <env name="BCRYPT_ROUNDS" value="4"/>
    <env name="CACHE_STORE" value="array"/>
    <env name="DB_CONNECTION" value="sqlite" force="true"/>
    <env name="DB_DATABASE" value=":memory:" force="true"/>
    <env name="DB_URL" value=""/>
    <env name="MAIL_MAILER" value="array"/>
    <env name="QUEUE_CONNECTION" value="sync"/>
    <env name="SESSION_DRIVER" value="array"/>
</php>

APP_ENV=testing
APP_DEBUG=true

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=ps_central_test
DB_USERNAME=ps_sass_test
DB_PASSWORD=

CACHE_STORE=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=array
REDIS_DB=14
REDIS_CACHE_DB=15
MAIL_MAILER=array

TENANT_TEST_DATABASE_PREFIX=ps_test_tenant_

<?php

/**
 * @description Laravel 测试基类
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    /** 清理可能残留的租户上下文。 */
    protected function tearDown(): void
    {
        if (tenancy()->initialized) {
            tenancy()->end();
        }

        parent::tearDown();
    }
}

<?php

/**
 * @description 中央用户测试数据工厂
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace Database\Factories;

use App\Platform\Identity\Enums\UserStatus;
use App\Platform\Identity\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;
use Illuminate\Support\Facades\Hash;

/** @extends Factory<User> */
final class UserFactory extends Factory
{
    protected $model = User::class;

    /** 获取中央用户测试数据。 */
    /** @return array<string, mixed> */
    public function definition(): array
    {
        return [
            'name' => fake()->name(),
            'email' => fake()->unique()->safeEmail(),
            'email_verified_at' => now(),
            'password' => Hash::make('password-for-test'),
            'status' => UserStatus::Active,
        ];
    }
}

protected static function newFactory(): UserFactory
{
    return UserFactory::new();
}

<?php

/**
 * @description API Feature Test 完整模板
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace Tests\Feature\Example;

use App\Enums\ErrorCode;
use App\Platform\Identity\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Laravel\Passport\Passport;
use Tests\TestCase;

final class ExampleApiTest extends TestCase
{
    use RefreshDatabase;

    /** 未认证用户不能读取受保护资源。 */
    public function test_resource_requires_authentication(): void
    {
        $this->getJson('/api/example')
            ->assertUnauthorized()
            ->assertJsonPath(
                'code',
                ErrorCode::UNAUTHENTICATED->value,
            );
    }

    /** 已认证用户可以读取资源且不会泄露密码。 */
    public function test_authenticated_user_can_view_resource(): void
    {
        $user = User::factory()->create();
        Passport::actingAs($user);

        $this->getJson('/api/example')
            ->assertOk()
            ->assertJsonPath('code', 0)
            ->assertJsonMissingPath('data.password');
    }
}

Event::fake();
Queue::fake();
Notification::fake();
Http::fake();

php artisan test

php artisan test --filter=AuthTest

.\vendor\bin\pint --test

.\vendor\bin\pint app\Platform\Identity\Services\AuthService.php

composer audit

composer install --no-interaction --prefer-dist
 -> php artisan key:generate
 -> php artisan migrate --force
 -> vendor/bin/pint --test
 -> composer audit
 -> php artisan test
 -> Integration Test

执行阶段：P07
功能状态：登录限流已实现；缓存 Key、锁和幂等为下一步实施
所属区域：app/Support/Cache + app/Support/Http
数据归属：Redis + 中央幂等表
前置流程：P00-P06

<?php

/**
 * @description 中央和租户 Redis Key 统一构建器
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Support\Cache;

use Illuminate\Support\Str;

final class CacheKey
{
    /** 构建中央平台缓存 Key。 */
    public static function central(string ...$segments): string
    {
        return implode(':', [
            Str::slug(config('app.name')),
            app()->environment(),
            'central',
            ...$segments,
        ]);
    }

    /** 构建带租户隔离前缀的缓存 Key。 */
    public static function tenant(string $tenantId, string ...$segments): string
    {
        return implode(':', [
            Str::slug(config('app.name')),
            app()->environment(),
            'tenant',
            $tenantId,
            ...$segments,
        ]);
    }
}

$key = CacheKey::tenant(tenant('id'), 'menus', (string) $user->id);

$menus = Cache::remember($key, now()->addMinutes(10), function () use ($user) {
    return $this->menuService->buildFor($user);
});

$lock = Cache::lock(
    CacheKey::central('tenant-provision', $tenantId),
    120,
);

try {
    return $lock->block(5, fn () => $this->provision($tenantId));
} catch (LockTimeoutException) {
    throw new DomainException('该租户正在处理中，请稍后重试');
} finally {
    $lock->release();
}

use App\Enums\ErrorCode;
use App\Support\ApiResponse;
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\Str;

RateLimiter::for('login', function (Request $request): Limit {
    $email = Str::lower((string) $request->input('email'));

    return Limit::perMinute(5)
        ->by($email.'|'.$request->ip())
        ->response(fn () => ApiResponse::error(
            ErrorCode::TOO_MANY_ATTEMPTS,
            '登录尝试过于频繁，请稍后再试',
            status: 429,
        ));
});

RateLimiter::for('admin-write', fn (Request $request) =>
    Limit::perMinute(60)->by((string) $request->user('api')?->id.'|'.$request->ip())
);

Route::post('/login', [AuthController::class, 'login'])
    ->middleware('throttle:identity-api-login');

Schema::create('idempotency_keys', function (Blueprint $table): void {
    $table->id();
    $table->string('tenant_id')->nullable();
    $table->unsignedBigInteger('user_id')->nullable();
    $table->string('route_name');
    $table->string('key', 100);
    $table->string('request_hash', 64);
    $table->string('status', 20)->default('processing');
    $table->unsignedSmallInteger('response_status')->nullable();
    $table->jsonb('response_body')->nullable();
    $table->timestampTz('expires_at');
    $table->timestampsTz();

    $table->unique(['tenant_id', 'user_id', 'route_name', 'key']);
});

<?php

/**
 * @description 中央幂等请求记录模型
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Idempotency\Models;

use Illuminate\Database\Eloquent\Model;
use Stancl\Tenancy\Database\Concerns\CentralConnection;

final class IdempotencyKey extends Model
{
    use CentralConnection;

    protected $fillable = [
        'tenant_id', 'user_id', 'route_name', 'key', 'request_hash',
        'status', 'response_status', 'response_body', 'expires_at',
    ];

    /** @return array<string, string> */
    protected function casts(): array
    {
        return [
            'response_body' => 'array',
            'expires_at' => 'datetime',
        ];
    }
}

<?php

/**
 * @description API 幂等请求中间件
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Idempotency\Http\Middleware;

use App\Enums\ErrorCode;
use App\Platform\Idempotency\Models\IdempotencyKey;
use App\Support\ApiResponse;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

final class EnsureIdempotentRequest
{
    /** 识别重复请求，并复用第一次成功响应。 */
    public function handle(Request $request, Closure $next): Response
    {
        $key = $request->header('Idempotency-Key');

        if (! is_string($key) || $key === '') {
            return ApiResponse::error(
                ErrorCode::VALIDATION_ERROR,
                'Idempotency-Key 请求头不能为空',
                status: 422,
            );
        }

        $identity = [
            'tenant_id' => tenant()?->getTenantKey(),
            'user_id' => $request->user('api')?->id,
            'route_name' => (string) $request->route()?->getName(),
            'key' => $key,
        ];

        $requestHash = hash('sha256', $request->getContent());
        $record = IdempotencyKey::firstOrCreate($identity, [
            'request_hash' => $requestHash,
            'status' => 'processing',
            'expires_at' => now()->addDay(),
        ]);

        if (! hash_equals($record->request_hash, $requestHash)) {
            return ApiResponse::error(
                ErrorCode::BUSINESS_ERROR,
                '同一幂等键不能用于不同请求',
                status: 409,
            );
        }

        if (! $record->wasRecentlyCreated && $record->status === 'completed') {
            return response()->json($record->response_body, $record->response_status);
        }

        if (! $record->wasRecentlyCreated) {
            return ApiResponse::error(
                ErrorCode::BUSINESS_ERROR,
                '相同请求正在处理中',
                status: 409,
            );
        }

        $response = $next($request);

        if ($response->isSuccessful()) {
            $record->forceFill([
                'status' => 'completed',
                'response_status' => $response->getStatusCode(),
                'response_body' => json_decode($response->getContent(), true),
            ])->save();
        } else {
            $record->delete();
        }

        return $response;
    }
}

Route::post(
    '/conversations/{conversation}/messages',
    [MessageController::class, 'send'],
)->middleware('idempotent');

Idempotency-Key: 每次业务动作生成的UUID

执行阶段：P08
功能状态：邀请通知已使用队列；统一事件和 Job 契约待对齐
所属区域：各领域 Events/Listeners/Jobs + 工程 Queue 配置
数据归属：Redis Queue + failed_jobs
前置流程：P00-P07

<?php

/**
 * @description 租户成员添加完成领域事件
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Tenancy\Events;

use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;

final readonly class TenantMemberAdded implements ShouldDispatchAfterCommit
{
    /** 保存异步 Listener 所需的稳定标识。 */
    public function __construct(
        public string $tenantId,
        public int $membershipId,
        public string $requestId,
    ) {}
}

<?php

/**
 * @description 异步发送租户成员欢迎通知
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Tenancy\Listeners;

use App\Platform\Tenancy\Events\TenantMemberAdded;
use App\Platform\Tenancy\Models\TenantMembership;
use App\Platform\Tenancy\Notifications\TenantMemberWelcomeNotification;
use Illuminate\Contracts\Queue\ShouldQueue;

final class SendTenantMemberWelcomeNotification implements ShouldQueue
{
    public string $queue = 'notifications';

    /** 根据提交后的成员记录发送通知。 */
    public function handle(TenantMemberAdded $event): void
    {
        $membership = TenantMembership::findOrFail($event->membershipId);
        $membership->user->notify(new TenantMemberWelcomeNotification(
            $event->tenantId,
        ));
    }
}

<?php

/**
 * @description 在明确租户上下文中执行异步任务
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Tenancy\Jobs;

use App\Platform\Tenancy\Models\Tenant;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Log;
use Throwable;

final class ProcessTenantTask implements ShouldQueue
{
    use Dispatchable;
    use InteractsWithQueue;
    use Queueable;
    use SerializesModels;

    public int $tries = 3;
    public int $timeout = 120;

    public bool $afterCommit = true;

    public function __construct(
        public readonly string $tenantId,
        public readonly string $requestId,
        public readonly string $idempotencyKey,
    ) {
        $this->onQueue('tenant-tasks');
    }

    /** 获取指数退避秒数。 */
    public function backoff(): array
    {
        return [10, 60, 300];
    }

    /** 初始化租户上下文并执行幂等任务。 */
    public function handle(): void
    {
        $tenant = Tenant::findOrFail($this->tenantId);
        tenancy()->initialize($tenant);

        Log::withContext([
            'request_id' => $this->requestId,
            'tenant_id' => $this->tenantId,
        ]);

        try {
            // 调用一个可重试且具备业务幂等键的 Service。
        } finally {
            tenancy()->end();
        }
    }

    /** 记录最终失败且不包含敏感参数。 */
    public function failed(Throwable $exception): void
    {
        Log::error('租户任务最终失败', [
            'tenant_id' => $this->tenantId,
            'request_id' => $this->requestId,
            'exception' => $exception,
        ]);
    }
}

composer require laravel/horizon

php artisan horizon:install

php artisan migrate

QUEUE_CONNECTION=redis

'environments' => [
    'production' => [
        'supervisor-default' => [
            'connection' => 'redis',
            'queue' => ['default', 'notifications'],
            'balance' => 'auto',
            'maxProcesses' => 10,
            'tries' => 3,
        ],
        'supervisor-ai' => [
            'connection' => 'redis',
            'queue' => ['ai', 'tenant-tasks'],
            'balance' => 'auto',
            'maxProcesses' => 5,
            'timeout' => 300,
            'tries' => 3,
        ],
    ],
],

php artisan queue:failed

php artisan queue:retry 失败任务UUID

php artisan queue:forget 失败任务UUID

Schedule::command('passport:purge')
    ->daily()
    ->withoutOverlapping()
    ->onOneServer();

Schedule::command('app:purge-idempotency-keys')
    ->hourly()
    ->withoutOverlapping()
    ->onOneServer();

Schedule::command('app:check-subscription-expiration')
    ->everyTenMinutes()
    ->withoutOverlapping()
    ->onOneServer();

php artisan schedule:run

php artisan schedule:work

Queue::fake();
ProcessTenantTask::dispatch('demo', 'request-id', 'idempotency-key');
Queue::assertPushed(ProcessTenantTask::class);

执行阶段：P08 按需能力
功能状态：SMTP 和租户邀请邮件已实现；数据库通知中心为规划草案
所属区域：Platform Notification
数据归属：中央 notifications 表 + Queue + Mail Provider
前置流程：P00-P08 队列最小闭环

Schema::create('notifications', function (Blueprint $table): void {
    $table->uuid('id')->primary();
    $table->string('type');
    $table->morphs('notifiable');
    $table->string('tenant_id')->nullable()->index();
    $table->text('data');
    $table->timestampTz('read_at')->nullable();
    $table->timestampsTz();
});

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldBeEncrypted;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;
use App\Platform\Identity\Models\UserInvitation;

<?php

/**
 * @description 租户成员邀请邮件通知
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-03 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Notifications;

use App\Platform\Identity\Models\UserInvitation;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldBeEncrypted;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;

final class TenantInvitationNotification extends Notification implements ShouldBeEncrypted, ShouldQueue
{
    use Queueable;

    public function __construct(
        private readonly UserInvitation $invitation,
        private readonly string $plainToken,
    ) {
        $this->onQueue('notifications');
        $this->afterCommit();
    }

    /** @return array<int, string> */
    public function via(object $notifiable): array
    {
        return ['mail'];
    }

    /** 构建不包含明文 Token 持久化数据的邀请邮件。 */
    public function toMail(object $notifiable): MailMessage
    {
        $url = config('services.frontend.url')
            .'/invitations/accept?token='.urlencode($this->plainToken);

        return (new MailMessage())
            ->subject('租户成员邀请')
            ->line("你被邀请加入租户 {$this->invitation->tenant_id}")
            ->action('接受邀请', $url)
            ->line('邀请链接将在指定时间后过期。');
    }
}

<?php

/**
 * @description 用户站内通知资源
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Notification\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

final class NotificationResource extends JsonResource
{
    /** @return array<string, mixed> */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'tenant_id' => $this->data['tenant_id'] ?? null,
            'type' => $this->data['type'] ?? null,
            'title' => $this->data['title'] ?? null,
            'message' => $this->data['message'] ?? null,
            'read_at' => $this->read_at,
            'created_at' => $this->created_at,
        ];
    }
}

public function index(PaginationRequest $request): JsonResponse
{
    $paginator = $request->user('api')
        ->notifications()
        ->latest()
        ->paginate($request->pageSize());

    return ApiResponse::success(data: [
        'items' => NotificationResource::collection($paginator->items()),
        'pagination' => [
            'current_page' => $paginator->currentPage(),
            'per_page' => $paginator->perPage(),
            'total' => $paginator->total(),
            'last_page' => $paginator->lastPage(),
        ],
    ]);
}

public function markRead(Request $request, string $notification): JsonResponse
{
    $model = $request->user('api')
        ->notifications()
        ->whereKey($notification)
        ->first();

    if ($model === null) {
        return ApiResponse::error(ErrorCode::NOT_FOUND, '通知不存在', status: 404);
    }

    $model->markAsRead();

    return ApiResponse::success(message: '通知已读');
}

Route::get('/notifications', [NotificationController::class, 'index']);
Route::patch('/notifications/{notification}/read', [NotificationController::class, 'markRead']);
Route::patch('/notifications/read-all', [NotificationController::class, 'markAllRead']);

GET http://127.0.0.1:8000/api/admin/notifications?page=1&page_size=20
Authorization: Bearer AccessToken

PATCH http://127.0.0.1:8000/api/admin/notifications/{id}/read
Authorization: Bearer AccessToken

Notification::fake();
$user->notify(new TenantInvitationNotification(
    invitation: $invitation,
    plainToken: 'test-plain-token',
));
Notification::assertSentTo($user, TenantInvitationNotification::class);

执行阶段：P09 Identity 核心
功能状态：A-D 已实现并验证；E 已实现待统一审计归属
所属区域：Platform/Identity + Operator 安全用例
数据归属：中央数据库 OAuth 与审计表
前置流程：P00-P08、Passport、中央 User

/** 仅本地开发启用 Password Grant。 */
if (app()->environment('local')) {
    Passport::enablePasswordGrant();
}

DEV_OAUTH_CLIENT_ID=本地PasswordClientID
DEV_OAUTH_CLIENT_SECRET=本地PasswordClientSecret
DEV_OAUTH_EMAIL=admin@example.com
DEV_OAUTH_PASSWORD=本地测试密码

'dev_oauth' => [
    'client_id' => env('DEV_OAUTH_CLIENT_ID'),
    'client_secret' => env('DEV_OAUTH_CLIENT_SECRET'),
    'email' => env('DEV_OAUTH_EMAIL'),
    'password' => env('DEV_OAUTH_PASSWORD'),
],

use Symfony\Component\HttpFoundation\Request as SymfonyRequest;
use Symfony\Component\HttpFoundation\Response;

/**
 * 本地开发环境快速获取 Access Token 和 Refresh Token。
 *
 * 通过当前 Laravel 进程内部调用 Passport Token 路由，
 * 避免 php artisan serve 单进程请求自己造成超时。
 *
 * @return Response Passport Token 响应
 *
 * @throws \LogicException 非本地环境禁止调用
 */
public function issueDevelopmentToken(): Response
{
    if (! app()->environment('local')) {
        throw new \LogicException('快速 Token 接口只允许在本地环境使用');
    }

    $request = SymfonyRequest::create(
        uri: '/oauth/token',
        method: 'POST',
        parameters: [
            'grant_type' => 'password',
            'client_id' => config('services.dev_oauth.client_id'),
            'client_secret' => config('services.dev_oauth.client_secret'),
            'username' => config('services.dev_oauth.email'),
            'password' => config('services.dev_oauth.password'),
            'scope' => '',
        ],
    );

    return app()->handle($request);
}

/**
 * 本地开发环境快速获取 Access Token 和 Refresh Token。
 *
 * @return JsonResponse Passport Token 响应
 */
public function developmentToken(): JsonResponse
{
    $response = $this->authService->issueDevelopmentToken();

    return response()->json(
        json_decode($response->getContent(), true),
        $response->getStatusCode(),
    );
}

/**
 * 本地开发环境快速获取 Access Token 和 Refresh Token。
 *
 * @method POST
 * @url /api/admin/auth/dev/token
 */
Route::post('/dev/token', [AuthController::class, 'developmentToken'])
    ->name('dev.token');

POST http://127.0.0.1:8000/api/admin/auth/dev/token

{
  "token_type": "Bearer",
  "expires_in": 900,
  "access_token": "...",
  "refresh_token": "..."
}

<?php

/**
 * @description OAuth 登录会话资源
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-03 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

/**
 * @mixin \Laravel\Passport\Token
 */
final class AuthSessionResource extends JsonResource
{
    /**
     * 转换为登录会话响应数据。
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        $currentTokenId = $request->user('api')?->token()?->id;

        return [
            'id' => $this->id,
            'client_id' => $this->client_id,
            'created_at' => $this->created_at,
            'expires_at' => $this->expires_at,
            'revoked' => $this->revoked,
            'is_current' => $currentTokenId === $this->id,
        ];
    }
}

/**
 * 获取当前用户的有效登录会话。
 *
 * @param Request $request 当前请求
 * @return JsonResponse 登录会话列表
 */
public function sessions(Request $request): JsonResponse
{
    $sessions = $request->user('api')
        ->tokens()
        ->where('revoked', false)
        ->where('expires_at', '>', now())
        ->latest('created_at')
        ->get();

    return ApiResponse::success(
        data: [
            'items' => AuthSessionResource::collection($sessions),
        ],
        message: '获取登录会话成功',
    );
}

/**
 * 获取当前用户的有效登录会话。
 *
 * @method GET
 * @url /api/admin/auth/sessions
 * @auth Bearer Token
 */
Route::get('/sessions', [AuthController::class, 'sessions'])
    ->name('sessions.index');

GET http://127.0.0.1:8000/api/admin/auth/sessions
Authorization: Bearer 当前AccessToken
Accept: application/json

/**
 * 撤销当前用户指定的登录会话。
 *
 * @param User $user 当前用户
 * @param string $sessionId 登录会话 ID
 * @return bool 会话存在并撤销成功返回 true
 */
public function revokeSession(User $user, string $sessionId): bool
{
    $token = $user->tokens()
        ->with('refreshToken')
        ->whereKey($sessionId)
        ->first();

    if ($token === null) {
        return false;
    }

    $token->revoke();
    $token->refreshToken?->revoke();

    return true;
}

/**
 * 撤销当前用户指定的登录会话。
 *
 * @param Request $request 当前请求
 * @param string $session 会话 ID
 * @return JsonResponse 撤销结果
 */
public function destroySession(Request $request, string $session): JsonResponse
{
    $revoked = $this->authService->revokeSession(
        $request->user('api'),
        $session,
    );

    if (! $revoked) {
        return ApiResponse::error(
            code: ErrorCode::NOT_FOUND,
            message: '登录会话不存在或不属于当前用户',
            status: 404,
        );
    }

    return ApiResponse::success(
        message: '删除登录会话成功',
    );
}

Route::delete('/sessions/{session}', [AuthController::class, 'destroySession'])
    ->where('session', '[a-f0-9]+')
    ->name('sessions.destroy');

DELETE http://127.0.0.1:8000/api/admin/auth/sessions/会话ID
Authorization: Bearer 当前AccessToken
Accept: application/json

{
  "code": 0,
  "message": "删除登录会话成功",
  "data": null
}

/**
 * 撤销当前用户除当前会话外的所有登录会话。
 *
 * Access Token 即使已经过期，也可能仍有关联的有效 Refresh Token，
 * 因此这里只排除当前 Token，不按 expires_at 过滤。
 *
 * @param User $user 当前用户
 * @param string $currentTokenId 当前 Access Token ID
 * @return int 实际撤销的其他会话数量
 */
public function revokeOtherSessions(
    User $user,
    string $currentTokenId,
): int {
    $tokens = $user->tokens()
        ->with('refreshToken')
        ->where('id', '!=', $currentTokenId)
        ->where('revoked', false)
        ->get();

    $tokens->each(function ($token): void {
        $token->revoke();
        $token->refreshToken?->revoke();
    });

    return $tokens->count();
}

/**
 * 撤销当前用户除当前会话外的所有登录会话。
 *
 * @param Request $request 当前请求
 * @return JsonResponse 撤销结果
 */
public function destroyOtherSessions(Request $request): JsonResponse
{
    $user = $request->user('api');
    $currentToken = $user->token();

    $revokedCount = $this->authService->revokeOtherSessions(
        $user,
        $currentToken->id,
    );

    return ApiResponse::success(
        data: [
            'revoked_count' => $revokedCount,
        ],
        message: '其他登录会话已退出',
    );
}

Route::delete('/sessions/others', [AuthController::class, 'destroyOtherSessions'])
    ->name('sessions.destroy-others');

Route::delete('/sessions/{session}', [AuthController::class, 'destroySession'])
    ->where('session', '[a-f0-9]+')
    ->name('sessions.destroy');

php -l app\Platform\Identity\Services\AuthService.php

php -l app\Platform\Identity\Http\Controllers\AuthController.php

php artisan route:clear

php artisan route:list --path=api/admin/auth/sessions

POST http://127.0.0.1:8000/api/admin/auth/dev/token

DELETE http://127.0.0.1:8000/api/admin/auth/sessions/others
Authorization: Bearer 最后一个AccessToken
Accept: application/json

{
  "code": 0,
  "message": "其他登录会话已退出",
  "data": {
    "revoked_count": 2
  }
}

<?php

/**
 * @description 管理员强制下线请求
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-03 18:40:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Http\Requests;

use App\Support\Http\Requests\ApiRequest;

final class ForceLogoutRequest extends ApiRequest
{
    /**
     * 权限由路由 auth:api 和 permission 中间件负责，
     * 本 Request 只负责验证强制下线原因。
     */
    public function authorize(): bool
    {
        return true;
    }

    /**
     * 获取强制下线请求的验证规则。
     *
     * @return array<string, array<int, string>>
     */
    public function rules(): array
    {
        return [
            'reason' => ['required', 'string', 'max:500'],
        ];
    }

    /**
     * 获取面向前端的中文验证消息。
     *
     * @return array<string, string>
     */
    public function messages(): array
    {
        return [
            'reason.required' => '强制下线原因不能为空',
            'reason.string' => '强制下线原因必须是文本',
            'reason.max' => '强制下线原因不能超过 500 个字符',
        ];
    }
}

use Illuminate\Support\Facades\DB;
use Laravel\Passport\Token;

use App\Platform\Identity\Http\Requests\ForceLogoutRequest;
use App\Platform\Identity\Models\User;

ForceLogoutUserService::execute()
 -> 从 Passport Token Model 取得中央连接
 -> 验证 Token 与中央审计使用同一连接
 -> 开启一次中央事务
 -> AuthService::revokeAllSessionsWithinTransaction()
 -> 统一审计 Service 写 force_logout
 -> 提交事务并返回 revoked_count

/**
 * 强制撤销指定中央用户的全部登录会话。
 *
 * @param ForceLogoutRequest $request 强制下线参数
 * @param User $user 目标中央用户
 * @return JsonResponse 强制下线结果
 */
public function forceLogout(
    ForceLogoutRequest $request,
    User $user,
): JsonResponse {
    $revokedCount = $this->forceLogoutService->execute(
        operator: $request->user('api'),
        target: $user,
        reason: $request->validated('reason'),
    );

    return ApiResponse::success(
        data: ['revoked_count' => $revokedCount],
        message: '用户已强制下线',
    );
}

/**
 * 强制下线指定中央用户的全部登录会话。
 *
 * @method POST
 * @url /api/operator/users/{user}/force-logout
 * @auth Bearer Token
 * @permission platform.users.force_logout
 */
Route::post('/users/{user}/force-logout', [UserSessionController::class, 'forceLogout'])
    ->whereNumber('user')
    ->middleware(
        'permission:'.OperatorPermission::ForceLogoutUser->value,
    )
    ->name('users.force-logout');

platform.users.force_logout

POST http://127.0.0.1:8000/api/operator/users/2/force-logout

Authorization: Bearer 有 platform.users.force_logout 权限的管理员Token
Accept: application/json
Content-Type: application/json

{
  "reason": "账号安全处置测试"
}

{
  "code": 0,
  "message": "用户已强制下线",
  "data": {
    "revoked_count": 2
  }
}

{
  "code": 40300,
  "message": "没有执行强制下线的权限",
  "data": null
}

{
  "code": 42200,
  "message": "参数验证失败",
  "data": {
    "reason": ["强制下线原因不能为空"]
  }
}

执行阶段：P09 Identity 核心
功能状态：邀请与账号状态已有实现，待按统一审计和队列规则回归
所属区域：Platform/Identity + Platform/Tenancy
数据归属：中央数据库 + Notification Queue
前置流程：P00-P09 登录安全、P10 Tenant 核心、P08 Queue/Notification

php artisan make:migration create_user_invitations_table

// 文件：database/migrations/YYYY_MM_DD_HHMMSS_create_user_invitations_table.php
// 需要引入：use Illuminate\Database\Schema\Blueprint;
// 需要引入：use Illuminate\Support\Facades\Schema;
// 该迁移使用中央数据库连接，不能放入 database/migrations/tenant。
Schema::create('user_invitations', function (Blueprint $table): void {
    $table->uuid('id')->primary();
    $table->string('tenant_id');
    $table->string('email');
    $table->string('role_name')->nullable();
    $table->string('token_hash', 64)->unique();
    $table->string('status', 20)->default('pending');
    $table->foreignId('invited_by')->constrained('users');
    $table->timestampTz('expires_at');
    $table->timestampTz('accepted_at')->nullable();
    $table->timestampsTz();

    $table->index(['tenant_id', 'email']);
    $table->index(['tenant_id', 'status']);
});

// 文件：database/migrations/YYYY_MM_DD_HHMMSS_create_user_invitations_table.php
// 需要引入：use Illuminate\Support\Facades\Schema;
Schema::dropIfExists('user_invitations');

<?php

/**
 * @description 中央用户邀请模型
 * @author Yanhong <jackyan@pshang.net>
 * @createTime YYYY-MM-DD HH:mm:ss
 * @lastModified YYYY-MM-DD HH:mm:ss
 */

namespace App\Platform\Identity\Models;

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Stancl\Tenancy\Database\Concerns\CentralConnection;

class UserInvitation extends Model
{
    /**
     * 中央数据库中的租户成员邀请模型。
     *
     * 原始邀请 Token 只在邮件中出现，模型只保存 token_hash。
     */
    use CentralConnection;
    use HasUuids;

    protected $fillable = [
        'tenant_id',
        'email',
        'role_name',
        'token_hash',
        'status',
        'invited_by',
        'expires_at',
        'accepted_at',
    ];

    protected $hidden = [
        'token_hash',
    ];

    /**
     * 获取邀请时间字段的类型转换规则。
     *
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'expires_at' => 'datetime',
            'accepted_at' => 'datetime',
        ];
    }

    /** 获取发起邀请的中央用户。 */
    public function inviter(): BelongsTo
    {
        return $this->belongsTo(User::class, 'invited_by');
    }
}

<?php

/**
 * @description 租户管理员邀请用户请求
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Http\Requests;

use App\Support\Http\Requests\ApiRequest;

final class InviteUserRequest extends ApiRequest
{
    /**
     * 权限由路由中间件负责，本 Request 只负责参数验证。
     */
    public function authorize(): bool
    {
        return true;
    }

    /**
     * 获取创建邀请的验证规则。
     *
     * @return array<string, array<int, mixed>>
     */
    public function rules(): array
    {
        return [
            'email' => ['required', 'email', 'max:255'],
            'role_name' => ['nullable', 'string', 'max:100'],
        ];
    }

    /**
     * 获取创建邀请的中文验证消息。
     *
     * @return array<string, string>
     */
    public function messages(): array
    {
        return [
            'email.required' => '邮箱不能为空',
            'email.email' => '邮箱格式不正确',
            'role_name.max' => '角色名称不能超过 100 个字符',
        ];
    }
}

<?php

/**
 * @description 用户接受租户邀请请求
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Http\Requests;

use App\Support\Http\Requests\ApiRequest;
use Illuminate\Validation\Rules\Password;

final class AcceptInvitationRequest extends ApiRequest
{
    /**
     * 接受邀请不依赖登录态，Token 由 Service 校验。
     */
    public function authorize(): bool
    {
        return true;
    }

    /**
     * 获取接受邀请的验证规则。
     *
     * @return array<string, array<int, mixed>>
     */
    public function rules(): array
    {
        return [
            'token' => ['required', 'string'],
            'name' => ['nullable', 'string', 'max:255'],
            'password' => ['nullable', 'confirmed', Password::default()],
        ];
    }

    /**
     * 获取接受邀请的中文验证消息。
     *
     * @return array<string, string>
     */
    public function messages(): array
    {
        return [
            'token.required' => '邀请 Token 不能为空',
            'password.confirmed' => '两次输入的密码不一致',
        ];
    }
}

// 文件：app/Platform/Identity/Services/InvitationService.php
// 需要引入：use App\Platform\Identity\Models\UserInvitation;
// 需要引入：use App\Platform\Identity\Models\User;
// 需要引入：use App\Platform\Tenancy\Models\TenantMembership;
// 需要引入：use Illuminate\Support\Str;
// 需要引入：use DomainException;
/**
 * 创建租户成员邀请。
 *
 * @return array{invitation: UserInvitation, plain_token: string}
 */
public function create(
    User $inviter,
    string $tenantId,
    string $email,
    ?string $roleName,
): array {
    // 事务连接从中央模型获取，避免依赖默认连接或手写连接名称。
    $connection = (new UserInvitation())->getConnection();

    return $connection->transaction(function () use ($inviter, $tenantId, $email, $roleName): array {
        $exists = TenantMembership::query()
        ->where('tenant_id', $tenantId)
        ->whereHas('user', fn ($query) => $query->where('email', $email))
        ->exists();

        if ($exists) {
            throw new DomainException('该用户已经是当前租户成员');
        }

    UserInvitation::query()
        ->where('tenant_id', $tenantId)
        ->where('email', $email)
        ->where('status', 'pending')
        ->update(['status' => 'revoked']);

    $plainToken = Str::random(64);

    $invitation = UserInvitation::create([
        'tenant_id' => $tenantId,
        'email' => Str::lower($email),
        'role_name' => $roleName,
        'token_hash' => hash('sha256', $plainToken),
        'status' => 'pending',
        'invited_by' => $inviter->id,
        'expires_at' => now()->addDays(3),
    ]);

        return [
            'invitation' => $invitation,
            'plain_token' => $plainToken,
        ];
    });
}

// 文件：app/Platform/Identity/Services/InvitationService.php
// 需要引入：use App\Platform\Identity\Models\User;
// 需要引入：use App\Platform\Identity\Models\UserInvitation;
// 需要引入：use App\Platform\Tenancy\Models\TenantMembership;
// 需要引入：use Illuminate\Support\Facades\Hash;
// 需要引入：use Illuminate\Validation\ValidationException;
/**
 * 接受邀请并建立中央用户与租户成员关系。
 */
public function accept(
    string $plainToken,
    ?string $name,
    ?string $password,
): TenantMembership {
    $invitation = UserInvitation::query()
        ->where('token_hash', hash('sha256', $plainToken))
        ->first();

    if ($invitation === null
        || $invitation->status !== 'pending'
        || $invitation->expires_at->isPast()) {
        throw new DomainException('邀请不存在或已失效');
    }

    // 事务连接从邀请模型获取，确保相关记录使用同一中央数据库。
    $connection = $invitation->getConnection();

    return $connection->transaction(function () use ($invitation, $name, $password): TenantMembership {
            $user = User::where('email', $invitation->email)->first();

            if ($user === null) {
                if ($name === null || $password === null) {
                    throw ValidationException::withMessages([
                        'password' => ['新用户必须填写姓名和密码'],
                    ]);
                }

                $user = User::create([
                    'name' => $name,
                    'email' => $invitation->email,
                    'password' => Hash::make($password),
                ]);
            }

            $membership = TenantMembership::firstOrCreate(
                [
                    'tenant_id' => $invitation->tenant_id,
                    'user_id' => $user->id,
                ],
                [
                    'status' => 'active',
                    'is_owner' => false,
                    'joined_at' => now(),
                ],
            );

            $invitation->forceFill([
                'status' => 'accepted',
                'accepted_at' => now(),
            ])->save();

            return $membership;
        });
}

// 文件：app/Platform/Identity/Http/Controllers/TenantInvitationController.php
// 需要引入：use App\Platform\Identity\Http\Requests\InviteUserRequest;
// 需要引入：use App\Platform\Identity\Services\InvitationService;
// 需要引入：use App\Support\ApiResponse;
// 需要引入：use Illuminate\Http\JsonResponse;
/**
 * 创建租户成员邀请并触发邀请通知。
 *
 * @param InviteUserRequest $request 已验证的邀请参数
 * @param InvitationService $service 邀请业务服务
 * @return JsonResponse 邀请创建结果
 */
public function invite(
    InviteUserRequest $request,
    InvitationService $service,
): JsonResponse {
    $result = $service->create(
        $request->user('api'),
        tenant('id'),
        $request->validated('email'),
        $request->validated('role_name'),
    );

    // 正式环境使用 Notification 发送 Token，不在 API 返回原始 Token。
    // local 环境如需调试，可以只写 Mailpit 或测试日志。

    return ApiResponse::success(
        data: ['id' => $result['invitation']->id],
        message: '邀请邮件已发送',
    );
}

// 文件：app/Platform/Identity/Http/Controllers/AuthController.php
// 需要引入：use App\Platform\Identity\Http\Requests\AcceptInvitationRequest;
// 需要引入：use App\Platform\Identity\Services\InvitationService;
// 需要引入：use App\Platform\Tenancy\Http\Resources\TenantMemberResource;
// 需要引入：use App\Support\ApiResponse;
// 需要引入：use Illuminate\Http\JsonResponse;
/**
 * 接受公开邀请并建立中央用户与租户成员关系。
 *
 * @param AcceptInvitationRequest $request 已验证的邀请参数
 * @param InvitationService $service 邀请业务服务
 * @return JsonResponse 新成员关系
 */
public function acceptInvitation(
    AcceptInvitationRequest $request,
    InvitationService $service,
): JsonResponse {
    $membership = $service->accept(
        $request->validated('token'),
        $request->validated('name'),
        $request->validated('password'),
    );

    return ApiResponse::success(
        data: new TenantMemberResource($membership->load('user')),
        message: '接受邀请成功',
    );
}

/**
 * 创建租户成员邀请。
 *
 * @method POST
 * @url /api/tenant/members/invitations
 * @auth Bearer Token
 * @permission tenant.members.manage
 */
Route::post('/members/invitations', [TenantInvitationController::class, 'invite'])
    ->middleware('permission:tenant.members.manage')
    ->name('tenant.members.invitations.store');

/**
 * 接受公开的租户成员邀请。
 *
 * @method POST
 * @url /api/admin/auth/invitations/accept
 * @auth Public + throttle:login
 */
Route::post('/admin/auth/invitations/accept', [AuthController::class, 'acceptInvitation'])
    ->middleware('throttle:login')
    ->name('admin.auth.invitations.accept');

POST http://demo.localhost:8000/api/tenant/members/invitations
Authorization: Bearer 租户管理员AccessToken
Content-Type: application/json

{
  "email": "new-user@example.com",
  "role_name": "tenant-member"
}

POST http://127.0.0.1:8000/api/admin/auth/invitations/accept
Content-Type: application/json

{
  "token": "邮件中的邀请Token",
  "name": "新成员",
  "password": "符合规则的密码",
  "password_confirmation": "相同密码"
}

php artisan make:migration add_status_columns_to_users_table

// 文件：database/migrations/YYYY_MM_DD_HHMMSS_add_status_columns_to_users_table.php
// 需要引入：use Illuminate\Database\Schema\Blueprint;
// 需要引入：use Illuminate\Support\Facades\Schema;
Schema::table('users', function (Blueprint $table): void {
    $table->string('status', 20)->default('active')->index();
    $table->timestampTz('locked_at')->nullable();
    $table->string('disabled_reason', 500)->nullable();
});

// 文件：app/Platform/Identity/Models/User.php
// User 模型已经引入 CentralConnection；这里只补充 casts 方法的 PHPDoc。
/**
 * 获取中央用户状态字段的类型转换规则。
 *
 * @return array<string, string>
 */
protected function casts(): array
{
    return [
        'email_verified_at' => 'datetime',
        'password' => 'hashed',
        'locked_at' => 'datetime',
    ];
}

/**
 * 在签发 Access Token 前拒绝非 active 状态的用户。
 *
 * @throws DomainException 账号不可登录时抛出
 */
if ($user->status !== 'active') {
    throw new DomainException('账号当前不可登录');
}

验证不能禁用当前 Operator 自己
 -> 验证 User、Passport Token、中央审计使用同一连接
 -> 开启中央事务并 lockForUpdate
 -> 相同状态幂等返回 changed=false
 -> 禁用前保护最后一个有效平台超级管理员
 -> 更新 UserStatus、操作人、时间和原因
 -> 禁用时撤销全部 Access/Refresh Token
 -> 写中央安全审计
 -> 返回 user/revoked_count/changed

/**
 * 更新中央用户账号状态。
 *
 * @method PATCH
 * @url /api/operator/users/{user}/status
 * @auth Bearer Token
 * @permission platform.users.status.update
 */
Route::patch('/users/{user}/status', [UserAccountController::class, 'updateStatus'])
    ->whereNumber('user')
    ->middleware(
        'permission:'.OperatorPermission::ManageUserStatus->value,
    )
    ->name('users.status.update');

PATCH http://127.0.0.1:8000/api/operator/users/2/status
Authorization: Bearer 平台安全管理员Token
Content-Type: application/json

{
  "status": "locked",
  "reason": "连续异常登录"
}

执行阶段：P09 Identity 扩展
功能状态：登录安全事件部分实现；MFA 与外部身份为规划草案
所属区域：Platform/Identity
数据归属：中央数据库
前置流程：Identity 登录闭环、Request ID、审计、限流、Queue

Features::twoFactorAuthentication([
    'confirm' => true,
    'confirmPassword' => true,
]),

two_factor_secret
two_factor_recovery_codes
two_factor_confirmed_at

use Laravel\Fortify\TwoFactorAuthenticatable;

use TwoFactorAuthenticatable;

POST   /api/admin/auth/mfa/enable
POST   /api/admin/auth/mfa/confirm
GET    /api/admin/auth/mfa/recovery-codes
POST   /api/admin/auth/mfa/recovery-codes
DELETE /api/admin/auth/mfa

<?php

/**
 * @description 确认多因素认证验证码请求
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Http\Requests;

use App\Support\Http\Requests\ApiRequest;

final class ConfirmMfaRequest extends ApiRequest
{
    /** 认证和权限由路由中间件负责。 */
    public function authorize(): bool
    {
        return true;
    }

    /** @return array<string, array<int, string>> */
    public function rules(): array
    {
        return [
            'code' => ['required', 'string', 'size:6'],
        ];
    }
}

php artisan make:migration create_user_identities_table

Schema::create('user_identities', function (Blueprint $table): void {
    $table->id();
    $table->foreignId('user_id')->constrained('users')->cascadeOnDelete();
    $table->string('provider', 50);
    $table->string('provider_subject');
    $table->jsonb('profile')->nullable();
    $table->timestampTz('last_login_at')->nullable();
    $table->timestampsTz();

    $table->unique(['provider', 'provider_subject']);
    $table->unique(['user_id', 'provider']);
});

<?php

/**
 * @description 中央用户外部身份绑定模型
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Stancl\Tenancy\Database\Concerns\CentralConnection;

final class UserIdentity extends Model
{
    use CentralConnection;

    protected $fillable = [
        'user_id',
        'provider',
        'provider_subject',
        'profile',
        'last_login_at',
    ];

    /** @return array<string, string> */
    protected function casts(): array
    {
        return [
            'profile' => 'array',
            'last_login_at' => 'datetime',
        ];
    }

    /** 获取该外部身份所属的中央用户。 */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

<?php

/**
 * @description 外部身份提供方适配契约
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Contracts;

use App\Platform\Identity\Data\ExternalIdentityData;

interface ExternalIdentityProvider
{
    /** 生成带状态参数的提供方授权地址。 */
    public function authorizationUrl(string $state): string;

    /** 使用一次性授权码换取标准化外部身份。 */
    public function exchangeCode(string $code): ExternalIdentityData;
}

<?php

/**
 * @description 标准化外部身份数据
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Platform\Identity\Data;

final readonly class ExternalIdentityData
{
    /** @param array<string, mixed> $profile 提供方返回的非敏感资料 */
    public function __construct(
        public string $provider,
        public string $subject,
        public ?string $email,
        public array $profile,
    ) {}
}

public function loginOrBind(ExternalIdentityData $identity): User
{
    $binding = UserIdentity::query()
        ->where('provider', $identity->provider)
        ->where('provider_subject', $identity->subject)
        ->first();

    if ($binding === null) {
        throw new DomainException('该外部身份尚未绑定平台账号');
    }

    if ($binding->user->status !== 'active') {
        throw new DomainException('账号当前不可登录');
    }

    $binding->forceFill([
        'profile' => $identity->profile,
        'last_login_at' => now(),
    ])->save();

    return $binding->user;
}

Route::get('/external/{provider}/redirect', [ExternalAuthController::class, 'redirect']);
Route::get('/external/{provider}/callback', [ExternalAuthController::class, 'callback']);
Route::post('/external/{provider}/bind', [ExternalIdentityController::class, 'bind'])
    ->middleware('auth:api');
Route::delete('/external/{provider}', [ExternalIdentityController::class, 'unbind'])
    ->middleware('auth:api');

密码错误/账号禁用/限流
 -> IdentityLoginEventService
 -> IdentityLoginOccurred
 -> PersistIdentityLoginEvent

Passport 成功签发 Token
 -> AccessTokenCreated
 -> RecordPassportAccessToken
 -> IdentityLoginEventService

Method：GET
URL：http://127.0.0.1:8000/api/admin/auth/login-events?page=1&page_size=20
Header：Accept: application/json、Authorization: Bearer <Access Token>
Body：无

执行阶段：P10 Tenant 核心
功能状态：租户、域名、成员和独立库基础已实现；生命周期状态机待完善
所属区域：Platform/Tenancy
数据归属：中央控制面 + 独立租户数据库
前置流程：P00-P08、Identity 中央用户

php artisan make:migration add_provisioning_columns_to_tenants_table

Schema::table('tenants', function (Blueprint $table): void {
    $table->string('name')->nullable();
    $table->string('status', 30)->default('provisioning')->index();
    $table->text('provisioning_error')->nullable();
    $table->timestampTz('provisioned_at')->nullable();
    $table->timestampTz('suspended_at')->nullable();
});

<?php

/**
 * @description 创建并开通租户请求
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Operator\Http\Requests;

use App\Support\Http\Requests\ApiRequest;

final class CreateTenantRequest extends ApiRequest
{
    /** 授权由 Operator 路由权限中间件负责。 */
    public function authorize(): bool
    {
        return true;
    }

    /** @return array<string, array<int, string>> */
    public function rules(): array
    {
        return [
            'id' => ['required', 'string', 'min:3', 'max:50', 'regex:/^[a-z0-9-]+$/', 'unique:tenants,id'],
            'name' => ['required', 'string', 'max:255'],
            'domain' => ['required', 'string', 'max:255', 'unique:domains,domain'],
            'owner_user_id' => ['required', 'integer', 'exists:users,id'],
        ];
    }
}

/**
 * 创建并初始化一个数据库隔离租户。
 *
 * @param array{id:string,name:string,domain:string,owner_user_id:int} $data
 * @return Tenant
 */
public function provision(array $data): Tenant
{
    $tenant = Tenant::firstOrCreate(
        ['id' => $data['id']],
        [
            'name' => $data['name'],
            'status' => 'provisioning',
        ],
    );

    if ($tenant->status === 'active') {
        return $tenant;
    }

    try {
        if (! $tenant->domains()->where('domain', $data['domain'])->exists()) {
            $tenant->domains()->create(['domain' => $data['domain']]);
        }

        // Stancl 的 TenantCreated 监听器负责创建数据库时，不要再次手工创建。
        tenancy()->initialize($tenant);

        Artisan::call('tenants:migrate', [
            '--tenants' => [$tenant->getTenantKey()],
            '--force' => true,
        ]);

        tenancy()->end();

        TenantMembership::firstOrCreate(
            [
                'tenant_id' => $tenant->getTenantKey(),
                'user_id' => $data['owner_user_id'],
            ],
            [
                'status' => 'active',
                'is_owner' => true,
                'joined_at' => now(),
            ],
        );

        $tenant->forceFill([
            'status' => 'active',
            'provisioning_error' => null,
            'provisioned_at' => now(),
        ])->save();

        return $tenant->refresh();
    } catch (Throwable $exception) {
        tenancy()->end();

        $tenant->forceFill([
            'status' => 'failed',
            'provisioning_error' => Str::limit($exception->getMessage(), 2000),
        ])->save();

        throw $exception;
    }
}

public function toArray(Request $request): array
{
    return [
        'id' => $this->getTenantKey(),
        'name' => $this->name,
        'status' => $this->status,
        'domains' => $this->whenLoaded('domains', fn () => $this->domains->pluck('domain')),
        'provisioned_at' => $this->provisioned_at,
    ];
}

public function store(
    CreateTenantRequest $request,
    TenantProvisioningService $service,
): JsonResponse {
    $tenant = $service->provision($request->validated());

    return ApiResponse::success(
        data: new TenantResource($tenant->load('domains')),
        message: '租户创建成功',
    );
}

Route::post('/operator/tenants', [OperatorTenantController::class, 'store'])
    ->middleware(['auth:api', 'permission:operator.tenants.create'])
    ->name('operator.tenants.store');

POST http://127.0.0.1:8000/api/operator/tenants
Authorization: Bearer 运营管理员Token
Content-Type: application/json

{
  "id": "customer-a",
  "name": "客户 A",
  "domain": "customer-a.localhost",
  "owner_user_id": 2
}

<?php

/**
 * @description 暂停租户请求
 * @author Yanhong <jackyan@pshang.net>
 * @createTime 2026-08-05 00:00:00
 * @lastModified 2026-08-05 00:00:00
 */

namespace App\Operator\Http\Requests;

use App\Support\Http\Requests\ApiRequest;

final class SuspendTenantRequest extends ApiRequest
{
    /** @return array<string, array<int, string>> */
    public function rules(): array
    {
        return ['reason' => ['required', 'string', 'max:500']];
    }
}

public function suspend(Tenant $tenant, string $reason): Tenant
{
    if ($tenant->status !== 'active') {
        throw new DomainException('只有正常租户可以暂停');
    }

    $tenant->forceFill([
        'status' => 'suspended',
        'suspended_at' => now(),
        'data' => array_merge($tenant->data ?? [], ['suspend_reason' => $reason]),
    ])->save();

    return $tenant->refresh();
}

public function resume(Tenant $tenant): Tenant
{
    if ($tenant->status !== 'suspended') {
        throw new DomainException('只有暂停租户可以恢复');
    }

    // 恢复前应检查数据库连接和迁移状态。
    $tenant->forceFill([
        'status' => 'active',
        'suspended_at' => null,
    ])->save();

    return $tenant->refresh();
}

if (tenant('status') !== 'active') {
    return ApiResponse::error(
        code: ErrorCode::FORBIDDEN,
        message: '当前租户已暂停服务',
        status: 403,
    );
}