# BA-Specs — Folder Structure

> **Managed by:** BA  
> **Organized by:** Output Type → Function-ID → Version  
> **Naming:** Function-ID format `F-001_User-Login`  
> **Note:** Templates are managed in a separate shared repo.

---

## Folder Tree

```
02.BA-Specs/
│
├── 00.Requirements/                    # Requirements Gathering
│   └── F-001_User-Login/
│       ├── Raw-Requirements_v1.md      # Optional. Customer raw requirements live on Backlog (ticket + Document)
│       ├── System-Requirement_v2.md    # Dev-facing bridge doc (create-system-requirement task type)
│       └── assets/                     # Images, attachments, recordings
│
├── 01.Analysis/                        # Gate 1: Business Analysis
│   └── F-001_User-Login/
│       ├── Analysis_v1.md              # frontmatter `sources`: Backlog ticket / Document / comment + `updated`
│       └── Analysis_v2.md              # Updated when requirements change (numbering continues across requests)
│
├── 02.QnA/                             # Gate 2: Q&A nội bộ với stakeholder
│   └── F-001_User-Login/
│       └── QnA-Log_v1.md               # Q&A loop until all Confirmed
│
├── 03.UI-Prototypes/                   # Gate 3: UI/UX Design
│   └── F-001_User-Login/
│       └── UI-Prototype_v1.html        # Static HTML/CSS prototype (akg: one file per screen, <Screen>_v1.html)
│
└── 04.UC-Specs/                        # Gate 4: Final UC Specification
    └── F-001_User-Login/
        ├── UC-Spec_v2.md               # frontmatter status: draft → signed (H1 / BA sign-off) — Dev input
        └── _archive/
            └── UC-Spec_v1.md           # Previous signed version, moved here when v2 is signed
```

---

## File Naming Convention

| Element | Convention | Example |
|---|---|---|
| Section folder | `{N}.{Pascal-Case}/` | `00.Requirements/`, `03.UI-Prototypes/` |
| Feature folder | `F-{3-digit}_{Pascal-Case}/` | `F-001_User-Login/` |
| Requirements file | `Raw-Requirements_v{N}.md` | `Raw-Requirements_v1.md` |
| System Requirement file | `System-Requirement_v{N}.md` | `System-Requirement_v2.md` |
| Analysis file | `Analysis_v{N}.md` | `Analysis_v2.md` |
| QnA file | `QnA-Log_v{N}.md` | `QnA-Log_v1.md` |
| Prototype file | `UI-Prototype_v{N}.html` | `UI-Prototype_v1.html` |
| Spec file | `UC-Spec_v{N}.md` | `UC-Spec_v2.md` |
| Archive folder | `_archive/` | `04.UC-Specs/F-001-User-Login/_archive/` |

---

## Gate → Folder Mapping

| Gate | Output | Folder |
|---|---|---|
| Gate 1 | Phân tích sơ bộ + Q&A clarify | `00.Requirements/` + `01.Analysis/` |
| Gate 2 | Q&A loop → Confirmed | `02.QnA/` |
| Gate 3 | UI Prototype | `03.UI-Prototypes/` |
| Gate 4 | UC Spec hoàn chỉnh (BA ký off) | `04.UC-Specs/` |

---

## Function-List.md Template

```markdown
| F-ID  | Feature Name | BA     | Dev    | Tester | Status                 | Tickets           | Link Spec |
|-------|-------------|--------|--------|--------|------------------------|-------------------|-----------|
| F-001 | User Login  | AnhNH  | HungPV | LinhTT | BA ✅ · Dev ✅ · QA ✅ | #100, #145, #167  | [link]()  |
| F-002 | Dashboard   | LyLT   | HungPV | LinhTT | BA ✅ · Dev 🔵 · QA 🔵 | #110, #178        | [link]()  |
| F-003 | ...         | ...    |        |        | BA ⬜ · Dev ⬜ · QA ⬜ | -                 | -         |
```

Cột `Status` do workflow tự cập nhật: ⬜ chưa bắt đầu, 🔵 đang làm, ✅ xong — mỗi vai trò một ký hiệu. Mốc cập nhật của từng workflow: `custom/rules/function-list-status.md`.

---

## UC Spec frontmatter (signed = input of Dev Team)

```yaml
---
functionId: F-001
title: User Login
type: new                # new | change
status: signed           # draft until signed (H1); Dev Team / akg only take the highest signed version
version: 2               # = N in UC-Spec_vN.md
signedBy: Human
signedAt: 2026-10-16
sources:                 # customer requirement on Backlog
  - backlog: PROJ-123
    updated: 2026-10-16T07:52:25Z
qna: 02.BA-Specs/02.QnA/F-001_User-Login/QnA-Log_v2.md   # confirmed Q&A, relative to AK-Docs
---
```

A signed UC Spec is not edited. A change creates `UC-Spec_v(N+1).md` (`type: change`); when it is signed, the previous signed file moves to `_archive/`.

## Rules

- Không tự sửa template — template nằm trong shared repo riêng
- Lưu tài liệu lên GitLab **sau khi Gate 4 được APPROVED**
- Thông báo cho Dev + Tester sau khi UC Spec sẵn sàng
- Không xóa file cũ — move vào `_archive/` khi có version mới
- `02.QnA/` là Q&A nội bộ với stakeholder — khác với `01.QnA/` ngoài dự án (dành cho khách hàng)
- `System-Requirement_v{N}.md` trong `00.Requirements/` do Dev viết (task type `create-system-requirement`, chạy 1 lần/functionId/UC Spec version), không phải do BA — `N` khớp đúng version của `UC-Spec_v{N}.md` mà nó trace tới, không phải bộ đếm riêng
