solution-erp/docs/rules.md

# Rules — Coding Conventions SOLUTION_ERP

> Nguồn duy nhất cho rules. Bất cứ commit nào vi phạm cần justify trong message.

## 1. Ngôn ngữ

| Thành phần | Ngôn ngữ |
|---|---|
| UI FE | **100% tiếng Việt** |
| Code (.cs/.ts) | **English** (tên biến/hàm/class) |
| Comment code | Tiếng Anh hoặc Việt — miễn rõ |
| Tên DB table + column | **English PascalCase** (Contracts, SupplierId) |
| Business label | Tiếng Việt (vd `"Đang soạn thảo"` cho phase 2) |
| Commit message | English hoặc Việt — preferred English |
| Doc MD (docs/) | **Tiếng Việt** (audience là người Việt) |

## 2. Backend — .NET 10

### 2.1 Clean Architecture dependency rule

```
Api → Application ← Domain
      ↑
Infrastructure ──┘
```

- **Domain:** pure, chỉ dùng `Microsoft.Extensions.Identity.Stores` (cần cho IdentityUser) — không depend ASP.NET Core framework
- **Application:** depend Domain; CQRS handlers + interfaces + DTOs + validators
- **Infrastructure:** depend Application + Domain; impl interfaces (EF, JWT, rendering, services)
- **Api:** depend Application + Infrastructure; Controllers + middleware + composition root

### 2.2 CQRS + MediatR pattern

- 1 feature = 1 file `{Verb}{Entity}Command.cs` / `{Verb}{Entity}Query.cs`
- File chứa: Command record + Validator + Handler (cùng 1 file cho compact)
- Dài thì tách: `{Feature}/Commands/{Create}/...`

**Command naming:**
```
Create{Entity}Command      // tạo mới
Update{Entity}Command      // update full
Patch{Entity}FieldCommand  // update 1 field
Delete{Entity}Command      // soft delete (default)
{Action}{Entity}Command    // action domain-specific (vd TransitionContract)
```

**Query naming:**
```
Get{Entity}Query            // single by Id
List{Entity}sQuery          // list với paging
{Entity}{Purpose}Query      // custom query (vd GetMyInboxQuery)
```

### 2.3 Validation

- FluentValidation (KHÔNG dùng DataAnnotation)
- Validator = class trong cùng file command: `{Command}Validator : AbstractValidator<{Command}>`
- Pipeline: `ValidationBehavior` auto-chạy trước Handler — throw `ValidationException` → 400 ProblemDetails

### 2.4 Error handling

- KHÔNG try-catch ở Controller
- Throw domain exception: `NotFoundException`, `ForbiddenException`, `UnauthorizedException`, `ConflictException`, `ValidationException`
- `GlobalExceptionMiddleware` map exception → HTTP status + ProblemDetails JSON
- Logging: Serilog structured, không `Console.WriteLine`

### 2.5 Async/await

- Tất cả I/O (DB, HTTP, file) PHẢI async
- Truyền `CancellationToken` mọi async call
- Tên method async: suffix `Async` (trừ ASP.NET action signature)

### 2.6 Entity rules

- Mọi entity mới extend `BaseEntity` (Id Guid + audit) hoặc `AuditableEntity` (+ soft delete)
- PK: `Id` type `Guid`, default `Guid.NewGuid()` trong constructor
- FK: `{Entity}Id` type `Guid`
- Enum: `HasConversion<int>()` trong EF config
- String: luôn `HasMaxLength(n)` trong EF config — không để `nvarchar(max)` trừ khi là JSON/rich text
- Money: `decimal` + `HasPrecision(18, 2)`
- DateTime: luôn UTC, lấy từ `IDateTime.UtcNow` (không `DateTime.Now`)
- Query filter soft delete: `HasQueryFilter(x => !x.IsDeleted)` cho AuditableEntity

### 2.7 DI registration

- Singleton: stateless services (DateTimeService, FormRenderer)
- Scoped: per-request services (JwtTokenService, ContractWorkflowService, DbContext)
- Transient: lightweight utility (hiếm dùng)

### 2.8 Package version pinning

- **KHÔNG dùng `*` hoặc `latest`** — luôn pin version cụ thể
- Check compatibility với .NET 10 trước khi add. Gotchas đã biết:
  - MediatR 14 → lỗi IMediator DI, **pin 12.4.1**
  - Swashbuckle 10 → conflict OpenApi 2, **pin 6.9.0**
- Xem [`gotchas.md`](gotchas.md) cho full list

## 3. Frontend — React 19 + Vite 8 + TS 6

### 3.1 Named export, không default export

```tsx
// ✅
export function SuppliersPage() { }
export const MyConstant = 1

// ❌
export default function SuppliersPage() { }

// Exception: App.tsx dùng default export (Vite convention)
```

### 3.2 erasableSyntaxOnly (Vite 8)

KHÔNG dùng `enum` — dùng const-object pattern:

```ts
// ❌
export enum SupplierType { NhaCungCap = 1 }

// ✅
export const SupplierType = { NhaCungCap: 1, NhaThauPhu: 2 } as const
export type SupplierType = typeof SupplierType[keyof typeof SupplierType]
```

### 3.3 Path alias

- Dùng `@/` cho absolute import: `import { api } from '@/lib/api'`
- Config ở `vite.config.ts` + `tsconfig.app.json` (chỉ `paths`, không `baseUrl`)

### 3.4 Data fetching

- **TanStack Query** cho mọi API call (KHÔNG useState + useEffect thủ công)
- `useQuery` cho GET, `useMutation` cho POST/PUT/DELETE
- `invalidateQueries` sau mutation thành công

### 3.5 API calls

- Qua `api` instance (`src/lib/api.ts`) — đã wire axios interceptor JWT + 401 redirect
- Base URL: `/api` (Vite proxy → `:5443`)

### 3.6 Permission guard

```tsx
<PermissionGuard menuKey="Contracts" action="Update">
  <Button>Sửa</Button>
</PermissionGuard>

// Hook
const { can } = usePermission()
if (!can('Contracts', 'Update')) return null
```

Nhớ: FE guard chỉ là UX. BE policy `[Authorize(Policy = "Contracts.Update")]` là source of truth.

### 3.7 Component naming

- PascalCase cho file: `SuppliersPage.tsx`, `DataTable.tsx`
- kebab-case cho utility: `api.ts`, `cn.ts`
- React component = PascalCase
- Hook: prefix `use`, ví dụ `usePermission`

### 3.8 Toast + error

- Dùng `sonner` (đã wire `<Toaster>` ở App)
- `toast.success('...')`, `toast.error(getErrorMessage(err))`
- Error helper: `src/lib/apiError.ts` extract từ ProblemDetails

### 3.9 Duplicate giữa 2 FE

**CÓ CHỦ ĐÍCH.** Mỗi app (`fe-admin` + `fe-user`) là standalone — copy shared code giữa 2 app thay vì extract ra package chung. Lý do: 2 app có UX rất khác (admin mission-critical, user workflow-heavy), evolution độc lập.

Khi share code: `cp` file từ app này sang app kia. Đồng bộ tay khi có breaking change.

## 4. Database

### 4.1 Convention

| Item | Rule |
|---|---|
| Schema | 1 schema duy nhất: `dbo` |
| Table | PascalCase tiếng Anh, plural: `Contracts`, `Suppliers` |
| Column | PascalCase: `FullName`, `CreatedAt` |
| PK | `Id` — `uniqueidentifier` |
| FK | `{Entity}Id` — `uniqueidentifier` |
| Index | `IX_{Table}_{Col}` |
| Unique | `UX_{Table}_{Col}` |

Full: xem [`database/database-guide.md`](database/database-guide.md).

### 4.2 Migration

- Một commit = 1 migration (trừ khi nhiều change nhỏ trong cùng feature)
- Naming PascalCase: `AddMasterData`, `AddContractsWorkflow`
- Commit đủ 3 file: `{Name}.cs`, `{Name}.Designer.cs`, `ApplicationDbContextModelSnapshot.cs`

## 5. Git & commits

### 5.1 Branch

- `main` — deploy branch
- Feature branch (nếu nhiều người): `feature/phase{N}-{feature}`

### 5.2 Commit format

```
[CLAUDE] <scope>: <imperative message>

<body optional — chi tiết what + why>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
```

**Scope:** `Contract` · `Form` · `Workflow` · `Supplier` · `Auth` · `Admin` · `Api` · `App` · `Domain` · `Infra` · `FE-Admin` · `FE-User` · `Docs` · `CICD` · `Scripts` · `Report` · `Dashboard`

### 5.3 Một commit nên

- Build pass (BE + FE)
- Không leave WIP nửa chừng (trừ khi commit message nói rõ)
- Test E2E với endpoint mới (curl trong session log)

### 5.4 Không commit

- `.env`, `appsettings.*.Local.json`
- `node_modules/`, `bin/`, `obj/`
- `wwwroot/uploads/` (user files)
- `SolutionErp_Design` database (tạm cho EF CLI)

## 6. Docs

### 6.1 Khi nào viết session log

- Session có commit thay đổi code → PHẢI tạo `docs/changelog/sessions/YYYY-MM-DD-HHMM-{topic}.md`
- Session chỉ Q&A, không đụng file → không cần

### 6.2 Session log format

```markdown
# Session YYYY-MM-DD HH:MM — <topic>

**Dev:** Claude / Copilot / <name>
**Duration:** ~Nh
**Base commit:** <sha>

## Làm được

### Chunk X — <name>
- bullet list deliverable

## E2E verified

<curl output hoặc screenshot>

## Bug gặp + fix

| Bug | Fix |

## Docs updates

## Handoff

## Thông số cumulative
```

### 6.3 Update khi thêm feature

- Thêm entity → update [`database/database-guide.md`](database/database-guide.md) schema section
- Thêm endpoint → update [`flows/`](flows/) relevant flow
- Thêm bug fix lặp lại → update [`gotchas.md`](gotchas.md)
- Thêm pattern → update skill tương ứng ở `.claude/skills/`
- Phase đổi → update [`STATUS.md`](STATUS.md) + [`HANDOFF.md`](HANDOFF.md) + [`changelog/migration-todos.md`](changelog/migration-todos.md)

## 7. Testing (hiện chưa có test tự động)

**Phase 1-4 — manual test:**
- E2E qua curl/Postman trong mỗi session log
- Build + TS check mỗi commit

**Phase 5 — tự động (chưa làm):**
- Unit test: xUnit cho BE, Vitest cho FE
- Integration test: TestContainer SQL Server cho BE
- E2E test: Playwright cho FE

## 8. Security baseline

- HTTPS everywhere prod
- JWT Secret trong user-secrets / env var (không commit appsettings)
- Password hash: PBKDF2 (Identity default)
- CORS whitelist chỉ 2 FE origin
- SQL injection: EF Core parameterized (không raw SQL trừ khi phải)
- Audit log: mọi ghi phải log qua `ContractApproval` hoặc `AuditLog` (future)
- Rate limit: `/api/auth/login` 5 req/min/IP (chưa implement — Phase 5)

## 9. Liên quan

- [`CLAUDE.md`](../CLAUDE.md) — entry point cho AI agent
- [`architecture.md`](architecture.md) — kiến trúc chi tiết (layered, CQRS, state machine)
- [`gotchas.md`](gotchas.md) — pitfalls đã gặp
- [`database/database-guide.md`](database/database-guide.md) — DB conventions
- [`flows/`](flows/) — sequence diagram per feature