Sổ tay team — MMS (Linkly MMS)¶

Bản tiếng Anh: team-playbook

Ngữ cảnh: Cách team MMS dùng Obsidian vault cùng GitLab, Figma và OpenProject. Đọc một lần khi vào team; owners duy trì tài liệu này.

Owners: Martin, Loi Truong

Mỗi công cụ dùng để làm gì¶

Công cụ	Vai trò	Link MMS
Vault này	Tri thức bền: spec, ADR, meeting, feature, truy vết về PDF trong `raw/`	`projects/mms/`
OpenProject	Việc hàng ngày: task, người phụ trách, deadline, sprint	Dự án MMS
GitLab BE	Code backend, MR, CI	cloudbanking
GitLab FE	Code frontend, MR, CI	mms-fe
Figma	Nguồn sự thật UI/UX	Linkly MMS
Slack / chat	Trao đổi nhanh — không phải nơi lưu chính thức	—

Gợi ý nhanh: Sau sáu tháng, câu “vì sao làm thế?” → trả lời trong vault (spec + ADR + link). Câu “tuần này ai làm gì?” → OpenProject.

Hai quy tắc sắt (không thỏa hiệp)¶

Không sửa raw/. Thả file gốc vào raw/specs/, raw/designs/, raw/meetings/, raw/emails/. File sai? Viết trang correction trong thư mục đã xử lý; không đổi file gốc.
Luôn cập nhật index.md và log.md sau khi thêm, đổi tên hoặc xóa trang wiki (project; thêm cả vault gốc nếu ảnh hưởng cross-project).

Quy tắc đầy đủ của vault: AGENTS.md / CLAUDE.md.

Bản đồ thư mục (MMS)¶

projects/mms/
├── README.md              ← trang chủ, link chính
├── team-playbook.md       ← bản tiếng Anh
├── team-playbook-vi.md    ← bản tiếng Việt (file này)
├── index.md               ← mục lục (giữ cập nhật)
├── log.md                 ← nhật ký thay đổi project
├── raw/                   ← chỉ nguồn gốc, không sửa
├── specs/                 ← spec đã xử lý (một trang / một nguồn)
├── designs/               ← ghi chú thiết kế → Figma / export raw
├── meetings/              ← biên bản meeting đã chỉnh
├── decisions/             ← ADR
├── features/              ← một trang / một feature
├── bugs/                  ← một trang / một bug
└── dev-notes/             ← spike, nhật ký kỹ thuật

Chuẩn dùng chung nhiều dự án (EMV, PCI, tài liệu vendor): _shared/ — không để dưới mms/ trừ khi chỉ thuộc MMS.

Flow Team Lead (từ YC khách → delivery)¶

Vai trò: Dung Pham (Team Lead) — nhận YC, định nghĩa phạm vi, tạo task, chốt ship. Owners dự án: Martin, Loi Truong.

1. Nhận yêu cầu khách (KH)¶

Bước	Việc	Ở đâu
1	Nhận PDF / email / brief từ KH	Ngoài vault
2	Thả file gốc không sửa	`raw/specs/` (hoặc `raw/meetings/`, `raw/emails/`)
3	Ingest / tóm tắt	`specs/<slug>.md` + số trang PDF
4	Họp nội bộ, ghi quyết định	`meetings/YYYY-MM-DD-<topic>.md`

Kết quả: team hiểu KH muốn gì (spec + meeting).

2. Chia thành feature (wiki = nguồn sự thật product)¶

Bước	Việc	Ở đâu
1	Map YC → feature có sẵn hoặc feature mới	`features/<slug>.md` (một file / một capability)
2	Viết Why, What, Out of scope	Cùng file feature
3	Chia AC: Product (E2E) + Frontend + Backend + Done together	Template feature
4	Gán người (nếu đã rõ)	`assignees.fe` / `be` / `qa` → link `[[_people/...]]`
5	Ghi release (nếu có)	`target_release:`
6	Cập nhật mục lục	index + log nếu thay đổi lớn

Kết quả: mọi người đọc một trang biết làm gì và xong khi nào.

3. Tạo task OpenProject (cha–con)¶

Parent (Epic / Feature WP)
  Wiki: projects/mms/features/<slug>.md
  Version: MMS-2026.06-R1   (khi có release)

  ├── Child FE  → assignee FE (vd. Loc Le)
  ├── Child BE  → assignee BE (vd. Vu Nguyen)
  └── Child QA  → assignee QA (vd. Hao Le)   (nếu cần)

Mỗi child trong description:

Wiki: projects/mms/features/<slug>.md
Layer: FE | BE | QA

Không tạo features/fe-* và features/be-* riêng — chỉ một trang wiki + nhiều task OP.

4. Trong sprint / hàng ngày (Team Lead)¶

Standup theo tên feature wiki, không chỉ theo MR lẻ.
Review MR: có link wiki + đúng layer FE/BE.
KH đổi scope → sửa feature/spec (processed), không sửa raw/; tạo/đổi task OP; ghi log.
Ship → tick AC Product + Done together; đóng parent + children OP; cập nhật status: feature.

Tóm tắt Lead: raw → spec/feature → OP (parent + FE/BE/QA) → assign → review MR → E2E → shipped + log

Flow Dev (member)¶

Đối tượng: Fullstack (Duc, An, Phat), FE (Loc), BE (Vu), QA (Hao).

Một dòng: OP → đọc wiki → code (MR app) → cập nhật wiki (PR mmswiki) → đóng OP

Nguyên tắc: Một feature = một file features/<slug>.md. Task OP của bạn = một layer (FE / BE / QA). Không tạo fe-* / be-* wiki riêng.

Các bước (mỗi task)¶

#	Việc	Làm gì
1	Nhận việc	Mở child OP → đọc `Wiki: projects/mms/features/<slug>.md` + `Layer: FE / BE / QA`
2	Đọc wiki	Why/What (không sửa). AC của layer mình. Delivery map / Figma
3	Phối hợp	FE↔BE contract API nếu cần; tranh chấp → Team Lead
4	Code	MR trên `mms-fe` (FE) hoặc `cloudbanking` (BE). Body: `Wiki: …` + `OP: #id`
5	Wiki PR	Branch `mms/wiki-<slug>-fe-<mô-tả>` (hoặc `-be-`) → sửa feature → MR `mmswiki` → reviewer Lead
6	Đóng OP	Staging OK + MR app merged + wiki PR merged → đóng child task

Wiki PR — chỉ sửa: AC Frontend/Backend (layer mình), Delivery map, Open questions; thêm dev-notes/ / bugs/ / _glossary/ nếu cần.

Wiki — không sửa (ping Lead): Why/What/Out of scope, Product & Done together AC, status: shipped, AC layer khác, raw/, index.md, log.md.

cd mmswiki && git pull origin develop
git checkout -b mms/wiki-<slug>-fe-<mô-tả>
# sửa projects/mms/features/<slug>.md
git commit -m "mms: <slug> — tick FE AC, add route …"
git push -u origin HEAD   # MR → develop → reviewer: Team Lead

Feature: <slug> | Layer: FE | OP: #1234 | App MR: <link>

Fullstack: có thể làm cả FE+BE — vẫn hai task OP (hoặc team thống nhất một task); một file wiki.

So sánh nhanh: Lead vs Dev¶

	Team Lead	Dev member
Input	YC khách, ưu tiên, release	Task OP + feature wiki
Wiki	Tạo/sửa feature, spec, meeting; review PR wiki	Đọc + sửa layer AC / Delivery map; PR vào mmswiki
OpenProject	Parent + FE/BE/QA, gán người, version	Làm & đóng child task
GitLab	Review MR	MR + link wiki/OP
Chốt “feature xong”	Product AC + E2E + `shipped`	Layer AC xong

Ví dụ: change mới trên Bulk Changes¶

Lead: KH gửi yêu cầu filter mới → cập nhật features/bulk-changes.md (AC FE/BE) → OP parent + task FE (Loc) + BE (Vu).
Dev FE: Đọc wiki → Figma → MR mms-fe + PR mmswiki (tick FE AC, route) → đóng task FE.
Dev BE: API → MR cloudbanking + PR mmswiki (tick BE AC, endpoint) → đóng task BE.
Lead / QA: E2E staging → tick Product AC → đóng parent → ghi log.

Quy trình thường ngày¶

Sau mỗi meeting quan trọng¶

Lưu recording/transcript vào raw/meetings/ (nếu có).
Tạo meetings/YYYY-MM-DD-<topic>.md từ template meeting.
Ghi rõ quyết định và action items (owner + deadline).
Đổi kiến trúc → ADR mới trong decisions/ và link từ meeting note.
Thêm dòng vào index và ghi log.

Người ghi biên bản luân phiên: thống nhất ở standup, hoàn thành trong 24h.

Spec / RFP / PDF chính thức mới từ khách¶

Thả file vào raw/specs/ (giữ tên gốc nếu được).
Nhờ assistant: “Ingest projects/mms/raw/specs/<file>.pdf” — xem đề xuất trước khi xác nhận.
Trang trong specs/ phải có số trang PDF trong frontmatter và dưới H1.
Tạo hoặc cập nhật features/ cho phạm vi bị ảnh hưởng; link hai chiều.

Phạm vi Figma mới hoặc export¶

Export / bằng chứng vào raw/designs/.
Trang trong designs/ tham chiếu frame Figma; dùng template design-review nếu cần.
Link các features/ liên quan.

Quyết định kiến trúc hoặc sản phẩm¶

decisions/<slug>.md từ template decision.
status: proposed → review team → accepted hoặc rejected.
Link từ features/, specs/ và ticket OpenProject bị ảnh hưởng.

Ship feature¶

Cập nhật features/<slug>.md → status: shipped (và lịch sử status).
Ghi log.
Đóng ticket OpenProject; merge MR trên GitLab BE/FE.

Bug¶

OpenProject — tái hiện lỗi, assignee, xác nhận fix.
Vault bugs/ — khi cần ghi chép bền (regression, lệch spec, RCA nhiều team). Link feature/spec/ADR.

Liên kết OpenProject ↔ vault¶

Trên mỗi work package không trivial, thêm vào mô tả:

Wiki: [[features/<slug>]] hoặc [[specs/<slug>]] hoặc [[decisions/<adr-slug>]]

Với người không dùng Obsidian, dán đường dẫn: projects/mms/features/<slug>.md.

Không dán nguyên spec vào OpenProject — chỉ link trang vault.

Quy trình Git (repo vault)¶

git pull trước khi làm.
Commit nhỏ, message rõ, ví dụ: mms: ingest merchant-onboarding spec, mms: ADR-002 api versioning.
Một người / một đợt ingest để tránh conflict index.md / log.md.
MR/PR khi team review tài liệu (nên có với ingest lớn).

PDF lớn: thống nhất commit tất cả bản binary hay chỉ bản “chính thức” (tránh nhiều bản draft trùng).

Làm việc với AI assistant¶

Prompt hay dùng

Ingest projects/mms/raw/specs/foo.pdf
Tạo feature merchant-onboarding link spec X và Figma; acceptance criteria từ trang 12–18
Tóm tắt quyết định từ ba meeting gần nhất về settlements
Trang nào link tới [[merchant-onboarding]]?

Assistant sẽ

Đề xuất vị trí trước khi viết (ingest).
Duy trì index.md và log.md.
Hỏi khi phân loại chưa rõ.

Bạn phải

Đối chiếu requirement đã ingest với PDF.
Xác nhận trước khi tách nhiều trang lớn.

Đặt tên và trạng thái¶

Tên file: lowercase-hyphenated.md
Meeting: YYYY-MM-DD-<topic>.md
Giá trị status: chỉ dùng bộ trong AGENTS.md (ví dụ feature proposed → shipped, spec draft → approved)
Người: _people/ — ho-ten.md (ví dụ loi-truong.md)

Checklist thành viên mới¶

[ ] Mở vault trong Obsidian; bật [[wikilinks]], Templates → _templates/
[ ] Đọc README, sổ tay này (hoặc bản EN), và log (10 entry gần nhất)
[ ] Có quyền: GitLab BE/FE, Figma, OpenProject MMS, Git remote vault
[ ] Lướt index — spec và feature đang active
[ ] Tham gia standup; biết ai ghi biên bản tuần này

Anti-patterns (tránh)¶

Sửa file trong raw/
Chỉ quyết định trên Slack, không ghi meetings/ hoặc decisions/
Copy cả spec vào OpenProject thay vì link vault
status feature trong vault lệch thực tế mà không ghi log
Tạo trang mà không cập nhật index hoặc log

Duy trì sổ tay¶

Ai: owners (Martin, Loi Truong) hoặc người được ủy quyền.
Khi nào: sau khi đổi quy trình; ghi log.
Đề xuất sửa: MR hoặc nhờ assistant cập nhật cả bản EN và VI rồi log.