fastapi-modular 0.1.0__tar.gz → 0.2.0__tar.gz

fastapi_modular-0.2.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Thay đổi
+
+Theo [Keep a Changelog](https://keepachangelog.com/vi/1.1.0/); phiên bản theo
+[SemVer](https://semver.org/lang/vi/).
+
+## [Chưa phát hành]
+
+## [0.2.0] — 2026-08-22
+
+**Đổi tên toàn bộ.** Tên `pymodular` bị PyPI từ chối vì trùng với project
+`py-modular` đã có, nên cả dự án đổi sang `fastapi-modular` cho thống nhất từ
+PyPI, GitHub, thư mục nguồn cho tới tên lệnh.
+
+### Phá vỡ
+
+- Gói trên PyPI: `pymodular` -> **`fastapi-modular`**.
+- Tên import: `import pymodular` -> **`import fastapi_modular`** (gạch dưới,
+  vì gạch ngang không hợp lệ trong tên module Python).
+- Lệnh CLI: `pymodular` / `pym` -> **`fastapi-modular` / `fam`**.
+- Thư mục nguồn `pymodular/` -> `fastapi_modular/`.
+- `APP_NAME` mặc định: `pymodular` -> `fastapi-modular`.
+- `APP_KAFKA__CLIENT_ID` mặc định: `pymodular` -> `fastapi-modular`.
+
+Nâng cấp từ 0.1.0: gỡ gói cũ (`pip uninstall pymodular`), cài
+`pip install fastapi-modular`, rồi đổi mọi `pymodular` trong import thành
+`fastapi_modular` và mọi lệnh `pym` thành `fam`.
+
+### Sửa
+
+- `fam lint` không tham số trỏ vào thư mục `app` không tồn tại nên lỗi ngay;
+  mặc định đổi thành `src`, đúng thứ `fam init` sinh ra.
+- `fam migrate-create` trong docs/migrations.md không phải lệnh có thật; lệnh
+  đúng là `fam migrate create`.
+- Link trong README đổi sang URL tuyệt đối: README là trang hiển thị trên PyPI,
+  ở đó link tương đối `docs/...` phân giải sai và trả 404.
+- Job đóng gói trong CI không bao giờ xanh được: import sai đường dẫn
+  (`src.api.main`) và liệt kê route bằng `r.path`, hỏng từ FastAPI 0.141.
+
+## [0.1.0] — 2026-08-21
+
+Bản đầu tiên. Cần **Python 3.10 trở lên**.
+
+### Có gì
+
+- **Kiến trúc module kiểu NestJS**: DI container (`@injectable`, `Lazy[...]`,
+  `Scope.REQUEST`), controller dạng class (`@controller`, `@get`/`@post`/...),
+  tự quét module — thêm thư mục là có route, không phải đăng ký ở đâu cả.
+- **Repository dùng chung cho 4 backend**: memory, SQLite, PostgreSQL, MongoDB.
+  Đổi backend không phải sửa service. Kèm circuit breaker và hạn thời gian.
+- **WebSocket**: `@gateway` / `@subscribe`, phòng, gửi thẳng tới một người,
+  nhịp tim, giới hạn tần suất, adapter Redis để phát tin xuyên worker.
+- **Bốn lớp hạ tầng tuỳ chọn, cùng một khuôn**: RabbitMQ, Redis, MQTT, Kafka.
+  Mặc định TẮT; thư viện chỉ được import khi bật. Tất cả tự nối lại.
+- **CLI** `fastapi-modular`, gõ tắt là `fam`: `init` (dựng dự án ngay trong thư mục
+  hiện tại) · `new` · `dev` / `run` · `module` · `env` · `info` · `migrate` ·
+  `test` / `lint`. `init` không bao giờ ghi đè file đã có.
+- **Tài liệu tiếng Việt** trong `docs/`, viết theo lối tra cứu: mỗi hàm nói rõ
+  truyền gì, không truyền thì mặc định là gì.

{fastapi_modular-0.1.0 → fastapi_modular-0.2.0}/Makefile

@@ -16,85 +16,85 @@ help: ## Danh sách lệnh
 	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
 		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'
 
-# Makefile này chỉ là lối tắt cho `pym` khi làm việc TRONG repo. Người dùng thư
-# viện không có nó, nên mọi lệnh đều phải chạy được qua `pym` — và cách chắc
+# Makefile này chỉ là lối tắt cho `fam` khi làm việc TRONG repo. Người dùng thư
+# viện không có nó, nên mọi lệnh đều phải chạy được qua `fam` — và cách chắc
 # chắn nhất để giữ điều đó đúng là ở đây không tự viết gì cả, chỉ gọi lại.
-PYM := $(PY) -m pymodular.cli.main
+FAM := $(PY) -m fastapi_modular.cli.main
 
 dev: ## Chạy API kèm autoreload
-	$(PYM) dev
+	$(FAM) dev
 
 run: ## Chạy API chế độ production (nhiều worker — cần driver DB thật)
-	$(PYM) run --workers $(or $(WORKERS),4)
+	$(FAM) run --workers $(or $(WORKERS),4)
 
 module: ## Sinh khung module mới — dùng: make module name=alerts [entity=alert] [ws=1] [mq=1]
 	@test -n "$(name)" || { echo 'Thiếu tên. Dùng: make module name=alerts'; exit 1; }
-	$(PYM) module $(name) $(if $(entity),--entity $(entity),) $(if $(ws),--gateway,) $(if $(mq),--consumer,)
+	$(FAM) module $(name) $(if $(entity),--entity $(entity),) $(if $(ws),--gateway,) $(if $(mq),--consumer,)
 
 gateway: ## Thêm gateway WebSocket vào module đã có — dùng: make gateway name=alerts
 	@test -n "$(name)" || { echo 'Thiếu tên. Dùng: make gateway name=alerts'; exit 1; }
-	$(PYM) module $(name) --gateway-only $(if $(entity),--entity $(entity),)
+	$(FAM) module $(name) --gateway-only $(if $(entity),--entity $(entity),)
 
 consumer: ## Thêm consumer RabbitMQ vào module đã có — dùng: make consumer name=alerts
 	@test -n "$(name)" || { echo 'Thiếu tên. Dùng: make consumer name=alerts'; exit 1; }
-	$(PYM) module $(name) --consumer-only $(if $(entity),--entity $(entity),)
+	$(FAM) module $(name) --consumer-only $(if $(entity),--entity $(entity),)
 
 migrate: ## Chạy migration lên bản mới nhất
-	$(PYM) migrate up
+	$(FAM) migrate up
 
 migrate-create: ## Sinh migration từ thay đổi entity — dùng: make migrate-create m="them cot phone"
 	@test -n "$(m)" || { echo 'Thiếu tên. Dùng: make migrate-create m="mô tả thay đổi"'; exit 1; }
-	$(PYM) migrate create -m "$(m)"
+	$(FAM) migrate create -m "$(m)"
 
 migrate-down: ## Lùi lại một bản
-	$(PYM) migrate down
+	$(FAM) migrate down
 
 migrate-history: ## Lịch sử migration và bản đang áp dụng
-	@$(PYM) migrate history
+	@$(FAM) migrate history
 
 migrate-sql: ## In câu SQL thay vì chạy (để DBA duyệt trước)
-	$(PYM) migrate sql
+	$(FAM) migrate sql
 
 lint: ## Soi lỗi tĩnh
-	$(PYM) lint pymodular src tests
+	$(FAM) lint fastapi_modular src tests
 
 lint-fix: ## Soi và tự sửa những lỗi sửa được
-	$(PYM) lint --fix pymodular src tests
+	$(FAM) lint --fix fastapi_modular src tests
 
 test: ## Chạy test
-	$(PYM) test
+	$(FAM) test
 
 install: ## Cài khung ở chế độ chỉnh sửa được (chưa có driver database)
 	$(PIP) install -e .
 
 install-dev: ## Cài kèm công cụ phát triển (pytest, httpx, ruff, build, twine)
 	$(PIP) install -e .
-	$(PYM) install dev
+	$(FAM) install dev
 	$(PIP) install build twine
 
 install-sqlite: ## Cài driver SQLite + ghi biến vào .env
-	$(PYM) install sqlite
+	$(FAM) install sqlite
 
 install-postgres: ## Cài driver PostgreSQL + ghi biến vào .env
-	$(PYM) install postgres
+	$(FAM) install postgres
 
 install-mongo: ## Cài driver MongoDB + ghi biến vào .env
-	$(PYM) install mongodb
+	$(FAM) install mongodb
 
 install-redis: ## Cài Redis (cache, đếm, pub/sub) + ghi biến vào .env
-	$(PYM) install redis
+	$(FAM) install redis
 
 install-ws-redis: ## Bật adapter Redis cho WebSocket nhiều worker + ghi biến vào .env
-	$(PYM) install ws-redis
+	$(FAM) install ws-redis
 
 install-rabbitmq: ## Cài client RabbitMQ + ghi biến vào .env
-	$(PYM) install rabbitmq
+	$(FAM) install rabbitmq
 
 install-mqtt: ## Cài client MQTT + ghi biến vào .env
-	$(PYM) install mqtt
+	$(FAM) install mqtt
 
 install-kafka: ## Cài client Kafka + ghi biến vào .env
-	$(PYM) install kafka
+	$(FAM) install kafka
 
 
 
@@ -103,16 +103,16 @@ install-kafka: ## Cài client Kafka + ghi biến vào .env
 
 
 info: ## Đang nối vào đâu, thư viện nào đã cài
-	@$(PYM) info
+	@$(FAM) info
 
 build: ## Dựng wheel + sdist vào dist/
-	$(PYM) build
+	$(FAM) build
 
 publish-test: build ## Đẩy lên TestPyPI (thử trước khi đẩy thật)
-	$(PYM) publish --test
+	$(FAM) publish --test
 
 publish: build ## Đẩy lên PyPI
-	$(PYM) publish
+	$(FAM) publish
 
 clean: ## Xoá cache và bản dựng
-	$(PYM) clean
+	$(FAM) clean

{fastapi_modular-0.1.0 → fastapi_modular-0.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: fastapi-modular
-Version: 0.1.0
+Version: 0.2.0
 Summary: FastAPI theo kiến trúc module kiểu NestJS: DI container, controller dạng class, WebSocket, RabbitMQ/Redis/MQTT/Kafka
-Project-URL: Homepage, https://github.com/quanglinh2909/pymodular
-Project-URL: Documentation, https://github.com/quanglinh2909/pymodular/tree/main/docs
-Project-URL: Source, https://github.com/quanglinh2909/pymodular
-Project-URL: Issues, https://github.com/quanglinh2909/pymodular/issues
-Project-URL: Changelog, https://github.com/quanglinh2909/pymodular/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/quanglinh2909/fastapi-modular
+Project-URL: Documentation, https://github.com/quanglinh2909/fastapi-modular/tree/main/docs
+Project-URL: Source, https://github.com/quanglinh2909/fastapi-modular
+Project-URL: Issues, https://github.com/quanglinh2909/fastapi-modular/issues
+Project-URL: Changelog, https://github.com/quanglinh2909/fastapi-modular/blob/main/CHANGELOG.md
 Author-email: Oryza <developer@oryza.vn>
 License-Expression: MIT
 License-File: LICENSE
@@ -61,13 +61,13 @@ Requires-Dist: alembic>=1.13.0; extra == 'sqlite'
 Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.30; extra == 'sqlite'
 Description-Content-Type: text/markdown
 
-# pymodular
+# fastapi-modular
 
 FastAPI theo kiến trúc module kiểu NestJS: DI container, controller dạng class,
 repository chung cho nhiều loại database, gateway WebSocket có phòng, và bốn lớp
 hạ tầng tuỳ chọn: RabbitMQ, Redis, MQTT, Kafka.
 
-> **In English:** pymodular brings NestJS-style modular architecture to FastAPI —
+> **In English:** fastapi-modular brings NestJS-style modular architecture to FastAPI —
 > a DI container, class-based controllers, auto-discovered modules, a shared
 > repository over four databases, a WebSocket gateway with rooms, and optional
 > RabbitMQ / Redis / MQTT / Kafka layers that stay dormant until enabled.
@@ -81,119 +81,119 @@ Cần **Python 3.10+**.
 python -m venv .venv && . .venv/bin/activate
 pip install fastapi-modular
 
-pym init          # đổ file vào THƯ MỤC HIỆN TẠI, không tạo thêm cấp
-pym dev
+fam init          # đổ file vào THƯ MỤC HIỆN TẠI, không tạo thêm cấp
+fam dev
 ```
 
 Mở http://localhost:8000/docs — đã có sẵn một module `health` chạy được.
 
-`pym init` lấy tên dự án theo **tên thư mục hiện tại**; đặt tên khác bằng
-`pym init --name ten-khac`. Nó không ghi đè file nào đã có, nên chạy được cả
-trong thư mục đang có sẵn code. Muốn nó tự tạo thư mục thì `pym new <tên>`.
+`fam init` lấy tên dự án theo **tên thư mục hiện tại**; đặt tên khác bằng
+`fam init --name ten-khac`. Nó không ghi đè file nào đã có, nên chạy được cả
+trong thư mục đang có sẵn code. Muốn nó tự tạo thư mục thì `fam new <tên>`.
 
 Lõi **không kéo theo** driver database hay client hàng đợi nào. Cần cái gì thì
 thêm cái đó:
 
 ```bash
-pym install sqlite      # hoặc postgres, mongodb
-pym install rabbitmq    # hoặc redis, mqtt, kafka
-pym install all         # tất cả
+fam install sqlite      # hoặc postgres, mongodb
+fam install rabbitmq    # hoặc redis, mqtt, kafka
+fam install all         # tất cả
 ```
 
-`pym install` vừa cài thư viện vừa ghi biến vào `.env`. Muốn tự cài bằng pip
+`fam install` vừa cài thư viện vừa ghi biến vào `.env`. Muốn tự cài bằng pip
 cũng được: `pip install "fastapi-modular[sqlite,rabbitmq]"`.
 
 ## Lệnh
 
-Một chương trình, hai tên: `pymodular` (đầy đủ) và `pym` (gõ tắt). Dưới đây dùng
-`pym` cho gọn.
+Một chương trình, hai tên: `fastapi-modular` (đầy đủ) và `fam` (gõ tắt). Dưới đây dùng
+`fam` cho gọn.
 
-Tên lệnh rút gọn được tới khi nào tiền tố còn chỉ đúng một lệnh — `pym mo alerts`
-chạy y hệt `pym module alerts`. Nhập nhằng thì `pym` hỏi lại chứ không đoán:
+Tên lệnh rút gọn được tới khi nào tiền tố còn chỉ đúng một lệnh — `fam mo alerts`
+chạy y hệt `fam module alerts`. Nhập nhằng thì `fam` hỏi lại chứ không đoán:
 
 ```
-$ pym m
-pym: lệnh 'm' chưa rõ — khớp với migrate, module. Gõ thêm vài chữ cho rõ.
+$ fam m
+fam: lệnh 'm' chưa rõ — khớp với migrate, module. Gõ thêm vài chữ cho rõ.
 ```
 
 | Lệnh | Rút gọn | Làm gì |
 |---|---|---|
-| `pym init [--name <tên>]` | `pym ini` | dựng dự án **trong thư mục hiện tại**, không ghi đè file nào đã có; tên dự án mặc định lấy theo tên thư mục |
-| `pym new <tên>` | `pym n` | dựng dự án trong một thư mục mới |
-| `pym dev` | `pym d` | chạy kèm autoreload |
-| `pym run --workers 4` | `pym r` | chạy chế độ production |
-| `pym module <tên>` | `pym mo` | sinh module: controller + service + dto + entity |
-| `pym module <tên> --gateway` | | kèm gateway WebSocket (`--consumer` cho RabbitMQ) |
-| `pym module <tên> --gateway-only` | | chỉ thêm gateway vào module **đã có** (`--consumer-only` cho RabbitMQ) |
-| `pym module <tên> --entity <Tên>` | | đặt tên lớp entity; mặc định đoán từ tên module |
-| `pym env <thành-phần>` | `pym e` | chỉ ghi biến cấu hình vào `.env` (không cài gì) |
-| `pym clean` | `pym c` | xoá cache và bản dựng (không đụng `data/`) |
-| `pym build` · `pym publish [--test]` | `pym b` · `pym p` | dựng wheel/sdist · đẩy lên PyPI |
-| `pym info` | `pym inf` | đang nối vào đâu, thư viện nào đã cài, cảnh báo cấu hình prod |
-| `pym migrate [up\|down\|history\|sql\|create]` | `pym mi` | Alembic |
-| `pym test` · `pym lint [--fix]` | `pym t` · `pym l` | pytest · ruff. `pym lint` không tham số soi `src`; truyền đường dẫn để soi chỗ khác |
+| `fam init [--name <tên>]` | `fam ini` | dựng dự án **trong thư mục hiện tại**, không ghi đè file nào đã có; tên dự án mặc định lấy theo tên thư mục |
+| `fam new <tên>` | `fam n` | dựng dự án trong một thư mục mới |
+| `fam dev` | `fam d` | chạy kèm autoreload |
+| `fam run --workers 4` | `fam r` | chạy chế độ production |
+| `fam module <tên>` | `fam mo` | sinh module: controller + service + dto + entity |
+| `fam module <tên> --gateway` | | kèm gateway WebSocket (`--consumer` cho RabbitMQ) |
+| `fam module <tên> --gateway-only` | | chỉ thêm gateway vào module **đã có** (`--consumer-only` cho RabbitMQ) |
+| `fam module <tên> --entity <Tên>` | | đặt tên lớp entity; mặc định đoán từ tên module |
+| `fam env <thành-phần>` | `fam e` | chỉ ghi biến cấu hình vào `.env` (không cài gì) |
+| `fam clean` | `fam c` | xoá cache và bản dựng (không đụng `data/`) |
+| `fam build` · `fam publish [--test]` | `fam b` · `fam p` | dựng wheel/sdist · đẩy lên PyPI |
+| `fam info` | `fam inf` | đang nối vào đâu, thư viện nào đã cài, cảnh báo cấu hình prod |
+| `fam migrate [up\|down\|history\|sql\|create]` | `fam mi` | Alembic |
+| `fam test` · `fam lint [--fix]` | `fam t` · `fam l` | pytest · ruff. `fam lint` không tham số soi `src`; truyền đường dẫn để soi chỗ khác |
 | **Thêm database** | | *cài thư viện **rồi** ghi biến vào `.env`* |
-| `pym install sqlite` | `pym ins s` | file `.db`, không cần server |
-| `pym install postgres` | `pym ins p` | PostgreSQL |
-| `pym install mongodb` | `pym ins mo` | MongoDB |
+| `fam install sqlite` | `fam ins s` | file `.db`, không cần server |
+| `fam install postgres` | `fam ins p` | PostgreSQL |
+| `fam install mongodb` | `fam ins mo` | MongoDB |
 | **Thêm hàng đợi** | | *cài thư viện **rồi** ghi biến vào `.env`* |
-| `pym install rabbitmq` | `pym ins ra` | hàng đợi bền, thử lại + DLQ |
-| `pym install redis` | `pym ins re` | cache, đếm nguyên tử, pub/sub |
-| `pym install mqtt` | `pym ins mq` | thiết bị IoT |
-| `pym install kafka` | `pym ins k` | nhật ký sự kiện đọc lại được |
-| `pym install ws-redis` | `pym ins w` | phát tin WebSocket xuyên nhiều worker |
-| `pym install dev` | `pym ins d` | pytest · pytest-asyncio · httpx · ruff — cần cho `pym test` / `pym lint` |
-| `pym install all` | `pym ins a` | tất cả những thứ trên, **trừ** `dev` |
+| `fam install rabbitmq` | `fam ins ra` | hàng đợi bền, thử lại + DLQ |
+| `fam install redis` | `fam ins re` | cache, đếm nguyên tử, pub/sub |
+| `fam install mqtt` | `fam ins mq` | thiết bị IoT |
+| `fam install kafka` | `fam ins k` | nhật ký sự kiện đọc lại được |
+| `fam install ws-redis` | `fam ins w` | phát tin WebSocket xuyên nhiều worker |
+| `fam install dev` | `fam ins d` | pytest · pytest-asyncio · httpx · ruff — cần cho `fam test` / `fam lint` |
+| `fam install all` | `fam ins a` | tất cả những thứ trên, **trừ** `dev` |
 
-Tham số dạng danh sách cũng rút gọn theo cùng luật đó: `pym ins sq`,
-`pym e post`, `pym mi h`. Còn giá trị bạn tự đặt thì không bị đụng tới —
-`pym mo ins` tạo module tên đúng là `ins`.
+Tham số dạng danh sách cũng rút gọn theo cùng luật đó: `fam ins sq`,
+`fam e post`, `fam mi h`. Còn giá trị bạn tự đặt thì không bị đụng tới —
+`fam mo ins` tạo module tên đúng là `ins`.
 
-Host và cổng lấy từ `APP_HOST` / `APP_PORT` trong `.env`, nên `pym dev` không cần
-tham số. `pym --help` cho danh sách đầy đủ.
+Host và cổng lấy từ `APP_HOST` / `APP_PORT` trong `.env`, nên `fam dev` không cần
+tham số. `fam --help` cho danh sách đầy đủ.
 
 ## Thêm module
 
 ```bash
-pym module alerts              # controller + service + dto + entities
-pym module alerts --gateway    # kèm gateway WebSocket
-pym module alerts --consumer   # kèm consumer RabbitMQ
+fam module alerts              # controller + service + dto + entities
+fam module alerts --gateway    # kèm gateway WebSocket
+fam module alerts --consumer   # kèm consumer RabbitMQ
 ```
 
 Route xuất hiện ngay, bảng được tạo ngay, validate chạy ngay — chỉ thân hàm là
 chưa viết (gọi vào trả 501 kèm tên hàm). Việc của bạn: thêm trường vào entity và
 DTO, rồi viết thân hàm trong service.
 
-Không phải sửa file nào khác. Chi tiết: [docs/architecture.md](docs/architecture.md#thêm-module-mới).
+Không phải sửa file nào khác. Chi tiết: [docs/architecture.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/architecture.md#thêm-module-mới).
 
 ## Chọn database
 
-`pym install sqlite` (hoặc `postgres`, `mongodb`) làm cả hai việc: cài thư viện
+`fam install sqlite` (hoặc `postgres`, `mongodb`) làm cả hai việc: cài thư viện
 của đúng driver đó, rồi ghi biến vào `.env`. Chỉ muốn ghi `.env` mà không cài gì
-thì dùng `pym env sqlite`.
+thì dùng `fam env sqlite`.
 
-`pym env` ghi mỗi biến kèm giải thích, cho biết nó **bắt buộc hay tuỳ chọn** và
-**mặc định là gì** nếu xoá dòng đi. `pym info` cho biết hiện đang nối vào đâu.
+`fam env` ghi mỗi biến kèm giải thích, cho biết nó **bắt buộc hay tuỳ chọn** và
+**mặc định là gì** nếu xoá dòng đi. `fam info` cho biết hiện đang nối vào đâu.
 
-Chi tiết: [docs/database.md](docs/database.md).
+Chi tiết: [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md).
 
 ## Cấu hình của riêng bạn
 
 Kế thừa `Settings` là thêm được biến vào `.env`, không phải sửa gì trong khung:
 
 ```python
-# src/core/config.py — pym init sinh sẵn file này
+# src/core/config.py — fam init sinh sẵn file này
 class AppSettings(Settings):
     team_name: str = Field(default="", alias="APP_TEAM_NAME")
     jwt: JwtSettings = Field(default_factory=JwtSettings, alias="APP_JWT")   # -> APP_JWT__SECRET
 ```
 
 Service nhận `AppSettings` qua DI với gợi ý kiểu đầy đủ.
-Chi tiết: [docs/config.md](docs/config.md).
+Chi tiết: [docs/config.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/config.md).
 
 ## Điểm vào là file của bạn
 
-`pym init` sinh ra `src/main.py` với từng bước lắp ráp bày ra hết — thêm
+`fam init` sinh ra `src/main.py` với từng bước lắp ráp bày ra hết — thêm
 middleware, đổi CORS, gắn router bên thứ ba thì sửa thẳng ở đó:
 
 ```python
@@ -240,18 +240,18 @@ class AlertGateway:
 ```
 
 ```bash
-pym dev
+fam dev
 # ws://localhost:8000/ws/chat?client_id=an
 
-pym module alerts --gateway-only   # thêm gateway vào module đã có
-pym install ws-redis               # bắt buộc khi chạy nhiều worker
+fam module alerts --gateway-only   # thêm gateway vào module đã có
+fam install ws-redis               # bắt buộc khi chạy nhiều worker
 ```
 
 Đẩy tin từ REST hay tác vụ nền: nhận `WebSocketServer` qua `__init__` rồi gọi
 `to_room` / `to_user` / `to_socket`.
 
 Hướng dẫn đầy đủ (kèm cách dùng bằng **Postman** và client **Next.js**):
-[docs/websocket.md](docs/websocket.md).
+[docs/websocket.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/websocket.md).
 
 ## Hàng đợi (RabbitMQ — tuỳ chọn)
 
@@ -269,12 +269,12 @@ async def gui_mail(self, payload: AlertCreated) -> None: ...
 ```
 
 ```bash
-pym install rabbitmq            # cài aio-pika + ghi APP_RABBITMQ__* vào .env
-pym module alerts --consumer    # module mới kèm consumer
+fam install rabbitmq            # cài aio-pika + ghi APP_RABBITMQ__* vào .env
+fam module alerts --consumer    # module mới kèm consumer
 ```
 
 Không cài, không bật thì mọi thứ chạy y như chưa từng có nó. Broker rớt thì app
-vẫn phục vụ và tự nối lại. Chi tiết: [docs/rabbitmq.md](docs/rabbitmq.md).
+vẫn phục vụ và tự nối lại. Chi tiết: [docs/rabbitmq.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/rabbitmq.md).
 
 ## Redis, MQTT, Kafka (cũng tuỳ chọn)
 
@@ -283,9 +283,9 @@ biến `APP_<TÊN>__*`, mặc định **tắt**, thư viện chỉ import khi b
 nối lại.
 
 ```bash
-pym install redis    # cache, đếm, pub/sub      -> docs/redis.md
-pym install mqtt     # thiết bị IoT             -> docs/mqtt.md
-pym install kafka    # nhật ký sự kiện          -> docs/kafka.md
+fam install redis    # cache, đếm, pub/sub      -> docs/redis.md
+fam install mqtt     # thiết bị IoT             -> docs/mqtt.md
+fam install kafka    # nhật ký sự kiện          -> docs/kafka.md
 ```
 
 ```python
@@ -311,16 +311,16 @@ await kafka.publish("don-hang", don, key=don.ma_don)   # cùng key = cùng thứ
 curl localhost:8000/api/health        # liveness
 curl localhost:8000/api/health/ready  # readiness, có ping database
 curl localhost:8000/api/metrics       # số đo dạng Prometheus
-pym migrate                           # chạy migration (SQL)
-pym info                              # cấu hình đang dùng + cảnh báo prod
+fam migrate                           # chạy migration (SQL)
+fam info                              # cấu hình đang dùng + cảnh báo prod
 ```
 
-Chi tiết: [docs/operations.md](docs/operations.md).
+Chi tiết: [docs/operations.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/operations.md).
 
 ## Cấu trúc repo này
 
 ```
-pymodular/          THƯ VIỆN — thứ được đóng gói và cài về
+fastapi_modular/          THƯ VIỆN — thứ được đóng gói và cài về
   core/             DI, controller, config, WebSocket, guard, số đo
   infrastructure/   database, rabbitmq, redis, mqtt, kafka (mỗi thứ một package)
   cli/              init · new · module · dev · run · install · env · info
@@ -336,42 +336,42 @@ tests/              341 test chạy không cần hạ tầng, 40 test nữa bậ
 docs/               tài liệu tra cứu
 ```
 
-`pymodular/` không import gì từ `src/`. Nó chỉ biết "có một package tên
+`fastapi_modular/` không import gì từ `src/`. Nó chỉ biết "có một package tên
 `src.api`, quét nó đi" — nên dự án xếp khác cũng được, khai một lần trong
 `src/main.py`: `register_routes(app, package="cong_ty.dich_vu")`.
 
 ## Đóng góp
 
 ```bash
-git clone <repo> && cd pymodular
+git clone <repo> && cd fastapi-modular
 pip install -e ".[all,dev]"
-pym dev                        # chạy ứng dụng mẫu trong src/
-pym test
-pym lint pymodular src tests
+fam dev                        # chạy ứng dụng mẫu trong src/
+fam test
+fam lint fastapi_modular src tests
 ```
 
 Nhóm test cần hạ tầng thật chỉ chạy khi có biến môi trường tương ứng:
 
 ```bash
 docker run -d -p 6379:6379 redis:7-alpine
-TEST_REDIS_URL=redis://localhost:6379/0 pym test
+TEST_REDIS_URL=redis://localhost:6379/0 fam test
 ```
 
 Xem đầu mỗi file `tests/test_<tên>.py` để biết lệnh Docker và biến cần đặt.
 
 ## Giấy phép
 
-MIT — xem [LICENSE](LICENSE).
+MIT — xem [LICENSE](https://github.com/quanglinh2909/fastapi-modular/blob/main/LICENSE).
 
 ## Tài liệu
 
-- [docs/architecture.md](docs/architecture.md) — cấu trúc module, DI, đối chiếu NestJS
-- [docs/config.md](docs/config.md) — Settings, thứ tự ưu tiên, thêm biến của riêng bạn
-- [docs/database.md](docs/database.md) — memory / SQLite / PostgreSQL / MongoDB
-- [docs/migrations.md](docs/migrations.md) — Alembic: sinh, chạy, lùi migration
-- [docs/websocket.md](docs/websocket.md) — gateway WebSocket, phòng, Postman, Next.js
-- [docs/rabbitmq.md](docs/rabbitmq.md) — exchange, topic, consumer nền, `.retry` / `.dlq`
-- [docs/redis.md](docs/redis.md) — cache, đếm nguyên tử, pub/sub
-- [docs/mqtt.md](docs/mqtt.md) — QoS, retain, luật khớp topic `+` và `#`
-- [docs/kafka.md](docs/kafka.md) — nhóm consumer, phân vùng, `.dlt`
-- [docs/operations.md](docs/operations.md) — guard, circuit breaker, metrics, trace
+- [docs/architecture.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/architecture.md) — cấu trúc module, DI, đối chiếu NestJS
+- [docs/config.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/config.md) — Settings, thứ tự ưu tiên, thêm biến của riêng bạn
+- [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) — memory / SQLite / PostgreSQL / MongoDB
+- [docs/migrations.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/migrations.md) — Alembic: sinh, chạy, lùi migration
+- [docs/websocket.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/websocket.md) — gateway WebSocket, phòng, Postman, Next.js
+- [docs/rabbitmq.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/rabbitmq.md) — exchange, topic, consumer nền, `.retry` / `.dlq`
+- [docs/redis.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/redis.md) — cache, đếm nguyên tử, pub/sub
+- [docs/mqtt.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mqtt.md) — QoS, retain, luật khớp topic `+` và `#`
+- [docs/kafka.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/kafka.md) — nhóm consumer, phân vùng, `.dlt`
+- [docs/operations.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/operations.md) — guard, circuit breaker, metrics, trace