# framework2

**Repository Path**: lzb-framework/framework2

## Basic Information

- **Project Name**: framework2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# framework2 Attr 注解规范（当前实现）

## 1. 文档定位

本文件描述当前 `framework2` 仓库内**已落地**的 Attr 注解与公共值编解码能力，作为注解使用、解析实现与后续扩展的基线。

适用模块：

1. `framework2-core-util`
2. `framework2-java-attr/framework2-java-attr-annotations`

---

## 2. 当前模块结构

```text
framework2
├── framework2-core-util
│   └── src/main/java/com/framework2/core/util/value
│       ├── TypedValueType.java
│       └── TypedValueCodec.java
└── framework2-java-attr
    └── framework2-java-attr-annotations
        └── src/main/java/com/framework2/java/attr/annotations
            ├── Attr.java
            ├── AttrEntity.java
            ├── AttrKind.java
            ├── common/TriState.java
            ├── hint/*
            └── role/*
```

---

## 3. 核心入口

### 3.1 `@Attr`

字段级核心注解：`com.framework2.java.attr.annotations.Attr`

```java
@Attr(AttrKind.ENUM)
@AttrHintEnum(EnumRole.STATUS)
private Integer taskStatus;
```

属性说明：

1. `value`: `AttrKind`，字段基础类型。
2. `label`: 字段展示名称。
3. `description`: 字段说明。
4. `examples`: 示例值列表。
5. `createDefaultValue`: 创建时业务默认值（不等同数据库 DDL DEFAULT）。
6. `createDefaultValueType`: `TypedValueType`，用于解析 `createDefaultValue`。
7. `required`: `TriState` 必填策略。
8. `readOnly`: `TriState` 只读策略。

### 3.2 `@AttrEntity`

实体级注解：`com.framework2.java.attr.annotations.AttrEntity`

```java
@AttrEntity(
    entity = "user",
    label = "用户",
    description = "平台用户",
    service = "user-center",
    defaultLabelFields = {"name"},
    plannedVolume = 20000
)
class UserEntity {
}
```

属性说明：

1. `entity`: 实体标识（必填）。
2. `label`: 实体展示名。
3. `description`: 实体说明。
4. `service`: 所属服务名。
5. `defaultLabelFields`: 默认标签字段。
6. `plannedVolume`: 规划规模（`-1` 表示未设置）。

### 3.3 `AttrKind`

当前枚举顺序与定义如下：

```java
ID, REF_ID, TEXT, RICH_CONTENT, NUMBER, ENUM, FLAG, DATETIME, MEDIA, JSON_DOC
```

> 说明：若任何外部系统依赖 `ordinal()`，调整顺序会有兼容风险。建议仅按枚举名使用。

---

## 4. 通用枚举

### 4.1 `TriState`

`UNSET / TRUE / FALSE`

用于表达“未设置/开启/关闭”三态语义，避免布尔值无法区分“默认”与“显式关闭”。

---

## 5. Hint 注解

### 5.1 `@AttrHintId`

主键语义：

1. `generator`: `UNSET/AUTO/SNOWFLAKE/UUID/CUSTOM`

### 5.2 `@AttrHintRefId`

引用语义：

1. `value`: `RefIdRole`
2. `refService`: 被引用服务
3. `refEntity`: 被引用实体
4. `refField`: 被引用字段（默认 `id`）

### 5.3 `@AttrHintEnum`

枚举语义：

1. `value`: `EnumRole`
2. `enumClass`: 绑定枚举类，默认 `UnspecifiedEnum.class`（表示未显式指定）
3. `valueType`: `UNSET/INT/STRING`（值语义，不直接绑定数据库列类型）
4. `cardinality`: `UNSET/SINGLE/MULTI`
5. `maxSelections`: 多选上限（`-1` 不限制）

### 5.4 `@AttrHintFlag`

布尔标记语义：

1. `value`: `FlagRole`

### 5.5 `@AttrHintDateTime`

时间语义：

1. `value`: `DateTimeRole`
2. `autoFill`: `UNSET/NONE/CREATED/UPDATED/CREATED_UPDATED`
3. `encoding`: `UNSET/ISO_LOCAL/INSTANT/EPOCH_MILLIS/EPOCH_SECONDS`
4. `timezone`: 时区（如 `Asia/Shanghai`）

### 5.6 `@AttrHintText`

文本语义：

1. `value`: `TextRole`
2. `multiline`: `TriState`
3. `maxLength`: 最大长度（`-1` 不限制）
4. `pattern`: 正则约束
5. `masking`: `UNSET/NONE/PARTIAL/FULL/HASH`

### 5.7 `@AttrHintRichContent`

富文本语义：

1. `format`: `UNSET/HTML/MARKDOWN`
2. `sanitizePolicy`: `UNSET/NONE/BASIC/STRICT`
3. `maxLength`: 最大长度（`-1` 不限制）

### 5.8 `@AttrHintNumber`

数值语义：

1. `value`: `NumberRole`
2. `precision`: 总位数（`-1` 不限制）
3. `scale`: 小数位（`-1` 不限制）
4. `min/max/step`: 字符串表示的范围与步长
5. `unit`: 单位描述

### 5.9 `@AttrHintMedia`

媒体语义：

1. `value`: `MediaRole`
2. `pathMode`: `UNSET/OBJECT_KEY/RELATIVE_PATH/ABSOLUTE_URL`
3. `accept`: 允许类型
4. `maxCount`: 最大文件数（`-1` 不限制）
5. `maxSize`: 单文件最大字节（`-1` 不限制）

### 5.10 `@AttrHintJson`

JSON 语义：

1. `value`: `JsonRole`
2. `validateMode`: `UNSET/NONE/BASIC/STRICT`
3. `schemaRef`: JSON schema 标识/地址
4. `maxBytes`: 最大字节数（`-1` 不限制）

---

## 6. Role 枚举

当前角色枚举：

1. `EnumRole`: `UNSET/GENERIC/STATUS`
2. `TextRole`: `UNSET/GENERIC/SECRET`
3. `NumberRole`: `UNSET/GENERIC/MONEY/RATE`
4. `RefIdRole`: `UNSET/GENERIC/TENANT`
5. `DateTimeRole`: `UNSET/GENERIC/CREATED_TIME/UPDATED_TIME/DELETED_TIME`
6. `MediaRole`: `UNSET/GENERIC/FILE/IMAGE`
7. `JsonRole`: `UNSET/GENERIC`
8. `FlagRole`: `UNSET/GENERIC/ENABLED/DEMO/SOFT_DELETE`

---

## 7. 默认值编解码（core-util）

包路径：`com.framework2.core.util.value`

### 7.1 `TypedValueType`

通用值类型：

`UNSET/STRING/BOOLEAN/INT/LONG/DECIMAL/JSON/ISO_LOCAL_DATE/ISO_LOCAL_DATE_TIME/INSTANT/EPOCH_MILLIS/EPOCH_SECONDS`

### 7.2 `TypedValueCodec`

常用方法：

1. `deserialize(String rawValue, TypedValueType type)`
2. `serialize(Object value, TypedValueType type)`
3. `inferType(Class<?> javaType)`

规则要点：

1. `createDefaultValue` 为空字符串视为未设置。
2. `createDefaultValueType != UNSET` 时按显式类型解析。
3. `createDefaultValueType == UNSET` 时建议按字段 Java 类型与 `AttrKind` 推断。
4. 解析失败建议在 `STRICT` 模式启动失败，在 `WARN` 模式记录告警并忽略默认值。

---

## 8. 合法 Hint 组合

建议映射：

1. `ID` -> `@AttrHintId`
2. `REF_ID` -> `@AttrHintRefId`
3. `TEXT` -> `@AttrHintText`
4. `RICH_CONTENT` -> `@AttrHintRichContent`
5. `NUMBER` -> `@AttrHintNumber`
6. `ENUM` -> `@AttrHintEnum`
7. `FLAG` -> `@AttrHintFlag`
8. `DATETIME` -> `@AttrHintDateTime`
9. `MEDIA` -> `@AttrHintMedia`
10. `JSON_DOC` -> `@AttrHintJson`

若字段标注多个不兼容 Hint，建议在校验阶段直接失败。

---

## 9. 示例清单

1. `taskStatus` -> `@Attr(ENUM) + @AttrHintEnum(STATUS)`
2. `tenantId` -> `@Attr(REF_ID) + @AttrHintRefId(TENANT, ...)`
3. `createTime` -> `@Attr(DATETIME) + @AttrHintDateTime(CREATED_TIME)`
4. `goodsDesc` -> `@Attr(RICH_CONTENT) + @AttrHintRichContent`
5. `priceAmount` -> `@Attr(NUMBER) + @AttrHintNumber(MONEY)`
6. `extJson` -> `@Attr(JSON_DOC) + @AttrHintJson(GENERIC)`

---

## 10. 版本说明

当前 README 以仓库内代码为准，不再描述尚未落地的未来模块实现细节。

---

## 11. V1 重构稿补充块（去重合并）

说明：

1. 本节来源于你提供的“V1 重构稿”新增内容块。
2. 与当前 README 已有章节重复或冲突时，以当前 README 既有内容为准。
3. 本节用于补充“目标架构/规则方法论”信息，不替代当前实现说明。

### 11.1 文档状态（补充）

- 状态：`ACTIVE`
- 版本：`v1.0-rebuilt-draft`
- 目标：将 Attr 语义规则与新模块架构对齐，作为后续实现与迁移基线。
- 说明：本稿从旧版 `ATTR_KIND_RULES_V1.md` 迁移核心规则，术语统一到 `java-to-schema`。

### 11.2 新架构目录基线（补充，目标态）

```text
framework2
├── docs
│   └── kernel
│       ├── ATTR_KIND_RULES_V1.md
│       └── ATTR_KIND_RULES_V1_REBUILT.md
├── framework2-core-util
├── framework2-java-attr
│   ├── framework2-java-attr-annotations
│   ├── framework2-java-attr-model
│   ├── framework2-java-attr-parser
│   ├── framework2-java-attr-validation
│   └── framework2-java-attr-api
├── framework2-java-to-schema
│   ├── framework2-java-to-schema-annotations
│   ├── framework2-java-to-schema-mapper
│   └── framework2-java-to-schema-starter-spring
├── framework2-java-to-ui
│   ├── framework2-java-to-ui-annotations
│   ├── framework2-java-to-ui-model
│   ├── framework2-java-to-ui-mapper
│   ├── framework2-java-to-ui-view-support
│   └── framework2-java-to-ui-starter-spring
├── framework2-schema
│   ├── framework2-schema-model
│   ├── framework2-schema-sync-engine
│   ├── framework2-schema-jdbc-support
│   └── framework2-schema-view-support
└── framework2-test
    ├── framework2-test-fixtures
    ├── framework2-test-core
    ├── framework2-test-java-attr-integration
    ├── framework2-test-java-to-schema-jdbc-integration
    ├── framework2-test-java-to-ui-integration
    └── framework2-test-spring-integration
```

### 11.3 模块定位（补充）

1. `framework2-java-attr`：语义核心层，定义与解析 `@Attr` 语义，不依赖 schema/ui 实现。
2. `framework2-java-to-schema`：投影层，将 Java/Attr 语义映射为 schema 目标结构。
3. `framework2-java-to-ui`：投影层，将 Java/Attr 语义映射为 UI 元数据。
4. `framework2-schema`：物理结构内核，负责模型、diff、执行、JDBC 支撑，不感知 Attr 注解。
5. `framework2-test`：单测与集成回归层。

依赖方向：

1. `java-to-schema` -> `java-attr` + `schema`
2. `java-to-ui` -> `java-attr`
3. `java-to-schema` 与 `java-to-ui` 不互相依赖
4. `schema` 不反向依赖 `java-to-schema`

### 11.4 术语与注解迁移（补充）

兼容策略（建议）：

1. V1 允许兼容读取旧注解。
2. 新增/新文档只使用 `@Jts*` 命名。
3. 迁移完成后移除旧别名。

### 11.5 推断与覆盖链（补充）

优先级：

1. `Java类型 + 名称规则`（同层基线）
2. `@Attr(AttrKind.*)`
3. `@AttrHint*`
4. `java-to-schema/java-to-ui` 默认投影
5. `@JtsColumn`（schema 最终覆盖）/ `@Ui*`（UI 最终覆盖）

同层基线冲突：

1. 精确命中
2. 后缀命中
3. 词干命中
4. 纯类型基线

### 11.6 基线推断规则（补充）

Java 类型映射：

1. `String` -> `TEXT`
2. `Long/long` -> `NUMBER`（命中 `*Id` 时 -> `REF_ID`）
3. `Integer/int/Short/short/Byte/byte/BigInteger` -> `NUMBER`
4. `BigDecimal/Double/double/Float/float` -> `NUMBER`
5. `Boolean/boolean` -> `FLAG`
6. `LocalDate/LocalTime/LocalDateTime/Instant` -> `DATETIME`
7. `UUID` -> `TEXT`
8. `byte[]` -> `MEDIA`
9. `Enum<?>` -> `ENUM`

名称规则（补充）：

1. `id` -> `ID`
2. `status` -> `ENUM + STATUS`
3. `type` -> `ENUM + TYPE`
4. `deleted/isDeleted` -> `FLAG + SOFT_DELETE`
5. `createTime/createdAt` -> `DATETIME + CREATED_TIME`
6. `updateTime/updatedAt` -> `DATETIME + UPDATED_TIME`
7. `deleteTime/deletedAt` -> `DATETIME + DELETED_TIME`
8. `*Id` -> `REF_ID`
9. `*Json` -> `JSON_DOC`
10. `*Time/*Date` -> `DATETIME`

### 11.7 专项规则补充（方法论）

1. `REF_ID`：`field` 默认 `id`；`labelFields` 与 `labelTemplate` 按字段级 > 实体级 > 全局策略回退。
2. `DATETIME`：支持 `NATIVE_DATETIME`、`EPOCH_MILLIS`、`EPOCH_SECONDS` 双模语义（具体以当前实现章节为准）。
3. 字段注释策略：默认 `NAME_ONLY`，注释建议不超过 `1024 bytes`。
4. `plannedVolume` 用于运行策略评估：规模、风险、方言能力。
5. 索引治理：唯一约束语义在 Attr 侧声明，schema 层处理方言细节。

### 11.8 默认投影（补充）

`java-to-schema` 默认类型：

1. `ID` -> `bigint`
2. `REF_ID` -> `bigint`
3. `ENUM` -> `int/varchar(32)`
4. `FLAG` -> `tinyint(1)/boolean`
5. `RICH_CONTENT` -> `text/longtext`
6. `NUMBER` -> 数值型
7. `MEDIA` -> `varchar/text/blob`
8. `JSON_DOC` -> `json/text`
9. `DATETIME` -> `datetime/date/time/bigint(epoch)`
10. `TEXT` -> `varchar(255)/text`

`java-to-ui` 默认组件：

1. `ID` -> 只读标识
2. `REF_ID` -> 引用选择器
3. `ENUM` -> `select/radio`
4. `FLAG` -> `switch/checkbox`
5. `RICH_CONTENT` -> 富文本编辑器
6. `NUMBER` -> 数字输入
7. `MEDIA` -> 上传器
8. `JSON_DOC` -> JSON 编辑/查看
9. `DATETIME` -> 时间组件
10. `TEXT` -> `input/textarea`

### 11.9 落地顺序（补充）

1. 先落 `framework2-java-attr-*`：注解、模型、解析、校验、API。
2. 再落 `framework2-java-to-schema-*`：注解、映射器、Spring 启动接入。
3. 同步对接 `framework2-schema-*`：模型、sync-engine、jdbc-support、view-support。
4. 再落 `framework2-java-to-ui-*`：注解、模型、映射、view-support。
5. 最后补齐 `framework2-test-*` 的单测与集成回归。

### 11.10 非目标（补充）

1. 不在 V1 引入 profile/多租户策略编排。
2. 不在 V1 定义完整页面模板生成器。
3. 不在 V1 覆盖复杂多表分析看板能力。