Stabilize build cache locks and filtered collection data

Author: tangly1024

.vitepress/config.mts

@@ -327,6 +327,7 @@ export default defineConfig({
           items: [
             { text: '开发文档首页', link: '/developer/' },
             { text: '快速上手', link: '/developer/GETTING_STARTED' },
+            { text: '愿景与路线图', link: '/developer/VISION_ROADMAP' },
             { text: '架构总览', link: '/developer/ARCHITECTURE' },
             { text: '目录与模块', link: '/developer/PROJECT_STRUCTURE' },
             { text: '配置体系', link: '/developer/CONFIGURATION' },
@@ -341,6 +342,7 @@ export default defineConfig({
             { text: '维护者手册', link: '/developer/MAINTAINER_RUNBOOK.zh-CN' },
             { text: '版本更新说明', link: '/developer/UPDATE' },
             { text: '社区路线图', link: '/developer/COMMUNITY_SITE_ROADMAP' },
+            { text: '5.0 愿景与参与方向', link: '/developer/VISION_ROADMAP' },
             { text: 'RFC', link: '/developer/rfc/' }
           ]
         },

README.md

@@ -140,6 +140,7 @@ NotionNext 主仓库由 GitHub 组织 [notionnext-org](https://github.com/notion
 | 内容 | 链接 |
 | --- | --- |
 | 参与社区 | [community-participate.md](./docs/user-guide/community-participate.md) |
+| 5.0 愿景与路线图 | [VISION_ROADMAP.md](./docs/developer/VISION_ROADMAP.md) |
 | 贡献指南 | [CONTRIBUTING.zh-CN.md](./CONTRIBUTING.zh-CN.md) |
 | 项目治理 | [GOVERNANCE.zh-CN.md](./GOVERNANCE.zh-CN.md) |
 | 维护者 | [MAINTAINERS.md](./MAINTAINERS.md) |

__tests__/lib/cache/file_lock.test.js

@@ -0,0 +1,120 @@
+/**
+ * @jest-environment node
+ */
+
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function loadFileLockWithTempCache() {
+  const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'notionnext-lock-'))
+  process.env.NOTION_NEXT_NOTION_CACHE_DIR = cacheDir
+  jest.resetModules()
+
+  const mod = await import('@/lib/cache/file_lock')
+
+  return {
+    cacheDir,
+    withFileLock: mod.withFileLock
+  }
+}
+
+describe('withFileLock', () => {
+  afterEach(() => {
+    delete process.env.NOTION_NEXT_NOTION_CACHE_DIR
+  })
+
+  it('waits for the lock holder cache result instead of bypassing in wait mode', async () => {
+    const { cacheDir, withFileLock } = await loadFileLockWithTempCache()
+    let cachedValue = null
+    let calls = 0
+
+    try {
+      const holder = withFileLock(
+        'shared-build-key',
+        async () => {
+          calls++
+          await sleep(50)
+          cachedValue = 'from-holder'
+          return cachedValue
+        },
+        () => cachedValue,
+        {
+          timeout: 1000,
+          staleLockMs: 5000,
+          timeoutStrategy: 'wait',
+          maxWaitMs: 1000
+        }
+      )
+
+      await sleep(5)
+
+      const waiter = withFileLock(
+        'shared-build-key',
+        () => {
+          calls++
+          return 'from-waiter'
+        },
+        () => cachedValue,
+        {
+          timeout: 10,
+          staleLockMs: 5000,
+          timeoutStrategy: 'wait',
+          maxWaitMs: 1000
+        }
+      )
+
+      await expect(Promise.all([holder, waiter])).resolves.toEqual([
+        'from-holder',
+        'from-holder'
+      ])
+      expect(calls).toBe(1)
+    } finally {
+      fs.rmSync(cacheDir, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps the default timeout bypass behavior for existing callers', async () => {
+    const { cacheDir, withFileLock } = await loadFileLockWithTempCache()
+    let cachedValue = null
+    let calls = 0
+
+    try {
+      const holder = withFileLock(
+        'compat-key',
+        async () => {
+          calls++
+          await sleep(500)
+          cachedValue = 'from-holder'
+          return cachedValue
+        },
+        () => cachedValue,
+        1000
+      )
+
+      await sleep(5)
+
+      const waiter = withFileLock(
+        'compat-key',
+        () => {
+          calls++
+          return 'from-bypass'
+        },
+        () => cachedValue,
+        10
+      )
+
+      await expect(Promise.all([holder, waiter])).resolves.toEqual([
+        'from-holder',
+        'from-bypass'
+      ])
+      expect(calls).toBe(2)
+    } finally {
+      fs.rmSync(cacheDir, { recursive: true, force: true })
+    }
+  })
+})

__tests__/lib/db/notion/convertInnerUrl.test.js

@@ -1,3 +1,11 @@
+jest.mock('notion-utils', () => ({
+  idToUuid: id =>
+    `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(
+      16,
+      20
+    )}-${id.slice(20)}`
+}))
+
 import { convertInnerUrl } from '@/lib/db/notion/convertInnerUrl'
 
 describe('convertInnerUrl', () => {

__tests__/lib/notion-data-format.test.js

@@ -1,4 +1,5 @@
 import getAllPageIds from '@/lib/db/notion/getAllPageIds'
+import { filterCollectionViewData } from '@/lib/db/notion/filterCollectionViewData'
 import {
   adapterNotionBlockMap,
   normalizeNotionBlockType
@@ -170,6 +171,95 @@ describe('Notion data format compatibility', () => {
     expect(pageIds).toEqual(['page_1', 'page_2'])
   })
 
+  it('filters embedded collection query results by selected view filters', () => {
+    const blockMap = {
+      block: {
+        published_page: {
+          value: {
+            id: 'published_page',
+            type: 'page',
+            properties: {
+              type: [['Post']],
+              status: [['Published']]
+            }
+          }
+        },
+        draft_page: {
+          value: {
+            id: 'draft_page',
+            type: 'page',
+            properties: {
+              type: [['Post']],
+              status: [['Draft']]
+            }
+          }
+        },
+        invisible_page: {
+          value: {
+            id: 'invisible_page',
+            type: 'page',
+            properties: {
+              type: [['Post']],
+              status: [['Invisible']]
+            }
+          }
+        }
+      },
+      collection_view: {
+        view_1: {
+          value: {
+            value: {
+              id: 'view_1',
+              page_sort: ['published_page', 'draft_page', 'invisible_page'],
+              format: {
+                collection_pointer: { id: 'collection_1' },
+                property_filters: [
+                  {
+                    filter: {
+                      property: 'type',
+                      filter: {
+                        operator: 'enum_is',
+                        value: { type: 'exact', value: 'Post' }
+                      }
+                    }
+                  },
+                  {
+                    filter: {
+                      property: 'status',
+                      filter: {
+                        operator: 'enum_is',
+                        value: { type: 'exact', value: 'Published' }
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        }
+      },
+      collection_query: {
+        collection_1: {
+          view_1: {
+            collection_group_results: {
+              blockIds: ['published_page', 'draft_page', 'invisible_page']
+            }
+          }
+        }
+      }
+    }
+
+    filterCollectionViewData(blockMap)
+
+    expect(
+      blockMap.collection_query.collection_1.view_1.collection_group_results
+        .blockIds
+    ).toEqual(['published_page'])
+    expect(blockMap.collection_view.view_1.value.value.page_sort).toEqual([
+      'published_page'
+    ])
+  })
+
   it('normalizes nested blocks and strips crdt fields before rendering', () => {
     const formatted = formatNotionBlock({
       page_1: {

docs/developer/README.md

@@ -10,6 +10,7 @@
 | 主题 | 中文 | English |
 | --- | --- | --- |
 | 快速上手 | [GETTING_STARTED.md](./GETTING_STARTED.md) | [GETTING_STARTED.en.md](./GETTING_STARTED.en.md) |
+| 愿景与路线图 | [VISION_ROADMAP.md](./VISION_ROADMAP.md) | — |
 | 架构总览 | [ARCHITECTURE.md](./ARCHITECTURE.md) | [ARCHITECTURE.en.md](./ARCHITECTURE.en.md) |
 | 目录与模块 | [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) | [PROJECT_STRUCTURE.en.md](./PROJECT_STRUCTURE.en.md) |
 | 配置体系 | [CONFIGURATION.md](./CONFIGURATION.md) | [CONFIGURATION.en.md](./CONFIGURATION.en.md) |
@@ -21,6 +22,7 @@
 | 主题迁移 | [THEME_MIGRATION_GUIDE.zh-CN.md](./THEME_MIGRATION_GUIDE.zh-CN.md) | [THEME_MIGRATION_GUIDE.md](./THEME_MIGRATION_GUIDE.md) |
 | 版本更新说明 | [UPDATE.md](./UPDATE.md) | — |
 | 社区路线图 | [COMMUNITY_SITE_ROADMAP.md](./COMMUNITY_SITE_ROADMAP.md) | — |
+| 5.0 愿景与参与方向 | [VISION_ROADMAP.md](./VISION_ROADMAP.md) | — |
 
 仓库贡献总则：[CONTRIBUTING.zh-CN.md](../../CONTRIBUTING.zh-CN.md) · 用户向 [参与社区](../user-guide/community-participate.md) · [MAINTAINERS.md](../../MAINTAINERS.md)
 

docs/developer/VISION_ROADMAP.md

@@ -0,0 +1,99 @@
+# NotionNext 愿景与路线图
+
+NotionNext 的长期目标，不是把 Notion 简单包装成另一个博客模板，而是让它成为一个稳定、可演进、可由社区共同维护的内容发布系统。
+
+Notion 负责内容生产、资料整理和团队协作；NotionNext 负责公开访问、主题展示、SEO、部署、性能和长期运营。两者连接得越自然，站长需要手工维护的地方就越少，内容也越容易持续沉淀。
+
+## 5.0 方向
+
+5.0 不应只是“多几个功能”的版本。它更应该回答一个问题：一个普通站长如何在不被 Git、部署平台和 Notion 数据结构反复打断的情况下，长期维护自己的站点？
+
+围绕这个目标，后续路线会优先关注这些方向。
+
+### 1. 降低使用门槛
+
+NotionNext 仍然是开源项目，但部署、升级、排错不能只服务熟悉工程流程的人。未来需要继续减少这些摩擦：
+
+- 更清楚的升级路径，降低分支、Fork、Pull Request 带来的理解成本。
+- 更稳定的构建和缓存策略，减少“代码已经更新但网站仍是旧状态”的困惑。
+- 更友好的错误提示和自检工具，让站长能先判断是配置问题、缓存问题还是代码问题。
+- 更完整的文档，把常见真实场景沉淀成可复用的排查步骤。
+
+### 2. 更完整地承接 Notion 数据库能力
+
+Notion 的数据库、视图、筛选和排序是许多站长真正依赖的能力。NotionNext 应尽量理解这些结构，而不是要求用户额外维护大量重复标签。
+
+近期已经开始补齐嵌入数据库视图筛选等兼容问题。长期可以继续推进：
+
+- 更稳定地读取 Notion 数据库视图筛选、排序和分组结果。
+- 支持更多 Notion 属性类型和多条件组合。
+- 降低“为了网站展示而重复造标签”的人工维护成本。
+- 明确哪些 Notion 行为可以可靠支持，哪些需要降级或文档说明。
+
+### 3. 主题、版型和内容模块化
+
+NotionNext 已经有多套主题，但长期维护的关键不是主题数量，而是主题之间能否共享稳定的基础能力。
+
+后续可以逐步沉淀：
+
+- 更清晰的主题接口和配置边界。
+- 可复用的文章卡片、列表、图库、导航、筛选页面等内容模块。
+- 面向不同场景的版型能力，例如案例库、作品集、知识库、产品页和导航站。
+- 更容易迁移和维护的主题文档、预览图与测试方式。
+
+### 4. 更安全的升级体验
+
+很多站长会在 Fork 后修改配置、样式或主题。项目需要承认这种现实，而不是假设所有人都只使用原始代码。
+
+未来需要继续优化：
+
+- 把站长自定义配置和核心代码改动尽量分离。
+- 让版本升级更容易判断哪些冲突必须人工处理。
+- 对常见下游分支维护方式提供更明确的建议。
+- 在 CI、测试和发布流程中尽早发现破坏性变更。
+
+### 5. 让更多角色能参与
+
+开源项目不只需要核心代码贡献者。NotionNext 的真实使用场景很多，站长、设计师、文档维护者、测试者都能帮助项目变好。
+
+我们希望把任务拆得更小、更清楚，让不同经验的人都能找到入口。
+
+## 可以如何参与
+
+如果你还不熟悉代码，可以从这些事情开始：
+
+- 复现问题：提供网站链接、Notion 页面、分支名、部署平台和截图。
+- 测试修复：在自己的站点或测试分支验证 PR 是否解决真实问题。
+- 补充文档：把踩过的坑整理成教程、FAQ 或排查步骤。
+- 改进体验：指出哪些概念、配置或升级流程对非开发者不友好。
+- 贡献主题素材：补主题截图、使用说明、适用场景和配置示例。
+
+如果你已经能改代码，可以优先关注：
+
+- Notion 数据结构兼容性和测试用例。
+- 主题公共组件和版型模块。
+- 构建、缓存、部署和升级稳定性。
+- 文档站、CI、发布流程和维护工具。
+- 带有 `good first issue` 或 `help wanted` 标签的问题。
+
+## 近期适合拆分的任务
+
+这些方向适合逐步拆成 Issue、Discussion 或 RFC：
+
+| 方向 | 可拆任务 |
+| --- | --- |
+| Notion 数据库能力 | 补齐视图筛选、排序、状态分组、多选、日期、关系属性等兼容测试 |
+| 图文卡片版型 | 为标签页、分类页或指定数据库视图提供稳定的卡片展示方案 |
+| 升级体验 | 梳理 Fork 用户如何同步上游、如何处理分支和部署缓存 |
+| 主题模块化 | 抽象文章卡片、列表、图库、筛选页等跨主题可复用组件 |
+| 文档维护 | 把真实用户反馈整理成 FAQ、排查手册和升级指南 |
+| 测试与 CI | 为关键数据格式、构建缓存、主题渲染补充小范围自动化验证 |
+
+## 协作原则
+
+- 先讨论真实场景，再设计功能。
+- 大改动先写 RFC，小修复保持 PR 小而清楚。
+- 优先补测试和文档，减少后续维护成本。
+- 允许非代码贡献存在价值，真实反馈本身就是项目路线的一部分。
+
+NotionNext 的 5.0 不是某个人一次性完成的大版本，而是社区持续把复杂度收拢、把门槛降下来的过程。每一次可复现的问题、一次文档修正、一个小范围 PR，都会让后来的站长少踩一个坑。

docs/developer/index.md

@@ -9,6 +9,7 @@ NotionNext 文档不再把“站长教程”和“开发者文档”做成两个
 | 主题 | 中文 | English |
 | --- | --- | --- |
 | 快速上手 | [GETTING_STARTED.md](./GETTING_STARTED.md) | [GETTING_STARTED.en.md](./GETTING_STARTED.en.md) |
+| 愿景与路线图 | [VISION_ROADMAP.md](./VISION_ROADMAP.md) | — |
 | 架构总览 | [ARCHITECTURE.md](./ARCHITECTURE.md) | [ARCHITECTURE.en.md](./ARCHITECTURE.en.md) |
 | 目录与模块 | [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) | [PROJECT_STRUCTURE.en.md](./PROJECT_STRUCTURE.en.md) |
 | 配置体系 | [CONFIGURATION.md](./CONFIGURATION.md) | [CONFIGURATION.en.md](./CONFIGURATION.en.md) |
@@ -30,5 +31,6 @@ NotionNext 文档不再把“站长教程”和“开发者文档”做成两个
 | --- | --- |
 | 版本更新说明 | [UPDATE.md](./UPDATE.md) |
 | 社区路线图 | [COMMUNITY_SITE_ROADMAP.md](./COMMUNITY_SITE_ROADMAP.md) |
+| 5.0 愿景与参与方向 | [VISION_ROADMAP.md](./VISION_ROADMAP.md) |
 | 项目治理 | [GOVERNANCE.zh-CN.md](https://github.com/notionnext-org/NotionNext/blob/main/GOVERNANCE.zh-CN.md) · [GOVERNANCE.md](https://github.com/notionnext-org/NotionNext/blob/main/GOVERNANCE.md) |
 | 仓库贡献总则 | [CONTRIBUTING.zh-CN.md](https://github.com/notionnext-org/NotionNext/blob/main/CONTRIBUTING.zh-CN.md) |