@fivepixels-js/lite-api 0.2.1

package/docs/guides/non-attachment-api-contract.md

@@ -0,0 +1,138 @@
+# 비첨부 API 호환 계약
+
+현재 Lite 구현은 34개 업무 operation입니다. selfdev(.NET Fivepixels)의 41개 중 이미지 첨부 7개를 제외한 경로를 제공합니다. 이번 변경은 기존 21개에 수정·상태·담당자·통합 조회 13개를 추가합니다. 패키지 버전은 0.2.1로 유지했으며 공개 배포는 수행하지 않았습니다.
+
+## SDK 연결 기준
+
+SDK의 상대 경로는 `/projects/...`로 유지하고 서버별 `baseUrl`만 설정합니다.
+
+- Lite: `http://localhost:3000/api/v1`
+- 현재 selfdev: `https://<selfdev-host>/api/v1/fivepixels`
+
+Lite에는 `/api/v1/fivepixels` 별칭이 없습니다. SDK를 새로 구현하거나 배포한 작업은 아니며, 아래 검증은 API 계약과 Lite의 HTTP/SQLite 동작에 대한 검증입니다. 동일 SDK 패키지를 두 서버에 실제 연결하는 E2E 검증은 별도로 필요합니다.
+
+이미지 업로드·예약·완료·연결·삭제·접근 URL 기능은 구현하지 않습니다. 기존 생성 요청의 `attachmentIds`가 비어 있지 않으면 `503 attachments-disabled`이고 응답의 `attachments`는 빈 배열입니다. SDK/UI는 Lite에서 이미지 기능을 호출하지 않아야 합니다.
+
+## 추가 엔드포인트와 DTO
+
+아래 경로는 baseUrl 기준입니다. 축약 표기:
+
+- P = `/projects/{projectId}`
+- F = `P/feedbacks/{feedbackId}`
+- C = `F/report-cases/{caseId}`
+- R = `F/report-cases/{reportCaseId}/replies/{replyId}`
+
+| Method | 경로 | 요청 본문 또는 query | 성공 result DTO |
+|---|---|---|---|
+| PATCH | P | `{projectName}` | ProjectResponse |
+| PUT | P/status | `{status: ACTIVE 또는 ARCHIVED}` | ProjectResponse |
+| PATCH | F | `{fieldValues, position, integrations, targetSelector?}` | FeedbackDetailResponse |
+| PUT | F/status | `{status: OPEN 또는 RESOLVED}` | FeedbackDetailResponse |
+| PUT | F/assignee | `{assigneeId?}` | FeedbackDetailResponse |
+| PATCH | C | `{content, pageElements?}` | ReportCaseResponse |
+| PUT | C/status | `{status: OPEN 또는 RESOLVED}` | ReportCaseResponse |
+| PUT | C/assignee | `{assigneeId?}` | ReportCaseResponse |
+| PATCH | R | `{content, pageElements?}` | ReplyResponse |
+| DELETE | R | 본문 없음 | 204, 빈 본문 |
+| GET | P/report-cases | 필수 environment, pathname; 선택 status, page, pageSize | ReportCaseResponse[] |
+| GET | C/timeline | page, pageSize | `{reportCase, replies}` |
+| GET | F/overview | casePageSize, replyPageSize | `{feedback, cases, selectedCase}` |
+
+DELETE 이외의 성공 상태는 200입니다. 모든 요청은 사용자 JWT가 필요하고 모든 PATCH/PUT/DELETE는 현재 리소스의 `If-Match`가 필수입니다. 성공한 수정 응답에는 새 `ETag`가 있습니다. 타임라인·overview에는 selfdev와 동일하게 ETag 헤더가 없으므로 내부 객체의 version 또는 개별 상세 조회 ETag를 사용합니다.
+
+`fieldValues`와 `position`은 JSON object, `integrations`는 JSON array이며 PATCH에서 모두 필수입니다. `targetSelector`의 생략/null은 null로 설정합니다. 프로젝트 이름은 trim 후 1~100자, 케이스 내용은 비어 있지 않아야 하며, 답글은 trim 후 1~10,000자입니다.
+
+`pageElements`는 기존 생성 DTO와 동일한 `{mentionId, label, selector, dataReportId?}[]`입니다. 생략/null은 보존, []는 연결 해제, 배열은 교체입니다. 동일 mentionId에 다른 요소 정보를 지정하면 409이며 내용·버전·태그 변경 전체가 롤백됩니다. 이미지 첨부와 별개인 화면 요소 태그 기능은 유지합니다.
+
+## 권한과 상태 규칙
+
+- 프로젝트 이름·상태, 피드백 담당자는 OWNER만 변경할 수 있습니다.
+- 피드백 내용은 작성자 또는 OWNER, 피드백 상태는 현재 담당자 또는 OWNER가 변경합니다.
+- 케이스 내용·상태·담당자는 케이스 작성자 또는 OWNER가 변경합니다. 담당자라는 이유만으로 케이스 수정 권한을 얻지는 않습니다.
+- 답글 수정·삭제는 답글 작성자 또는 OWNER만 수행합니다. 해결된 케이스의 기존 답글은 수정·삭제 가능하지만 신규 답글 생성은 계속 금지합니다.
+- ARCHIVED 프로젝트는 조회와 OWNER의 프로젝트 상태 복구만 허용합니다.
+- 비멤버에게 프로젝트 존재를 노출하지 않으며 404를 반환합니다. 담당자는 해당 프로젝트의 멤버여야 합니다. assigneeId 생략/null은 담당자 해제입니다.
+- 프로젝트 이름·상태, 내용 수정은 동일 값이어도 버전이 증가합니다. 피드백/케이스 상태와 담당자가 동일하면 버전은 유지합니다.
+- 열린 케이스가 남아 있으면 피드백을 수동으로 해결할 수 없습니다.
+- 마지막 열린 케이스 해결 시 피드백을 RESOLVED로 바꾸고 RESOLVED 시스템 답글을 생성합니다. 해결된 피드백의 케이스를 다시 열면 피드백도 OPEN이 되며 REOPENED 시스템 답글을 생성합니다.
+- 실제 케이스 상태 변경마다 피드백 버전도 증가합니다. 케이스 내용·담당자 및 답글 수정·삭제는 피드백 버전을 변경하지 않습니다.
+- 케이스 담당자 변경 시 ASSIGNEE_ASSIGNED / ASSIGNEE_TRANSFERRED / ASSIGNEE_UNASSIGNED 시스템 답글에 이전·새 담당자를 남깁니다. 피드백 담당자 변경은 시스템 답글을 생성하지 않습니다.
+- 시스템 답글은 수정·삭제 불가입니다. 사용자 답글 삭제는 soft delete이며 목록에 DELETED 상태, 빈 content, 빈 pageElements/attachments와 증가한 version을 반환합니다. DB 원문은 보존됩니다.
+
+## 조회 및 페이지 구조
+
+기본 페이지 크기는 20, 최대 100입니다. 프로젝트 케이스 목록은 environment(소문자 정규화)와 pathname(해시 및 원문)을 모두 비교합니다. 케이스는 createdAt DESC, id DESC이고 답글은 createdAt ASC, id ASC입니다. 동일 시각의 항목 순서는 id가 결정하며 요청 도착 순서를 의미하지 않습니다.
+
+타임라인의 최상위 pagination은 replies에만 적용됩니다. overview는 최상위 빈 pagination과 다음 내부 페이지들을 반환합니다.
+
+```text
+result
+├─ feedback: 기존 상세 DTO에서 projectId와 cases를 제외한 필드
+├─ cases
+│  ├─ items: {id, type, content, createdAt, pageElements, attachments}[]
+│  └─ pagination: 케이스 첫 페이지
+└─ selectedCase: 최신 케이스가 없으면 null
+   ├─ id: cases.items[0].id
+   └─ replies
+      ├─ items: ReplyResponse[]
+      └─ pagination: 선택한 케이스 답글 첫 페이지
+```
+
+프로젝트 목록/overview/타임라인은 SQLite 읽기 트랜잭션으로 일관된 스냅샷을 조회합니다. overview는 전체 케이스를 먼저 적재하지 않으며, 페이지에 포함된 사용자와 태그는 일괄 조회합니다.
+
+사용자 검색 `GET /users`도 selfdev처럼 query 생략·공백·한 글자를 허용합니다. 결과는 활성 사용자만 포함하고 기존 페이지 제한, 분당 30회 제한 및 개인정보 비노출을 유지합니다.
+
+## 요청·응답 예제
+
+아래는 최신 케이스 version이 0인 경우의 상태 변경 요청입니다. 실제 서버 주소·프로젝트/피드백/케이스 ID와 사용자 토큰을 사용하십시오.
+
+```http
+PUT <baseUrl>/projects/<projectId>/feedbacks/<feedbackId>/report-cases/<caseId>/status
+Authorization: Bearer <ACCESS_TOKEN>
+If-Match: "0"
+Content-Type: application/json
+
+{"status":"RESOLVED"}
+```
+
+성공은 HTTP 200, ETag `"1"`이고 result는 version 1인 ReportCaseResponse입니다. result에는 id, feedbackId, type, status, content, creator, assignee, version, resolvedAt, createdAt, updatedAt, pageElements, attachments가 포함됩니다. 같은 If-Match로 다시 변경하면 다음과 같이 412를 반환합니다.
+
+```json
+{
+  "resultCode": "version-conflict",
+  "resultMessage": "다른 요청에서 변경되었습니다. 최신 데이터를 다시 조회해 주세요.",
+  "result": null,
+  "pagination": {
+    "page": 0, "pageSize": 0, "totalCount": 0,
+    "totalPages": 0, "hasNext": false, "hasPrevious": false
+  }
+}
+```
+
+SDK는 412 발생 시 최신 상태를 조회하고 사용자 변경 의도를 재확인해야 합니다. 버전만 바꿔 무조건 재시도하면 다른 사용자의 수정을 덮어쓸 수 있습니다.
+
+## 실패와 운영 확인
+
+| 상태 | 대표 resultCode / 원인 |
+|---|---|
+| 400 | 잘못된 DTO·상태·페이지·UUID, invalid-if-match |
+| 401 | JWT 없음·만료·유효하지 않음 |
+| 403 | project-owner-required, feedback-edit-forbidden, feedback-status-forbidden, report-case-edit-forbidden, reply-edit-forbidden |
+| 404 | project-not-found, feedback-not-found, report-case-not-found, reply-not-found, project-member-not-found |
+| 409 | project-archived, feedback-has-open-report-cases, page-element-mention-conflict, reply-deleted, system-reply-immutable |
+| 412 | version-conflict |
+| 428 | precondition-required |
+| 413 / 429 | 1 MiB 본문 제한 / 요청 횟수 제한 |
+| 500 / 503 | 내부 DB 오류 / DB busy 등 가용성 오류; 내부 정보는 응답에서 제외 |
+
+브라우저 SDK용 CORS에는 GET/HEAD/POST/PUT/PATCH/DELETE/OPTIONS를 허용하고 ETag, Location, Retry-After를 노출합니다. CORS 자체는 기본 비활성화이며 명시적으로 허용한 origin에만 적용합니다. 운영 SDK origin을 정확히 설정하십시오.
+
+변경 로그는 actorId, target 리소스 ID, HTTP operation, 응답 version과 기본 요청 ID/응답 시간으로 추적합니다. 본문·토큰은 기록하지 않습니다. 412 증가 시 동시 편집, 409 시 업무 상태, 503 시 SQLite 잠금 시간을 확인합니다.
+
+이번 변경은 기존 테이블/컬럼을 사용하며 신규 migration이나 DB 삭제는 없습니다. 쓰기 작업은 BEGIN IMMEDIATE 안에서 권한·버전 확인, 상태·태그 변경과 시스템 답글 생성을 완료합니다. SQLite 단일 writer 특성상 대용량 필드/케이스가 많은 상세 응답은 쓰기 잠금 시간을 늘릴 수 있으므로 운영 부하를 별도로 점검하십시오. 롤백은 배포 전 백업 및 이전 애플리케이션 아티팩트로 수행하며 신규 API에 의존한 클라이언트도 함께 조정해야 합니다. 운영 배포·서비스 재시작·DB 복원은 별도 승인 대상입니다.
+
+## 검증 범위와 남은 차이
+
+`test/fixtures/community-api-0.2.1.json`은 34개 메서드·경로·요청/응답 필드·ETag 계약을 고정하고 `test/lifecycle.test.ts`는 Fastify HTTP 주입과 임시 SQLite로 상태·권한·버전·롤백·페이징·CORS를 검증합니다. 이는 실브라우저 또는 selfdev SQL Server에 대한 운영 검증은 아닙니다.
+
+현재 selfdev의 알 수 없는 refresh token 로그아웃 오류, 비활성 사용자 멤버 추가 정책 등 기존 구현 차이는 이번 Lite 기능 추가로 변경하지 않았습니다. 따라서 “34개 비첨부 operation 제공”과 “모든 오류 경로까지 두 서버가 완전히 동일함”은 구분해야 합니다. 검색 정렬/대소문자 비교도 실제 SQL Server collation과 SQLite에서 추가 비교가 필요합니다.

package/docs/plans/selfdev-schema-alignment.md

@@ -0,0 +1,61 @@
+# selfdev 코드 기준 Lite 저장 규칙 정렬
+
+## 구현 범위
+
+미배포 개발 브랜치 `feat/selfdev-storage-alignment`의 변경이다. selfdev의 현재 엔티티·EF 매핑·실행 코드를 기준으로 Lite만 변경했다. 자동 export/import 도구, selfdev 수정, 이미지 첨부, workspace_id 추가는 포함하지 않는다. 기존 SQL Server 전체 DDL 스냅샷을 Lite의 업무 모델로 복제하지 않는다.
+
+공통 11개 테이블의 컬럼은 `test/fixtures/selfdev-runtime-schema.json`으로 고정했고 실제 SQLite 마이그레이션 결과와 비교한다. 기준 DbContext SHA-256은 `b9afcb4946c46be85075ade39865687e5c92f9edad4263eda1eceb98cfba6b8e`이다.
+
+## 저장 계약
+
+| 항목 | 적용 규칙 |
+|---|---|
+| 인증 키 | normalized_login_id/email 제거. login_id는 ASCII NOCASE UNIQUE, email은 소문자 저장 및 원본 UNIQUE |
+| 비밀번호 | 신규 Identity V3 / PBKDF2-HMAC-SHA256 600,000회 / salt 16바이트 / subkey 32바이트 |
+| 기존 비밀번호 | scrypt 및 Identity V2/V3 읽기 지원. 성공 로그인에서만 필요한 재해시를 로그인·토큰 저장과 같은 트랜잭션으로 처리 |
+| 날짜 | 업무 날짜 저장/비교를 UTC, 소수초 7자리로 통일. 100ns 단위 값의 마지막 4자리를 Date 변환으로 잃지 않음 |
+| 경로 해시 | BOM 없는 UTF-16LE SHA-256. Lite는 64자리 소문자 HEX, SQL Server는 같은 바이트의 BINARY(32) 표현 |
+| UUID/정렬 | 기존 UUID 값 보존. SQL에서 동일 시각 tie-breaker를 SqlGuid 순서로 정렬하고 대응 표현식 인덱스 사용 |
+| 업무 값 | 상태·역할·유형·본문·JSON 원문·NULL·태그 관계·lock_version 보존 |
+| FK/CHECK | 기존 무결성 제약 유지. CASCADE 일괄 변경 없음 |
+
+Identity V3의 형식은 [ASP.NET Core 6 PasswordHasher](https://github.com/dotnet/aspnetcore/blob/v6.0.36/src/Identity/Extensions.Core/src/PasswordHasher.cs)를 기준으로 한다. 해시는 PBKDF2 비용 최대 1,000,000회, salt/subkey 16~64바이트로 제한하고 scrypt는 기존 고정 파라미터만 허용한다. 연산 동시 처리 1개, 대기 최대 16개를 유지한다. 과도한 비용이나 손상된 해시는 실패 처리하며 해시·비밀번호를 로그에 남기지 않는다.
+
+기존 scrypt 계정이 모두 즉시 같은 형식으로 바뀌는 것은 아니다. 미접속 계정의 해시는 보존되며 selfdev로 그대로 복사하면 로그인할 수 없다. 이번 작업은 계정 이전 도구나 세션 공유를 제공하지 않는다.
+
+SQLite의 기본 문자열 비교와 SQL Server의 실제 collation은 모든 Unicode에 대해 같다고 보장하지 않는다. 특히 사용자 이름 검색·정렬과 이메일 중복의 Unicode 경계는 실제 selfdev DB 비교가 필요하다.
+
+## 마이그레이션과 보존
+
+- 001~005의 SQL/checksum은 변경하지 않았다. 원본 체크섬을 회귀 테스트로 고정했다.
+- 006_align_credentials: local_credentials 한 테이블만 재구성한다. 기존 인증정보를 복사하고 원본 컬럼의 고유 인덱스를 생성한다.
+- 007_align_storage_values: 기존 날짜를 표현만 정렬하고 원본 pathname에서 파생 해시를 재계산한다. 페이지 정렬용 인덱스 8개를 교체하고 필터 없는 정렬용 인덱스 2개를 추가한다.
+- 버전 고정 함수 fp_storage_timestamp_v1/fp_pathname_hash_v1의 의미를 나중에 변경하지 않는다. 새 변환 규칙은 새 migration으로 추가한다.
+- 모든 단계에서 foreign_keys=ON을 유지한다. 각 migration은 IMMEDIATE 트랜잭션 안에서 스키마 사전 검사, 변환, 행 수 및 integrity_check/foreign_key_check 검증을 수행한다.
+- 기존 DB는 적용 전에 SQLite backup API로 자동 백업한다. 성공 후 자동 백업 최근 3개만 보존하고 수동 백업은 건드리지 않는다.
+- 사용자 정의 스키마가 있으면 unsupported-custom-schema, 인증 정규화 키가 다르면 inconsistent-credential-keys, 유효하지 않은 날짜면 invalid-storage-timestamp로 중단한다. 데이터와 구조를 자동으로 삭제/수정해 통과시키지 않는다.
+- 007 실패 시 006은 커밋된 상태일 수 있다. 새 앱은 마이그레이션 실패 후 수신을 시작하지 않는다. 롤백은 서비스를 중지한 후 업그레이드 전 백업·해당 앱 버전·동일 시점 JWT 키를 함께 복원한다. 원본 DB/WAL/SHM을 보존하며 백업 위에 덮어쓰지 않는다.
+- 전체 테이블 재구성 및 FK 해제를 포함했던 006_selfdev_runtime_alignment.sql.draft는 폐기된 비실행 초안이다. 자동 migration 디렉터리에 넣거나 실행하지 않는다.
+
+007은 기존 행 전체를 읽고 날짜를 갱신하므로 데이터 크기에 비례하는 시간·임시 디스크/WAL 공간이 필요하다. 추가 인덱스 2개의 저장 공간과 쓰기 비용이 있다. 운영 적용 전에 복사본에서 소요 시간과 여유 공간을 확인하고 백업을 별도 보관한다.
+
+## 검증
+
+```bash
+npm ci --offline
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run test:storage-interop
+npm pack --dry-run
+```
+
+순서대로 잠금 파일 의존성 재설치, 타입 검사, 린트, 회귀 테스트, 빌드, .NET 교차 검증, 공개 패키지 포함 파일 점검이다. 오프라인 설치에는 기존 npm 캐시가 필요하며 교차 검증에는 .NET 6 SDK/runtime이 필요하다. 명령은 실제 업무 DB를 사용하지 않는다.
+
+- 기본 테스트: API 34개 계약, 인증/권한/ETag/상태 변경/CORS 및 SQLite 동작.
+- 추가 테스트: 기존 v5의 계정·토큰·JSON/NULL·삭제 답글 원문·태그 관계 보존, v5 백업 무결성, v6/v7 재실행, custom schema/키 불일치/잘못된 날짜 차단, v7 부분 변경 실패 롤백, 정밀도·SqlGuid 정렬/대표 인덱스 사용.
+- 인증 테스트: 기존 scrypt 유지/전환, 오류 비밀번호, 비활성 계정, 동시 암호 변경, 토큰 저장 실패 시 해시 전환 롤백.
+- .NET 교차 검증: .NET 6이 만든 Identity V2/V3 해시를 Lite가 검증하고 Lite 신규 해시를 .NET 6 PasswordHasher가 검증한다. Encoding.Unicode SHA256 및 SqlGuid 순서도 비교한다. `test/interop`은 합성 데이터만 사용하는 테스트 보조 도구다.
+
+실제 SQL Server/배포 selfdev HTTP/CORS/동일 SDK E2E는 검증하지 않았다. 교차 런타임 검증은 실제 DB 검증을 대체하지 않는다. npm/GHCR 공개, 운영 적용, 서비스 재시작, commit/push는 실행하지 않는다.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@fivepixels-js/lite-api",
+  "version": "0.2.1",
+  "description": "Fivepixels Lite API, a lightweight self-hosted Fastify and SQLite server.",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siwan315/fivepixels-lite-api.git"
+  },
+  "homepage": "https://github.com/siwan315/fivepixels-lite-api#readme",
+  "bugs": {
+    "url": "https://github.com/siwan315/fivepixels-lite-api/issues"
+  },
+  "type": "module",
+  "exports": {
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0"
+  },
+  "bin": {
+    "fivepixels-lite-api": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "sql/fivepixels-lite-init.sql",
+    "docs/guides/community-api-quickstart.md",
+    "docs/guides/non-attachment-api-contract.md",
+    "docs/guides/feature-structure.md",
+    "docs/guides/independent-cli.md",
+    "docs/plans/selfdev-schema-alignment.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true
+  },
+  "scripts": {
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
+    "dev": "tsx src/cli/index.ts start",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:storage-interop": "npm run build && node scripts/check-storage-interop.mjs",
+    "test:coverage": "vitest run --coverage",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.3.0",
+    "@fastify/jwt": "10.2.2",
+    "@fastify/rate-limit": "11.2.0",
+    "@fastify/swagger": "^9.8.1",
+    "@fastify/swagger-ui": "^6.1.1",
+    "better-sqlite3": "13.0.3",
+    "fastify": "^5.12.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.9.1",
+    "tsx": "^4.23.13",
+    "typescript": "6.0.3",
+    "typescript-eslint": "^8.69.0",
+    "vitest": "^4.1.11"
+  }
+}