80 lines
3.2 KiB
Markdown
80 lines
3.2 KiB
Markdown
# 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`
|