From ecf65493b69f3ca7fb146eb2342f61652e731bf4 Mon Sep 17 00:00:00 2001 From: toki Date: Fri, 29 May 2026 05:37:20 +0900 Subject: [PATCH] =?UTF-8?q?docs(readme):=20README=EB=A5=BC=20=ED=95=9C?= =?UTF-8?q?=EA=B5=AD=EC=96=B4=EB=A1=9C=20=EC=A0=95=EB=A6=AC=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 184 ++++++++++++++++++++++++------------------------------ 1 file changed, 80 insertions(+), 104 deletions(-) diff --git a/README.md b/README.md index 9afbf3f9..701f0850 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,48 @@ # nexo -`nexo` is a Flutter messaging and notification package workspace. The main -deliverable is `packages/messaging_flutter`: a reusable package that lets many -Flutter apps integrate messaging and push-notification behavior without each app -reimplementing the same native runtime. It is intended to be a shared messaging -layer for sibling products such as IOP, NomadCode, and ALT when they need -Mattermost-compatible messaging behavior without inheriting the full Mattermost -product shape. +`nexo`는 여러 Flutter 앱이 메시징과 푸시 알림 기능을 공통으로 사용할 수 있게 만드는 패키지 워크스페이스다. 핵심 산출물은 `packages/messaging_flutter`이며, 각 앱이 네이티브 메시징/푸시 런타임을 다시 구현하지 않고도 같은 기반을 소비할 수 있게 한다. -Mattermost upstream repositories are kept as references around the package: -`apps/mattermost` for the original Mattermost app, `services/core` for the -server, and `services/push-proxy` for the push server. This repository does not -contain a dedicated nexo product app, and it does not aim to become a broad -Mattermost fork. Mattermost snapshots are kept as upstream baselines and -validation references so Nexo-specific customization can stay in the plugin, -compose/runtime wrappers, docs, or small explicit patches. +이 패키지는 여러 소비 제품이 Mattermost 호환 메시징 동작은 필요하지만 Mattermost의 전체 제품 형태를 그대로 물려받고 싶지는 않을 때 쓰는 공통 메시징 계층이다. -## Name +Mattermost 업스트림 저장소는 이 패키지 주변의 기준선과 검증 참조로 둔다. `apps/mattermost`는 원래 Mattermost 앱, `services/core`는 Mattermost 서버, `services/push-proxy`는 Mattermost 푸시 서버 스냅샷이다. 이 저장소는 별도의 nexo 제품 앱을 담지 않으며, 넓은 Mattermost 포크가 되는 것도 목표가 아니다. Nexo 전용 커스터마이징은 가능한 한 플러그인, compose/런타임 래퍼, 문서, 작고 명시적인 패치에 둔다. -`nexo` comes from `nexus`: a connection point where apps, messages, -notifications, and service infrastructure meet. +## 이름 -## Product Boundary +`nexo`는 `nexus`에서 온 이름이다. 여러 앱, 메시지, 알림, 서비스 인프라가 만나는 연결 지점을 뜻한다. -- `packages/messaging_flutter/` is the Nexo-owned product surface. It should - hold reusable messaging, push notification, native bridge, and notification - tap/intake behavior that multiple Flutter apps can consume. -- Consuming apps such as IOP, NomadCode, and ALT own their product UI, workflow - semantics, and app-specific business logic. They should depend on Nexo for the - common messaging runtime instead of copying native push/messaging integration. -- Mattermost upstream code is a comparison and validation baseline, not the main - customization surface. Keep `apps/mattermost`, `services/core`, and - `services/push-proxy` close to their recorded upstream snapshots unless an - explicit upstream refresh or small targeted patch is being reviewed. -- When Mattermost product behavior does not fit a consuming app, prefer adding a - narrow Nexo plugin contract, wrapper, configuration point, or documented - integration path over changing the upstream snapshots directly. +## 제품 경계 -## Current Status +- `packages/messaging_flutter/`는 Nexo가 소유하는 제품 표면이다. 여러 Flutter 앱이 소비할 수 있는 메시징, 푸시 알림, 네이티브 브리지, 알림 탭/수신 동작을 이곳에 둔다. +- 이 패키지를 소비하는 앱은 각자의 제품 UI, 워크플로우 의미, 앱별 비즈니스 로직을 소유한다. 공통 메시징 런타임은 Nexo에 의존하고, 앱별 동작은 각 프로젝트에 남긴다. +- Mattermost 업스트림 코드는 비교와 검증을 위한 기준선이지 주 커스터마이징 표면이 아니다. 명시적인 업스트림 갱신이나 작은 대상 패치를 검토하는 경우가 아니라면 `apps/mattermost`, `services/core`, `services/push-proxy`는 기록된 업스트림 스냅샷에 가깝게 유지한다. +- Mattermost 제품 동작이 소비 앱에 맞지 않을 때는 업스트림 스냅샷을 직접 크게 바꾸기보다 좁은 Nexo 플러그인 계약, 래퍼, 설정 지점, 문서화된 통합 경로를 추가한다. -- `packages/messaging_flutter/` is the main product surface: an Android-first Flutter messaging and push-notification plugin package. -- `apps/flutter-test/` is the plugin test app. -- `apps/mattermost/` is the original Mattermost mobile app repository snapshot (see `apps/mattermost/UPSTREAM.md`). -- `services/core/` is the Mattermost server repository clone. -- `services/push-proxy/` is the Mattermost push-proxy repository snapshot (see `services/push-proxy/UPSTREAM.md`). -- Public package, import, and native identifiers are being moved to Nexo-owned names. -- iOS and macOS plugin scaffolds exist, but Android is the current implementation target. +## 현재 상태 -## Quick Start +- `packages/messaging_flutter/`는 Android 우선 Flutter 메시징/푸시 알림 플러그인 패키지이며, 이 저장소의 주 제품 표면이다. +- `apps/flutter-test/`는 플러그인을 검증하는 테스트용 Flutter 앱이다. +- `apps/mattermost/`는 원래 Mattermost 모바일 앱 저장소 스냅샷이다. 기준선은 `apps/mattermost/UPSTREAM.md`를 본다. +- `services/core/`는 Mattermost 서버 저장소 clone이다. +- `services/push-proxy/`는 Mattermost push-proxy 저장소 스냅샷이다. 기준선은 `services/push-proxy/UPSTREAM.md`를 본다. +- 공개 package, import, 네이티브 identifier는 Nexo 소유 이름으로 전환 중이다. +- iOS와 macOS 플러그인 scaffold는 있지만, 현재 구현 대상은 Android다. -Show development entrypoints: +## 빠른 시작 + +개발 진입점을 확인한다. ```sh bin/dev ``` -Run Flutter package and `flutter-test` host checks: +Flutter 패키지와 `flutter-test` 호스트 검증을 실행한다. ```sh bin/test bin/lint ``` -Start the core compose runtime: +core compose 런타임을 실행한다. ```sh cd services/core/compose @@ -70,87 +50,83 @@ cp .env.example .env docker compose up ``` -## Commands +## 주요 명령 -| Purpose | Command | Notes | +| 목적 | 명령 | 비고 | | --- | --- | --- | -| Show development entrypoints | `bin/dev` | Prints test host, plugin, and core compose commands | -| Run default tests | `bin/test` | Runs Flutter tests; skips Go tests by default | -| Run default lint | `bin/lint` | Runs Flutter analyze; skips Go vet by default | -| Run default build | `bin/build` | Runs configured app builds; skips `apps/flutter-test` web build when web is not configured and skips Go build by default | -| Include server Go tests | `NEXO_CORE_GO_TEST=1 bin/test` | Requires local `go` | -| Include server Go vet | `NEXO_CORE_GO_LINT=1 bin/lint` | Requires local `go` | -| Include server Go build | `NEXO_CORE_GO_BUILD=1 bin/build` | Requires local `go` | -| Run the `flutter-test` host directly | `cd apps/flutter-test && flutter run` | Requires Flutter SDK | -| Test the plugin directly | `cd packages/messaging_flutter && flutter test` | Requires Flutter SDK | -| Run Android native unit tests | `cd apps/flutter-test/android && ./gradlew testDebugUnitTest` | Requires Android SDK | +| 개발 진입점 확인 | `bin/dev` | 테스트 호스트, 플러그인, core compose 명령을 출력한다. | +| 기본 테스트 실행 | `bin/test` | Flutter 테스트를 실행하고, 기본값에서는 Go 테스트를 건너뛴다. | +| 기본 lint 실행 | `bin/lint` | Flutter analyze를 실행하고, 기본값에서는 Go vet을 건너뛴다. | +| 기본 build 실행 | `bin/build` | 설정된 앱 build를 실행한다. web 설정이 없으면 `apps/flutter-test` web build를 건너뛰고, 기본값에서는 Go build를 건너뛴다. | +| 서버 Go 테스트 포함 | `NEXO_CORE_GO_TEST=1 bin/test` | 로컬 `go`가 필요하다. | +| 서버 Go vet 포함 | `NEXO_CORE_GO_LINT=1 bin/lint` | 로컬 `go`가 필요하다. | +| 서버 Go build 포함 | `NEXO_CORE_GO_BUILD=1 bin/build` | 로컬 `go`가 필요하다. | +| `flutter-test` 호스트 직접 실행 | `cd apps/flutter-test && flutter run` | Flutter SDK가 필요하다. | +| 플러그인 직접 테스트 | `cd packages/messaging_flutter && flutter test` | Flutter SDK가 필요하다. | +| Android 네이티브 단위 테스트 실행 | `cd apps/flutter-test/android && ./gradlew testDebugUnitTest` | Android SDK가 필요하다. | -The `bin/*` helpers skip checks when a required local tool is unavailable. Note -any skipped checks in work reports. +`bin/*` helper는 필요한 로컬 도구가 없으면 일부 검증을 건너뛸 수 있다. 작업 보고에는 건너뛴 검증을 함께 적는다. -## Structure +## 구조 -| Path | Role | +| 경로 | 역할 | | --- | --- | -| `packages/messaging_flutter/` | Main Flutter messaging and push-notification package | -| `apps/flutter-test/` | `flutter-test` app for package integration checks | -| `apps/mattermost/` | Mattermost mobile app repository snapshot | -| `services/core/` | Mattermost server repository clone and current compose runtime | -| `services/push-proxy/` | Mattermost push-proxy repository snapshot | -| `docs/` | Cross-module product, migration, and operations notes | -| `bin/` | Workspace helper entrypoints | -| `agent-ops/` | Agent rules, domain rules, and common skill entrypoints | +| `packages/messaging_flutter/` | 주 Flutter 메시징/푸시 알림 패키지 | +| `apps/flutter-test/` | 패키지 통합 검증용 `flutter-test` 앱 | +| `apps/mattermost/` | Mattermost 모바일 앱 저장소 스냅샷 | +| `services/core/` | Mattermost 서버 저장소 clone과 현재 compose 런타임 | +| `services/push-proxy/` | Mattermost push-proxy 저장소 스냅샷 | +| `docs/` | 모듈 간 제품, migration, 운영 문서 | +| `bin/` | workspace helper 진입점 | +| `agent-ops/` | agent 규칙, domain rule, 공통 skill 진입점 | -## Work Context +## 작업 맥락 -- Start by reading `AGENTS.md`, then `agent-ops/rules/project/rules.md`. -- Follow path-specific domain rules under `agent-ops/rules/project/domain/*/rules.md`. -- For standard tasks such as README, plan, review, or commit/push, route through `agent-ops/skills/common/router.md`. -- Treat `packages/messaging_flutter/` as the primary product. App-specific product UI and business logic belong in consuming apps outside this repository. -- Treat IOP, NomadCode, and ALT as expected sibling consumers of the Nexo messaging layer; keep shared behavior in the plugin and app-specific behavior in those projects. -- Treat `apps/flutter-test/` only as the plugin integration test host; do not grow it into a product app or duplicate plugin internals there. -- Treat `apps/mattermost`, `services/core`, and `services/push-proxy` as original Mattermost repository clones, not as nexo-owned app or server products. -- Do not change `services/core/UPSTREAM.md` baseline information without an explicit upstream decision. -- Keep upstream working clones outside this repository under a sibling/external `mattermost/` staging folder, one clone for each original repository. -- Track each upstream repository on its recorded staging branch: `main` for `mattermost-mobile`, and `master` for `mattermost` and `mattermost-push-proxy`. When a tracked branch changes or a refresh is intentionally scheduled, take a fresh snapshot from staging and open a merge request into this repository. -- Record the exact upstream commit SHA for every snapshot that enters this repository. -- Prefer one merge request per upstream repository snapshot: `apps/mattermost`, `services/core`, or `services/push-proxy`. -- Never auto-apply staging updates into this repository; review the snapshot diff and run the relevant smoke checks first. -- Keep nexo-specific patches outside the upstream snapshot where possible, using compose, docs, wrappers, or small explicit patches. +- 작업을 시작할 때는 `AGENTS.md`를 읽고, 이어서 `agent-ops/rules/project/rules.md`를 읽는다. +- 변경 경로에 맞는 domain rule은 `agent-ops/rules/project/domain/*/rules.md`에서 확인한다. +- README, plan, review, commit/push 같은 표준 작업은 `agent-ops/skills/common/router.md`를 통해 공통 skill로 라우팅한다. +- `packages/messaging_flutter/`를 주 제품으로 본다. 앱별 제품 UI와 비즈니스 로직은 이 저장소가 아니라 패키지를 소비하는 앱의 책임이다. +- 여러 sibling 또는 외부 제품이 Nexo 메시징 계층을 소비할 수 있다. 공통 동작은 플러그인에 두고, 앱별 동작은 각 프로젝트에 둔다. +- `apps/flutter-test/`는 플러그인 통합 검증용 호스트로만 본다. 제품 앱으로 키우거나 플러그인 내부 동작을 복제하지 않는다. +- `apps/mattermost`, `services/core`, `services/push-proxy`는 Mattermost 원본 저장소 clone으로 본다. nexo 소유 앱이나 독자 서버 제품으로 재정의하지 않는다. +- 명시적인 업스트림 결정 없이 `services/core/UPSTREAM.md`의 기준선 정보를 바꾸지 않는다. +- 업스트림 작업 clone은 이 저장소 밖의 sibling/external `mattermost/` staging 폴더에 원본 저장소별로 둔다. +- 업스트림 저장소는 기록된 branch를 따라간다. `mattermost-mobile`은 `main`, `mattermost`와 `mattermost-push-proxy`는 `master`를 기준으로 하며, branch 변경 시점이나 의도적으로 정한 갱신 시점에 스냅샷을 떠서 이 저장소로 merge 요청한다. +- 이 저장소에 들어오는 스냅샷은 원본 저장소별 정확한 commit SHA를 기록한다. +- merge 요청은 원칙적으로 업스트림 저장소별로 분리한다. `apps/mattermost`, `services/core`, `services/push-proxy` 스냅샷을 한 요청에 섞지 않는다. +- staging pull 결과를 이 저장소에 자동 반영하지 않는다. 스냅샷 diff와 관련 smoke 검증을 확인한 뒤 merge 요청한다. +- Nexo 전용 패치는 가능한 한 업스트림 스냅샷 밖의 compose, 문서, 래퍼, 작고 명시적인 패치로 둔다. -## Development Flow +## 개발 흐름 -1. Read the domain rule for the path you will change. -2. Make focused changes inside the owning module. -3. Run the smallest useful verification for the change. -4. Use `bin/test`, `bin/lint`, or `bin/build` when workspace-level checks are needed. -5. Use `services/core/compose/` when runtime server verification is needed. +1. 변경할 경로의 domain rule을 읽는다. +2. 소유 모듈 안에서 변경 범위를 좁게 유지한다. +3. 변경에 맞는 가장 작은 유효 검증을 실행한다. +4. workspace 수준 검증이 필요하면 `bin/test`, `bin/lint`, `bin/build`를 사용한다. +5. 서버 런타임 검증이 필요하면 `services/core/compose/`를 사용한다. -## Environment Variables +## 환경 변수 ### Core Compose -| Name | Description | Required | +| 이름 | 설명 | 필수 | | --- | --- | --- | -| `NEXO_DB_PASSWORD` | Password for the Postgres `mmuser` account | Yes | -| `NEXO_SITE_URL` | Site URL used by the core service | Yes | -| `NEXO_CORE_PORT` | Host port mapped to core `8065` | No | -| `NEXO_PUSH_PROXY_PORT` | Host port mapped to push-proxy `8066` | No | +| `NEXO_DB_PASSWORD` | Postgres `mmuser` 계정 password | 예 | +| `NEXO_SITE_URL` | core service가 사용하는 site URL | 예 | +| `NEXO_CORE_PORT` | core `8065`에 매핑할 host port | 아니오 | +| `NEXO_PUSH_PROXY_PORT` | push-proxy `8066`에 매핑할 host port | 아니오 | -See `services/core/compose/.env.example` for example values. Do not commit real -`.env` files or runtime data. The Docker network subnet is fixed to -`172.38.0.0/16`; reserve this range for nexo and do not reuse it for other Docker -networks. +예시는 `services/core/compose/.env.example`를 본다. 실제 `.env` 파일이나 런타임 데이터는 커밋하지 않는다. Docker network subnet은 `172.38.0.0/16`으로 고정되어 있으므로, 이 범위는 nexo용으로 예약하고 다른 Docker network에서 재사용하지 않는다. -### Optional Verification +### 선택 검증 -| Name | Description | Default | +| 이름 | 설명 | 기본값 | | --- | --- | --- | -| `NEXO_CORE_GO_TEST` | Run server Go tests from `bin/test` | `0` | -| `NEXO_CORE_GO_LINT` | Run server Go vet from `bin/lint` | `0` | -| `NEXO_CORE_GO_BUILD` | Run server Go build from `bin/build` | `0` | +| `NEXO_CORE_GO_TEST` | `bin/test`에서 서버 Go 테스트를 실행한다. | `0` | +| `NEXO_CORE_GO_LINT` | `bin/lint`에서 서버 Go vet을 실행한다. | `0` | +| `NEXO_CORE_GO_BUILD` | `bin/build`에서 서버 Go build를 실행한다. | `0` | -## Reference Documents +## 참고 문서 - `AGENTS.md` - `agent-ops/rules/project/rules.md`