docs(agents): 落实按主题单一文档原则,合并规则到对应技能

- AGENTS.md 代码分层铁律精简为入口摘要,链接指向技能详情
- 合并 ulthon-timer-multi-node 规则到 ulthon-timer 技能(多节点协调章节)
- 合并 ulthon-database-design 规则到 ulthon-scheme-definition 技能(含字段约定、组件类型)
- 合并 ulthon-testing 规则到 ulthon-testing 技能(含设计哲学、决策树、测试约束)
- rules-manager 边界原则从规则/技能二分改为按主题单一文档
- AGENTS.md 通用基础规范中表结构规范链接改向技能
- 工作流索引中三个技能描述扩充(明确承载原规则内容)
This commit is contained in:
augushong
2026-07-19 09:07:42 +08:00
parent 1f91abe9d2
commit e392db007a
8 changed files with 340 additions and 430 deletions

View File

@@ -220,21 +220,19 @@ site 任务会按站点域名发起请求,默认从 `sysconfig('site','site_do
## 多节点协调
定时器支持多节点部署,以数据库MySQL为协调中心。多个节点连接同一个数据库即自动组成集群。
定时器支持多节点部署,以数据库为协调中心。多个节点连接同一个数据库即自动组成集群,无需额外服务发现
### 节点注册
### 设计决策
每个节点启动后通过 `system_host_register` call 任务自动注册心跳(每 30 秒一次)。节点 ID 生成规则为 `{hostname}-{8位md5}`,持久化在 `runtime/node_id.lock` 文件中,重启后保持不变。
- **以数据库为协调中心**:多节点连接同一个数据库即自动组成集群
- **主节点自动选举**:第一个注册的节点自动成为主节点;管理员可在主机列表页面手动切换
- **节点身份持久化**:节点 ID`{hostname}-{8位md5}`)写入 `runtime/node_id.lock`,重启保持不变
- **节点心跳**:通过 `system_host_register` call 任务每 30 秒自动注册一次
- **配置通过 UI 管理**`run_type``status`、手动触发等均由管理后台维护
### 主节点选举
### run_type 调度模式
- 第一个注册的节点自动成为主节点
- 管理员可在主机列表页面手动切换主节点
- 相关 API`HostService::setMasterNode()` / `HostService::getMasterNode()`
### run_type 调度
`run_type` 仅对 `site` 类型任务生效,`call` 类型任务始终在所有节点执行。可选值:
`run_type` 仅对 `site` 类型任务生效;`call` 类型任务始终在所有节点执行。
| run_type | 行为 | 适用场景 |
|----------|------|----------|
@@ -243,13 +241,22 @@ site 任务会按站点域名发起请求,默认从 `sysconfig('site','site_do
| `all` | 所有节点各自独立执行 | 节点本地清理等 |
| `manual` | 仅当 DB 中 `manual_trigger=1` 时执行,执行后自动重置为 0。通过管理后台触发 | 运维手动触发 |
### 配置同步
### 节点注册与主节点管理
`TimerService::syncConfigToDatabase()` 在定时器启动时运行,将 PHP 配置文件中的任务同步到 `system_timer_config` 表。同步时不会覆盖数据库中已管理的字段(`run_type``status`),以管理后台的设置为准。
- 节点启动后自动通过 `system_host_register` call 任务注册心跳(每 30 秒一次)
- 节点 ID 持久化在 `runtime/node_id.lock`(重启保持不变)
- 主节点切换 API`HostService::setMasterNode()` / `HostService::getMasterNode()`
### 执行日志
### 自动机制(开发者无需手动调用)
`TimerControllerBase::execute()` 自动包裹 `do()` 并调用 `logStart()` / `logEnd()` 记录执行日志,开发者无需手动调用。配置中写 `/do`,运行时 `TimerServiceBase` 自动重写为 `/execute` 以触发日志包裹。`host_id` 会自动注入到 site 任务的 URL 参数中,用于标识执行节点。
- **配置同步**:定时器启动时 `TimerService::syncConfigToDatabase()` 将 PHP 配置同步到 `system_timer_config` 表,不覆盖 `run_type``status` 等管理字段(以 UI 设置为准)
- **执行日志**`TimerControllerBase::execute()` 自动包裹 `do()` 并调用 `logStart()` / `logEnd()`。配置中写 `/do`,运行时 `TimerServiceBase` 自动重写为 `/execute` 以触发日志包裹。`host_id` 会自动注入到 site 任务的 URL 参数中
### 相关数据表
- `ul_system_timer_config`任务协调配置run_type、status、manual_trigger 等)
- `ul_system_timer_log`:执行日志记录
- `ul_system_host`:节点注册信息(含 `is_master` 字段标识主节点)
### 管理后台
@@ -264,9 +271,3 @@ site 任务会按站点域名发起请求,默认从 `sysconfig('site','site_do
```bash
php think admin:timer:log:clean --days=30
```
### 相关数据表
- `ul_system_timer_config`任务协调配置run_type、status、manual_trigger 等)
- `ul_system_timer_log`:执行日志记录
- `ul_system_host`:新增 `is_master` 字段,标识主节点