> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Project History Failures 컬렉션

`projectHistoryFailures`에는 project-history가 기록 업데이트를 처리하지 못했거나 재동기화를 시작한 프로젝트마다 문서 하나가 저장됩니다. 처리가 성공하면 문서는 곧바로 다시 삭제됩니다. project-history가 `services/project-history/app/js/ErrorRecorder.js`에서 쓰며, 타입은 `services/project-history/app/js/mongo-types.ts:3-24`에 있습니다. Web에도 이에 대한 Mongoose 스키마가 있지만(`services/web/app/src/models/ProjectHistoryFailure.mjs:5-19`) 그 모델을 사용하는 Web 코드는 없습니다.

#### 필드

| 필드 | 타입 | 의미 | 출처 |
| - | - | - | - |
| `_id` | ObjectId | upsert로 생성됩니다. | `ErrorRecorder.js:45-60` |
| `project_id` | String | 프로젝트 ID로, ObjectId가 아니라 문자열로 저장됩니다. | `ErrorRecorder.js:46`, `mongo-types.ts:5` |
| `error` | String | 마지막 오류로, `error.toString()` 형태입니다. | `ErrorRecorder.js:37` |
| `stack` | String | 마지막 오류의 스택. | `ErrorRecorder.js:38` |
| `queueSize` | Number | 마지막 오류 시점에 프로젝트의 Redis 큐에서 대기 중이던 업데이트 수(`services/project-history/app/js/UpdatesProcessor.js:375`). 오류가 재동기화 시작에서 발생했다면 `-1`입니다(`services/project-history/app/js/SyncManager.js:75`, `96`). | `ErrorRecorder.js:36` |
| `ts` | Date | 마지막 오류 시각. | `ErrorRecorder.js:39` |
| `attempts` | Number | 문서가 생성된 이후 기록된 오류 수. | `ErrorRecorder.js:49` |
| `history` | Array of Object | 최근 이벤트 10개(최신순): 오류 기록 `{ queueSize, error, stack, ts }`와 재동기화 시작 `{ resyncStartedAt }`. | `ErrorRecorder.js:50-56`, `92-98` |
| `resyncStartedAt` | Date | 마지막 재동기화가 시작된 시각. | `ErrorRecorder.js:90` |
| `resyncAttempts` | Number | 문서가 생성된 이후 시작된 재동기화 수. | `ErrorRecorder.js:91` |
| `forceDebug` | Boolean | project-history `POST /project/:project_id/force`가 설정합니다(`?clear=true`는 `false`로 설정). `true`인 동안에는 저장된 chunk의 ops-out-of-order 오류를 로그에 남기고 무시합니다(`UpdatesProcessor.js:574-592`). | `ErrorRecorder.js:72-82` |
| `requestCount` | Number | Web 스키마에 있습니다(`ProjectHistoryFailure.mjs:16`). `ErrorRecorder.getLastFailure`만 이를 증가시키며, 그 함수를 호출하는 곳은 없습니다. | `ErrorRecorder.js:131-138` |

#### 쓰는 곳

| 코드 | 하는 일 |
| - | - |
| `services/project-history/app/js/ErrorRecorder.js:34-66` | `record`: 오류를 upsert하고, `attempts`를 1 늘리고, `history`에 항목을 추가합니다. 프로젝트의 업데이트 처리가 실패할 때(`UpdatesProcessor.js:91`, `169`, `242`, `293`, `345`)와 재동기화를 시작할 수 없을 때(`SyncManager.js:75`, `96`) 호출합니다. |
| `ErrorRecorder.js:86-102` | `recordSyncStart`: 재동기화가 시작될 때마다 upsert하고, `resyncStartedAt`를 설정하고, `resyncAttempts`를 1 늘리고, `history`에 항목을 추가합니다(`SyncManager.js:104`). |
| `ErrorRecorder.js:68-70` | `clearError`: flush가 성공한 뒤(`UpdatesProcessor.js:101`, `194`, `259`, `355`), project-history `DELETE /project/:project_id`에서(`services/project-history/app/js/HttpController.js:1386`), 그리고 재시도 중 잘못된 프로젝트 ID가 있을 때(`services/project-history/app/js/RetryManager.js:161`) 문서를 삭제합니다. |
| `ErrorRecorder.js:72-82` | `setForceDebug`: `forceDebug`를 upsert합니다(`HttpController.js:1016-1035`, 경로는 `services/project-history/app/js/Router.js:82`). |
| `ErrorRecorder.js:109-119` | `cloneFailure`: 문서를 다른 프로젝트로 복사합니다. project-history `POST /project/:project_id/clone`용이며(`HttpController.js:135`), Web에는 이를 호출하는 코드가 없습니다. |

#### 읽는 곳

| 코드 | 하는 일 |
| - | - |
| `RetryManager.js:113-126` | 재시도 cron 작업을 위해 모든 실패를 불러옵니다(`server-ce/config/crontab-history`, project-history `POST /retry/failures`). soft 작업은 큐를 다시 처리하고, hard 작업은 프로젝트를 재동기화합니다. `resyncAttempts`가 1 이상이고 오류가 실행 중인 재동기화가 아니면 hard 재동기화로 실행합니다(`RetryManager.js:30-31`, `35-56`, `106-111`). |
| `services/project-history/app/js/FlushManager.js:73-82` | 모든 프로젝트를 flush할 때 실패가 있는 프로젝트는 건너뜁니다. |
| `UpdatesProcessor.js:578-592` | `forceDebug`를 읽습니다. |
| `ErrorRecorder.js:124-129`, `140-145` | `getFailureRecord`와 `getFailedProjects`: `GET /project/:project_id/debug-info`(`HttpController.js:571`)와 `GET /status/failures`, `GET /status/failures-full`(`Router.js:88-90`)에서 사용합니다. |

#### 인덱스

| 이름 | 키 | 옵션 | 마이그레이션 |
| - | - | - | - |
| `project_id_1` | `{ project_id: 1 }` | | `tools/migrations/20190912145018_create_projectHistoryFailures_indexes.mjs` |

#### 참고

* 문서는 프로젝트의 flush가 성공하거나 프로젝트가 삭제될 때까지 남습니다(위의 `clearError`). 따라서 각 문서는 마지막 flush나 재동기화가 아직 성공하지 않은 프로젝트를 나타냅니다.
* `OError:`로 시작하는 오류 문자열은 `Error:`로 반환됩니다(`ErrorRecorder.js:18-26`). 저장된 값은 바뀌지 않습니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.