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 기반 생성물이며 직접 수정하지 않는다.

빠른 시작

의존성을 가져온다.

dart pub get

테스트를 실행한다.

dart test

예제 코드를 실행한다.

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