From 2010751684659b7ef3b9dfc3a4c06fb8b356f284 Mon Sep 17 00:00:00 2001
From: wangziqi <wangziqi@gongxue100.com>
Date: Thu, 2 Jul 2026 17:34:36 +0800
Subject: [PATCH] tweak: add *.tsbuildinfo to .gitignore to prevent stale
 incremental cache

---
 .gitignore                                    |  3 +++
 .../.openspec.yaml                            |  2 ++
 .../add-tsbuildinfo-to-gitignore/design.md    | 21 ++++++++++++++++++
 .../add-tsbuildinfo-to-gitignore/proposal.md  | 22 +++++++++++++++++++
 .../add-tsbuildinfo-to-gitignore/tasks.md     |  8 +++++++
 5 files changed, 56 insertions(+)
 create mode 100644 openspec/changes/add-tsbuildinfo-to-gitignore/.openspec.yaml
 create mode 100644 openspec/changes/add-tsbuildinfo-to-gitignore/design.md
 create mode 100644 openspec/changes/add-tsbuildinfo-to-gitignore/proposal.md
 create mode 100644 openspec/changes/add-tsbuildinfo-to-gitignore/tasks.md

diff --git a/.gitignore b/.gitignore
index c6353e2..7980f69 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,9 @@ node_modules/
 dist/
 build/
 
+# TypeScript 增量编译缓存
+*.tsbuildinfo
+
 # 环境变量（包含密码等敏感信息）
 .env
 .env.local
diff --git a/openspec/changes/add-tsbuildinfo-to-gitignore/.openspec.yaml b/openspec/changes/add-tsbuildinfo-to-gitignore/.openspec.yaml
new file mode 100644
index 0000000..8e26fbe
--- /dev/null
+++ b/openspec/changes/add-tsbuildinfo-to-gitignore/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-02
diff --git a/openspec/changes/add-tsbuildinfo-to-gitignore/design.md b/openspec/changes/add-tsbuildinfo-to-gitignore/design.md
new file mode 100644
index 0000000..40284f6
--- /dev/null
+++ b/openspec/changes/add-tsbuildinfo-to-gitignore/design.md
@@ -0,0 +1,21 @@
+## Context
+
+TypeScript 的 `incremental: true` 选项会在编译时生成 `.tsbuildinfo` 文件用于增量编译加速。当 `dist/` 目录被清理（如 `nest build` 的 `deleteOutDir: true` 行为）但 `.tsbuildinfo` 缓存未被同步清理时，TypeScript 会基于缓存判定所有文件已是最新、跳过编译，导致运行时找不到输出文件。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 将 `*.tsbuildinfo` 加入 `.gitignore`，防止缓存文件被版本控制追踪
+
+**Non-Goals:**
+- 不改变 TypeScript 编译配置
+- 不添加自动清理缓存的构建脚本
+
+## Decisions
+
+- **方案**：在 `.gitignore` 中新增一行 `*.tsbuildinfo` 规则，置于「构建产物」区域下方
+- **理由**：这是最小改动方案。`.tsbuildinfo` 属于构建产物类文件，应与 `dist/`、`build/` 等同对待；加入 `.gitignore` 后既不会被提交，也提示开发者此为自动生成文件
+
+## Risks / Trade-offs
+
+- 无风险。该改动仅影响 git 追踪行为，不改变编译或运行逻辑
diff --git a/openspec/changes/add-tsbuildinfo-to-gitignore/proposal.md b/openspec/changes/add-tsbuildinfo-to-gitignore/proposal.md
new file mode 100644
index 0000000..f91b2d9
--- /dev/null
+++ b/openspec/changes/add-tsbuildinfo-to-gitignore/proposal.md
@@ -0,0 +1,22 @@
+## Why
+
+`npm run dev` 启动失败，原因是 `apps/server/tsconfig.build.tsbuildinfo`（TypeScript 增量编译缓存）残留但 `dist/` 目录已被清理。TypeScript 看到增量缓存认为无需重新编译，导致 `nest start --watch` 找不到 `dist/main.js` 而崩溃。`.gitignore` 中缺少对 `*.tsbuildinfo` 的忽略规则，使该缓存文件可能被提交或在清理构建产物后残留。
+
+## What Changes
+
+- 在 `.gitignore` 中新增 `*.tsbuildinfo` 规则，确保 TypeScript 增量编译缓存文件不被版本控制追踪
+
+## Capabilities
+
+### New Capabilities
+
+无（纯配置优化，不涉及新能力）
+
+### Modified Capabilities
+
+无
+
+## Impact
+
+- 影响的文件：`.gitignore`（根目录）
+- 无 API、依赖或系统层面的影响
diff --git a/openspec/changes/add-tsbuildinfo-to-gitignore/tasks.md b/openspec/changes/add-tsbuildinfo-to-gitignore/tasks.md
new file mode 100644
index 0000000..29471b9
--- /dev/null
+++ b/openspec/changes/add-tsbuildinfo-to-gitignore/tasks.md
@@ -0,0 +1,8 @@
+## 1. 核心修改
+
+- [x] 1.1 在 `.gitignore` 中新增 `*.tsbuildinfo` 规则
+- [x] 1.2 删除残留的 `apps/server/tsconfig.build.tsbuildinfo` 文件
+
+## 2. 验证
+
+- [x] 2.1 运行 `npm run dev` 确认 server 和 admin 正常启动