adspecs 0.1.12

package/references/ecp-end-standard/IdToName/344/275/277/347/224/250/350/247/204/350/214/203.md

@@ -0,0 +1,148 @@
+# 平台 ID 转名称（IdToName）使用规范
+
+## 核心原则
+
+- 使用 "字段注解 + 方法开关注解 + AOP" 自动完成 ID 到名称的填充
+- 只做展示增强：原始 ID 字段保留，不覆盖
+- 名称字段必须通过 `alias` 显式指定，禁止隐式推断
+- 类型必须来自统一枚举：`USER`、`DEPT`、`TENANT`、`PERSON`
+- 批量场景必须去重后查询，禁止逐条远程调用
+
+---
+
+## 组件角色
+
+| 组件 | 位置 | 职责 |
+|------|------|------|
+| `@IdToName` | 字段注解 | 标注 ID 字段，定义转换类型和名称落地字段 |
+| `@EnableIdToName` | 方法注解 | 开启该方法返回值的自动填充 |
+| `IdToNameType` | 枚举 | 定义 ID 类型：USER / DEPT / TENANT / PERSON |
+| `IdToNameAspect` | AOP 切面 | 方法返回后自动执行批量查询与回填 |
+| `BaseIdToNameClient` | Feign 客户端 | 按类型批量查询名称，顺序与入参一致 |
+
+---
+
+## 注解规范
+
+### 字段注解 `@IdToName`
+
+```java
+@IdToName(alias = "userName", type = IdToNameType.USER)
+private Long userId;
+
+private String userName;
+```
+
+| 属性 | 是否必填 | 说明 |
+|------|----------|------|
+| `alias` | 必填 | 同对象内承载名称的字段名，为空则跳过回填 |
+| `type` | 选填 | 默认 `USER`，可选 `DEPT` / `TENANT` / `PERSON` |
+
+约束：
+- 只能标注在 `Long` 类型字段上
+- `alias` 必须指向同对象内已声明的可写字段
+- `alias` 目标字段建议为 `String`
+
+### 方法注解 `@EnableIdToName`
+
+```java
+@EnableIdToName
+public List<DemoVO> queryList(...) { ... }
+```
+
+约束：
+- 只标注在对外返回数据的方法上
+- 切面在方法返回后自动处理，无需手动调用
+
+---
+
+## 返回值支持范围
+
+| 返回类型 | 处理方式 |
+|----------|----------|
+| 单对象 `Object` | 直接处理该对象的字段 |
+| 集合 `List<?>` | 遍历列表每个元素 |
+| 分页 `Pagination<?>` | 从 `pagination.getData()` 取集合后处理 |
+
+不在以上范围内的返回结构，不保证转换。
+
+---
+
+## AI 执行步骤（逐步指令）
+
+### Step 1：定位入口方法
+- 找到对外返回数据的 Server 或 Controller 方法
+- 在方法上添加 `@EnableIdToName`
+
+### Step 2：标注 ID 字段
+- 在返回对象（VO/Bean）中找到需要转换的 ID 字段
+- 为每个字段添加 `@IdToName`，指定 `type` 和 `alias`
+
+### Step 3：准备名称承载字段
+- 在同一对象中声明 `alias` 对应的 `String` 字段
+- 字段必须可写（反射可 set，不能是 final）
+
+### Step 4：按类型收集 ID（切面内部逻辑，AI 理解用）
+- 扫描返回对象的所有字段
+- 按 `USER / DEPT / TENANT / PERSON` 分组收集 ID 值
+- 过滤 null，执行 `distinct()` 去重
+
+### Step 5：批量查询名称（切面内部逻辑，AI 理解用）
+- 对每个非空类型 ID 列表执行一次批量查询
+- 生成 `Map<Long, String>` 映射（id → name）
+
+### Step 6：回填名称（切面内部逻辑，AI 理解用）
+- 再次遍历对象字段
+- 根据 `type + id` 从映射取 name
+- 根据 `alias` 找目标字段并写入
+
+### Step 7：容错处理（切面内部逻辑，AI 理解用）
+- 远程查询失败或返回码非成功：仅记录日志，不中断主流程
+- 名称缺失时保留 null，不抛异常
+
+---
+
+
+## 禁止事项
+1. 禁止仅加 `@IdToName` 不加 `@EnableIdToName`（注解不生效）
+2. 禁止 `alias` 为空字符串（回填会被跳过）
+3. 禁止 ID 字段为非 `Long` 类型（反射取值会 ClassCastException）
+4. 禁止逐条远程查名（N+1 调用）
+5. 禁止在转换失败时抛异常影响主业务返回
+6. 禁止使用枚举之外的类型值
+
+---
+
+## AI 自检清单（生成代码后逐项验证）
+
+- [ ] 方法是否添加 `@EnableIdToName`
+- [ ] 每个需转换 ID 字段是否添加 `@IdToName`
+- [ ] `alias` 是否非空且目标字段存在于同对象
+- [ ] ID 字段类型是否为 `Long`
+- [ ] 是否按类型分组并去重查询（无 N+1）
+- [ ] 返回类型是否在支持范围内（单对象 / List / Pagination）
+- [ ] 失败是否降级为日志，不中断主流程
+- [ ] 原始 ID 字段是否未被修改
+
+---
+
+## 最小模板
+
+```java
+// VO 定义
+public class DemoVO {
+    @IdToName(alias = "creatorName", type = IdToNameType.USER)
+    private Long creatorId;
+    private String creatorName;
+
+    @IdToName(alias = "deptName", type = IdToNameType.DEPT)
+    private Long deptId;
+    private String deptName;
+}
+
+// Server 方法
+@EnableIdToName
+public List<DemoVO> queryList(QueryBean query) {
+    return demoDao.selectList(query);
+}
+```

package/references/ecp-end-standard/Liquibase /346/225/260/346/215/256/345/272/223/345/217/230/346/233/264/347/256/241/347/220/206/350/247/204/350/214/203.md"

@@ -0,0 +1,197 @@
+# Liquibase 数据库变更管理规范
+
+## 1. 强制规则
+
+- 所有数据库变更必须通过 Liquibase 管理，禁止直接执行 SQL 不补录
+- DDL 必须幂等：`CREATE TABLE IF NOT EXISTS`
+- DML 必须幂等：`REPLACE INTO` 代替 `INSERT INTO`；`UPDATE` 带 `WHERE` 条件
+- 禁止修改已执行的 changeset（MD5 校验会失败）
+- 禁止 `DROP TABLE`
+- 完成后必须执行自检清单（第 7 节）
+
+## 2. 目录结构
+
+Liquibase 文件位于工程的 resources 下，固定结构：
+
+```
+{端口}-sieiot-{模块}/src/main/resources/liquibase/mysql/{模块名}/
+├── master.xml              # 入口，只引版本 XML
+├── v{版本}.xml             # 版本变更日志，引 DDL/DML 文件
+├── ddl/DDL_{版本}_{日期}.sql
+└── dml/DML_{版本}_{日期}.sql
+```
+
+AI 必须自行探索确定实际路径：
+```bash
+# 找到目标模块的 Liquibase 根目录
+find . -path "*/src/main/resources/liquibase/mysql/*/master.xml"
+```
+
+## 3. 文件命名
+
+| 类型 | 格式 |
+|------|------|
+| 版本 XML | `v{MAJOR}.{MINOR}.{PATCH}.xml` |
+| DDL | `DDL_{MAJOR}.{MINOR}_{YYYYMMDD}.sql` |
+| DML | `DML_{MAJOR}.{MINOR}_{YYYYMMDD}.sql` |
+
+- 版本段只取 `MAJOR.MINOR`（如 `26.1` 不是 `26.1.0`）
+- DDL 放 `ddl/`，DML 放 `dml/`，禁止混放
+## 4. XML 规范
+
+### master.xml
+
+只引版本 XML，按版本顺序排列：
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.17.xsd">
+    <include file="liquibase/mysql/{模块名}/v{版本}.xml" relativeToChangelogFile="false"/>
+</databaseChangeLog>
+```
+
+### 版本 XML
+
+引 DDL/DML，末尾 `<tagDatabase>`。`author` 用端口号，`id` 用版本号：
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.17.xsd">
+    <include file="liquibase/mysql/{模块名}/ddl/DDL_{版本}_{日期}.sql" relativeToChangelogFile="false"/>
+    <include file="liquibase/mysql/{模块名}/dml/DML_{版本}_{日期}.sql" relativeToChangelogFile="false"/>
+
+    <changeSet id="v{版本号}" author="{端口号}">
+        <tagDatabase tag="v{版本号}"/>
+    </changeSet>
+</databaseChangeLog>
+```
+
+关键属性：
+- `relativeToChangelogFile="false"` — 路径从 classpath 根开始
+- `<include>` 必须在 `<tagDatabase>` 之前
+- DDL/DML 按日期顺序排列
+
+## 5. SQL 文件规范
+
+### 文件头（必须）
+
+```sql
+--liquibase formatted sql
+--changeset {端口号}:v{版本号}:{序号}
+```
+
+- `{端口号}`：模块端口号
+- `{序号}`：当前版本内 DDL+DML 共享序号空间，不可重复。可纯数字（`001`）或语义化（`mail_01`）
+
+### DDL — 建表模板
+
+```sql
+--liquibase formatted sql
+--changeset {端口}:v{版本}:{序号}
+
+CREATE TABLE IF NOT EXISTS `{表名}` (
+  `id` bigint NOT NULL COMMENT '主键ID',
+  `tenant_id` bigint NOT NULL COMMENT '租户ID',
+  -- 业务字段 ...
+  `creation_date` datetime NOT NULL COMMENT '创建日期',
+  `created_by` bigint NOT NULL COMMENT '创建人',
+  `last_update_date` datetime DEFAULT NULL COMMENT '更新日期',
+  `last_updated_by` bigint DEFAULT NULL COMMENT '更新人',
+  `last_update_login` bigint DEFAULT NULL COMMENT '最后登录ID',
+  `delete_flag` int DEFAULT '0' COMMENT '删除标识 0未删除 1删除',
+  `version_num` int NOT NULL COMMENT '版本号',
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='{表注释}';
+```
+
+建表强制要求：`CREATE TABLE IF NOT EXISTS` | 每字段和表有 `COMMENT` | 必含审计字段（`creation_date`/`created_by`/`last_update_date`/`last_updated_by`/`last_update_login`）+ `delete_flag` + `version_num` | 多租户表含 `tenant_id` | 引擎 `InnoDB`
+
+### DDL — 改表
+
+```sql
+ALTER TABLE `{表名}` ADD COLUMN `{字段}` {类型} DEFAULT NULL COMMENT '{注释}';
+```
+
+幂等依赖 changeset 机制。如需额外保证，用 XML `<preConditions>` 方式。
+
+### DML — 插入/更新
+
+```sql
+--liquibase formatted sql
+--changeset {端口}:v{版本}:{序号}
+
+REPLACE INTO `{表名}` (`id`, `tenant_id`, ...) VALUES (...);
+UPDATE `{表名}` SET {字段} = {值} WHERE {条件};
+```
+
+- 有主键冲突风险必须用 `REPLACE INTO`
+- 系统级基础数据 `tenant_id` 用 `-999`
+- `UPDATE` 必须带 `WHERE` 条件保证幂等
+
+## 6. AI 操作流程
+
+### 步骤 1：探索目录，确定版本和路径
+
+```bash
+# 1. 找到目标模块的 Liquibase 目录
+find . -path "*/src/main/resources/liquibase/mysql/*/master.xml"
+
+# 2. 读取 master.xml 确定最新版本
+cat {找到的路径}/master.xml
+
+# 3. 读取最新版本 XML 了解已有 include
+cat {找到的路径}/v{最新版本}.xml
+```
+
+### 步骤 2：确定 changeset 序号
+
+```bash
+grep "changeset" {liquibase目录}/ddl/DDL_{版本}_*.sql {liquibase目录}/dml/DML_{版本}_*.sql
+```
+
+新文件使用下一个序号。
+
+### 步骤 3：创建 SQL 文件
+
+建表/改表 → `ddl/DDL_{版本}_{今天YYYYMMDD}.sql`
+数据变更 → `dml/DML_{版本}_{今天YYYYMMDD}.sql`
+
+### 步骤 4：注册到版本 XML
+
+在 `<tagDatabase>` 之前追加 `<include>`。
+
+### 步骤 5：新版本额外操作
+
+若版本 XML 不存在：创建版本 XML → 在 `master.xml` 末尾追加引用。
+
+## 7. 自检清单（强制，全部通过才可提交）
+
+### 文件结构
+- [ ] SQL 在正确的 `ddl/` 或 `dml/` 目录
+- [ ] 命名符合 `DDL_{MAJOR.MINOR}_{YYYYMMDD}.sql` / `DML_{MAJOR.MINOR}_{YYYYMMDD}.sql`
+
+### SQL 内容
+- [ ] 首行 `--liquibase formatted sql`
+- [ ] 第二行 `--changeset {端口}:v{版本}:{序号}`
+- [ ] 序号在当前版本内唯一（已 grep 确认）
+- [ ] DDL 用 `CREATE TABLE IF NOT EXISTS`
+- [ ] DML 用 `REPLACE INTO`（非裸 `INSERT INTO`）
+- [ ] 建表含全部审计字段 + `delete_flag` + `version_num`
+- [ ] 多租户表含 `tenant_id`
+- [ ] 所有字段和表有 `COMMENT`
+- [ ] 引擎 `InnoDB`
+
+### XML 注册
+- [ ] SQL 已在版本 XML 中 `<include>` 注册
+- [ ] `<include>` 在 `<tagDatabase>` 之前
+- [ ] `relativeToChangelogFile="false"` 已设置
+- [ ] 路径格式 `liquibase/mysql/{模块名}/ddl|dml/{文件名}`
+- [ ] 新版本时 `master.xml` 已追加引用
+
+### 幂等性
+- [ ] DDL 可重复执行不报错
+- [ ] DML 可重复执行不产生重复数据

package/references/ecp-end-standard/Redis/344/275/277/347/224/250/350/247/204/350/214/203.md

@@ -0,0 +1,78 @@
+# 平台 Redis 使用规范
+
+## 核心原则
+
+- 优先使用 `DawnRedis`（`com.sie.iot.common.redis.DawnRedis`）
+- 仅当 `DawnRedis` 无法满足需求时（如 Pipeline、Lua 脚本、Stream），才使用 `RedisTemplate`
+- 通过 `DawnRedis.getRedisTemplate()` 获取底层 `RedisTemplate`，不要单独注入
+
+## 注入方式
+
+```java
+@Autowired
+private DawnRedis dawnRedis;
+```
+
+## Key 规范
+
+- 格式：`模块:业务:标识`，如 `user:session:10001`
+- 推荐通过 `ICacheKey` 接口定义枚举统一管理 key 前缀和过期时间：
+
+```java
+public enum UserCacheKey implements ICacheKey {
+    USER_INFO("user:info:", Duration.ofMinutes(30)),
+    USER_TOKEN("user:token:", Duration.ofHours(2));
+
+    private final String prefix;
+    private final Duration expire;
+
+    @Override
+    public String getPrefix() { return prefix; }
+    @Override
+    public Duration getExpire() { return expire; }
+}
+
+// 使用
+CacheKey cacheKey = UserCacheKey.USER_INFO.getKey(userId);
+dawnRedis.set(cacheKey, userInfo);
+User user = dawnRedis.get(cacheKey);
+```
+
+- 禁止使用无过期时间的 key（除非明确需要永久缓存）
+- 禁止使用 `keys()` 在生产环境大范围匹配，改用 `scanAll()`（已内置 scan 实现）
+
+## 常用 API 速查
+
+| 场景 | 方法 |
+|------|------|
+| 字符串读写 | `set(key, value)` / `setEx(key, value, duration)` / `get(key)` |
+| 带 CacheKey 读写 | `set(cacheKey, value)` / `get(cacheKey)` |
+| 缓存加载（防穿透） | `get(key, () -> loader)` / `get(cacheKey, () -> loader)` |
+| 条件设置 | `setNx(key, value)` / `setNx(key, value, timeout, unit)` |
+| 计数器 | `incr(key)` / `incrBy(key, n)` / `decr(key)` / `decrBy(key, n)` |
+| 过期管理 | `expire(key, seconds)` / `expire(key, duration)` / `ttl(key)` |
+| 删除 | `del(key)` / `del(cacheKey)` / `del(key1, key2, ...)` |
+| 存在性 | `exists(key)` |
+| Hash | `hSet` / `hGet` / `hMset` / `hGetAll` / `hDel` / `hExists` / `hKeys` / `hIncrBy` |
+| List | `lPush` / `lPushRight` / `lPop` / `rPop` / `lRange` / `lLen` / `lTrim` |
+| Set | `sAdd` / `sMembers` / `sIsMember` / `sRem` / `sInter` / `sUnion` / `sDiff` |
+| ZSet | `zAdd` / `zRange` / `zRevrange` / `zRangeByScore` / `zRank` / `zRem` / `zScore` |
+| 查询任意类型 | `query(key)` 返回 `RedisResult`（自动识别类型） |
+
+## 禁止事项
+
+1. 禁止直接 `new DawnRedis()`，必须通过 Spring 注入
+2. 禁止存储大对象（单个 value > 1MB）
+3. 禁止在循环中逐个操作，批量场景用 `mSet` / `mGet` 或 Pipeline
+4. 禁止使用 `redisTemplate.keys()`，用 `dawnRedis.keys()` 或 `scanAll()`（内部已用 scan 实现）
+5. 禁止存储敏感明文数据（密码、密钥等）
+
+## 降级到 RedisTemplate 的场景
+
+以下场景 `DawnRedis` 未封装，需通过 `dawnRedis.getRedisTemplate()` 操作：
+
+- Pipeline 批量操作
+- Lua 脚本执行（`execute(RedisScript, keys, args)`）
+- Redis Stream
+- Pub/Sub
+- 事务（`multi/exec`）

package/references/ecp-end-standard/index.md

@@ -0,0 +1,63 @@
+# 后端集成开发规范索引
+
+本目录包含后端（Java / Spring Boot）集成开发规范。生成或修改后端代码前，先按任务类型读取对应规范。
+
+---
+
+## 文件清单
+
+| 序号 | 文件名 | 主要内容 |
+| ---- | ------ | -------- |
+| 01 | [后端分层开发与数据库设计规范.md](./后端分层开发与数据库设计规范.md) | Controller / Service / Manager / DAO 分层约束、数据库设计强制规则 |
+| 02 | [多语言及全局异常处理规范.md](./多语言及全局异常处理规范.md) | 异常必须在 Server 层抛出、多语言消息、全局异常拦截 |
+| 03 | [Liquibase 数据库变更管理规范.md](./Liquibase%20数据库变更管理规范.md) | 所有数据库变更必须走 Liquibase，禁止直接执行 SQL 不补录 |
+| 04 | [Redis使用规范.md](./Redis使用规范.md) | 优先使用 `DawnRedis`，Key 命名规范、过期策略 |
+| 05 | [ES使用规范.md](./ES使用规范.md) | 基于 `sieiot-es-plus-starter`（ES 8.x）静态链式 API 操作 Elasticsearch |
+| 06 | [分布式锁规范.md](./分布式锁规范.md) | 两种分布式锁方式（Redis / 注解）适用场景与用法 |
+| 07 | [IdToName使用规范.md](./IdToName使用规范.md) | 字段注解 + 方法开关注解 + AOP 自动完成 ID → 名称填充 |
+| 08 | [编码自动生成规范.md](./编码自动生成规范.md) | 业务编码（客户、供应商、订单等）统一通过 `AutoCodeRuleService` 生成 |
+| 09 | [文件中心使用规范.md](./文件中心使用规范.md) | 平台文件中心 `IotBaseAttachmentClient` 统一附件管理 |
+| 10 | [流程中心接入规范.md](./流程中心接入规范.md) | 业务单据接入 BPM 流程中心（Kafka 异步 + 状态回调） |
+| 11 | [通用工具类使用规范.md](./通用工具类使用规范.md) | 平台通用工具类选型约束，避免重复造轮子 |
+
+---
+
+## 按场景推荐阅读
+
+### 新增业务模块（建工程）
+
+1. `后端分层开发与数据库设计规范.md` — 先确定分层结构与数据库规范
+2. `多语言及全局异常处理规范.md` — 异常处理与多语言消息
+3. `Liquibase 数据库变更管理规范.md` — 数据库变更管理流程
+4. `通用工具类使用规范.md` — 避免重复造轮子
+
+### 新增 CRUD 接口
+
+1. `后端分层开发与数据库设计规范.md` — 分层约束
+2. `编码自动生成规范.md` — 业务编码生成
+3. `IdToName使用规范.md` — 列表返回时自动翻译 ID 为名称
+4. `多语言及全局异常处理规范.md` — 异常抛出与提示
+
+### 涉及缓存 / 搜索 / 锁
+
+1. `Redis使用规范.md` — 缓存读写
+2. `ES使用规范.md` — 全文检索 / 复杂查询
+3. `分布式锁规范.md` — 并发控制
+
+### 文件 / 流程 / 附件
+
+1. `文件中心使用规范.md` — 附件上传 / 查询 / 删除
+2. `流程中心接入规范.md` — BPM 审批流接入
+
+### 数据库变更
+
+1. `Liquibase 数据库变更管理规范.md` — 强制走 Liquibase
+2. `后端分层开发与数据库设计规范.md` — 表结构与索引设计约束
+
+---
+
+## 维护说明
+
+- 新增规范文件时，同步更新本索引。
+- 规范文件命名使用中文，便于阅读；文件名中的空格在链接中需要 URL 编码（如 `%20`）。
+- 本目录规范与 `ant6-front-integration/`（前端规范）、`yudaocloud-end-integration/`（ECP 后端集成）互补，按技术栈选用。

package/references/ecp-end-standard//345/210/206/345/270/203/345/274/217/351/224/201/350/247/204/350/214/203.md

@@ -0,0 +1,65 @@
+# 分布式锁规范
+
+## 1. 两种方式
+
+| 方式 | 适用场景 | 依赖 |
+|------|----------|------|
+| `@Klock` 注解 | 整个方法需要加锁，锁粒度=方法级 | `sieiot-klock-component` |
+
+**选择原则：能用 `@Klock` 强制用 `@Klock`**
+
+---
+
+## 2. @Klock 注解式（优先）
+
+### 2.1 强制规则
+
+- `keys` 必须包含业务唯一标识，**禁止省略 keys 导致全局锁**
+- `keys` 中的字符串常量用单引号包裹：`keys = {"'bizKey'"}`
+- `keys` 中引用参数用 SpEL：`keys = {"#param"}`、`keys = {"#bean.id"}`
+- `leaseTime` 必须 > 业务最大耗时，防止锁提前释放
+- 默认锁类型为公平锁，高并发场景保持默认
+
+### 2.2 模板
+
+```java
+// 固定业务Key（同步类操作）
+@Klock(keys = "'synchroDuty'")
+public Result bizMethod() { ... }
+
+// 动态业务Key（基于参数）
+@Klock(keys = {"#bean.id"}, waitTime = 10, leaseTime = 30)
+public Result bizMethod(BizBean bean) { ... }
+
+// 多Key组合
+@Klock(keys = {"#user.name", "#user.id"})
+public Result bizMethod(User user) { ... }
+
+// 配置超时策略
+@Klock(keys = {"#id"}, waitTime = 5, lockTimeoutStrategy = LockTimeoutStrategy.FAIL_FAST)
+public Result bizMethod(Long id) { ... }
+```
+
+### 2.3 @Klock 参数速查
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `name` | 类名+方法名 | 锁名前缀 |
+| `keys` | 无 | **必填**，SpEL 业务Key数组 |
+| `lockType` | 公平锁 | 可重入锁/公平锁/读写锁 |
+| `waitTime` | 60s | 获取锁等待时间 |
+| `leaseTime` | 60s | 锁自动释放时间 |
+| `lockTimeoutStrategy` | NO_OPERATION | 加锁超时：NO_OPERATION / FAIL_FAST / KEEP_ACQUIRE |
+| `releaseTimeoutStrategy` | NO_OPERATION | 释放超时：NO_OPERATION / FAIL_FAST |
+| `customLockTimeoutStrategy` | 无 | 自定义加锁超时处理方法名 |
+| `customReleaseTimeoutStrategy` | 无 | 自定义释放超时处理方法名 |
+
+---
+
+## 3. 禁止事项
+
+1. 禁止不带 `keys` 使用 `@Klock`（会退化为方法级全局锁）
+2. 禁止 `leaseTime` 小于业务耗时
+4. 禁止 lockKey 不含业务唯一标识
+5. 禁止 `tryLock` 不设超时参数（`waitTime`/`leaseTime`）
+6. 禁止吞掉 `InterruptedException` 不恢复中断状态