Autumn

Autumn 是一套可扩展的后台基础框架：在 Spring Boot 之上提供权限、系统管理、代码生成、两级缓存、分布式队列、HTTP 混合加解密、字段存储加密、定时任务、机器人开放 API、支付安全凭证等能力，并配套 docs/ 约束文档与 Cursor Skill，支持传统开发与 AI 协作并行。

---

版本与分支

业务工程请在 AGENTS.md 或首轮对话中写明依赖的 Autumn 主版本，避免 2.x / 3.x 规范与 Skill 混用。具体版本以根 pom.xml 为准。

---

核心能力一览

传输加密（docs/AI_CRYPTO.md）与 字段存储加密（docs/AI_FIELD_ENCRYPT.md）使用不同密钥与服务，请勿混用。

---

字段存储加密（at-rest）

面向需要在数据库中加密 String 字段、又要在业务层保持明文的场景。

怎么用

1. 实体字段标注 @FieldEncrypt（可选 searchable=true + 手写 {field}Hash 列）。
2. 模块 Service 继承 EncryptModuleService（无加密字段则继续用 ModuleService，零开销）。
3. 配置 autumn.crypto.field.*（见下文）；管理页 fieldencrypt.html / API /sys/crypto/field/*。

加解密路径（唯一）

• 列表/分页 searchable 等值条件：EncryptModuleService#tryHashQueryCondition 改写 hash 列。
• @Cache + 加密字段：明文键与 hash 通道（FieldEncryptService.HASH_CACHE_CHANNEL）由框架钩子处理，详见 docs/AI_FIELD_ENCRYPT.md §7。
• 迁移读库内密文：FieldEncryptContext.runSkip(...)（FieldEncryptMigrationService）。

配置示例

autumn:
  crypto:
    field:
      enabled: true
      key: ${AUTUMN_FIELD_ENCRYPT_KEY:}    # Base64，32 字节 AES-256
      hash-key: ${AUTUMN_FIELD_HASH_KEY:}  # 盲索引 HMAC；建议与 key 分开
      prefix: "ENC$v1$"

关键类

约束单测：FieldEncryptConventionTest · FieldEncryptCacheTest · EncryptModuleServiceTest。

---

Service 默认继承链

业务 Service 通常从 ModuleService 出发，按需获得以下能力（无需重复实现）：

ModuleService
  → BaseService          # 分页、getCondition、菜单
  → DistributedService   # withLock*
  → ShareCacheService    # 跨模块共享缓存
  → BaseCacheService     # @Cache 回源与失效
  → BaseQueueService     # 队列注册与发送
  → AutoIdService        # UuidBased / SnowBased 第二主键
  → DialectService       # RuntimeSql / columnInWrapper

含 @FieldEncrypt 的实体：将 ModuleService 换为 EncryptModuleService，其余链不变。

---

文档入口

应用内在线文档

仓库 docs/（AI 与研发约束）

所有 AI_*.md 均在 docs/ 目录，不在仓库根目录。

按场景追加（见 AI_INDEX.md §2）：

Cursor / 业务仓引用

• 本仓库：@docs/AI_INDEX.md
• 与 autumn 并列的业务仓：@../autumn/docs/AI_BOOT.md（见 AI_INDEX.md §4）

---

AI 协作与 Cursor Skill

Skill 与 docs/ 口径一致，摘要包括：分层纪律、Dao Provider、双主键、@FieldEncrypt / EncryptModuleService、加密缓存钩子、Bot、safe 等。可同步到 ~/.cursor/skills/ 供全局使用。

约束扫描（按需）：全量 bash scripts/constraints-scan（含 I 组 FQN）；PR 硬门禁 bash scripts/check-java-fqn（见 AI_CODE_STYLE.md §7.1、.github/workflows/java-style-check.yml）。

---

工程结构

autumn/
├── autumn-handler/     # Handler 扩展接口与默认实现
├── autumn-lib/       # 缓存、队列、加解密、RuntimeSql、FieldEncryptService 等
├── autumn-modules/   # 业务模块（sys、gen、bot、safe…）与 Controller
├── autumn-starter/   # 一站式依赖聚合
├── web/              # 启动入口（主类 cn.org.autumn.Web）
├── docs/             # AI_*.md 约束与专项文档
├── scripts/          # constraints-scan、dependency-scan 等
└── .cursor/skills/   # autumn-framework-2x / 3x

---

环境与构建

父 POM 在 validate 阶段启用 dependencyConvergence；升级依赖后若 enforcer 报错，请在 dependencyManagement 中对齐版本。

mvn clean package -DskipTests

---

快速启动

1. 创建数据库 autumn（UTF-8 / utf8mb4）。
2. 修改 web/src/main/resources/application-dev.yml 中的数据源。
3. 确认 application.yml 中 Redis 可连接（若启用）。
4. 构建（见上），然后：
   • IDE 运行 web/src/main/java/cn/org/autumn/Web.java，或
   • java -jar web/target/web.jar

生产环境建议：autumn.redis.open=true、autumn.shiro.redis=true；多节点定时任务配合 LoopJob 的 assignTag / server.tag。

---

开发纪律（摘要）

完整条文见 docs/AI_STANDARDS.md。高频项：

• 分层：Controller 禁止注入 Dao；Service 通过 baseMapper 访问本实体；跨域走对方 Service。
• SQL：Dao 仅 Provider（*DaoSql extends RuntimeSql），禁止 Dao 内联 @Select；条件列用 columnInWrapper，禁止硬编码方言引号。
• 代码生成：controller/gen、Pages/*.html/js 勿手改；业务写在非 gen 层。
• 双主键：关联与对外标识用 uuid，不用自增 id（docs/AI_DUAL_KEY.md）。
• 定时任务：固定周期优先 LoopJob.*；复杂日历再用 cron。
• 字段加密：@FieldEncrypt 实体 → EncryptModuleService；手写 SQL → afterRead*；searchable → 手写 hash 列。

---

维护脚本

---

链接

• 项目站点：http://autumn.org.cn
• 文档总索引：docs/AI_INDEX.md