v0.1.8 - 백엔드 초안 추가

.gitignore

@@ -1,5 +1,7 @@
 node_modules/
+backend/node_modules/
 dist/
 .DS_Store
 *.log
-
+backend/.env
+backend/data/

HANDOFF.md

@@ -4,7 +4,7 @@
 
 - 프로젝트명: 10 Minute Planner 웹 UI
 - 기술 스택: Vue 3 + Vite + TailwindCSS + JavaScript
-- 현재 기준 버전: `v0.1.7`
+- 현재 기준 버전: `v0.1.8`
 - Git 원격 저장소: `https://git.sori.studio/zenn/planner.sori.studio.git`
 
 ## 기준 디자인
@@ -19,12 +19,15 @@
 - 화면 인상은 종이 다이어리 같아야 하지만, 상호작용은 웹앱처럼 빠르고 자연스러워야 한다.
 - 현재는 개인용 단일 브라우저 흐름으로 개발 중이지만, 이후 회원 기반 개인 문서 관리 서비스로 확장해야 한다.
 - 최종적으로는 프론트엔드와 백엔드를 Docker로 묶어서 UGREEN NAS에서 구동할 예정이다.
+- `backend/` 폴더에 백엔드 초안이 추가되었고, 현재는 프론트와 분리된 구조로 관리한다.
 
 ## 현재 구현 상태
 
 - 메인 화면 셸: `src/App.vue`
 - 플래너 종이 레이아웃: `src/components/PlannerPage.vue`
 - 우측 달력 컴포넌트: `src/components/MiniCalendar.vue`
+- 백엔드 엔트리 포인트: `backend/src/server.js`
+- 백엔드 DB 스키마: `backend/src/db/schema.js`
 - Tailwind 설정은 완료되어 있으며, 이 프로젝트의 스타일링 기준으로 유지한다.
 - 현재 선택 날짜는 시스템 날짜 기준으로 시작한다.
 - `COMMENT`, `TASKS`, `MEMO`는 화면에서 바로 편집할 수 있다.
@@ -42,6 +45,7 @@
 - 상단 날짜 표시에서는 토요일의 `(토)`만 파란색, 일요일의 `(일)`만 빨간색으로 표시한다.
 - 플래너 상태는 `localStorage`에 저장되며, 날짜별 기록과 선택 날짜, 달력 보고 있던 월까지 복원된다.
 - `localStorage` 접근 로직은 `src/lib/plannerStorage.js`로 분리하기 시작했고, 이후 API/DB adapter로 교체하기 쉬운 구조로 정리 중이다.
+- 루트에서 `npm run dev:backend`, `npm run db:generate`, `npm run db:migrate`로 백엔드 명령을 호출할 수 있다.
 - 상단 전환 버튼으로 `PLANNER / STATS` 화면을 오갈 수 있다.
 - 통계 화면에서는 전체 집중 시간, 평균 완료율, 기록 일수, 최근 7일 흐름, 최근 기록, 베스트 데이를 보여준다.
 - 통계 화면은 시작일/종료일을 직접 선택해 그 기간 기준으로 지표를 다시 계산할 수 있다.
@@ -58,6 +62,8 @@
 - `1-UP`은 여백이 과하지 않도록 다시 확대했고, `2-UP`은 한 페이지 고정 안정성을 위해 가로 폭과 세로 높이를 조금 더 보수적으로 조정했다.
 - `1-UP`은 세로 가운데 정렬을 없애고 상단 기준으로 붙여야 여백이 덜 커 보인다.
 - 현재 `1-UP`은 프레임 자체를 A4 세로에 가깝게 키우고 배율을 크게 올려 빈 여백을 줄이는 방향으로 맞추고 있다.
+- 백엔드 초안은 `Fastify + Drizzle + SQLite` 조합이며, 현재는 `/health`, `/api/meta` 정도의 기본 라우트만 있다.
+- 현재 샌드박스에서는 포트 바인딩 제한 때문에 백엔드 실제 리슨 확인이 막힐 수 있다. `listen EPERM 0.0.0.0:3001`은 코드 자체보다 실행 환경 제약에 가깝다.
 
 ## 확정된 결정사항
 
@@ -86,6 +92,7 @@
 - 원격 저장소 `origin`은 `https://git.sori.studio/zenn/planner.sori.studio.git`로 연결되어 있다.
 - 앞으로 버전 체크포인트 커밋은 `v0.1.7 - 작업 요약`처럼 버전 뒤에 짧은 작업 설명을 함께 남기는 형식으로 통일한다.
 - 이후 배포 단계에서는 `docker-compose.yml`도 함께 작성해야 하며, 포트 번호와 서비스 구성은 추후 사용자와 확정한다.
+- `backend/.env.example`에는 기본 `PORT`, `DB_FILE`, `CORS_ORIGIN` 예시가 들어 있다.
 
 ## 다음 권장 작업
 
@@ -94,6 +101,7 @@
 - 통계 화면 구현은 현재 `localStorage` 기반으로 먼저 진행해도 된다.
 - DB는 기능 탐색 속도를 해치지 않는 선에서, 저장 레이어를 분리할 수 있는 적절한 시점에 붙이는 것이 좋다.
 - 현재 기준 추천 백엔드 방향은 `Vue 프론트엔드 + Node.js API + SQLite 또는 PostgreSQL`이다.
+- 현재는 SQLite로 시작하되, 확장 시 PostgreSQL로 옮길 수 있게 Drizzle 기반 스키마를 유지한다.
 - 이미지 저장 기능은 추후 `print-only` 또는 별도 export 전용 레이아웃을 기준으로 구현하면 화면/인쇄/공유 결과를 맞추기 쉽다.
 - Docker Compose는 프론트엔드와 백엔드를 함께 올리는 기준으로 설계하되, NAS 환경에 맞는 볼륨과 재시작 정책도 함께 고려한다.
 

TODO.md

@@ -47,7 +47,7 @@
 - [x] 입력 데이터의 저장 위치를 결정한다.
 - [x] 로컬 저장 또는 외부 저장 방식 중 우선 구현 방식을 정한다.
 - [x] 입력 상태가 새로고침 후에도 유지되도록 만든다.
-- [ ] DB 전환 시점을 잡을 수 있도록 저장 레이어를 분리한다.
+- [x] DB 전환 시점을 잡을 수 있도록 저장 레이어를 분리한다.
 - [ ] 회원 가입 및 로그인 구조를 고려한 사용자별 데이터 모델을 설계한다.
 - [ ] 사용자별 문서 저장/조회 흐름을 정리한다.
 - [ ] 출력용 문서 포맷과 프린트 흐름을 고려한 데이터 구조를 정리한다.
@@ -76,6 +76,7 @@
 - [ ] 공유를 위한 이미지 저장 기능을 추가한다.
 - [ ] Docker 배포 구조를 정리한다.
 - [ ] UGREEN NAS 기준 `docker-compose.yml` 초안을 작성한다.
+- [x] 백엔드 기본 스캐폴딩을 추가한다.
 
 ## 메모
 
@@ -87,4 +88,5 @@
 - 실제 인쇄는 HTML/CSS 기반 프린트 레이아웃으로 유지하고, 공유용으로는 별도의 이미지 저장 기능을 추가하는 방향이 적합하다.
 - 최종 배포는 UGREEN NAS에서 Docker 기반으로 동작할 예정이며, 포트와 실제 서비스 구성은 추후 확정한다.
 - 백엔드는 빠른 목업이면 PocketBase도 가능하지만, 현재 방향상 커스텀 로직과 확장성을 생각하면 전용 Node.js API + DB 조합을 우선 검토한다.
+- 현재 백엔드는 `backend/` 폴더에 `Fastify + Drizzle + SQLite` 기준 초안이 추가되었다.
 - 구현할 때마다 완료된 항목은 체크하고, 큰 결정사항은 `HANDOFF.md`에도 함께 반영한다.

backend/.env.example

@@ -0,0 +1,3 @@
+PORT=3001
+DB_FILE=./data/planner.sqlite
+CORS_ORIGIN=http://localhost:5173

backend/drizzle.config.js

@@ -0,0 +1,17 @@
+import { config } from 'dotenv'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+config({ path: path.join(__dirname, '.env') })
+
+export default {
+  schema: './src/db/schema.js',
+  out: './drizzle',
+  dialect: 'sqlite',
+  dbCredentials: {
+    url: process.env.DB_FILE ?? './data/planner.sqlite',
+  },
+}

backend/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "ten-minute-planner-backend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch src/server.js",
+    "start": "node src/server.js",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate"
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.1",
+    "better-sqlite3": "^11.8.1",
+    "dotenv": "^16.4.7",
+    "drizzle-orm": "^0.39.1",
+    "fastify": "^5.2.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.30.4"
+  }
+}

backend/src/config.js

@@ -0,0 +1,17 @@
+import { config } from 'dotenv'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { z } from 'zod'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+config({ path: path.join(__dirname, '..', '.env') })
+
+const envSchema = z.object({
+  PORT: z.coerce.number().default(3001),
+  DB_FILE: z.string().default('./data/planner.sqlite'),
+  CORS_ORIGIN: z.string().default('http://localhost:5173'),
+})
+
+export const env = envSchema.parse(process.env)

backend/src/db/client.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { env } from '../config.js'
+import * as schema from './schema.js'
+
+function ensureDatabaseDirectory(dbFile) {
+  const absoluteDbPath = path.resolve(dbFile)
+  fs.mkdirSync(path.dirname(absoluteDbPath), { recursive: true })
+  return absoluteDbPath
+}
+
+const sqlite = new Database(ensureDatabaseDirectory(env.DB_FILE))
+
+export const db = drizzle(sqlite, { schema })
+export { sqlite }

backend/src/db/schema.js

@@ -0,0 +1,19 @@
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  email: text('email').notNull().unique(),
+  passwordHash: text('password_hash').notNull(),
+  nickname: text('nickname').notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+export const plannerEntries = sqliteTable('planner_entries', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  userId: integer('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  entryDate: text('entry_date').notNull(),
+  payload: text('payload').notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})

backend/src/server.js

@@ -0,0 +1,46 @@
+import Fastify from 'fastify'
+import cors from '@fastify/cors'
+import { env } from './config.js'
+import { sqlite } from './db/client.js'
+
+const app = Fastify({
+  logger: true,
+})
+
+await app.register(cors, {
+  origin: env.CORS_ORIGIN,
+  credentials: true,
+})
+
+app.get('/health', async () => {
+  const version = sqlite.prepare('select sqlite_version() as version').get()
+
+  return {
+    status: 'ok',
+    service: 'ten-minute-planner-backend',
+    database: {
+      client: 'sqlite',
+      version: version?.version ?? 'unknown',
+    },
+  }
+})
+
+app.get('/api/meta', async () => ({
+  auth: 'planned',
+  storage: 'sqlite',
+  orm: 'drizzle',
+  notes: [
+    '회원가입 및 로그인 API는 다음 단계에서 추가 예정',
+    '플래너 저장 API는 로컬 저장 레이어 분리 이후 연결 예정',
+  ],
+}))
+
+try {
+  await app.listen({
+    port: env.PORT,
+    host: '0.0.0.0',
+  })
+} catch (error) {
+  app.log.error(error)
+  process.exit(1)
+}

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "ten-minute-planner",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ten-minute-planner",
-      "version": "0.1.7",
+      "version": "0.1.8",
       "dependencies": {
         "vue": "^3.5.13"
       },

package.json

@@ -1,12 +1,15 @@
 {
   "name": "ten-minute-planner",
   "private": true,
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "scripts": {
     "dev": "vite",
+    "dev:backend": "npm --prefix backend run dev",
     "build": "vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "db:generate": "npm --prefix backend run db:generate",
+    "db:migrate": "npm --prefix backend run db:migrate"
   },
   "dependencies": {
     "vue": "^3.5.13"