@fivepixels-js/lite-api 0.2.1

package/dist/users/user-search.schemas.js

@@ -0,0 +1,41 @@
+import { communityErrorResponses, communityResponseSchema, nullableStringSchema, uuidSchema, } from '../community/schemas.js';
+const nullableBooleanSchema = {
+    anyOf: [{ type: 'boolean' }, { type: 'null' }],
+};
+export const userSearchItemSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'userName', 'profileImageUrl', 'isProjectMember'],
+    properties: {
+        id: uuidSchema,
+        userName: { type: 'string', minLength: 1, maxLength: 100 },
+        profileImageUrl: nullableStringSchema,
+        isProjectMember: nullableBooleanSchema,
+    },
+};
+export const searchUsersSchema = {
+    tags: ['users'],
+    summary: '활성 사용자 검색',
+    security: [{ userJwt: [] }],
+    querystring: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            query: {
+                type: 'string',
+                description: '사용자 이름 검색어. 생략하거나 공백이면 활성 사용자 전체를 페이지 단위로 조회합니다.',
+            },
+            projectId: uuidSchema,
+            page: { type: 'integer', default: 1 },
+            pageSize: { type: 'integer', default: 20 },
+        },
+    },
+    response: {
+        200: communityResponseSchema({
+            type: 'array',
+            items: userSearchItemSchema,
+        }),
+        ...communityErrorResponses,
+    },
+};
+//# sourceMappingURL=user-search.schemas.js.map

package/dist/users/user-search.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-search.schemas.js","sourceRoot":"","sources":["../../src/users/user-search.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,UAAU,GACX,MAAM,yBAAyB,CAAC;AAEjC,MAAM,qBAAqB,GAAG;IAC5B,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;CACtC,CAAC;AAEX,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,CAAC;IAClE,UAAU,EAAE;QACV,EAAE,EAAE,UAAU;QACd,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE;QAC1D,eAAe,EAAE,oBAAoB;QACrC,eAAe,EAAE,qBAAqB;KACvC;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,CAAC,OAAO,CAAC;IACf,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC3B,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,oBAAoB,EAAE,KAAK;QAC3B,UAAU,EAAE;YACV,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,kDAAkD;aAChE;YACD,SAAS,EAAE,UAAU;YACrB,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE;YACrC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE;SAC3C;KACF;IACD,QAAQ,EAAE;QACR,GAAG,EAAE,uBAAuB,CAAC;YAC3B,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,oBAAoB;SAC5B,CAAC;QACF,GAAG,uBAAuB;KAC3B;CACO,CAAC"}

package/dist/users/user-search.service.d.ts

@@ -0,0 +1,20 @@
+import { type PaginationMetadata } from '../community/contracts.js';
+import type { ProjectAccessRepository } from '../projects/project-access.repository.js';
+import type { UserSearchItemRecord, UserSearchRepository } from './user-search.repository.js';
+export interface UserSearchQuery {
+    page?: number;
+    pageSize?: number;
+    projectId?: string;
+    query?: string;
+}
+export interface UserSearchResult {
+    items: UserSearchItemRecord[];
+    pagination: PaginationMetadata;
+}
+export declare class UserSearchService {
+    private readonly repository;
+    private readonly accessRepository;
+    constructor(repository: UserSearchRepository, accessRepository: ProjectAccessRepository);
+    search(actorId: string, request: UserSearchQuery): UserSearchResult;
+}
+//# sourceMappingURL=user-search.service.d.ts.map

package/dist/users/user-search.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-search.service.d.ts","sourceRoot":"","sources":["../../src/users/user-search.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAGpG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AACxF,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAE9F,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,UAAU,EAAE,kBAAkB,CAAC;CAChC;AAED,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,UAAU,EAAE,oBAAoB,EAChC,gBAAgB,EAAE,uBAAuB;IAGrD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,gBAAgB;CAkC3E"}

package/dist/users/user-search.service.js

@@ -0,0 +1,41 @@
+import { pageMetadata, parsePageRequest } from '../community/contracts.js';
+import { CommunityApiError } from '../community/errors.js';
+import { requireUuid } from '../community/input.js';
+export class UserSearchService {
+    repository;
+    accessRepository;
+    constructor(repository, accessRepository) {
+        this.repository = repository;
+        this.accessRepository = accessRepository;
+    }
+    search(actorId, request) {
+        const query = request.query?.trim() ?? '';
+        if (query.includes('\0')) {
+            throw new CommunityApiError(400, 'invalid-user-query', 'query에 NUL 문자를 포함할 수 없습니다.');
+        }
+        const { page, pageSize } = parsePageRequest(request.page, request.pageSize);
+        const offset = (page - 1) * pageSize;
+        if (!Number.isSafeInteger(offset)) {
+            throw new CommunityApiError(400, 'invalid-page', 'page는 1 이상이어야 합니다.');
+        }
+        const projectId = request.projectId === undefined
+            ? undefined
+            : requireUuid(request.projectId, 'projectId');
+        if (projectId !== undefined) {
+            this.accessRepository.requireAccess(projectId, actorId, false);
+        }
+        const result = this.repository.search(`%${escapeLike(query)}%`, pageSize, offset, projectId);
+        return {
+            items: result.items,
+            pagination: pageMetadata(page, pageSize, result.totalCount),
+        };
+    }
+}
+function escapeLike(value) {
+    return value
+        .replaceAll('~', '~~')
+        .replaceAll('%', '~%')
+        .replaceAll('_', '~_')
+        .replaceAll('[', '~[');
+}
+//# sourceMappingURL=user-search.service.js.map

package/dist/users/user-search.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-search.service.js","sourceRoot":"","sources":["../../src/users/user-search.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAA2B,MAAM,2BAA2B,CAAC;AACpG,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAgBpD,MAAM,OAAO,iBAAiB;IAET;IACA;IAFnB,YACmB,UAAgC,EAChC,gBAAyC;QADzC,eAAU,GAAV,UAAU,CAAsB;QAChC,qBAAgB,GAAhB,gBAAgB,CAAyB;IACzD,CAAC;IAEG,MAAM,CAAC,OAAe,EAAE,OAAwB;QACrD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC1C,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,iBAAiB,CACzB,GAAG,EACH,oBAAoB,EACpB,4BAA4B,CAC7B,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5E,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,iBAAiB,CAAC,GAAG,EAAE,cAAc,EAAE,oBAAoB,CAAC,CAAC;QACzE,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,SAAS;YAC/C,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAChD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,gBAAgB,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CACnC,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,EACxB,QAAQ,EACR,MAAM,EACN,SAAS,CACV,CAAC;QACF,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,UAAU,EAAE,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC;SAC5D,CAAC;IACJ,CAAC;CACF;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK;SACT,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC;SACrB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC;SACrB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC;SACrB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/dist/users/user.schemas.d.ts

@@ -0,0 +1,47 @@
+export declare const userSchema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["id", "userName", "profileImageUrl"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly format: "uuid";
+        };
+        readonly userName: {
+            readonly type: "string";
+        };
+        readonly profileImageUrl: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
+    };
+};
+export declare const nullableUserSchema: {
+    readonly anyOf: readonly [{
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["id", "userName", "profileImageUrl"];
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+                readonly format: "uuid";
+            };
+            readonly userName: {
+                readonly type: "string";
+            };
+            readonly profileImageUrl: {
+                readonly anyOf: readonly [{
+                    readonly type: "string";
+                }, {
+                    readonly type: "null";
+                }];
+            };
+        };
+    }, {
+        readonly type: "null";
+    }];
+};
+//# sourceMappingURL=user.schemas.d.ts.map

package/dist/users/user.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.schemas.d.ts","sourceRoot":"","sources":["../../src/users/user.schemas.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;CASb,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;CAAqD,CAAC"}

package/dist/users/user.schemas.js

@@ -0,0 +1,13 @@
+import { nullableStringSchema, uuidSchema } from '../community/schemas.js';
+export const userSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'userName', 'profileImageUrl'],
+    properties: {
+        id: uuidSchema,
+        userName: { type: 'string' },
+        profileImageUrl: nullableStringSchema,
+    },
+};
+export const nullableUserSchema = { anyOf: [userSchema, { type: 'null' }] };
+//# sourceMappingURL=user.schemas.js.map

package/dist/users/user.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.schemas.js","sourceRoot":"","sources":["../../src/users/user.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE3E,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,iBAAiB,CAAC;IAC/C,UAAU,EAAE;QACV,EAAE,EAAE,UAAU;QACd,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC5B,eAAe,EAAE,oBAAoB;KACtC;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,KAAK,EAAE,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAW,CAAC"}

package/dist/users/user.types.d.ts

@@ -0,0 +1,6 @@
+export interface CommunityUserResponse {
+    id: string;
+    profileImageUrl: string | null;
+    userName: string;
+}
+//# sourceMappingURL=user.types.d.ts.map

package/dist/users/user.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.types.d.ts","sourceRoot":"","sources":["../../src/users/user.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/users/user.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=user.types.js.map

package/dist/users/user.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.types.js","sourceRoot":"","sources":["../../src/users/user.types.ts"],"names":[],"mappings":""}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const PACKAGE_NAME: string;
+export declare const PACKAGE_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,YAAY,QAAgB,CAAC;AAC1C,eAAO,MAAM,eAAe,QAAmB,CAAC"}

package/dist/version.js

@@ -0,0 +1,5 @@
+import { readFileSync } from 'node:fs';
+const metadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const PACKAGE_NAME = metadata.name;
+export const PACKAGE_VERSION = metadata.version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAOvC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC/C,CAAC;AAErB,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC"}

package/docs/guides/community-api-quickstart.md

@@ -0,0 +1,171 @@
+# Community API 연동 빠른 시작
+
+Community API의 업무 경로는 `/api/v1`입니다. 기존 .NET API의
+`/api/v1/fivepixels` 접두사는 사용하지 않습니다.
+
+## 1. 사용자 등록
+
+localhost에서는 회원가입이 기본 활성화됩니다. 외부 바인딩과 Docker에서는 최초
+사용자 등록 시에만 `REGISTRATION_ENABLED=true`를 명시하십시오.
+
+```bash
+curl --request POST http://127.0.0.1:3000/api/v1/auth/register \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "loginId": "frontend.dev",
+    "email": "frontend@example.com",
+    "password": "change-this-password",
+    "userName": "Frontend Developer"
+  }'
+```
+
+이 명령은 로컬 계정을 만들며 토큰은 발급하지 않습니다. `curl --request`는 사용할
+HTTP Method를, `--header`는 JSON 본문임을, `--data`는 요청 본문을 지정합니다.
+
+## 2. 로그인과 프로젝트 생성
+
+```ts
+const baseUrl = 'http://127.0.0.1:3000/api/v1';
+
+const loginResponse = await fetch(`${baseUrl}/auth/login`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    loginId: 'frontend.dev',
+    password: 'change-this-password',
+  }),
+});
+
+const login = await loginResponse.json();
+if (!loginResponse.ok || login.resultCode !== 'SUCCESS') {
+  throw new Error(login.resultMessage);
+}
+
+const accessToken = login.result.accessToken;
+const refreshToken = login.result.refreshToken;
+
+const projectResponse = await fetch(`${baseUrl}/projects`, {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${accessToken}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({ projectName: 'My Website' }),
+});
+
+const project = await projectResponse.json();
+```
+
+Access Token은 React 상태나 별도 메모리 저장소에 두는 방식을 우선하십시오. XSS가
+발생하면 브라우저의 `localStorage`에 보관한 Access/Refresh Token이 탈취될 수
+있으므로 예제에서는 자동 영구 저장을 하지 않습니다.
+
+## 3. 사용자 검색과 프로젝트 멤버 관리
+
+프로젝트에 추가할 사용자는 먼저 Fivepixels에 가입된 활성 계정이어야 합니다. 사용자 검색은
+selfdev와 동일하게 검색어 생략·공백·한 글자를 허용합니다. 생략하거나 공백이면 활성 사용자 전체를 페이지 단위로 조회하며 로그인 ID와 이메일은 반환하지 않습니다. 페이지 크기 제한과 분당 30회 요청 제한은 유지합니다.
+
+```ts
+const projectId = project.result.id;
+const usersResponse = await fetch(
+  `${baseUrl}/users?query=${encodeURIComponent('Designer')}&projectId=${projectId}`,
+  { headers: { Authorization: `Bearer ${accessToken}` } },
+);
+const users = await usersResponse.json();
+const targetUserId = users.result[0].id;
+
+const addMemberResponse = await fetch(`${baseUrl}/projects/${projectId}/members`, {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${accessToken}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({ userId: targetUserId, role: 'MEMBER' }),
+});
+
+if (!addMemberResponse.ok) {
+  const error = await addMemberResponse.json();
+  throw new Error(error.resultMessage);
+}
+
+const memberEtag = addMemberResponse.headers.get('ETag');
+if (memberEtag === null) {
+  throw new Error('멤버 응답에 ETag가 없습니다.');
+}
+```
+
+멤버 추가·역할 변경·제거는 OWNER만 실행할 수 있습니다. 역할 변경과 제거에는 가장 최근
+멤버 응답의 `ETag`를 `If-Match`로 전달해야 합니다. 멤버 목록을 다시 조회한 경우에는 대상
+항목의 `version`을 `"${member.version}"` 형태로 감싸 `If-Match` 값으로 사용합니다. OWNER 권한을 이전할 때는 새 OWNER를
+먼저 추가하거나 승격한 다음 기존 OWNER를 강등 또는 제거하십시오. 마지막 OWNER는 강등하거나
+제거할 수 없으며, Feedback 또는 Report Case 담당자는 먼저 담당 항목을 이관해야 합니다.
+
+```ts
+const promoteResponse = await fetch(
+  `${baseUrl}/projects/${projectId}/members/${targetUserId}`,
+  {
+    method: 'PATCH',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+      'If-Match': memberEtag,
+    },
+    body: JSON.stringify({ role: 'OWNER' }),
+  },
+);
+
+if (promoteResponse.status === 412) {
+  throw new Error('멤버 목록을 다시 조회한 뒤 최신 ETag로 재시도해야 합니다.');
+}
+```
+
+일반 MEMBER가 직접 탈퇴하는 전용 API와 이메일 초대 기능은 이 버전에 포함되지 않습니다.
+
+## 4. 토큰 갱신과 로그아웃
+
+```ts
+const refreshResponse = await fetch(`${baseUrl}/auth/refresh`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ refreshToken }),
+});
+
+const refreshed = await refreshResponse.json();
+// 갱신 성공 시 이전 Refresh Token을 버리고 새 값을 보관합니다.
+const nextAccessToken = refreshed.result.accessToken;
+const nextRefreshToken = refreshed.result.refreshToken;
+
+await fetch(`${baseUrl}/auth/logout`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ refreshToken: nextRefreshToken }),
+});
+```
+
+Refresh Token은 일회성으로 회전합니다. 같은 토큰을 동시에 여러 번 갱신에 사용하지
+말고, 성공 응답을 받은 즉시 기존 값을 폐기하십시오.
+
+## 5. 오류 처리
+
+업무 API의 오류도 성공 응답과 같은 봉투를 사용합니다.
+
+```json
+{
+  "resultCode": "UNAUTHORIZED",
+  "resultMessage": "인증이 필요합니다.",
+  "result": null,
+  "pagination": {
+    "page": 0,
+    "pageSize": 0,
+    "totalCount": 0,
+    "totalPages": 0,
+    "hasNext": false,
+    "hasPrevious": false
+  }
+}
+```
+
+클라이언트는 HTTP 상태코드를 먼저 확인하고 `resultCode`로 세부 원인을 분기합니다.
+401에서는 로그인 또는 갱신을 시도하고, 403은 권한이나 가입 설정을 확인하며, 409는
+현재 리소스 상태를 다시 조회하십시오. 503에는 짧은 지수 백오프를 적용할 수 있지만
+쓰기 요청을 무제한 자동 재시도해서는 안 됩니다.

package/docs/guides/feature-structure.md

@@ -0,0 +1,138 @@
+# 기능별 코드 구조
+
+## 목적과 유지하는 계약
+
+Lite API를 기능 단위로 탐색하고 수정할 수 있도록 구성합니다. selfdev 기준으로 정렬한 저장 규칙은 그대로 두고, 이번 변경은 내부 파일 배치와 업무 처리 책임만 정리합니다.
+
+- 업무 API 34개와 시스템 API 2개의 URL, HTTP Method, 요청·응답 DTO, 성공·실패 상태코드, 인증, ETag, Location 계약을 유지합니다.
+- Swagger의 업무 분류만 실제 기능에 맞춥니다. 범용 `lifecycle` 태그와 모듈은 제거합니다.
+- DB 테이블·컬럼·인덱스·제약조건, migration 001~007, `sql/fivepixels-lite-init.sql`은 변경하지 않습니다.
+- 이미지 첨부는 계속 제외합니다. 페이지 요소 태그/멘션은 이미지 첨부와 별개인 기존 기능입니다.
+- SDK 소스, selfdev 소스, npm 패키지 버전, 배포 설정은 이 리팩터링의 변경 대상이 아닙니다.
+
+엔드포인트 목록은 [README](../../README.md#api와-swagger), 요청·응답 예시는 [빠른 시작](community-api-quickstart.md), 권한·ETag·상태 전이는 [비첨부 API 계약](non-attachment-api-contract.md)을 참고하십시오.
+
+## 디렉터리와 기능 소유권
+
+```text
+src/
+  auth/                 회원가입·로그인·토큰 갱신/폐기·비밀번호
+  users/                현재 사용자 조회·프로젝트 범위 사용자 검색
+  projects/             프로젝트 생성·조회·이름/상태 변경·접근 권한
+    members/            프로젝트 멤버 조회·추가·역할 변경·제거
+  feedbacks/            피드백 생성·조회·마커·수정·상태/담당자·overview
+  report-cases/         Case 생성·조회·수정·상태/담당자·프로젝트 목록·timeline
+  replies/              답글 생성·조회·수정·삭제·시스템 답글 저장
+  page-elements/        Case/답글의 HTML 요소 태그·멘션 검증과 저장
+  community/            공통 응답·오류·ETag·입력 검증·변경 라우트 등록
+  plugins/              인증·CORS·Swagger·업무 API 조립
+  db/                   SQLite 연결·트랜잭션·마이그레이션·백업
+    migrations/         변경하지 않은 001~007 SQL
+  storage/              selfdev 호환 날짜·경로 해시 등 저장 값 변환
+  routes/               공개 시스템 API /health, /version만 유지
+  errors/               시스템 API 오류 처리
+  config/               설정·데이터 경로·JWT 키
+  cli/                  CLI 명령
+  app.ts                애플리케이션 조립
+  server.ts             프로세스 시작·수신·종료
+```
+
+기능에 필요한 파일만 둡니다. 모든 폴더에 의미 없는 Service나 Repository를 만들지는 않습니다. 예를 들어 `users/me`는 인증된 사용자 정보를 반환하므로 별도 조회 Service가 없고, `page-elements`에는 독립 HTTP API가 없습니다.
+
+| Swagger 태그 | 소유 폴더 | HTTP 작업 수 |
+|---|---|---:|
+| `auth` | `auth` | 4 |
+| `users` | `users` | 2 |
+| `projects` | `projects` | 5 |
+| `project-members` | `projects/members` | 4 |
+| `feedbacks` | `feedbacks` | 7 |
+| `report-cases` | `report-cases` | 8 |
+| `replies` | `replies` | 4 |
+| `system` | `routes` | 2 |
+
+각 기능의 라우트는 `plugins/community-api.plugin.ts`에서 `/api/v1` 아래 등록합니다. 사용자 JWT 인증은 기존 `plugins/user-auth.plugin.ts`가 담당합니다.
+
+## 파일별 책임
+
+| 파일 | 책임 |
+|---|---|
+| `*.routes.ts` | 경로·Method·인증·Schema 연결, 객체 조립, HTTP 응답·로그 처리 |
+| `*.schemas.ts` | Fastify 요청·응답 검증 및 Swagger 계약 |
+| `*.types.ts` | 해당 기능이 소유하는 내부 타입과 DTO |
+| `*.input.ts` | 기능별 입력 정규화·검증 |
+| `*.service.ts` | 생성·조회 등의 업무 규칙, Repository 호출 |
+| `*-mutation.service.ts` | 해당 기능의 수정·삭제 규칙 및 트랜잭션 조정 |
+| `*-workflow.service.ts` | 상태 전이·담당자·통합 조회 등 여러 저장소를 조정하는 처리 |
+| `*.repository.ts` | 바인딩 SQL, 행 변환, 저장·조회 |
+
+Route에는 SQL이나 권한 판단을 넣지 않습니다. Service에는 SQLite 객체나 SQL을 노출하지 않습니다. 기능 간 호출이 필요하면 소유 기능의 Repository를 사용하고, 관련 없는 SQL을 공통 저장소로 다시 모으지 않습니다.
+
+작은 범용 처리만 공통화합니다.
+
+- `projects/project-access.policy.ts`: ID 정규화, 프로젝트 접근/활성 상태, OWNER, 담당자 멤버십 검사
+- `community/etag.ts`: If-Match 파싱, 버전 비교, 응답 ETag 설정
+- `community/mutation-route.ts`: 수정·삭제의 인증/검증 순서, 응답 봉투, ETag, 204 응답, 공통 변경 로그
+- `db/transaction.ts`: 동기 쓰기/읽기 트랜잭션 실행
+
+기능별 권한 차이와 동일 값 재요청 시 버전 증가 여부는 각 Service의 기존 규칙을 유지합니다. 모든 변경을 같은 정책으로 단순화하지 않습니다.
+
+## 복합 처리와 트랜잭션
+
+기존 `LifecycleService`의 업무 처리를 다음 소유자로 분리했습니다.
+
+| 처리 | 소유 Service |
+|---|---|
+| 프로젝트 이름·상태 변경 | `ProjectMutationService` |
+| 피드백 수정·상태·담당자, overview | `FeedbackWorkflowService` |
+| Case 수정·상태·담당자, 프로젝트 Case 목록·timeline | `ReportCaseWorkflowService` |
+| 답글 수정·삭제 | `ReplyMutationService` |
+
+`TransactionRunner.write()`는 기존과 같이 `BEGIN IMMEDIATE`를 사용합니다. 권한 확인, 현재 버전 조회, 데이터 변경, 응답 데이터 조회까지 하나의 동기 트랜잭션에 포함합니다.
+
+특히 Case 상태 변경에서는 다음 작업이 모두 성공하거나 모두 롤백되어야 합니다.
+
+1. Case 상태·버전·해결 시각 변경
+2. 조건에 맞는 시스템 답글 생성
+3. 피드백 상태·버전 갱신
+4. 변경 결과 조회
+
+담당자 변경과 시스템 답글, 본문 변경과 페이지 요소 교체도 같은 트랜잭션을 유지합니다. `overview`·`timeline`의 여러 조회는 `read()`의 동일 스냅샷에서 수행합니다. 기존 생성 처리의 Repository 내부 트랜잭션도 유지합니다.
+
+**TransactionRunner와 참여 Repository에는 반드시 같은 SQLite 연결을 전달해야 합니다.** 트랜잭션 콜백은 동기 함수로 유지하고 `await`, HTTP 호출, 파일 I/O를 넣지 않습니다. 별도 연결이나 비동기 작업은 원자성을 깨뜨릴 수 있습니다.
+
+## 예외·성능·로그
+
+- 인증 실패, 접근할 수 없는 리소스의 404, 권한 부족 403, 비활성 프로젝트 등 업무 충돌 409, 버전 불일치 412, If-Match 누락 428의 기존 처리 순서를 유지합니다.
+- 입력 오류와 이미지 첨부 제외 정책의 상태코드/오류 코드는 기존 계약을 따릅니다.
+- 답글 생성이나 마지막 피드백 UPDATE가 실패해도 Case·답글·피드백 중 일부만 저장되지 않아야 합니다.
+- SQL, 조회 순서, 페이지 제한, 인덱스를 이 구조 변경으로 추가하거나 변경하지 않습니다. 새로운 DB 연결이나 worker도 만들지 않습니다. 성능 향상을 주장하는 변경이 아니며 실제 부하 성능은 별도 측정 대상입니다.
+- 기존 Fastify 요청 로그와 기능별 생성/변경 로그를 유지합니다. 변경 로그는 actorId, 대상 ID, Method, 결과 version으로 추적합니다. 토큰, 비밀번호, 본문, SQL 내부 오류를 응답이나 로그에 추가하지 않습니다.
+
+## 새 기능 또는 변경을 넣는 순서
+
+1. 승인된 API 계약과 기능 소유자를 정합니다. 관련 기능 폴더에 Schema/DTO를 먼저 배치합니다.
+2. Repository에 SQL을 두고, Service에 권한·업무 규칙을 둡니다. 여러 테이블 변경은 소유 기능의 Workflow/Mutation Service에서 조정합니다.
+3. 해당 기능의 `*.routes.ts`에 등록하고 Swagger 태그를 맞춥니다. 신규 기능인 경우에만 업무 API plugin에 등록 함수를 추가합니다.
+4. 성공뿐 아니라 인증, 권한, 잘못된 입력, 리소스 누락, 오래된 ETag, 동일 값 재요청, 마지막 단계 실패 시 롤백을 검증합니다.
+5. 순환 런타임 import를 만들지 않습니다. 타입만 필요하면 `import type`을 사용하고, 공통 Schema가 필요하면 실제 소유 기능 또는 공통 모듈에서 가져옵니다.
+
+## 검증과 배포 주의
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run test:storage-interop
+npm pack --dry-run
+```
+
+순서대로 타입 검사, 정적 검사, 전체 테스트, 실행 파일 빌드, .NET과 저장 값/비밀번호 상호 호환 검사, npm 포함 파일 검사를 수행합니다. 상호 호환 검사는 로컬 .NET SDK가 필요하며 실제 SQL Server 연결이나 SDK 브라우저 E2E 검사는 아닙니다.
+
+`test/feature-structure.test.ts`는 리팩터링 전 HTTP 작업 계약 해시(태그 제외), 기존 SQL 해시, 폐기한 lifecycle 모듈의 부재, 런타임 import 순환, 트랜잭션 오류 후 롤백을 확인합니다. 기준값은 `test/fixtures/feature-refactor-contract.json`에 있습니다. 실제 API/DB 변경이 승인된 경우에만 예상 차이를 검토하고 해당 기준값을 갱신하십시오. 테스트를 통과시키려고 일괄 덮어쓰면 안 됩니다. 이미 적용된 migration SQL은 수정하지 않습니다.
+
+`test/lifecycle.test.ts`는 기능을 가로지르는 기존 업무 계약 회귀 테스트이므로 파일명을 유지했습니다. 이 테스트에는 시스템 답글 실패, 마지막 피드백 갱신 실패, 담당자 시스템 답글 실패의 원자성 검사가 포함됩니다.
+
+이 리팩터링 자체는 새 migration이 없으므로 DB 재생성·DDL 재실행이 필요하지 않습니다. 다만 기존 개발 브랜치의 미적용 migration 006·007이 있다면 배포 시 별도의 기존 마이그레이션 절차가 수행되므로 상태와 백업을 먼저 확인해야 합니다.
+
+배포할 때는 `npm run build`로 이전 경로의 dist 생성물을 정리한 완전한 빌드를 사용합니다. 소스만 복사하거나 이전 dist와 합치지 않습니다. 이번 구조 변경만 되돌리는 경우 이전 소스/빌드를 복원하고 재검증하며, 별도 DB migration을 되돌리는 작업과 혼동하지 않습니다. 실제 서비스 재시작·배포는 별도 승인이 필요합니다.

package/docs/guides/independent-cli.md

@@ -0,0 +1,73 @@
+# 독립 CLI와 Lite 공개 런타임
+
+## 현재 구조
+
+`@fivepixels-js/cli` 0.1.0은 별도 `fivepixels-cli` Git 프로젝트에서 관리합니다. Lite API를 모노레포로 옮기지 않습니다. CLI는 `@fivepixels-js/lite-api` 0.2.1을 정확한 npm 의존성으로 사용합니다.
+
+사용자는 새 `fivepixels` 명령을 사용할 수 있고, 기존 `fivepixels-lite-api` 명령과 Docker의 `node dist/cli/index.js start` 진입점도 유지합니다. 새 CLI의 현재 범위는 Lite의 init/start/status/backup/migrate와 도움말·버전뿐입니다.
+
+CLI는 명령·사용자 안내·호환성 검사를 소유합니다. Lite는 설정 우선순위, 보안 검증, JWT 키, 서버 시작·종료, DB·마이그레이션·백업을 계속 소유합니다. 명령 처리 코드가 API에 남는 것은 하위 실행 도구와 기존 설치를 보존하기 위한 의도된 구조입니다.
+
+## 라이선스 경계
+
+Lite 서버 패키지 `@fivepixels-js/lite-api`는 [Elastic License 2.0](../../LICENSE)인 source-available 소프트웨어입니다. 공개 runtime과 기존 `fivepixels-lite-api` 명령도 서버 패키지의 ELv2를 따릅니다.
+
+독립 `@fivepixels-js/cli` 자체 코드는 Apache-2.0입니다. 서버를 npm 의존성으로 설치하거나 같은 Node 프로세스에서 호출하더라도 서버의 라이선스는 바뀌지 않습니다. 제3자에게 서버의 상당한 기능을 호스팅·관리형 서비스로 제공하는 제한 등은 서버 라이선스 전문을 확인하십시오. SDK와 다른 API 저장소의 실제 라이선스 적용 여부는 각 저장소에서 별도로 확인합니다.
+
+## 공개 패키지 계약
+
+- `@fivepixels-js/lite-api/runtime`: ESM 함수 `runRuntimeCommand(args: string[]): Promise<number>`
+- `@fivepixels-js/lite-api/package.json`: 버전·이름 확인용 공개 메타데이터
+- `fivepixels-lite-api`: 기존 bin 명령
+
+기존 공개 HTTP 계약은 변경하지 않습니다. 패키지 내부 src/dist 파일은 독립 CLI의 연동 계약이 아니며 export하지 않습니다.
+
+```ts
+import { runRuntimeCommand } from '@fivepixels-js/lite-api/runtime';
+
+process.exitCode = await runRuntimeCommand(process.argv.slice(2));
+```
+
+위 코드는 같은 Node 프로세스에서 명령을 수행하는 진입점 예시입니다. 모듈 import만으로는 설정 검증, DB 연결, JWT 파일 생성, 서버 시작이나 signal handler 등록이 발생하지 않습니다.
+
+함수를 호출하면 기존 Lite CLI로 위임하며 process.env, 현재 작업 디렉터리, 기존 표준 출력/오류와 종료 코드 0/1/2를 유지합니다. 이 API는 CLI 프로세스 진입점용이지 HTTP 요청마다 호출하는 서버 관리 API가 아닙니다.
+
+`start`의 Promise는 서버가 수신을 시작한 뒤 반환됩니다. 이벤트 루프와 기존 SIGINT/SIGTERM 핸들러가 서버를 유지·종료하므로 반환 직후 `process.exit()`를 호출하지 마십시오. 한 프로세스에서 여러 서버를 중복 시작하지 않습니다. 독립 CLI는 별도 서버 자식 프로세스나 signal forwarding을 추가하지 않습니다.
+
+## 호환성과 검증
+
+독립 CLI는 명령 실행 전에 패키지 이름·정확한 Lite 버전을 확인한 뒤 공개 runtime 함수를 가져옵니다. 버전이 같아도 runtime export가 없는 과거 개발 tarball이면 거부합니다. 같은 개발 버전 0.2.1의 파일을 임의로 혼용하지 않습니다.
+
+현재 API 프로젝트의 테스트는 공개 export와 기존 bin을 확인하고, import만으로 데이터나 signal handler가 생기지 않는지 검증합니다. 독립 CLI의 패키지 테스트에서는 두 실제 tarball을 임시 위치에 설치하여 다음을 확인합니다.
+
+- help/version/status의 불필요한 DB 미생성과 외부 바인딩 보안 거부
+- init/start/health/status/온라인 백업/migrate
+- 백업 integrity_check·foreign_key_check 및 미덮어쓰기
+- 기존 Lite 명령과 새 CLI의 동일 DB 사용
+- 실제 POSIX SIGINT/SIGTERM 종료 코드 0과 포트 해제
+
+이 검증은 실제 SDK·selfdev·SQL Server E2E나 운영 배포 검증을 의미하지 않습니다. Node 22·24 및 Linux/macOS/Windows CI 구성과 실제 실행된 환경도 구분합니다.
+
+## 패키징과 배포 경계
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm test
+npm pack
+```
+
+각 명령은 의존성 설치, 타입 검사, 정적 검사, 테스트, 빌드된 로컬 tarball 생성을 수행합니다. npm publish는 실행하지 않습니다.
+
+소스 기반 개발에서는 생성한 Lite tarball을 독립 CLI의 `setup:local`로 공급합니다. 공개된 버전은 CLI의 `fetch:runtime`으로 registry에서 준비할 수 있습니다. CLI의 공개 manifest는 Lite 0.2.1 의존성을 유지하며, 개발 lockfile은 실제 tarball의 SHA-512를 고정합니다. API 소스나 포함 문서 변경 후 tarball 체크섬이 달라지면 CLI 쪽에서 변경을 검토하고 명시적으로 lock을 갱신한 뒤 다시 검증해야 합니다. 공개한 동일 이름·버전의 내용을 교체하지 않으며 공개 후 변경은 새 버전으로 배포합니다.
+
+정식 CLI 배포에는 이 공개 runtime이 포함된 Lite의 선행 공개가 필요합니다. 실제 scope/registry 권한과 registry를 통한 설치는 별도 승인·검증 대상입니다. API와 CLI의 비공개 GitHub 저장소는 각각 생성·연결되어 있지만, Git commit/push, npm 공개와 운영 배포는 별도로 승인된 단계에서 수행합니다.
+
+DB 스키마·단일 DDL·migration SQL은 이 분리로 바뀌지 않습니다. 새 CLI를 쓰기 위해 DB를 재생성하지 않습니다. 다만 기존 pending migration은 실제 init/start/migrate 실행 시 기존 규칙대로 적용될 수 있습니다.
+
+문제가 생기면 기존 Lite 명령으로 운영할 수 있습니다. 이번 CLI 분리만 롤백할 때는 이전 소스/빌드 또는 기존 명령을 사용하며 DB 복원·DDL 재실행은 하지 않습니다.
+
+## 미래 계획과의 구분
+
+`docs/plans/one-command-self-hosted-cli.md`의 Docker·PostgreSQL·Basic API·selfdev 확장 등은 현재 구현이 아닙니다. 해당 문서의 모노레포 구성은 이전 초안이며, 현재 독립 CLI 결정에 따라 자동 적용하지 않습니다. Docker 관리, stop/logs/restore/upgrade와 버전 선택을 추가하려면 별도 범위·계약이 필요합니다.