From 3db3f7de78ab9454a24272e2bdd055bbed365b1d Mon Sep 17 00:00:00 2001
From: augushong <augushong@163.com>
Date: Sat, 25 Jul 2026 21:57:39 +0800
Subject: [PATCH] =?UTF-8?q?feat(timer):=20syncConfig=20concurrency=20?=
 =?UTF-8?q?=E4=B8=8D=E5=8F=98=E9=87=8F=E4=B8=8E=E6=8E=A7=E5=88=B6=E5=99=A8?=
 =?UTF-8?q?=20cap=20=E9=98=B2=E5=BE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TimerServiceBase syncConfig 不覆盖 DB concurrency（NULL=继承代码默认）。TimerControllerBase cap 改 >= 语义，放行 concurrency_id < cap 的 0-indexed 分片。

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 .../base/common/controller/TimerControllerBase.php   | 12 +++++++++++-
 extend/base/common/service/TimerServiceBase.php      |  5 +++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/extend/base/common/controller/TimerControllerBase.php b/extend/base/common/controller/TimerControllerBase.php
index a60e17a..ed79f41 100644
--- a/extend/base/common/controller/TimerControllerBase.php
+++ b/extend/base/common/controller/TimerControllerBase.php
@@ -10,6 +10,14 @@ class TimerControllerBase extends ToolsController
 {
     protected $frequency = null;
 
+    /**
+     * 最大并发上限 cap.
+     * 放行 concurrency_id < $concurrency 的请求（0-indexed 分片，合法 id ∈ [0, cap-1]）；
+     * 放行 concurrency_count <= $concurrency 的请求（并发总数声明，合法 ∈ [1, cap]）。
+     * DB 实际并发通过 T6 有效域钳制 = min(DB concurrency, 控制器 cap, max_handles 预算)，
+     * 动态扩容时高 concurrency_id 只要 < cap 就不会被误杀。
+     * 子类按任务实际承载力自行设置（默认 1 = 单分片，只允许 id=0）。
+     */
     protected $concurrency = 1;
 
     protected $concurrencyId = 0;
@@ -21,12 +29,14 @@ class TimerControllerBase extends ToolsController
         parent::initialize();
 
         $concurrency_id = $this->request->param('concurrency_id', 0);
-        if ($concurrency_id > $this->concurrency) {
+        // cap 防御：0-indexed 分片号，合法 id ∈ [0, cap-1]；id >= cap 视为越界（超 cap 的分片不被本控制器承载）
+        if ($concurrency_id >= $this->concurrency) {
             $this->error('concurrency id error');
         }
         $this->concurrencyId = $concurrency_id;
 
         $concurrency_count = $this->request->param('concurrency_count', 1);
+        // cap 防御：并发总数声明，合法 ∈ [1, cap]；count > cap 视为超限（DB concurrency 经 T6 钳制后不会超过 cap）
         if ($concurrency_count > $this->concurrency) {
             $this->error('concurrency count error');
         }
diff --git a/extend/base/common/service/TimerServiceBase.php b/extend/base/common/service/TimerServiceBase.php
index 4e8a715..4672022 100644
--- a/extend/base/common/service/TimerServiceBase.php
+++ b/extend/base/common/service/TimerServiceBase.php
@@ -13,6 +13,11 @@ class TimerServiceBase
     /**
      * 将配置文件中的定时任务同步到数据库.
      * 仅新增不存在的记录，标记孤立记录，不覆盖 run_type/status.
+     *
+     * concurrency 不变量（DB 为准）：
+     * - 新建行不写 concurrency，列 nullable 自然得 NULL（NULL = 继承代码 config 默认值）；
+     * - 已有行即便 config 中 concurrency 变化也不覆盖（以 UI/DB 显式配置为准）。
+     * config 的 concurrency 仅作为代码默认供 NULL 行继承，永不在此同步写入 DB。
      */
     public static function syncConfigToDatabase(): void
     {