[INTERNAL] Kế hoạch Phân việc, Break Task & Ước lượng Effort cho Đội Dev Spores ​

• Ngày lập: 10/11/2026
• Phạm vi lưu hành: NỘI BỘ ĐỘI DEV SPORES (INTERNAL DEV ONLY)
• Nguồn WBS gốc: Google Sheets WBS (gid=1244770703) — Lọc theo cột D (Người thực hiện = Spore)
• Target Codebase: Gotrace-portal (commit 93d9a64e03883e55050c9a41d66da41a863c368b — Monorepo 4 Apps: apps/backend, apps/frontend, apps/zalo-be, apps/integration-gateway)

📂 Kho Tài liệu Đặc tả (SRS / Technical Specs) Đính kèm trên Cloud Nội bộ ​

Toàn bộ 10 file tài liệu SRS, Mapping chuẩn quốc tế và Báo cáo Audit từ repo liên quan trực tiếp tới 12 task của đội Dev Spores đã được trích xuất và đẩy lên Cloud nội bộ dưới đây để anh em dev mở tra cứu ngay khi code:

1. Tóm tắt Đánh giá Hiện trạng & Khối lượng Công việc ​

Qua rà soát toàn bộ bảng phân việc WBS và đối chiếu trực tiếp tới từng module trong codebase Gotrace-portal, đội Spore phụ trách 12 hạng mục công việc (1 hạng mục thuộc Dự án HanoiTrace và 11 hạng mục thuộc Dự án GoTrace – Hoàn thiện chức năng B2B).

1.1. Ba điểm bất cập trên file Google Sheets WBS cần lưu ý ​

1. Thiếu mốc thời gian ở cả 12 dòng của Spore: Cột Ngày bắt đầu (Cột G) và Hạn hoàn thành (Cột H) của cả 12 task gán cho Spore đều đang để trống, trong khi các task cha (Cấp 2) và các sub-task QA/QC test (của Cấn Thị Việt Hà) đã có hạn hoàn thành từ 20/11/2026 đến 17/12/2026.
2. Xung đột mốc thời gian (Timeline Conflict):
   • WBS 2.41 / 2.41.1 (Open API HanoiTrace): Hạn task cha ghi 05/11/2026 (đã quá hạn so với ngày báo cáo), ghi chú tại 2.41.1 là "có thể làm được luôn" → Đưa lên Ưu tiên số 1 (Wave 1).
   • WBS 2.13 (Xuất báo cáo dashboard): Sub-task 2.13.3 (QA test) đang ghi hạn 05/11/2026 – 07/11/2026, sớm hơn cả hạn hoàn thành tài liệu BA 2.13.1 của Lê Trung Hiếu (11/11/2026) và hạn task cha 2.13 (03/12/2026).
3. Lỗi công thức trên Sheet "Tổng hợp" (gid=12449873): Toàn bộ các ô thống kê trên sheet "Tổng hợp" đang báo #VALUE! và danh sách người thực hiện chưa có tên Spore.

2. Bảng Đối chiếu 12 Task của Spore với Codebase & Ước lượng Effort ​

3. Lộ trình Thực thi 4 Waves & Kiến trúc Module Mới ​

3.1. Sơ đồ Lộ trình Thực thi (4 Waves theo Critical Path) ​

flowchart LR
    subgraph W1["Wave 1 (11/11 – 16/11)
Ưu tiên Khẩn & Bảo mật Cốt lõi"]
        T241["2.41.1: Open API HanoiTrace
& Tài liệu Tích hợp (1.5d)"]
        T236["2.36.1: Vá 10 Lỗ hổng
CRITICAL/HIGH (1.0d)"]
    end

    subgraph W2["Wave 2 (17/11 – 23/11)
Gói Cước, Thanh toán & Pentest"]
        T233["2.33.1: Hoàn thiện
Quản lý Gói dịch vụ (0.5d)"]
        T234["2.34.1: Thanh toán Online
& Hóa đơn Điện tử (2.0d)"]
        T237["2.37.1: Vá MEDIUM/INFRA
& Kiểm thử Xâm nhập (1.5d)"]
        T235["2.35.1: Tách Lớp Entitlement
& Usage Metering (1.5d)"]
    end

    subgraph W3["Wave 3 (24/11 – 02/12)
CMS, Báo cáo, PDF QR & EPCIS/DPP"]
        T16["1.6: CMS Quản trị & Hiển thị
Bài viết HanoiTrace (1.5d)"]
        T213["2.13.2: Xuất Báo cáo
Dashboard Tổng (1.0d)"]
        T229["2.29.1: Xuất PDF DN/SP/Lô
có QR Xác thực VC (1.5d)"]
        T230["2.30.1: Xuất JSON/EPCIS 2.0,
Linkset & DPP theo GTIN (1.5d)"]
    end

    subgraph W4["Wave 4 (03/12 – 10/12)
Hồ sơ số DN/Lô & Nhật ký Điện tử v1"]
        T2281["2.28.1: Hồ sơ số
Doanh nghiệp (1.0d)"]
        T2282["2.28.2: Hồ sơ số Lô hàng
& Nhật ký Điện tử v1 (1.5d)"]
    end

    W1 --> W2 --> W3 --> W4

3.2. Sơ đồ Vị trí Các Module Mới của Spore trong Monorepo Gotrace-portal ​

flowchart TB
    subgraph FE["apps/frontend (Next.js 16 — Multi-Brand Portal)"]
        FE_CMS["Admin CMS & Public Blog/News
(WBS 1.6)"]
        FE_BILL["Pricing, Checkout & Entitlement UI
(WBS 2.33.1, 2.34.1, 2.35.1)"]
        FE_DOS["Digital Enterprise & Batch Dossier UI
(WBS 2.28.1, 2.28.2)"]
    end

    subgraph BE["apps/backend (NestJS 11 — Core API :3001)"]
        SEC["Security Hardening & Tenant Guards
(WBS 2.36.1, 2.37.1)"]
        OPEN["OpenApiHanoitraceModule
(/api/v1/open/hanoitrace/* — WBS 2.41.1)"]
        ENT["Entitlements & BillingPaymentsModule
(WBS 2.33.1, 2.34.1, 2.35.1)"]
        EXP["VerifiablePdf & MachineReadableExport
(EPCIS 2.0, Linkset, DPP — WBS 2.29.1, 2.30.1)"]
        DOS["DigitalDossiers & DashboardTongExport
(WBS 2.13.2, 2.28.1, 2.28.2)"]
        CMS["CmsModule (Multi-Brand Articles)
(WBS 1.6)"]
    end

    subgraph IGW["apps/integration-gateway (:3003 / :3013)"]
        HN_CONN["connectors/hanoitrace
(WBS 2.41.1)"]
    end

    FE_CMS --> CMS
    FE_BILL --> ENT
    FE_DOS --> DOS
    DOS --> EXP
    OPEN --> HN_CONN
    SEC -.->|Bảo vệ toàn bộ Controllers| BE

4. Break Task Chi tiết Từng Workstream (Hướng dẫn Code cho Dev Spores) ​

Workstream 1: Bảo mật & Kiểm thử Xâm nhập (WBS 2.36.1 & WBS 2.37.1) ​

• Tài liệu tham chiếu bắt buộc: Security Audit Report (SEC-01..SEC-16 & INFRA-01..03)

Task 1A — WBS 2.36.1: Vá 5 lỗ hổng CRITICAL & 5 lỗ hổng HIGH (Hạn: 16/11/2026) ​

• Files cần sửa trong Gotrace-portal:
  • apps/backend/src/modules/registrations/registrations.controller.ts:34-100 & registrations.service.ts:542-690 (SEC-01): Gắn @UseGuards(JwtAuthGuard, AdminGuard) cho các route duyệt đơn; chặn approve() tự động gán owner mới vào doanh nghiệp đã có thành viên (memberCount > 0); bỏ generated_password khỏi HTTP response.
  • apps/backend/src/modules/users/users.controller.ts:109-200, users.service.ts:343-1140, permission.guard.ts:35 (SEC-02): Viết helper assertCanManageUser(actor, targetId) kiểm tra company_id và unit_path; chặn ROLE.AGENT tự nâng quyền lên ROLE.ADMIN (role: 1); bật global omit: { password: true }.
  • apps/backend/src/modules/companies/companies.controller.ts:28-95 & companies.service.ts:488-943 (SEC-03): Kiểm tra user.company_id trên GET /api/v1/companies/:id và /dashboard; omit token và webhook_id; chặn ROLE.GOVERNMENT và ROLE.AGENT ghi đè các trường nhạy cảm trong PUT /api/v1/companies/:id.
  • 10 Modules bị Cross-Tenant BOLA/IDOR & 4 Modules bị BFLA (SEC-04):
    • Bổ sung companyHelper.getCompanyId(user) tại batches, stamps (findOne, getHistory, suspendStamp, reactivateStamp, recallStamp, markDefective, reprintStamp), qr-codes, raw-material-zones, company-certifications, input-sources, warehouses, shipment-orders, vehicles, drivers.
    • Thay AdminOrActiveCompanyGuard bằng PermissionsGuard + @CheckPermissions tại personnel.controller.ts, lookups.controller.ts, consultation-request.controller.ts.
  • apps/backend/prisma/seed.ts:29-53 & deploy-prod.sh:709-718 (SEC-05): Gỡ lệnh chạy seed khỏi deploy-prod.sh; đổi update: { password: hashedPassword } của admin@gmail.com thành update: {}; xóa 9 bản dump .sql khỏi repo và enforce must_change_password.
  • apps/frontend/utils/public-trace-format.ts:19-22 & components/common/markdown/markdown.tsx:5-14 (SEC-06): Sanitize HTML bằng DOMPurify.sanitize() và thêm rehypeSanitize.
  • apps/zalo-be/src/main.ts:36 & apps/zalo-be/src/modules/auth/auth.service.ts (SEC-07 & SEC-16): Sửa CORS wildcard origin: true; đăng ký ThrottlerGuard; đồng bộ enforceServiceGate và kiểm tra token_version sang zalo-be.
  • apps/backend/src/main.ts:45 & anti-crawl.middleware.ts (SEC-08): Đổi trust proxy: true sang TRUSTED_PROXIES, đổi includes(HONEYPOT_ROUTE) thành ===, gỡ NEXT_PUBLIC_ANTI_CRAWL_SECRET.

Task 1B — WBS 2.37.1: Vá 6 lỗ hổng MEDIUM, Nâng cấp Dependencies & Pentest (Hạn: 21/11/2026) ​

• Files cần sửa:
  • apps/backend/src/modules/auth/jwt.strategy.ts:98-192 (SEC-09): Filter (!ra.valid_from || ra.valid_from <= now) && (!ra.valid_to || ra.valid_to >= now).
  • apps/backend/src/common/services/minio-storage.service.ts:123 & s3-storage.service.ts:128 (SEC-10): Bỏ toán tử short-circuit || để luôn gọi this.fileValidation.validateMimeType(buffer, options?.contentType).
  • apps/backend/src/modules/auth/auth.service.ts:356 (SEC-11): Tăng token_version: { increment: 1 } khi changePassword(); lưu jti Refresh Token trên Redis để revoke khi logout.
  • SEC-12..SEC-15: Bảo vệ /api/v1/webhook, thêm ALLOWED_SORT_COLUMNS chống orderBy injection, giới hạn fileSize: 5MB cho upload đăng ký.
  • package.json (INFRA-01) & 4 Dockerfile (INFRA-02): Thêm resolutions xử lý 92 CVEs trong yarn.lock và thêm USER node vào runner stage của 4 Dockerfiles.
  • Viết E2E test apps/backend/test/security-bola-bfla.e2e-spec.ts và xuất biên bản Pentest bàn giao cho QC Việt Hà (2.37.2).

Workstream 2: Open API HanoiTrace & Tài liệu Hướng dẫn Tích hợp (WBS 2.41.1) ​

• Tài liệu tham chiếu: Integration Catalog & GS1 + TT 02/2024 Mapping
• Hạn đề xuất: 13/11/2026 (Làm ngay trong Wave 1)
• Files cần tạo/sửa:
  • Create: apps/backend/src/modules/open-api-hanoitrace/open-api-hanoitrace.module.ts
  • Create: apps/backend/src/modules/open-api-hanoitrace/open-api-hanoitrace.controller.ts
  • Create: apps/backend/src/modules/open-api-hanoitrace/open-api-hanoitrace.service.ts
  • Create: apps/backend/src/modules/open-api-hanoitrace/guards/open-api-hmac.guard.ts
  • Create: apps/integration-gateway/src/connectors/hanoitrace/index.ts
  • Modify: apps/integration-gateway/src/connectors/registry.ts:1-15
• Chi tiết triển khai:
  1. OpenApiHmacGuard: Kiểm tra headers X-HanoiTrace-Api-Key, X-HanoiTrace-Timestamp (±300s), X-HanoiTrace-Signature (HMAC-SHA256(timestamp + "." + rawBody) dùng crypto.timingSafeEqual) và Idempotency-Key (Redis TTL 24h). Tự động pin company_id theo API Key.
  2. 4 Nhóm Endpoints Open API (@ApiTags("HanoiTrace Open API v1")):
     • POST /api/v1/open/hanoitrace/products (Đồng bộ sản phẩm GTIN-14, phân loại GS1 GPC / VSIC 2025).
     • POST /api/v1/open/hanoitrace/batches (Tạo/cập nhật lô sản xuất & liên kết nguyên liệu đầu vào PlanInputLink).
     • POST /api/v1/open/hanoitrace/events (Ghi nhận sự kiện CTE/KDE và tự động enqueue phát hành W3C VC vào vc_outbox).
     • GET /api/v1/open/hanoitrace/trace/:code (Tra cứu chuỗi truy xuất nguồn gốc chuẩn Thông tư 02/2024/TT-BKHCN).
  3. Outbound Connector hanoitrace: Đăng ký vào buildConnectorRegistry() trong apps/integration-gateway để đẩy sự kiện liên thông.
  4. Bộ Tài liệu Hướng dẫn Tích hợp: Xuất file OpenAPI 3.1 YAML + tài liệu Markdown/HTML hướng dẫn xác thực HMAC, bảng mã lỗi và Postman Collection mẫu.

Workstream 3: Quản lý Gói Dịch vụ, Entitlement Metering & Thanh toán/HĐĐT (WBS 2.33.1, 2.35.1, 2.34.1) ​

• Tài liệu tham chiếu: SRS TXNG-F45 (Cấu hình Gói Dịch vụ) & SRS TXNG-F46 (Kích hoạt & Vòng đời Gói Dịch vụ)

sequenceDiagram
    autonumber
    participant DN as Enterprise Admin
    participant FE as apps/frontend
    participant BE as BillingPayments & Subscriptions (:3001)
    participant PG as PostgreSQL (Entitlement & Meter)
    participant Pay as Payment Gateway (VietQR/PayOS/VNPay)
    participant EInv as E-Invoice (MISA/Viettel)

    DN->>FE: Chọn gói cước / Mua thêm Add-on Quota
    FE->>BE: POST /api/v1/billing/checkout
    BE->>PG: Tạo BillingInvoice (PENDING)
    BE-->>FE: Trả mã VietQR động / Payment URL
    DN->>Pay: Quét QR chuyển khoản thanh toán
    Pay->>BE: POST /api/v1/billing/webhooks/:provider (HMAC Signed)
    rect rgb(235, 248, 255)
        Note over BE,PG: Atomic Transaction + Idempotency Check
        BE->>PG: 1. Mark BillingInvoice = PAID
        BE->>PG: 2. Activate/Renew CompanySubscription (2.33.1)
        BE->>PG: 3. Provision/Update CompanyEntitlement & UsageMeter (2.35.1)
    end
    BE->>EInv: Async BullMQ Job: Phát hành Hóa đơn điện tử (2.34.1)
    EInv-->>BE: Trả mã tra cứu HĐĐT & link PDF

Task 3A — WBS 2.33.1: Hoàn thiện Quản lý Gói Dịch vụ (Đã có ~80%, Hạn: 17/11/2026) ​

• Tận dụng code sẵn có: apps/backend/src/modules/service-plans/ và apps/backend/src/modules/company-subscriptions/.
• Phần code thêm: Bổ sung method changePlan(subscriptionId, dto, actorId) trong CompanySubscriptionsService xử lý nâng/hạ bậc gói giữa kỳ và cập nhật UI bảng giá/gói dịch vụ trên apps/frontend.

Task 3B — WBS 2.35.1: Tách Lớp Entitlement khỏi Bậc Gói & Đo Định mức Real-time (Hạn: 23/11/2026) ​

• Files cần tạo/sửa:
  • Modify: apps/backend/prisma/schema.prisma (thêm models CompanyEntitlement và CompanyUsageMeter).
  • Create: apps/backend/src/modules/entitlements/ (entitlements.module.ts, entitlements.service.ts, entitlements.controller.ts, guards/entitlement.guard.ts).
• Chi tiết triển khai:
  • CompanyEntitlement lưu hạn mức cơ sở từ ServicePlan cộng với hạn mức mua thêm lẻ (addon_qr_quota, addon_max_products, addon_storage_gb, feature_overrides JSONB).
  • EntitlementsService.checkAndConsumeQuota(companyId, metric, delta) dùng câu lệnh SQL nguyên tử UPDATE company_usage_meters SET used_value = used_value + $1 WHERE company_id = $2 AND metric_code = $3 AND (used_value + $1) <= effective_limit để chặn vượt định mức mà không bị race condition.

Task 3C — WBS 2.34.1: Thanh toán Trực tuyến & Hóa đơn Điện tử (Hạn: 20/11/2026) ​

• Files cần tạo/sửa:
  • Modify: apps/backend/prisma/schema.prisma (thêm BillingInvoice, PaymentTransaction, EInvoiceRecord).
  • Create: apps/backend/src/modules/billing-payments/ (billing-payments.controller.ts, billing-payments.service.ts, providers/payos-vietqr.provider.ts, providers/einvoice.provider.ts).
• Chi tiết triển khai:
  • POST /api/v1/billing/checkout: Tạo hóa đơn chờ thanh toán (tính chiết khấu chu kỳ 2 năm/3 năm từ ServicePlan + VAT) và trả mã VietQR động / link thanh toán.
  • POST /api/v1/billing/webhooks/:provider: Verify chữ ký HMAC từ cổng thanh toán, xử lý idempotent theo provider_tx_id, tự động kích hoạt CompanySubscription / cộng CompanyEntitlement, và đẩy BullMQ job phát hành Hóa đơn điện tử (MISA meInvoice / Viettel SInvoice).

Workstream 4: Hồ sơ số DN/Lô, Xuất PDF có QR Xác thực, EPCIS/Linkset/DPP & Báo cáo Dashboard (WBS 2.13.2, 2.28.1, 2.28.2, 2.29.1, 2.30.1) ​

Task 4A — WBS 2.13.2: Xuất Báo cáo Dashboard (Đã có ~65%, Hạn: 28/11/2026) ​

• Tài liệu tham chiếu: SRS TXNG-F30 Dashboard & Bản đối chiếu Implementation vs SRS TXNG-F30
• Tận dụng code sẵn có: txng-dashboard.controller.ts đã có sẵn /overview/export, /production/export, /inventory/export, /module/:slug/export.
• Phần code thêm: Tạo apps/backend/src/modules/dashboard-tong/dashboard-tong-export.service.ts và route GET /api/v1/dashboard-tong/export?format=xlsx|pdf cho DashboardTongController, đồng thời nối vào dashboard-tong-scheduler để gửi email báo cáo tuần định kỳ.

Task 4B — WBS 2.30.1: Xuất Dữ liệu Máy đọc JSON/EPCIS, Linkset, DPP khi có GTIN (Đã có ~45%, Hạn: 02/12/2026) ​

• Tài liệu tham chiếu: GS1 EPCIS 2.0 & EU DPP Mapping & SRS ENV-F07 (Digital Product Passport)
• Files cần tạo/sửa:
  • Create: apps/backend/src/modules/machine-readable-export/ (epcis-serializer.service.ts, linkset-builder.service.ts, machine-readable-export.controller.ts).
  • Modify: apps/backend/src/modules/digital-product-passports/digital-product-passports.service.ts.
• Chi tiết triển khai:
  • GS1 EPCIS 2.0 JSON-LD (GET /api/v1/export/epcis/batch/:batchId & /public/trace/:gtin/:ulid/epcis.jsonld): Serialize các sự kiện CTE-MATERIAL-IN (TransformationEvent), CTE-PACKAGING (AggregationEvent), CTE-PRODUCTION/CTE-SHIP/CTE-RECEIVE/CTE-SOLD (ObjectEvent).
  • GS1 Digital Link Linkset (GET /api/v1/public/linkset/01/:gtin14): Trả application/linkset+json chuẩn RFC 9264 gồm gs1:pip, gs1:epcis, gs1:dpp, gs1:certificationInfo.
  • DPP theo GTIN/Batch (GET /api/v1/public/dpp/01/:gtin14): Xuất JSON-LD hộ chiếu số sản phẩm khi sản phẩm có nda_gtin_code (GTIN-14).

Task 4C — WBS 2.29.1, 2.28.1 & 2.28.2: Hồ sơ số DN/Lô, Nhật ký Điện tử v1 & Xuất PDF có QR Xác thực (Hạn: 30/11 – 10/12/2026) ​

• Tài liệu tham chiếu: SRS TXNG-F07 (Nhật ký Sơ chế/Chế biến) & SRS TXNG-F09 (Quản lý Lô & Mã)
• Files cần tạo/sửa:
  • Modify: apps/backend/prisma/schema.prisma (thêm ProductionLogHistory lưu audit trail khi sửa ProductionLog).
  • Create: apps/backend/src/modules/digital-dossiers/ (digital-dossiers.controller.ts, digital-dossiers.service.ts, verifiable-pdf.service.ts).
  • Create: apps/frontend/app/admin/dossiers/company/page.tsx & apps/frontend/app/admin/dossiers/batches/[id]/page.tsx.
• Chi tiết triển khai:
  • 2.28.1 (Hồ sơ số DN): API & UI tổng hợp pháp nhân, DID/GCP, chứng nhận, vùng nguyên liệu, cơ sở sản xuất và lịch sử tuân thủ.
  • 2.28.2 (Hồ sơ số Lô hàng & Nhật ký điện tử v1): Ghi lại ProductionLogHistory mỗi khi sửa nhật ký; xem timeline hợp nhất (Input Links + Production Logs + QC + VC) và xuất Excel/PDF theo lô hoặc theo kỳ kèm sheet lịch sử sửa.
  • 2.29.1 (Xuất PDF có QR xác thực): VerifiablePdfService render PDF A4 cho Hồ sơ DN / Sản phẩm / Lô hàng, nhúng mã QR xác thực dẫn tới URL kiểm tra chữ ký số W3C VC (SgtinVc) & Merkle Proof (VcAnchorLeaf) trên Spores Blockchain kèm mã băm SHA-256.

Workstream 5: Portal HanoiTrace — CMS Quản trị & Hiển thị Bài viết (WBS 1.6) ​

• Hạn đề xuất: 26/11/2026
• Hiện trạng: Trang apps/frontend/components/blog/blog-content.tsx và apps/frontend/app/blog/page.tsx đang lấy dữ liệu tĩnh từ apps/frontend/_mock/_blog.ts và _mock/_category.ts.
• Files cần tạo/sửa:
  • Modify: apps/backend/prisma/schema.prisma (thêm CmsCategory, CmsArticle).
  • Create: apps/backend/src/modules/cms/ (cms.module.ts, cms-admin.controller.ts, cms-public.controller.ts, cms.service.ts).
  • Create: apps/frontend/app/admin/cms/articles/page.tsx & categories/page.tsx.
  • Modify: apps/frontend/components/blog/blog-content.tsx & apps/frontend/app/blog/[slug]/page.tsx.
• Chi tiết triển khai:
  • Hỗ trợ đa thương hiệu qua cột brand (HANOITRACE | GOTRACE | ALL), trạng thái DRAFT → PUBLISHED → ARCHIVED, ghim bài nổi bật (is_featured, is_pinned), sanitize content_html chống Stored XSS, và cache danh sách bài viết công khai trên Redis.