Bài 65: Soft Delete Pattern Đầy Đủ + Update Parent

Sau bài học, bạn sẽ:

• Áp dụng soft delete pattern cho 3 resource khác nhau: orders (cancel state), users (deactivate), categories (deleted_at).
• Phân biệt soft delete state-based (orders.status) so với timestamp-based (deleted_at) và biết khi nào chọn cái nào.
• Implement update_parent categories với cycle detection qua WITH RECURSIVE EXISTS subquery.
• Implement bulk restore endpoint POST /admin/products/restore-bulk với cap 100 slug/request.
• Implement GET /admin/audit-logs filter endpoint với QueryBuilder dynamic SQL 4 filter.
• Tạo migration users table với 4-state lifecycle (active/suspended/deactivated) + deleted_at cho GDPR (preparation cho Group 11 auth).
• Hiểu trade-off audit trail vs storage cost và roadmap partition cho production.

B62 đã lock timestamp-based soft delete cho products qua cột deleted_at TIMESTAMPTZ NULL + audit log table. B63 áp dụng cùng pattern cho categories. Khi tiến tới orders + users, semantic xóa khác nhau buộc phải chọn 1 trong 3 model:

• Timestamp-based (deleted_at TIMESTAMPTZ) — đơn giản nhất, mỗi mutation chỉ cần set deleted_at = NOW() thay DELETE. Use case: products, categories, users (B62 + B63 lock). Pros: pattern thống nhất mọi resource, restore dễ (set NULL), partial index WHERE deleted_at IS NULL giữ hot subset nhanh. Cons: mất semantic vì sao xóa — không biết user tự xóa hay admin ban, không biết refund hay duplicate.
• State-based (status enum) — cột text với CHECK constraint giới hạn giá trị hợp lệ. Use case điển hình: orders với 5 trạng thái pending → paid → shipped → delivered + transition phụ cancelled. Pros: rich semantic phân biệt cancelled vs refunded vs returned (3 case khác nhau cho cùng "đã xóa khỏi flow active"), state machine cưỡng chế transition hợp lệ qua code. Cons: phức tạp hơn, mỗi state transition phải validate, query filter active phải combine theo state thay 1 cột NULL.
• Combined (state + timestamp) — cả 2 cùng tồn tại trên 1 bảng. Use case: users với status: active/suspended/deactivated + deleted_at riêng cho GDPR hard erase. Pros: multi-stage soft delete linh hoạt — user tự "deactivate" account vẫn giữ data 30 ngày restore, sau đó admin xóa PII qua deleted_at theo Article 17 GDPR. Cons: filter query phức tạp hơn — phải combine 2 điều kiện cho mọi list endpoint.

Lock decision Shop API qua bảng mapping:

Resource    | Model         | Cột tracking                    | Restore khả thi
products    | Timestamp     | deleted_at                       | SET NULL
categories  | Timestamp     | deleted_at                       | SET NULL
orders      | State         | status enum (cancelled)          | KHÔNG (đơn đã hủy không revert)
users       | Combined      | status enum + deleted_at GDPR    | SET status (deleted_at irreversible)

Điểm cốt lõi cần nhớ: orders KHÔNG có cột deleted_at — semantic "đơn hàng đã hủy" được biểu đạt qua status = 'cancelled'. Đây là exception duy nhất của soft delete lock B62 timestamp-based, đánh dấu vì orders mang giá trị tài chính — không bao giờ xóa khỏi DB (audit kế toán bắt buộc), chỉ chuyển sang state terminal.

Tạo migration 9 create_users. Bảng users hiện chưa có trong DB (B54 đã tạo orders.user_id BIGINT chưa kèm FK), nên migration này vừa tạo bảng mới vừa ALTER TABLE orders thêm constraint:

sqlx migrate add --source crates/shop-db/migrations create_users

-- File: crates/shop-db/migrations/20260615180000_create_users.sql

CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    email TEXT NOT NULL UNIQUE,
    password_hash TEXT NOT NULL,
    display_name TEXT NOT NULL,
    phone TEXT,
    avatar_url TEXT,
    status TEXT NOT NULL DEFAULT 'active'
        CHECK (status IN ('active', 'suspended', 'deactivated')),
    deleted_at TIMESTAMPTZ,           -- GDPR right-to-erasure hard delete
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    last_login_at TIMESTAMPTZ
);

-- Partial index — chỉ user active (hot path login)
CREATE INDEX users_email_active_idx
    ON users(email) WHERE deleted_at IS NULL;

CREATE INDEX users_status_idx
    ON users(status) WHERE deleted_at IS NULL;

CREATE INDEX users_active_idx
    ON users(deleted_at) WHERE deleted_at IS NULL;

CREATE TRIGGER users_updated_at
    BEFORE UPDATE ON users
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

-- Hoàn thành FK orders.user_id (B54 preview)
ALTER TABLE orders
    ADD CONSTRAINT orders_user_fk
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT;

4-state lifecycle của users:

• active — user bình thường, login + checkout được, hiển thị mặc định trong mọi list admin.
• suspended — admin tạm khóa (vi phạm chính sách, đang debug fraud). User không login được nhưng data còn nguyên, restore qua admin UI.
• deactivated — user tự deactivate từ UI "Delete my account". Sau 30 ngày grace period nếu không activate lại, admin job set deleted_at = NOW() GDPR hard erase.
• deleted_at != NULL — GDPR Article 17 right-to-erasure đã thực thi, PII đã anonymize (email → user-{id}@deleted.local, display_name → "Deleted User", phone NULL, avatar_url NULL). Row giữ lại để bảo toàn FK orders.user_id reference (đơn hàng cũ vẫn còn tồn tại theo luật kế toán Việt Nam giữ 10 năm).

Apply migration:

sqlx migrate run --source crates/shop-db/migrations
# Hoặc khởi động shop-api với AUTO_MIGRATE=true (B52 lock)
AUTO_MIGRATE=true cargo run -p shop-api -- serve

Tạo skeleton crates/shop-db/src/users.rs cho B65 — chỉ định nghĩa UserRow struct + UserStatus enum, CRUD chi tiết để B71+ implement đầy đủ trong Group 11 Authentication:

// File: crates/shop-db/src/users.rs

use chrono::{DateTime, Utc};

#[derive(Debug, Clone, sqlx::FromRow)]
pub struct UserRow {
    pub id: i64,
    pub email: String,
    pub password_hash: String,
    pub display_name: String,
    pub phone: Option<String>,
    pub avatar_url: Option<String>,
    pub status: String,
    pub deleted_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub last_login_at: Option<DateTime<Utc>>,
}

// CRUD đầy đủ implement ở Group 11 Authentication (B101+)
// B65 chỉ cần struct + FK để extend orders.rs cancel_order audit actor

B54 đã lock orders với cột status TEXT CHECK IN ('pending', 'paid', 'shipped', 'delivered', 'cancelled'). Bảng state transition hợp lệ:

From       | To           | Allowed | Lý do
pending    | paid         | YES     | Customer thanh toán thành công
pending    | cancelled    | YES     | Customer huỷ trước thanh toán
paid       | shipped      | YES     | Warehouse xác nhận xuất kho
paid       | cancelled    | YES     | Refund flow B71 (Stripe refund)
shipped    | delivered    | YES     | Vận chuyển xác nhận giao
shipped    | cancelled    | NO      | Đã giao vận chuyển — phải dùng return endpoint B68
delivered  | cancelled    | NO      | Đã giao đến tay — phải dùng return endpoint B68
cancelled  | bất kỳ       | NO      | Terminal state

Implement cancel_order trong crates/shop-db/src/orders.rs với 5 step kèm pessimistic row lock chống race condition giữa 2 admin cùng huỷ 1 đơn:

// File: crates/shop-db/src/orders.rs

use sqlx::PgPool;
use crate::audit;

pub async fn cancel_order(
    pool: &PgPool,
    order_id: i64,
    actor_user_id: Option<i64>,
    request_id: Option<&str>,
) -> Result<OrderRow, OrderError> {
    let mut tx = pool.begin().await?;

    // Step 1: Get current status với FOR UPDATE (row lock chống race)
    let current = sqlx::query!(
        "SELECT status FROM orders WHERE id = $1 FOR UPDATE",
        order_id
    )
    .fetch_optional(&mut *tx)
    .await?
    .ok_or(OrderError::NotFound(order_id))?;

    // Step 2: Validate state transition
    match current.status.as_str() {
        "pending" | "paid" => {} // OK to cancel
        "shipped" | "delivered" | "cancelled" => {
            tx.rollback().await?;
            return Err(OrderError::InvalidTransition {
                from: current.status,
                to: "cancelled".into(),
            });
        }
        _ => unreachable!("invalid status in DB — CHECK constraint vi phạm"),
    }

    // Step 3: Restore stock cho mọi item của order
    sqlx::query!(
        r#"
        UPDATE products SET stock = stock + oi.quantity
        FROM order_items oi
        WHERE oi.order_id = $1 AND products.id = oi.product_id
        "#,
        order_id
    )
    .execute(&mut *tx)
    .await?;

    // Step 4: Update order status
    let order = sqlx::query_as!(
        OrderRow,
        r#"
        UPDATE orders SET status = 'cancelled'
        WHERE id = $1
        RETURNING id, user_id, total, status, created_at, updated_at
        "#,
        order_id
    )
    .fetch_one(&mut *tx)
    .await?;

    // Step 5: Audit log với diff status
    audit::log_action(
        &mut tx,
        "orders",
        order_id,
        "cancel",
        actor_user_id,
        Some(serde_json::json!({
            "from_status": current.status,
            "to_status": "cancelled",
        })),
        request_id,
    )
    .await?;

    tx.commit().await?;
    Ok(order)
}

Mở rộng OrderError enum (B54 continued) thêm variant InvalidTransition:

// File: crates/shop-db/src/orders.rs

#[derive(Debug, thiserror::Error)]
pub enum OrderError {
    #[error(transparent)]
    Sqlx(#[from] sqlx::Error),

    #[error("order {0} not found")]
    NotFound(i64),

    #[error("invalid state transition from {from} to {to}")]
    InvalidTransition { from: String, to: String },

    #[error("product {0} not found")]
    ProductNotFound(i64),

    #[error("insufficient stock for product {product_id}: requested {requested}, available {available}")]
    InsufficientStock {
        product_id: i64,
        requested: i32,
        available: i32,
    },
}

Handler HTTP wire endpoint POST /api/v1/orders/{id}/cancel — action verb pattern B61 continued, action thay vì soft delete trực tiếp:

// File: crates/shop-api/src/routes/orders.rs

use axum::{
    extract::{Path, State},
    Json,
};
use shop_db::orders;
use crate::{state::AppState, error::AppError};

pub async fn cancel_order(
    State(state): State<AppState>,
    Path(order_id): Path<i64>,
) -> Result<Json<OrderResponseDto>, AppError> {
    let order = orders::cancel_order(&state.db, order_id, None, None).await?;
    Ok(Json(OrderResponseDto::from(order)))
}

FOR UPDATE row lock MANDATORY ở step 1 vì 2 admin có thể cùng gọi cancel với cùng order_id đồng thời. Không có lock: cả 2 đọc status = 'paid', cả 2 validate pass, cả 2 restore stock (stock bị cộng 2 lần dư!), cả 2 update status (vẫn idempotent), nhưng audit log ghi 2 lần. Có FOR UPDATE: transaction thứ 2 block tại SELECT đến khi transaction thứ 1 COMMIT, transaction thứ 2 đọc thấy status = 'cancelled' → InvalidTransition reject. Pattern lock vĩnh viễn cho mọi state transition Shop API.

B63 đã preview cycle detection cho move category nhưng chưa implement đầy đủ. Vấn đề cụ thể: cây categories adjacency + materialized path, nếu admin move category A vào subtree của chính nó → cycle A → B → C → A, materialized path infinite loop khi update descendant.

Cycle detection MANDATORY qua WITH RECURSIVE EXISTS subquery — duyệt subtree của category đang move, kiểm tra new_parent_id có nằm trong subtree không:

// File: crates/shop-db/src/categories.rs

use sqlx::PgPool;
use crate::audit;

pub async fn update_parent(
    pool: &PgPool,
    category_id: i64,
    new_parent_id: Option<i64>,
    actor_user_id: Option<i64>,
    request_id: Option<&str>,
) -> Result<CategoryRow, CategoryError> {
    let mut tx = pool.begin().await?;

    // Step 1: Get current category (active only)
    let current = sqlx::query!(
        r#"SELECT id, path, depth FROM categories
           WHERE id = $1 AND deleted_at IS NULL"#,
        category_id
    )
    .fetch_optional(&mut *tx)
    .await?
    .ok_or(CategoryError::NotFound(category_id))?;

    // Step 2: Cycle detection — new_parent KHÔNG được là descendant của current
    if let Some(npid) = new_parent_id {
        let is_descendant: Option<bool> = sqlx::query_scalar!(
            r#"
            WITH RECURSIVE subtree AS (
                SELECT id FROM categories WHERE id = $1
                UNION ALL
                SELECT c.id FROM categories c
                INNER JOIN subtree s ON c.parent_id = s.id
                WHERE c.deleted_at IS NULL
            )
            SELECT EXISTS(SELECT 1 FROM subtree WHERE id = $2)
            "#,
            category_id,
            npid
        )
        .fetch_one(&mut *tx)
        .await?;

        if is_descendant.unwrap_or(false) {
            tx.rollback().await?;
            return Err(CategoryError::CycleDetected {
                category_id,
                new_parent_id: npid,
            });
        }
    }

    // Step 3: Get new parent path + depth (hoặc root nếu None)
    let (new_path_prefix, new_depth) = if let Some(npid) = new_parent_id {
        let p = sqlx::query!(
            r#"SELECT path, depth FROM categories
               WHERE id = $1 AND deleted_at IS NULL"#,
            npid
        )
        .fetch_optional(&mut *tx)
        .await?
        .ok_or(CategoryError::ParentNotFound(npid))?;
        (format!("{}.{}", p.path, category_id), p.depth + 1)
    } else {
        (category_id.to_string(), 0)
    };

    let old_path = current.path.clone();

    // Step 4a: Update current node
    sqlx::query!(
        "UPDATE categories SET parent_id = $1, path = $2, depth = $3 WHERE id = $4",
        new_parent_id,
        new_path_prefix,
        new_depth,
        category_id,
    )
    .execute(&mut *tx)
    .await?;

    // Step 4b: Update descendants — replace old_path prefix bằng new_path_prefix
    sqlx::query!(
        r#"
        UPDATE categories
        SET path = $1 || SUBSTRING(path FROM LENGTH($2) + 1),
            depth = depth + ($3 - $4)
        WHERE path LIKE $2 || '.%' AND deleted_at IS NULL
        "#,
        new_path_prefix,
        old_path,
        new_depth,
        current.depth,
    )
    .execute(&mut *tx)
    .await?;

    // Step 5: Audit log
    audit::log_action(
        &mut tx,
        "categories",
        category_id,
        "update_parent",
        actor_user_id,
        Some(serde_json::json!({
            "new_parent_id": new_parent_id,
            "old_path": old_path,
            "new_path": new_path_prefix,
        })),
        request_id,
    )
    .await?;

    let updated = sqlx::query_as!(
        CategoryRow,
        r#"SELECT id, parent_id, name, slug, path, depth, display_order,
                  deleted_at, created_at, updated_at
           FROM categories WHERE id = $1"#,
        category_id
    )
    .fetch_one(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(updated)
}

CategoryError enum mới — định nghĩa cuối cùng (B63 đã preview, B65 hoàn thành):

// File: crates/shop-db/src/categories.rs

#[derive(Debug, thiserror::Error)]
pub enum CategoryError {
    #[error(transparent)]
    Sqlx(#[from] sqlx::Error),

    #[error("category {0} not found")]
    NotFound(i64),

    #[error("parent category {0} not found")]
    ParentNotFound(i64),

    #[error("cycle detected: category {category_id} cannot have parent {new_parent_id} (descendant)")]
    CycleDetected { category_id: i64, new_parent_id: i64 },
}

Mapping CategoryError sang AppError trong shop-common::error:

// File: crates/shop-common/src/error.rs

use shop_db::categories::CategoryError;

impl From<CategoryError> for AppError {
    fn from(err: CategoryError) -> Self {
        match err {
            CategoryError::NotFound(id) => AppError::NotFound {
                resource: "category".into(),
                id: id.to_string(),
            },
            CategoryError::ParentNotFound(id) => AppError::ValidationFailed {
                field: "parent_id".into(),
                message: format!("parent category {id} not found"),
            },
            CategoryError::CycleDetected { category_id, new_parent_id } => {
                AppError::ValidationFailed {
                    field: "parent_id".into(),
                    message: format!(
                        "moving category {category_id} under {new_parent_id} would create a cycle"
                    ),
                }
            }
            CategoryError::Sqlx(e) => AppError::from(e),
        }
    }
}

Endpoint wire PATCH /api/v1/admin/categories/{slug}/parent với DTO chỉ chứa 1 field:

// File: crates/shop-common/src/dto/category.rs

use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct UpdateParentDto {
    pub parent_id: Option<i64>,  // None = move thành root
}

WITH RECURSIVE EXISTS bound terminate vì subtree finite (tree adjacency + cycle detection chính câu query này), Postgres planner thực thi recursive CTE đến khi không còn row mới thêm. Performance: subtree N node → query O(N) row scan, với cây Shop API ~3-4 depth × 50 node/level ~200 node max → <5ms thực tế. Nếu cây sâu hơn 10+ depth, cần index bổ sung CREATE INDEX categories_parent_id_idx ON categories(parent_id) WHERE deleted_at IS NULL.

Use case thực tế: admin UI "Trash" hiển thị product đã soft-deleted, cho phép bulk select 5-20 item rồi click "Restore". Endpoint POST /api/v1/admin/products/restore-bulk — namespace /admin/ sẽ guard auth elevated ở B112.

DTO với cap 100 slug/request bằng validator::Validate:

// File: crates/shop-common/src/dto/product.rs

use serde::{Deserialize, Serialize};
use validator::Validate;

#[derive(Debug, Deserialize, Validate)]
pub struct BulkRestoreDto {
    #[validate(length(min = 1, max = 100, message = "1-100 slug mỗi request"))]
    pub slugs: Vec<String>,
}

#[derive(Debug, Serialize)]
pub struct BulkRestoreResponse {
    pub requested: u32,
    pub restored_count: u32,
    pub restored_slugs: Vec<String>,
}

Function bulk restore trong shop-db dùng = ANY($1) + RETURNING slug 1 statement:

// File: crates/shop-db/src/products.rs

pub async fn bulk_restore_products(
    pool: &PgPool,
    slugs: &[String],
    actor_user_id: Option<i64>,
    request_id: Option<&str>,
) -> Result<Vec<String>, sqlx::Error> {
    let mut tx = pool.begin().await?;

    let restored: Vec<String> = sqlx::query_scalar!(
        r#"
        UPDATE products SET deleted_at = NULL
        WHERE slug = ANY($1) AND deleted_at IS NOT NULL
        RETURNING slug
        "#,
        slugs
    )
    .fetch_all(&mut *tx)
    .await?;

    // Audit log bulk action — row_id = 0 đánh dấu bulk
    audit::log_action(
        &mut tx,
        "products",
        0,
        "bulk_restore",
        actor_user_id,
        Some(serde_json::json!({
            "requested": slugs,
            "restored": restored,
            "count": restored.len(),
        })),
        request_id,
    )
    .await?;

    tx.commit().await?;
    Ok(restored)
}

Handler HTTP:

// File: crates/shop-api/src/routes/products.rs

use crate::extractors::ValidatedJson;
use axum::{extract::State, Extension, Json};
use shop_common::dto::{BulkRestoreDto, BulkRestoreResponse};

pub async fn bulk_restore_products(
    State(state): State<AppState>,
    Extension(req_id): Extension<RequestId>,
    ValidatedJson(dto): ValidatedJson<BulkRestoreDto>,
) -> Result<Json<BulkRestoreResponse>, AppError> {
    let restored = shop_db::products::bulk_restore_products(
        &state.db,
        &dto.slugs,
        None,
        Some(&req_id.0),
    )
    .await?;

    Ok(Json(BulkRestoreResponse {
        requested: dto.slugs.len() as u32,
        restored_count: restored.len() as u32,
        restored_slugs: restored,
    }))
}

Test bằng curl:

curl -X POST http://localhost:3000/api/v1/admin/products/restore-bulk \
  -H 'Content-Type: application/json' \
  -d '{
    "slugs": ["iphone-15-pro", "macbook-air-m3", "ipad-pro"]
  }'

# Response:
# {
#   "requested": 3,
#   "restored_count": 2,
#   "restored_slugs": ["iphone-15-pro", "macbook-air-m3"]
# }
# — slug "ipad-pro" không restore vì không soft-deleted (đã active)

Audit log với row_id = 0 là convention đánh dấu bulk action — không phải 1 product cụ thể mà là tập hợp. Khi filter audit log ?row_id=0 AND action=bulk_restore, admin xem được lịch sử mọi bulk operation. Cap 100 slug/request lock vì payload + transaction time scale linear theo size; 100 đủ cho UI bulk select page, cao hơn nên chia nhiều request.

Use case: admin xem audit trail filter theo table (mọi mutation products), action (cancel orders gần đây), actor (action của 1 admin cụ thể), hoặc request_id (trace 1 request xuyên 5 mutation cùng correlation id).

DTO query với pagination + 4 filter optional:

// File: crates/shop-common/src/dto/audit.rs

use serde::{Deserialize, Serialize};
use validator::Validate;

#[derive(Debug, Deserialize, Validate)]
pub struct AuditLogQuery {
    #[serde(default)]
    pub table_name: Option<String>,

    #[serde(default)]
    pub action: Option<String>,

    #[serde(default)]
    pub actor_user_id: Option<i64>,

    #[serde(default)]
    pub request_id: Option<String>,

    #[serde(default = "default_page")]
    pub page: u32,

    #[serde(default = "default_per_page")]
    #[validate(range(min = 1, max = 100))]
    pub per_page: u32,
}

fn default_page() -> u32 { 1 }
fn default_per_page() -> u32 { 20 }

#[derive(Debug, Serialize)]
pub struct AuditLogResponseDto {
    pub id: i64,
    pub table_name: String,
    pub row_id: i64,
    pub action: String,
    pub actor_user_id: Option<i64>,
    pub changes: Option<serde_json::Value>,
    pub request_id: Option<String>,
    pub created_at: chrono::DateTime<chrono::Utc>,
}

Function shop-db dùng QueryBuilder dynamic SQL (B59 pattern continued) — conditional WHERE clauses:

// File: crates/shop-db/src/audit.rs

use sqlx::{PgPool, Postgres, QueryBuilder};

#[derive(Debug, sqlx::FromRow)]
pub struct AuditLogRow {
    pub id: i64,
    pub table_name: String,
    pub row_id: i64,
    pub action: String,
    pub actor_user_id: Option<i64>,
    pub changes: Option<serde_json::Value>,
    pub request_id: Option<String>,
    pub created_at: chrono::DateTime<chrono::Utc>,
}

pub async fn list_audit_logs(
    pool: &PgPool,
    filter: &AuditLogQuery,
) -> Result<(Vec<AuditLogRow>, u64), sqlx::Error> {
    let mut qb: QueryBuilder<Postgres> = QueryBuilder::new(
        "SELECT id, table_name, row_id, action, actor_user_id, \
         changes, request_id, created_at FROM audit_logs WHERE 1=1"
    );

    if let Some(table) = &filter.table_name {
        qb.push(" AND table_name = ").push_bind(table.clone());
    }
    if let Some(action) = &filter.action {
        qb.push(" AND action = ").push_bind(action.clone());
    }
    if let Some(actor) = filter.actor_user_id {
        qb.push(" AND actor_user_id = ").push_bind(actor);
    }
    if let Some(rid) = &filter.request_id {
        qb.push(" AND request_id = ").push_bind(rid.clone());
    }

    qb.push(" ORDER BY created_at DESC");
    qb.push(" LIMIT ").push_bind(filter.per_page as i64);
    qb.push(" OFFSET ").push_bind(((filter.page - 1) * filter.per_page) as i64);

    let rows = qb.build_query_as::<AuditLogRow>().fetch_all(pool).await?;

    // Count query song song (giản lược — production dùng cùng filter builder)
    let total: i64 = sqlx::query_scalar!("SELECT COUNT(*) FROM audit_logs")
        .fetch_one(pool)
        .await?
        .unwrap_or(0);

    Ok((rows, total as u64))
}

Handler HTTP wire route trong module mới routes/admin.rs:

// File: crates/shop-api/src/routes/admin.rs

use axum::{
    extract::{Query, State},
    routing::get,
    Json, Router,
};
use shop_common::dto::{AuditLogQuery, AuditLogResponseDto};
use crate::{state::AppState, error::AppError};

pub async fn list_audit_logs(
    State(state): State<AppState>,
    Query(filter): Query<AuditLogQuery>,
) -> Result<Json<serde_json::Value>, AppError> {
    let (rows, total) = shop_db::audit::list_audit_logs(&state.db, &filter).await?;

    let items: Vec<AuditLogResponseDto> = rows.into_iter()
        .map(AuditLogResponseDto::from)
        .collect();

    Ok(Json(serde_json::json!({
        "items": items,
        "total": total,
        "page": filter.page,
        "per_page": filter.per_page,
    })))
}

pub fn routes() -> Router<AppState> {
    Router::new()
        .route("/admin/audit-logs", get(list_audit_logs))
}

Test bằng curl 3 case:

# Filter theo table
curl 'http://localhost:3000/api/v1/admin/audit-logs?table_name=products&per_page=10'

# Filter theo request_id (trace 1 request xuyên nhiều mutation)
curl 'http://localhost:3000/api/v1/admin/audit-logs?request_id=550e8400-e29b-41d4-a716-446655440000'

# Filter theo actor + action (admin nào đã cancel order nào)
curl 'http://localhost:3000/api/v1/admin/audit-logs?actor_user_id=1&action=cancel'

Pattern QueryBuilder + push_bind bảo vệ SQL injection vì binding vẫn qua prepared statement underlying. KHÔNG bao giờ dùng format!() chèn user input vào câu query.

Audit log mỗi mutation → bảng audit_logs growth nhanh nhất trong toàn DB Shop API. Phép tính thực tế cho shop quy mô vừa:

10K order/day × 5 mutation/order (create + paid + shipped + delivered + items)
= 50K row audit/day
× 365 day = 18.25M row/year
× ~500 byte/row (id + table_name + row_id + action + actor + JSONB changes + request_id + created_at)
≈ 9 GB raw data + ~3 GB index = 12 GB/year

4 mitigation strategy theo độ phức tạp tăng dần:

• Partitioning theo tháng qua Postgres PARTITION BY RANGE (created_at) — bảng cha audit_logs + bảng con audit_logs_2026_06, audit_logs_2026_07 tạo tự động qua pg_partman extension hoặc cron job. Pros: query gần đây chỉ scan 1 partition mỏng (~750MB/tháng), DROP partition cũ tức thì thay DELETE chậm. Cons: planner cần partition pruning đúng (PG 11+ tốt), complex hơn.
• Archive older 90 ngày → cold storage S3 Glacier hoặc cloud equivalent → vacuum DB sau archive. Pros: chi phí storage giảm 10× (S3 Glacier ~$0.004/GB/tháng so với managed Postgres ~$0.10/GB/tháng), DB hot subset nhỏ. Cons: query log cũ chậm (phải restore từ S3), workflow phức tạp.
• Compress JSONB — Postgres TOAST tự động compress payload > 2KB. Pros: zero config. Cons: row nhỏ < 2KB không compress, không giúp với audit Shop API (JSONB diff thường nhỏ).
• Sample rate — chỉ log mutation quan trọng (CRUD products/orders/users, payment events), skip read endpoint. Pros: giảm row 80-90%. Cons: mất visibility cho fraud detection, compliance audit thiếu.

Lock decision Shop API 3 phase theo growth thực tế:

• Phase 1 (B65 → G17): single table không partition, retention forever. Khi DB < 50GB tổng, complexity thêm partition không worth. Index audit_created_at_idx + audit_request_id_idx đủ cho query < 100ms p95.
• Phase 2 (G18 deploy production): monthly partition + 90-day hot retention. Khi audit_logs > 10GB hoặc > 100M row, partition giảm query latency + cho phép DROP partition cũ tức thời.
• Phase 3 (G18+ scale): archive cold storage S3 Glacier monthly job, giữ 90 ngày hot trong DB + 7 năm archive cho compliance kế toán Việt Nam.

GDPR Article 17 right-to-erasure xung đột audit trail — preview G19: khi user request xóa data, audit log có actor_user_id hoặc changes.user_email phải anonymize (replace user_id bằng 0, redact PII trong JSONB). Pattern: retention exception cho audit log dưới điều khoản "legal obligation" (Article 17(3)(b)) khi liên quan đơn hàng/thanh toán, nhưng PII trong free-text field vẫn phải erase.

• 3 model soft delete: timestamp deleted_at cho products + categories + users, state status enum cho orders cancel transition, combined (state + deleted_at) cho users với GDPR right-to-erasure.
• users table mới với 4-state lifecycle (active/suspended/deactivated) + deleted_at GDPR Article 17.
• Migration 9 create_users + ALTER FK orders.user_id → users(id) ON DELETE RESTRICT hoàn thành preview B54.
• cancel_order state machine 5 step: FOR UPDATE row lock → validate transition match arm → restore stock UPDATE products FROM order_items → UPDATE orders status → audit log diff.
• State transition table orders: pending→paid→shipped→delivered hợp lệ; pending|paid → cancelled OK; shipped|delivered → cancelled REJECT (dùng return endpoint B68).
• update_parent cycle detection qua WITH RECURSIVE EXISTS subquery — defend pattern A → B → A loop.
• Update descendant path qua UPDATE ... SET path = $new_prefix || SUBSTRING(path FROM LENGTH($old_path) + 1) + depth recompute cho mọi node subtree (materialized path B63 lock continued).
• CategoryError enum: NotFound + ParentNotFound + CycleDetected + Sqlx 4 variant + impl From<CategoryError> for AppError map 404/422.
• Bulk restore endpoint POST /admin/products/restore-bulk với BulkRestoreDto validate min=1 max=100 slug/request, RETURNING slug, audit row_id 0 bulk marker.
• Audit log filter endpoint GET /admin/audit-logs với QueryBuilder dynamic SQL + 4 filter (table_name/action/actor_user_id/request_id) + pagination.
• Storage cost trade-off roadmap: phase 1 single table → phase 2 monthly partition G18 → phase 3 cold archive S3 G18+.
• File path lock: extend crates/shop-db/src/orders.rs (cancel_order), categories.rs (update_parent + CategoryError), products.rs (bulk_restore_products), audit.rs (list_audit_logs + AuditLogRow); NEW users.rs skeleton; migration 20260615180000_create_users.sql; NEW crates/shop-api/src/routes/admin.rs.

Tự trả lời, đáp án ở cuối:

1. 3 model soft delete khác nhau ra sao (timestamp/state/combined)? Tại sao orders chọn state thay deleted_at như products?
2. State machine cancel_order 5 step — bước nào MANDATORY restore stock và tại sao đặt trước UPDATE status? Pattern FOR UPDATE chống race condition cụ thể nào?
3. Cycle detection update parent — WITH RECURSIVE EXISTS pattern hoạt động ra sao trong câu query? Cho ví dụ cycle scenario A → B → C → A và kết quả query.
4. Bulk restore endpoint cap 100 slug/request — lý do? Trade-off với UI admin cần bulk select 1000 item?
5. Audit log storage cost — 3 mitigation strategies (partition/archive/sample) là gì? Trade-off mỗi cái với requirement compliance kế toán Việt Nam giữ 10 năm?

Bài 66: POST /orders Endpoint Hoàn Chỉnh — Idempotency + Retry — implement POST /api/v1/orders endpoint dùng create_order_atomic B54, Idempotency-Key header (Stripe-style) lưu Redis 24h tránh double-charge, retry strategy cho SerializationFailure (B55 with_retry), CreateOrderDto validation, response Created<OrderResponseDto> với Location header.