tableDB/CHANGELOG.md

# CHANGELOG

## v1.1.8 (2026-05-16)
- **文档增强**:
  - **Hook 事件指南**: 在 `README.md` 中新增了 Hook 事件的详细声明与用法说明，涵盖从表结构变更到数据 CRUD 的全生命周期钩子。

## v1.1.7 (2026-05-15)
- **底层架构重构与标准字段**:
  - **强制标准字段**: 所有数据表自动携带并维护 5 个标准字段（`id`, `creator`, `createTime`, `updater`, `updateTime`），极大地规范了业务记录生命周期。
  - **默认倒序排列**: `List` 与 `Query` 现默认按 `createTime DESC` 返回数据，以符合现代业务开发直觉。
  - **严格的 SELECT 安全**: `buildQuery` 彻底摒弃了 `SELECT *`，基于内存缓存中的合法字段列表动态拼接 SQL，彻底杜绝已删除残余字段的泄露。
- **Hook 系统重构**:
  - **增强上下文注入**: 全面重构了 `Hooks` 接口签名，现在 `OnUpdatedRows`、`OnRemovedRows` 等事件会完整返回 `rows/ids` 以及关联的 `TableSchema` 和 `FieldSchema`。
  - **RAG 友好型设计**: 增强后的 Hook 系统能够让外部模块（如 RAG 索引器）在零额外查询的情况下，直接获取所需的所有元数据与数据正文。
- **基础设施对齐与 ID 自动化**:
  - **移除手动 ID 生成**: 去除了 `tableDB` 内部的 `record["id"] = id.MakeID(10)` 逻辑，完全下推至 `go/db` 基础设施处理。
  - **自动随机 ID 识别**: 配合底层 `db` 升级，现在只要字段名为 `id`、类型为 `char(8~16)` 且在插入时为空，系统将自动产生全局随机 ID。
  - **分布式 ID 支持**: `GetDB` 增加 `redis` 参数，用于配置底层 `db` 的 Redis 实例，确保在分布式环境下生成的 ID 具备全局唯一性。
- **架构重构稳定性修复**:
  - **修复 Schema 重建 bug**: 修正了 `reconstructAndSyncSchema` 在生成 DSL 时丢失 `PK` (Primary Key) 标记的问题，确保动态创建的表始终具备正确的索引结构。
  - **对齐 GetDB 签名**: 同步更新所有测试用例与示例文档，对齐最新的多参数初始化模型。

## v1.1.6 (2026-05-15)
- **零开销 ABAC 鉴权引擎**:
  - **内存展平技术**: 引入 `SchemaCache` 策略展平算法，支持无限深度的用户权限继承（如 `Manager -> Boss`），并将复杂权限图谱在内存中转换为 O(1) 的平滑映射，彻底消除运行时递归与 N+1 数据库查询。
  - **1-RTT 动态 SQL 注入**: 重构 `checkAuth` 与 `appendAuthAndConstraint`，将行级过滤条件（RLS）直接下推至 SQL WHERE 子句中。无论是 `Get`, `List` 还是 `Remove`，所有权限校验均与业务查询合并执行，确保极致性能。
  - **Opt-in 行级安全**: `_Table` 增加 `enableRLS` 开关。仅在显式开启的表上执行权限拦截，避免普通表（如字典表、日志表）产生不必要的计算开销。
- **全新策略管理 API**:
  - 新增 `SetPolicy` 与 `ListPolicy` 接口，支持标准化的 ABAC 策略配置（SQL 条件、参数绑定）。
  - **权限分级管理**: 实现了自主授权逻辑。普通用户仅在拥有目标表 `full` 权限时方可为他人分配该表权限；`inherit` 类高阶策略仅限 `SystemUserID` 操作。
- **极致性能与校验**:
  - **O(1) 字段验证**: 增加 `ValidFieldsMap` 缓存，消除 `buildQuery` 过程中高频的 Map 构建开销。
  - **防死锁与容错**: 权限继承逻辑内置环状检测，自动忽略 `A -> B -> A` 式的逻辑死循环。
- **文档与工程化**:
  - 全面重写 `README.md`，以 AI 驱动开发为中心，提供了清晰的 Schema 与 Policy 使用示例。
  - 同步更新 `.profile/README.md`，对齐基础设施版本索引。

## v1.1.5 (2026-05-14)
- **强制身份校验模型**: 重构 `GetDB` 返回类型为 `*TableDBUnauthorized`，在编译期强制要求必须先调用 `Auth` 后才能执行后续数据表操作。
- **自定义元数据扩展**: 在系统表 `_Table` 和 `_Field` 中增加了 `settings` (JSON) 字段，业务方可通过 `TableSchema` 和 `FieldSchema` 存储自定义的表级或字段级配置。
- **Schema API 正规化**: 引入了完整的 `TableSchema` 结构体，并将 `SetTable` 和 `RemoveTable` API 上提至 `TableDB` 层级。彻底废弃并移除了遗留的 `Table("xxx:Schema")` 魔法后缀调用方式。
- **底层行为一致性**: `SetTable`, `RemoveTable`, `SetField`, `RemoveField` 现已彻底改写为底层封装调用 `Table("_Table")` 和 `Table("_Field")` 的 `Set/Remove` 方法，确保了系统自动更新的时间戳(`createTime`)、操作人(`creator`)及各种 Hook 生命周期事件能够被 100% 一致地触发。

## v1.1.4 (2026-05-14)
- **API 语义优化**: 
  - `Query` 方法从 `TableDB` 移动到 `Table` 对象，更符合面向对象调用习惯；`QueryRequest` 移除 `Table` 字段。
  - 移除 `App` 类型别名，统一使用 `TableDB`。
  - `SyncSchema` 改为私有方法 `syncSchema`，外部调用统一通过 `SetTable` 和 `SetField` 进行结构维护。
- **结构维护增强**:
  - 新增 `SetTable(memo)` 用于设置表元数据。
  - `SetField` 参数从 `any` 改为强类型的 `FieldSchema` 切片，并自动忽略 `CreateTime` 等系统字段，增强类型安全性。
  - `SetField` 在创建新表时会自动补全 `id` 字段的元数据，确保查询验证一致性。
  - 新增 `Tables()` 方法，支持列出当前用户有权访问的所有数据表。
- **安全性完善**: 
  - 强化了所有公共 API 的 Auth 检查，确保未授权实例无法执行任何操作。
  - 内部 `buildQuery` 现在需要明确传入表名，增强了多表操作时的上下文隔离。
- **测试回归**: 完全重构了测试用例，所有业务表创建均通过 `SetField` 接口完成，验证了公共 API 的闭环能力。

## v1.1.3 (2026-05-14)
- **API 统一与简化**: 引入 `SetField` 和 `RemoveField` 接口，支持通过统一的 Table API 动态管理表结构，实现了“操作表结构像操作数据一样简单”。
- **批量操作支持**: `Set`, `Remove`, `SetField`, `RemoveField` 全面支持变长参数（Variadic arguments），显著提升了批量数据处理效率。
- **安全性增强**: 
  - `GetDB` 返回实例默认未授权，强制调用 `Auth` 进行身份绑定。
  - `GetRawDB` (原 `Base`) 现已增加权限校验，仅限 `_system` 身份访问。
  - `Query` (App 级) 现已自动集成行级权限过滤。
- **性能与稳定性**: 优化了元数据同步流程，合并批量操作后的 Schema 重建；修复了 `Cache.Load` 在并发调用时的死锁隐患。
- **文档完善**: 重新编写了 README.md，完全抹除了实现细节，侧重于纯粹的 API 指南与最佳实践。

## v1.1.2 (2026-05-14)
- **文档重构**: 重新编写 README.md，以 AI 为中心，侧重于 API 功能说明与使用指南，移除了无关的实现细节。
- **命名规范对齐**: 消灭了所有 Struct 中的 `json` tag，全面对齐驼峰命名规范，利用 `cast` 库自动处理大小写转换。
- **API 完整性**: 基于 `getExports` 工具补全了 API 文档，涵盖了常量、全局变量及完整的 Table 操作接口。

## v1.1.1 (2026-05-14)
- **基础设施对齐**: 深度对接 `@go/db` 的自动 ID 生成器 (`NextID`) 与版本管理特性。
- **元数据模型对齐**: 重构 `FieldSchema` 结构体，对齐 `_Field` 表物理结构，并统一使用 `cast.Convert` 进行 JSON 兼容的类型转换。
- **查询安全性强化**: 增强 `BuildQuery` 的标识符验证与自动转义（Backticks），防止潜在的 SQL 注入风险。
- **Schema 同步健壮性**: 优化 `reconstructAndSyncSchema` 与 `SyncSchema` 的元数据采集逻辑，支持更复杂的 DSL 结构。

## v1.1.0
- **内置系统架构 (SystemSchema)**: `_Table`, `_Field`, `_Policy` 等核心元数据表现已内置，`SyncSchema` 会在启动时自动补齐，无需在业务 DSL 中显式定义。
- **自动化 Schema 修复**: 修复了通过 API 创建表时缺少 `id` 字段导致的同步失败问题；`reconstructAndSyncSchema` 现在会自动为所有表补齐 `id c10 PK` 主键。
- **全域行级权限增强**: 行级权限检查逻辑现已扩展至所有包含 `creator` 字段的表（不仅限于系统表），通过 `Auth(userID)` 创建的实例在插入新记录时会自动填充 `creator`。
- **元数据安全性提升**: `_Field` 和 `_Policy` 现在也包含 `creator` 字段，支持对元数据本身的行级访问控制。
- **测试套件重构**: 全面重新设计了测试用例，覆盖了从零启动、API 驱动的架构变更、影子删除、策略授权及 Hook 触发等全量场景。

## v1.0.0
- **初始化重构迁移**: 剥离自 `knowbase/internal/db` 作为纯净独立包。
- **动态 Schema 管理**: 保留动态解析与同步，并封装独立的缓存与 Hook 事件触发逻辑。
- **权限隔离体系**: 通过 `Auth(userID)` 方法引入多维度的数据隔离层，`SystemUserID` 下退化为超管权限操作全域数据。