@walwal-harness/cli 4.0.0-alpha.2 → 4.0.0-alpha.21

package/skills/generator-frontend-flutter/references/api-layer-pattern.md

@@ -1,233 +0,0 @@
----
-docmeta:
-  id: api-layer-pattern
-  title: API Layer Pattern (integrated_data_layer)
-  type: output
-  createdAt: 2026-04-09T00:00:00Z
-  updatedAt: 2026-04-09T00:00:00Z
-  source:
-    producer: agent
-    skillId: harness-generator-frontend-flutter
-  inputs:
-    - documentId: clue-fe-flutter-api-layer
-      uri: ../../../../../moon_web/clue-fe-flutter.skill
-      relation: output-from
-      sections:
-        - sourceRange:
-            startLine: 1
-            endLine: 187
-          targetRange:
-            startLine: 32
-            endLine: 205
-  tags:
-    - flutter
-    - retrofit
-    - json-serializable
-    - integrated-data-layer
----
-
-# API Layer Pattern (integrated_data_layer)
-
-하네스 Flutter Generator는 `api-contract.json` 을 **Source of Truth** 로 삼아
-`integrated_data_layer` 하위에 Dart 타입을 1:1 생성한다.
-
-## 디렉토리 구조
-
-```
-integrated_data_layer/
-├── lib/
-│   ├── 1_repositories/              # Repository (비즈니스 로직 래퍼)
-│   │   ├── ac_repository.dart
-│   │   ├── visitor_repository.dart
-│   │   ├── s3_repository.dart
-│   │   ├── oauth_repository.dart
-│   │   └── reservation_repository.dart
-│   ├── 2_data_sources/
-│   │   ├── remote/
-│   │   │   ├── rest_api.dart           # 모든 Retrofit 엔드포인트
-│   │   │   ├── rest_provider.dart      # Dio/RestClient Provider
-│   │   │   ├── request/body/           # Request Body 클래스
-│   │   │   └── response/
-│   │   │       └── abstract/          # 베이스 응답 (ClueResponseImpl 등)
-│   │   └── local/
-│   └── 3_others/
-│       ├── enum/
-│       └── extension/
-├── test/                               # lib/ 미러 구조
-│   ├── 1_repositories/
-│   ├── 2_data_sources/remote/request/body/
-│   └── 2_data_sources/remote/response/
-└── data_layer.dart                     # 진입점 (dataLayer Provider)
-```
-
-## 1. api-contract.json → Request Body 변환
-
-api-contract.json의 요청 스키마를 `@JsonSerializable(includeIfNull: false)`
-클래스로 1:1 매핑한다. **필수 지시가 없으면 모든 필드 Nullable.**
-
-```dart
-// lib/2_data_sources/remote/request/body/example_body.dart
-import 'package:json_annotation/json_annotation.dart';
-
-part 'example_body.g.dart';
-
-@JsonSerializable(includeIfNull: false)  // ★ 필수
-class ExampleBody {
-  final String? name;       // ★ Nullable 기본
-  final int? placeId;
-  final String? description;
-
-  const ExampleBody({
-    this.name,
-    this.placeId,
-    this.description,
-  });
-
-  factory ExampleBody.fromJson(Map<String, dynamic> json) =>
-      _$ExampleBodyFromJson(json);
-  Map<String, dynamic> toJson() => _$ExampleBodyToJson(this);
-}
-```
-
-## 2. Response 변환
-
-응답 베이스 클래스 계층:
-- `ClueResponseImpl<T>` — 단일 데이터 (code, data, errors)
-- `ClueResponseListImpl<T>` — 목록 (code, data, errors, totalCount)
-- `VisitorResponseImpl<T>` — Visitor 서버 전용
-
-```dart
-// lib/2_data_sources/remote/response/example_response.dart
-import 'package:integrated_data_layer/2_data_sources/remote/response/abstract/clue/clue_response_impl.dart';
-import 'package:json_annotation/json_annotation.dart';
-
-part 'example_response.g.dart';
-
-@JsonSerializable(explicitToJson: true)
-class ExampleResponse extends ClueResponseImpl<ExampleResponseData> {
-  const ExampleResponse({
-    required super.code,
-    required super.data,
-    required super.errors,
-  });
-
-  factory ExampleResponse.fromJson(Map<String, dynamic> json) =>
-      _$ExampleResponseFromJson(json);
-  Map<String, dynamic> toJson() => _$ExampleResponseToJson(this);
-}
-
-@JsonSerializable(explicitToJson: true)
-class ExampleResponseData {
-  final int? id;          // ★ Nullable 기본
-  final String? name;
-
-  const ExampleResponseData({this.id, this.name});
-
-  factory ExampleResponseData.fromJson(Map<String, dynamic> json) =>
-      _$ExampleResponseDataFromJson(json);
-  Map<String, dynamic> toJson() => _$ExampleResponseDataToJson(this);
-}
-```
-
-**기존 응답 재사용 원칙**: api-contract.json 의 서로 다른 엔드포인트가
-동일한 응답 구조를 가지면 새 Response 클래스를 만들지 않는다.
-
-## 3. rest_api.dart 엔드포인트 추가
-
-```dart
-// rest_api.dart 내부 — RestClient 클래스에 추가
-@GET("/examples/{exampleId}")
-Future<ExampleResponse> getExample(
-  @Path("exampleId") int exampleId,
-);
-
-@POST("/examples")
-Future<ExampleResponse> createExample(
-  @Body() ExampleBody requestBody,
-);
-
-@PUT("/examples/{exampleId}")
-Future<ExampleResponse> updateExample(
-  @Path("exampleId") int exampleId,
-  @Body() ExampleBody requestBody,
-);
-
-@DELETE("/examples/{exampleId}")
-Future<ClueDefaultResponse> deleteExample(
-  @Path("exampleId") int exampleId,
-);
-```
-
-api-contract.json의 path, method, param 위치를 **그대로** 옮긴다.
-경로 변수 추가/제거 금지 — 계약이 Source of Truth.
-
-## 4. Repository 래퍼 추가
-
-```dart
-// 1_repositories/ac_repository.dart 내부에 메서드 추가
-Future<ExampleResponse> getExample({required int exampleId}) {
-  return _restClient.getExample(exampleId);
-}
-```
-
-Repository는 **순수 래퍼** — 비즈니스 로직 없이 Retrofit 호출을 전달만 한다.
-도메인 분기, 에러 매핑은 VM 계층에서 수행.
-
-## 5. 호출 패턴 (VM에서)
-
-```dart
-// VM 내부
-final result = await ref.read(dataLayer).ac.getExample(exampleId: 123);
-if (result.code == 200) {
-  // 성공 처리
-}
-```
-
-## 6. TC 작성 (필수)
-
-**모든 Request Body, Response에 왕복 테스트 필수.**
-Evaluator가 test 디렉토리를 점검한다.
-
-```dart
-// test/2_data_sources/remote/request/body/example_body_test.dart
-import 'dart:convert';
-import 'package:flutter_test/flutter_test.dart';
-import 'package:integrated_data_layer/2_data_sources/remote/request/body/example_body.dart';
-
-void main() {
-  group("example body test", () {
-    test("/fromJson & toJson", () {
-      ExampleBody body1 = const ExampleBody(
-        name: 'test',
-        placeId: 1,
-      );
-
-      ExampleBody body2 = ExampleBody.fromJson(body1.toJson());
-
-      expect(body1.name, 'test');
-      expect(body1.placeId, 1);
-
-      var body1Data = jsonEncode(body1.toJson());
-      var body2Data = jsonEncode(body2.toJson());
-      expect(body1Data == body2Data, true);
-    });
-
-    test("/null fields excluded", () {
-      ExampleBody body = const ExampleBody(name: 'test');
-      var json = body.toJson();
-      expect(json.containsKey('placeId'), false);  // includeIfNull: false 검증
-    });
-  });
-}
-```
-
-## 7. 코드 생성
-
-모든 Request/Response 파일 추가/수정 후 **반드시** 실행:
-
-```bash
-cd <integrated_data_layer 경로>
-flutter pub run build_runner build --delete-conflicting-outputs
-```
-
-생성된 `*.g.dart` 파일은 커밋한다 (CI에서 재생성하지 않음).

package/skills/generator-frontend-flutter/references/flutter-web-pattern.md

@@ -1,273 +0,0 @@
----
-docmeta:
-  id: flutter-web-pattern
-  title: Flutter Web 패턴 — fe_target=web 전용
-  type: output
-  createdAt: 2026-04-09T00:00:00Z
-  updatedAt: 2026-04-09T00:00:00Z
-  source:
-    producer: agent
-    skillId: harness-generator-frontend-flutter
-  inputs:
-    - documentId: harness-generator-frontend-flutter-skill
-      uri: ../SKILL.md
-      relation: output-from
-      sections:
-        - sourceRange:
-            startLine: 56
-            endLine: 90
-          targetRange:
-            startLine: 21
-            endLine: 240
-    - documentId: flutter-anti-patterns
-      uri: ./anti-patterns.md
-      relation: output-from
-      sections:
-        - sourceRange:
-            startLine: 22
-            endLine: 75
-          targetRange:
-            startLine: 90
-            endLine: 165
-  tags:
-    - flutter
-    - flutter-web
-    - dart-web
-    - go-router
----
-
-# Flutter Web 패턴 (`fe_target = web` 전용)
-
-`pipeline.json.fe_target == "web"` 일 때만 적용. Mobile/Desktop 타겟에서는 이 문서의 규칙을 무시한다.
-
-## 1. 프로젝트 활성화
-
-기존 Flutter 프로젝트에 Web 타겟이 없으면:
-
-```bash
-flutter config --enable-web
-flutter create --platforms=web .
-```
-
-`web/index.html`, `web/manifest.json`, `web/favicon.png`, `web/icons/` 가 생성된다.
-
-## 2. 빌드 및 개발 서버
-
-| 명령 | 용도 |
-|------|------|
-| `flutter run -d chrome` | 개발 서버 (HMR 포함) |
-| `flutter run -d chrome --web-port 8080` | 포트 고정 |
-| `flutter build web --release` | 프로덕션 빌드 (`build/web/`) |
-| `flutter build web --release --web-renderer canvaskit` | CanvasKit 렌더러 (성능 우선) |
-| `flutter build web --release --web-renderer html` | HTML 렌더러 (호환성 우선, 작은 번들) |
-
-> **렌더러 선택**: 모바일 사파리 호환성이 중요하면 `html`, 데스크톱/Chrome 중심이면 `canvaskit` (또는 auto).
-
-## 3. 라우팅 — `go_router` 권장
-
-URL 동기화 + 브라우저 history 지원을 위해 `go_router` 사용.
-
-```yaml
-# pubspec.yaml
-dependencies:
-  go_router: ^14.0.0
-```
-
-```dart
-// lib/router/app_router.dart
-import 'package:go_router/go_router.dart';
-
-final pAppRouterProvider = Provider<GoRouter>((ref) {
-  return GoRouter(
-    initialLocation: '/',
-    routes: [
-      GoRoute(path: '/', builder: (ctx, state) => const HomePage()),
-      GoRoute(path: '/login', builder: (ctx, state) => const LoginPage()),
-      GoRoute(
-        path: '/items/:id',
-        builder: (ctx, state) => ItemPage(id: state.pathParameters['id']!),
-      ),
-    ],
-  );
-});
-```
-
-```dart
-// main.dart
-class App extends ConsumerWidget {
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final router = ref.watch(pAppRouterProvider);
-    return MaterialApp.router(
-      routerConfig: router,
-      // ...
-    );
-  }
-}
-```
-
-**Hash routing vs Path routing**:
-- 기본은 hash routing (`/#/login`)
-- Path routing 으로 바꾸려면 `web/index.html` 의 `<base href="/">` 설정 + 서버 fallback (모든 경로 → `index.html`)
-
-## 4. JS Interop (필요할 때만)
-
-크로스플랫폼 코드를 우선하되, Web 전용 API 가 필요하면 `package:web` + `dart:js_interop` 사용.
-
-```dart
-import 'package:web/web.dart' as web;
-import 'dart:js_interop';
-
-void copyToClipboard(String text) {
-  web.window.navigator.clipboard.writeText(text.toJS);
-}
-
-String getUserAgent() => web.window.navigator.userAgent;
-```
-
-**Conditional import 패턴** (cross-platform 코드를 web/io 로 분기):
-
-```dart
-// platform_helper.dart (interface)
-abstract class PlatformHelper {
-  String get platformName;
-}
-
-PlatformHelper getPlatformHelper() => throw UnimplementedError();
-```
-
-```dart
-// platform_helper_web.dart
-import 'package:web/web.dart' as web;
-import 'platform_helper.dart';
-
-class WebPlatformHelper implements PlatformHelper {
-  @override
-  String get platformName => 'web (${web.window.navigator.userAgent})';
-}
-
-PlatformHelper getPlatformHelper() => WebPlatformHelper();
-```
-
-```dart
-// platform_helper_io.dart
-import 'dart:io';
-import 'platform_helper.dart';
-
-class IoPlatformHelper implements PlatformHelper {
-  @override
-  String get platformName => 'io (${Platform.operatingSystem})';
-}
-
-PlatformHelper getPlatformHelper() => IoPlatformHelper();
-```
-
-```dart
-// 사용처
-import 'platform_helper.dart'
-  if (dart.library.html) 'platform_helper_web.dart'
-  if (dart.library.io) 'platform_helper_io.dart';
-
-final helper = getPlatformHelper();
-print(helper.platformName);
-```
-
-## 5. CORS 와 백엔드 연동
-
-Flutter Web 은 브라우저에서 실행되므로 백엔드 API 호출 시 **CORS** 가 적용된다.
-
-- 개발 단계: 백엔드 Gateway 의 `Access-Control-Allow-Origin` 에 `http://localhost:8080` (또는 `*`) 추가
-- 프로덕션: 동일 origin 또는 명시적 CORS 화이트리스트
-- API 키/인증 토큰은 **HttpOnly cookie** 또는 메모리 보관 (localStorage 는 XSS 위험)
-
-`Dio` 인터셉터로 CSRF 토큰 등을 헤더에 추가:
-
-```dart
-final dio = Dio(BaseOptions(
-  baseUrl: 'https://api.example.com',
-  headers: {'Content-Type': 'application/json'},
-));
-
-dio.interceptors.add(InterceptorsWrapper(
-  onRequest: (options, handler) {
-    final token = ref.read(pAuthProvider).accessToken;
-    if (token != null) {
-      options.headers['Authorization'] = 'Bearer $token';
-    }
-    return handler.next(options);
-  },
-));
-```
-
-## 6. SEO / Meta Tags
-
-`web/index.html` 의 `<head>` 에 SEO 메타 태그 추가:
-
-```html
-<meta name="description" content="Suprema CLUe — Smart Access Control">
-<meta property="og:title" content="CLUe">
-<meta property="og:description" content="...">
-<meta property="og:image" content="/icons/og-image.png">
-<link rel="canonical" href="https://app.example.com">
-```
-
-> SPA 의 SEO 한계: Flutter Web 은 client-side rendering 이므로 검색엔진이 동적 콘텐츠를 인덱싱하지 못할 수 있다. SSR 이 필요하면 Next.js + REST API 패턴을 고려.
-
-## 7. 자산 최적화
-
-- 이미지: `assets/images/` 에 두고 `pubspec.yaml` 의 `flutter.assets` 에 등록
-- 폰트: `web/fonts/` 또는 `assets/fonts/` + `pubspec.yaml` 의 `flutter.fonts`
-- 큰 이미지: webp 사용 권장 (`flutter_image_compress` 또는 사전 변환)
-- Tree-shaking: `flutter build web --tree-shake-icons` 로 사용하지 않는 Material 아이콘 제거
-
-## 8. PWA (Progressive Web App)
-
-`flutter create --platforms=web` 시 자동 생성되는 `web/manifest.json` 을 채워서 PWA 로 동작:
-
-```json
-{
-  "name": "CLUe",
-  "short_name": "CLUe",
-  "start_url": "/",
-  "display": "standalone",
-  "background_color": "#FFFFFF",
-  "theme_color": "#6682FF",
-  "icons": [
-    { "src": "icons/Icon-192.png", "sizes": "192x192", "type": "image/png" },
-    { "src": "icons/Icon-512.png", "sizes": "512x512", "type": "image/png" }
-  ]
-}
-```
-
-Service worker 는 `flutter build web` 시 자동 생성된다 (`flutter_service_worker.js`).
-
-## 9. 디버깅 — Chrome DevTools
-
-- `flutter run -d chrome` 후 Chrome 자체 DevTools 열기 (F12)
-- Console 에서 `print()` 출력 확인 가능 (단, 프로덕션 빌드에서는 `print` 금지)
-- Source map 활성화: `--web-renderer html --source-maps` (디버그 빌드 기본)
-- Network 탭에서 API 호출 직접 검사 가능 → Playwright 기반 `evaluator-functional` 도 동일하게 동작
-
-## 10. Eval 인터페이스
-
-`fe_target = web` 인 경우 `harness-next.sh` 가 다음과 같이 자동 라우팅:
-
-```
-generator-frontend-flutter (Self-Verification: flutter analyze + flutter test)
-  → evaluator-functional (Playwright MCP — http://localhost:포트 E2E)
-  → evaluator-visual (Playwright MCP — 스크린샷 + 반응형 + 접근성)
-```
-
-**Generator 의 Self-Verification 단계에서 `flutter build web --release` 가 성공하는지 확인** 후 handoff.
-
-## 11. 호스팅 (참고)
-
-| 호스팅 | 빌드 산출물 |
-|--------|------------|
-| Vercel | `build/web/` 디렉토리를 정적 호스팅 |
-| Netlify | 동일 |
-| Firebase Hosting | `firebase deploy --only hosting` (firebase.json 의 public 을 `build/web` 으로) |
-| GitHub Pages | `build/web/` 을 gh-pages 브랜치에 푸시 |
-| 자체 서버 | nginx 로 정적 파일 서빙 + SPA fallback (`try_files $uri /index.html`) |
-
-호스팅 결정은 Planner / 사용자가 함. Generator 는 빌드 산출물만 보장.

package/skills/generator-frontend-flutter/references/i18n-pattern.md

@@ -1,102 +0,0 @@
----
-docmeta:
-  id: i18n-pattern
-  title: 다국어 (i18n) ARB 패턴
-  type: output
-  createdAt: 2026-04-09T00:00:00Z
-  updatedAt: 2026-04-09T00:00:00Z
-  source:
-    producer: agent
-    skillId: harness-generator-frontend-flutter
-  inputs:
-    - documentId: clue-fe-flutter-i18n
-      uri: ../../../../../moon_web/clue-fe-flutter.skill
-      relation: output-from
-      sections:
-        - sourceRange:
-            startLine: 1
-            endLine: 60
-          targetRange:
-            startLine: 32
-            endLine: 110
-  tags:
-    - flutter
-    - i18n
-    - arb
-    - l10n
----
-
-# 다국어 (i18n) ARB 패턴
-
-## ARB 파일 기반 l10n
-
-### 파일 경로
-
-- 영어: `lib/l10n/app_en.arb`
-- 한국어: `lib/l10n/app_ko.arb`
-- 일본어: `lib/l10n/app_ja.arb`
-
-프로젝트에 따라 `assets/strings/en.json` 등 다른 경로를 쓸 수 있다.
-`AGENTS.md` / sprint-contract.md 의 기존 컨벤션을 우선한다.
-
-### 작업 순서
-
-1. 문자열 언어 판별 (예: "취소" → ko, "Cancel" → en)
-2. 해당 언어 arb 파일에 **키 존재 여부 확인** (중복 방지)
-3. 없으면 모든 언어 파일에 동시 추가 (`app_en.arb`, `app_ko.arb`, `app_ja.arb`)
-4. 코드 치환 → `LocaleAssist().of.키이름`
-
-### 사용법
-
-```dart
-// 기본 문자열
-Text(
-  LocaleAssist().of.cancel,
-  style: MyTextStyle.size15.w500.xFF9CA3AF,
-)
-
-// 문자열 내 스타일 별도 구현 (ClueText 등 프로젝트 커스텀 위젯 사용)
-ClueText(
-  "${LocaleAssist().of.all} (${count})",
-  style: MyTextStyle.size16.w500,
-  targetList: [
-    TargetModel(
-      text: "(${count})",
-      style: MyTextStyle.size16.w500.xFF6682FF,
-    ),
-  ],
-)
-```
-
-### ARB 키 네이밍 규칙
-
-```json
-{
-  "cancel": "취소",
-  "confirm": "확인",
-  "doorOpen": "문 열기",
-  "networkError": "네트워크 오류가 발생했습니다"
-}
-```
-
-- **camelCase** 사용
-- 모든 arb 파일(en, ko, ja)에 **동일 키 동시 추가**
-- 기존 키 검색 후 중복 방지 (`grep -rn '"cancel"' lib/l10n/`)
-- 플레이스홀더 필요 시 ICU MessageFormat 사용
-
-## 필수 원칙
-
-- 영문 전용 표기 지시가 없는 한 **모든 사용자 노출 문자열은 다국어 처리**
-- 하드코딩된 문자열 사용 금지 (`Text('취소')` ✗)
-- 새 페이지 추가 시 관련 문자열 **일괄 등록** — 스프린트 중 누락 방지
-- 모든 arb 파일의 키 집합은 동일해야 한다 (Evaluator가 diff 검사)
-
-## Self-Check
-
-```bash
-# 하드코딩된 한글 탐지
-grep -rn "Text('[가-힣]" lib/ui/
-
-# 누락 키 탐지 (en 기준)
-python3 -c "import json; en=set(json.load(open('lib/l10n/app_en.arb')).keys()); ko=set(json.load(open('lib/l10n/app_ko.arb')).keys()); print('missing in ko:', en - ko); print('missing in en:', ko - en)"
-```