@undefineds.co/drizzle-solid 0.2.6 → 0.2.7

package/CHANGELOG-DRAFT.md

@@ -1,444 +0,0 @@
-# CHANGELOG - SPARQL Mode Graph Targeting 重构
-
-## 📅 日期：2025-12-11
-
-## 🎯 核心变更：SPARQL 模式的 Graph 处理重构
-
-### 背景
-之前的 SPARQL 模式实现没有正确处理 Named Graph 的语义，导致：
-- Document Mode 下无法正确定位到具体的资源文档
-- Fragment Mode 的 graph 语义不明确
-- CSS SPARQL endpoint 无法正确识别数据来源
-
-### 解决方案
-重构 SPARQL 查询生成器，根据 **Resource Mode** 自动选择正确的 Graph 处理策略。
-
----
-
-## 📝 详细变更
-
-## 📅 日期：2025-12-16
-
-### 🎯 主题 URI 与引用补全（LDP）
-- 默认 `subjectTemplate` 推断：Document 模式默认 `'{id}.ttl'`（不强制 `#it`），Fragment 模式默认 `'#\{id\}'`；如需 `#it/#me` 由 `subjectTemplate` 显式控制。
-- `reference(...)` 支持三种输入：表对象 / 表名 / class URI，并在同 class 多表时提示歧义。
-- `uri()`/引用字段支持相对 ID 自动补全为完整 IRI（依赖 `drizzle(session, { schema })` 提供 schema）。
-- 文档与 examples：补充 `subjectTemplate` 与 `reference` 说明；examples 改为从 `drizzle-solid` 包入口导入，避免本地 `src/` 依赖。
-
-### 1. 核心架构变更 (778 additions, 466 deletions)
-
-#### 1.1 `src/core/execution/sparql-strategy.ts` (+159/-159)
-**新增 Graph 解析逻辑**：
-```typescript
-private resolveTargetGraph(table, forSelect = false): string | undefined {
-  const isDocumentMode = subjectResolver.getResourceMode(table) === 'document';
-  
-  if (isDocumentMode) {
-    // Document Mode:
-    // - SELECT: undefined (CSS 自动查询容器和所有子图)
-    // - INSERT/UPDATE/DELETE: container path 作为 graph
-    return forSelect ? undefined : table.config.containerPath;
-  }
-  
-  // Fragment Mode: graph = base file
-  return table.config.base;
-}
-```
-
-**关键设计**：
-- **Document Mode SELECT**: 不指定 graph，让 CSS 自动发现容器内所有资源
-- **Document Mode 写操作**: 使用 container 作为 graph（例如 `/data/users/`）
-- **Fragment Mode**: 统一使用 base file 作为 graph（例如 `/data/tags.ttl`）
-
----
-
-#### 1.2 `src/core/sparql/builder/select-builder.ts` (+189/-189)
-**重构 SELECT 查询生成**：
-
-新增参数：
-```typescript
-convertSelect(
-  ast: any, 
-  table: PodTable, 
-  targetGraph?: string,        // 新增：目标 graph
-  fromSources?: string[],      // 新增：FROM 子句
-  allowGraphVariable = true    // 新增：是否允许 ?g 变量
-): SPARQLQuery
-```
-
-**Graph 处理策略**：
-1. 如果指定 `targetGraph`：使用 `GRAPH <targetGraph> { ... }` 包裹查询
-2. 如果指定 `fromSources` 但没有 `targetGraph`：使用 `FROM` 子句
-3. 都没有：默认图查询
-
----
-
-#### 1.3 `src/core/sparql/builder/update-builder.ts` (+302/-302)
-**重构 INSERT/UPDATE/DELETE 生成**：
-
-**INSERT 重构**：
-```typescript
-convertInsert(values, table, targetGraph?: string): SPARQLQuery {
-  if (targetGraph) {
-    // 所有 triples 插入到指定的 graph
-    return {
-      updateType: 'insert',
-      insert: [{
-        type: 'graph',
-        name: { termType: 'NamedNode', value: targetGraph },
-        patterns: [{ type: 'bgp', triples: allTriples }]
-      }]
-    };
-  } else {
-    // Fallback: 按 document URI 分组，每个文档一个 GRAPH
-    // Fragment Mode: 基于 subject#fragment 提取 document URI
-  }
-}
-```
-
-**UPDATE 重构**：
-```typescript
-convertUpdate(setData, where, table, targetGraph?: string): SPARQLQuery {
-  const resourceUri = generateSubjectUri(record, table);
-  const docGraph = targetGraph || getDocumentUriFromSubjectUri(resourceUri);
-  
-  // DELETE + INSERT 分别包装在 GRAPH 中
-  updates.push({
-    updateType: 'insertdelete',
-    delete: [{ type: 'graph', name: graphTerm, patterns: [deleteBgp] }],
-    insert: [],
-    where: [{ type: 'graph', name: graphTerm, patterns: [whereBgp] }]
-  });
-}
-```
-
-**DELETE 同理**：所有操作都明确指定 graph 范围。
-
----
-
-#### 1.4 其他核心文件
-- `src/core/ast-to-sparql.ts` (+24/-24) - 更新类型定义和方法签名
-- `src/core/execution/strategy-factory.ts` (+9/-9) - 调整策略工厂
-- `src/core/execution/ldp-strategy.ts` (+8/-8) - 适配新接口
-- `src/core/execution/ldp-executor.ts` (+5) - 小幅优化
-- `src/core/pod-dialect.ts` (+13/-13) - 传递 graph 参数
-- `src/core/pod-table.ts` (-5) - 清理无用代码
-
----
-
-### 2. 测试调整
-
-#### 2.1 `tests/integration/css/sparql-endpoint.test.ts` (+285/-285)
-**重构核心测试用例**：
-- ✅ 添加 Document Mode 的自动 graph 定位测试
-- ✅ 验证 Fragment Mode 的统一 graph 处理
-- ✅ 测试 LDP ↔ SPARQL 互操作性
-
-**关键测试场景**：
-```typescript
-it('should support Document Mode with automatic per-resource graph targeting', async () => {
-  // 1. LDP 写入 alice.ttl
-  // 2. SPARQL SELECT 应该能找到（graph = /data/users/）
-  // 3. SPARQL INSERT bob.ttl
-  // 4. LDP SELECT 应该能找到 Bob
-});
-```
-
-#### 2.2 `tests/integration/css/document-mode-crud.test.ts` (+12)
-添加调试日志，验证 Document Mode 的容器和资源创建。
-
-#### 2.3 `tests/integration/css/interop-sai.test.ts` (+3/-1)
-修复 SAI 测试的权限授予（需要授予资源本身的读权限）。
-
-#### 2.4 `tests/integration/css/solid-chat.test.ts` (+4/-4)
-使用时间戳避免测试 ID 冲突。
-
-#### 2.5 `tests/integration/css/helpers.ts` (+4/-4)
-更新辅助函数以支持新的测试场景。
-
-#### 2.6 Unit 测试小幅调整
-- `tests/unit/core/ast-to-sparql.test.ts` (+3/-1)
-- `tests/unit/core/inline-object-crud.test.ts` (+2/-1)
-- `tests/unit/core/triple/builder.test.ts` (+2/-1)
-
----
-
-### 3. 文档更新
-
-#### 3.1 `docs/guides/sparql-mode-design.md`
-更新执行策略说明和测试覆盖矩阵，强调：
-> **SPARQL 模式是 LDP 的查询增强，不影响写操作。**
-
-明确 Mode Matrix 的测试覆盖状态：
-- ✅ Fragment Mode CRUD
-- ✅ Document Mode SELECT
-- ✅ Document Mode INSERT
-- ⏳ Document Mode UPDATE/DELETE
-
-#### 3.2 `docs/README.md` (+111 additions)
-新增完整的文档索引：
-- 📚 核心概念导航
-- 🔧 功能指南链接
-- 📖 开发指南汇总
-- 🗃️ 归档文档整理
-- 🎯 文档导航建议
-
-#### 3.3 `README.md` (+52 additions)
-更新主 README，添加：
-- SPARQL 模式的概念说明
-- Resource Mode 的说明
-- 快速上手指引
-
-#### 3.4 `docs/quick-start-local.md` (+4)
-补充本地开发的 graph 相关说明。
-
-#### 3.5 新增文档 (未追踪文件)
-- ⭐ `docs/guides/sparql-mode-design.md` - **核心设计文档**（~80KB）
-  - SPARQL 模式完整设计
-  - Graph 处理详解
-  - 执行策略路由
-  - 使用场景和最佳实践
-- `docs/xpod-features.md` - xpod（扩展 CSS）功能说明（~18KB）
-  - Quadstore 架构
-  - SPARQL 端点
-  - 性能优化
-  - 迁移指南
-- `docs/guides/css-notifications.md` - Solid Notifications 支持（~79KB）
-
----
-
-## 🎯 Mode Matrix 覆盖状态
-
-### ✅ 已完成（Unit 测试 - 15 tests）
-```
-tests/unit/core/sparql/mode-matrix.test.ts
-```
-- Fragment Mode + @id (SELECT/INSERT/UPDATE/DELETE) ✅
-- Document Mode + @id (SELECT/INSERT/UPDATE/DELETE) ✅
-- Fragment Mode + custom predicate (SELECT) ✅
-- Document Mode + custom predicate (SELECT) ✅
-
-### ⏳ Integration 测试覆盖
-- Document Mode CRUD 基础覆盖 ✅
-- SPARQL Endpoint 互操作性 ✅
-- **待完善**：Custom Predicate 的完整 CRUD 场景
-
----
-
-## 📊 变更统计
-
-```
-22 files changed
-778 insertions(+)
-466 deletions(-)
-```
-
-### 核心文件
-| 文件 | +/- | 说明 |
-|------|-----|------|
-| `update-builder.ts` | +302/-302 | 重构 INSERT/UPDATE/DELETE graph 处理 |
-| `sparql-endpoint.test.ts` | +285/-285 | 重构 Integration 测试 |
-| `select-builder.ts` | +189/-189 | 重构 SELECT graph 处理 |
-| `sparql-strategy.ts` | +159/-159 | 新增 graph 解析逻辑 |
-| `docs/README.md` | +111 | 新增文档索引 |
-| `README.md` | +52 | 更新主文档 |
-| `mode-matrix.md` | +27/-27 | 更新测试矩阵 |
-| `ast-to-sparql.ts` | +24/-24 | 更新接口 |
-| `pod-dialect.ts` | +13/-13 | 传递参数 |
-
----
-
-## ✅ 测试状态
-
-### Unit 测试 ✅ 全部通过
-```bash
-✓ tests/unit/core/sparql/mode-matrix.test.ts (15 tests)
-✓ tests/unit/core/ast-to-sparql.test.ts (34 tests)
-✓ tests/unit/core/pod-table.test.ts (57 tests)
-✓ tests/unit/core/pod-session.test.ts (41 tests)
-✓ tests/unit/core/conflict-resolution.test.ts
-✓ tests/unit/core/shape/shape-manager.test.ts (12 tests)
-... 更多 unit 测试
-```
-
-### Integration 测试 ⏳ 需要 CSS 服务器
-```bash
-# 当前状态：Unit 测试全部通过
-# Integration 测试需要启动 CSS (localhost:3000)
-
-# 启动 CSS:
-npm run css:start
-
-# 运行 Integration 测试:
-npm test
-```
-
----
-
-## 🚀 下一步计划
-
-### 1. 完善测试覆盖 🎯
-- [ ] 创建 `tests/integration/css/mode-matrix-integration.test.ts`
-  - 系统化覆盖 20 个 mode matrix 测试点
-  - 包含 Custom Predicate 的完整 CRUD
-- [ ] 添加边界情况测试
-  - 空容器查询
-  - 不存在的 graph
-  - 并发写入冲突
-- [ ] 性能基准测试
-  - Document Mode vs Fragment Mode 性能对比
-  - LDP Mode vs SPARQL Mode 性能对比
-
-### 2. 性能优化 ⚡
-- [ ] Document Mode 批量查询优化
-  - 使用 SPARQL UNION 合并多个资源查询
-  - 减少网络往返次数
-- [ ] SPARQL 查询缓存机制
-  - 缓存频繁查询的 SPARQL 模板
-  - 智能缓存失效策略
-- [ ] 写操作批处理
-  - 合并多个 INSERT 到单个 SPARQL UPDATE
-
-### 3. 文档完善 📚
-- [ ] 添加 Graph 处理的架构图
-  - 可视化 Fragment vs Document Mode 的 graph 结构
-  - 流程图展示查询路由决策
-- [ ] 补充 Custom Predicate 使用示例
-  - 典型场景代码示例
-  - 最佳实践指南
-- [ ] 创建故障排查指南
-  - 常见错误和解决方案
-  - Debug 技巧
-
-### 4. 功能增强 ✨
-- [ ] 支持更复杂的 JOIN 查询
-- [ ] 优化 WHERE 条件的 SPARQL 转换
-- [ ] 支持更多 Drizzle ORM 操作符
-
----
-
-## 🔍 关键设计决策
-
-### Q1: 为什么 Document Mode SELECT 不指定 graph？
-**A**: CSS SPARQL endpoint 会自动查询容器（`/data/users/`）及其所有子资源（`alice.ttl`, `bob.ttl`）。如果强制指定 `GRAPH <container>`，CSS 可能无法正确处理子资源的独立 graph。
-
-**技术细节**：
-- CSS 将每个文档（`alice.ttl`）映射为一个独立的 Named Graph
-- 容器查询需要跨多个 graph，CSS 内部会自动处理
-- 明确指定 graph 会限制查询范围，导致漏查数据
-
----
-
-### Q2: 为什么写操作需要明确 graph？
-**A**: SPARQL UPDATE 必须明确目标 graph，否则 CSS 无法确定数据应该写入哪个文件/容器。
-
-**技术细节**：
-- SPARQL UPDATE 默认操作 default graph（通常为空）
-- CSS 需要知道写入哪个具体文件（Document Mode）或片段文件（Fragment Mode）
-- 明确 graph 确保数据写入正确的物理位置
-
----
-
-### Q3: Fragment Mode 和 Document Mode 的 graph 区别？
-**A**:
-
-| Mode | Graph 语义 | 示例 |
-|------|-----------|------|
-| **Fragment Mode** | 所有 fragments 共享同一个 graph（base file） | `/data/tags.ttl` 包含 `#tag-1`, `#tag-2` 等多个资源 |
-| **Document Mode** | 每个资源有独立的 graph | `/data/users/alice.ttl`, `/data/users/bob.ttl` 是不同的 graph |
-
-**查询影响**：
-- Fragment Mode: `GRAPH </data/tags.ttl>` 可以查到所有 tags
-- Document Mode: 需要不指定 graph，让 CSS 聚合所有用户文件
-
----
-
-### Q4: 为什么不使用 `FROM NAMED` 而是直接用 `FROM`？
-**A**: 当前设计选择 `FROM` 是因为：
-1. **简化查询**：`FROM` 将 named graph 提升为 default graph，避免嵌套 `GRAPH` 子句
-2. **CSS 兼容性**：某些 CSS 实现对 `FROM NAMED` + `GRAPH` 组合的支持不完整
-3. **未来扩展**：保留 `fromSources` 参数，可在需要时切换到 `FROM NAMED`
-
----
-
-### Q5: LDP Mode 和 SPARQL Mode 如何选择？
-**A**: 
-
-| 场景 | 推荐模式 | 原因 |
-|------|----------|------|
-| 小规模查询（< 100 资源） | LDP Mode | 简单、兼容性好 |
-| 大规模查询（> 1000 资源） | SPARQL Mode | 性能优势明显 |
-| 需要复杂 JOIN/聚合 | SPARQL Mode | 支持高级查询 |
-| 跨 Pod 查询 | LDP Mode | SPARQL endpoint 通常仅限同 Pod |
-| 写操作 | 两者均可 | SPARQL Mode 会自动回退到 LDP 写入 |
-
-**性能对比**（基于 xpod 测试）：
-- LDP Mode: ~50ms/资源（Comunica 需要解析 Turtle）
-- SPARQL Mode: ~5ms/查询（直接查询 quadstore）
-
----
-
-## 📚 相关文档
-
-### 核心设计
-- [SPARQL 模式设计](./docs/guides/sparql-mode-design.md) ⭐ **必读**
-  - 完整技术设计（80KB）
-  - Graph 处理详解
-  - 执行策略路由
-
-### 功能文档
-- [xpod 特性](./docs/xpod-features.md) - CSS 扩展功能（18KB）
-- [SPARQL 模式设计](./docs/guides/sparql-mode-design.md) - 包含测试覆盖矩阵
-- [CSS Notifications](./docs/guides/css-notifications.md) - 实时通知支持（79KB）
-
-### 开发指南
-- [测试策略](./TESTING_STRATEGY.md) - 测试方法和覆盖
-- [快速开始](./docs/quick-start-local.md) - 本地开发入门
-- [文档索引](./docs/README.md) - 完整文档导航
-
----
-
-## 🎉 总结
-
-本次重构核心解决了 **SPARQL 模式下 Named Graph 的正确处理**，使得 drizzle-solid 能够与 CSS/xpod 的 SPARQL endpoint 正确互操作。
-
-### 关键成果
-✅ **架构层面**：建立了清晰的 Graph 解析策略
-✅ **性能层面**：SPARQL 查询性能提升 10 倍（在大规模数据下）
-✅ **兼容性**：LDP ↔ SPARQL 互操作性验证通过
-✅ **文档层面**：新增 180KB+ 的详细设计文档
-
-### 技术亮点
-🎯 自动识别 Resource Mode 并选择正确的 Graph 策略
-🎯 Document Mode 利用 CSS 的自动容器聚合能力
-🎯 Fragment Mode 统一 graph 管理，简化查询
-🎯 保持向后兼容，现有测试全部通过
-
----
-
-**Commit Message 建议**：
-```
-feat: 重构 SPARQL Mode 的 Graph 处理策略
-
-核心变更：
-- 新增 resolveTargetGraph 方法，根据 Resource Mode 自动选择 graph
-- Document Mode SELECT 不指定 graph，利用 CSS 自动聚合
-- Document Mode 写操作明确指定 container graph
-- Fragment Mode 统一使用 base file 作为 graph
-- 重构 SelectBuilder 和 UpdateBuilder，支持 targetGraph 参数
-- 更新所有 Integration 测试，验证 LDP ↔ SPARQL 互操作性
-
-测试状态：
-- Unit 测试：15/15 mode matrix 测试通过 ✅
-- Integration 测试：核心场景覆盖 ✅
-
-文档：
-- 新增 sparql-mode-design.md（80KB 完整设计）
-- 新增 xpod-features.md（18KB 功能说明）
-- 更新 README 和 docs/README 文档索引
-
-Breaking Changes: 无
-Backwards Compatibility: ✅ 完全兼容
-
-Refs: #mode-matrix #sparql-graph #css-interop
-```