chore: 收尾清账——type:module/gitattributes/engines/lint/CI/根typecheck覆盖

Co-Authored-By: Claude Code <noreply@anthropic.com>

.env.example

@@ -1,2 +1,3 @@
 # 复制为 .env 使用；.env 已被 gitignore
 DATABASE_URL=postgres://siteforge:siteforge_dev@localhost:5434/siteforge
+# DATABASE_URL_TEST（集成测试库）由 vitest globalSetup 自动创建临时库并注入——勿手动设置

.gitattributes

@@ -0,0 +1,3 @@
+# 统一行尾为 LF（治 Windows core.autocrlf=true 带来的 CRLF 警告）；
+# text=auto 由 git 自动检测二进制文件（如 fixtures/*.png）并保持原样。
+* text=auto eol=lf

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+# CI（备用）：自建 git 服务可能不跑 GitHub Actions——本文件保留备用，
+# 本地质量门以 pnpm 脚本为准：pnpm lint && pnpm typecheck && pnpm db:test。
+# 与本地等价性：PG 由 services 容器提供（同 infra/docker-compose.yml 凭据/端口），
+# vitest globalSetup 自建临时库 sf_test_<ts>，无需预迁移开发库。
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: siteforge
+          POSTGRES_PASSWORD: siteforge_dev
+          POSTGRES_DB: siteforge
+        ports:
+          - 5434:5432
+        options: >-
+          --health-cmd "pg_isready -U siteforge"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+    env:
+      DATABASE_URL: postgres://siteforge:siteforge_dev@localhost:5434/siteforge
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.7.1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm test

eslint.config.js

@@ -0,0 +1,29 @@
+// eslint 9 flat config（Task 14）：最小保守集——JS/TS recommended + 少量明显增益规则。
+// 原则：不做风格警察；现有代码若对某规则大面积误报则降级该规则，而非批量改代码。
+import eslint from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  // 依赖与构建产物不参与 lint
+  { ignores: ['**/node_modules/**', '**/dist/**', 'coverage/**', '.artifacts/**'] },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      // 未用变量报错，但允许下划线前缀显式豁免（测试/签名对齐常见）
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' },
+      ],
+    },
+  },
+  {
+    // 测试代码放宽 no-explicit-any：夹具行插入用 `as any` 表达"部分列 + 任意宽松形状"、
+    // catch (e: any) 取 postgres.js 错误细节，均为有意为之（50 处违例集中于此）。
+    // 生产代码（src/）保持该规则严格。
+    files: ['tests/**/*.ts', '**/test/**/*.ts'],
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+)

package.json

@@ -1,14 +1,24 @@
 {
   "name": "siteforge",
   "private": true,
+  "type": "module",
   "packageManager": "pnpm@10.7.1",
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint ."
+    "typecheck": "tsc -p tsconfig.json --noEmit && pnpm --filter @sf/api typecheck && pnpm --filter @sf/contracts typecheck",
+    "lint": "eslint .",
+    "db:up": "docker compose -f infra/docker-compose.yml up -d --wait",
+    "db:migrate": "pnpm --filter @sf/api db:migrate",
+    "db:test": "bash scripts/migrate-test.sh"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.0",
+    "eslint": "^9.39.0",
     "typescript": "^5.6.0",
+    "typescript-eslint": "^8.46.4",
     "vitest": "^2.1.0"
   }
 }

packages/contracts/package.json

@@ -12,6 +12,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

packages/contracts/src/universal-row.ts

@@ -20,6 +20,7 @@ export interface UniversalRow {
   rawLocation: string
 }
 
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- {} extends Pick<T,K> 是检测可选键的惯用条件类型比较，非"任意非空值"类型标注
 type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T]
 
 // 契约冻结：REQUIRED = 接口必填字段全集；接口新增必填字段而列表漏改 → 编译报错