From f1a6deedae8760966177b4c554e301ab0a25d9c2 Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 21 May 2026 18:36:17 +0900 Subject: [PATCH] update domain rules and project rules --- agent-ops/rules/project/domain/dart/rules.md | 16 ++++++++---- agent-ops/rules/project/domain/go/rules.md | 11 +++++--- .../rules/project/domain/kotlin/rules.md | 25 +++++++++++++------ .../rules/project/domain/protocol/rules.md | 23 +++++++++++++---- agent-ops/rules/project/domain/tools/rules.md | 16 +++++++----- agent-ops/rules/project/rules.md | 4 ++- 6 files changed, 66 insertions(+), 29 deletions(-) diff --git a/agent-ops/rules/project/domain/dart/rules.md b/agent-ops/rules/project/domain/dart/rules.md index 0de7e4d..c3fbdf7 100644 --- a/agent-ops/rules/project/domain/dart/rules.md +++ b/agent-ops/rules/project/domain/dart/rules.md @@ -2,14 +2,15 @@ ## 목적 / 책임 -Proto Socket의 Dart/Flutter 구현체를 담당한다. ProtobufClient, ProtobufServer 등 핵심 클래스를 제공하며, 크로스 언어 테스트의 기준 구현으로 동작한다. +Proto Socket의 Dart/Flutter 구현체를 담당한다. TCP/WebSocket 클라이언트·서버, 공통 Communicator/BaseClient 로직, 하트비트 처리를 제공한다. ## 포함 경로 -- `dart/lib/` — 공개 API 및 구현 +- `dart/lib/` — 공개 API 및 구현 (packets/ 제외) - `dart/test/` — 동일 언어 단위/통합 테스트 -- `dart/crosstest/` — 크로스 언어 테스트 (Go, Kotlin과 연동). 오케스트레이터 또는 클라이언트 헬퍼 +- `dart/crosstest/` — 크로스 언어 테스트 (Go, Kotlin, Python, TypeScript와 연동). 오케스트레이터 또는 클라이언트 헬퍼 - `dart/pubspec.yaml` — 패키지 의존성 +- `dart/analysis_options.yaml` — Dart 정적 분석 설정 ## 제외 경로 @@ -19,19 +20,24 @@ Proto Socket의 Dart/Flutter 구현체를 담당한다. ProtobufClient, Protobuf - `ProtobufClient` — 소켓 클라이언트 기반 클래스 - `ProtobufServer` — 소켓 서버 기반 클래스 +- `WsProtobufClient` / `WsProtobufServer` — WebSocket 클라이언트/서버 기반 클래스 +- `BaseClient` / `Communicator` — 메시지 라우팅, 요청-응답 상관관계, 전송 공통 로직 +- `HeartbeatMixin` — 하트비트 송수신 및 연결 종료 처리 ## 유지할 패턴 - `dart pub get` 후 `dart test`로 테스트 실행 - crosstest는 상대방 언어 서버/클라이언트가 실행 중인 상태에서 수행 - Available 표시 조건: 동일 언어 테스트 + 크로스 언어 테스트 통과 +- PacketBase의 `typeName`, `nonce`, `data`, `responseNonce` 의미는 PROTOCOL.md와 맞춘다 ## 다른 도메인과의 경계 -- **protocol**: proto 타입을 사용하지만, proto 파일 자체는 protocol 도메인 -- **go/kotlin**: crosstest에서 상호 연동하지만, 각 구현체 내부 로직은 독립 +- **protocol**: proto 타입을 사용하지만, proto 파일과 생성된 packets 코드는 protocol 도메인 +- **go/kotlin/python/typescript**: crosstest에서 상호 연동하지만, 각 구현체 내부 로직은 독립 ## 금지 사항 - Dart 구현체에 Go/Kotlin 특화 로직을 추가하지 않는다 +- Dart 구현체에 Python/TypeScript 특화 로직을 추가하지 않는다 - proto schema 변경 시 proto 도메인 규칙을 먼저 따른다 diff --git a/agent-ops/rules/project/domain/go/rules.md b/agent-ops/rules/project/domain/go/rules.md index ccced52..030710a 100644 --- a/agent-ops/rules/project/domain/go/rules.md +++ b/agent-ops/rules/project/domain/go/rules.md @@ -2,13 +2,13 @@ ## 목적 / 책임 -Proto Socket의 Go 구현체를 담당한다. TCP/WebSocket 서버·클라이언트, TLS 지원, 타입 헬퍼 함수를 제공하며, 서버·툴링·스크립팅 용도로 사용된다. +Proto Socket의 Go 구현체를 담당한다. TCP/WebSocket 서버·클라이언트, TLS 지원, 공통 Communicator 로직, 타입 헬퍼 함수를 제공한다. ## 포함 경로 -- `go/*.go` — 핵심 구현 (packets/ 제외) +- `go/*.go` — 핵심 구현 및 루트 패키지 테스트 (packets/ 제외) - `go/test/` — 동일 언어 테스트 -- `go/crosstest/` — 크로스 언어 테스트 (Dart, Kotlin과 연동). 오케스트레이터 또는 클라이언트 헬퍼 +- `go/crosstest/` — 크로스 언어 테스트 (Dart, Kotlin, Python, TypeScript와 연동). 오케스트레이터 또는 클라이언트 헬퍼 - `go/go.mod`, `go/go.sum` — 모듈 의존성 - `go/examples/` — 사용 예제 @@ -21,18 +21,21 @@ Proto Socket의 Go 구현체를 담당한다. TCP/WebSocket 서버·클라이언 - `TcpServer` / `TcpClient` — TCP 서버/클라이언트 - `WsServer` / `WsClient` — WebSocket 서버/클라이언트 - `Communicator` — 메시지 라우팅 및 요청-응답 상관관계 공통 로직 +- `Transport` / `ParserMap` — 전송 추상화와 타입명 기반 파서 등록 - `AddListenerTyped`, `AddRequestListenerTyped`, `SendRequestTyped` — 타입 헬퍼 +- `HeartbeatTimer` / `baseClient` — 하트비트 및 연결 종료 공통 처리 ## 유지할 패턴 - `go test ./...`로 테스트 실행 - `ParserMap`으로 타입명 → 파서 함수 등록 - TLS 변형은 기본 구현과 같은 인터페이스 유지 +- PacketBase의 `typeName`, `nonce`, `data`, `responseNonce` 의미는 PROTOCOL.md와 맞춘다 ## 다른 도메인과의 경계 - **protocol**: packets/ 패키지를 import하지만, 패키지 내용은 protocol 도메인 -- **dart/kotlin**: crosstest에서 상호 연동 +- **dart/kotlin/python/typescript**: crosstest에서 상호 연동 ## 금지 사항 diff --git a/agent-ops/rules/project/domain/kotlin/rules.md b/agent-ops/rules/project/domain/kotlin/rules.md index 060c2b6..e5b6363 100644 --- a/agent-ops/rules/project/domain/kotlin/rules.md +++ b/agent-ops/rules/project/domain/kotlin/rules.md @@ -2,33 +2,42 @@ ## 목적 / 책임 -Proto Socket의 Kotlin/Android 구현체를 담당한다. Android 및 JVM 환경을 대상으로 한다. +Proto Socket의 Kotlin/Android 구현체를 담당한다. JVM/Android 대상 TCP/WebSocket 클라이언트·서버, 공통 Communicator/BaseClient 로직, 하트비트 처리를 제공한다. ## 포함 경로 -- `kotlin/src/` — 구현 소스 -- `kotlin/crosstest/` — 크로스 언어 테스트 (Dart, Go와 연동). 오케스트레이터 또는 클라이언트 헬퍼 +- `kotlin/src/main/kotlin/` — 구현 소스 +- `kotlin/src/test/` — 동일 언어 테스트 및 테스트 리소스 +- `kotlin/crosstest/` — 크로스 언어 테스트 (Dart, Go, Python, TypeScript와 연동). 오케스트레이터 또는 클라이언트 헬퍼 - `kotlin/build.gradle.kts`, `kotlin/settings.gradle.kts` — Gradle 빌드 설정 +- `kotlin/gradle/`, `kotlin/gradlew`, `kotlin/gradlew.bat` — Gradle wrapper ## 제외 경로 -- `kotlin/src/**/packets/` — protocol 도메인 +- `kotlin/src/main/proto/` — protocol 도메인의 Kotlin proto 복사본 +- `kotlin/build/`, `kotlin/.gradle/`, `kotlin/.kotlin/` — 빌드 산출물 및 로컬 캐시 ## 주요 구성 요소 -- `Transport`, `Communicator`, `BaseClient` 등 코어 로직 -- TCP / WebSocket 통신 클라이언트 +- `Transport` / `ParserMap` — 전송 추상화와 타입명 기반 파서 등록 +- `Communicator` — 메시지 라우팅 및 요청-응답 상관관계 공통 로직 +- `BaseClient` — 하트비트와 연결 종료 공통 처리 +- `TcpClient` / `TcpServer` — TCP 클라이언트/서버 +- `WsClient` / `WsServer` — WebSocket 클라이언트/서버 +- `HeartbeatTimer` — 하트비트 타이머 처리 ## 유지할 패턴 - `./gradlew test`로 테스트 실행 - `./gradlew run -PmainClass=...`으로 crosstest 실행 +- PacketBase의 `typeName`, `nonce`, `data`, `responseNonce` 의미는 PROTOCOL.md와 맞춘다 ## 다른 도메인과의 경계 -- **protocol**: proto 타입을 사용하지만, 스키마 정의는 protocol 도메인 -- **dart/go**: crosstest에서 상호 연동 +- **protocol**: proto 타입을 사용하지만, `kotlin/src/main/proto/`의 스키마 복사본은 protocol 도메인 +- **dart/go/python/typescript**: crosstest에서 상호 연동 ## 금지 사항 - Kotlin proto 복사본에서 메시지 스키마를 변경하지 않는다 +- Kotlin 구현체에 특정 상대 언어 전용 동작을 추가하지 않는다 diff --git a/agent-ops/rules/project/domain/protocol/rules.md b/agent-ops/rules/project/domain/protocol/rules.md index 66991e0..eb7eca5 100644 --- a/agent-ops/rules/project/domain/protocol/rules.md +++ b/agent-ops/rules/project/domain/protocol/rules.md @@ -2,14 +2,16 @@ ## 목적 / 책임 -와이어 포맷 명세와 proto 정의를 관리한다. PacketBase 프레이밍, 타입 라우팅, 요청-응답 상관관계, 하트비트의 공식 계약을 정의한다. +와이어 포맷 명세와 proto 정의, 언어별 packet 바인딩/코덱을 관리한다. PacketBase 프레이밍, 타입 라우팅, 요청-응답 상관관계, 하트비트의 공식 계약을 정의한다. ## 포함 경로 - `proto/` — 언어 옵션 없는 proto 정식 원본 - `dart/lib/src/packets/` — Dart protobuf 생성 코드 - `go/packets/` — Go용 proto 복사본 (go_package 옵션만 추가) -- `kotlin/src/**/packets/` — Kotlin용 proto 복사본 (Java 패키지 옵션만 추가) +- `kotlin/src/main/proto/` — Kotlin용 proto 복사본 (Java 패키지 옵션만 추가) +- `python/proto_socket/packets/` — Python proto 복사본 및 protobuf 바인딩 +- `typescript/src/packets/` — TypeScript packet 타입 및 바이너리 코덱 - `PROTOCOL.md` — 공식 와이어 포맷 명세 - `VERSIONING.md` — 프로토콜/패키지 버전 정책 @@ -17,24 +19,35 @@ - `dart/lib/src/` (packets/ 외) — Dart 구현체 로직 (dart 도메인) - `go/*.go` (packets/ 외) — Go 구현체 로직 (go 도메인) +- `kotlin/src/main/kotlin/`, `kotlin/src/test/`, `kotlin/crosstest/` — Kotlin 구현체 로직 (kotlin 도메인) +- `python/proto_socket/` (packets/ 외), `python/test/`, `python/crosstest/` — Python 구현체 로직 +- `typescript/src/` (packets/ 외), `typescript/test/`, `typescript/crosstest/` — TypeScript 구현체 로직 ## 주요 구성 요소 - `proto/message_common.proto` — PacketBase, 메시지 타입 정식 원본 -- `PacketBase` — 모든 패킷의 공통 래퍼 (type_name, payload, correlation_id) +- `go/packets/message_common.proto` — Go 언어 옵션이 붙은 proto 복사본 +- `kotlin/src/main/proto/message_common.proto` — Kotlin/Java 언어 옵션이 붙은 proto 복사본 +- `python/proto_socket/packets/message_common.proto` — Python 패키지의 proto 복사본 +- `typescript/src/packets/message_common_pb.ts` — TypeScript packet 타입 및 수동 바이너리 코덱 +- `PacketBase` — 모든 패킷의 공통 래퍼 (`typeName`, `nonce`, `data`, `responseNonce`) +- `HeartBeat` / `TestData` — 내장 하트비트 및 크로스 테스트용 메시지 ## 유지할 패턴 - proto 원본은 `proto/message_common.proto`에서만 편집 - Go/Kotlin proto는 언어별 옵션만 추가. 메시지 스키마는 건드리지 않는다 -- 변경 후 반드시 `tools/generate_proto.sh` + `tools/check_proto_sync.sh` 실행 +- Python proto 복사본은 정식 원본과 메시지 스키마를 맞춘다 +- TypeScript packet 코덱은 `PacketBase`, `HeartBeat`, `TestData`의 필드 번호와 wire type을 PROTOCOL.md/proto와 맞춘다 +- 변경 후 반드시 `tools/generate_proto.sh` + `tools/check_proto_sync.sh` 실행. 현재 스크립트는 Dart/Go 바인딩 생성과 Go/Kotlin proto 동기화 검증을 수행한다 ## 다른 도메인과의 경계 -- **dart/go/kotlin**: 구현체가 proto 타입을 사용하지만, 타입 정의 자체는 protocol 도메인 +- **dart/go/kotlin/python/typescript**: 구현체가 proto 타입을 사용하지만, 타입 정의·packet 바인딩·코덱 자체는 protocol 도메인 - **tools**: proto 생성/검증 스크립트는 tools 도메인. proto 파일 자체는 protocol 도메인 ## 금지 사항 - proto 파일을 Go/Kotlin 복사본에서 직접 편집하지 않는다 (메시지 스키마 변경은 `proto/message_common.proto`에서만) +- Python proto 복사본 또는 TypeScript packet 코덱에서 메시지 스키마를 단독 변경하지 않는다 - PROTOCOL.md에 정의되지 않은 프레이밍 방식을 구현체에서 임의로 추가하지 않는다 diff --git a/agent-ops/rules/project/domain/tools/rules.md b/agent-ops/rules/project/domain/tools/rules.md index f0a1cc6..03227c1 100644 --- a/agent-ops/rules/project/domain/tools/rules.md +++ b/agent-ops/rules/project/domain/tools/rules.md @@ -2,7 +2,7 @@ ## 목적 / 책임 -Proto 생성·동기화 스크립트를 담당한다. 모든 언어 구현체가 공통으로 사용하는 빌드 도구를 관리한다. +Proto 생성·동기화 스크립트를 담당한다. 현재 Dart/Go proto 바인딩 생성과 Go/Kotlin proto 스키마 동기화 검증 도구를 관리한다. ## 포함 경로 @@ -11,23 +11,27 @@ Proto 생성·동기화 스크립트를 담당한다. 모든 언어 구현체가 ## 제외 경로 -- `*/crosstest/` — 각 언어 구현체 도메인에 속함 (dart/go/kotlin) -- `dart/lib/`, `go/*.go`, `kotlin/src/` — 각 언어 구현체 도메인 +- `*/crosstest/` — 각 언어 구현체 도메인에 속함 +- `dart/lib/`, `go/*.go`, `kotlin/src/`, `python/proto_socket/`, `typescript/src/` — 각 언어 구현체 또는 protocol 도메인 +- `proto/`, `*/packets/`, `kotlin/src/main/proto/` — protocol 도메인 ## 주요 구성 요소 -- `tools/generate_proto.sh` — 모든 언어용 proto 바인딩 생성 -- `tools/check_proto_sync.sh` — 언어 간 proto 스키마 동기화 검증 +- `tools/generate_proto.sh` — Dart/Go proto 바인딩 생성 후 동기화 검사 실행 +- `tools/check_proto_sync.sh` — `proto/message_common.proto`와 Go/Kotlin proto 복사본의 스키마 동기화 검증 ## 유지할 패턴 - proto 변경 후 항상 generate → check_sync 순서로 실행 +- Bash 스크립트는 `set -euo pipefail`과 repo root 기준 경로 계산 패턴을 유지 +- 동기화 검사는 언어별 option 차이를 normalize한 뒤 schema 차이만 비교 ## 다른 도메인과의 경계 - **protocol**: 스크립트가 proto 파일을 읽지만, proto 파일 자체는 protocol 도메인 -- **dart/go/kotlin**: crosstest 코드는 각 언어 도메인에 속함. tools 도메인은 `tools/` 스크립트만 담당 +- **dart/go/kotlin/python/typescript**: crosstest 코드는 각 언어 도메인에 속함. tools 도메인은 `tools/` 스크립트만 담당 ## 금지 사항 - `check_proto_sync.sh` 실패를 무시하고 다음 단계로 진행하지 않는다 +- tools 스크립트에 언어별 런타임 구현 로직을 넣지 않는다 diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 092bf2d..944c75d 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -63,7 +63,9 @@ VERSIONING.md — 프로토콜/패키지 버전 정책 | `proto/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | | `dart/lib/src/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | | `go/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | -| `kotlin/src/**/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | +| `kotlin/src/main/proto/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | +| `python/proto_socket/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | +| `typescript/src/packets/**` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | | `PROTOCOL.md` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | | `VERSIONING.md` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` | | `tools/**` | tools | `agent-ops/rules/project/domain/tools/rules.md` |