init git

.claude/skills/sad-bid/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: sad-bid
+description: Lập bộ hồ sơ dự thầu dự án CNTT hoàn chỉnh từ tài liệu SAD — ma trận đáp ứng HSMT, danh mục chức năng/tính năng, sơ đồ hoạt động, tech stack, ước lượng MM (WBS bottom-up + Use Case Points, tính bằng code), chi phí, kế hoạch/timeline/staffing, đề xuất tài chính, checklist hồ sơ pháp lý — qua workflow generate-bid.js với cổng phê duyệt từng stage và reviewer độc lập. Dùng khi người dùng nói "làm hồ sơ thầu", "hồ sơ dự thầu", "đề xuất kỹ thuật/tài chính", "ước lượng MM", "báo giá dự án", "kế hoạch triển khai cho thầu".
+---
+
+# Hồ sơ thầu từ SAD — quy trình có cổng phê duyệt
+
+Bạn (main assistant) điều phối & làm gatekeeper. Agent viết, code tính, **con người duyệt từng stage và điền số liệu thương mại**. Cấu trúc chuẩn & quy tắc: `references/dossier-structure.md`. Engine: `Workflow({ scriptPath: "<abs>/.claude/workflows/generate-bid.js", args })` — **một stage mỗi lần gọi**.
+
+## `args`
+| Tham số | Ý nghĩa |
+|---|---|
+| `stage` | `intake` → `technical` → `estimate` → `plan` → `financial` → `assemble` → `deck` → `export` → `review` |
+| `targets` | (export, tuỳ chọn) `[{html, pdf, kind, optional}]` — mặc định `index.html → HO-SO-THAU.pdf` và `deck.html → deck.pdf` (optional) |
+| `date` | ngày hôm nay `YYYY-MM-DD` (bắt buộc) |
+| `pricing` | object lấy từ frontmatter `bid/bid-config.md` (roles, mdPerMM, hoursPerDay, hoursPerUCP, overheadMode/Pct/Role, contingencyPct, vatPct, currency, rateCard, nonLabor, teamSize, targetMonths, parallelEfficiency, projectStartDate, projectDeadline, ucpVarianceThresholdPct) — **bắt buộc ở stage estimate** |
+| `notes` | ghi chú người duyệt khi chạy lại một stage |
+| `bidDir`, `sadFile`, `sectionsDir`, `briefFile` | đường dẫn (mặc định `bid/`, `docs/SAD.md`, `docs/sections`, `docs/00-project-brief.md`) |
+
+## Bước 0 — Điều kiện & thông tin thương mại
+1. `docs/SAD.md` phải có (không ⇒ đề nghị chạy `sad-pipeline` consolidate; chạy từ sections được nhưng cảnh báo). Section chưa `approved` ⇒ hồ sơ là **bản nháp nội bộ**, nói rõ.
+2. Tạo `bid/inputs/` và hỏi người dùng có HSMT/RFP không → đặt file vào đó, ghi `rfpFiles`. Không có ⇒ pipeline dùng cấu trúc mặc định + tự đối chiếu theo FR.
+3. Chưa có `bid/bid-config.md` ⇒ copy `bid-config.template.md`. Hỏi (≤4 câu/lượt, ≤3 lượt, không hỏi lại điều đã có): bên dự thầu/bên mời thầu/gói thầu/nguồn vốn; deadline nộp & ngày bắt đầu & deadline thực hiện; **rate card theo vai trò & VAT & currency** (không có ⇒ để 0 → placeholder, giá sẽ "tạm tính"); chi phí phi nhân công đã biết; teamSize/targetMonths; hồ sơ năng lực sẵn có (companyDocs); nhân sự chủ chốt. Ghi vào config bằng Edit.
+
+## Vòng lặp stage — luôn: chạy → trình bày trung thực → hỏi **Duyệt / Sửa (ghi chú) / Dừng** → Duyệt mới sang stage kế
+1. **intake** (`bid-analyst`) → trình: tiêu chí chấm & trọng số, yêu cầu bắt buộc & mức đáp ứng, `gaps` (yêu cầu SAD không đáp ứng — **quyết định của người dùng**: bổ sung giải pháp, chấp nhận "một phần", hay không dự thầu), checklist tài liệu Phần A với trạng thái, cấu trúc HSMT quy định (nếu có).
+2. **technical** (`bid-technical-writer`) → trình: mục đã viết, sơ đồ, tech stack, `uncoveredMandatory` (phải rỗng), placeholders, keyFacts.
+3. **estimate** (`bid-estimator` + **code tính**) → truyền `pricing`. Trình: số hạng mục, `uncovered` FR, bảng MM theo vai trò, dự phòng, overhead, **grandMM**, đối chiếu UCP & `variancePct` (vượt ngưỡng ⇒ khuyến nghị xem lại hạng mục), chi phí (`missingRates`/`missingAmounts` ⇒ giá tạm tính), timeline (số tháng, teamSize suy ra hay cấu hình, `deadlineFit`), `warnings`. **Đây là gate quan trọng nhất**: người dùng xác nhận đơn giá, giả định năng suất, mức dự phòng, teamSize trước khi đi tiếp; sửa config ⇒ chạy lại estimate (số liệu mới ghi vào `bid/estimate.computed.json`).
+4. **plan** (`bid-planner`) → trình: giai đoạn/mốc/ngày, peak headcount, `deadlineFits` & phương án tăng tốc, placeholders. Nếu người dùng muốn đổi teamSize/ngày bắt đầu ⇒ sửa config, **chạy lại estimate rồi plan** (số phải đồng bộ).
+5. **financial** (`bid-financial-writer`) → trình: tổng trước/sau VAT, `missingRates`/`missingAmounts`, mốc thanh toán ↔ mốc B7, placeholders.
+6. **assemble** (`bid-builder`) → trình: `sectionsMissing` (phải rỗng), `checks`, `priceConsistentA1C5`, placeholdersCount; có thể publish `bid/artifact.html` (Artifact, favicon 📁) để người duyệt xem trực quan trước khi xuất PDF.
+7. **deck** (`bid-deck-builder`) → trình: `slideCount` (15–25), danh sách slide & nguồn, `numbersUsed`, `checks`, placeholdersCount; có thể publish `bid/deck-artifact.html` để xem. Duyệt kịch bản/nhấn mạnh theo tiêu chí chấm trước khi export.
+8. **export** (`bid-exporter`) → trình: `browser` đã dùng, từng PDF (`pages`, `sizeKB`, `mermaidRendered/mermaidExpected`, `outline`), `warnings`. `blocked=true` (không có Edge/Chrome) ⇒ đưa `manualInstructions` cho người dùng. Mermaid chưa render đủ ⇒ chạy lại export; lỗi thuộc HTML ⇒ quay lại `assemble`/`deck` với `notes`.
+9. **review** (`bid-reviewer`) → trình: `verdict`, `canSubmit`, `uncoveredMandatory`, `numberMismatches`, `leaks`, `placeholders`, `exportChecks`, findings theo `target`. Định tuyến sửa theo `target` (chạy lại stage đó với `notes`, rồi các stage sau phụ thuộc: sửa estimate ⇒ plan, financial, assemble, deck, export; sửa technical ⇒ assemble, deck, export; sửa plan ⇒ financial (C6), assemble, deck, export; sửa assemble/deck ⇒ export) và `review` lại; tối đa 2 vòng, sau đó báo người dùng.
+
+## Bàn giao
+**Bộ nộp:** `bid/HO-SO-THAU.pdf` (hồ sơ in hoàn chỉnh A4, có bookmark theo mục, số trang) và `bid/deck.pdf` (slide thuyết trình 16:9); **bản nguồn:** `bid/HO-SO-THAU.md`, `bid/index.html`, `bid/deck.html`; checklist Phần A với việc còn phải đính kèm (giấy tờ công ty do người dùng chuẩn bị). PDF được xuất tự động bằng Edge/Chrome headless có sẵn trên máy; nếu máy khác không có trình duyệt Chromium, exporter trả hướng dẫn in thủ công. Chỉ nói **"nộp được"** khi `canSubmit = true`; còn placeholder/`missingRates` ⇒ "bản nháp chờ điền". Nhắc: SAD và `estimate.json` (lý giải nội bộ) **không nộp** — chỉ nộp hồ sơ đã ráp; kiểm tra hiệu lực văn bản pháp lý tại thời điểm nộp.
+
+## Không được
+Bỏ gate · tự điền đơn giá/thuế/tên/ngày · để agent cộng số (chỉ code) · sửa nội dung thay agent (trừ frontmatter trạng thái) · nộp/publish khi còn `leaks` hoặc yêu cầu bắt buộc chưa đáp ứng.

.claude/skills/sad-bid/bid-config.template.md

@@ -0,0 +1,68 @@
+---
+# Cấu hình hồ sơ thầu — NGUỒN DUY NHẤT cho đơn giá / thuế / ngày / tên. Người điều phối điền cùng người dùng.
+# Giá trị còn [[CẦN ĐIỀN]] hoặc 0/null sẽ thành placeholder trong hồ sơ; hệ thống không bịa.
+bidder: "[[CẦN ĐIỀN: Tên công ty dự thầu]]"
+bidderContact: "[[CẦN ĐIỀN: Người phụ trách hồ sơ — chức danh, email, điện thoại]]"
+client: "[[CẦN ĐIỀN: Bên mời thầu]]"
+package: "[[CẦN ĐIỀN: Tên gói thầu]]"
+fundingType: private            # private | public  (public ⇒ nêu khung pháp lý VN kèm cờ 'cần xác minh')
+rfpFiles: []                    # đường dẫn HSMT/RFP trong bid/inputs/ (để trống nếu không có)
+submissionDeadline: ""          # YYYY-MM-DD
+priceValidityDays: 90
+language: vi
+brandColor: "#1f4e9c"
+logo: ""
+
+# --- Kế hoạch ---
+projectStartDate: "[[CẦN ĐIỀN: YYYY-MM-DD]]"
+projectDeadline: ""             # nếu HSMT ấn định thời gian thực hiện
+methodology: "Agile/Scrum hybrid, bàn giao theo đợt"
+warrantyMonths: 12
+teamSize: 0                     # 0 = hệ thống suy ra từ MM
+targetMonths: 0                 # 0 = không ép; >0 = suy teamSize để đạt
+parallelEfficiency: 0.85        # hệ số song song hoá (0.7–0.95)
+
+# --- Ước lượng ---
+roles: [PM, BA, SA, UIUX, BE, FE, QA, DEVOPS]
+mdPerMM: 21                     # man-day / man-month
+hoursPerDay: 8
+hoursPerUCP: 20                 # năng suất Use Case Points (20–28 giờ/UCP)
+overheadMode: itemized          # itemized = PM/BA ước lượng theo hạng mục | percent = cộng overheadPct
+overheadPct: 0                  # chỉ dùng khi overheadMode = percent
+overheadRole: PM
+contingencyPct: { low: 10, medium: 20, high: 35 }
+ucpVarianceThresholdPct: 25     # lệch WBS↔UCP vượt ngưỡng ⇒ phải giải thích ở C1
+
+# --- Giá ---
+currency: VND
+vatPct: 10
+pricingModel: fixed             # fixed | time-and-materials | phased
+rateCard:                       # đơn giá theo MM, chưa VAT; 0 = [[CẦN ĐIỀN]]
+  PM: 0
+  BA: 0
+  SA: 0
+  UIUX: 0
+  BE: 0
+  FE: 0
+  QA: 0
+  DEVOPS: 0
+nonLabor: []                    # [{id: NL-01, name: "Cloud năm 1", amount: 0, recurring: yearly, basis: "sizing §3"}]
+paymentMilestones: []           # [{milestone: "Ký hợp đồng", pct: 20}, ...]
+options: []                     # hạng mục tùy chọn tách riêng giá (GĐ2, bảo trì năm 2…)
+
+# --- Hồ sơ năng lực (Phần A) ---
+companyDocs:
+  businessLicense: missing      # available | missing
+  financialReports: missing
+  similarContracts: missing
+  keyPersonnelCVs: missing
+  iso9001: missing
+  iso27001: missing
+  cmmi: missing
+  bidSecurity: missing
+keyPersonnel: []                # [{role: PM, name: "", yearsExp: 0, certs: []}]
+consortium: []                  # liên danh/thầu phụ
+---
+
+## Ghi chú thương mại & điều kiện
+<!-- Điều khoản thanh toán chi tiết, loại trừ, điều kiện đặc biệt, tỷ giá. -->

.claude/skills/sad-bid/references/dossier-structure.md

@@ -0,0 +1,57 @@
+# Cấu trúc hồ sơ dự thầu dự án CNTT — chuẩn áp dụng cho pipeline `sad-bid`
+
+Mọi agent trong pipeline đọc file này trước khi viết. Số thứ tự mục (A1…D5) là **ID cố định** để truy vết và để reviewer kiểm tra thiếu mục.
+
+## Nguyên tắc
+1. **Một nguồn số liệu duy nhất:** mọi con số MM/chi phí/thời gian trong hồ sơ lấy từ `bid/estimate.computed.json` (do workflow tính bằng code). Agent không tự cộng trừ, không làm tròn khác.
+2. **Mọi mục Phần B truy vết được về SAD** (ghi "Nguồn: SAD §x") hoặc về `bid-config`/HSMT. Không nguồn ⇒ giả định, ghi vào B10.
+3. **Không rò rỉ nội bộ:** không đưa ghi chú rà soát, trạng thái duyệt, OQ, findings, mã FR/NFR/TC ngoài Phụ lục, điểm yếu thiết kế, tên agent/pipeline.
+4. **Thiếu thông tin ⇒ `[[CẦN ĐIỀN: …]]`**, không bịa giá, tên, ngày, số hợp đồng, chứng chỉ.
+5. **Có HSMT/RFP ⇒ ma trận đáp ứng (B2.1) là bắt buộc** và cấu trúc hồ sơ phải theo mẫu HSMT nếu HSMT quy định; cấu trúc dưới đây là mặc định khi HSMT không quy định.
+6. Ngôn ngữ trang trọng, khách quan, hướng đánh giá theo tiêu chí chấm (nếu biết trọng số ⇒ ưu tiên độ sâu tương ứng).
+
+## Phần A — Hồ sơ hành chính, pháp lý & năng lực *(không suy từ SAD → checklist + placeholder)*
+| ID | Tài liệu | Bắt buộc | Nguồn |
+|---|---|---|---|
+| A1 | Đơn dự thầu (theo mẫu HSMT), thư giới thiệu/bìa | Có | bid-config, HSMT |
+| A2 | Bảo đảm dự thầu (thư bảo lãnh ngân hàng / đặt cọc) | Theo HSMT | HSMT |
+| A3 | Giấy ĐKKD, giấy ủy quyền ký hồ sơ | Có | Hồ sơ công ty |
+| A4 | Báo cáo tài chính 2–3 năm gần nhất, xác nhận thuế | Theo HSMT | Hồ sơ công ty |
+| A5 | Kinh nghiệm: hợp đồng tương tự + biên bản nghiệm thu/xác nhận | Có | Hồ sơ công ty |
+| A6 | Nhân sự chủ chốt: CV, bằng cấp/chứng chỉ, cam kết tham gia | Có | Hồ sơ công ty + B8 |
+| A7 | Chứng chỉ tổ chức (ISO 9001, ISO/IEC 27001, CMMI…) | Nếu có / theo HSMT | Hồ sơ công ty |
+| A8 | Thỏa thuận liên danh / danh sách thầu phụ | Nếu có | bid-config |
+| A9 | Cam kết: bảo mật, không vi phạm, không xung đột lợi ích, tuân thủ pháp luật | Theo HSMT | Mẫu công ty |
+| A10 | Tài liệu khác HSMT yêu cầu riêng | Theo HSMT | HSMT |
+
+## Phần B — Đề xuất kỹ thuật
+| ID | Mục | Nội dung tối thiểu | Nguồn SAD |
+|---|---|---|---|
+| B1 | Hiểu biết về yêu cầu & bài toán | bối cảnh, mục tiêu, phạm vi, đối tượng sử dụng, KPI | §1, brief |
+| B2 | Phạm vi & Danh mục chức năng/tính năng | bảng chức năng theo nhóm người dùng, mô tả, ưu tiên/giai đoạn; trong/ngoài phạm vi | §2, §7 |
+| B2.1 | **Ma trận đáp ứng yêu cầu HSMT** | Yêu cầu HSMT ↔ mục đáp ứng ↔ mức (Đáp ứng / Đáp ứng một phần / Vượt / Không) ↔ bằng chứng | HSMT ↔ §2–§9 |
+| B3 | Giải pháp kỹ thuật & sơ đồ hoạt động | kiến trúc tổng thể, use case, luồng nghiệp vụ chính (sequence), sơ đồ triển khai, mô hình dữ liệu khái niệm, tích hợp bên ngoài | §3, §4, §5, §6 |
+| B4 | Tech stack & hạ tầng đề xuất | bảng lớp × công nghệ × lý do × license; sizing hạ tầng (môi trường, cấu hình) | §3, §5 |
+| B5 | Bảo mật & tuân thủ | xác thực/phân quyền, bảo vệ dữ liệu, chuẩn tuân thủ, kiểm thử bảo mật | §8 |
+| B6 | Phương pháp luận triển khai & quản lý | mô hình (Agile/hybrid), quy trình chất lượng, chiến lược kiểm thử, quản lý rủi ro/thay đổi/cấu hình, báo cáo | §9 |
+| B7 | Kế hoạch triển khai | WBS, Gantt, mốc, sản phẩm bàn giao theo giai đoạn, tiêu chí nghiệm thu từng mốc | computed + §9 |
+| B8 | Tổ chức nhân sự & staffing plan | sơ đồ tổ chức, vai trò/trách nhiệm, số lượng theo tháng, nhân sự chủ chốt (→A6) | computed, bid-config |
+| B9 | Đào tạo, chuyển giao, bảo hành, hỗ trợ | kế hoạch đào tạo, tài liệu bàn giao, thời hạn bảo hành, SLA hỗ trợ | §9, bid-config |
+| B10 | Giả định, ràng buộc, loại trừ, trách nhiệm bên mời thầu | | §1, intake |
+
+## Phần C — Đề xuất tài chính
+| ID | Mục | Nội dung | Nguồn |
+|---|---|---|---|
+| C1 | Cơ sở & phương pháp ước lượng | WBS bottom-up (chính) + Use Case Points (đối chiếu), độ lệch, giả định năng suất | estimate.json, computed |
+| C2 | Bảng effort theo chức năng × vai trò | MD từng hạng mục, tổng theo vai trò, quy đổi MM (MD/MM theo config) | computed |
+| C3 | Đơn giá nhân sự & chi phí nhân công | rate card theo vai trò × MM | bid-config, computed |
+| C4 | Chi phí khác | hạ tầng/cloud năm đầu, license, dịch vụ bên thứ ba, đào tạo, bảo hành, quản lý, dự phòng | bid-config, §3 |
+| C5 | Tổng giá dự thầu | trước/sau VAT, tùy chọn (option), đơn vị tiền | computed |
+| C6 | Điều khoản thanh toán & hiệu lực giá | mốc thanh toán gắn với B7, hiệu lực báo giá | bid-config, B7 |
+| C7 | Biểu giá theo mẫu HSMT | nếu HSMT có mẫu | HSMT |
+
+## Phần D — Phụ lục
+D1 Danh mục chức năng chi tiết (kèm mã tham chiếu) · D2 Bộ sơ đồ · D3 Ước lượng chi tiết (bảng từ estimate.json) · D4 Ma trận truy vết yêu cầu → chức năng → mốc bàn giao → hạng mục giá · D5 Thuật ngữ.
+
+## Khung pháp lý tham chiếu (Việt Nam) — **phải xác minh hiệu lực tại thời điểm nộp thầu**
+Luật Đấu thầu 22/2023/QH15 và nghị định/thông tư hướng dẫn (mẫu HSMT dịch vụ phi tư vấn/hàng hóa CNTT); Nghị định 73/2019/NĐ-CP về quản lý đầu tư ứng dụng CNTT sử dụng NSNN (dự án vốn nhà nước); phương pháp xác định giá trị phần mềm theo Use Case Points (Công văn 2589/BTTTT-ƯDCNTT) thường được bên mời thầu nhà nước tham chiếu. Thầu tư nhân/doanh nghiệp: theo RFP của bên mời thầu. Agent chỉ **nêu tên** văn bản kèm cờ "cần xác minh", không trích dẫn điều khoản cụ thể nếu không có văn bản trong `bid/inputs/`.