@starci/skills 1.1.0

package/knowledge/patterns/be/imports.vi.md

@@ -0,0 +1,79 @@
+# Import
+
+Tệp này trả lời một câu hỏi: cho một tệp backend, nó được import gì, qua đường dẫn nào, theo kiểu
+nào, và theo thứ tự nào?
+
+Nguồn: `tsconfig.json` (`paths`), `jest.config.ts` (`moduleNameMapper`), `eslint.config.mjs`,
+`features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`features/api/core/graphql/queries/courses/course/course.handler.ts`,
+`modules/platform/exceptions/errors/ai/ai-quota-exhausted.ts`,
+`modules/platform/exceptions/filters/abstract-exception-http.filter.ts`.
+
+## BE-IMPORTS-1 — Alias
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một năng lực | `@modules/<capability>/<đường dẫn sâu tới tệp>` — `import { ICQRSHandler } from "@modules/platform/cqrs/icqrs-handler"` |
+| Case 2 | Một cánh cửa | `@features/<door>/…` (dùng từ `apps/` và kiểm thử) |
+| Case 3 | Trợ giúp kiểm thử | `import { makeEntityManagerMock } from "@tests/mocks/entity-manager.mock"` |
+| Case 4 | Trong một đơn vị | `./add-to-cart.command`, `./graphql-types/request`, `./add-to-cart.service` |
+| Case 5 | Ngược lên trong cùng cánh cửa | `import { ExecuteParams } from "../../../../types/execute"` — 290 tệp dưới `features` dùng đường dẫn tương đối này; 0 tệp dùng `@features/api/core/types/execute` (lint `no-self-module-alias`) |
+| Case 6 | Trong cây exception | `import { AbstractException } from "../abstract"` |
+
+## BE-IMPORTS-2 — Kiểu ngoặc
+
+Mọi import đều nhiều dòng, một binding mỗi dòng, dấu phẩy cuối. Lint `object-curly-newline` với
+`ImportDeclaration: "always"` ép điều này.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Một binding | `import {\n    Injectable,\n} from "@nestjs/common"` |
+| Case 2 | Nhiều binding | `import {\n    CommandHandler,\n    ICommandHandler,\n} from "@nestjs/cqrs"` |
+| Case 3 | Chỉ kiểu | `import type {\n    EntityManager,\n} from "typeorm"`; `import type {\n    AbstractExceptionMetadata,\n} from "../abstract"` (1388 trên 4463 tệp dùng `import type`) |
+
+## BE-IMPORTS-3 — Thứ tự
+
+Không bị lint ép. Import đầu tiên chiếm ưu thế trong tệp đơn vị GraphQL là framework Nest.
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Framework trước | `@nestjs/graphql`, `@nestjs/common`, `@nestjs/cqrs` (import đầu tiên ở 303 trên 398 tệp GraphQL được lấy mẫu) |
+| Case 2 | Rồi năng lực | `@modules/api/…`, `@modules/integrations/…`, `@modules/platform/…`, `@modules/databases/…` (46 tệp bắt đầu ở đây) |
+| Case 3 | Rồi tương đối | `../../../../types/execute` (41 tệp bắt đầu ở đây), rồi `./…` sau cùng (7) |
+| Case 4 | Lệch | `add-to-cart.handler.ts` mở bằng `@modules/platform/cqrs/icqrs-handler` và xen `@nestjs/common` sau nhiều import `@modules`; thứ tự trên là ưu thế, không phải toàn thể |
+
+## BE-IMPORTS-4 — Chiều phân tầng
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | `features` → `modules` | luôn được phép: handler import entity, exception, decorator từ `@modules/…` |
+| Case 2 | `modules` → `features` | không được phép (lint `no-capability-imports-features`); 6 tệp không phải spec dưới `modules/bussiness/{daily-quest,flashcard,kpi-reward,streak,weekly-challenge}` vẫn làm vậy — ghi nhận là nợ, không phải mẫu |
+| Case 3 | `modules/**/*.module.ts` → module khác trong repo | không import; module năng lực được đăng ký `isGlobal: true` ở gốc app (lint `no-non-global-module-import`, ở mức error cho cả `src/modules` lẫn `src/features`) |
+| Case 4 | Barrel thư mục | không tồn tại để import; mọi import gọi thẳng tên tệp (lint `must-deep-module-import`, `no-folder-reexport`) |
+| Case 5 | Thoát tương đối qua năng lực khác | `from "../../modules/…"` xuất hiện ở 0 tệp (lint `no-relative-capability-escape`) |
+
+## BE-IMPORTS-5 — Một đơn vị GraphQL import gì
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Handler | `@modules/platform/cqrs/icqrs-handler`, entity từ `@modules/databases/postgresql/primary/entities/*.entity`, exception từ `@modules/platform/exceptions/errors/<domain>/<name>`, `@nestjs/common`, `@nestjs/cqrs`, `typeorm` (kiểu), `./<name>.command` |
+| Case 2 | Resolver | `@nestjs/graphql`, `@nestjs/common`, `@modules/api/apollo/server/decorators/locale.decorators`, `@modules/api/apollo/server/interceptors/graphql-transform.interceptor`, `@modules/integrations/keycloak/guards/keycloak-auth-graphql.guard`, `@modules/integrations/keycloak/keycloak.decorators`, `@modules/platform/throttler/*`, `./graphql-types/request`, `./graphql-types/response`, `./<name>.service` |
+| Case 3 | Response | `@nestjs/graphql`, `@modules/api/apollo/server/graphql-types/object-types/graphql-response`, `@modules/api/apollo/server/types/graphql-response`, entity |
+| Case 4 | Module | `@nestjs/common` và bốn tệp anh em |
+
+## BE-IMPORTS-6 — Bị cấm
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Default export | không có (lint `no-default-export`; các điểm vào vòng đời Jest được miễn) |
+| Case 2 | `process.env` | chỉ `src/modules/platform/env/utils/parse-env.ts`; mọi nơi khác gọi `envConfig()` |
+| Case 3 | `console.*` | lint error trong `src/**`; 188 tệp ghi log qua `WinstonService`, còn sót 12 chỗ `console.` |
+| Case 4 | `Logger` của Nest | không dùng (lint `no-nest-logger`, `no-framework-logger`) |
+| Case 5 | Token cache thô ngoài module cache | lint `must-use-cache-service` |
+
+## BE-IMPORTS-7 — Jest nhìn thấy cùng alias
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | `jest.config.ts` | `moduleNameMapper: { "^@modules/(.*)$": "<rootDir>/src/modules/$1", "^@features/(.*)$": "<rootDir>/src/features/$1", "^@tests/(.*)$": "<rootDir>/src/tests/$1" }` |
+| Case 2 | Spec giả lập một đường dẫn module | `jest.mock("@modules/platform/env/config", () => ({ envConfig: () => ({ … }) }))` |

package/knowledge/patterns/be/naming.md

@@ -0,0 +1,87 @@
+# Naming
+
+This file answers one question: given a backend file, class, type, constant or method, what is it
+called?
+
+Sources: `features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`features/api/core/graphql/queries/courses/course/*`, `modules/platform/exceptions/errors/**`,
+`modules/databases/postgresql/primary/enums/locale.ts`, `modules/ai/ai-entitlement.service.ts`,
+`modules/ai/constants/`, `modules/api/apollo/server/interceptors/graphql-transform.interceptor.ts`.
+
+## BE-NAMING-1 — Files: kebab-case plus a role suffix
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | GraphQL unit | `add-to-cart.handler.ts`, `add-to-cart.service.ts`, `add-to-cart.resolver.ts`, `add-to-cart.command.ts`, `course.query.ts`, `add-to-cart.module.ts`, `add-to-cart.module-definition.ts` |
+| Case 2 | Capability | `winston.service.ts`, `winston.providers.ts`, `winston.decorators.ts`, `keycloak-auth-graphql.guard.ts`, `graphql-transform.interceptor.ts`, `abstract-exception-http.filter.ts` |
+| Case 3 | Data | `cart-item.entity.ts`, `enums/locale.ts`, `kpi-current.util.ts` |
+| Case 4 | Exception | `errors/courses/challenge-not-found.ts` — no suffix (289 of 294) |
+| Case 5 | Spec | same basename plus `.spec` / `.int-spec`: `add-to-cart.handler.spec.ts`, `schema-builds.int-spec.ts` |
+| Case 6 | Migration | `1719200000000-AddIsEnrolledToEnrollments.ts` |
+
+## BE-NAMING-2 — Classes: PascalCase subject plus role
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Handler / Service / Resolver | `AddToCartHandler`, `AddToCartService`, `AddToCartResolver`, `CourseHandler` (154 `…Handler`, 701 `…Service`, 309 `…Resolver`) |
+| Case 2 | Message | `AddToCartCommand` (83), `CourseQuery` (67) |
+| Case 3 | GraphQL types | `AddToCartRequest` (209 `…Request`), `AddToCartResponse` (303 `…Response`) |
+| Case 4 | Unit module | `AddToCartSingleMutationModule extends ConfigurableModuleClass`; query units `…SingleQueryModule` |
+| Case 5 | Capability module | `AiModule`, `AiBalancerModule`, `WinstonModule` (552 `…Module`) |
+| Case 6 | Entity | `CartItemEntity`, `CourseEntity`, `EnrollmentEntity`, `UserEntity` (200) |
+| Case 7 | Others | `KeycloakAuthGraphQLGuard`, `GraphQLTransformInterceptor`, `AbstractExceptionHttpFilter`, `ICQRSHandler` (abstract base, `I` prefix kept) |
+
+## BE-NAMING-3 — Exception identity
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Class | `ChallengeNotFoundException`, `AiQuotaExhaustedException` — ends in `Exception` (337; lint `exception-name-ends-in-exception`) |
+| Case 2 | Code | `"CHALLENGE_NOT_FOUND_EXCEPTION"`, `"AI_QUOTA_EXHAUSTED_EXCEPTION"` — the class name in UPPER_SNAKE (lint `exception-code-matches-class-name`) |
+| Case 3 | Metadata | `interface ChallengeNotFoundExceptionMetadata extends AbstractExceptionMetadata` (285 of 294 files; lint `exception-metadata-type-named-for-class`) |
+| Case 4 | Message | a short sentence: `"Challenge not found"`, `` `AI quota exhausted (${window})` `` |
+
+## BE-NAMING-4 — Enums
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Declaration | `export enum Locale { Vi = "vi", En = "en" }`, `export enum ActionType { … }` — PascalCase name and members, string values (137 enums, 0 `const enum`) |
+| Case 2 | GraphQL registration | `export const GraphQLTypeLocale = createEnumType(Locale)` then `registerEnumType(GraphQLTypeLocale, { name: "Locale", … })` |
+| Case 3 | Log identity | `WinstonLog.HttpExceptionLogged` — an enum member, never a string message |
+| Case 4 | Throttle level | `ThrottlerConfig.Medium` |
+
+## BE-NAMING-5 — Constants
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Module-level value | `const SUCCESS_MESSAGE_METADATA = "graphqlSuccessMessage"`, `TIER_ALLOWED_CATEGORIES`, `const POSTGRESQL_PRIMARY = "primary"` (194 exported UPPER_SNAKE consts) |
+| Case 2 | Constants file | `modules/ai/constants/ai-entitlement.constants.ts`, `constants/credit-cost.ts` |
+| Case 3 | Exported function value | camelCase arrow: `export const getKpiCurrentValues = (stats: UserStatsResult): Record<KpiKey, number> => …`, `export const GraphQLSuccessMessage = (message) => SetMetadata(…)` (decorator factories keep PascalCase) |
+| Case 4 | Spec fixtures | `const BASE_CREDITS_5H = 30`, `const futureDate = (): Date => …` |
+
+## BE-NAMING-6 — Methods
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Handler body | `protected override async process(command: AddToCartCommand)` — always `process` (140/140) |
+| Case 2 | Service and resolver door | `async execute(params: ExecuteParams<AddToCartRequest>)` |
+| Case 3 | Capability service | verbs: `resolve`, `consume`, `history`, `snapshot`, `assertNotOverQuota`, `getSettings`, `grantTier` (`AiEntitlementService`) |
+| Case 4 | Not a bare verb export | lint `no-bare-verb-export`; `getKpiCurrentValues`, not `get` |
+| Case 5 | No version in a name | lint `no-version-in-name` |
+
+## BE-NAMING-7 — Type names
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Input object | `…Params` (614 interfaces): `ExecuteParams<T>`, `UseQueryCourseSwrParams` |
+| Case 2 | Output object | `…Result` (216): `UserStatsResult` |
+| Case 3 | Options | `…Options` (35) |
+| Case 4 | Exception payload | `…ExceptionMetadata` (290) |
+| Case 5 | Plain interface for a decorated class | `IAbstractGraphQLResponse<T>` beside `AbstractGraphQLResponse` |
+
+## BE-NAMING-8 — GraphQL surface
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Field name | camelCase in the decorator: `@Mutation(() => AddToCartResponse, { name: "addToCart", … })` |
+| Case 2 | Argument | always `"request"`: `@Args("request", { description: "Course id to add to the cart." }) request: AddToCartRequest` |
+| Case 3 | Own decorators | `@InjectPrimaryPostgreSQLEntityManager()`, `@KeycloakGraphQLUser()`, `@GraphQLLocale()`, `@UseThrottler(…)`, `@GraphQLSuccessMessage({…})` |

package/knowledge/patterns/be/naming.vi.md

@@ -0,0 +1,87 @@
+# Đặt tên
+
+Tệp này trả lời một câu hỏi: cho một tệp, lớp, kiểu, hằng hay phương thức backend, nó được gọi là
+gì?
+
+Nguồn: `features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`features/api/core/graphql/queries/courses/course/*`, `modules/platform/exceptions/errors/**`,
+`modules/databases/postgresql/primary/enums/locale.ts`, `modules/ai/ai-entitlement.service.ts`,
+`modules/ai/constants/`, `modules/api/apollo/server/interceptors/graphql-transform.interceptor.ts`.
+
+## BE-NAMING-1 — Tệp: kebab-case cộng hậu tố vai trò
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đơn vị GraphQL | `add-to-cart.handler.ts`, `add-to-cart.service.ts`, `add-to-cart.resolver.ts`, `add-to-cart.command.ts`, `course.query.ts`, `add-to-cart.module.ts`, `add-to-cart.module-definition.ts` |
+| Case 2 | Năng lực | `winston.service.ts`, `winston.providers.ts`, `winston.decorators.ts`, `keycloak-auth-graphql.guard.ts`, `graphql-transform.interceptor.ts`, `abstract-exception-http.filter.ts` |
+| Case 3 | Dữ liệu | `cart-item.entity.ts`, `enums/locale.ts`, `kpi-current.util.ts` |
+| Case 4 | Exception | `errors/courses/challenge-not-found.ts` — không hậu tố (289 trên 294) |
+| Case 5 | Spec | cùng tên gốc cộng `.spec` / `.int-spec`: `add-to-cart.handler.spec.ts`, `schema-builds.int-spec.ts` |
+| Case 6 | Migration | `1719200000000-AddIsEnrolledToEnrollments.ts` |
+
+## BE-NAMING-2 — Lớp: chủ thể PascalCase cộng vai trò
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Handler / Service / Resolver | `AddToCartHandler`, `AddToCartService`, `AddToCartResolver`, `CourseHandler` (154 `…Handler`, 701 `…Service`, 309 `…Resolver`) |
+| Case 2 | Thông điệp | `AddToCartCommand` (83), `CourseQuery` (67) |
+| Case 3 | Kiểu GraphQL | `AddToCartRequest` (209 `…Request`), `AddToCartResponse` (303 `…Response`) |
+| Case 4 | Module đơn vị | `AddToCartSingleMutationModule extends ConfigurableModuleClass`; đơn vị query là `…SingleQueryModule` |
+| Case 5 | Module năng lực | `AiModule`, `AiBalancerModule`, `WinstonModule` (552 `…Module`) |
+| Case 6 | Entity | `CartItemEntity`, `CourseEntity`, `EnrollmentEntity`, `UserEntity` (200) |
+| Case 7 | Khác | `KeycloakAuthGraphQLGuard`, `GraphQLTransformInterceptor`, `AbstractExceptionHttpFilter`, `ICQRSHandler` (lớp gốc trừu tượng, giữ tiền tố `I`) |
+
+## BE-NAMING-3 — Danh tính exception
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Lớp | `ChallengeNotFoundException`, `AiQuotaExhaustedException` — kết thúc bằng `Exception` (337; lint `exception-name-ends-in-exception`) |
+| Case 2 | Mã | `"CHALLENGE_NOT_FOUND_EXCEPTION"`, `"AI_QUOTA_EXHAUSTED_EXCEPTION"` — tên lớp viết UPPER_SNAKE (lint `exception-code-matches-class-name`) |
+| Case 3 | Metadata | `interface ChallengeNotFoundExceptionMetadata extends AbstractExceptionMetadata` (285 trên 294 tệp; lint `exception-metadata-type-named-for-class`) |
+| Case 4 | Thông điệp | một câu ngắn: `"Challenge not found"`, `` `AI quota exhausted (${window})` `` |
+
+## BE-NAMING-4 — Enum
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Khai báo | `export enum Locale { Vi = "vi", En = "en" }`, `export enum ActionType { … }` — tên và thành viên PascalCase, giá trị chuỗi (137 enum, 0 `const enum`) |
+| Case 2 | Đăng ký GraphQL | `export const GraphQLTypeLocale = createEnumType(Locale)` rồi `registerEnumType(GraphQLTypeLocale, { name: "Locale", … })` |
+| Case 3 | Danh tính log | `WinstonLog.HttpExceptionLogged` — một thành viên enum, không bao giờ là chuỗi thông điệp |
+| Case 4 | Mức throttle | `ThrottlerConfig.Medium` |
+
+## BE-NAMING-5 — Hằng
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Giá trị cấp module | `const SUCCESS_MESSAGE_METADATA = "graphqlSuccessMessage"`, `TIER_ALLOWED_CATEGORIES`, `const POSTGRESQL_PRIMARY = "primary"` (194 hằng UPPER_SNAKE được export) |
+| Case 2 | Tệp hằng | `modules/ai/constants/ai-entitlement.constants.ts`, `constants/credit-cost.ts` |
+| Case 3 | Giá trị hàm được export | arrow camelCase: `export const getKpiCurrentValues = (stats: UserStatsResult): Record<KpiKey, number> => …`, `export const GraphQLSuccessMessage = (message) => SetMetadata(…)` (nhà máy decorator giữ PascalCase) |
+| Case 4 | Fixture trong spec | `const BASE_CREDITS_5H = 30`, `const futureDate = (): Date => …` |
+
+## BE-NAMING-6 — Phương thức
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Thân handler | `protected override async process(command: AddToCartCommand)` — luôn là `process` (140/140) |
+| Case 2 | Cửa của service và resolver | `async execute(params: ExecuteParams<AddToCartRequest>)` |
+| Case 3 | Service năng lực | động từ: `resolve`, `consume`, `history`, `snapshot`, `assertNotOverQuota`, `getSettings`, `grantTier` (`AiEntitlementService`) |
+| Case 4 | Không export động từ trần | lint `no-bare-verb-export`; `getKpiCurrentValues`, không phải `get` |
+| Case 5 | Không phiên bản trong tên | lint `no-version-in-name` |
+
+## BE-NAMING-7 — Tên kiểu
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Object đầu vào | `…Params` (614 interface): `ExecuteParams<T>`, `UseQueryCourseSwrParams` |
+| Case 2 | Object đầu ra | `…Result` (216): `UserStatsResult` |
+| Case 3 | Tùy chọn | `…Options` (35) |
+| Case 4 | Payload exception | `…ExceptionMetadata` (290) |
+| Case 5 | Interface thuần cho một lớp có decorator | `IAbstractGraphQLResponse<T>` bên cạnh `AbstractGraphQLResponse` |
+
+## BE-NAMING-8 — Bề mặt GraphQL
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Tên trường | camelCase trong decorator: `@Mutation(() => AddToCartResponse, { name: "addToCart", … })` |
+| Case 2 | Đối số | luôn là `"request"`: `@Args("request", { description: "Course id to add to the cart." }) request: AddToCartRequest` |
+| Case 3 | Decorator của mình | `@InjectPrimaryPostgreSQLEntityManager()`, `@KeycloakGraphQLUser()`, `@GraphQLLocale()`, `@UseThrottler(…)`, `@GraphQLSuccessMessage({…})` |

package/knowledge/patterns/be/test.md

@@ -0,0 +1,79 @@
+# Test
+
+This file answers one question: given a backend unit, where does its spec live, how is the subject
+built, what does it assert, and what does it leave alone?
+
+Sources: `jest.config.ts`, `features/api/core/graphql/mutations/courses/add-to-cart/add-to-cart.handler.spec.ts`,
+`modules/ai/ai-entitlement.service.spec.ts`,
+`modules/ai/ping/classes/abstract-provider-ping.service.spec.ts`, `src/tests/**`, `eslint.config.mjs`.
+
+## BE-TEST-1 — Placement and lanes
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Unit | `<name>.spec.ts` beside `<name>.ts` (875; lint `unit-test-colocated`) |
+| Case 2 | Handler twin | `add-to-cart.handler.spec.ts` beside the handler (118 of 149 handlers; lint `handler-has-twin-spec`) |
+| Case 3 | Service twin | 271 of 396 services under `src/modules` |
+| Case 4 | Integration | `*.int-spec.ts` (7), Testcontainers, `globalSetup: src/tests/helpers/e2e-setup.ts`, `testTimeout: 120_000` |
+| Case 5 | E2E and harness | `*.e2e-spec.ts`, `*.harness-spec.ts` under `src/tests/<lane>`, excluded from `unit` by suffix |
+| Case 6 | Projects | `projects: [{ displayName: "unit", testMatch: ["**/*.spec.ts"], testPathIgnorePatterns: ["\\.int-spec\\.ts$", "\\.e2e-spec\\.ts$", "\\.harness-spec\\.ts$"] }, { displayName: "integration", testMatch: ["**/*.int-spec.ts"], … }]` |
+| Case 7 | Runner | `jest` with `ts-jest` (`diagnostics: false`), `testEnvironment: "node"` |
+
+## BE-TEST-2 — Handler spec: construct directly, cast the mocks
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Subject | `const handler = new AddToCartHandler({ exists } as never)` — the entity manager is a bare object of `jest.fn()`; `as never` appears in 496 of 875 specs, `as unknown as` in 323 |
+| Case 2 | Message factory | `const command = (courseId: string) => new AddToCartCommand({ request: { courseId }, user: { id: "u1" } } as never)` |
+| Case 3 | Ordered mock answers | `const exists = jest.fn().mockResolvedValueOnce(false)`; later `exists.mockResolvedValueOnce(true).mockResolvedValueOnce(true)` |
+| Case 4 | Call through the public door | `handler.execute(command("missing"))`, never `process` |
+
+## BE-TEST-3 — Service spec: a testing module with shared mocks
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Module | `Test.createTestingModule({ … })` (274 specs) with `getEntityManagerToken(POSTGRESQL_PRIMARY)` |
+| Case 2 | Entity manager | `import { makeEntityManagerMock } from "@tests/mocks/entity-manager.mock"` with `EntityManagerMock`, `QueryBuilderMock` types |
+| Case 3 | Config | `jest.mock("@modules/platform/env/config", () => ({ envConfig: () => ({ ai: { ping: mockPingConfig } }) }))` |
+| Case 4 | Abstract class | a local subclass: `class TestPingService extends AbstractProviderPingService { protected readonly provider = ModelProvider.OpenAI; execute = jest.fn()…; protected executePing(key: string) { return this.execute(key) } }` |
+| Case 5 | Fixture constants | documented UPPER_SNAKE: `/** Free base credit caps the mocked quota config hands back (credits per window). */ const BASE_CREDITS_5H = 30` |
+
+## BE-TEST-4 — What is asserted
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | The exception type | `await expect(handler.execute(command("missing"))).rejects.toBeInstanceOf(CourseNotFoundException)` (262 specs use `rejects.toBeInstanceOf` / `toThrow(`; 49 match a message string) |
+| Case 2 | Ordering of side effects | `await expect(handler.execute(…)).rejects.toBeInstanceOf(UserNotFoundException); expect(exists).not.toHaveBeenCalled()` |
+| Case 3 | The returned row | `await expect(handler.execute(command("one"))).resolves.toBe(existing)`; `.resolves.toEqual({ id: "cart-2" })` |
+| Case 4 | Persisted argument | `expect(save).toHaveBeenCalledWith({ id: "draft" })` |
+| Case 5 | `it` phrasing | verb first: `throws` (83), `rejects` (65), `returns` (50), `refuses` (25), `maps`, `creates` — e.g. `it("rejects anonymous callers before querying course state", …)` |
+
+## BE-TEST-5 — What is not asserted
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | A call alone | a spec that only proves a mock was invoked (lint `no-call-only-spec`) |
+| Case 2 | Envelope instead of state, in e2e | an e2e step asserts the persisted row, not `success: true` (lint `e2e-asserts-persisted-state`) |
+| Case 3 | Elapsed time | no `sleep` in a flow; poll for state (lint `no-sleep-in-flow`) |
+| Case 4 | Live model output, in e2e | no provider call in e2e (`no-model-call-in-e2e`); the harness lane owns it (`harness-calls-provider-directly`) |
+| Case 5 | A branch inside one step | one step proves one outcome (lint `no-branch-in-flow-step`) |
+
+## BE-TEST-6 — Names and layout
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | `describe` | the class: `describe("AddToCartHandler", () => { … })`, `describe("AbstractProviderPingService", …)` (367 `…Service`, 121 `…Handler`, 58 `…Resolver`) |
+| Case 2 | Formatting | callbacks on a new line: `describe("AddToCartHandler",\n    () => {` and `it("…",\n        async () => {` — the repo's `function-call-argument-newline: always` rule |
+| Case 3 | Imports | same multi-line brace style as source; subject first, then exceptions, then mocks |
+
+## BE-TEST-7 — Coverage and lint carve-outs
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Coverage denominator | `collectCoverageFrom: ["src/**/*.ts", "apps/**/*.ts", "!src/tests/**", "!**/*.spec.ts", "!**/*.int-spec.ts", "!**/*.e2e-spec.ts", "!**/*.harness-spec.ts", "!**/*.d.ts", "!**/main.ts"]` |
+| Case 2 | Allowed only in specs | `as unknown as X`, `process.env` (under `src/tests/**`), `new Error(…)` in `src/tests/**` and `apps/*/test/**` |
+
+## Open question
+
+31 of 149 handlers and 125 of 396 services have no colocated spec today. The twin is the pattern
+(lint rule exists); the gap is recorded, not excused.

package/knowledge/patterns/be/test.vi.md

@@ -0,0 +1,79 @@
+# Kiểm thử
+
+Tệp này trả lời một câu hỏi: cho một đơn vị backend, spec của nó nằm đâu, đối tượng được dựng
+thế nào, khẳng định gì, và để yên điều gì?
+
+Nguồn: `jest.config.ts`, `features/api/core/graphql/mutations/courses/add-to-cart/add-to-cart.handler.spec.ts`,
+`modules/ai/ai-entitlement.service.spec.ts`,
+`modules/ai/ping/classes/abstract-provider-ping.service.spec.ts`, `src/tests/**`, `eslint.config.mjs`.
+
+## BE-TEST-1 — Vị trí và làn
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đơn vị | `<name>.spec.ts` cạnh `<name>.ts` (875; lint `unit-test-colocated`) |
+| Case 2 | Bản sao của handler | `add-to-cart.handler.spec.ts` cạnh handler (118 trên 149 handler; lint `handler-has-twin-spec`) |
+| Case 3 | Bản sao của service | 271 trên 396 service dưới `src/modules` |
+| Case 4 | Tích hợp | `*.int-spec.ts` (7), Testcontainers, `globalSetup: src/tests/helpers/e2e-setup.ts`, `testTimeout: 120_000` |
+| Case 5 | Đầu cuối và harness | `*.e2e-spec.ts`, `*.harness-spec.ts` dưới `src/tests/<lane>`, bị loại khỏi `unit` theo hậu tố |
+| Case 6 | Projects | `projects: [{ displayName: "unit", testMatch: ["**/*.spec.ts"], testPathIgnorePatterns: ["\\.int-spec\\.ts$", "\\.e2e-spec\\.ts$", "\\.harness-spec\\.ts$"] }, { displayName: "integration", testMatch: ["**/*.int-spec.ts"], … }]` |
+| Case 7 | Bộ chạy | `jest` với `ts-jest` (`diagnostics: false`), `testEnvironment: "node"` |
+
+## BE-TEST-2 — Spec handler: dựng trực tiếp, ép kiểu các mock
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đối tượng | `const handler = new AddToCartHandler({ exists } as never)` — entity manager là một object trần gồm `jest.fn()`; `as never` xuất hiện ở 496 trên 875 spec, `as unknown as` ở 323 |
+| Case 2 | Nhà máy thông điệp | `const command = (courseId: string) => new AddToCartCommand({ request: { courseId }, user: { id: "u1" } } as never)` |
+| Case 3 | Câu trả lời mock theo thứ tự | `const exists = jest.fn().mockResolvedValueOnce(false)`; sau đó `exists.mockResolvedValueOnce(true).mockResolvedValueOnce(true)` |
+| Case 4 | Gọi qua cửa công khai | `handler.execute(command("missing"))`, không bao giờ gọi `process` |
+
+## BE-TEST-3 — Spec service: một testing module với mock dùng chung
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Module | `Test.createTestingModule({ … })` (274 spec) với `getEntityManagerToken(POSTGRESQL_PRIMARY)` |
+| Case 2 | Entity manager | `import { makeEntityManagerMock } from "@tests/mocks/entity-manager.mock"` cùng các kiểu `EntityManagerMock`, `QueryBuilderMock` |
+| Case 3 | Cấu hình | `jest.mock("@modules/platform/env/config", () => ({ envConfig: () => ({ ai: { ping: mockPingConfig } }) }))` |
+| Case 4 | Lớp trừu tượng | một lớp con cục bộ: `class TestPingService extends AbstractProviderPingService { protected readonly provider = ModelProvider.OpenAI; execute = jest.fn()…; protected executePing(key: string) { return this.execute(key) } }` |
+| Case 5 | Hằng fixture | UPPER_SNAKE có chú thích: `/** Free base credit caps the mocked quota config hands back (credits per window). */ const BASE_CREDITS_5H = 30` |
+
+## BE-TEST-4 — Điều được khẳng định
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Kiểu exception | `await expect(handler.execute(command("missing"))).rejects.toBeInstanceOf(CourseNotFoundException)` (262 spec dùng `rejects.toBeInstanceOf` / `toThrow(`; 49 so khớp chuỗi thông điệp) |
+| Case 2 | Thứ tự tác dụng phụ | `await expect(handler.execute(…)).rejects.toBeInstanceOf(UserNotFoundException); expect(exists).not.toHaveBeenCalled()` |
+| Case 3 | Hàng được trả về | `await expect(handler.execute(command("one"))).resolves.toBe(existing)`; `.resolves.toEqual({ id: "cart-2" })` |
+| Case 4 | Đối số được lưu | `expect(save).toHaveBeenCalledWith({ id: "draft" })` |
+| Case 5 | Cách viết `it` | động từ đứng đầu: `throws` (83), `rejects` (65), `returns` (50), `refuses` (25), `maps`, `creates` — ví dụ `it("rejects anonymous callers before querying course state", …)` |
+
+## BE-TEST-5 — Điều không được khẳng định
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Chỉ một lời gọi | một spec chỉ chứng minh mock đã được gọi (lint `no-call-only-spec`) |
+| Case 2 | Phong bì thay vì trạng thái, trong e2e | một bước e2e khẳng định hàng đã lưu, không phải `success: true` (lint `e2e-asserts-persisted-state`) |
+| Case 3 | Thời gian trôi | không `sleep` trong luồng; thăm dò trạng thái (lint `no-sleep-in-flow`) |
+| Case 4 | Đầu ra mô hình thật, trong e2e | không gọi nhà cung cấp trong e2e (`no-model-call-in-e2e`); làn harness sở hữu việc đó (`harness-calls-provider-directly`) |
+| Case 5 | Một nhánh trong một bước | một bước chứng minh một kết quả (lint `no-branch-in-flow-step`) |
+
+## BE-TEST-6 — Tên và bố cục
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | `describe` | tên lớp: `describe("AddToCartHandler", () => { … })`, `describe("AbstractProviderPingService", …)` (367 `…Service`, 121 `…Handler`, 58 `…Resolver`) |
+| Case 2 | Định dạng | callback xuống dòng mới: `describe("AddToCartHandler",\n    () => {` và `it("…",\n        async () => {` — luật `function-call-argument-newline: always` của repo |
+| Case 3 | Import | cùng kiểu ngoặc nhiều dòng như mã nguồn; đối tượng trước, rồi exception, rồi mock |
+
+## BE-TEST-7 — Độ phủ và miễn trừ lint
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Mẫu số độ phủ | `collectCoverageFrom: ["src/**/*.ts", "apps/**/*.ts", "!src/tests/**", "!**/*.spec.ts", "!**/*.int-spec.ts", "!**/*.e2e-spec.ts", "!**/*.harness-spec.ts", "!**/*.d.ts", "!**/main.ts"]` |
+| Case 2 | Chỉ được phép trong spec | `as unknown as X`, `process.env` (dưới `src/tests/**`), `new Error(…)` trong `src/tests/**` và `apps/*/test/**` |
+
+## Câu hỏi để ngỏ
+
+31 trên 149 handler và 125 trên 396 service hôm nay chưa có spec kề bên. Bản sao là mẫu (luật lint
+đã có); khoảng trống được ghi nhận, không được bào chữa.

package/knowledge/patterns/be/typing.md

@@ -0,0 +1,73 @@
+# Typing
+
+This file answers one question: given a backend value, how is its type declared?
+
+Sources: `tsconfig.json` (`strictNullChecks: true`, `noImplicitAny: false`), `eslint.config.mjs`,
+`features/api/core/types/execute.ts`, `features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`modules/platform/exceptions/errors/abstract.ts`, `errors/ai/ai-quota-exhausted.ts`,
+`modules/api/apollo/server/types/graphql-response.ts`,
+`modules/api/apollo/server/interceptors/graphql-transform.interceptor.ts`,
+`modules/databases/postgresql/primary/enums/locale.ts`, `modules/platform/cqrs/icqrs-handler.ts`.
+
+## BE-TYPING-1 — `interface` for object shapes, `type` for aliases
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Object shape | `export interface ExecuteParams<T> { request: T; locale?: Locale; user?: UserEntity; … }` (1991 `export interface` against 197 `export type`, of which only 12 are object literals) |
+| Case 2 | Exception metadata | `export interface AiQuotaExhaustedExceptionMetadata extends AbstractExceptionMetadata { window: string }` |
+| Case 3 | Response contract | `export interface IAbstractGraphQLResponse<T = undefined> { success: boolean; message: string; data?: T; error?: string }` |
+| Case 4 | Alias | `export type GraphQLSuccessMessage = Record<Locale, string>` — shares its name with the decorator const |
+
+## BE-TYPING-2 — Named parameter types, no inline objects
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Function taking an object | `constructor({ window, originalError }: AiQuotaExhaustedExceptionMetadata)` — destructured from a named interface (lint `no-inline-param-type`, `no-inline-object-type`) |
+| Case 2 | Handler input | `process(command: AddToCartCommand)` — the class is the type |
+| Case 3 | Return | always declared on public methods: `Promise<CartItemEntity>`, `Record<KpiKey, number>`, `Observable<GraphQLResponse<T>>` |
+| Case 4 | Primitive param | positional, annotated: `execute(key: string)`, `getOriginalError(): Error` |
+
+## BE-TYPING-3 — `readonly`
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Injected dependency | `private readonly entityManager: EntityManager` (2489 against 26 without `readonly`) |
+| Case 2 | Message payload | `constructor(readonly params: ExecuteParams<AddToCartRequest>) {}` |
+| Case 3 | Exception fields | `readonly code: string`, `readonly metadata?: Record<string, unknown>`, `readonly httpStatus?: number` |
+| Case 4 | Decorated GraphQL field | not `readonly`: `@Field(() => ID, { description: "Course id." }) courseId: string` — class-validator/GraphQL classes are mutable DTOs |
+
+## BE-TYPING-4 — Enums
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Declaration | `export enum Locale { Vi = "vi", En = "en" }` — string-valued, PascalCase members (137 enums; `const enum` 0, lint `no-const-enum`) |
+| Case 2 | Home | `modules/databases/postgresql/primary/enums/` (76 files), plus per-module `enums/` folders (`platform/exceptions/enums`, `integrations/cache/enums`, `ai/balancer/enums`) |
+| Case 3 | GraphQL exposure | `export const GraphQLTypeLocale = createEnumType(Locale)` + `registerEnumType(GraphQLTypeLocale, { name: "Locale", description: "…", valuesMap: { [Locale.Vi]: { … } } })` |
+| Case 4 | Boolean on an entity | `isEnrolled: true` in `where` — `is` prefix |
+
+## BE-TYPING-5 — `unknown`, never `any`
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Unknown payload | `readonly metadata?: Record<string, unknown>` |
+| Case 2 | Narrowing an error | `originalError: error instanceof Error ? error : undefined`; `error instanceof Error ? error : new Error(String(error))` |
+| Case 3 | Apollo's untyped error | `const original = (error as { originalError?: unknown })?.originalError ?? error; if (original instanceof AbstractException) { … }` |
+| Case 4 | Residual | 13 `any` sites in 4463 files; lint `@typescript-eslint/no-explicit-any` is at error |
+| Case 5 | Double cast | `as unknown as X` only inside `*.spec.ts` and `src/tests/**` (323 specs); banned elsewhere by `no-restricted-syntax` |
+
+## BE-TYPING-6 — Generics
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Template base | `export abstract class ICQRSHandler<TParams, TResponse = unknown>` — `T` prefix on descriptive names |
+| Case 2 | Single | `IAbstractGraphQLResponse<T = undefined>`, `GraphQLTransformInterceptor<T = unknown>` |
+| Case 3 | Static factory | `static fromJSON<T extends AbstractException>(this: new (message: string, code: string, metadata?: Record<string, unknown>) => T, json: string): T` |
+
+## BE-TYPING-7 — GraphQL classes
+
+| Case | When | Write |
+| --- | --- | --- |
+| Case 1 | Input | `@InputType({ description: "…" }) export class AddToCartRequest { @Field(() => ID, { description: "Course id." }) courseId: string }` |
+| Case 2 | Output | `@ObjectType({ description: "…" }) export class AddToCartResponse extends AbstractGraphQLResponse implements IAbstractGraphQLResponse<CartItemEntity> { @Field(() => CartItemEntity, { nullable: true, description: "…" }) data: CartItemEntity }` |
+| Case 3 | `data` nullability | always `nullable: true` — the interceptor writes `data = null` on failure |
+| Case 4 | Entity table | every `@Entity` names its table (lint `require-entity-table-name`, 181/181); no `eager: true` relations |

package/knowledge/patterns/be/typing.vi.md

@@ -0,0 +1,73 @@
+# Kiểu
+
+Tệp này trả lời một câu hỏi: cho một giá trị backend, kiểu của nó được khai báo thế nào?
+
+Nguồn: `tsconfig.json` (`strictNullChecks: true`, `noImplicitAny: false`), `eslint.config.mjs`,
+`features/api/core/types/execute.ts`, `features/api/core/graphql/mutations/courses/add-to-cart/*`,
+`modules/platform/exceptions/errors/abstract.ts`, `errors/ai/ai-quota-exhausted.ts`,
+`modules/api/apollo/server/types/graphql-response.ts`,
+`modules/api/apollo/server/interceptors/graphql-transform.interceptor.ts`,
+`modules/databases/postgresql/primary/enums/locale.ts`, `modules/platform/cqrs/icqrs-handler.ts`.
+
+## BE-TYPING-1 — `interface` cho hình dạng object, `type` cho bí danh
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Hình dạng object | `export interface ExecuteParams<T> { request: T; locale?: Locale; user?: UserEntity; … }` (1991 `export interface` so với 197 `export type`, trong đó chỉ 12 là object literal) |
+| Case 2 | Metadata exception | `export interface AiQuotaExhaustedExceptionMetadata extends AbstractExceptionMetadata { window: string }` |
+| Case 3 | Hợp đồng response | `export interface IAbstractGraphQLResponse<T = undefined> { success: boolean; message: string; data?: T; error?: string }` |
+| Case 4 | Bí danh | `export type GraphQLSuccessMessage = Record<Locale, string>` — trùng tên với const decorator |
+
+## BE-TYPING-2 — Kiểu tham số có tên, không object nội tuyến
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Hàm nhận object | `constructor({ window, originalError }: AiQuotaExhaustedExceptionMetadata)` — phá cấu trúc từ một interface có tên (lint `no-inline-param-type`, `no-inline-object-type`) |
+| Case 2 | Đầu vào handler | `process(command: AddToCartCommand)` — lớp chính là kiểu |
+| Case 3 | Trả về | luôn khai báo trên phương thức công khai: `Promise<CartItemEntity>`, `Record<KpiKey, number>`, `Observable<GraphQLResponse<T>>` |
+| Case 4 | Tham số nguyên thủy | theo vị trí, có chú kiểu: `execute(key: string)`, `getOriginalError(): Error` |
+
+## BE-TYPING-3 — `readonly`
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Phụ thuộc được tiêm | `private readonly entityManager: EntityManager` (2489 so với 26 không `readonly`) |
+| Case 2 | Payload thông điệp | `constructor(readonly params: ExecuteParams<AddToCartRequest>) {}` |
+| Case 3 | Trường exception | `readonly code: string`, `readonly metadata?: Record<string, unknown>`, `readonly httpStatus?: number` |
+| Case 4 | Trường GraphQL có decorator | không `readonly`: `@Field(() => ID, { description: "Course id." }) courseId: string` — lớp class-validator/GraphQL là DTO khả biến |
+
+## BE-TYPING-4 — Enum
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Khai báo | `export enum Locale { Vi = "vi", En = "en" }` — giá trị chuỗi, thành viên PascalCase (137 enum; `const enum` 0, lint `no-const-enum`) |
+| Case 2 | Nhà | `modules/databases/postgresql/primary/enums/` (76 tệp), cộng thư mục `enums/` theo module (`platform/exceptions/enums`, `integrations/cache/enums`, `ai/balancer/enums`) |
+| Case 3 | Phơi ra GraphQL | `export const GraphQLTypeLocale = createEnumType(Locale)` + `registerEnumType(GraphQLTypeLocale, { name: "Locale", description: "…", valuesMap: { [Locale.Vi]: { … } } })` |
+| Case 4 | Boolean trên entity | `isEnrolled: true` trong `where` — tiền tố `is` |
+
+## BE-TYPING-5 — `unknown`, không bao giờ `any`
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Payload chưa biết | `readonly metadata?: Record<string, unknown>` |
+| Case 2 | Thu hẹp một lỗi | `originalError: error instanceof Error ? error : undefined`; `error instanceof Error ? error : new Error(String(error))` |
+| Case 3 | Lỗi không kiểu của Apollo | `const original = (error as { originalError?: unknown })?.originalError ?? error; if (original instanceof AbstractException) { … }` |
+| Case 4 | Còn sót | 13 chỗ `any` trong 4463 tệp; lint `@typescript-eslint/no-explicit-any` ở mức error |
+| Case 5 | Ép kép | `as unknown as X` chỉ bên trong `*.spec.ts` và `src/tests/**` (323 spec); bị cấm nơi khác bởi `no-restricted-syntax` |
+
+## BE-TYPING-6 — Generic
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Lớp gốc khuôn | `export abstract class ICQRSHandler<TParams, TResponse = unknown>` — tiền tố `T` trên tên mô tả |
+| Case 2 | Đơn | `IAbstractGraphQLResponse<T = undefined>`, `GraphQLTransformInterceptor<T = unknown>` |
+| Case 3 | Nhà máy tĩnh | `static fromJSON<T extends AbstractException>(this: new (message: string, code: string, metadata?: Record<string, unknown>) => T, json: string): T` |
+
+## BE-TYPING-7 — Lớp GraphQL
+
+| Case | Dùng khi | Viết |
+| --- | --- | --- |
+| Case 1 | Đầu vào | `@InputType({ description: "…" }) export class AddToCartRequest { @Field(() => ID, { description: "Course id." }) courseId: string }` |
+| Case 2 | Đầu ra | `@ObjectType({ description: "…" }) export class AddToCartResponse extends AbstractGraphQLResponse implements IAbstractGraphQLResponse<CartItemEntity> { @Field(() => CartItemEntity, { nullable: true, description: "…" }) data: CartItemEntity }` |
+| Case 3 | Tính nullable của `data` | luôn `nullable: true` — interceptor ghi `data = null` khi thất bại |
+| Case 4 | Bảng của entity | mọi `@Entity` đều đặt tên bảng (lint `require-entity-table-name`, 181/181); không quan hệ `eager: true` |

package/knowledge/patterns/fe/INDEX.md

@@ -0,0 +1,29 @@
+# Frontend code patterns
+
+`knowledge/ui/` decides what the interface must be: which Grammar object renders, which gap, which
+tone. `knowledge/patterns/fe/` decides how the code that produces that interface is written: where
+a unit lives, what its files are called, how a component function is shaped, where a class string
+sits, how a failure is represented, and where the spec goes. A pattern rule never chooses a visual;
+a `ui/` rule never chooses a file name. Every rule below was extracted from
+`starci-academy-fe/src/` and `starci-academy-fe/packages/grammar/src/` by opening files and counting,
+and each table cites the files it was read from. Where the code is split, the file records the
+dominant variant with its count instead of legislating.
+
+## Catalog
+
+| Knowledge | What it decides | Rules |
+| --- | --- | --- |
+| [Folder](folder.md) | Tier directories, the file set of one unit, what a unit folder may not hold | FE-FOLDER-1 … FE-FOLDER-6 |
+| [Naming](naming.md) | Folder, export, props type, class-name export, hook, constant and spec names | FE-NAMING-1 … FE-NAMING-7 |
+| [Function](function.md) | Component shape, the `props` parameter, the three-part contract, helpers, route files | FE-FUNCTION-1 … FE-FUNCTION-7 |
+| [Imports](imports.md) | The `@/` alias, Grammar entry, import order, tier direction, the hooks barrel | FE-IMPORTS-1 … FE-IMPORTS-7 |
+| [Comment](comment.md) | Export docblocks, field docs, decision prose, `//` sentences, banned content | FE-COMMENT-1 … FE-COMMENT-5 |
+| [Typing](typing.md) | `type` over `interface`, `readonly`, literal unions, `Array<T>`, inferred returns | FE-TYPING-1 … FE-TYPING-7 |
+| [Error](error.md) | Failure as a state, the GraphQL envelope, `throw new Error`, toasts | FE-ERROR-1 … FE-ERROR-5 |
+| [Test](test.md) | Spec placement, connected versus pure spec, what is asserted, what is not | FE-TEST-1 … FE-TEST-6 |
+
+## Sources
+
+Application: `D:\Repositories\starci-academy-fe\src\` (976 non-spec TypeScript files, 497 specs).
+Grammar package: `D:\Repositories\starci-academy-fe\packages\grammar\src\`. Lint canon consulted for
+rule names only: `@starci/eslint-canon-fe` as installed under `node_modules`.

package/knowledge/patterns/fe/INDEX.vi.md

@@ -0,0 +1,29 @@
+# Mẫu mã nguồn frontend
+
+`knowledge/ui/` quyết định giao diện phải là gì: đối tượng Grammar nào được vẽ, khoảng cách nào,
+sắc thái nào. `knowledge/patterns/fe/` quyết định mã nguồn tạo ra giao diện ấy được viết ra sao:
+một đơn vị mã nằm ở đâu, các tệp của nó tên gì, hàm component có hình dạng nào, chuỗi class đặt ở
+đâu, thất bại được biểu diễn thế nào, và spec đi kèm nằm chỗ nào. Một luật mẫu không bao giờ chọn
+hình ảnh; một luật `ui/` không bao giờ chọn tên tệp. Mọi luật dưới đây được rút ra từ
+`starci-academy-fe/src/` và `starci-academy-fe/packages/grammar/src/` bằng cách mở tệp và đếm, và
+mỗi bảng đều dẫn nguồn tệp đã đọc. Nơi nào mã nguồn chia hai ngả, tệp ghi lại biến thể chiếm ưu thế
+cùng con số thay vì áp đặt.
+
+## Danh mục
+
+| Tri thức | Quyết định điều gì | Luật |
+| --- | --- | --- |
+| [Thư mục](folder.vi.md) | Thư mục theo tầng, bộ tệp của một đơn vị, thứ một thư mục đơn vị không được chứa | FE-FOLDER-1 … FE-FOLDER-6 |
+| [Đặt tên](naming.vi.md) | Tên thư mục, export, kiểu props, export class-name, hook, hằng và spec | FE-NAMING-1 … FE-NAMING-7 |
+| [Hàm](function.vi.md) | Hình dạng component, tham số `props`, hợp đồng ba phần, helper, tệp route | FE-FUNCTION-1 … FE-FUNCTION-7 |
+| [Import](imports.vi.md) | Alias `@/`, cửa vào Grammar, thứ tự import, chiều giữa các tầng, barrel hooks | FE-IMPORTS-1 … FE-IMPORTS-7 |
+| [Chú thích](comment.vi.md) | Docblock cho export, chú thích trường, văn xuôi lý giải quyết định, câu `//`, nội dung bị cấm | FE-COMMENT-1 … FE-COMMENT-5 |
+| [Kiểu](typing.vi.md) | `type` thay cho `interface`, `readonly`, union literal, `Array<T>`, kiểu trả về suy luận | FE-TYPING-1 … FE-TYPING-7 |
+| [Lỗi](error.vi.md) | Thất bại là một trạng thái, phong bì GraphQL, `throw new Error`, toast | FE-ERROR-1 … FE-ERROR-5 |
+| [Kiểm thử](test.vi.md) | Vị trí spec, spec nửa nối và nửa thuần, điều được khẳng định và điều không | FE-TEST-1 … FE-TEST-6 |
+
+## Nguồn
+
+Ứng dụng: `D:\Repositories\starci-academy-fe\src\` (976 tệp TypeScript không phải spec, 497 spec).
+Gói Grammar: `D:\Repositories\starci-academy-fe\packages\grammar\src\`. Bộ luật lint chỉ được tra để
+lấy tên luật: `@starci/eslint-canon-fe` như đã cài trong `node_modules`.