fastapi-modular 0.3.0__tar.gz → 0.4.0__tar.gz

{fastapi_modular-0.3.0 → fastapi_modular-0.4.0}/CHANGELOG.md

@@ -3,7 +3,162 @@
 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.4.0] — 2026-08-28
+
+### Thêm
+
+- **`id: int` — khoá chính là số tự tăng.** Khai `id: int = 0` thay cho
+  `id: str` là database phát số; `id: str` vẫn là UUID khung sinh, không đổi gì.
+
+  ```python
+  @entity()
+  @dataclass(slots=True)
+  class Camera(Entity):
+      id: int = 0                    # 0 = "chưa có"
+
+  cam = await repo.save(Camera(name="Cổng chính"))
+  print(cam.id)                      # 1
+  ```
+
+  `SERIAL` trên Postgres, `INTEGER PRIMARY KEY AUTOINCREMENT` trên SQLite, bộ
+  đếm `_fam_counters` (`$inc`, nguyên tử) trên MongoDB, bộ đếm trong bộ nhớ ở
+  `memory`. `get` / `update` / `delete` nhận cả chuỗi lẫn số.
+
+  Ba chỗ phải bắt để bốn backend cư xử như nhau:
+
+  - SQLite mặc định cấp `max(rowid) + 1`, nên xoá bản ghi cuối bảng rồi ghi tiếp
+    là số cũ QUAY LẠI (đo được: `1, 2`, xoá `2`, ghi ra `2`). Bảng có id số nay
+    được tạo với `AUTOINCREMENT`.
+  - MongoDB: bản ghi MỚI dùng `insert_one` thay cho `replace_one(upsert=True)`.
+    Bộ đếm lệch — vì có ai đó gán id tay — nay cho **409** chứ không lặng lẽ đè
+    lên document của người khác.
+  - Câu `INSERT` bỏ hẳn cột `id` thay vì gửi `0` xuống.
+
+  Nhớ đổi `<tên>_id: str` thành `int` ở controller và service, nếu không FastAPI
+  nhận `"12"` (chuỗi) và bạn được 404 khó hiểu. `fam module` ghi sẵn lời nhắc
+  này ngay cạnh trường `id`.
+
+- **`column(length=50)` và `column(text=True)`** — đặt độ dài cột chữ, hoặc đổi
+  sang `TEXT`. Tương đương `@Column({length})` / `@Column({type: 'text'})` của
+  TypeORM:
+
+  ```python
+  code: str = field(default="", metadata=column(length=50))     # VARCHAR(50)
+  note: str = field(default="", metadata=column(text=True))     # TEXT
+  ```
+
+  Độ dài được kiểm **ở tầng khung**, trước khi câu lệnh xuống database, và cho
+  **400** kèm câu nói rõ chỗ sai. Vì sao không giao hết cho database: đo được,
+  ghi 60 ký tự vào `VARCHAR(50)` thì SQLite nhận bình thường, Postgres ném
+  `StringDataRightTruncation`, MongoDB không có khái niệm độ dài — tức là chạy
+  được lúc dev và đổ lúc chạy thật. Chặn ở cả `save()`, `update()` và
+  `update_where()`; Enum đếm theo `.value`.
+
+  Gộp với khoá ngoại trên cùng một cột bằng `|`:
+  `field(metadata=reference(Camera) | column(length=36))`.
+
+  Soi schema (`schema_mode="sync"`) nay kêu cả khi lệch độ dài
+  (`cameras.code: VARCHAR(8) -> VARCHAR(64)`), nhưng chỉ khi entity CÓ khai —
+  bảng cũ có `VARCHAR(50)` mà entity để `str` trơn thì không bị kêu oan.
+
+- **`repo.update(id, changes)` và `repo.update_where(dieu_kien, changes)`** —
+  sửa thẳng dưới database, không phải đọc bản ghi về trước. Thay vòng ba bước
+  `get` -> sửa -> `save` bằng một câu lệnh:
+
+  ```python
+  cam = await cameras.update("cam-01", status="offline")            # -> bản ghi đã sửa
+  n = await cameras.update_where({"zone": "Tầng 1"}, status="off")  # -> số dòng khớp
+  ```
+
+  Cùng cặp với `delete` / `delete_where`. `update` trả về **chính bản ghi đã
+  sửa** (`None` nếu không có id đó) và chỉ tốn **một** câu lệnh — đo được: 1 câu
+  so với 2 của `get` + `save` — nhờ `UPDATE ... RETURNING *` (SQL) và
+  `find_one_and_update` (Mongo). Bản trả về đọc từ database sau khi ghi, không
+  phải bản trong bộ nhớ.
+
+  `update_where` trả **số dòng khớp** chứ không trả dữ liệu, cố ý: một câu lệnh
+  có thể khớp hàng trăm nghìn dòng.
+
+  Giá trị truyền bằng dict, kwargs, hay **thẳng DTO của PATCH**:
+
+  ```python
+  async def update(self, camera_id: str, payload: CameraUpdate) -> int:
+      return await self._repo.update(camera_id, payload)
+  ```
+
+  DTO đọc bằng `exclude_unset=True`, y như `apply_changes`: chỉ field client
+  THỰC SỰ gửi mới được ghi. `model_dump()` trần sẽ ghi `None` đè lên mọi cột
+  không gửi. Truyền entity thì bị từ chối, kèm lời chỉ đường sang `save(obj)`.
+  Trả về **số dòng khớp**.
+
+- `fam module` sinh gợi ý `update_<tên>` theo API mới — `repo.update(id, payload)`
+  thay cho vòng `get` -> `apply_changes` -> `save`. Có test chép-dán-chạy-thật:
+  bỏ chú thích cả năm gợi ý, thêm một trường như bộ sinh dặn, rồi gọi qua HTTP.
+  Thứ tự tham số lấy đúng của TypeORM (`repo.update(criteria, partialEntity)`).
+
+  `updated_at` tự đóng dấu như `save()`. Ràng buộc vẫn được áp trên cả ba
+  backend: khoá ngoại trỏ tới cha không tồn tại, hay làm trùng cột `unique`,
+  đều bị từ chối.
+
+  Ba thứ bị chặn có chủ đích: đổi `id` (khoá ngoại của bảng khác đang trỏ vào),
+  `where` rỗng (gần như luôn là biến rỗng do lỗi lập trình — cố ý sửa cả bảng
+  thì nói rõ bằng `match=lambda _: True`), và cột không có thật (gõ sai mà im
+  lặng bỏ qua thì câu lệnh báo "đã sửa N dòng" nhưng không sửa gì).
+
+  Trên MongoDB đếm bằng `matched_count` chứ không phải `modified_count`: ghi
+  đúng giá trị đang có thì Mongo coi là không sửa gì và trả 0, trong khi SQL vẫn
+  đếm dòng đã khớp. Đo trên Mongo thật để chắc: `matched=1, modified=0`.
+
+### Sửa
+
+- **Trường `X | None` sinh ra cột `VARCHAR`.** `int | None` không phải một
+  `type`, nên mọi phép `is datetime` / `issubclass(..., Enum)` đều trượt và cột
+  rơi vào nhánh mặc định. Đo được với `port: int | None`: `memory` đọc về `8080`,
+  SQLite đọc về `'8080'` (chuỗi), Postgres ném `DataError` NGAY LÚC GHI.
+  `datetime | None` mất luôn múi giờ, `Enum | None` không được ép lại thành
+  Enum. Nay `X | None` cho ra đúng cột của `X`, chỉ khác là nhận `NULL`.
+
+  **Nâng cấp:** bảng tạo bằng bản ≤ 0.3.1 có cột `VARCHAR` cho những trường ấy,
+  nên `schema_mode="sync"` sẽ cảnh báo `VARCHAR -> INTEGER`. Đổi cột bằng
+  migration; bảng SQLite cũ vẫn đọc ghi được, còn Postgres thì trước đây ném lỗi
+  ngay lúc ghi nên gần như chắc chắn chưa có dữ liệu kiểu đó.
+
+- `update` / `update_where` nhận id số, không còn chặn "phải là chuỗi".
+
+- Bảng test chạy trên Postgres nay mang hậu tố ngẫu nhiên và tự xoá sau khi
+  chạy. Trước đó `test_drivers` dùng bảng `users` của app mẫu và gọi
+  `delete_where()` không điều kiện — trỏ `TEST_POSTGRES_DSN` vào một database
+  đang dùng là xoá sạch bảng `users` của dự án khác.
+
+- Bỏ hai file rác lọt vào gói: `ebsocket.md#...#`.
+
+## [0.3.1] — 2026-08-27
+
+### Sửa
+
+- **Worker ghi database không được commit.** `contextvars` được sao chép khi tạo
+  Task/Thread, nên `@worker` sinh ra từ trong một HTTP request — hoặc từ
+  `@interval`/`@job`, vốn cũng mở request scope — thừa hưởng đúng store của
+  request đó. Mà `SqlUnitOfWork` là provider request-scoped: nó mở transaction
+  rồi chỉ commit ở `on_request_end`. Worker sống lâu hơn request nên transaction
+  ấy không bao giờ được commit.
+
+  Kiểu hỏng này im lặng đến khó chịu:
+
+  ```python
+  print("Deleted:", await repo.delete(row.id))   # -> True
+  ```
+
+  `True` là đúng — DELETE khớp một dòng, và câu SELECT ngay sau cũng thấy dữ
+  liệu mới vì cùng một connection. Chỉ có điều trên đĩa không đổi gì, và tắt app
+  là mất sạch.
+
+  Nay worker được cắt khỏi request scope thừa hưởng (`detach_request_scope`),
+  nên mỗi thao tác tự commit như docs vẫn mô tả. Gộp nhiều lệnh ghi thì bọc
+  `async with db.transaction():` — vẫn dùng được trong `ctx.run`.
+
+  Hệ quả có thể thấy: `container.resolve(<provider Scope.REQUEST>)` trong worker
+  giờ báo lỗi thay vì trả về một instance mồ côi. Đó là cố ý.
 
 ## [0.3.0] — 2026-08-27
 

{fastapi_modular-0.3.0 → fastapi_modular-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-modular
-Version: 0.3.0
+Version: 0.4.0
 Summary: NestJS-style modular architecture for FastAPI: DI container, class-based controllers, auto-discovered modules, WebSocket gateway, RabbitMQ/Redis/MQTT/Kafka
 Project-URL: Homepage, https://github.com/quanglinh2909/fastapi-modular
 Project-URL: Documentation, https://github.com/quanglinh2909/fastapi-modular/tree/main/docs
@@ -96,7 +96,7 @@ public API, and this README, are in English. Start with
 |---|---|
 | `@Module()` + module scanning | a directory under `src/api/`, auto-scanned |
 | `@Controller('users')` | `@controller(prefix="/users", tags=["users"])` |
-| `@Get()` `@Post()` `@Patch()` `@Delete()` | `@get()` `@post()` `@patch()` `@delete()` |
+| `@Get()` `@Post()` `@Put()` `@Patch()` `@Delete()` | `@get()` `@post()` `@put()` `@patch()` `@delete()` |
 | sync handler runs on the main thread (Nest) | `def` handler runs in a thread pool, `async def` on the event loop — FastAPI's own rule |
 | `@Injectable()` | `@injectable` |
 | `@Injectable({scope: Scope.REQUEST})` | `@injectable(scope=Scope.REQUEST)` |
@@ -104,6 +104,7 @@ public API, and this README, are in English. Start with
 | `@InjectRepository(X) repo: Repository<X>` | `repo: Repository[X]` |
 | `@Transaction()` / `queryRunner.startTransaction()` | `async with db.transaction():` — nested blocks become SAVEPOINTs |
 | `queryRunner.rollbackTransaction()` | automatic on exception; `await tx.rollback()` to bail out without raising |
+| `repo.update(criteria, partialEntity)` (TypeORM) | `repo.update("cam-01", payload)` — takes the DTO directly and **returns the updated row** in one SQL statement; `repo.update_where({"zone": "T1"}, status="off")` for many rows |
 | `repo.createQueryBuilder()` (TypeORM) | `repo.query().join(X).where(Event.score >= …)` — real SQL, `.sql()` to see it |
 | `Repository.find({where: {score: MoreThan(…)}})` (TypeORM) | `class Event(Entity)` then `.where(Event.score >= …)`, or `.where(score__gte=…)` |
 | `.groupBy().having()` (TypeORM) | `.group_by(Event.camera_id).select(n=count()).having(count() > 5)` |
@@ -116,6 +117,8 @@ public API, and this README, are in English. Start with
 | `relations: {camera: {logs: {items: true}}}` (TypeORM) | `.nest_under(Camera, CameraLog, ItemLog)` — one query per level |
 | *(no TypeORM equivalent)* | `.nest_under(Camera)` — filter on events, get cameras back with them nested |
 | `@ManyToOne(…, {onDelete: 'CASCADE'})` (TypeORM) | `field(metadata=reference(Camera, on_delete="CASCADE"))` — a real FK in the database |
+| `@PrimaryGeneratedColumn()` / `@PrimaryGeneratedColumn('uuid')` (TypeORM) | `id: int = 0` (database assigns 1, 2, 3…) / `id: str` (the framework generates a UUID) |
+| `@Column({length: 50})` / `@Column({type: 'text'})` (TypeORM) | `field(metadata=column(length=50))` / `column(text=True)` — checked before the write on every backend |
 | `@UseGuards()` | `guards=[...]` on the controller or a single route |
 | `@WebSocketGateway()` | `@gateway(path="/ws/…")` |
 | `@SubscribeMessage('x')` | `@subscribe("x")` |
@@ -165,7 +168,7 @@ same job `package.json` does for `npm i`.
 
 ```
 # requirements.txt, after `fam install sqlite` and `fam install redis`
-fastapi-modular[redis,sqlite]>=0.3.0
+fastapi-modular[redis,sqlite]>=0.4.0
 ```
 
 It records the extras, not the individual packages: the version ranges of
@@ -196,7 +199,7 @@ fam: lệnh 'm' chưa rõ — khớp với migrate, module. Gõ thêm vài chữ
 | `fam init [--name <n>]` | `fam ini` | scaffold **into the current directory**; never overwrites; name defaults to the directory name |
 | `fam new <name>` | `fam n` | scaffold into a new directory |
 | `fam dev` | `fam d` | run with autoreload |
-| `fam run --workers 4` | `fam r` | run in production mode |
+| `fam run` | `fam r` | run in production mode (1 process; `--workers 4` for more) |
 | `fam module <name>` | `fam mo` | generate a module: controller + service + dto + entity |
 | `fam module <name> --gateway` | | plus a WebSocket gateway (`--consumer` for RabbitMQ) |
 | `fam module <name> --gateway-only` | | add a gateway to an **existing** module (`--consumer-only` for RabbitMQ) |
@@ -250,7 +253,7 @@ fam env sqlite          # write .env only, install nothing
 fam info                # what it is connected to right now
 ```
 
-Details: [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) (SQL) · [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md) (MongoDB).
+Details: [docs/entity.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/entity.md) · [docs/repository.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/repository.md) · [docs/query.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/query.md) · [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md).
 
 ## Your own configuration
 
@@ -423,7 +426,7 @@ Write `while ctx.running:`, not `while True:` — a loop that never checks makes
 Ctrl+C look dead for the whole shutdown timeout. The framework says so at
 startup (`worker.endless_loop`) rather than letting you find out at 2am.
 
-`fam run` starts 4 workers, so a hand-written `while True: sleep(5)` runs
+`fam run --workers 4` starts 4 processes, so a hand-written `while True: sleep(5)` runs
 **four times**. `single=True` (the default) locks it down: measured 5 runs
 across 1 process, versus 20 runs across 4 with the lock off. The lock is
 `flock` (one machine) or Redis (many), picked automatically.
@@ -511,7 +514,7 @@ src/                SAMPLE APPLICATION — not shipped in the package; delete fr
   core/config.py    AppSettings: subclass Settings to add your own .env variables
   core/lifespan.py  application-specific startup / shutdown work
   api/              business modules; every subdirectory is one module
-tests/              1097 tests that need no infrastructure, 292 more with real drivers/servers
+tests/              1163 tests that need no infrastructure, 424 more with real drivers/servers
 docs/               reference documentation (Vietnamese)
 ```
 
@@ -550,7 +553,11 @@ Written in Vietnamese, organised for reference rather than reading front to back
 
 - [docs/architecture.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/architecture.md) — module layout, DI, the NestJS comparison
 - [docs/config.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/config.md) — Settings, precedence, adding your own variables
-- [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) — SQL: memory / SQLite / PostgreSQL — entities, foreign keys, query builder, transactions
+- [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) — SQL: pick a driver (memory / SQLite / PostgreSQL), connections, schema sync
+- [docs/entity.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/entity.md) — declare tables: `@entity`, foreign keys + `on_delete`, unique/index, column length
+- [docs/repository.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/repository.md) — read/write in a service: `find`, `save`, `update`, `delete`
+- [docs/query.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/query.md) — query builder: JOIN, comparisons, NULL, grouping, nested results
+- [docs/transaction.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/transaction.md) — write several tables: all or nothing, SAVEPOINT
 - [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md) — MongoDB: queries, nested data, and what is not there (no JOIN, no transactions)
 - [docs/migrations.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/migrations.md) — Alembic: generate, run, roll back
 - [docs/websocket.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/websocket.md) — WebSocket gateway, rooms, Postman, Next.js

{fastapi_modular-0.3.0 → fastapi_modular-0.4.0}/README.md

@@ -26,7 +26,7 @@ public API, and this README, are in English. Start with
 |---|---|
 | `@Module()` + module scanning | a directory under `src/api/`, auto-scanned |
 | `@Controller('users')` | `@controller(prefix="/users", tags=["users"])` |
-| `@Get()` `@Post()` `@Patch()` `@Delete()` | `@get()` `@post()` `@patch()` `@delete()` |
+| `@Get()` `@Post()` `@Put()` `@Patch()` `@Delete()` | `@get()` `@post()` `@put()` `@patch()` `@delete()` |
 | sync handler runs on the main thread (Nest) | `def` handler runs in a thread pool, `async def` on the event loop — FastAPI's own rule |
 | `@Injectable()` | `@injectable` |
 | `@Injectable({scope: Scope.REQUEST})` | `@injectable(scope=Scope.REQUEST)` |
@@ -34,6 +34,7 @@ public API, and this README, are in English. Start with
 | `@InjectRepository(X) repo: Repository<X>` | `repo: Repository[X]` |
 | `@Transaction()` / `queryRunner.startTransaction()` | `async with db.transaction():` — nested blocks become SAVEPOINTs |
 | `queryRunner.rollbackTransaction()` | automatic on exception; `await tx.rollback()` to bail out without raising |
+| `repo.update(criteria, partialEntity)` (TypeORM) | `repo.update("cam-01", payload)` — takes the DTO directly and **returns the updated row** in one SQL statement; `repo.update_where({"zone": "T1"}, status="off")` for many rows |
 | `repo.createQueryBuilder()` (TypeORM) | `repo.query().join(X).where(Event.score >= …)` — real SQL, `.sql()` to see it |
 | `Repository.find({where: {score: MoreThan(…)}})` (TypeORM) | `class Event(Entity)` then `.where(Event.score >= …)`, or `.where(score__gte=…)` |
 | `.groupBy().having()` (TypeORM) | `.group_by(Event.camera_id).select(n=count()).having(count() > 5)` |
@@ -46,6 +47,8 @@ public API, and this README, are in English. Start with
 | `relations: {camera: {logs: {items: true}}}` (TypeORM) | `.nest_under(Camera, CameraLog, ItemLog)` — one query per level |
 | *(no TypeORM equivalent)* | `.nest_under(Camera)` — filter on events, get cameras back with them nested |
 | `@ManyToOne(…, {onDelete: 'CASCADE'})` (TypeORM) | `field(metadata=reference(Camera, on_delete="CASCADE"))` — a real FK in the database |
+| `@PrimaryGeneratedColumn()` / `@PrimaryGeneratedColumn('uuid')` (TypeORM) | `id: int = 0` (database assigns 1, 2, 3…) / `id: str` (the framework generates a UUID) |
+| `@Column({length: 50})` / `@Column({type: 'text'})` (TypeORM) | `field(metadata=column(length=50))` / `column(text=True)` — checked before the write on every backend |
 | `@UseGuards()` | `guards=[...]` on the controller or a single route |
 | `@WebSocketGateway()` | `@gateway(path="/ws/…")` |
 | `@SubscribeMessage('x')` | `@subscribe("x")` |
@@ -95,7 +98,7 @@ same job `package.json` does for `npm i`.
 
 ```
 # requirements.txt, after `fam install sqlite` and `fam install redis`
-fastapi-modular[redis,sqlite]>=0.3.0
+fastapi-modular[redis,sqlite]>=0.4.0
 ```
 
 It records the extras, not the individual packages: the version ranges of
@@ -126,7 +129,7 @@ fam: lệnh 'm' chưa rõ — khớp với migrate, module. Gõ thêm vài chữ
 | `fam init [--name <n>]` | `fam ini` | scaffold **into the current directory**; never overwrites; name defaults to the directory name |
 | `fam new <name>` | `fam n` | scaffold into a new directory |
 | `fam dev` | `fam d` | run with autoreload |
-| `fam run --workers 4` | `fam r` | run in production mode |
+| `fam run` | `fam r` | run in production mode (1 process; `--workers 4` for more) |
 | `fam module <name>` | `fam mo` | generate a module: controller + service + dto + entity |
 | `fam module <name> --gateway` | | plus a WebSocket gateway (`--consumer` for RabbitMQ) |
 | `fam module <name> --gateway-only` | | add a gateway to an **existing** module (`--consumer-only` for RabbitMQ) |
@@ -180,7 +183,7 @@ fam env sqlite          # write .env only, install nothing
 fam info                # what it is connected to right now
 ```
 
-Details: [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) (SQL) · [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md) (MongoDB).
+Details: [docs/entity.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/entity.md) · [docs/repository.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/repository.md) · [docs/query.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/query.md) · [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md).
 
 ## Your own configuration
 
@@ -353,7 +356,7 @@ Write `while ctx.running:`, not `while True:` — a loop that never checks makes
 Ctrl+C look dead for the whole shutdown timeout. The framework says so at
 startup (`worker.endless_loop`) rather than letting you find out at 2am.
 
-`fam run` starts 4 workers, so a hand-written `while True: sleep(5)` runs
+`fam run --workers 4` starts 4 processes, so a hand-written `while True: sleep(5)` runs
 **four times**. `single=True` (the default) locks it down: measured 5 runs
 across 1 process, versus 20 runs across 4 with the lock off. The lock is
 `flock` (one machine) or Redis (many), picked automatically.
@@ -441,7 +444,7 @@ src/                SAMPLE APPLICATION — not shipped in the package; delete fr
   core/config.py    AppSettings: subclass Settings to add your own .env variables
   core/lifespan.py  application-specific startup / shutdown work
   api/              business modules; every subdirectory is one module
-tests/              1097 tests that need no infrastructure, 292 more with real drivers/servers
+tests/              1163 tests that need no infrastructure, 424 more with real drivers/servers
 docs/               reference documentation (Vietnamese)
 ```
 
@@ -480,7 +483,11 @@ Written in Vietnamese, organised for reference rather than reading front to back
 
 - [docs/architecture.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/architecture.md) — module layout, DI, the NestJS comparison
 - [docs/config.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/config.md) — Settings, precedence, adding your own variables
-- [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) — SQL: memory / SQLite / PostgreSQL — entities, foreign keys, query builder, transactions
+- [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) — SQL: pick a driver (memory / SQLite / PostgreSQL), connections, schema sync
+- [docs/entity.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/entity.md) — declare tables: `@entity`, foreign keys + `on_delete`, unique/index, column length
+- [docs/repository.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/repository.md) — read/write in a service: `find`, `save`, `update`, `delete`
+- [docs/query.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/query.md) — query builder: JOIN, comparisons, NULL, grouping, nested results
+- [docs/transaction.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/transaction.md) — write several tables: all or nothing, SAVEPOINT
 - [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md) — MongoDB: queries, nested data, and what is not there (no JOIN, no transactions)
 - [docs/migrations.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/migrations.md) — Alembic: generate, run, roll back
 - [docs/websocket.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/websocket.md) — WebSocket gateway, rooms, Postman, Next.js

{fastapi_modular-0.3.0 → fastapi_modular-0.4.0}/README.vi.md

@@ -21,7 +21,7 @@ fam init && fam dev
 |---|---|
 | `@Module()` + module scanning | một thư mục dưới `src/api/`, tự quét |
 | `@Controller('users')` | `@controller(prefix="/users", tags=["users"])` |
-| `@Get()` `@Post()` `@Patch()` `@Delete()` | `@get()` `@post()` `@patch()` `@delete()` |
+| `@Get()` `@Post()` `@Put()` `@Patch()` `@Delete()` | `@get()` `@post()` `@put()` `@patch()` `@delete()` |
 | handler đồng bộ chạy ngay luồng chính (Nest) | `def` thường chạy ở thread pool, `async def` chạy trên vòng lặp — đúng luật FastAPI |
 | `@Injectable()` | `@injectable` |
 | `@Injectable({scope: Scope.REQUEST})` | `@injectable(scope=Scope.REQUEST)` |
@@ -29,6 +29,7 @@ fam init && fam dev
 | `@InjectRepository(X) repo: Repository<X>` | `repo: Repository[X]` |
 | `@Transaction()` / `queryRunner.startTransaction()` | `async with db.transaction():` — khối lồng nhau thành SAVEPOINT |
 | `queryRunner.rollbackTransaction()` | tự động khi có exception; `await tx.rollback()` để huỷ mà không ném lỗi |
+| `repo.update(criteria, partialEntity)` (TypeORM) | `repo.update("cam-01", payload)` — nhận thẳng DTO, **trả về bản ghi đã sửa** trong 1 câu SQL; `repo.update_where({"zone": "T1"}, status="off")` cho nhiều dòng |
 | `repo.createQueryBuilder()` (TypeORM) | `repo.query().join(X).where(Event.score >= …)` — SQL thật, xem bằng `.sql()` |
 | `Repository.find({where: {score: MoreThan(…)}})` (TypeORM) | `class Event(Entity)` rồi `.where(Event.score >= …)`, hoặc `.where(score__gte=…)` |
 | `.groupBy().having()` (TypeORM) | `.group_by(Event.camera_id).select(n=count()).having(count() > 5)` |
@@ -41,6 +42,8 @@ fam init && fam dev
 | `relations: {camera: {logs: {items: true}}}` (TypeORM) | `.nest_under(Camera, CameraLog, ItemLog)` — mỗi mức một câu lệnh |
 | *(TypeORM không có)* | `.nest_under(Camera)` — lọc theo sự kiện, nhận về camera kèm sự kiện bên trong |
 | `@ManyToOne(…, {onDelete: 'CASCADE'})` (TypeORM) | `field(metadata=reference(Camera, on_delete="CASCADE"))` — khoá ngoại THẬT dưới database |
+| `@PrimaryGeneratedColumn()` / `@PrimaryGeneratedColumn('uuid')` (TypeORM) | `id: int = 0` (database phát số 1, 2, 3…) / `id: str` (khung sinh UUID) |
+| `@Column({length: 50})` / `@Column({type: 'text'})` (TypeORM) | `field(metadata=column(length=50))` / `column(text=True)` — chặn ngay lúc ghi, trên mọi backend |
 | `@UseGuards()` | `guards=[...]` ở controller hoặc từng route |
 | `@WebSocketGateway()` | `@gateway(path="/ws/…")` |
 | `@SubscribeMessage('x')` | `@subscribe("x")` |
@@ -87,7 +90,7 @@ phần vào `requirements.txt`** để đồng nghiệp clone repo về chỉ c
 
 ```
 # requirements.txt, sau khi `fam install sqlite` rồi `fam install redis`
-fastapi-modular[redis,sqlite]>=0.3.0
+fastapi-modular[redis,sqlite]>=0.4.0
 ```
 
 Nó ghi extras chứ không liệt kê từng gói con: khoảng phiên bản của
@@ -117,7 +120,7 @@ fam: lệnh 'm' chưa rõ — khớp với migrate, module. Gõ thêm vài chữ
 | `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 run` | `fam r` | chạy chế độ production (1 tiến trình; `--workers 4` để nhiều hơn) |
 | `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) |
@@ -172,7 +175,7 @@ thì dùng `fam env sqlite`.
 `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](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) (SQL) · [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md) (MongoDB).
+Chi tiết: [docs/entity.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/entity.md) · [docs/repository.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/repository.md) · [docs/query.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/query.md) · [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md).
 
 ## Cấu hình của riêng bạn
 
@@ -347,7 +350,7 @@ Viết `while ctx.running:`, đừng viết `while True:` — vòng lặp không
 làm Ctrl+C trông như chết suốt cả thời gian chờ tắt. Khung kêu ngay lúc khởi
 động (`worker.endless_loop`) chứ không để bạn phát hiện lúc 2 giờ sáng.
 
-`fam run` bật 4 worker, nên một vòng `while True: sleep(5)` viết tay sẽ chạy
+`fam run --workers 4` chạy 4 tiến trình, nên một vòng `while True: sleep(5)` viết tay sẽ chạy
 **bốn lần**. Mặc định `single=True` khoá lại: đo được 5 lượt / 1 tiến trình,
 so với 20 lượt / 4 tiến trình khi tắt khoá. Khoá dùng `flock` (một máy) hoặc
 Redis (nhiều máy), tự chọn.
@@ -439,7 +442,7 @@ src/                ỨNG DỤNG MẪU — không nằm trong gói cài; xoá th
   core/config.py    AppSettings: kế thừa Settings để thêm biến .env của bạn
   core/lifespan.py  việc lúc khởi động / lúc tắt của riêng ứng dụng
   api/              các module nghiệp vụ; mỗi thư mục con là một module
-tests/              1097 test chạy không cần hạ tầng, 292 test nữa cần driver/server thật
+tests/              1163 test chạy không cần hạ tầng, 424 test nữa cần driver/server thật
 docs/               tài liệu tra cứu
 ```
 
@@ -474,7 +477,11 @@ MIT — xem [LICENSE](https://github.com/quanglinh2909/fastapi-modular/blob/main
 
 - [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) — SQL: memory / SQLite / PostgreSQL — entity, khoá ngoại, query builder, transaction
+- [docs/database.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/database.md) — SQL: chọn driver (memory / SQLite / PostgreSQL), kết nối, tự chỉnh schema
+- [docs/entity.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/entity.md) — khai bảng: `@entity`, khoá ngoại + `on_delete`, unique/index, độ dài cột chữ
+- [docs/repository.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/repository.md) — đọc/ghi trong service: `find`, `save`, `update`, `delete`
+- [docs/query.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/query.md) — query builder: JOIN, lớn/bé, NULL, gộp nhóm, dữ liệu lồng nhau
+- [docs/transaction.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/transaction.md) — ghi nhiều bảng: cùng thành công hoặc cùng không
 - [docs/mongodb.md](https://github.com/quanglinh2909/fastapi-modular/blob/main/docs/mongodb.md) — MongoDB: truy vấn, dữ liệu lồng nhau, và những thứ bên đó không có (không JOIN, không transaction)
 - [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

{fastapi_modular-0.3.0 → fastapi_modular-0.4.0}/docs/README.md

@@ -2,7 +2,11 @@
 
 | Tài liệu | Nội dung |
 |---|---|
-| [database.md](database.md) | SQL: memory, SQLite, PostgreSQL — entity, khoá ngoại, query builder, transaction |
+| [database.md](database.md) | SQL: chọn driver (memory / SQLite / PostgreSQL), kết nối, mất kết nối, tự chỉnh schema |
+| [entity.md](entity.md) | Khai bảng dữ liệu: `@entity`, khoá ngoại + `on_delete`, unique/index, độ dài cột chữ, dấu thời gian |
+| [repository.md](repository.md) | Đọc/ghi trong service: `find`, `save`, `update`/`update_where`, `delete` |
+| [query.md](query.md) | Truy vấn phức tạp: JOIN, lớn/bé, NULL, gộp nhóm, dữ liệu lồng nhau, injection |
+| [transaction.md](transaction.md) | Ghi nhiều bảng: cùng thành công hoặc cùng không, SAVEPOINT |
 | [mongodb.md](mongodb.md) | MongoDB: truy vấn, dữ liệu lồng nhau, và những thứ bên đó không có |
 | [config.md](config.md) | Settings: thứ tự ưu tiên, **thêm biến của riêng bạn**, .env |
 | [architecture.md](architecture.md) | Cấu trúc module, DI container, đối chiếu với NestJS |

{fastapi_modular-0.3.0 → fastapi_modular-0.4.0}/docs/architecture.md

@@ -68,15 +68,17 @@ quét nó đi". Xếp khác thì nói ra một lần trong `src/main.py`:
 | `@Module()` + module scanning | thư mục dưới `src/api/`, tự quét ở `fastapi_modular/discovery.py` |
 | `@UseGuards()` | `guards=[...]` ở `@controller` hoặc từng route |
 | `@Controller('users')` | `@controller(prefix="/users", tags=["users"])` |
-| `@Get()` `@Post()` `@Patch()` `@Delete()` | `@get()` `@post()` `@patch()` `@delete()` |
+| `@Get()` `@Post()` `@Put()` `@Patch()` `@Delete()` | `@get()` `@post()` `@put()` `@patch()` `@delete()` |
 | `@Injectable()` | `@injectable` |
 | `@Injectable({scope: Scope.REQUEST})` | `@injectable(scope=Scope.REQUEST)` |
 | `forwardRef(() => X)` | `Lazy[X]` |
 | `@InjectRepository(X) repo: Repository<X>` | `repo: Repository[X]` |
-| `repo.createQueryBuilder()` (TypeORM) | `repo.query()` — `join`/`left_join`/`right_join`/`outer_join`, `where`/`or_where`, `group_by`/`having`; xem [database.md](database.md#truy-vấn-phức-tạp--join-lớnbé-null) |
+| `repo.createQueryBuilder()` (TypeORM) | `repo.query()` — `join`/`left_join`/`right_join`/`outer_join`, `where`/`or_where`, `group_by`/`having`; xem [database.md](query.md#truy-vấn-phức-tạp--join-lớnbé-null) |
 | `find({relations: …})` (TypeORM) | `.include(Event, fields=…, exclude=…)` · `.nest_under(Camera)` — dữ liệu lồng nhau, hai chiều |
-| `@ManyToOne(…, {onDelete})` (TypeORM) | `reference(X, on_delete=…)` — xem [database.md](database.md#khoá-ngoại-nối-hai-bảng-với-nhau) |
+| `@ManyToOne(…, {onDelete})` (TypeORM) | `reference(X, on_delete=…)` — xem [database.md](entity.md#khoá-ngoại-nối-hai-bảng-với-nhau) |
 | `@Entity()` | `@entity` |
+| `@PrimaryGeneratedColumn()` (TypeORM) | `id: int = 0` — xem [entity.md](entity.md#id-chuỗi-uuid-hay-số-tự-tăng) |
+| `@Column({length, type: 'text'})` (TypeORM) | `field(metadata=column(length=50))` — xem [entity.md](entity.md#độ-dài-cột-chữ-varchar50-và-text) |
 | `extends BaseEntity` | `class X(Entity)` — chỉ để lọc bằng toán tử: `.where(X.score >= 0.8)` |
 | `overrideProvider()` | `container.override()` |
 | `@WebSocketGateway()` | `@gateway(path="/ws/…")` |
@@ -194,8 +196,13 @@ chỉ thân hàm là chưa viết, gọi vào trả **501** kèm tên hàm:
 Ba việc còn lại của bạn:
 
 1. Thêm trường vào `entities/<tên>_model.py` và `dto/<tên>_schema.py`
-2. Khai `unique=` / `indexes=` trong `@entity` nếu cần
-3. Viết thân hàm trong `<tên>_service.py` — mỗi hàm có sẵn gợi ý dạng chú thích
+2. Khai `unique=` / `indexes=` trong `@entity`, độ dài cột chữ bằng `column(length=…)`
+3. Viết thân hàm trong `<tên>_service.py` — mỗi hàm có sẵn gợi ý dạng chú thích,
+   bỏ chú thích ra là chạy được (có test chép-dán-chạy-thật canh điều đó). Gợi ý
+   của `update_<tên>` dùng [`repo.update(id, payload)`](repository.md#sửa-dữ-liệu-không-cần-đọc-về-trước)
+   — nhận thẳng DTO, một lượt đi database. Cần đọc bản ghi cũ trước khi ghi
+   (kiểm trùng, so giá trị cũ) thì dùng `apply_changes` + `save` như
+   `src/api/users/user_service.py`.
 
 Không phải đăng ký ở đâu cả: không sửa `main.py`, không sửa `api/app.py`.
 
@@ -227,6 +234,45 @@ Hai lỗi hay gặp, cả hai đều được log cảnh báo lúc boot:
 - `api.module_without_controller` — thư mục không có `@controller` nào.
 - `controller.no_routes` — có controller nhưng chưa method nào mang `@get`/`@post`.
 
+### Tham số của `@controller`
+
+| Tham số | Bắt buộc | Mặc định | Để làm gì |
+|---|---|---|---|
+| `prefix` | không | `""` | tiền tố đường dẫn cho MỌI route trong class: `"/alerts"` |
+| `tags` | không | `None` | nhóm trong trang `/docs`; thường để đúng một tên module |
+| `guards` | không | `()` | guard chạy trước MỌI route của class — xem [operations.md](operations.md#guard) |
+| *(còn lại)* | không | — | mọi tham số khác chuyển thẳng cho `APIRouter` của FastAPI: `dependencies`, `responses`, `deprecated`… |
+
+### Tham số của `@get` / `@post` / `@put` / `@patch` / `@delete`
+
+| Tham số | Bắt buộc | Mặc định | Để làm gì |
+|---|---|---|---|
+| `path` | không | `""` | phần đường dẫn nối sau `prefix`. `""` là chính `prefix`; `"/{alert_id}"` là route động |
+| *(còn lại)* | không | — | chuyển thẳng cho `add_api_route` của FastAPI — hay dùng nhất: `response_model`, `status_code`, `summary`, `guards` |
+
+`guards` khai ở route thì **cộng dồn** với `guards` của class, chạy sau.
+
+```python
+@controller(prefix="/alerts", tags=["alerts"], guards=[RequireHeader])
+class AlertController:
+    @get("/{alert_id}", response_model=AlertOut, summary="Một cảnh báo")
+    async def detail(self, alert_id: str) -> AlertOut: ...
+
+    @delete("/{alert_id}", status_code=204, guards=[ChiAdmin])
+    async def remove(self, alert_id: str) -> None: ...
+```
+
+### Tham số của `@injectable`
+
+| Tham số | Bắt buộc | Mặc định | Để làm gì |
+|---|---|---|---|
+| `scope` | không | `Scope.SINGLETON` | `SINGLETON` = một bản cho cả app. `Scope.REQUEST` = mỗi request một bản mới |
+
+**Singleton không được nhận provider request-scoped qua `__init__`** — nó sống
+lâu hơn request nên sẽ giữ mãi bản của request đầu tiên. Khung chặn thẳng lúc
+dựng, kèm câu chỉ đường: hoặc cho nó `scope=Scope.REQUEST`, hoặc gọi
+`container.resolve()` ngay trong method.
+
 ### `def` thường hay `async def`?
 
 Đúng luật của FastAPI, khung không đổi gì:
@@ -288,7 +334,7 @@ truy vấn database thật (1–10 ms) thì dưới 2%.
 fam lint                      # ruff trên `src` (mặc định): F, E, W, I, B, UP, SIM, RUF, BLE
 fam lint fastapi_modular src tests  # soi cả thư viện và test — dùng cái này khi phát triển repo
 fam lint --fix                # tự sửa phần sửa được
-fam test       # 1097 test trên backend memory (292 test nữa cần hạ tầng hoặc driver thật)
+fam test       # 1163 test trên backend memory (424 test nữa cần hạ tầng hoặc driver thật)
 ```
 
 Cấu hình ở [`ruff.toml`](../ruff.toml). Rule `BLE` được bật có chủ ý: mỗi