# DEV TEAM OPERATION HANDBOOK # DEV TEAM OPERATION HANDBOOK *(Sổ tay tổ chức & vận hành đội phát triển phần mềm – bản dùng cho Wiki nội bộ / Markdown)* --- ## 0. OUTLINE – KIẾN TRÚC TỔ CHỨC & CÔNG CỤ ### 0.1 Hệ sinh thái công cụ - **Jira / Issue Tracker**: quản lý Bug / Feature / Task / Epic, Sprint, Roadmap. - **Git (GitHub)**: mã nguồn, Pull Request (PR), bảo vệ nhánh, CI/CD. - **Wiki (Confluence/Notion/GitLab Wiki)**: HLD/LLD, Release Notes, KB, Meeting notes. - **Chat (Teams)**: daily standup, thông báo release, phối hợp Dev–QA–Ops. - **CI/CD (GitHub Actions)**: build, test, security scan, deploy. - **Monitoring/Alerting**: Sentry/Graylog/ELK + Prometheus/Grafana (log, APM, metric). ### 0.2 Liên kết giữa các công cụ - Mỗi **issue Jira** bắt buộc có **Issue Key** và được gắn trong **commit/PR** (`[#ISSUE-123]`). - **PR** phải liên kết **Issue** và **HLD/LLD** (nếu là feature/refactor). - **Pipeline CI** gửi **notification** về kênh `#dev-release` và cập nhật trạng thái vào Issue (transition tự động khi pass). - **Release Notes** mỗi version link danh sách **PR/Issue** đã merge và link **tag**. --- ## 1. TỔ CHỨC WORKSPACE ### 1.1 Jira / Boards / Workflow - **Boards**: - `Maintenance Board`: Bug, Hotfix, Support. - `Development Board`: Feature, Refactor, Improvement. - **Issue types**: `Epic`, `Story/Feature`, `Task`, `Bug`, `Sub-task`. - **Workflow chuẩn**: `To Do → In Progress → In Review → In Test → Ready to Deploy → Done`. - **Trường bắt buộc**: Assignee, Priority (P1/P2/P3), Estimate (SP/giờ), Labels (module), Sprint. ### 1.2 Wiki / Cấu trúc thư mục ``` /wiki ├─ roadmap/ ├─ release_notes/ ├─ design/ │ ├─ hld/ │ └─ lld/ ├─ processes/ ├─ retro/ └─ templates/ ``` ### 1.3 Channel giao tiếp (ví dụ Slack/Teams) - `#dev-daily`: daily standup, blocker. - `#dev-general`: trao đổi chung, thông báo. - `#dev-release`: thông báo CI/CD, tag, downtime, rollback. - `#qa-channel`: xác nhận test, ghi nhận bug. - `#dev-techup`: nội dung đào tạo, tài liệu, lịch. --- ## 2. QUY TRÌNH CHUẨN ISSUE → DEPLOY (E2E) | Stage | Mục tiêu | Đầu vào | Đầu ra | Trách nhiệm | | ---------------- | ----------------------------- | ------------------ | --------------- | ------------- | | 1. Tiếp nhận | Xác nhận phạm vi & độ ưu tiên | Yêu cầu/bug report | Issue hợp lệ | PO/QA/Lead | | 2. Design & Plan | Thiết kế & ước lượng | Issue + HLD/LLD | Plan + Estimate | Lead/Dev | | 3. Development | Thực hiện code | Plan + branch | PR hợp lệ | Dev | | 4. Review | Bảo đảm chất lượng | PR | PR được approve | Reviewer/Lead | | 5. Testing | Xác nhận chất lượng | Build staging | QA-PASS | QA | | 6. Deployment | Đưa lên môi trường | Tag/release | Prod updated | DevOps | | 7. Retrospective | Cải tiến liên tục | Số liệu sprint | Action items | Toàn team | --- ## 3. CHECKLIST THEO GIAI ĐOẠN ### 3.1 Stage 1 – Tiếp nhận - [ ] Mô tả rõ _What/Why/Expected Outcome_. - [ ] Assignee, Priority (P1/P2/P3), Estimate (SP/giờ), Labels module. - [ ] Acceptance Criteria (AC) rõ ràng. - [ ] **Bug**: môi trường, steps to reproduce, expected vs actual, logs/screenshot. - [ ] **Feature**: link HLD (bắt buộc), LLD nếu chạm DB/API. ### 3.2 Stage 2 – Design & Plan - [ ] HLD/LLD cập nhật trong `/wiki/design/`. - [ ] Phân tích rủi ro: dữ liệu, hiệu năng, bảo mật, tương thích ngược. - [ ] Chia nhỏ thành sub-task nếu > 2–3 ngày. - [ ] Gắn Sprint/Milestone, xác nhận effort & dependency. ### 3.3 Stage 3 – Development - [ ] Tạo branch đúng format (`feature/`, `bugfix/`, `hotfix/`, `refactor/`). - [ ] Commit message: `[TYPE] short description (#ISSUE-ID)`. - [ ] Không commit secret/.env/log/dump; `.gitignore` đầy đủ. - [ ] Có unit test/fixture (khi áp dụng), script demo nếu cần. - [ ] Update schema/API phải có migration và doc. ### 3.4 Stage 4 – Code Review **Reviewer kiểm tra:** - [ ] Đúng convention (PEP8/Odoo/ESLint), dễ đọc, tách hàm. - [ ] Không duplicate logic, không _magic number_. - [ ] Xử lý lỗi/exception đầy đủ, timeout/transaction. - [ ] Truy vấn/IO tối ưu; không N+1; index phù hợp. - [ ] Test/CI pass; PR ≤ 500 LOC (nếu lớn: đề nghị tách PR). - [ ] Tài liệu cập nhật khi đổi hành vi. ### 3.5 Stage 5 – Testing (QA) - [ ] Test case trong Jira/TestRail; mapping AC đầy đủ. - [ ] Test trên `staging` với dữ liệu gần thực tế. - [ ] Kiểm tra regression module liên quan. - [ ] Gắn nhãn `QA-PASS` trước khi deploy. ### 3.6 Stage 6 – Deployment - [ ] Merge `develop → release/x.y`; **tag** `vX.Y.Z`. - [ ] CI/CD: build, unit/integration test, security scan pass. - [ ] Maintenance window (20:00–22:00) + người trực Dev & QA. - [ ] Post kết quả/rollback (nếu có) vào `#dev-release`. - [ ] Cập nhật `/wiki/release_notes/`. ### 3.7 Stage 7 – Retrospective - [ ] Thống kê bug post-release, MTTR, tỉ lệ pass pipeline. - [ ] Review estimate vs thực tế, nguyên nhân chênh lệch. - [ ] Chốt action items + owner + ETA; lưu `/wiki/retro/`. --- ## 4. QUẢN TRỊ MEETING & NGHI THỨC LÀM VIỆC ### 4.1 Lịch & nội dung chuẩn | Meeting | Tần suất | Thành phần | Thời lượng | Nội dung/Checklist | | --------------- | ----------- | --------------------- | ------------- | -------------------------------------------------------- | | Daily Standup | Mỗi ngày | Dev/QA/Lead | 15 phút | Hôm qua/Hôm nay/Blocker; cập nhật Jira trước họp | | Sprint Planning | 2 tuần/lần | PM/Lead/Dev/QA | 60–90 phút | Chọn scope, estimate, assign, rủi ro, Definition of Done | | Sprint Review | Cuối sprint | PM/Stakeholder/Dev/QA | 45–60 phút | Demo, kết quả KPI, quyết định release | | Retrospective | Cuối sprint | Toàn team | 45–60 phút | What went well/bad/learned; action items | | Weekly Report | Hàng tuần | Lead/PM | 30 phút | Velocity, bug ratio, blockers, staffing | | TechUp | Hàng tuần | Tất cả dev | 45–60 phút | Chủ đề, slide, demo, KB; đăng ký host luân phiên | | 1–1 Mentoring | Hàng tháng | Lead + từng Dev | 30 phút/người | Kỹ năng, mục tiêu, kế hoạch phát triển | ### 4.2 Quy tắc tổ chức họp - Bắt đầu đúng giờ, kết thúc đúng giờ; facilitator rõ ràng. - Tất cả quyết định phải **ghi log** vào Wiki/Minutes & assign owner. - Không họp nếu không có agenda; agenda phải gửi tối thiểu 2h trước. --- ## 5. CHIẾN LƯỢC BRANCH, PR, CI/CD ### 5.1 Branching ``` main (production – protected) ├─ release/x.y (stable for patch) ├─ develop (integration) │ ├─ feature/ │ ├─ bugfix/- │ ├─ hotfix/ │ └─ refactor/ ``` **Quy tắc:** - Chỉ PR mới được merge (cấm push trực tiếp `main`, `release/*`, `develop`). - `hotfix/*` có thể từ `main` → PR vào `main` + `develop` (back-merge). ### 5.2 Commit & PR - **Commit**: nhỏ, có ý nghĩa; `[TYPE] msg (#ISSUE-ID)` (TYPE: FEATURE/BUGFIX/REFACTOR/CHORE/DOCS). - **PR template** bắt buộc (mô tả, ảnh hưởng, risk, checklist, test plan). - **Reviewers**: ≥ 1 (PR > 500 LOC: ≥ 2). SLA phản hồi: 24h. ### 5.3 CI/CD Pipeline (tham chiếu) 1) Lint + Unit Test → 2) Build Image/Package → 3) Security Scan (SAST/Dependency) → 4) Integration Test → 5) Staging Deploy → 6) Manual Gate → 7) Prod Deploy khi **tag**. --- ## 6. CODE REVIEW POLICY (TIÊU CHÍ & CHẤM ĐIỂM) ### 6.1 Tiêu chí đánh giá - **Đúng**: logic đúng, AC đạt, không phá backward compatibility. - **Sạch**: convention, cấu trúc, tách lớp/service, log rõ ràng. - **Nhanh**: truy vấn tối ưu, hạn chế round-trip, batch/bulk hợp lý. - **An toàn**: input validation, permission check, secret handling, rate limit. - **Kiểm thử**: có test/plan; QA có thể theo dõi và tái hiện. ### 6.2 Thang điểm gợi ý (0–2 điểm mỗi tiêu chí; tổng 10) - 0: thiếu/không đạt; 1: chấp nhận được; 2: tốt. - PR < 7 yêu cầu chỉnh sửa; ≥ 8 cho phép merge. --- ## 7. WORKLOAD, KPI & NĂNG LỰC ### 7.1 Quy tắc phân bổ - Mỗi dev tối đa **2 issue song song**; ưu tiên dứt điểm. - Task > 3 ngày → chia nhỏ; cập nhật estimate khi thay đổi > 20%. ### 7.2 KPI đề xuất - **Velocity**: Story points/sprint. - **Lead Time**: Issue created → Done. - **PR Throughput**: số PR/tuần; **Review Time** trung bình. - **Bug Ratio**: (Bug post-release)/(Feature release). - **TechUp Contribution**: số buổi host/bài KB/quý. ### 7.3 Năng lực & mentoring - Ma trận năng lực: Domain (Odoo/Backend/Frontend/DevOps), Coding, Review, Testing, Communication. - 1–1 hằng tháng: mục tiêu 3 tháng, kế hoạch học tập, shadowing/mentoring. --- ## 8. VAI TRÒ & RACI | Hạng mục | PO | PM | Dev | QA | Dev Lead | DevOps | | ------------------ | -- | -- | --- | --- | -------- | ------ | | Tiếp nhận yêu cầu | A | R | C | C | C | - | | Thiết kế (HLD/LLD) | C | C | R | C | A | - | | Phát triển | - | C | R | C | A | - | | Code Review | - | - | C | - | A/R | - | | Kiểm thử | - | C | C | A/R | C | - | | Triển khai | - | C | C | C | C | A/R | | Release Notes | C | A | C | C | R | C | | Retro/Improvement | C | A | R | R | A | C | (A: Accountable, R: Responsible, C: Consulted) --- ## 9. TEMPLATES (RAW MD) ### 9.1 Pull Request Template ```md ## Description [Feature/Bug/Refactor] … ## Related Issue Fixes #ISSUE-ID ## Impact/Risk - Module ảnh hưởng: … - Migration: Có/Không (mô tả) ## Test Plan - Case 1: … - Case 2: … ## Checklist - [ ] Đã test local - [ ] Pass CI - [ ] Cập nhật wiki/doc - [ ] Không commit file rác/secret ``` ### 9.2 Weekly Report Template ```md # Weekly Report – [Tên Dev] – Tuần [XX] ## Done - [x] … ## In Progress - [ ] … ## Blockers - … ## Next Week Plan - … ``` ### 9.3 TechUp Note Template ```md # TechUp – [Ngày] – [Chủ đề] **Host:** … **Tóm tắt:** … **Demo/Repo:** … **Bài học:** … **Tài liệu tham khảo:** … ``` --- ## 10. PHỤ LỤC – CHECKLIST TỔNG HỢP THEO LOẠI TASK ### 10.1 BUG / HOTFIX - **Tiếp nhận**: [ ] Steps to reproduce; [ ] Env; [ ] Logs; [ ] Priority P1/P2/P3. - **Dev**: [ ] Branch `bugfix/` hoặc `hotfix/`; [ ] Test local; [ ] PR liên kết issue. - **Review**: [ ] RCA ngắn; [ ] Không ảnh hưởng chức năng khác; [ ] Pipeline pass. - **Test**: [ ] QA regression; [ ] Tag `QA-PASS`. - **Deploy**: [ ] Nếu P1: theo quy trình hotfix (cửa sổ khẩn). ### 10.2 FEATURE - **Tiếp nhận**: [ ] AC; [ ] HLD; [ ] Estimate; [ ] Labels module. - **Dev**: [ ] Branch `feature/`; [ ] Unit test (nếu có); [ ] Doc cập nhật. - **Review**: [ ] Design alignment; [ ] Security/permission; [ ] Performance. - **Test**: [ ] UAT trên staging với dữ liệu mẫu. - **Deploy**: [ ] Tag version; [ ] Release note. ### 10.3 REFACTOR / IMPROVEMENT - **Tiếp nhận**: [ ] Phạm vi; [ ] Chỉ số kỳ vọng (perf/memory/complexity). - **Dev**: [ ] Benchmark trước/sau; [ ] Không đổi behavior (hoặc có doc). - **Review**: [ ] Code smell giảm; [ ] Test coverage không giảm. - **Test**: [ ] Regression lân cận; [ ] So sánh benchmark. ### 10.4 INFRA / MAINTENANCE - **Kế hoạch**: [ ] Thời gian; [ ] Ảnh hưởng; [ ] Rollback plan. - **Thực thi**: [ ] Script/IaC; [ ] Change log. - **Sau triển khai**: [ ] Health check; [ ] Post-mortem nếu sự cố. --- ## 11. MEETING AGENDA – SUMMARY - **Daily**: Yesterday/Today/Blocker (<= 60s/người). Cập nhật Jira trước họp. - **Planning**: mục tiêu sprint, scope, estimate, risk, DoR/DoD, capacity, dependency. - **Review**: demo; KPI sprint; quyết định release. - **Retro**: keep/try/stop; 3 hành động ưu tiên + owner + ETA. - **TechUp**: 1 chủ đề/tuần; slide + demo; KB sau buổi. --- ## 12. ĐỊNH NGHĨA – DoR & DoD - **Definition of Ready (DoR)**: Issue có mô tả + AC + estimate + assignee + tài liệu kèm. - **Definition of Done (DoD)**: Code + Review + Test pass + Doc/Release note + Deploy/Verify. --- ## 13. BẢO MẬT & TUÂN THỦ - Không lưu secret trong repo; dùng Vault/CI variables. - Log không chứa dữ liệu nhạy cảm; ẩn PII theo quy định. - Bật branch protection, 2FA, review bắt buộc. - Định kỳ security scan dependency & SAST.