feat(F-138): completed feature
This commit is contained in:
chattie
86
spec/tech.md
86
spec/tech.md
@@ -1,49 +1,51 @@
|
||||
# F-154 — Technical Design
|
||||
# F-138 — Especificación técnica
|
||||
|
||||
## Context
|
||||
- `identity_users` tiene `role: citext NOT NULL DEFAULT 'customer'` (valores: `customer`,
|
||||
`admin`, `editor`, `pos_cashier`, `pos_manager`). `customer` = storefront; el resto = backoffice.
|
||||
- `GET /users` (módulo `users`): `PgProfileRepository.listCustomers` hace
|
||||
`SELECT ... FROM identity_users iu LEFT JOIN users_profiles up ... WHERE ($1::text IS NULL OR iu.email ILIKE $1)`.
|
||||
Devuelve TODO. Usado por `clientsApi.list` (página Customers) → `/api/users`.
|
||||
- `GET /admin/users` (módulo `security`): query inline con condiciones opcionales `role` y `q`.
|
||||
Sin `?role=` devuelve TODO. Usado por `adminUsersApi.list` (página Users) → `/api/admin/users`.
|
||||
- `listCustomers` se consume SOLO en `users.routes.ts` (`/users`). `findCustomerById`
|
||||
(single, `/users/:id`) es role-agnostic (owner-or-admin) → no cambia.
|
||||
- No existe test de `users`/`security` routes; `users.itest.ts` AC2/AC3 asocia al admin (ana)
|
||||
al listado `/users` (true hoy porque /users devuelve todo; romperá si /users es customer-only).
|
||||
## Contrato de separación (F-154 precedent)
|
||||
- `pricing` **es dueño** de `pricing_variant_prices` (tabla a su módulo). No se inserta desde `catalog` con SQL crudo — se expone un método en el **servicio público** `PricingService` (patrón idéntico al que `cart` ya inyecta en build-app: cross-module write vía servicio público, R1 legal).
|
||||
|
||||
## Decision
|
||||
Forzar la separación en el backend (no cliente):
|
||||
1. `listCustomers` → siempre `... AND iu.role = 'customer'` (literal, no user input → sin inyección).
|
||||
Parámetros inalterados: `[searchFilter, limit, offset]`; COUNT también filtra por rol.
|
||||
2. `GET /admin/users` → condición base `role <> 'customer'` (literal). `?role=admin|editor`
|
||||
se andaña con `AND role = $1`. Así `/admin/users` NUNCA devuelve customers, incluso con
|
||||
`?role=customer` (devuelve vacío). Parámetro base es literal → índices de `$N` de los
|
||||
filtros opcionales inalterados.
|
||||
3. Frontend: dropdown de Users quita `<option value="customer">`.
|
||||
## Cambios
|
||||
|
||||
## Alternatives
|
||||
- Filtrado cliente-only: rechazado. El backend es la fuente única de verdad; el cliente no
|
||||
debe poder ver customers vía `/admin/users`.
|
||||
- Nuevo endpoint `/customers`: rechazado. El cliente ya consume `/users` (customers) y
|
||||
`/admin/users` (internos); crear `/customers` duplicaría y obligaría cambios frontend
|
||||
sin valor.
|
||||
### 1. `pricing/domain/ports.ts`
|
||||
- Añadir a `PricingRepository`: `seedVariantPrice(variantId: string): Promise<void>`.
|
||||
- Añadir a `PricingService`: `seedVariantPrice(variantId: string): Promise<void>`.
|
||||
|
||||
## Boundary / Security
|
||||
- `users` módulo referencia `identity_users` SOLO como nombre de tabla SQL (patrón ya usado en
|
||||
`search`); sin import TS users↔security. `lint:boundaries` sin cambios nuevos.
|
||||
- `role` proviene de la DB (no user input directo en el filtro de roles; el literal `'customer'`/`'customer'`
|
||||
está en código). En `/admin/users`, `?role=` validado por zod enum `['customer','editor','admin']`.
|
||||
- Sin inyección: los valores user input (`q`, `role`) siguen parametrizados (`$N`); los literales
|
||||
`role = 'customer'` / `role <> 'customer'` son constantes de código.
|
||||
### 2. `pricing/application/pricing-service.ts`
|
||||
- `PricingService.seedVariantPrice(variantId)` → delega a `this.repository.seedVariantPrice(variantId)`. Sin validación extra (el `variantId` ya proviene de una variante creada en la misma transacción lógica).
|
||||
|
||||
## Migration
|
||||
Ninguna. `identity_users.role` ya existe (NOT NULL DEFAULT 'customer').
|
||||
### 3. `pricing/infrastructure/pg-pricing-repository.ts`
|
||||
```ts
|
||||
async seedVariantPrice(variantId: string): Promise<void> {
|
||||
await this.pool.query(
|
||||
`INSERT INTO pricing_variant_prices (variant_id, net_unit_amount_cents, offer_cents, cost_cents, vat_rate)
|
||||
VALUES ($1, 0, NULL, NULL, 'general')
|
||||
ON CONFLICT (variant_id) DO NOTHING`,
|
||||
[variantId],
|
||||
);
|
||||
}
|
||||
```
|
||||
- Columnas idénticas al INSERT de `setVariantPrice` (omite `currency` → DDL default `'EUR'`; `created_at`/`updated_at` → `now()` DDL default). Reutiliza `VatRate = 'general'`.
|
||||
- `ON CONFLICT (variant_id)` válido: `variant_id` es UNIQUE/PK (usado por `setVariantPrice`). → **idempotente / re-sembbrado no-op**.
|
||||
|
||||
### 4. `catalog/application/variant-use-cases.ts`
|
||||
- Import (type, público, R1): `import type { PricingService } from '../../pricing/index.js';` (catalog/application → ../../pricing/index = modules/pricing/index ✓ R1 a index público).
|
||||
- `CreateProductVariant` recibe `pricing: PricingService` en ctor.
|
||||
- `execute`: tras `this.variants.create(productId, input)` (y solo si el producto existe), `await this.pricing.seedVariantPrice(variant.id)` **best-effort** (try/catch silencioso: la variante ya persistió; un fallo del seed no revierte la creación).
|
||||
|
||||
### 5. `catalog/api/catalog.routes.ts`
|
||||
- `CatalogRoutesDeps` += `pricing: PricingService` (import type desde pricing index — R1).
|
||||
- `const createVariant = new CreateProductVariant(repository, variants, pricing);` (único constructor; cubre los 3 call sites: POST /products autovariante, GET /products/:id/variants lazy, POST /products/:id/variants).
|
||||
|
||||
### 6. `build-app.ts`
|
||||
- Mover `const pricing = createPricingService(deps.pool);` **antes** del bloque `registerCatalogRoutes` (actualmente está después → orden L247 catalog, L264 pricing). Crear pricing antes del registro de catalog permite pasarlo a `CatalogRoutesDeps`.
|
||||
- Pasar `pricing` en deps de `registerCatalogRoutes`.
|
||||
- La ruta de pricing (`registerPricingRoutes`) y cart siguen usando `pricing` (sin cambios; pricing sigue definido). `createPricingService` ya está importado (L33).
|
||||
|
||||
## Riesgos / mitigaciones
|
||||
- **Orden en build-app (timing):** mover `const pricing` antes de catalog es seguro (constructor puro, `deps.pool` disponible). Precio routes lo vuelve a usar → no se rompe.
|
||||
- **Fallo del seed:** best-effort (try/catch) → no hace 500 en variant creation. AC3 lo prueba.
|
||||
- **Doble creación (createVariant en autovariante + retry):** `ON CONFLICT DO NOTHING` → idempotente. AC2 lo prueba.
|
||||
- **Boundary R1:** catalog→pricing público index ✓ (cart ya lo usa). Deep imports prohibidos — usar `../../pricing/index.js`.
|
||||
|
||||
## Tests
|
||||
- `pg-profile-repository.test.ts` (mock pool): `listCustomers` emite `iu.role = 'customer'`,
|
||||
`q` filtra sobre email, COUNT y SELECT coinciden, returns solo filas customer.
|
||||
- `security.routes.test.ts` (mock app+deps): `/admin/users` default → `role <> 'customer'`;
|
||||
`?role=admin` → `role <> 'customer' AND role = $1`; respuesta items internos.
|
||||
- `users.itest.ts` AC2/AC3: actualizar aserción — `/users` devuelve customer (ben) no admin (ana).
|
||||
- **Unitario (runnable, sin DB):** `catalog/tests/variant-use-cases.test.ts` — FakeProductRepository, FakeProductVariantRepository, FakePricingService; assert (a) seedVariantPrice llamado con variant.id tras create, (b) no se sembran si producto no existe, (c) create sigue devolviendo variante si seed lanza.
|
||||
- **Integración (AC):** itest en `catalog.itest.ts` skipIf(!hasDb) — POST /products/:id/variants → GET /pricing/variants/:id = 200 con `netUnitAmountCents=0`, `vatRate='general'`. Skipped sin `TEST_DATABASE_URL` (no bloquea verify.sh).
|
||||
|
||||
Reference in New Issue
Block a user