Compare commits
3 Commits
2788b35108
...
de306d09dc
| Author | SHA1 | Date | |
|---|---|---|---|
|
de306d09dc | ||
|
|
7cb12be97f | ||
|
|
39d859bd8b |
@@ -1,5 +1,37 @@
|
||||
# Hướng Dẫn Đóng Góp
|
||||
|
||||
## Kỷ Luật Commit & Push (Bắt Buộc)
|
||||
|
||||
> Để tránh conflict khi nhiều agent/engineer làm việc song song, toàn bộ team PHẢI tuân thủ các quy định sau. Nguồn: [GOO-91](/GOO/issues/GOO-91) (chỉ thị từ CEO qua [GOO-88](/GOO/issues/GOO-88)).
|
||||
|
||||
1. **Commit ngay khi hoàn thành task** — mỗi task = một commit (hoặc một chuỗi commit nhỏ liên quan). Không gom nhiều task không liên quan vào một commit lớn.
|
||||
2. **Pull/rebase trước khi push** — luôn chạy `git pull --rebase origin <branch>` trước `git push` để giảm merge conflict.
|
||||
3. **Push ngay sau commit** — không giữ commit local quá 1 ngày làm việc. Commit không push = rủi ro mất việc + conflict tăng.
|
||||
4. **Conventional Commits** — bắt buộc (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`, `style:`, `perf:`). Xem [Quy Ước Commit](#quy-ước-commit) bên dưới.
|
||||
5. **KHÔNG push trực tiếp lên `main` / `master`** — luôn dùng feature branch + Pull Request. Branch chính được bảo vệ bằng GitHub branch protection rules.
|
||||
6. **PR phải pass CI** (`lint` → `typecheck` → `test` → `build`) trước khi merge. PR đỏ CI không được merge dù đã approve.
|
||||
7. **Squash-merge khi merge PR** — giữ history trên `main` sạch, mỗi PR = một commit logic.
|
||||
8. **Xóa feature branch sau khi merge** — tránh branch sprawl. GitHub có auto-delete branch sau merge; bật nó trong repo settings.
|
||||
|
||||
### Flow nhanh cho mỗi task
|
||||
|
||||
```bash
|
||||
# 1. Tạo/chuyển sang feature branch (KHÔNG commit trực tiếp vào main)
|
||||
git checkout -b feature/goo-xx-short-description
|
||||
|
||||
# 2. Làm việc, khi hoàn thành task:
|
||||
git add <files>
|
||||
git commit -m "feat(scope): mô tả ngắn"
|
||||
|
||||
# 3. Đồng bộ & push
|
||||
git pull --rebase origin main # hoặc develop
|
||||
git push -u origin feature/goo-xx-short-description
|
||||
|
||||
# 4. Mở PR, chờ CI xanh + review, squash-merge, xóa branch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quy Trình Git & Branching
|
||||
|
||||
### Nhánh Chính
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
import { ConflictException } from '@modules/shared';
|
||||
import { CreateProjectCommand } from '../commands/create-project/create-project.command';
|
||||
import { CreateProjectHandler } from '../commands/create-project/create-project.handler';
|
||||
|
||||
function makeCommand(overrides: Partial<Record<string, unknown>> = {}): CreateProjectCommand {
|
||||
return new CreateProjectCommand(
|
||||
(overrides.name as string) ?? 'Test Project',
|
||||
(overrides.slug as string) ?? 'test-project',
|
||||
(overrides.developer as string) ?? 'DevCorp',
|
||||
(overrides.developerLogo as string | null) ?? null,
|
||||
(overrides.totalUnits as number) ?? 100,
|
||||
(overrides.status as 'PLANNING') ?? 'PLANNING',
|
||||
(overrides.latitude as number) ?? 10.82,
|
||||
(overrides.longitude as number) ?? 106.83,
|
||||
(overrides.address as string) ?? 'addr',
|
||||
(overrides.ward as string) ?? 'ward',
|
||||
(overrides.district as string) ?? 'dist',
|
||||
(overrides.city as string) ?? 'HCM',
|
||||
null, null, null, null, null, null, null, null, null, null,
|
||||
[],
|
||||
null, null,
|
||||
(overrides.suitableFor as string[]) ?? [],
|
||||
(overrides.whyThisLocation as string | null) ?? null,
|
||||
(overrides.ownerId as string | null) ?? null,
|
||||
);
|
||||
}
|
||||
|
||||
describe('CreateProjectHandler', () => {
|
||||
let handler: CreateProjectHandler;
|
||||
let mockRepo: {
|
||||
findBySlug: ReturnType<typeof vi.fn>;
|
||||
save: ReturnType<typeof vi.fn>;
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
mockRepo = {
|
||||
findBySlug: vi.fn().mockResolvedValue(null),
|
||||
save: vi.fn().mockResolvedValue(undefined),
|
||||
};
|
||||
handler = new CreateProjectHandler(mockRepo as any);
|
||||
});
|
||||
|
||||
it('should create project and return id + slug', async () => {
|
||||
const cmd = makeCommand();
|
||||
const result = await handler.execute(cmd);
|
||||
|
||||
expect(result.id).toBeDefined();
|
||||
expect(result.slug).toBe('test-project');
|
||||
expect(mockRepo.save).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should generate unique id via cuid2', async () => {
|
||||
const r1 = await handler.execute(makeCommand({ slug: 'slug-1' }));
|
||||
mockRepo.findBySlug.mockResolvedValue(null);
|
||||
const r2 = await handler.execute(makeCommand({ slug: 'slug-2' }));
|
||||
|
||||
expect(r1.id).not.toBe(r2.id);
|
||||
});
|
||||
|
||||
it('should throw ConflictException when slug already exists', async () => {
|
||||
mockRepo.findBySlug.mockResolvedValue({ id: 'existing' });
|
||||
|
||||
await expect(handler.execute(makeCommand())).rejects.toThrow(ConflictException);
|
||||
expect(mockRepo.save).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should pass suitableFor and whyThisLocation to entity', async () => {
|
||||
const cmd = makeCommand({ suitableFor: ['family'], whyThisLocation: 'Near metro' });
|
||||
await handler.execute(cmd);
|
||||
|
||||
const saved = mockRepo.save.mock.calls[0][0];
|
||||
expect(saved.suitableFor).toEqual(['family']);
|
||||
expect(saved.whyThisLocation).toBe('Near metro');
|
||||
});
|
||||
|
||||
it('should pass ownerId to entity', async () => {
|
||||
const cmd = makeCommand({ ownerId: 'dev-1' });
|
||||
await handler.execute(cmd);
|
||||
|
||||
const saved = mockRepo.save.mock.calls[0][0];
|
||||
expect(saved.ownerId).toBe('dev-1');
|
||||
});
|
||||
|
||||
it('should default completedUnits to 0', async () => {
|
||||
await handler.execute(makeCommand());
|
||||
|
||||
const saved = mockRepo.save.mock.calls[0][0];
|
||||
expect(saved.completedUnits).toBe(0);
|
||||
});
|
||||
|
||||
it('should default isVerified to false', async () => {
|
||||
await handler.execute(makeCommand());
|
||||
|
||||
const saved = mockRepo.save.mock.calls[0][0];
|
||||
expect(saved.isVerified).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,89 @@
|
||||
import { ForbiddenException } from '@nestjs/common';
|
||||
import { NotFoundException } from '@modules/shared';
|
||||
import { ProjectDevelopmentEntity, type ProjectDevelopmentProps } from '../../domain/entities/project-development.entity';
|
||||
import { DeleteProjectCommand } from '../commands/delete-project/delete-project.command';
|
||||
import { DeleteProjectHandler } from '../commands/delete-project/delete-project.handler';
|
||||
|
||||
function makeProps(overrides: Partial<ProjectDevelopmentProps> = {}): ProjectDevelopmentProps {
|
||||
return {
|
||||
name: 'Vinhomes Grand Park', slug: 'vinhomes-grand-park',
|
||||
developer: 'Vingroup', developerLogo: null, totalUnits: 10000,
|
||||
completedUnits: 5000, status: 'UNDER_CONSTRUCTION',
|
||||
startDate: null, completionDate: null, description: null,
|
||||
amenities: null, masterPlanUrl: null, latitude: 10.8231,
|
||||
longitude: 106.8368, address: 'addr', ward: 'ward',
|
||||
district: 'dist', city: 'HCM', minPrice: null, maxPrice: null,
|
||||
pricePerM2Range: null, totalArea: null, buildingCount: null,
|
||||
floorCount: null, unitTypes: null, media: null, documents: null,
|
||||
tags: [], suitableFor: [], whyThisLocation: null,
|
||||
isVerified: false, ownerId: 'dev-user-1', ...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function makeEntity(id = 'proj-1', overrides: Partial<ProjectDevelopmentProps> = {}): ProjectDevelopmentEntity {
|
||||
return new ProjectDevelopmentEntity(id, makeProps(overrides), new Date(), new Date());
|
||||
}
|
||||
|
||||
describe('DeleteProjectHandler', () => {
|
||||
let handler: DeleteProjectHandler;
|
||||
let mockRepo: {
|
||||
findById: ReturnType<typeof vi.fn>;
|
||||
delete: ReturnType<typeof vi.fn>;
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
mockRepo = {
|
||||
findById: vi.fn(),
|
||||
delete: vi.fn().mockResolvedValue(undefined),
|
||||
};
|
||||
handler = new DeleteProjectHandler(mockRepo as any);
|
||||
});
|
||||
|
||||
it('should delete project as ADMIN', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity());
|
||||
|
||||
const cmd = new DeleteProjectCommand('proj-1', 'admin-1', 'ADMIN');
|
||||
await handler.execute(cmd);
|
||||
|
||||
expect(mockRepo.delete).toHaveBeenCalledWith('proj-1');
|
||||
});
|
||||
|
||||
it('should throw NotFoundException when project not found', async () => {
|
||||
mockRepo.findById.mockResolvedValue(null);
|
||||
|
||||
const cmd = new DeleteProjectCommand('missing', 'admin-1', 'ADMIN');
|
||||
await expect(handler.execute(cmd)).rejects.toThrow(NotFoundException);
|
||||
expect(mockRepo.delete).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should allow DEVELOPER to delete own project', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity('proj-1', { ownerId: 'dev-user-1' }));
|
||||
|
||||
const cmd = new DeleteProjectCommand('proj-1', 'dev-user-1', 'DEVELOPER');
|
||||
await handler.execute(cmd);
|
||||
|
||||
expect(mockRepo.delete).toHaveBeenCalledWith('proj-1');
|
||||
});
|
||||
|
||||
it('should deny DEVELOPER deleting another owners project', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity('proj-1', { ownerId: 'other-dev' }));
|
||||
|
||||
const cmd = new DeleteProjectCommand('proj-1', 'dev-user-1', 'DEVELOPER');
|
||||
await expect(handler.execute(cmd)).rejects.toThrow(ForbiddenException);
|
||||
expect(mockRepo.delete).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should deny USER role from deleting', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity());
|
||||
|
||||
const cmd = new DeleteProjectCommand('proj-1', 'user-1', 'USER');
|
||||
await expect(handler.execute(cmd)).rejects.toThrow(ForbiddenException);
|
||||
});
|
||||
|
||||
it('should deny AGENT role from deleting', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity());
|
||||
|
||||
const cmd = new DeleteProjectCommand('proj-1', 'agent-1', 'AGENT');
|
||||
await expect(handler.execute(cmd)).rejects.toThrow(ForbiddenException);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,106 @@
|
||||
import { ForbiddenException } from '@nestjs/common';
|
||||
import { NotFoundException } from '@modules/shared';
|
||||
import { ProjectDevelopmentEntity, type ProjectDevelopmentProps } from '../../domain/entities/project-development.entity';
|
||||
import { GetProjectStatsHandler } from '../queries/get-project-stats/get-project-stats.handler';
|
||||
import { GetProjectStatsQuery } from '../queries/get-project-stats/get-project-stats.query';
|
||||
|
||||
function makeProps(overrides: Partial<ProjectDevelopmentProps> = {}): ProjectDevelopmentProps {
|
||||
return {
|
||||
name: 'Test', slug: 'test', developer: 'Dev', developerLogo: null,
|
||||
totalUnits: 100, completedUnits: 0, status: 'PLANNING',
|
||||
startDate: null, completionDate: null, description: null,
|
||||
amenities: null, masterPlanUrl: null, latitude: 10, longitude: 106,
|
||||
address: 'a', ward: 'w', district: 'd', city: 'HCM',
|
||||
minPrice: null, maxPrice: null, pricePerM2Range: null,
|
||||
totalArea: null, buildingCount: null, floorCount: null,
|
||||
unitTypes: null, media: null, documents: null,
|
||||
tags: [], suitableFor: [], whyThisLocation: null,
|
||||
isVerified: false, ownerId: 'dev-1', ...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function makeEntity(id = 'proj-1', overrides: Partial<ProjectDevelopmentProps> = {}): ProjectDevelopmentEntity {
|
||||
return new ProjectDevelopmentEntity(id, makeProps(overrides), new Date(), new Date());
|
||||
}
|
||||
|
||||
describe('GetProjectStatsHandler', () => {
|
||||
let handler: GetProjectStatsHandler;
|
||||
let mockRepo: { findById: ReturnType<typeof vi.fn> };
|
||||
let mockPrisma: { $queryRaw: ReturnType<typeof vi.fn> };
|
||||
|
||||
const defaultStatsRow = [{
|
||||
linked: BigInt(5), active: BigInt(3),
|
||||
inquiries: BigInt(10), unread: BigInt(2), saves: BigInt(7),
|
||||
}];
|
||||
|
||||
beforeEach(() => {
|
||||
mockRepo = { findById: vi.fn() };
|
||||
mockPrisma = { $queryRaw: vi.fn().mockResolvedValue(defaultStatsRow) };
|
||||
handler = new GetProjectStatsHandler(mockRepo as any, mockPrisma as any);
|
||||
});
|
||||
|
||||
it('should return stats for ADMIN', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity());
|
||||
|
||||
const query = new GetProjectStatsQuery('proj-1', 'admin-1', 'ADMIN');
|
||||
const result = await handler.execute(query);
|
||||
|
||||
expect(result.projectId).toBe('proj-1');
|
||||
expect(result.linkedListingCount).toBe(5);
|
||||
expect(result.activeListingCount).toBe(3);
|
||||
expect(result.totalInquiries).toBe(10);
|
||||
expect(result.unreadInquiries).toBe(2);
|
||||
expect(result.savedByUsers).toBe(7);
|
||||
});
|
||||
|
||||
it('should return stats for DEVELOPER who owns the project', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity('proj-1', { ownerId: 'dev-1' }));
|
||||
|
||||
const query = new GetProjectStatsQuery('proj-1', 'dev-1', 'DEVELOPER');
|
||||
const result = await handler.execute(query);
|
||||
|
||||
expect(result.projectId).toBe('proj-1');
|
||||
});
|
||||
|
||||
it('should throw NotFoundException when project not found', async () => {
|
||||
mockRepo.findById.mockResolvedValue(null);
|
||||
|
||||
const query = new GetProjectStatsQuery('missing', 'admin-1', 'ADMIN');
|
||||
await expect(handler.execute(query)).rejects.toThrow(NotFoundException);
|
||||
});
|
||||
|
||||
it('should deny DEVELOPER viewing stats of another owners project', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity('proj-1', { ownerId: 'other-dev' }));
|
||||
|
||||
const query = new GetProjectStatsQuery('proj-1', 'dev-1', 'DEVELOPER');
|
||||
await expect(handler.execute(query)).rejects.toThrow(ForbiddenException);
|
||||
});
|
||||
|
||||
it('should deny USER role', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity());
|
||||
|
||||
const query = new GetProjectStatsQuery('proj-1', 'user-1', 'USER');
|
||||
await expect(handler.execute(query)).rejects.toThrow(ForbiddenException);
|
||||
});
|
||||
|
||||
it('should handle empty stats row', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity());
|
||||
mockPrisma.$queryRaw.mockResolvedValue([]);
|
||||
|
||||
const query = new GetProjectStatsQuery('proj-1', 'admin-1', 'ADMIN');
|
||||
const result = await handler.execute(query);
|
||||
|
||||
expect(result.linkedListingCount).toBe(0);
|
||||
expect(result.activeListingCount).toBe(0);
|
||||
expect(result.totalInquiries).toBe(0);
|
||||
expect(result.unreadInquiries).toBe(0);
|
||||
expect(result.savedByUsers).toBe(0);
|
||||
});
|
||||
|
||||
it('should construct query DTO correctly', () => {
|
||||
const q = new GetProjectStatsQuery('p1', 'u1', 'ADMIN');
|
||||
expect(q.projectId).toBe('p1');
|
||||
expect(q.requesterUserId).toBe('u1');
|
||||
expect(q.requesterRole).toBe('ADMIN');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,105 @@
|
||||
import { GetProjectQuery } from '../queries/get-project/get-project.query';
|
||||
import { GetProjectHandler } from '../queries/get-project/get-project.handler';
|
||||
import { ListProjectsQuery } from '../queries/list-projects/list-projects.query';
|
||||
import { ListProjectsHandler } from '../queries/list-projects/list-projects.handler';
|
||||
|
||||
describe('GetProjectQuery', () => {
|
||||
it('should store slugOrId', () => {
|
||||
const q = new GetProjectQuery('my-slug');
|
||||
expect(q.slugOrId).toBe('my-slug');
|
||||
});
|
||||
});
|
||||
|
||||
describe('GetProjectHandler', () => {
|
||||
let handler: GetProjectHandler;
|
||||
let mockRepo: {
|
||||
findDetailBySlug: ReturnType<typeof vi.fn>;
|
||||
findDetailById: ReturnType<typeof vi.fn>;
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
mockRepo = {
|
||||
findDetailBySlug: vi.fn().mockResolvedValue(null),
|
||||
findDetailById: vi.fn().mockResolvedValue(null),
|
||||
};
|
||||
handler = new GetProjectHandler(mockRepo as any);
|
||||
});
|
||||
|
||||
it('should try slug first', async () => {
|
||||
const detail = { id: 'p1', name: 'Project' };
|
||||
mockRepo.findDetailBySlug.mockResolvedValue(detail);
|
||||
|
||||
const result = await handler.execute(new GetProjectQuery('my-slug'));
|
||||
|
||||
expect(result).toBe(detail);
|
||||
expect(mockRepo.findDetailBySlug).toHaveBeenCalledWith('my-slug');
|
||||
expect(mockRepo.findDetailById).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should fall back to id when slug returns null', async () => {
|
||||
const detail = { id: 'p1', name: 'Project' };
|
||||
mockRepo.findDetailById.mockResolvedValue(detail);
|
||||
|
||||
const result = await handler.execute(new GetProjectQuery('some-id'));
|
||||
|
||||
expect(result).toBe(detail);
|
||||
expect(mockRepo.findDetailBySlug).toHaveBeenCalledWith('some-id');
|
||||
expect(mockRepo.findDetailById).toHaveBeenCalledWith('some-id');
|
||||
});
|
||||
|
||||
it('should return null when neither slug nor id match', async () => {
|
||||
const result = await handler.execute(new GetProjectQuery('nope'));
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('ListProjectsQuery', () => {
|
||||
it('should store all params', () => {
|
||||
const q = new ListProjectsQuery('search', 'PLANNING', 'HCM', 'Q1', 'Dev', true, 2, 10, 'owner-1');
|
||||
expect(q.query).toBe('search');
|
||||
expect(q.status).toBe('PLANNING');
|
||||
expect(q.city).toBe('HCM');
|
||||
expect(q.district).toBe('Q1');
|
||||
expect(q.developer).toBe('Dev');
|
||||
expect(q.isVerified).toBe(true);
|
||||
expect(q.page).toBe(2);
|
||||
expect(q.limit).toBe(10);
|
||||
expect(q.ownerId).toBe('owner-1');
|
||||
});
|
||||
});
|
||||
|
||||
describe('ListProjectsHandler', () => {
|
||||
let handler: ListProjectsHandler;
|
||||
let mockRepo: { search: ReturnType<typeof vi.fn> };
|
||||
|
||||
beforeEach(() => {
|
||||
mockRepo = { search: vi.fn() };
|
||||
handler = new ListProjectsHandler(mockRepo as any);
|
||||
});
|
||||
|
||||
it('should delegate to repo.search with correct params', async () => {
|
||||
const expected = { data: [], total: 0, page: 1, limit: 20, totalPages: 0 };
|
||||
mockRepo.search.mockResolvedValue(expected);
|
||||
|
||||
const q = new ListProjectsQuery('q', 'COMPLETED', 'HCM', 'Q2', 'VG', false, 1, 20, 'own-1');
|
||||
const result = await handler.execute(q);
|
||||
|
||||
expect(mockRepo.search).toHaveBeenCalledWith({
|
||||
query: 'q', status: 'COMPLETED', city: 'HCM', district: 'Q2',
|
||||
developer: 'VG', isVerified: false, ownerId: 'own-1', page: 1, limit: 20,
|
||||
});
|
||||
expect(result).toBe(expected);
|
||||
});
|
||||
|
||||
it('should return paginated result from repo', async () => {
|
||||
const data = { data: [{ id: 'p1' }], total: 1, page: 1, limit: 10, totalPages: 1 };
|
||||
mockRepo.search.mockResolvedValue(data);
|
||||
|
||||
const result = await handler.execute(
|
||||
new ListProjectsQuery(undefined, undefined, undefined, undefined, undefined, undefined, 1, 10),
|
||||
);
|
||||
|
||||
expect(result.data).toHaveLength(1);
|
||||
expect(result.total).toBe(1);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,155 @@
|
||||
import { ForbiddenException } from '@nestjs/common';
|
||||
import { NotFoundException } from '@modules/shared';
|
||||
import { ProjectDevelopmentEntity, type ProjectDevelopmentProps } from '../../domain/entities/project-development.entity';
|
||||
import { UpdateProjectCommand } from '../commands/update-project/update-project.command';
|
||||
import { UpdateProjectHandler } from '../commands/update-project/update-project.handler';
|
||||
|
||||
function makeProps(overrides: Partial<ProjectDevelopmentProps> = {}): ProjectDevelopmentProps {
|
||||
return {
|
||||
name: 'Vinhomes Grand Park', slug: 'vinhomes-grand-park',
|
||||
developer: 'Vingroup', developerLogo: null, totalUnits: 10000,
|
||||
completedUnits: 5000, status: 'UNDER_CONSTRUCTION',
|
||||
startDate: null, completionDate: null, description: null,
|
||||
amenities: null, masterPlanUrl: null, latitude: 10.8231,
|
||||
longitude: 106.8368, address: 'addr', ward: 'ward',
|
||||
district: 'dist', city: 'HCM', minPrice: null, maxPrice: null,
|
||||
pricePerM2Range: null, totalArea: null, buildingCount: null,
|
||||
floorCount: null, unitTypes: null, media: null, documents: null,
|
||||
tags: [], suitableFor: [], whyThisLocation: null,
|
||||
isVerified: false, ownerId: 'dev-user-1', ...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function makeEntity(id = 'proj-1', overrides: Partial<ProjectDevelopmentProps> = {}): ProjectDevelopmentEntity {
|
||||
return new ProjectDevelopmentEntity(id, makeProps(overrides), new Date(), new Date());
|
||||
}
|
||||
|
||||
describe('UpdateProjectHandler', () => {
|
||||
let handler: UpdateProjectHandler;
|
||||
let mockRepo: {
|
||||
findById: ReturnType<typeof vi.fn>;
|
||||
update: ReturnType<typeof vi.fn>;
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
mockRepo = {
|
||||
findById: vi.fn(),
|
||||
update: vi.fn().mockResolvedValue(undefined),
|
||||
};
|
||||
// NOTE: EventBusService is imported as `type` in the handler, so the
|
||||
// constructor param and publish call are stripped from compiled output.
|
||||
const mockEventBus = { publish: vi.fn() };
|
||||
|
||||
handler = new UpdateProjectHandler(mockRepo as any, mockEventBus as any);
|
||||
});
|
||||
|
||||
it('should update project as ADMIN', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity());
|
||||
|
||||
const cmd = new UpdateProjectCommand('proj-1', 'admin-1', 'ADMIN', 'Updated Name');
|
||||
|
||||
const result = await handler.execute(cmd);
|
||||
|
||||
expect(result.id).toBe('proj-1');
|
||||
expect(mockRepo.update).toHaveBeenCalledTimes(1);
|
||||
const updated: ProjectDevelopmentEntity = mockRepo.update.mock.calls[0][0];
|
||||
expect(updated.name).toBe('Updated Name');
|
||||
});
|
||||
|
||||
it('should throw NotFoundException when project not found', async () => {
|
||||
mockRepo.findById.mockResolvedValue(null);
|
||||
|
||||
const cmd = new UpdateProjectCommand('missing', 'admin-1', 'ADMIN', 'Name');
|
||||
|
||||
await expect(handler.execute(cmd)).rejects.toThrow(NotFoundException);
|
||||
expect(mockRepo.update).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should allow DEVELOPER to update their own project', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity('proj-1', { ownerId: 'dev-user-1' }));
|
||||
|
||||
const cmd = new UpdateProjectCommand('proj-1', 'dev-user-1', 'DEVELOPER', 'New Name');
|
||||
|
||||
const result = await handler.execute(cmd);
|
||||
expect(result.id).toBe('proj-1');
|
||||
expect(mockRepo.update).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('should deny DEVELOPER editing another owners project', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity('proj-1', { ownerId: 'other-dev' }));
|
||||
|
||||
const cmd = new UpdateProjectCommand('proj-1', 'dev-user-1', 'DEVELOPER', 'Hacked');
|
||||
|
||||
await expect(handler.execute(cmd)).rejects.toThrow(ForbiddenException);
|
||||
expect(mockRepo.update).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should deny DEVELOPER reassigning ownerId', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity('proj-1', { ownerId: 'dev-user-1' }));
|
||||
|
||||
// UpdateProjectCommand params: id, requesterUserId, requesterRole,
|
||||
// name, developer, developerLogo, totalUnits, completedUnits,
|
||||
// status, description, amenities, masterPlanUrl,
|
||||
// minPrice, maxPrice, pricePerM2Range, totalArea,
|
||||
// buildingCount, floorCount, unitTypes, media, documents,
|
||||
// tags, isVerified, startDate, completionDate,
|
||||
// suitableFor, whyThisLocation, ownerId
|
||||
const cmd = new UpdateProjectCommand(
|
||||
'proj-1', 'dev-user-1', 'DEVELOPER',
|
||||
undefined, undefined, undefined, undefined, undefined,
|
||||
undefined, undefined, undefined, undefined,
|
||||
undefined, undefined, undefined, undefined,
|
||||
undefined, undefined, undefined, undefined, undefined,
|
||||
undefined, undefined, undefined, undefined,
|
||||
undefined, undefined,
|
||||
'another-user', // ownerId (28th param)
|
||||
);
|
||||
|
||||
await expect(handler.execute(cmd)).rejects.toThrow(ForbiddenException);
|
||||
});
|
||||
|
||||
it('should allow ADMIN to reassign ownerId', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity('proj-1'));
|
||||
|
||||
const cmd = new UpdateProjectCommand(
|
||||
'proj-1', 'admin-1', 'ADMIN',
|
||||
undefined, undefined, undefined, undefined, undefined,
|
||||
undefined, undefined, undefined, undefined,
|
||||
undefined, undefined, undefined, undefined,
|
||||
undefined, undefined, undefined, undefined, undefined,
|
||||
undefined, undefined, undefined, undefined,
|
||||
undefined, undefined,
|
||||
'new-owner', // ownerId (28th param)
|
||||
);
|
||||
|
||||
const result = await handler.execute(cmd);
|
||||
expect(result.id).toBe('proj-1');
|
||||
const updated: ProjectDevelopmentEntity = mockRepo.update.mock.calls[0][0];
|
||||
expect(updated.ownerId).toBe('new-owner');
|
||||
});
|
||||
|
||||
it('should deny USER role from editing any project', async () => {
|
||||
mockRepo.findById.mockResolvedValue(makeEntity());
|
||||
|
||||
const cmd = new UpdateProjectCommand('proj-1', 'user-1', 'USER', 'Name');
|
||||
|
||||
await expect(handler.execute(cmd)).rejects.toThrow(ForbiddenException);
|
||||
});
|
||||
|
||||
it('should only update provided fields', async () => {
|
||||
const entity = makeEntity();
|
||||
mockRepo.findById.mockResolvedValue(entity);
|
||||
|
||||
const cmd = new UpdateProjectCommand(
|
||||
'proj-1', 'admin-1', 'ADMIN',
|
||||
undefined, undefined, undefined, undefined, undefined,
|
||||
'COMPLETED',
|
||||
);
|
||||
|
||||
await handler.execute(cmd);
|
||||
|
||||
const updated: ProjectDevelopmentEntity = mockRepo.update.mock.calls[0][0];
|
||||
expect(updated.status).toBe('COMPLETED');
|
||||
expect(updated.name).toBe('Vinhomes Grand Park'); // unchanged
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,155 @@
|
||||
import { ProjectDevelopmentEntity, type ProjectDevelopmentProps } from '../entities/project-development.entity';
|
||||
|
||||
function makeProps(overrides: Partial<ProjectDevelopmentProps> = {}): ProjectDevelopmentProps {
|
||||
return {
|
||||
name: 'Vinhomes Grand Park', slug: 'vinhomes-grand-park',
|
||||
developer: 'Vingroup', developerLogo: null, totalUnits: 10000,
|
||||
completedUnits: 5000, status: 'UNDER_CONSTRUCTION',
|
||||
startDate: null, completionDate: null, description: null,
|
||||
amenities: null, masterPlanUrl: null, latitude: 10.8231,
|
||||
longitude: 106.8368, address: 'addr', ward: 'ward',
|
||||
district: 'dist', city: 'HCM', minPrice: null, maxPrice: null,
|
||||
pricePerM2Range: null, totalArea: null, buildingCount: null,
|
||||
floorCount: null, unitTypes: null, media: null, documents: null,
|
||||
tags: [], suitableFor: [], whyThisLocation: null,
|
||||
isVerified: false, ownerId: null, ...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('ProjectDevelopmentEntity', () => {
|
||||
const now = new Date();
|
||||
|
||||
it('should expose all getters correctly', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps(), now, now);
|
||||
|
||||
expect(entity.id).toBe('id-1');
|
||||
expect(entity.name).toBe('Vinhomes Grand Park');
|
||||
expect(entity.slug).toBe('vinhomes-grand-park');
|
||||
expect(entity.developer).toBe('Vingroup');
|
||||
expect(entity.developerLogo).toBeNull();
|
||||
expect(entity.totalUnits).toBe(10000);
|
||||
expect(entity.completedUnits).toBe(5000);
|
||||
expect(entity.status).toBe('UNDER_CONSTRUCTION');
|
||||
expect(entity.latitude).toBe(10.8231);
|
||||
expect(entity.longitude).toBe(106.8368);
|
||||
expect(entity.address).toBe('addr');
|
||||
expect(entity.city).toBe('HCM');
|
||||
expect(entity.tags).toEqual([]);
|
||||
expect(entity.suitableFor).toEqual([]);
|
||||
expect(entity.isVerified).toBe(false);
|
||||
expect(entity.ownerId).toBeNull();
|
||||
expect(entity.createdAt).toBe(now);
|
||||
expect(entity.updatedAt).toBe(now);
|
||||
});
|
||||
|
||||
it('should support nullable fields', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps({
|
||||
startDate: new Date('2024-01-01'),
|
||||
completionDate: new Date('2026-12-31'),
|
||||
description: 'A project',
|
||||
amenities: { pool: true },
|
||||
masterPlanUrl: 'https://example.com/plan.pdf',
|
||||
minPrice: BigInt(1_000_000_000),
|
||||
maxPrice: BigInt(5_000_000_000),
|
||||
pricePerM2Range: { min: 50, max: 80 },
|
||||
totalArea: 250.5,
|
||||
buildingCount: 10,
|
||||
floorCount: 30,
|
||||
unitTypes: { studio: 100 },
|
||||
media: [{ url: 'img.jpg' }],
|
||||
documents: [{ url: 'doc.pdf' }],
|
||||
whyThisLocation: 'Near metro',
|
||||
ownerId: 'dev-1',
|
||||
}), now, now);
|
||||
|
||||
expect(entity.startDate).toEqual(new Date('2024-01-01'));
|
||||
expect(entity.minPrice).toBe(BigInt(1_000_000_000));
|
||||
expect(entity.media).toEqual([{ url: 'img.jpg' }]);
|
||||
expect(entity.ownerId).toBe('dev-1');
|
||||
expect(entity.whyThisLocation).toBe('Near metro');
|
||||
});
|
||||
|
||||
it('should update only provided fields via updateDetails', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps(), now, now);
|
||||
|
||||
entity.updateDetails({ name: 'New Name', status: 'COMPLETED' });
|
||||
|
||||
expect(entity.name).toBe('New Name');
|
||||
expect(entity.status).toBe('COMPLETED');
|
||||
expect(entity.developer).toBe('Vingroup'); // unchanged
|
||||
});
|
||||
|
||||
it('should allow setting fields to null via updateDetails', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps({
|
||||
description: 'desc', masterPlanUrl: 'url',
|
||||
}), now, now);
|
||||
|
||||
entity.updateDetails({ description: null, masterPlanUrl: null });
|
||||
|
||||
expect(entity.description).toBeNull();
|
||||
expect(entity.masterPlanUrl).toBeNull();
|
||||
});
|
||||
|
||||
it('should update ownerId via updateDetails', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps({ ownerId: 'old' }), now, now);
|
||||
|
||||
entity.updateDetails({ ownerId: 'new-owner' });
|
||||
|
||||
expect(entity.ownerId).toBe('new-owner');
|
||||
});
|
||||
|
||||
it('should update suitableFor and whyThisLocation', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps(), now, now);
|
||||
|
||||
entity.updateDetails({ suitableFor: ['family', 'investor'], whyThisLocation: 'Prime location' });
|
||||
|
||||
expect(entity.suitableFor).toEqual(['family', 'investor']);
|
||||
expect(entity.whyThisLocation).toBe('Prime location');
|
||||
});
|
||||
|
||||
it('should update updatedAt when updateDetails is called', () => {
|
||||
const oldDate = new Date('2020-01-01');
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps(), oldDate, oldDate);
|
||||
|
||||
entity.updateDetails({ name: 'X' });
|
||||
|
||||
expect(entity.updatedAt.getTime()).toBeGreaterThan(oldDate.getTime());
|
||||
});
|
||||
|
||||
it('should implement equals from BaseEntity', () => {
|
||||
const a = new ProjectDevelopmentEntity('id-1', makeProps(), now, now);
|
||||
const b = new ProjectDevelopmentEntity('id-1', makeProps({ name: 'Other' }), now, now);
|
||||
const c = new ProjectDevelopmentEntity('id-2', makeProps(), now, now);
|
||||
|
||||
expect(a.equals(b)).toBe(true);
|
||||
expect(a.equals(c)).toBe(false);
|
||||
});
|
||||
|
||||
it('should support domain events (AggregateRoot)', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps(), now, now);
|
||||
|
||||
expect(entity.domainEvents).toEqual([]);
|
||||
expect(entity.commit()).toEqual([]);
|
||||
});
|
||||
|
||||
it('should update media and documents', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps(), now, now);
|
||||
|
||||
entity.updateDetails({
|
||||
media: [{ url: 'new.jpg', type: 'image' }],
|
||||
documents: [{ url: 'doc.pdf' }],
|
||||
});
|
||||
|
||||
expect(entity.media).toEqual([{ url: 'new.jpg', type: 'image' }]);
|
||||
expect(entity.documents).toEqual([{ url: 'doc.pdf' }]);
|
||||
});
|
||||
|
||||
it('should update tags and isVerified', () => {
|
||||
const entity = new ProjectDevelopmentEntity('id-1', makeProps(), now, now);
|
||||
|
||||
entity.updateDetails({ tags: ['luxury', 'new'], isVerified: true });
|
||||
|
||||
expect(entity.tags).toEqual(['luxury', 'new']);
|
||||
expect(entity.isVerified).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,164 @@
|
||||
import { PrismaProjectDevelopmentRepository } from '../repositories/prisma-project-development.repository';
|
||||
import { ProjectDevelopmentEntity, type ProjectDevelopmentProps } from '../../domain/entities/project-development.entity';
|
||||
|
||||
function makeProps(overrides: Partial<ProjectDevelopmentProps> = {}): ProjectDevelopmentProps {
|
||||
return {
|
||||
name: 'Test', slug: 'test', developer: 'Dev', developerLogo: null,
|
||||
totalUnits: 100, completedUnits: 0, status: 'PLANNING',
|
||||
startDate: null, completionDate: null, description: null,
|
||||
amenities: null, masterPlanUrl: null, latitude: 10, longitude: 106,
|
||||
address: 'a', ward: 'w', district: 'd', city: 'HCM',
|
||||
minPrice: null, maxPrice: null, pricePerM2Range: null,
|
||||
totalArea: null, buildingCount: null, floorCount: null,
|
||||
unitTypes: null, media: null, documents: null,
|
||||
tags: [], suitableFor: [], whyThisLocation: null,
|
||||
isVerified: false, ownerId: null, ...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function makeRawRow(overrides: Record<string, unknown> = {}) {
|
||||
return {
|
||||
id: 'p1', name: 'Test', slug: 'test', developer: 'Dev',
|
||||
developerLogo: null, totalUnits: 100, completedUnits: 0,
|
||||
status: 'PLANNING', startDate: null, completionDate: null,
|
||||
description: null, amenities: null, masterPlanUrl: null,
|
||||
lat: 10, lng: 106, address: 'a', ward: 'w', district: 'd', city: 'HCM',
|
||||
minPrice: null, maxPrice: null, pricePerM2Range: null,
|
||||
totalArea: null, buildingCount: null, floorCount: null,
|
||||
unitTypes: null, media: null, documents: null,
|
||||
tags: [], suitableFor: [], whyThisLocation: null,
|
||||
isVerified: false, ownerId: null,
|
||||
createdAt: new Date(), updatedAt: new Date(),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('PrismaProjectDevelopmentRepository', () => {
|
||||
let repo: PrismaProjectDevelopmentRepository;
|
||||
let mockPrisma: {
|
||||
$queryRaw: ReturnType<typeof vi.fn>;
|
||||
$executeRaw: ReturnType<typeof vi.fn>;
|
||||
projectDevelopment: { delete: ReturnType<typeof vi.fn> };
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
mockPrisma = {
|
||||
$queryRaw: vi.fn(),
|
||||
$executeRaw: vi.fn().mockResolvedValue(1),
|
||||
projectDevelopment: { delete: vi.fn().mockResolvedValue({}) },
|
||||
};
|
||||
repo = new PrismaProjectDevelopmentRepository(mockPrisma as any);
|
||||
});
|
||||
|
||||
it('findById should return entity when found', async () => {
|
||||
mockPrisma.$queryRaw.mockResolvedValue([makeRawRow()]);
|
||||
|
||||
const result = await repo.findById('p1');
|
||||
|
||||
expect(result).toBeInstanceOf(ProjectDevelopmentEntity);
|
||||
expect(result!.id).toBe('p1');
|
||||
expect(result!.name).toBe('Test');
|
||||
});
|
||||
|
||||
it('findById should return null when not found', async () => {
|
||||
mockPrisma.$queryRaw.mockResolvedValue([]);
|
||||
|
||||
const result = await repo.findById('missing');
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it('findBySlug should return entity when found', async () => {
|
||||
mockPrisma.$queryRaw.mockResolvedValue([makeRawRow({ slug: 'my-slug' })]);
|
||||
|
||||
const result = await repo.findBySlug('my-slug');
|
||||
expect(result).toBeInstanceOf(ProjectDevelopmentEntity);
|
||||
expect(result!.slug).toBe('my-slug');
|
||||
});
|
||||
|
||||
it('findBySlug should return null when not found', async () => {
|
||||
mockPrisma.$queryRaw.mockResolvedValue([]);
|
||||
expect(await repo.findBySlug('nope')).toBeNull();
|
||||
});
|
||||
|
||||
it('findDetailBySlug should return detail data when found', async () => {
|
||||
mockPrisma.$queryRaw.mockResolvedValue([makeRawRow({ propertyCount: 5 })]);
|
||||
|
||||
const result = await repo.findDetailBySlug('test');
|
||||
expect(result).not.toBeNull();
|
||||
expect(result!.id).toBe('p1');
|
||||
expect(result!.propertyCount).toBe(5);
|
||||
});
|
||||
|
||||
it('findDetailBySlug should return null when not found', async () => {
|
||||
mockPrisma.$queryRaw.mockResolvedValue([]);
|
||||
expect(await repo.findDetailBySlug('nope')).toBeNull();
|
||||
});
|
||||
|
||||
it('findDetailById should return detail data when found', async () => {
|
||||
mockPrisma.$queryRaw.mockResolvedValue([makeRawRow({ propertyCount: 3 })]);
|
||||
|
||||
const result = await repo.findDetailById('p1');
|
||||
expect(result).not.toBeNull();
|
||||
expect(result!.propertyCount).toBe(3);
|
||||
});
|
||||
|
||||
it('findDetailById should return null when not found', async () => {
|
||||
mockPrisma.$queryRaw.mockResolvedValue([]);
|
||||
expect(await repo.findDetailById('nope')).toBeNull();
|
||||
});
|
||||
|
||||
it('save should call $executeRaw', async () => {
|
||||
const entity = new ProjectDevelopmentEntity('p1', makeProps(), new Date(), new Date());
|
||||
await repo.save(entity);
|
||||
expect(mockPrisma.$executeRaw).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('update should call $executeRaw', async () => {
|
||||
const entity = new ProjectDevelopmentEntity('p1', makeProps(), new Date(), new Date());
|
||||
await repo.update(entity);
|
||||
expect(mockPrisma.$executeRaw).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('delete should call prisma.projectDevelopment.delete', async () => {
|
||||
await repo.delete('p1');
|
||||
expect(mockPrisma.projectDevelopment.delete).toHaveBeenCalledWith({ where: { id: 'p1' } });
|
||||
});
|
||||
|
||||
it('search should return paginated results', async () => {
|
||||
// First call: count query; second call: data query
|
||||
mockPrisma.$queryRaw
|
||||
.mockResolvedValueOnce([{ count: BigInt(1) }])
|
||||
.mockResolvedValueOnce([makeRawRow({ propertyCount: 2 })]);
|
||||
|
||||
const result = await repo.search({ page: 1, limit: 10 });
|
||||
|
||||
expect(result.total).toBe(1);
|
||||
expect(result.page).toBe(1);
|
||||
expect(result.limit).toBe(10);
|
||||
expect(result.totalPages).toBe(1);
|
||||
expect(result.data).toHaveLength(1);
|
||||
expect(result.data[0].id).toBe('p1');
|
||||
});
|
||||
|
||||
it('search should handle null tags/suitableFor in raw rows', async () => {
|
||||
mockPrisma.$queryRaw
|
||||
.mockResolvedValueOnce([{ count: BigInt(1) }])
|
||||
.mockResolvedValueOnce([makeRawRow({ tags: null, suitableFor: null, propertyCount: 0 })]);
|
||||
|
||||
const result = await repo.search({ page: 1, limit: 20 });
|
||||
|
||||
expect(result.data[0].tags).toEqual([]);
|
||||
expect(result.data[0].suitableFor).toEqual([]);
|
||||
});
|
||||
|
||||
it('search should default page=1 and limit=20', async () => {
|
||||
mockPrisma.$queryRaw
|
||||
.mockResolvedValueOnce([{ count: BigInt(0) }])
|
||||
.mockResolvedValueOnce([]);
|
||||
|
||||
const result = await repo.search({});
|
||||
|
||||
expect(result.page).toBe(1);
|
||||
expect(result.limit).toBe(20);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,254 @@
|
||||
import { NotFoundException } from '@modules/shared';
|
||||
import { ProjectsController } from '../controllers/projects.controller';
|
||||
|
||||
describe('ProjectsController', () => {
|
||||
let controller: ProjectsController;
|
||||
let mockCommandBus: { execute: ReturnType<typeof vi.fn> };
|
||||
let mockQueryBus: { execute: ReturnType<typeof vi.fn> };
|
||||
|
||||
beforeEach(() => {
|
||||
mockCommandBus = { execute: vi.fn() };
|
||||
mockQueryBus = { execute: vi.fn() };
|
||||
controller = new ProjectsController(mockCommandBus as any, mockQueryBus as any);
|
||||
});
|
||||
|
||||
// ── listProjects ──────────────────────────────────────────────────
|
||||
|
||||
describe('listProjects', () => {
|
||||
it('should shape projects with developer object and thumbnailUrl', async () => {
|
||||
mockQueryBus.execute.mockResolvedValue({
|
||||
data: [{
|
||||
id: 'p1', name: 'Test', slug: 'test',
|
||||
developer: 'Vingroup', developerLogo: 'logo.png',
|
||||
media: [{ url: 'img.jpg', type: 'image' }],
|
||||
}],
|
||||
total: 1, page: 1, limit: 20, totalPages: 1,
|
||||
});
|
||||
|
||||
const result = await controller.listProjects({ page: 1, limit: 20 } as any);
|
||||
|
||||
expect(result.data[0].developer).toEqual({
|
||||
id: 'Vingroup', name: 'Vingroup', logo: 'logo.png',
|
||||
});
|
||||
expect(result.data[0].thumbnailUrl).toBe('img.jpg');
|
||||
expect(result.data[0]).not.toHaveProperty('media');
|
||||
});
|
||||
|
||||
it('should handle null media', async () => {
|
||||
mockQueryBus.execute.mockResolvedValue({
|
||||
data: [{ id: 'p1', name: 'T', slug: 's', developer: 'D', developerLogo: null, media: null }],
|
||||
total: 1, page: 1, limit: 20, totalPages: 1,
|
||||
});
|
||||
|
||||
const result = await controller.listProjects({} as any);
|
||||
expect(result.data[0].thumbnailUrl).toBeNull();
|
||||
});
|
||||
|
||||
it('should handle empty media array', async () => {
|
||||
mockQueryBus.execute.mockResolvedValue({
|
||||
data: [{ id: 'p1', name: 'T', slug: 's', developer: 'D', developerLogo: null, media: [] }],
|
||||
total: 1, page: 1, limit: 20, totalPages: 1,
|
||||
});
|
||||
|
||||
const result = await controller.listProjects({} as any);
|
||||
expect(result.data[0].thumbnailUrl).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// ── listMyProjects ────────────────────────────────────────────────
|
||||
|
||||
describe('listMyProjects', () => {
|
||||
it('should pass user.sub as ownerId', async () => {
|
||||
mockQueryBus.execute.mockResolvedValue({
|
||||
data: [], total: 0, page: 1, limit: 20, totalPages: 0,
|
||||
});
|
||||
|
||||
const user = { sub: 'dev-1', role: 'DEVELOPER' };
|
||||
await controller.listMyProjects(user as any, {} as any);
|
||||
|
||||
const query = mockQueryBus.execute.mock.calls[0][0];
|
||||
expect(query.ownerId).toBe('dev-1');
|
||||
});
|
||||
});
|
||||
|
||||
// ── getProjectStats ───────────────────────────────────────────────
|
||||
|
||||
describe('getProjectStats', () => {
|
||||
it('should pass id, user.sub, and user.role', async () => {
|
||||
const stats = { projectId: 'p1', linkedListingCount: 5 };
|
||||
mockQueryBus.execute.mockResolvedValue(stats);
|
||||
|
||||
const user = { sub: 'admin-1', role: 'ADMIN' };
|
||||
const result = await controller.getProjectStats(user as any, 'p1');
|
||||
|
||||
expect(result).toBe(stats);
|
||||
const query = mockQueryBus.execute.mock.calls[0][0];
|
||||
expect(query.projectId).toBe('p1');
|
||||
expect(query.requesterUserId).toBe('admin-1');
|
||||
expect(query.requesterRole).toBe('ADMIN');
|
||||
});
|
||||
});
|
||||
|
||||
// ── getProject ────────────────────────────────────────────────────
|
||||
|
||||
describe('getProject', () => {
|
||||
it('should shape detail with media array preserved', async () => {
|
||||
mockQueryBus.execute.mockResolvedValue({
|
||||
id: 'p1', name: 'T', slug: 's', developer: 'D', developerLogo: null,
|
||||
media: [{ url: 'img.jpg' }],
|
||||
});
|
||||
|
||||
const result = await controller.getProject('s');
|
||||
expect(result.media).toEqual([{ url: 'img.jpg' }]);
|
||||
expect(result.developer).toEqual({ id: 'D', name: 'D', logo: null });
|
||||
});
|
||||
|
||||
it('should throw NotFoundException when result is null', async () => {
|
||||
mockQueryBus.execute.mockResolvedValue(null);
|
||||
|
||||
await expect(controller.getProject('nope')).rejects.toThrow(NotFoundException);
|
||||
});
|
||||
|
||||
it('should handle null media in detail', async () => {
|
||||
mockQueryBus.execute.mockResolvedValue({
|
||||
id: 'p1', name: 'T', slug: 's', developer: 'D', developerLogo: null,
|
||||
media: null,
|
||||
});
|
||||
|
||||
const result = await controller.getProject('s');
|
||||
expect(result.media).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
// ── createProject ─────────────────────────────────────────────────
|
||||
|
||||
describe('createProject', () => {
|
||||
it('should set ownerId to user.sub for DEVELOPER', async () => {
|
||||
mockCommandBus.execute.mockResolvedValue({ id: 'new-1', slug: 'test' });
|
||||
|
||||
const user = { sub: 'dev-1', role: 'DEVELOPER' };
|
||||
const dto = {
|
||||
name: 'P', slug: 'p', developer: 'D', totalUnits: 10,
|
||||
status: 'PLANNING', latitude: 10, longitude: 106,
|
||||
address: 'a', ward: 'w', district: 'd', city: 'HCM',
|
||||
};
|
||||
|
||||
await controller.createProject(user as any, dto as any);
|
||||
|
||||
const cmd = mockCommandBus.execute.mock.calls[0][0];
|
||||
expect(cmd.ownerId).toBe('dev-1');
|
||||
});
|
||||
|
||||
it('should set ownerId to null for ADMIN', async () => {
|
||||
mockCommandBus.execute.mockResolvedValue({ id: 'new-1', slug: 'test' });
|
||||
|
||||
const user = { sub: 'admin-1', role: 'ADMIN' };
|
||||
const dto = {
|
||||
name: 'P', slug: 'p', developer: 'D', totalUnits: 10,
|
||||
status: 'PLANNING', latitude: 10, longitude: 106,
|
||||
address: 'a', ward: 'w', district: 'd', city: 'HCM',
|
||||
};
|
||||
|
||||
await controller.createProject(user as any, dto as any);
|
||||
|
||||
const cmd = mockCommandBus.execute.mock.calls[0][0];
|
||||
expect(cmd.ownerId).toBeNull();
|
||||
});
|
||||
|
||||
it('should convert minPrice/maxPrice to BigInt', async () => {
|
||||
mockCommandBus.execute.mockResolvedValue({ id: 'new-1', slug: 'test' });
|
||||
|
||||
const user = { sub: 'dev-1', role: 'DEVELOPER' };
|
||||
const dto = {
|
||||
name: 'P', slug: 'p', developer: 'D', totalUnits: 10,
|
||||
status: 'PLANNING', latitude: 10, longitude: 106,
|
||||
address: 'a', ward: 'w', district: 'd', city: 'HCM',
|
||||
minPrice: '1000000000', maxPrice: '5000000000',
|
||||
};
|
||||
|
||||
await controller.createProject(user as any, dto as any);
|
||||
|
||||
const cmd = mockCommandBus.execute.mock.calls[0][0];
|
||||
expect(cmd.minPrice).toBe(BigInt('1000000000'));
|
||||
expect(cmd.maxPrice).toBe(BigInt('5000000000'));
|
||||
});
|
||||
|
||||
it('should convert startDate/completionDate to Date', async () => {
|
||||
mockCommandBus.execute.mockResolvedValue({ id: 'new-1', slug: 'test' });
|
||||
|
||||
const user = { sub: 'dev-1', role: 'DEVELOPER' };
|
||||
const dto = {
|
||||
name: 'P', slug: 'p', developer: 'D', totalUnits: 10,
|
||||
status: 'PLANNING', latitude: 10, longitude: 106,
|
||||
address: 'a', ward: 'w', district: 'd', city: 'HCM',
|
||||
startDate: '2024-01-01', completionDate: '2026-12-31',
|
||||
};
|
||||
|
||||
await controller.createProject(user as any, dto as any);
|
||||
|
||||
const cmd = mockCommandBus.execute.mock.calls[0][0];
|
||||
expect(cmd.startDate).toBeInstanceOf(Date);
|
||||
expect(cmd.completionDate).toBeInstanceOf(Date);
|
||||
});
|
||||
});
|
||||
|
||||
// ── updateProject ─────────────────────────────────────────────────
|
||||
|
||||
describe('updateProject', () => {
|
||||
it('should pass user info and dto params to UpdateProjectCommand', async () => {
|
||||
mockCommandBus.execute.mockResolvedValue({ id: 'p1' });
|
||||
|
||||
const user = { sub: 'admin-1', role: 'ADMIN' };
|
||||
const dto = { name: 'Updated', status: 'COMPLETED' };
|
||||
|
||||
await controller.updateProject(user as any, 'p1', dto as any);
|
||||
|
||||
const cmd = mockCommandBus.execute.mock.calls[0][0];
|
||||
expect(cmd.id).toBe('p1');
|
||||
expect(cmd.requesterUserId).toBe('admin-1');
|
||||
expect(cmd.requesterRole).toBe('ADMIN');
|
||||
expect(cmd.name).toBe('Updated');
|
||||
expect(cmd.status).toBe('COMPLETED');
|
||||
});
|
||||
|
||||
it('should convert minPrice to BigInt when provided', async () => {
|
||||
mockCommandBus.execute.mockResolvedValue({ id: 'p1' });
|
||||
|
||||
const user = { sub: 'admin-1', role: 'ADMIN' };
|
||||
const dto = { minPrice: '2000000000' };
|
||||
|
||||
await controller.updateProject(user as any, 'p1', dto as any);
|
||||
|
||||
const cmd = mockCommandBus.execute.mock.calls[0][0];
|
||||
expect(cmd.minPrice).toBe(BigInt('2000000000'));
|
||||
});
|
||||
|
||||
it('should leave minPrice as undefined when not in dto', async () => {
|
||||
mockCommandBus.execute.mockResolvedValue({ id: 'p1' });
|
||||
|
||||
const user = { sub: 'admin-1', role: 'ADMIN' };
|
||||
await controller.updateProject(user as any, 'p1', {} as any);
|
||||
|
||||
const cmd = mockCommandBus.execute.mock.calls[0][0];
|
||||
expect(cmd.minPrice).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
// ── deleteProject ─────────────────────────────────────────────────
|
||||
|
||||
describe('deleteProject', () => {
|
||||
it('should return { success: true }', async () => {
|
||||
mockCommandBus.execute.mockResolvedValue(undefined);
|
||||
|
||||
const user = { sub: 'admin-1', role: 'ADMIN' };
|
||||
const result = await controller.deleteProject(user as any, 'p1');
|
||||
|
||||
expect(result).toEqual({ success: true });
|
||||
|
||||
const cmd = mockCommandBus.execute.mock.calls[0][0];
|
||||
expect(cmd.id).toBe('p1');
|
||||
expect(cmd.requesterUserId).toBe('admin-1');
|
||||
expect(cmd.requesterRole).toBe('ADMIN');
|
||||
});
|
||||
});
|
||||
});
|
||||
447
docs/security/secret-rotation.md
Normal file
447
docs/security/secret-rotation.md
Normal file
@@ -0,0 +1,447 @@
|
||||
# Secret Rotation Runbook
|
||||
|
||||
**Owner:** Security Engineering
|
||||
**Tracker:** [GOO-121](/GOO/issues/GOO-121) · Parent: [GOO-85](/GOO/issues/GOO-85)
|
||||
**Last reviewed:** 2026-04-23
|
||||
**Audience:** On-call SRE, Security, Platform TechLead
|
||||
|
||||
This runbook covers rotation of GoodGo Platform's production secrets. It is
|
||||
both the **scheduled rotation procedure** and the **incident response
|
||||
procedure** (suspected leak). Every secret class below has:
|
||||
|
||||
1. Rotation trigger (scheduled + incident).
|
||||
2. Pre-flight checks.
|
||||
3. Step-by-step rotation.
|
||||
4. Verification.
|
||||
5. Rollback.
|
||||
|
||||
> **Golden rules**
|
||||
>
|
||||
> - Always rehearse in **staging** before touching production.
|
||||
> - Never paste production secrets into chat, issues, or commits.
|
||||
> - Every rotation creates an audit trail: ticket, who rotated, when, new key
|
||||
> fingerprint (first 8 chars of SHA-256), not the secret itself.
|
||||
> - Use a break-glass buddy for production rotations (two-person rule).
|
||||
|
||||
---
|
||||
|
||||
## 1. Secret inventory
|
||||
|
||||
| Secret class | Env vars | Rotation cadence | Blast radius | Owner |
|
||||
| ----------------------------- | ------------------------------------------------------------------------ | --------------------- | ------------------------------------------------------- | --------------- |
|
||||
| JWT signing keys | `JWT_SECRET`, `JWT_REFRESH_SECRET` | 90 days / on leak | All active user sessions | Security / Auth |
|
||||
| Field-level encryption | `FIELD_ENCRYPTION_KEY` | 180 days / on leak | At-rest encrypted columns (PII) | Security |
|
||||
| VNPay | `VNPAY_HASH_SECRET`, `VNPAY_TMN_CODE` | 90 days / on leak | All VNPay checkout + IPN | Payments |
|
||||
| MoMo | `MOMO_PARTNER_CODE`, `MOMO_ACCESS_KEY`, `MOMO_SECRET_KEY` | 90 days / on leak | All MoMo checkout + IPN | Payments |
|
||||
| ZaloPay | `ZALOPAY_APP_ID`, `ZALOPAY_KEY1`, `ZALOPAY_KEY2` | 90 days / on leak | All ZaloPay checkout + IPN | Payments |
|
||||
| Bank transfer webhook | `BANK_TRANSFER_WEBHOOK_SECRET` | 90 days / on leak | Inbound bank webhook verification | Payments |
|
||||
| Database password | `DATABASE_URL` (password portion) | 180 days / on leak | All API DB access | Platform |
|
||||
| Redis password | `REDIS_URL` / `REDIS_PASSWORD` | 180 days / on leak | Session cache, queues | Platform |
|
||||
| OAuth provider secrets | `GOOGLE_CLIENT_SECRET`, `ZALO_APP_SECRET` | 180 days / on leak | Social login flows | Auth |
|
||||
| Object storage | `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY` | 180 days / on leak | Media uploads/downloads | Platform |
|
||||
| Notification | `ZALO_OA_ACCESS_TOKEN` | Per provider policy | Push / OA messages | Growth |
|
||||
|
||||
All of these are enforced by `apps/api/src/modules/shared/infrastructure/env-validation.ts`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Key-generation reference
|
||||
|
||||
Use **only** cryptographically secure generators. Never use `Math.random`, UUIDs,
|
||||
or ad-hoc strings. Record only the **SHA-256 fingerprint** in the rotation
|
||||
ticket.
|
||||
|
||||
```bash
|
||||
# JWT / webhook / generic 256-bit+ secret (>= 32 chars, base64)
|
||||
openssl rand -base64 48
|
||||
|
||||
# Field-level encryption key (exactly 32 bytes, base64)
|
||||
openssl rand -base64 32
|
||||
|
||||
# Database / Redis password (URL-safe, 32+ chars)
|
||||
openssl rand -base64 36 | tr -d '/+=' | cut -c1-32
|
||||
|
||||
# Fingerprint to record in the rotation ticket (paste secret on stdin)
|
||||
printf '%s' "$NEW_SECRET" | openssl dgst -sha256 | cut -c1-16
|
||||
```
|
||||
|
||||
Storage: secrets live in the platform secret store (Vault / SSM / sealed
|
||||
secrets). **Never commit real values to `.env.example`** — that file documents
|
||||
names only.
|
||||
|
||||
---
|
||||
|
||||
## 3. JWT_SECRET / JWT_REFRESH_SECRET — dual-key rolling rotation
|
||||
|
||||
### 3.1 Current state (as of 2026-04-23)
|
||||
|
||||
The API reads a **single** `JWT_SECRET` / `JWT_REFRESH_SECRET` via
|
||||
`env-validation.ts` and `apps/api/src/modules/auth/infrastructure/strategies/jwt.strategy.ts`.
|
||||
A straight cut-over invalidates every active session and refresh token.
|
||||
|
||||
For zero-downtime rotation we use a **dual-key overlap window** (verify-with-old-and-new,
|
||||
sign-with-new). During the overlap window the app reads:
|
||||
|
||||
- `JWT_SECRET` — **new** key, used to sign all new tokens.
|
||||
- `JWT_SECRET_PREVIOUS` — **old** key, used only to verify unexpired tokens.
|
||||
|
||||
> Dual-key loading requires a small code change in `JwtStrategy` /
|
||||
> `TokenService` (pass both secrets, try new first, fall back to previous).
|
||||
> The code change is tracked as a follow-up; **until it ships, rotations are
|
||||
> "break sessions" rotations — schedule them during a low-traffic window and
|
||||
> pre-announce**.
|
||||
|
||||
### 3.2 Scheduled rotation (dual-key path, once code is in place)
|
||||
|
||||
1. **Pre-flight**
|
||||
- Ticket opened, change window booked, on-call notified.
|
||||
- Staging rehearsal complete within last 7 days.
|
||||
- Verify current access-token TTL (`JWT_EXPIRES_IN`, default `15m`) and
|
||||
refresh-token TTL (default `30d`). The overlap window must be **≥** the
|
||||
longest valid token's remaining life.
|
||||
|
||||
2. **Generate new secrets**
|
||||
|
||||
```bash
|
||||
NEW_JWT=$(openssl rand -base64 48)
|
||||
NEW_JWT_REFRESH=$(openssl rand -base64 48)
|
||||
```
|
||||
|
||||
3. **Stage the overlap**
|
||||
|
||||
In the secret store:
|
||||
|
||||
| Variable | Value |
|
||||
| --------------------------- | ------------------- |
|
||||
| `JWT_SECRET_PREVIOUS` | current `JWT_SECRET` |
|
||||
| `JWT_SECRET` | `$NEW_JWT` |
|
||||
| `JWT_REFRESH_SECRET_PREVIOUS` | current `JWT_REFRESH_SECRET` |
|
||||
| `JWT_REFRESH_SECRET` | `$NEW_JWT_REFRESH` |
|
||||
|
||||
Roll the API deployment. Monitor `auth_login_total`, `auth_refresh_total`,
|
||||
`auth_jwt_verify_failure_total`. Expected: no spike in 401s.
|
||||
|
||||
4. **Hold overlap**
|
||||
|
||||
Keep both keys live for **refresh-TTL + 24 h** (default 31 days). During this
|
||||
time old tokens continue to verify against `*_PREVIOUS`, but every refresh
|
||||
mints a new token signed with the new key.
|
||||
|
||||
5. **Retire previous key**
|
||||
|
||||
Remove `JWT_SECRET_PREVIOUS` and `JWT_REFRESH_SECRET_PREVIOUS` from the
|
||||
secret store. Redeploy. At this point any remaining token signed with the
|
||||
old key will fail verification — which is the intended end state.
|
||||
|
||||
6. **Audit**
|
||||
- Record fingerprints of new keys in the rotation ticket.
|
||||
- Confirm no secrets appear in git, logs, or issue comments.
|
||||
|
||||
### 3.3 Incident rotation (suspected leak)
|
||||
|
||||
Skip the overlap. This **will** invalidate all sessions; that is the point.
|
||||
|
||||
1. Generate new `JWT_SECRET` / `JWT_REFRESH_SECRET`.
|
||||
2. Put service in maintenance mode (optional — it's graceful without it).
|
||||
3. Update secret store → redeploy API.
|
||||
4. Invalidate server-side sessions:
|
||||
- Flush Redis key prefix `auth:user_status:v1:*` (see `jwt.strategy.ts`
|
||||
constant `USER_STATUS_CACHE_PREFIX`).
|
||||
- Truncate `RefreshToken` table (or flag revoked) so no old refresh token
|
||||
can mint a new access token.
|
||||
5. Announce forced re-login to users.
|
||||
6. Post-mortem within 48 h.
|
||||
|
||||
### 3.4 Verification
|
||||
|
||||
- `GET /health/ready` returns 200.
|
||||
- Smoke: login with a test account, hit an authenticated endpoint, refresh.
|
||||
- Metrics: `auth_jwt_verify_failure_total` returns to baseline within 1 h.
|
||||
|
||||
### 3.5 Rollback
|
||||
|
||||
- Scheduled rotation: put old value back into `JWT_SECRET` / `JWT_REFRESH_SECRET`
|
||||
(still present in `*_PREVIOUS` during overlap) and redeploy.
|
||||
- Incident rotation: there is no rollback — old key is assumed burned.
|
||||
|
||||
---
|
||||
|
||||
## 4. Payment provider secrets — VNPay / MoMo / ZaloPay
|
||||
|
||||
Payment secrets are **shared** with the provider; you cannot rotate them
|
||||
unilaterally. The rotation is always a coordinated cut-over via the provider
|
||||
portal.
|
||||
|
||||
### 4.1 Scope
|
||||
|
||||
| Provider | Variables rotated in portal + our env |
|
||||
| -------- | ------------------------------------------------------------------------------ |
|
||||
| VNPay | `VNPAY_HASH_SECRET` (keep `VNPAY_TMN_CODE` stable unless the merchant rotates) |
|
||||
| MoMo | `MOMO_ACCESS_KEY`, `MOMO_SECRET_KEY` |
|
||||
| ZaloPay | `ZALOPAY_KEY1`, `ZALOPAY_KEY2` |
|
||||
|
||||
All three providers sign both request and IPN callback. A mismatched secret
|
||||
causes signature-verification failure on both legs.
|
||||
|
||||
### 4.2 Pre-flight
|
||||
|
||||
- Low-traffic window booked (recommend 02:00–04:00 ICT).
|
||||
- Coordinate with the provider account manager; confirm the portal supports
|
||||
immediate rotation (VNPay and MoMo do; ZaloPay requires ticket for prod).
|
||||
- Staging rehearsal completed within last 14 days (see §4.5).
|
||||
- Freeze new checkouts if the provider cannot overlap old + new secrets (most
|
||||
cannot — rotation is atomic).
|
||||
- Payments-on-call paged.
|
||||
- Confirm no in-flight IPNs older than the provider's retry window
|
||||
(VNPay 24 h, MoMo 24 h, ZaloPay 48 h).
|
||||
|
||||
### 4.3 Scheduled rotation (production)
|
||||
|
||||
1. **Drain:** stop the checkout queue consumers; let in-flight IPNs settle for
|
||||
the provider's retry window.
|
||||
2. **Provider portal:** log in → rotate secret → record new value + fingerprint
|
||||
in the rotation ticket.
|
||||
3. **Secret store:** update our env with the new value.
|
||||
4. **Deploy:** roll the API. Consumers come back up.
|
||||
5. **Smoke:** run the provider-specific test transaction (sandbox-shaped
|
||||
minimum amount). Verify both checkout and IPN sign + verify with the new
|
||||
secret.
|
||||
6. **Monitor for 60 min:**
|
||||
- `payment_signature_failure_total{provider}` stays at baseline.
|
||||
- `payment_ipn_reject_total{provider}` stays at baseline.
|
||||
- No unusual refund / reconciliation drift.
|
||||
|
||||
### 4.4 Incident rotation (suspected leak)
|
||||
|
||||
Same steps as §4.3, but compress the timeline and accept failed in-flight
|
||||
transactions — better a handful of failed checkouts than a compromised secret.
|
||||
File a follow-up for manual reconciliation of any payment created in the 30 min
|
||||
before the rotation.
|
||||
|
||||
### 4.5 Staging rehearsal
|
||||
|
||||
The staging rehearsal for payment secrets **must** exist as a dry run before
|
||||
any production rotation. Use the sandbox credentials documented in the
|
||||
payments module runbook (each provider has a public sandbox).
|
||||
|
||||
Record in the drill report (see §8):
|
||||
|
||||
- Duration from "portal updated" to "first successful IPN verified".
|
||||
- Any failed transactions and their reason codes.
|
||||
- Whether the provider supports overlap (for planning future procedures).
|
||||
|
||||
### 4.6 Rollback
|
||||
|
||||
- If the provider portal still has the old secret active (rare — most providers
|
||||
replace), revert the env var and redeploy.
|
||||
- Otherwise rotate forward again to a freshly generated value; there is no way
|
||||
to "un-rotate" at the provider.
|
||||
|
||||
---
|
||||
|
||||
## 5. DATABASE_URL password — zero-downtime rotation
|
||||
|
||||
### 5.1 Strategy
|
||||
|
||||
Postgres supports **multiple roles** and connection strings already identify a
|
||||
user. We rotate the password in two phases, using a transient dual-password
|
||||
state via a second role:
|
||||
|
||||
1. Create a shadow role `goodgo_app_v2` with the **new** password, same
|
||||
privileges as the live role. Permit both roles to authenticate.
|
||||
2. Update the app's `DATABASE_URL` to point at the new role. Roll the API.
|
||||
3. Once all API pods have reconnected, drop the old role (or reset its
|
||||
password and keep it as a break-glass).
|
||||
|
||||
Postgres itself does not support "two valid passwords for one role"; swapping
|
||||
roles is the clean zero-downtime path.
|
||||
|
||||
### 5.2 Pre-flight
|
||||
|
||||
- PostgreSQL 16 + PgBouncer connection pool verified healthy.
|
||||
- Staging rehearsal completed within last 14 days.
|
||||
- `pg_stat_activity` reviewed; no long-running migrations.
|
||||
- Backup snapshot taken within last 6 h (see `docs/backup-restore.md`).
|
||||
|
||||
### 5.3 Scheduled rotation
|
||||
|
||||
```sql
|
||||
-- Phase 1: create shadow role (run as DB owner / postgres)
|
||||
CREATE ROLE goodgo_app_v2 LOGIN PASSWORD '<NEW_PASSWORD>';
|
||||
GRANT goodgo_app TO goodgo_app_v2; -- inherit group, or mirror explicit grants
|
||||
GRANT CONNECT ON DATABASE goodgo TO goodgo_app_v2;
|
||||
GRANT USAGE ON SCHEMA public TO goodgo_app_v2;
|
||||
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO goodgo_app_v2;
|
||||
-- Mirror any other grants the live role has. Verify with:
|
||||
-- \du goodgo_app
|
||||
```
|
||||
|
||||
```bash
|
||||
# Phase 2: update secret store, then roll API
|
||||
# DATABASE_URL=postgresql://goodgo_app_v2:<NEW_PASSWORD>@host:5432/goodgo?sslmode=require
|
||||
|
||||
# Rolling restart — one pod at a time; watch readiness probe before moving on.
|
||||
kubectl -n goodgo rollout restart deployment/api
|
||||
kubectl -n goodgo rollout status deployment/api --timeout=10m
|
||||
```
|
||||
|
||||
```sql
|
||||
-- Phase 3: verify no sessions still on old role, then retire it.
|
||||
-- Run 30+ minutes after rollout completes.
|
||||
SELECT usename, count(*) FROM pg_stat_activity WHERE usename IN ('goodgo_app','goodgo_app_v2') GROUP BY usename;
|
||||
-- Expect: only goodgo_app_v2 connections.
|
||||
|
||||
-- Option A: drop the old role (only if no other consumers use it).
|
||||
-- REASSIGN OWNED BY goodgo_app TO goodgo_app_v2;
|
||||
-- DROP OWNED BY goodgo_app;
|
||||
-- DROP ROLE goodgo_app;
|
||||
|
||||
-- Option B (recommended): reset its password to a fresh random value and keep
|
||||
-- it as an emergency break-glass. Document the fingerprint in the ticket.
|
||||
ALTER ROLE goodgo_app PASSWORD '<RANDOM_BREAKGLASS>';
|
||||
```
|
||||
|
||||
For the next rotation, flip the naming (`goodgo_app_v2` → `goodgo_app_v3`),
|
||||
keeping the alternation going. This avoids ever needing to drop and recreate
|
||||
the "canonical" role name.
|
||||
|
||||
### 5.4 PgBouncer considerations
|
||||
|
||||
If PgBouncer sits in front of Postgres:
|
||||
|
||||
- Update `userlist.txt` (or its auth source) with both roles **before** the
|
||||
API roll.
|
||||
- `RELOAD` PgBouncer; do not `RESTART` (clients reconnect automatically from
|
||||
`RELOAD` without dropping server-side transactions).
|
||||
- Verify with `SHOW USERS;` on the PgBouncer admin console.
|
||||
|
||||
### 5.5 Incident rotation
|
||||
|
||||
Same steps but:
|
||||
|
||||
- Skip the 30-minute settle in Phase 3 — rotate immediately to Option A (drop
|
||||
the compromised role) once no active sessions remain.
|
||||
- If a session is actively using the compromised role, terminate it:
|
||||
```sql
|
||||
SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE usename = 'goodgo_app';
|
||||
```
|
||||
- Run a post-rotation audit on the compromised-role's activity since the last
|
||||
known-good window.
|
||||
|
||||
### 5.6 Verification
|
||||
|
||||
- `GET /health/ready` reports DB connectivity 200.
|
||||
- `db_connection_pool_active` returns to steady state.
|
||||
- Smoke queries via `pnpm db:studio` with the new credential.
|
||||
|
||||
### 5.7 Rollback
|
||||
|
||||
- Until Phase 3 completes, rollback is: revert `DATABASE_URL` to the old role
|
||||
and redeploy. The old role still authenticates.
|
||||
- After Phase 3 Option A (drop): no rollback; restore from snapshot is the
|
||||
last resort.
|
||||
|
||||
---
|
||||
|
||||
## 6. FIELD_ENCRYPTION_KEY
|
||||
|
||||
Rotating the field-encryption key requires **re-encrypting at-rest data**. It
|
||||
is not a hot swap. Out of scope for this runbook beyond documenting that it
|
||||
exists and requires its own migration playbook. A separate issue will track
|
||||
the re-encryption tooling; until then:
|
||||
|
||||
- Generate and stage the new key alongside the old (`FIELD_ENCRYPTION_KEY` +
|
||||
`FIELD_ENCRYPTION_KEY_PREVIOUS`).
|
||||
- Do not flip the primary until a re-encrypt job has rewritten all
|
||||
encrypted columns.
|
||||
- This path is **approved-change-only** (CTO sign-off).
|
||||
|
||||
Tracked as follow-up: see §9.
|
||||
|
||||
---
|
||||
|
||||
## 7. Rotation checklist (copy into the rotation ticket)
|
||||
|
||||
```md
|
||||
## Rotation — <secret class> — <env>
|
||||
|
||||
- [ ] Ticket opened in Paperclip; linked to [GOO-121](/GOO/issues/GOO-121)
|
||||
- [ ] Change window booked (date/time ICT)
|
||||
- [ ] Staging rehearsal completed (date, drill report link)
|
||||
- [ ] Buddy on-call: <name>
|
||||
- [ ] New secret generated with `openssl rand -base64 48` (or class-specific)
|
||||
- [ ] New-secret fingerprint (SHA-256 first 16 chars): `________________`
|
||||
- [ ] Secret store updated (do not paste the value here)
|
||||
- [ ] Deploy rolled; readiness probes green
|
||||
- [ ] Smoke + metrics verified (link to dashboard snapshot)
|
||||
- [ ] Overlap window end date (JWT only): ____
|
||||
- [ ] Old secret retired / role dropped (timestamp)
|
||||
- [ ] Post-rotation audit note in ticket
|
||||
- [ ] Runbook updated if anything surprised us
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Drill report template
|
||||
|
||||
Each scheduled rotation — starting with a staging dry run — produces a drill
|
||||
report posted as a comment on [GOO-121](/GOO/issues/GOO-121) (for the initial
|
||||
drill) or on the rotation ticket.
|
||||
|
||||
```md
|
||||
## Drill report — <secret class> — <env> — <date>
|
||||
|
||||
**Window:** 02:00–02:47 ICT
|
||||
**Rotated by:** <agent/user> with buddy <name>
|
||||
|
||||
### Timeline
|
||||
- 02:00 — Pre-flight complete
|
||||
- 02:05 — New secret generated (fingerprint `abcd1234…`)
|
||||
- 02:10 — Secret store updated
|
||||
- 02:12 — Deployment rolled
|
||||
- 02:18 — Smoke passed
|
||||
- 02:20 — Monitoring baseline confirmed
|
||||
- 02:47 — Drill closed
|
||||
|
||||
### Results
|
||||
- Duration: 47 min
|
||||
- Auth errors during rotation: 0 (scheduled) / N (incident — list)
|
||||
- Payment failures: 0 / N
|
||||
- Rollback triggered: no
|
||||
- Follow-ups: link any new issues created
|
||||
|
||||
### Learnings
|
||||
- …
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Follow-ups
|
||||
|
||||
The following items are **not** delivered by this runbook and should be
|
||||
tracked as separate issues:
|
||||
|
||||
- **Dual-key JWT code path.** `JwtStrategy` and `TokenService` need to accept
|
||||
`JWT_SECRET_PREVIOUS` / `JWT_REFRESH_SECRET_PREVIOUS` so §3.2 is truly
|
||||
zero-downtime. Until then, JWT rotation invalidates sessions.
|
||||
- **Field-encryption re-encrypt tool.** Required before `FIELD_ENCRYPTION_KEY`
|
||||
can be rotated safely in production.
|
||||
- **Secret-store automation.** Today rotations are manual via the secret
|
||||
store UI; an automated rotator (Vault / SSM Parameter Store rotation
|
||||
lambda) would shrink the window and reduce human error.
|
||||
- **Production rotation approval.** Payment + DB password rotations in
|
||||
production require a CTO approval window — see [GOO-85](/GOO/issues/GOO-85).
|
||||
|
||||
---
|
||||
|
||||
## 10. References
|
||||
|
||||
- `apps/api/src/modules/shared/infrastructure/env-validation.ts` — authoritative
|
||||
list of required secrets and minimum-length enforcement.
|
||||
- `apps/api/src/modules/auth/infrastructure/strategies/jwt.strategy.ts` —
|
||||
current single-key JWT verification path.
|
||||
- `docs/RUNBOOK.md` — general incident response procedures.
|
||||
- `docs/backup-restore.md` — database snapshot / restore steps invoked during
|
||||
DB password rotation pre-flight.
|
||||
- `docs/security/PAYMENT_SECURITY_CHECKLIST.md` — payment security controls.
|
||||
- Parent tracker: [GOO-85](/GOO/issues/GOO-85).
|
||||
Reference in New Issue
Block a user