690326:2212 Fixing Refactor ADR-019 Naming convention uuid #08
This commit is contained in:
@@ -0,0 +1,254 @@
|
||||
# UUID Handling (ADR-019)
|
||||
|
||||
**Project-specific: Hybrid Identifier Strategy for NAP-DMS**
|
||||
|
||||
This project uses ADR-019: INT Primary Key (internal) + UUIDv7 (public API). Frontend code must handle this correctly.
|
||||
|
||||
## The Pattern
|
||||
|
||||
| Source | Field Name | Type | Notes |
|
||||
|--------|------------|------|-------|
|
||||
| **API Response** | `id` | `string` (UUID) | Actually `publicId` exposed via `@Expose({ name: 'id' })` |
|
||||
| **TypeScript Interface** | `publicId?: string` | UUID string | Use this for all references |
|
||||
| **Fallback** | `id?: number` | INT (internal) | May be undefined due to `@Exclude()` |
|
||||
| **Form Values** | `xxxUuid` | `string` | DTO field names: `projectUuid`, `contractUuid` |
|
||||
|
||||
## Critical Rules
|
||||
|
||||
### 1. NEVER Use `parseInt()` on UUID
|
||||
|
||||
```tsx
|
||||
// ❌ WRONG - parseInt on UUID gives garbage
|
||||
const id = parseInt(projectId); // "0195a1b2-..." → 195 (wrong!)
|
||||
|
||||
// ❌ WRONG - Number() on UUID
|
||||
const id = Number(projectId); // NaN
|
||||
|
||||
// ❌ WRONG - Unary plus
|
||||
const id = +projectId; // NaN
|
||||
|
||||
// ✅ CORRECT - Send UUID string directly to API
|
||||
apiClient.get(`/projects/${projectId}`); // projectId is already UUID string
|
||||
```
|
||||
|
||||
### 2. Use `publicId ?? id` Pattern
|
||||
|
||||
```tsx
|
||||
// types/project.ts
|
||||
interface Project {
|
||||
id?: number; // Internal INT (may be undefined)
|
||||
publicId?: string; // UUID from API (use this)
|
||||
projectCode: string;
|
||||
projectName: string;
|
||||
}
|
||||
|
||||
// Component usage
|
||||
const projectOptions = projects.map((p) => ({
|
||||
label: `${p.projectName} (${p.projectCode})`,
|
||||
value: String(p.publicId ?? p.id ?? ''), // ADR-019 pattern
|
||||
key: String(p.publicId ?? p.id ?? ''),
|
||||
}));
|
||||
```
|
||||
|
||||
### 3. Form Field Names (camelCase)
|
||||
|
||||
```tsx
|
||||
// ❌ WRONG - snake_case doesn't match TypeScript interface
|
||||
fields={[{ name: 'project_id', label: 'Project' }]}
|
||||
|
||||
// ✅ CORRECT - camelCase matches interface
|
||||
fields={[{ name: 'projectUuid', label: 'Project' }]}
|
||||
|
||||
// Form submission
|
||||
const onSubmit = (data: { projectUuid: string }) => {
|
||||
// projectUuid is UUID string - send as-is
|
||||
await apiClient.post('/contracts', data);
|
||||
};
|
||||
```
|
||||
|
||||
## Select Component Pattern
|
||||
|
||||
```tsx
|
||||
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
|
||||
|
||||
interface ContractSelectProps {
|
||||
contracts: Contract[];
|
||||
value: string;
|
||||
onChange: (value: string) => void;
|
||||
}
|
||||
|
||||
export function ContractSelect({ contracts, value, onChange }: ContractSelectProps) {
|
||||
return (
|
||||
<Select value={value} onValueChange={onChange}>
|
||||
<SelectTrigger>
|
||||
<SelectValue placeholder="เลือกสัญญา" />
|
||||
</SelectTrigger>
|
||||
<SelectContent>
|
||||
{contracts.map((c) => (
|
||||
<SelectItem
|
||||
key={String(c.publicId ?? c.id ?? '')}
|
||||
value={String(c.publicId ?? c.id ?? '')}
|
||||
>
|
||||
{c.contractName} ({c.contractCode})
|
||||
</SelectItem>
|
||||
))}
|
||||
</SelectContent>
|
||||
</Select>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Data Table Pattern
|
||||
|
||||
```tsx
|
||||
// Show relation columns with UUID entities
|
||||
const columns: ColumnDef<Discipline>[] = [
|
||||
{
|
||||
accessorKey: 'disciplineCode',
|
||||
header: 'Code',
|
||||
},
|
||||
{
|
||||
accessorKey: 'contract',
|
||||
header: 'Contract',
|
||||
cell: ({ row }) => {
|
||||
const contract = row.original.contract;
|
||||
return contract ? (
|
||||
<span>{contract.contractName} ({contract.contractCode})</span>
|
||||
) : (
|
||||
<span className="text-muted-foreground">-</span>
|
||||
);
|
||||
},
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
## API Service Pattern
|
||||
|
||||
```tsx
|
||||
// lib/services/contract.service.ts
|
||||
export const contractService = {
|
||||
async getById(uuid: string): Promise<Contract> {
|
||||
// Send UUID string directly - backend resolves to INT
|
||||
const { data } = await apiClient.get(`/contracts/${uuid}`);
|
||||
return data;
|
||||
},
|
||||
|
||||
async create(dto: CreateContractDto): Promise<Contract> {
|
||||
// DTO contains projectUuid (UUID string)
|
||||
const { data } = await apiClient.post('/contracts', dto);
|
||||
return data;
|
||||
},
|
||||
|
||||
async update(uuid: string, dto: Partial<CreateContractDto>): Promise<Contract> {
|
||||
const { data } = await apiClient.put(`/contracts/${uuid}`, dto);
|
||||
return data;
|
||||
},
|
||||
|
||||
async delete(uuid: string): Promise<void> {
|
||||
await apiClient.delete(`/contracts/${uuid}`);
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## TypeScript Interfaces
|
||||
|
||||
```tsx
|
||||
// types/entities.ts
|
||||
export interface BaseEntity {
|
||||
id?: number; // Internal INT - may be undefined
|
||||
publicId?: string; // UUID - use this for API calls
|
||||
createdAt?: string;
|
||||
updatedAt?: string;
|
||||
}
|
||||
|
||||
export interface Project extends BaseEntity {
|
||||
projectCode: string;
|
||||
projectName: string;
|
||||
description?: string;
|
||||
}
|
||||
|
||||
export interface Contract extends BaseEntity {
|
||||
contractCode: string;
|
||||
contractName: string;
|
||||
projectId?: number; // Internal INT FK
|
||||
projectUuid?: string; // UUID for DTOs
|
||||
project?: Project; // Relation
|
||||
}
|
||||
|
||||
// DTOs
|
||||
export interface CreateContractDto {
|
||||
projectUuid: string; // Accept UUID from form
|
||||
contractCode: string;
|
||||
contractName: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Form with React Hook Form + Zod
|
||||
|
||||
```tsx
|
||||
import { useForm } from 'react-hook-form';
|
||||
import { zodResolver } from '@hookform/resolvers/zod';
|
||||
import * as z from 'zod';
|
||||
|
||||
const formSchema = z.object({
|
||||
projectUuid: z.string().uuid('กรุณาเลือกโปรเจกต์'),
|
||||
contractCode: z.string().min(1, 'กรุณาระบุรหัสสัญญา'),
|
||||
contractName: z.string().min(1, 'กรุณาระบุชื่อสัญญา'),
|
||||
});
|
||||
|
||||
type FormData = z.infer<typeof formSchema>;
|
||||
|
||||
export function ContractForm() {
|
||||
const form = useForm<FormData>({
|
||||
resolver: zodResolver(formSchema),
|
||||
defaultValues: {
|
||||
projectUuid: '',
|
||||
contractCode: '',
|
||||
contractName: '',
|
||||
},
|
||||
});
|
||||
|
||||
const onSubmit = async (data: FormData) => {
|
||||
// Send UUID strings directly
|
||||
await contractService.create(data);
|
||||
};
|
||||
|
||||
return (
|
||||
<Form {...form}>
|
||||
<form onSubmit={form.handleSubmit(onSubmit)}>
|
||||
{/* Form fields */}
|
||||
</form>
|
||||
</Form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## URL Parameters
|
||||
|
||||
```tsx
|
||||
// app/contracts/[id]/page.tsx
|
||||
export default async function ContractPage({ params }: { params: Promise<{ id: string }> }) {
|
||||
const { id } = await params;
|
||||
// id is UUID string from URL
|
||||
const contract = await contractService.getById(id);
|
||||
|
||||
return <ContractDetail contract={contract} />;
|
||||
}
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
| Pitfall | Wrong | Right |
|
||||
|---------|-------|-------|
|
||||
| Assuming `entity.id` exists | `key={entity.id}` | `key={entity.publicId ?? entity.id}` |
|
||||
| parseInt on UUID | `parseInt(projectId)` | `projectId` (string) |
|
||||
| Field name mismatch | `name="project_id"` | `name="projectUuid"` |
|
||||
| Missing fallback | `value={entity.publicId}` | `value={entity.publicId ?? entity.id ?? ''}` |
|
||||
|
||||
## Reference
|
||||
|
||||
- [ADR-019 Hybrid Identifier Strategy](../../../../specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md)
|
||||
- [Frontend Guidelines](../../../../specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md)
|
||||
- [UUID Implementation Plan](../../../../specs/05-Engineering-Guidelines/05-07-hybrid-uuid-implementation-plan.md)
|
||||
|
||||
> **Warning**: Using `parseInt()` on UUID values causes data corruption. Always use UUID strings directly in API calls.
|
||||
Reference in New Issue
Block a user