# dart-app-core

`dart-app-core`는 Dart 애플리케이션에서 반복해서 쓰는 공통 기능을 모아둔 라이브러리 패키지다. 패키지 이름은 `dart_framework`이며, 앱 초기화, 플랫폼별 I/O 추상화, 문자셋 변환, 자막 파싱, Slack 전송, 간단한 암호화/유틸리티 기능을 제공한다.

## 현재 상태

- Dart SDK `>=3.2.3 <4.0.0`을 기준으로 한다.
- `lib/dart_framework.dart`가 주요 공개 API 진입점이다.
- 플랫폼 분기는 `lib/platform/platform_stub.dart`, `lib/platform/platform_io.dart`, `lib/platform/platform_web.dart`의 조건부 import 구조를 사용한다.
- `lib/charset/**`에는 EUC-KR, EUC-JP, GBK, Shift-JIS, UTF 계열 문자셋 처리 코드와 매핑 테이블이 있다.
- `lib/subtitle/**`에는 SMI, SRT, VTT 파서가 있다.
- `lib/utils/slack/**`에는 Slack message 전송 helper가 있다.
- `*.g.dart` 파일은 `json_serializable` 기반 생성물이며 직접 수정하지 않는다.

## 빠른 시작

의존성을 가져온다.

```bash
dart pub get
```

테스트를 실행한다.

```bash
dart test
```

예제 코드를 실행한다.

```bash
dart run example/dart_framework_example.dart
```

## 주요 명령

| 목적 | 명령 | 비고 |
|------|------|------|
| 의존성 설치 | `dart pub get` | `pubspec.yaml` 기준으로 패키지를 가져온다. |
| 테스트 실행 | `dart test` | `test/` 아래 테스트를 실행한다. |
| 예제 실행 | `dart run example/dart_framework_example.dart` | 공개 API 사용 예시를 확인한다. |
| 생성 코드 갱신 | `dart run build_runner build` | `json_serializable` 생성물이 바뀔 때만 실행한다. |

## 구조

| 경로 | 역할 |
|------|------|
| `lib/dart_framework.dart` | 패키지 공개 API 진입점 |
| `lib/core/` | 애플리케이션, 앱 데이터, 예외 관리 기본 구조 |
| `lib/platform/` | I/O, Web, stub 플랫폼 분기와 process/isolate helper |
| `lib/charset/` | 문자셋 변환과 코드 페이지 매핑 |
| `lib/subtitle/` | 자막 파서 |
| `lib/utils/` | path, string, system, startup, Slack helper |
| `lib/encrypt/` | 암호화 helper |
| `lib/model/`, `lib/data/` | 공유 데이터 모델과 생성 코드 |
| `test/` | 패키지 테스트 |
| `example/` | 사용 예시 |
| `agent-ops/` | AI agent 작업 규칙과 공통 skill |

## 작업 맥락

- 작업 전 `AGENTS.md`와 `agent-ops/rules/project/rules.md`를 읽는다.
- 변경 경로에 맞는 domain rule이 있으면 `agent-ops/rules/project/domain/*/rules.md`를 먼저 확인한다.
- `lib/charset/**`의 문자셋 테이블과 매핑 파일은 대량 데이터 성격이 있으므로 불필요한 포맷 변경을 피한다.
- 공개 API를 바꾸면 `lib/dart_framework.dart`와 관련 top-level export 파일을 함께 확인한다.
- 생성 파일인 `*.g.dart`는 소스 변경 후 build runner로 갱신하며 손으로 고치지 않는다.

## 개발 흐름

1. 변경할 경로의 domain rule을 확인한다.
2. 공개 API, 플랫폼 분기, 생성 코드 여부를 먼저 판단한다.
3. 변경 범위에 맞는 최소 테스트를 실행한다.
4. 필요한 경우 `dart test`로 전체 테스트를 확인한다.

## 참고 문서

- `AGENTS.md`
- `agent-ops/rules/project/rules.md`
- `pubspec.yaml`
- `CHANGELOG.md`