SMP Process Documentation · v3.4¶
Phiên bản: 3.4 · Ngày: 2026-05-27 · Scope: Batch A + B (15 docs cho pilot)
Tài liệu chuẩn hoá process cho team SMP (10+ người · BA, Dev, QC, DevOps, Security) sử dụng Go + MySQL + Redis + MongoDB.
Mục đích¶
Sau khi product spec v3.1/v3.2/v3.3 đã ổn (UI/UX + business flow), team chuyển sang execution phase. Tài liệu này: - Chuẩn hoá how-to-build cho 6 vai trò - Reference cho onboarding member mới - Single source of truth cho decisions kỹ thuật - Tiền đề cho audit, compliance, scaling
Danh sách 16 docs + 1 plan¶
🌟 Start here¶
| # | Doc | Audience | Purpose |
|---|---|---|---|
| 00 | System Functional Overview | All roles | Executive summary · gom module + feature + flows + KPIs · đọc đầu tiên trước khi đào sâu |
| 🔮 | MIGRATION-PLAN-v4.md | Tech Lead, BA Lead, DevOps | 5-phase plan v3.4 → v4.0 · timeline · risks · rollback · success metrics |
🏛️ Architecture¶
| # | Doc | Audience | Purpose |
|---|---|---|---|
| 01 | Architecture · C4 + Service Catalog | All eng | Big picture: context, container, component diagrams · 10 microservices catalog · cross-cutting concerns |
🗄️ Database¶
| # | Doc | Audience | Purpose |
|---|---|---|---|
| 02 | Database Schema · ERD + DDL | DBA, Backend | Full MySQL DDL (smp_order, smp_catalog, smp_agent, smp_partner, smp_geo) + MongoDB collections + Redis patterns + naming + indexing + retention |
⚙️ Backend¶
| # | Doc | Audience | Purpose |
|---|---|---|---|
| 03 | API Contract · OpenAPI 3.0 | Backend, Frontend, Integration | REST conventions · auth · pagination · errors · all endpoints (orders, partners, dispatch, finance, quality) · rate limits |
| 04 | Go Coding Standards + Local Dev Setup | Backend | Go style guide · project structure · error handling · testing · DI · docker-compose for infra · Git workflow |
📊 BA · Business Analyst¶
| # | Doc | Audience | Purpose |
|---|---|---|---|
| 05 | Glossary · Thuật ngữ thống nhất | All | VN-EN dictionary cho domain (Service Template, Step, Agent, Partner, BOM, Stage, Dispatch...) |
| 09 | User Stories + Acceptance Criteria | BA, Dev, QC | 6 epics: Customer, Technician, Partner v3.3, Material BOM, Integration, Quality · Gherkin format · DoD · Fibonacci sizing |
| 14 | KPI / Metrics Definition | BA, PM, Data | Formulas cho 30+ metrics: GMV, completion rate, dispatch SLA, agent utilization, partner wallet health · dashboard mapping |
| 15 | Business Rules | All | 80+ rules tập trung: dispatch, pricing, payment, KYC, stages, materials, partners, integration, quality, notifications, retention |
🧪 QA¶
| # | Doc | Audience | Purpose |
|---|---|---|---|
| 10 | Test Plan + Test Cases | QC | Test strategy · TC template · sample cases cho Order/Partner/Dispatch/BOM/Integration · performance criteria (k6) · bug template · severity matrix |
🚀 DevOps¶
| # | Doc | Audience | Purpose |
|---|---|---|---|
| 06 | Environment Matrix · dev/staging/prod | DevOps, Backend | URLs · sizing · secrets (Vault) · per-env config · deployment promotion · access control · DNS · cost budgets |
| 07 | CI/CD Pipeline | DevOps | GitHub Actions sample (lint/test/build/scan/deploy) · GitOps + ArgoCD · Helm · blue/green strategy · migration in pipeline · SemVer releases · rollback |
| 11 | Runbook · Top 5 Incidents | SRE, On-call | Detect → Triage → Mitigate → Communicate → Resolve · 5 scenarios: dispatch down, webhook fail, MySQL lag, Redis OOM, integration circuit · escalation matrix |
🔒 Security¶
| # | Doc | Audience | Purpose |
|---|---|---|---|
| 08 | Auth Spec · JWT + RBAC | Backend, Frontend, Security | OAuth flows (customer phone OTP, ops email+2FA) · JWT structure (RS256) · scope catalog per role · resource-level authZ · password policy · session management · token revocation · CORS · rate limits |
| 12 | Audit Log Spec | Security, Backend, Compliance | Event categories · schema · naming convention · 7-year retention · query API · tamper resistance · PII handling · compliance mapping (PDPA VN) |
| 13 | Data Classification + Encryption Policy | Security, Backend, DevOps | L0-L4 classification · field encryption (AES-256) · key management (Vault) · TLS · PII display masking · vendor risk · compliance checklist · breach response |
Reading order theo vai trò¶
💡 Mọi role bắt đầu với Doc 00 · System Functional Overview — đọc 30-45 phút để hiểu big picture trước khi đào sâu chi tiết.
Dev mới onboard¶
- 00 System Functional Overview — big picture (45 min)
- 05 Glossary — hiểu thuật ngữ
- 01 Architecture — bức tranh tổng
- 04 Coding Standards + Setup — cài máy + chuẩn code
- 02 Database Schema — domain mình sẽ làm
- 03 API Contract — contract với FE/other svc
- 08 Auth Spec — security baseline
- 15 Business Rules — không gì khác trừ doc này khi confused
- 09 User Stories — what to build
BA mới onboard¶
- 00 System Functional Overview — big picture (45 min)
- 05 Glossary
- SPEC-v3.md, SPEC-v3.2.md, SPEC-v3.3.md (product specs)
- 09 User Stories
- 15 Business Rules
- 14 KPI Metrics
QC mới onboard¶
- 00 System Functional Overview — big picture (45 min)
- 05 Glossary
- 09 User Stories
- 15 Business Rules
- 10 Test Plan + Cases
- 03 API Contract (cho API testing)
DevOps mới onboard¶
- 00 System Functional Overview — big picture (45 min)
- 01 Architecture
- 06 Environment Matrix
- 07 CI/CD Pipeline
- 11 Runbook Incidents
- 13 Data Classification (encryption + Vault)
Security review¶
- 00 System Functional Overview — big picture (45 min)
- 08 Auth Spec
- 12 Audit Log
- 13 Data Classification
- 11 Runbook (incident response)
Stakeholder (CEO, Investor, Partner mới)¶
Chỉ cần đọc Doc 00 · System Functional Overview — 30-45 min. Đủ để hiểu hệ thống.
Cách maintain¶
Doc này là living document. Quy trình đóng góp đầy đủ xem CONTRIBUTING.md.
Tóm tắt:
1. PR vào repo smp-doc-process
2. Reviewer = 1 dev + 1 BA (cross-discipline)
3. Update version + changelog ở dưới
4. Notify team qua Slack #engineering-docs
Deploy / Setup¶
Lần đầu push lên GitHub: xem DEPLOY-GUIDE.md.
Repo URL: https://github.com/trungnguyenchanh/smp-doc-process
Site đẹp (sau khi setup MkDocs · xem DEPLOY-GUIDE): https://trungnguyenchanh.github.io/smp-doc-process/
Phase 2 docs (chưa build · Batch C)¶
Khi đi GA cần thêm: - Threat model (STRIDE per service) - Performance test results + capacity planning - Disaster recovery plan (RPO/RTO) - Compliance checklist (đầy đủ PDPA + financial) - Privacy policy + ToS (legal review) - C4 Level 3 component diagrams chi tiết - ADRs đầy đủ (architecture decision records)
Changelog¶
| Version | Date | Change | Author |
|---|---|---|---|
| 3.4 | 2026-05-27 | Initial · 15 docs Batch A+B | Team SMP |