@fivepixels-js/lite-api 0.2.1

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,537 @@
+# Fivepixels Lite API
+
+Fastify, TypeScript, SQLite로 만든 경량 독립형 API 플랫폼입니다. 단일 서버·단일 Node.js 프로세스와 1 vCPU / RAM 512MB 수준의 환경을 우선합니다.
+
+현재 `0.2.1`은 실행·설정·SQLite 마이그레이션·백업 기반과 `/api/v1` 아래의 인증, 프로젝트·멤버, 피드백, Report Case, 답글 핵심 API 34개를 제공합니다. 이미지 첨부, selfdev 런타임 선택, PostgreSQL은 현재 지원 범위가 아닙니다.
+
+## 현재 상태와 관련 저장소
+
+npm 패키지 이름은 `@fivepixels-js/lite-api`이며 기존 실행 명령은 `fivepixels-lite-api`입니다. 일반 사용자는 아래 npm 빠른 시작을, 소스 수정·개발 검증은 소스 실행 절차를 사용하십시오. npm 공개 여부와 설치 가능한 버전은 registry에서 확인하며, GitHub 저장소와 npm 이름 공간은 별개입니다.
+
+- [fivepixels-lite-api](https://github.com/siwan315/fivepixels-lite-api): 이 API의 독립 Git 저장소
+- [fivepixels-cli](https://github.com/siwan315/fivepixels-cli): 사용자용 `fivepixels` 명령의 독립 Git 저장소. Lite `0.2.1`에 의존합니다.
+
+두 GitHub 저장소는 현재 비공개이므로 소스 checkout에는 접근 권한이 필요합니다. 공개 npm 패키지 설치에는 GitHub 접근 권한이 필요하지 않습니다.
+
+npm 패키지에는 `dist/`, 단일 DDL, README, LICENSE와 현재 운영·연동 문서 5개를 함께 포함합니다. 아래의 상대 문서 링크는 소스 checkout과 설치된 패키지 내부에서 사용할 수 있습니다. npm 웹사이트가 링크를 비공개 GitHub로 연결하면 접근이 제한될 수 있으므로, 설치된 패키지의 `docs/` 파일을 직접 확인하십시오. 미래 제품 계획과 폐기된 SQL 초안은 패키지에 포함하지 않습니다.
+
+## 라이선스
+
+Copyright (c) 2026 Fivepixels
+
+이 저장소의 Lite API 서버는 [Elastic License 2.0 (ELv2)](LICENSE), SPDX 식별자 `Elastic-2.0`으로 제공합니다. 소스를 열람·수정할 수 있는 **source-available** 소프트웨어이며 OSI 기준의 오픈소스 라이선스는 아닙니다.
+
+- 라이선스 조건을 지키는 자체 설치·사용·수정·재배포를 허용합니다.
+- 제3자에게 서버의 상당한 기능에 접근할 수 있는 호스팅·관리형 서비스를 제공하는 것은 제한됩니다. 유료 서비스만을 대상으로 하는 제한이 아닙니다.
+- 라이선스 키 기능의 우회·보호 기능 제거와 라이선스·저작권 등 고지의 삭제·은폐를 금지합니다. 배포 시 라이선스를 전달하고 수정본에는 변경 사실을 표시해야 합니다.
+
+위 내용은 이해를 돕는 요약이며 적용 조건은 [라이선스 전문](LICENSE)을 따릅니다. 모든 경쟁 제품의 개발·판매를 일괄 금지하는 라이선스로 해석하지 마십시오. 경계 사례는 [공식 FAQ](https://www.elastic.co/licensing/elastic-license/faq)를 참고하고 별도 법률 검토를 거치십시오.
+
+독립 `@fivepixels-js/cli` 자체 코드는 Apache-2.0이지만, 이 서버와 공개 runtime 및 기존 `fivepixels-lite-api` 명령은 모두 이 패키지의 ELv2를 따릅니다. CLI 설치나 같은 Node 프로세스에서의 호출이 서버 라이선스를 변경하지 않습니다. 제3자 의존성은 각자의 라이선스·고지를 유지합니다.
+
+이번 변경은 이전에 적법하게 배포된 MIT 코드의 권한을 소급해서 회수하지 않습니다. 공개 전에는 외부 기여·제3자 코드의 권리, 과거 배포 이력과 실제 사용 조건을 확인해야 합니다.
+
+## 요구사항
+
+- Node.js 22 또는 24 LTS
+- npm 10 이상 권장
+- SQLite 데이터 파일을 저장할 로컬 디스크
+- Docker 사용 시 Docker Engine과 Compose v2
+
+SQLite DB를 NFS, SMB, NAS 공유 폴더에 저장하지 마십시오. WAL은 동일 호스트의 신뢰할 수 있는 로컬 파일 잠금을 전제로 합니다.
+
+## 빠른 시작: npm 설치
+
+```bash
+npm install -g @fivepixels-js/lite-api
+fivepixels-lite-api --version
+fivepixels-lite-api init
+fivepixels-lite-api start
+```
+
+순서대로 npm의 `latest` 태그 버전을 전역 설치하고 버전을 확인한 뒤, OS별 기본 경로에 DB·JWT 키를 준비하고 포그라운드 서버를 실행합니다. 설치만으로 서버·DB·키가 생성되지는 않습니다. 기존 데이터가 있는지 먼저 확인하고 개발용 별도 DB를 사용하려면 `init`과 `start`에 동일한 `--db-path`를 지정하십시오. 기본 주소는 `http://127.0.0.1:3000`입니다.
+
+패키지 이름에 버전을 붙일 필요는 없습니다. 재현 가능한 운영 설치가 필요할 때만 `@fivepixels-js/lite-api@0.2.1`처럼 버전을 명시하십시오. npm 조회가 404이면 해당 패키지의 공개 여부·registry 설정을 확인하고 소스 개발 절차를 사용하십시오.
+
+## 개발: 소스에서 실행
+
+### 1. 의존성 설치와 빌드
+
+코드가 있는 `fivepixels-lite-api` 디렉터리에서 실행합니다.
+
+```bash
+npm ci
+npm run build
+node dist/cli/index.js --help
+node dist/cli/index.js --version
+```
+
+순서대로 lockfile 기반 의존성을 설치하고 TypeScript를 빌드한 뒤 도움말과 API 버전 `0.2.1`을 확인합니다. 이 단계는 서버·DB·JWT 키를 생성하지 않으며 전역 명령도 설치하지 않습니다.
+
+### 2. 개발용 DB 초기화와 서버 실행
+
+아래 DB는 프로젝트 밖의 `../fivepixels-local-data/lite/data.db`입니다. 기존 운영 데이터가 없는 새 개발 경로인지 먼저 확인하십시오. 다른 배포의 `JWT_SECRET_FILE`, `ADMIN_TOKEN_FILE` 등 환경변수를 가져온 셸은 사용하지 마십시오. `init`은 기존 DB를 지정하면 미적용 마이그레이션을 적용할 수 있습니다.
+
+```bash
+node dist/cli/index.js init --db-path ../fivepixels-local-data/lite/data.db
+node dist/cli/index.js start --host 127.0.0.1 --port 3000 --db-path ../fivepixels-local-data/lite/data.db
+```
+
+`init`은 해당 DB·마이그레이션과 DB 옆 JWT 키를 준비하고, `start`는 같은 DB로 포그라운드 서버를 실행합니다. 뒤의 확인 명령은 별도 터미널에서 실행하십시오. 3000 포트를 이미 사용한다면 시작·상태 확인·HTTP 조회의 포트를 모두 같은 값으로 바꿉니다.
+
+### 3. 상태 확인과 정상 종료
+
+별도 터미널에서도 동일한 `fivepixels-lite-api` 디렉터리를 사용합니다.
+
+```bash
+node dist/cli/index.js status --host 127.0.0.1 --port 3000 --db-path ../fivepixels-local-data/lite/data.db
+node -e "fetch('http://127.0.0.1:3000/health').then(r => { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); }).then(console.log)"
+```
+
+첫 명령은 HTTP·DB·마이그레이션 상태를 확인합니다. 두 번째 명령은 Node로 health API를 조회하며 `status: 'ok'`, `database: 'ok'`인지 확인합니다. 기본 로컬 설정에서는 브라우저의 `http://127.0.0.1:3000/docs`에서 Swagger를 볼 수 있습니다.
+
+서버를 시작한 터미널에서 Ctrl+C로 정상 종료합니다. `start`는 백그라운드 서비스 등록 명령이 아닙니다. 서버 종료 후 `status`가 종료 코드 `1`과 `HTTP: unavailable`을 반환하는 것은 서버가 실행 중이 아니기 때문입니다.
+
+이후 문서의 `fivepixels-lite-api ...` 예제는 설치된 기존 CLI 기준입니다. 소스에서 실행할 때는 `node dist/cli/index.js ...`로 바꾸고, 위 개발 DB를 계속 사용할 경우 모든 데이터 명령에 같은 `--db-path`를 지정하십시오. 생략하면 OS별 기본 DB를 사용합니다.
+
+## 로컬 패키지 검증
+
+위 의존성 설치 후 같은 API 디렉터리에서 실행합니다.
+
+```bash
+npm pack --dry-run
+npm pack
+```
+
+각 명령은 빌드 후 포함 파일을 미리 확인하고, `fivepixels-js-lite-api-0.2.1.tgz`를 생성합니다. npm 공개나 전역 설치는 하지 않습니다. CLI 연동은 [독립 CLI 저장소](https://github.com/siwan315/fivepixels-cli)의 `setup:local` 절차로 진행하십시오.
+
+전역 명령 자체를 검증해야 할 때만 다음 단계를 사용합니다. 기존 전역 설치가 있다면 교체될 수 있으므로 먼저 확인하십시오.
+
+```bash
+npm install -g ./fivepixels-js-lite-api-0.2.1.tgz
+fivepixels-lite-api --version
+```
+
+로컬 tarball을 전역 설치하고 API 버전을 확인합니다. 설치만으로 서버나 사용자 데이터가 생성되지는 않습니다. **README만 바꾸어도 새 tarball의 체크섬이 달라집니다.** CLI의 기존 lockfile과 다르면 변경을 검토한 뒤 CLI의 `setup:local -- --update-lock <tarball>`로 갱신하고 연동을 다시 검증해야 합니다.
+
+## 전역 설치 없이 실행
+
+공개 npm 패키지를 `npx`로 실행할 수도 있습니다.
+
+```bash
+npx @fivepixels-js/lite-api init
+npx @fivepixels-js/lite-api start
+```
+
+`npx`가 패키지를 준비한 뒤 기존 초기화·실행 명령을 호출합니다. 재현 가능한 실행에는 두 명령 모두 같은 명시적 버전을 사용하십시오. 이 방식도 기본 데이터 경로를 사용하므로 테스트용 경로를 원하면 명시해야 합니다.
+
+## CLI
+
+사용자용 `@fivepixels-js/cli` 0.1.0은 별도 [fivepixels-cli 저장소](https://github.com/siwan315/fivepixels-cli)로 분리했습니다. Lite는 공개 `@fivepixels-js/lite-api/runtime` 진입점을 제공하고, 아래의 기존 `fivepixels-lite-api` 명령과 Docker 실행 방식은 그대로 유지합니다. 역할·호환성·패키지 검증은 [독립 CLI와 공개 런타임](docs/guides/independent-cli.md)을 참고하십시오. Docker 실행 관리나 selfdev 선택 기능까지 구현된 것은 아닙니다.
+
+```text
+fivepixels-lite-api init
+fivepixels-lite-api start
+fivepixels-lite-api status
+fivepixels-lite-api backup [--output <경로>]
+fivepixels-lite-api migrate
+fivepixels-lite-api --version
+fivepixels-lite-api --help
+```
+
+- `init`: 데이터 디렉터리와 DB를 생성하고 마이그레이션합니다. 반복 실행해도 안전합니다.
+- `start`: 보안 설정을 검증하고 자동 마이그레이션 후 API를 실행합니다.
+- `status`: HTTP, DB, 스키마 버전을 조회합니다. DB가 없을 때 새로 만들지 않습니다.
+- `backup`: 실행 중인 DB를 SQLite backup API로 백업하고 무결성을 검사합니다.
+- `migrate`: 서버를 시작하지 않고 미적용 마이그레이션을 적용합니다.
+
+종료 코드는 성공 `0`, 실행 실패 `1`, 잘못된 옵션·설정 `2`입니다.
+
+## 환경설정
+
+일반 설정 우선순위는 `CLI 옵션 > 환경변수 > 기본값`입니다.
+
+| 환경변수 | CLI 옵션 | 기본값 | 설명 |
+|---|---|---|---|
+| `HOST` | `--host` | `127.0.0.1` | 수신 주소 |
+| `PORT` | `--port` | `3000` | 1~65535 |
+| `DB_PATH` | `--db-path` | OS별 사용자 데이터 경로 | SQLite 파일 |
+| `LOG_LEVEL` | `--log-level` | `info` | Pino 로그 수준 |
+| `CORS_ORIGIN` | `--cors-origin` | 비활성화 | 쉼표 구분 exact origin |
+| `DOCS_ENABLED` | `--docs-enabled` | localhost만 활성화 | `true` 또는 `false` |
+| `ADMIN_TOKEN_FILE` | `--admin-token-file` | 없음 | 토큰 파일 경로 |
+| `ADMIN_TOKEN` | 없음 | 없음 | 외부 바인딩에 필요한 32자 이상의 운영 토큰 |
+| `JWT_SECRET_FILE` | `--jwt-secret-file` | DB 옆 `jwt-secret` | 사용자 JWT 서명 키 파일 |
+| `JWT_SECRET` | 없음 | 미설정 시 관리 파일 생성 | 32바이트 이상의 JWT 서명 키; 파일 방식 권장 |
+| `REGISTRATION_ENABLED` | `--registration-enabled` | loopback에서만 `true` | 로컬 회원가입 허용 여부 |
+| `TRUST_PROXY` | `--trust-proxy` | 비활성화 | 신뢰할 reverse proxy IP/CIDR 목록 |
+
+관리 토큰은 `--admin-token-file > ADMIN_TOKEN_FILE > ADMIN_TOKEN` 순서로 선택합니다. JWT 키는 `--jwt-secret-file > JWT_SECRET_FILE > JWT_SECRET > DB 옆 자동 관리 파일` 순서입니다. 원문 secret을 명령줄에 노출하는 옵션은 제공하지 않습니다.
+
+`init` 또는 최초 `start`는 기본 JWT 키를 생성하지만 npm 설치와 `status`는 파일을 만들지 않습니다. 외부 주소에 바인딩하더라도 `ADMIN_TOKEN`은 업무 API의 사용자 JWT를 대신하지 않습니다.
+
+기본 데이터 위치:
+
+- Linux: `$XDG_DATA_HOME/fivepixels-api/data.db` 또는 `~/.local/share/fivepixels-api/data.db`
+- macOS: `~/Library/Application Support/fivepixels-api/data.db`
+- Windows: `%LOCALAPPDATA%\fivepixels-api\data.db`
+
+공개 패키지와 실행 명령은 Lite 이름을 사용하지만, 기존 설치의 DB와 JWT 키를 그대로 찾도록 내부 데이터 디렉터리 이름 `fivepixels-api`는 호환 식별자로 유지합니다. Docker volume 이름과 systemd의 사용자·그룹·데이터 경로도 같은 이유로 기존 예시를 유지하며, 새 설치에서는 운영 환경에 맞는 이름을 선택해도 됩니다.
+
+상대 `DB_PATH`는 현재 작업 디렉터리를 기준으로 절대 경로로 변환됩니다. 운영에서는 절대 경로를 사용하십시오. npm 패키지 설치 경로 내부에는 DB를 둘 수 없습니다.
+
+## API와 Swagger
+
+| Method | Path | 인증 | 설명 |
+|---|---|---|---|
+| GET | `/health` | 없음 | 애플리케이션·DB 상태 |
+| GET | `/version` | 없음 | 패키지 이름과 버전 |
+| GET | `/docs` | 설정에 따름 | Swagger UI |
+| GET | `/openapi.json` | 설정에 따름 | OpenAPI 문서 |
+
+업무 API는 제품명 접두사 없이 `/api/v1`을 사용합니다.
+
+| 영역 | Method | Path |
+|---|---|---|
+| 인증 | POST | `/api/v1/auth/register` |
+| 인증 | POST | `/api/v1/auth/login` |
+| 인증 | POST | `/api/v1/auth/refresh` |
+| 인증 | POST | `/api/v1/auth/logout` |
+| 사용자 | GET | `/api/v1/users` |
+| 사용자 | GET | `/api/v1/users/me` |
+| 프로젝트 | POST/GET | `/api/v1/projects` |
+| 프로젝트 | GET/PATCH | `/api/v1/projects/{projectId}` |
+| 프로젝트 | PUT | `/api/v1/projects/{projectId}/status` |
+| 프로젝트 멤버 | GET/POST | `/api/v1/projects/{projectId}/members` |
+| 프로젝트 멤버 | PATCH/DELETE | `/api/v1/projects/{projectId}/members/{userId}` |
+| 피드백 | POST | `/api/v1/projects/{projectId}/feedbacks` |
+| 피드백 | GET | `/api/v1/projects/{projectId}/feedbacks/markers` |
+| 피드백 | GET/PATCH | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}` |
+| 피드백 | PUT | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/status` |
+| 피드백 | PUT | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/assignee` |
+| 피드백 | GET | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/overview` |
+| Case | GET | `/api/v1/projects/{projectId}/report-cases` |
+| Case | POST/GET | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/report-cases` |
+| Case | GET/PATCH | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/report-cases/{caseId}` |
+| Case | PUT | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/report-cases/{caseId}/status` |
+| Case | PUT | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/report-cases/{caseId}/assignee` |
+| Case | GET | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/report-cases/{caseId}/timeline` |
+| 답글 | POST/GET | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/report-cases/{reportCaseId}/replies` |
+| 답글 | PATCH/DELETE | `/api/v1/projects/{projectId}/feedbacks/{feedbackId}/report-cases/{reportCaseId}/replies/{replyId}` |
+
+이미지 첨부 7개 API는 제외되어 있으며, 비어 있지 않은 `attachmentIds`는 계속 `503 attachments-disabled`를 반환합니다. 수정·삭제의 권한, ETag, 상태 전이 및 통합 조회 DTO는 [비첨부 API 호환 계약](docs/guides/non-attachment-api-contract.md)을 참고하십시오.
+
+localhost에서는 문서가 기본 활성화되고 외부 바인딩과 Docker에서는 비활성화됩니다. 외부에서 문서를 공개하려면 노출 위험을 검토한 뒤 `DOCS_ENABLED=true`를 명시하십시오.
+
+가입·로그인·갱신·로그아웃을 제외한 업무 API는 로그인 응답의 사용자 Access Token을 요구합니다.
+
+```http
+Authorization: Bearer <ACCESS_TOKEN>
+```
+
+기존 .NET API의 `/api/v1/fivepixels/**` 경로는 Community에서 제공하지 않습니다. 기존 프론트엔드는 `baseUrl`을 `http://localhost:3000/api/v1`처럼 변경하십시오.
+
+회원가입부터 JWT 갱신과 프로젝트 생성까지의 복사 가능한 예제는 [Community API 연동 빠른 시작](docs/guides/community-api-quickstart.md)을 참고하십시오.
+
+Vite 개발 서버만 CORS로 허용하는 예시는 다음과 같습니다.
+
+```bash
+fivepixels-lite-api start \
+  --cors-origin 'http://localhost:5173,http://127.0.0.1:5173'
+```
+
+이 옵션은 두 origin만 정확히 허용합니다. 운영에서는 실제 프론트엔드의 HTTPS origin만
+지정하고 `*`를 사용하지 마십시오. 첨부 기능은 이번 버전에 포함되지 않으므로 비어 있지
+않은 `attachmentIds`를 보내면 `503 attachments-disabled`를 반환합니다.
+
+## 최초 설치용 단일 DDL
+
+수동으로 DB를 준비하려면 [sql/fivepixels-lite-init.sql](sql/fivepixels-lite-init.sql) 하나만 실행하면 됩니다. **SQLite 전용이며, 현재 미배포 개발 소스의 migration 007까지 반영한 신규 설치용 파일**입니다. migration 007이 없는 이전 배포 패키지와 혼용하지 마십시오. 일반 설치는 기존 `init`/`start` 자동 생성 방식을 그대로 사용해도 됩니다.
+
+- 업무 테이블 11개와 `schema_migrations`, 명시적 인덱스 21개, OWNER 보호 트리거 3개, PK/FK/UNIQUE/CHECK/기본값, 001~007 이력과 체크섬을 포함합니다. PK/UNIQUE의 SQLite 자동 인덱스는 별도입니다.
+- SQLite 3.38 이상(STRICT·내장 JSON 지원)에서 앱 함수나 확장 모듈 없이 실행합니다. 최신 보안 패치 버전 사용을 권장하며, API 런타임의 WAL 안전 버전 검사는 그대로 유지됩니다.
+- **새 연결·빈 DB 전용**입니다. `BEGIN IMMEDIATE` 안에서 기존 테이블·뷰 등 사용자 스키마를 검사하고, 기존 DB나 재실행이면 `fivepixels-init-requires-empty-database` 오류로 거부합니다. 기존 테이블을 삭제하거나 덮어쓰지 않습니다.
+- 파일 전체를 오류 즉시 중단 모드로 실행해야 합니다. GUI의 자동 커밋/오류 무시 후 계속 실행은 사용하지 마십시오. 오류가 나면 `ROLLBACK` 후 연결을 닫습니다. `sqlite3 -bail`은 첫 오류에 종료하며 미커밋 변경은 연결 종료로 롤백됩니다.
+- 관리자 계정·JWT 키·샘플 업무 데이터는 포함하지 않습니다. FK는 켜고, WAL/동기화 설정과 JWT 키 준비는 이후 API `init`/`start`가 처리합니다.
+
+아래 예시는 이 개발 소스를 빌드한 디렉터리에서 실행합니다. `/srv/fivepixels-new`는 **API 실행 계정이 소유한 신규 로컬 디렉터리의 예시**이며, 실제 경로·소유자·권한을 먼저 확인하십시오. API를 실행한 상태의 DB나 기존 운영 DB에는 적용하지 마십시오.
+
+```bash
+umask 077
+mkdir -p /srv/fivepixels-new
+sqlite3 -bail /srv/fivepixels-new/data.db < sql/fivepixels-lite-init.sql
+```
+
+차례로 신규 파일의 기본 접근 권한을 제한하고, 저장 디렉터리를 준비하고, 단일 DDL을 오류 즉시 중단 모드로 실행합니다. `umask`는 현재 셸에만 적용되며 기존 경로의 소유권·권한은 바꾸지 않습니다. 성공 시 busy timeout 값 `5000`, schema version `7`, 무결성 결과 `ok`가 출력되고 FK 위반 목록은 비어 있어야 합니다. **종료 코드 0과 성공 출력을 확인한 후에만** 다음 단계로 진행하십시오.
+
+```bash
+node dist/cli/index.js init --db-path /srv/fivepixels-new/data.db
+node dist/cli/index.js start --db-path /srv/fivepixels-new/data.db
+```
+
+`init`은 같은 DB의 스키마 버전 7을 확인하고 WAL과 JWT 키를 준비합니다. `Database is already initialized.`가 정상 결과이며 001~007을 다시 실행하지 않습니다. `start`는 해당 DB로 API를 시작합니다. 외부 바인딩 전 관리 토큰·JWT 키 파일·가입 정책·CORS·방화벽 설정은 이 문서의 보안 설정 절차를 따르십시오. npm 패키지에도 `sql/fivepixels-lite-init.sql` 경로로 포함되지만, 현재 개발 변경의 공개/배포를 의미하지는 않습니다.
+
+설치 확인용 읽기 전용 SQL:
+
+```sql
+SELECT version, name, checksum, applied_at FROM schema_migrations ORDER BY version;
+PRAGMA integrity_check;
+PRAGMA foreign_key_check;
+```
+
+기존 설치의 업그레이드는 단일 DDL 재실행이 아니라 `migrate`/`start`의 순차 마이그레이션을 사용합니다. 초기 설치 실패 시 이 파일을 중간부터 재개하지 말고 원인을 확인한 뒤 빈 DB 여부를 확인하여 전체를 실행하십시오. 서비스 사용 후 롤백은 아래 백업/복원 절차를 따릅니다. 테스트는 이 파일의 실제 스키마와 이력을 자동 마이그레이션 결과와 비교하므로, 새 마이그레이션 추가 시 단일 DDL도 함께 갱신해야 합니다.
+
+## Docker
+
+아래는 **소스에서 직접 빌드한 로컬 이미지**를 사용하는 예제입니다. `ghcr.io/fivepixels/lite-api:0.2.1`은 이미지 태그이며 npm 이름 공간과 별개입니다. Docker registry에는 공개하지 않았으므로 직접 빌드한 뒤 실행하십시오. [기존 CI 검증](https://github.com/siwan315/fivepixels-lite-api/actions/runs/34565870607)에서는 이미지 빌드·health·비-root 실행·1 vCPU/512MB 제한·정상 종료·DB 영속성을 확인했습니다. 이는 실제 운영 배포나 운영 부하 검증을 대신하지 않습니다.
+
+이미지 빌드:
+
+```bash
+docker build -t ghcr.io/fivepixels/lite-api:0.2.1 .
+```
+
+이 명령은 Debian slim builder에서 `better-sqlite3`를 컴파일하고, 컴파일러가 없는 비-root runtime 이미지를 만듭니다.
+
+실행:
+
+```bash
+docker volume create fivepixels-api-data
+docker run -d \
+  --name fivepixels-lite-api \
+  -p 3000:3000 \
+  -v fivepixels-api-data:/data \
+  -e ADMIN_TOKEN='<32자 이상의 토큰>' \
+  -e REGISTRATION_ENABLED=true \
+  ghcr.io/fivepixels/lite-api:0.2.1
+```
+
+첫 명령은 영구 볼륨을 만들고, 두 번째 명령은 3000 포트와 `/data` 볼륨을 연결해 최초 사용자를 등록할 수 있는 상태로 실행합니다. 최초 등록 후 컨테이너를 정상 종료하고 같은 볼륨으로 `REGISTRATION_ENABLED=false` 상태에서 다시 실행하십시오. 환경변수는 `docker inspect` 권한이 있는 사용자에게 보일 수 있으므로 Compose에서는 secret 파일을 권장합니다.
+
+Compose 실행 전 `./secrets/admin_token`에 32자 이상의 토큰을 저장하고 권한을 제한합니다.
+
+```bash
+REGISTRATION_ENABLED=true docker compose up -d --build
+docker compose ps
+docker compose logs -f api
+```
+
+첫 명령은 최초 가입만 임시 허용해 이미지를 빌드·실행하고, 뒤의 명령은 Healthcheck 상태와 API 로그를 확인합니다. 최초 계정을 등록한 뒤 `docker compose down`으로 컨테이너를 정상 종료하고 일반 `docker compose up -d`로 다시 시작하면 Compose 기본값에 따라 가입이 비활성화됩니다. `down`만으로 named volume은 삭제되지 않지만 `down -v`는 데이터를 삭제하므로 사용하지 마십시오. 실제 DB와 token 파일은 이미지 빌드 컨텍스트에서 제외됩니다.
+
+호스트 bind mount를 사용한다면 컨테이너의 `node` 사용자(일반적으로 UID 1000)가 디렉터리에 쓸 수 있어야 합니다. 권한을 임의로 `777`로 열지 마십시오.
+
+```bash
+docker run --rm --entrypoint id ghcr.io/fivepixels/lite-api:0.2.1
+ls -ld /호스트/데이터/경로
+```
+
+첫 명령으로 이미지의 UID/GID를 확인하고, 두 번째 명령으로 호스트 디렉터리 소유권과 권한을 비교합니다. 불일치하면 운영 정책에 맞는 전용 디렉터리를 만들고 해당 UID/GID에만 쓰기 권한을 부여하십시오.
+
+## systemd 예제
+
+Linux 운영 환경용이며, 검증된 로컬 tarball 또는 정식 공개 패키지를 전역 설치한 뒤 사용합니다. 소스 빠른 시작만 실행했다면 전역 명령이 없으므로 이 예제를 그대로 적용하지 마십시오.
+
+전역 설치된 실행 경로는 먼저 확인합니다.
+
+```bash
+command -v fivepixels-lite-api
+```
+
+이 명령은 systemd의 `ExecStart`에 넣을 실제 절대 경로를 출력합니다. 다음 내용을 `/etc/systemd/system/fivepixels-lite-api.service`에 맞게 작성합니다.
+
+```ini
+[Unit]
+Description=Fivepixels Lite API
+After=network.target
+
+[Service]
+Type=simple
+User=fivepixels-api
+Group=fivepixels-api
+ExecStart=/usr/local/bin/fivepixels-lite-api start
+Environment=HOST=127.0.0.1
+Environment=PORT=3000
+Environment=DB_PATH=/var/lib/fivepixels-api/data.db
+Environment=LOG_LEVEL=info
+Environment=DOCS_ENABLED=false
+Environment=REGISTRATION_ENABLED=false
+Environment=ADMIN_TOKEN_FILE=/etc/fivepixels-api/admin-token
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=15
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/fivepixels-api
+
+[Install]
+WantedBy=multi-user.target
+```
+
+전용 사용자에게 `/var/lib/fivepixels-api` 쓰기 권한과 token 파일 읽기 권한만 부여하십시오. 설정 후 다음 명령을 사용합니다.
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now fivepixels-lite-api
+sudo systemctl status fivepixels-lite-api
+sudo journalctl -u fivepixels-lite-api -f
+```
+
+각 명령은 unit을 다시 읽고, 서비스를 시작·자동 시작 등록하고, 상태와 로그를 확인합니다. 운영 서비스 시작·재시작 전에는 경로, 사용자, 포트, token 파일을 반드시 확인하십시오.
+
+## 백업과 복원
+
+기본 백업:
+
+```bash
+fivepixels-lite-api backup
+fivepixels-lite-api backup --output /safe/local/path/data-backup.db
+```
+
+첫 명령은 DB 옆 `backups/`에 시간 기반 이름으로 저장하고, 두 번째 명령은 지정한 새 파일에 저장합니다. 기존 파일은 덮어쓰지 않습니다.
+
+미적용 마이그레이션이 있으면 기존 DB를 먼저 자동 백업합니다. 성공 후 자동 백업은 최근 3개만 보존하고 수동 백업은 삭제하지 않습니다.
+
+복원은 반드시 서비스를 중지한 상태에서 수행합니다.
+
+1. 현재 `data.db`, `data.db-wal`, `data.db-shm`을 별도 안전 경로로 이동합니다.
+2. 검증된 백업을 설정된 `DB_PATH`의 파일명으로 복사합니다.
+3. 서비스 계정의 파일 소유권과 읽기·쓰기 권한을 확인합니다.
+4. `sqlite3 /복원/경로/data.db 'PRAGMA integrity_check; PRAGMA foreign_key_check;'`를 실행합니다. 첫 결과는 `ok`, 이후 결과는 빈 목록이어야 합니다.
+5. 서비스를 시작하고 `/health`, `fivepixels-lite-api status`, 로그를 확인합니다.
+
+위 `sqlite3` 명령은 복원 파일의 페이지 무결성과 외래 키 위반을 서비스 시작 전에 검사합니다. 검사 결과가 다르면 서비스를 시작하지 말고 다른 백업을 선택하십시오.
+
+복원 실패 시 서비스를 다시 중지하고 보존해 둔 기존 DB 세트를 원래 위치로 되돌립니다.
+
+JWT 키도 DB와 별도로 백업하십시오. POSIX 환경에서는 실제 경로를 확인한 뒤 다음처럼
+소유자만 읽을 수 있는 파일로 복사할 수 있습니다.
+
+```bash
+install -m 600 '/실제/데이터/경로/jwt-secret' '/보안/백업/경로/fivepixels-jwt-secret'
+```
+
+`install -m 600`은 키를 복사하면서 소유자 읽기·쓰기 권한만 부여합니다. 키를 복원할 때는
+서비스를 먼저 중지하고, 현재 키를 별도로 보존한 뒤 다음처럼 원래 위치에 복사합니다.
+
+```bash
+install -m 600 '/보안/백업/경로/fivepixels-jwt-secret' '/실제/데이터/경로/jwt-secret'
+```
+
+서비스 계정의 소유권과 읽기 권한을 확인한 후 다시 시작하십시오. 잘못된 키를 복원하면
+기존 Access Token 검증이 실패합니다. DB 복원과 JWT 키 복원은 같은 백업 시점을 기준으로
+관리하되, Refresh Token 원문은 DB에 저장되지 않으므로 별도 복구할 수 없습니다.
+
+## 업그레이드와 롤백
+
+현재 미배포 개발 브랜치에는 selfdev 저장 규칙 정렬을 위한 migration 006·007이 포함되어 있습니다.
+006은 인증 정규화 보조 컬럼을 제거하고, 007은 날짜를 UTC 소수초 7자리로 정렬하며 경로 해시를
+SQL Server와 같은 UTF-16LE 입력으로 재계산합니다. 신규 비밀번호는 Identity V3이고 기존 scrypt는
+로그인 성공 시 전환합니다. 공통 업무 API 34개와 `/api/v1` 경로는 유지합니다.
+
+사용자 정의 테이블·컬럼·인덱스·트리거·뷰 또는 일관되지 않은 인증 키/잘못된 날짜가 있으면
+자동 정렬을 중단합니다. 제약을 끄거나 해당 데이터를 임의 삭제해 통과시키지 마십시오.
+각 migration은 별도 트랜잭션이므로 007 실패 시 006까지는 적용된 상태일 수 있습니다.
+이전 바이너리만 되돌리지 말고, 업그레이드 전 DB 백업과 이전 앱을 함께 복원해야 합니다.
+
+구현 범위, 보존 규칙, 검증과 남은 차이는 [selfdev 저장 규칙 정렬](docs/plans/selfdev-schema-alignment.md)을 참고하십시오.
+
+1. `fivepixels-lite-api backup`으로 수동 백업합니다.
+2. 새 npm 패키지 또는 Docker 이미지를 준비합니다.
+3. 서비스를 정상 종료합니다.
+4. 새 버전을 설치하고 시작합니다. 시작 시 미적용 마이그레이션이 자동 적용됩니다.
+5. `/health`, `/version`, `fivepixels-lite-api status`, 운영 로그를 확인합니다.
+
+마이그레이션은 forward-only입니다. `0.2.1`의 migration 005를 적용한 DB는 엄격한 migration 이력 검사 때문에 migration 005 파일이 없는 `0.2.0`으로 바이너리만 되돌릴 수 없습니다. `0.2.0`으로 롤백하려면 서비스를 중지하고 업그레이드 전에 자동 생성된 DB 백업과 같은 시점의 JWT 키를 명시적으로 복원하십시오.
+
+## SQLite 운영 제한과 PostgreSQL 전환 기준
+
+WAL에서는 읽기와 쓰기를 병행할 수 있지만 동시 writer는 하나입니다. 쿼리는 인덱스를 사용하고 트랜잭션을 짧게 유지하며, 현재 목록 API는 `page=1`, `pageSize=20`, 최대 `100`을 강제합니다.
+
+다음 상황에서는 PostgreSQL 전환을 검토하십시오.
+
+- API 프로세스를 두 개 이상 실행해야 하는 경우
+- 지속적인 `SQLITE_BUSY` 또는 쓰기 대기가 관측되는 경우
+- 고가용성, 원격 DB, 실시간 복제 또는 무중단 장애 조치가 필요한 경우
+- 장시간 트랜잭션·분석 쿼리·대량 동시 쓰기가 필요한 경우
+- 사용자별 DB 권한과 복잡한 데이터 격리가 필요한 경우
+
+Service에는 SQLite 객체나 SQL을 노출하지 않고 Repository에 SQL을 격리해 PostgreSQL 전환 시 Route와 Service 계약을 유지합니다.
+
+## 보안 주의사항
+
+- 기본 수신 주소는 localhost이며 외부 수신에는 관리자 토큰이 필수입니다.
+- CORS는 기본 비활성화되고 wildcard origin은 거부됩니다.
+- 토큰과 `Authorization` 헤더는 로그에 기록하지 않습니다.
+- JWT 키 파일은 DB 백업과 별도로 안전하게 보관하십시오. 키를 잃거나 교체하면 기존 Access Token은 무효화됩니다.
+- 실제 `.env`, DB, token, 로그, 백업은 npm 패키지와 Docker 이미지에 포함하지 않습니다.
+- 인터넷 공개 시 TLS 종료, 방화벽, 요청 제한은 Nginx나 관리형 reverse proxy에서 추가하십시오.
+- Swagger를 외부에 공개하면 endpoint와 schema가 노출됩니다.
+
+## 문제 해결
+
+- `ADMIN_TOKEN ... required`: 외부 바인딩에는 32자 이상의 `ADMIN_TOKEN` 또는 읽을 수 있는 `ADMIN_TOKEN_FILE`이 필요합니다.
+- `JWT_SECRET_FILE could not be read`: 지정한 JWT 키 파일의 경로와 서비스 사용자의 읽기 권한을 확인합니다.
+- 회원가입 403: 외부 바인딩과 Docker에서는 가입이 기본 비활성화됩니다. 최초 등록 시에만 `REGISTRATION_ENABLED=true`를 사용하고 즉시 다시 끄십시오.
+- `SQLite WAL mode could not be enabled`: DB 경로가 로컬 디스크인지, 상위 디렉터리에 쓰기 권한이 있는지 확인합니다.
+- `SQLITE_BUSY`: 장시간 트랜잭션, 별도 프로세스의 DB 접근, 대량 쓰기를 확인합니다. API는 이를 503으로 변환합니다.
+- `better_sqlite3.node` 로드 실패: 지원 Node 22·24인지 확인한 뒤 같은 Node 버전에서 패키지를 다시 설치합니다.
+- `/docs`가 404: 외부 수신과 Docker에서는 기본 비활성화됩니다. 필요할 때만 `DOCS_ENABLED=true`를 설정합니다.
+- `EADDRINUSE`: `PORT`를 사용하는 다른 프로세스를 확인하거나 사용 가능한 포트로 변경합니다.
+- Docker에서 `/data` 쓰기 실패: volume 또는 bind mount가 컨테이너 `node` 사용자에게 쓰기 가능한지 확인합니다.
+
+## 개발과 검증
+
+Node 22·24 및 Linux/macOS/Windows CI 구성이 있습니다. 기존 로컬 실행 검증은 macOS / Node 24 기준이며, CI 설정 존재가 모든 OS·Node 조합의 통과나 운영 배포 성공을 뜻하지 않습니다. 아래 명령은 개발자 검증 절차입니다.
+
+소스는 `auth`, `users`, `projects/members`, `feedbacks`, `report-cases`, `replies`, `page-elements` 기능별로 구성합니다. 파일별 책임, Swagger 분류, 복합 처리 트랜잭션과 검증 기준은 [기능별 코드 구조](docs/guides/feature-structure.md)를 참고하십시오. 내부 구조 정리로 외부 API 계약이나 DB 스키마를 변경하지 않습니다.
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm pack --dry-run
+```
+
+각 명령은 lockfile 기반 설치, 타입 검사, 정적 검사, 테스트, 배포 빌드, npm 포함 파일 검증을 수행합니다. `.gitattributes`는 소스·SQL·문서의 checkout 줄바꿈을 LF로 고정하여 OS별 체크섬 차이를 방지합니다. 실제 다른 OS에서 생성한 tarball의 동일성은 CI로 확인해야 합니다.
+
+Docker 리소스 제한 검증:
+
+```bash
+docker run --rm \
+  --cpus 1 \
+  --memory 512m \
+  -p 3000:3000 \
+  -v fivepixels-api-data:/data \
+  -e ADMIN_TOKEN='<32자 이상의 토큰>' \
+  ghcr.io/fivepixels/lite-api:0.2.1
+```
+
+이 명령은 컨테이너를 1 vCPU와 RAM 512MB로 제한해 실행합니다. 실제 운영 전에는 예상 payload와 동시 쓰기량을 반영한 별도 부하 테스트가 필요합니다.
+
+## 공개 전 점검
+
+- `@fivepixels-js` npm 이름 공간의 소유·배포 권한과 패키지 이름을 확인합니다. GitHub 저장소 소유권이 npm 권한을 뜻하지는 않습니다.
+- `package.json`의 `repository`, `homepage`, `bugs`는 `siwan315/fivepixels-lite-api`로 연결되어 있습니다. 공개 전 실제 저장소·이슈 접근 정책을 다시 확인합니다.
+- 운영·연동 문서 5개의 포함 목록과 상대 링크를 테스트로 확인합니다. `test/package.test.ts`는 소스와 포함 목록의 계약을, 독립 CLI의 패키지 테스트는 실제 설치본의 문서·링크를 검사합니다.
+- 실제 tarball의 DB·키·토큰·로그·백업 제외 여부와 지원 환경의 설치·실행을 검증합니다.
+- 공개 runtime이 포함된 Lite `0.2.1`을 먼저 공개한 뒤, CLI에서 **실제 공개 tarball**과 lockfile을 맞추고 설치·CI를 다시 검증한 다음 CLI `0.1.0` 공개를 진행합니다.
+
+현재 `publishConfig.access`는 `public`입니다. GitHub가 비공개여도 npm 공개 시 배포 파일은 누구나 내려받을 수 있으므로 코드·문서의 공개 범위를 별도로 검토하십시오. npm 공개·Git commit/push·이미지 registry push·운영 배포는 각각 명시적으로 승인한 단계에서만 수행합니다.
+
+## 상세 문서와 향후 제품 방향
+
+아래 운영·연동 문서 5개는 소스와 npm 패키지에 함께 포함됩니다.
+
+- [기능별 코드 구조](docs/guides/feature-structure.md)
+- [Community API 연동 빠른 시작](docs/guides/community-api-quickstart.md)
+- [비첨부 API 호환 계약](docs/guides/non-attachment-api-contract.md)
+- [독립 CLI와 공개 런타임](docs/guides/independent-cli.md)
+- [selfdev 저장 규칙 정렬](docs/plans/selfdev-schema-alignment.md)
+
+미래 계획은 [소스 저장소](https://github.com/siwan315/fivepixels-lite-api)의 `docs/product/self-hosted-and-saas-strategy.md`와 `docs/plans/one-command-self-hosted-cli.md`에서만 관리합니다. 비공개 저장소 접근 권한이 필요하며 npm 패키지에는 넣지 않습니다.
+
+독립 `@fivepixels-js/cli`의 Lite 명령 연결은 이미 구현되어 있습니다. PostgreSQL 기반 `@fivepixels/basic-api`, Docker 실행 관리, selfdev 선택, 관리형 SaaS는 미래 범위입니다. 미래 계획 문서의 모노레포 구성은 이전 초안이며, 현재 API와 CLI는 독립 Git 저장소를 유지합니다.

package/dist/app.d.ts

@@ -0,0 +1,10 @@
+import type { FastifyInstance } from 'fastify';
+import type { AppConfig } from './config/config.js';
+import type { SqliteDatabase } from './db/connection.js';
+export interface BuildAppOptions {
+    config: AppConfig;
+    database: SqliteDatabase;
+    logger?: boolean;
+}
+export declare function buildApp(options: BuildAppOptions): Promise<FastifyInstance>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAQzD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA+DjF"}