docs: update framework starter guidance

Author: bruceblink

README.md

@@ -1,6 +1,6 @@
 # Keystone
 
-[![Release](https://img.shields.io/badge/Release-V3.6.0-green.svg)](https://github.com/bruceblink/Keystone)
+[![Release](https://img.shields.io/badge/Release-V3.6.1-green.svg)](https://github.com/bruceblink/Keystone)
 [![JDK](https://img.shields.io/badge/JDK-25-green.svg)](https://github.com/bruceblink/Keystone)
 [![Spring%20Boot](https://img.shields.io/badge/Spring%20Boot-3.5.13-blue.svg)](https://github.com/bruceblink/Keystone)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -32,9 +32,12 @@
 
 ```text
 keystone-admin           # 管理后台接口
+keystone-framework-admin # 框架 Web/API 层自动配置
+keystone-framework-domain # 框架领域服务、系统管理、定时任务
+keystone-framework-spring-boot-starter # 框架聚合 starter
 keystone-common          # 通用基础能力
 keystone-infrastructure  # 配置与基础设施
-keystone-domain          # 核心业务领域
+keystone-domain          # 下游应用扩展模块，占位承载业务扩展
 ```
 
 ## ⚡ 30 秒开始
@@ -196,8 +199,10 @@ docker compose down -v
   - [keystone-infrastructure/src/main/resources/db/migrate/common/V3_3_0__flyway_baseline_marker.sql](keystone-infrastructure/src/main/resources/db/migrate/common/V3_3_0__flyway_baseline_marker.sql) — Flyway 基线标记
   - [keystone-infrastructure/src/main/resources/db/migrate/mysql/V3_3_1__init_core_schema_data.sql](keystone-infrastructure/src/main/resources/db/migrate/mysql/V3_3_1__init_core_schema_data.sql) — 核心结构与初始化数据
   - [keystone-infrastructure/src/main/resources/db/migrate/mysql/V3_3_2__init_dict_schema_data.sql](keystone-infrastructure/src/main/resources/db/migrate/mysql/V3_3_2__init_dict_schema_data.sql) — 字典结构与初始化数据
-  - [keystone-infrastructure/src/main/resources/db/migrate/h2/keystone_schema.sql](keystone-infrastructure/src/main/resources/db/migrate/h2/keystone_schema.sql) — H2 测试 schema
-  - [keystone-infrastructure/src/main/resources/db/migrate/h2/keystone_data.sql](keystone-infrastructure/src/main/resources/db/migrate/h2/keystone_data.sql) — H2 测试 data
+  - [keystone-admin/src/test/resources/db/migrate/h2/keystone_schema.sql](keystone-admin/src/test/resources/db/migrate/h2/keystone_schema.sql) — admin H2 测试 schema
+  - [keystone-admin/src/test/resources/db/migrate/h2/keystone_data.sql](keystone-admin/src/test/resources/db/migrate/h2/keystone_data.sql) — admin H2 测试 data
+  - [keystone-domain/src/test/resources/db/migrate/h2/keystone_schema.sql](keystone-domain/src/test/resources/db/migrate/h2/keystone_schema.sql) — domain H2 集成测试 schema
+  - [keystone-domain/src/test/resources/db/migrate/h2/keystone_data.sql](keystone-domain/src/test/resources/db/migrate/h2/keystone_data.sql) — domain H2 集成测试 data
 - Flyway SQL 命名规范：
   - MySQL 迁移脚本统一放在 `keystone-infrastructure/src/main/resources/db/migrate/mysql/`
   - 文件名格式必须为 `V<版本号>__<描述>.sql`，例如 `V3_4_0__add_user_profile_table.sql`
@@ -207,6 +212,8 @@ docker compose down -v
   - 已执行过的 Flyway 脚本不要重命名、不要改版本号；如需继续演进，新增更高版本脚本
   - 脚本内容不得写死数据库名（例如 `use keystone;`），应始终作用于当前 datasource 指向的库
 - 数据库密码加密：[DATABASE_PASSWORD_ENCRYPTION_GUIDE.md](DATABASE_PASSWORD_ENCRYPTION_GUIDE.md)
+- 框架 starter 使用说明：[docs/framework-starter-usage.md](docs/framework-starter-usage.md)
+- 框架 starter 维护文档：[docs/framework-starter-maintenance.md](docs/framework-starter-maintenance.md)
 - Keylo 对接说明（含可选启用、统一 `/login` 后端 Keylo 凭证鉴权、用户新增同步注册）：见 [docs/项目说明.md](docs/项目说明.md) 的“Keylo 集成与用户注册流程”章节
 
 ## 🤝 贡献

docs/framework-business-isolation.md

@@ -4,7 +4,7 @@
 
 第一条低风险边界是 admin Web 层。当前 `keystone-admin` 模块同时包含框架接口和业务接口，但 `controller/system`、`controller/common`、`customize` 这些包主要依赖系统领域服务和公共基础设施，可以在不修改请求路径和 Java 包名的前提下拆到独立模块。
 
-完整拆成 Spring Boot starter 是可行的，但需要分阶段推进。当前框架代码已经隔离到独立 Gradle 模块，可以在仓库内独立开发；同时已增加 starter 聚合模块，后续应用可以依赖统一的框架入口，而不需要逐个装配框架子模块。
+完整拆成 Spring Boot starter 是可行的，当前已经进入可用阶段。框架代码已经隔离到独立 Gradle 模块，可以在仓库内独立开发；starter 聚合模块提供统一的框架入口，消费应用不需要逐个装配框架子模块。
 
 相关文档：
 
@@ -27,6 +27,11 @@
 - 下游应用的业务迁移由消费方自行提供，框架 starter 传递依赖不携带业务表迁移。
 - 将 H2 集成测试 schema/data 移出 infrastructure 主资源，改为 admin/domain 测试资源。
 - 将 `keystone-admin` 调整为依赖 `keystone-framework-spring-boot-starter` 和扩展模块 `keystone-domain`。
+- `keystone-admin` 启动类移除全仓 `@ComponentScan("app.keystone.*")`，框架组件由 starter 自动配置装配。
+- 删除 `keystone-admin` 中重复的系统监控 controller，`/monitor/**` 由 `keystone-framework-admin` 提供。
+- 将定时任务运行日志清理任务和定时任务运行时相关测试迁入 `keystone-framework-domain`。
+- 系统导出接口改为调用无分页 `export...` 方法，避免只导出当前分页。
+- `keystone-domain/src/main/java` 当前保持为空，作为下游扩展模块边界。
 - 移除 `domain/common/cache` 对具体业务实体的直接依赖，改为通过通用缓存名称查找。
 - 暂时保持 Java 包名不变，确保 Spring 组件扫描、路由映射和现有 import 稳定。
 - 保留 `keystone-admin` 作为可执行应用入口。

docs/framework-starter-maintenance.md

@@ -62,6 +62,7 @@ src/main/resources/db/migrate/mysql
 - `domain/common`
 - `domain/system`
 - 系统用户、角色、菜单、部门、岗位、字典、日志、通知、定时任务等框架领域能力
+- 系统定时任务运行时、运行日志清理任务和相关单元测试
 
 自动配置：
 
@@ -82,6 +83,7 @@ KeystoneFrameworkDomainAutoConfiguration
 - `admin/controller/common`
 - `admin/controller/system`
 - `admin/customize`
+- 系统监控、日志、用户、角色、菜单、定时任务等框架 controller
 
 自动配置：
 
@@ -95,6 +97,8 @@ KeystoneFrameworkAdminAutoConfiguration
 - 业务 controller
 - 业务 application service
 
+`keystone-admin` 不应再保留同路径的框架 controller 副本。例如 `/monitor/**` 由 `keystone-framework-admin` 提供，主应用中不要再新增 `app.keystone.admin.controller.system.MonitorController`。
+
 ### keystone-framework-spring-boot-starter
 
 只做依赖聚合，原则上不放业务代码。
@@ -113,6 +117,8 @@ starter 模块可以放少量测试，用于验证依赖链、自动配置和资
 
 保留为空的下游扩展模块。开源分支不在该模块内放置业务领域代码或业务迁移资源。
 
+当前 `src/main/java` 应保持无框架运行时代码。框架领域代码、框架定时任务和框架单元测试必须放在 `keystone-framework-domain`。如果下游应用需要自己的业务能力，应放在消费应用自己的领域模块和迁移路径中。
+
 ### keystone-admin
 
 保留 Keystone 可执行应用入口。
@@ -131,6 +137,8 @@ classpath:db/migrate/common
 classpath:db/migrate/mysql
 ```
 
+主应用启动类只保留 `@SpringBootApplication`。不要重新添加 `@ComponentScan(basePackages = "app.keystone.*")`，否则会绕过 starter 自动配置边界，导致重复 controller 或隐藏自动配置缺失问题。
+
 ## 自动配置维护规则
 
 自动配置注册文件：
@@ -160,6 +168,27 @@ keystone:
       enabled: true
 ```
 
+## 系统导出维护规则
+
+系统管理导出接口必须使用无分页查询方法，不能复用分页列表结果。分页列表只返回当前页，导出接口需要导出筛选条件下的完整集合。
+
+当前约定：
+
+```text
+SysUserController.exportUserByExcel -> UserApplicationService.exportUsers
+SysRoleController.export -> RoleApplicationService.exportRoles
+SysLogsController.loginInfosExcel -> LogApplicationService.exportLoginInfos
+SysLogsController.operationLogsExcel -> LogApplicationService.exportOperationLogs
+ConfigApplicationService.exportConfigs
+```
+
+维护要求：
+
+- 新增系统导出接口时，在 application service 中提供明确的 `export...` 方法。
+- `export...` 方法使用 `list(...)` 或专门的无分页 mapper 方法，不调用 `page(...)`。
+- 需要稳定排序的日志类导出必须补充主排序字段之外的 ID 倒序，例如 `login_time, info_id`。
+- 对应测试放在 `keystone-framework-domain/src/test/java/app/keystone/domain/system/SystemExportApplicationServiceTest.java`。
+
 ## 发布维护
 
 框架相关发布模块：
@@ -285,6 +314,9 @@ jar tf keystone-domain\build\libs\keystone-domain-3.6.1.jar | Select-String "db/
 ```text
 keystone-framework-admin/src/test/java/app/keystone/framework/admin/autoconfigure/KeystoneFrameworkAdminAutoConfigurationTest.java
 keystone-framework-domain/src/test/java/app/keystone/framework/domain/autoconfigure/KeystoneFrameworkDomainAutoConfigurationTest.java
+keystone-framework-domain/src/test/java/app/keystone/domain/system/SystemExportApplicationServiceTest.java
+keystone-framework-domain/src/test/java/app/keystone/domain/system/job/runtime/JobInvokeUtilTest.java
+keystone-framework-domain/src/test/java/app/keystone/domain/system/job/runtime/JobSchedulerManagerTest.java
 keystone-framework-spring-boot-starter/src/test/java/app/keystone/framework/starter/KeystoneFrameworkStarterDependencyTest.java
 ```
 

docs/framework-starter-usage.md

@@ -16,6 +16,8 @@ keystone-framework-spring-boot-starter
 
 业务模块不属于 starter。具体业务代码和业务迁移仍由下游应用单独引入。
 
+消费应用不需要再通过 `@ComponentScan("app.keystone.*")` 扫描整个仓库。引入 starter 后，框架 controller、领域服务和基础设施组件由自动配置加载；应用自己的包仍由本应用的 `@SpringBootApplication` 默认扫描范围负责。
+
 ## 环境要求
 
 - Java 17+
@@ -202,6 +204,8 @@ app.keystone.infrastructure
 
 注意：当前仍保留历史包名，外部应用不要定义同名类或同路径控制器，避免 Bean 或路由冲突。
 
+自动配置包含系统管理 Web 层，例如用户、角色、菜单、日志、监控、定时任务等 controller。Keystone 主应用已经删除 `keystone-admin` 中重复的系统监控 controller，`/monitor/**` 由 `keystone-framework-admin` 提供。
+
 ## Keystone 主应用使用方式
 
 Keystone 主应用已经接入 starter：
@@ -213,6 +217,16 @@ dependencies {
 }
 ```
 
+启动类只保留 Spring Boot 默认扫描：
+
+```java
+@SpringBootApplication
+public class KeystoneAdminApplication {
+}
+```
+
+不要在主应用中重新添加 `@ComponentScan(basePackages = "app.keystone.*")`。全仓扫描会掩盖 starter 自动配置问题，也可能把下游扩展模块中尚未明确暴露的组件误装配进运行时。
+
 主应用加载框架迁移：
 
 ```yaml
@@ -231,6 +245,12 @@ spring:
 .\gradlew.bat :keystone-framework-spring-boot-starter:test
 ```
 
+验证 starter 自动配置和主应用接入：
+
+```powershell
+.\gradlew.bat :keystone-framework-spring-boot-starter:test :keystone-framework-domain:test :keystone-framework-admin:test :keystone-admin:test :keystone-admin:compileJava
+```
+
 验证发布：
 
 ```powershell
@@ -282,3 +302,16 @@ keystone:
     admin:
       enabled: false
 ```
+
+### 引入 starter 后系统接口 404
+
+检查应用是否只引入了 `keystone-framework-spring-boot-starter`，而不是只引入了 `keystone-common` 或 `keystone-infrastructure`。还需要确认没有关闭：
+
+```yaml
+keystone:
+  framework:
+    domain:
+      enabled: true
+    admin:
+      enabled: true
+```

docs/scheduled-job-design.md

@@ -22,6 +22,7 @@ Keystone 定时作业用于把后台周期性任务从代码中的固定 `@Sched
 | 调用目标发现 | 扫描 `@JobTask` 和 `@Scheduled` 方法，返回候选列表 |
 | 任务参数 | `sys_job.job_params` 保存 JSON 参数，支持目标方法接收一个参数对象 |
 | 运行历史 | 每次自动调度、手动执行、失败、并发跳过写入 `sys_job_log` |
+| 运行历史清理 | 内置 `sysJobLogCleanupTask.cleanExpiredJobLogs()`，默认清理 30 天前的运行日志 |
 | 操作审计 | 新增、修改、启停、立即运行、删除进入 `sys_operation_log` |
 | 前端辅助 | 调用目标下拉选择，点击任务编号查看运行日志 |
 
@@ -31,7 +32,7 @@ Keystone 定时作业用于把后台周期性任务从代码中的固定 `@Sched
 | --- | --- |
 | 分布式任务锁 | 当前运行态注册表是单 JVM 内存结构，多节点部署时需要单独设计分布式锁 |
 | Cron 在线解析器 | 只做后端 Cron 语法校验，不在后端提供复杂表达式解释 |
-| 调度历史清理策略 | 当前只记录运行历史，后续可按保留天数或最大条数增加清理任务 |
+| 复杂调度历史保留策略 | 当前提供基础 30 天清理任务；按任务分组、最大条数或多租户维度的保留策略后续单独设计 |
 | 任务依赖编排 | 不支持 DAG、前置任务、失败重试编排 |
 
 ## 3. 关键概念
@@ -51,21 +52,22 @@ Keystone 定时作业用于把后台周期性任务从代码中的固定 `@Sched
 ## 4. 模块结构
 
 ```text
-keystone-admin
+keystone-framework-admin
   app.keystone.admin.controller.system.SysJobController
 
 keystone-common
   app.keystone.common.annotation.JobTask
   app.keystone.common.enums.common.JobLogStatusEnum
   app.keystone.common.enums.common.JobTriggerTypeEnum
 
-keystone-domain
+keystone-framework-domain
   app.keystone.domain.system.job.JobApplicationService
   app.keystone.domain.system.job.db.SysJobEntity
   app.keystone.domain.system.job.db.SysJobLogEntity
   app.keystone.domain.system.job.runtime.JobInvokeUtil
   app.keystone.domain.system.job.runtime.JobSchedulerManager
   app.keystone.domain.system.job.runtime.JobStartupRunner
+  app.keystone.domain.system.job.task.SysJobLogCleanupTask
 
 keystone-infrastructure
   db/migrate/mysql/V3_5_46__add_dict_and_job_management.sql

docs/scheduled-job-development-guide.md

@@ -42,12 +42,15 @@
 
 ```text
 keystone-infrastructure/src/main/java/app/keystone/infrastructure/schedule
-keystone-domain/src/main/java/app/keystone/domain/{module}/job
+keystone-framework-domain/src/main/java/app/keystone/domain/system/job/task
+<business-app-domain>/src/main/java/.../{module}/job
 ```
 
 如果任务只是基础设施类维护动作，例如清理临时文件、刷新公共缓存，可以放在 `keystone-infrastructure`。
 
-如果任务明显属于某个业务领域，例如工单超时扫描、设备状态同步，可以放在对应领域模块下。
+如果任务属于 Keystone 框架系统能力，例如清理 `sys_job_log`，放在 `keystone-framework-domain`。
+
+如果任务明显属于某个业务领域，例如工单超时扫描、设备状态同步，应放在消费应用自己的领域模块下，不放回开源框架模块。当前开源仓库中的 `keystone-domain` 仅作为下游扩展模块占位。
 
 ## 4. 标准代码模板
 
@@ -336,8 +339,9 @@ public void cleanExpiredFiles() {
 现有参考测试：
 
 ```text
-keystone-domain/src/test/java/app/keystone/domain/system/job/runtime/JobInvokeUtilTest.java
-keystone-domain/src/test/java/app/keystone/domain/system/job/runtime/JobSchedulerManagerTest.java
+keystone-framework-domain/src/test/java/app/keystone/domain/system/job/runtime/JobInvokeUtilTest.java
+keystone-framework-domain/src/test/java/app/keystone/domain/system/job/runtime/JobSchedulerManagerTest.java
+keystone-framework-domain/src/test/java/app/keystone/domain/system/job/task/SysJobLogCleanupTaskTest.java
 ```
 
 ## 15. 排查指南
@@ -347,7 +351,7 @@ keystone-domain/src/test/java/app/keystone/domain/system/job/runtime/JobSchedule
 检查：
 
 1. 类是否有 `@Component`、`@Service` 等 Spring Bean 注解。
-2. Bean 是否在 `app.keystone.*` 扫描范围内。
+2. Bean 是否在当前应用组件扫描范围内，或由 starter 自动配置加载。
 3. 方法是否无参，或只接收一个参数对象。
 4. 方法是否标注 `@JobTask`。
 5. 应用是否重启或重新加载。