# Mục 1.4.2 — Thêm mới tài liệu trong Cấu trúc hồ sơ (UC23)

> 📌 **PHẠM VI FILE NÀY — CHỈ TIỀN ĐIỀU KIỆN CHUNG CỦA CẢ BỘ CASE.**
>
> Được ghi ở đây: nguyên văn tiền điều kiện QA, cách đọc nó, bảng "vai → cách script dựng dữ liệu",
> dữ liệu mà setup tạo ra, danh sách case của mục.
>
> **KHÔNG** ghi ở đây: thao tác/kỳ vọng của từng case, cách assert, giả định khi viết case, điểm cần
> QA/DEV chốt, bảng hàm dùng chung. Những thứ đó là **logic của case** → mô tả trong khối comment đầu
> file `1.4.2.<mã case>.spec.ts` của chính case đó (hàm dùng chung thì tự mô tả bằng JSDoc trong
> `1.4.2.steps.ts` / `KHO-TAI-LIEU.functions.ts`).
>
> Lý do: 1 mục có nhiều case với logic khác nhau; nhồi logic vào đây làm file phình ra, trùng lặp và
> nhanh lạc hậu so với spec.

> **Đọc file này trước khi viết bất kỳ case nào của mục 1.4.2.**
>
> Tài liệu màn hình: `src/screen-instructions/KHO-TAI-LIEU.md` (+ `MODAL-TAO-TAI-LIEU.md`,
> `MODAL-TAO-THU-MUC.md`, `MODAL-PHAN-QUYEN-NANG-CAO.md`, `PHAN-QUYEN-THEO-VAI.md`).
> Quy ước đặt tên & cấu trúc: `CLAUDE.md`. Fixture/TIMEOUT/PW: `tests/README.md`.

> ⚠️ **Mã UC = UC23** theo xác nhận của người dùng 2026-08-04 (1.4.1 = UC22, 1.4.6 = UC25).

---

## 1. Tiền điều kiện chung của mục 1.4.2

Chưa có bản **nguyên văn QA** cho toàn mục — hiện chỉ có phần thao tác của từng case do người dùng
gửi. Bản dưới đây suy ra từ mục 1.4.1 (cùng màn, cùng nhóm vai); **thay bằng nguyên văn khi QA gửi**:

- Thủ thư / ITAdmin / Người dùng được phân quyền **tạo mới hồ sơ**: BHS ở trạng thái
  **"Khai báo"** hoặc **"Đang hoạt động"**.
- Người dùng / Nhóm được phân quyền **Owner** của Bộ hồ sơ: BHS **"Đang hoạt động"**.
- Người dùng / Nhóm được phân quyền **Tạo mới** trong Cấu trúc hồ sơ: BHS **"Đang hoạt động"**.
- Người dùng / Nhóm được phân quyền **Owner / Tạo mới tại Thư mục**: BHS **"Đang hoạt động"**.

Cách đọc tiền điều kiện: xem `CLAUDE.md` mục "Đọc tiền điều kiện của testcase QA" — vai QA ghi là
có quyền thì **mặc định làm được** tới bước Mong muốn; quyền **cấp lớn bao trùm cấp nhỏ**.

### 🚨 Hai ràng buộc bắt buộc khi dựng dữ liệu

1. **Vai không phải người tạo BHS chỉ mở được BHS ở trạng thái "Hoạt động"**
   (`KHO-TAI-LIEU.PHAN-QUYEN-THEO-VAI.md` mục 1) → phải `chuyenHoatDong` trước khi vai đó thao tác.
2. **Vai chỉ có quyền tại 1 thư mục con KHÔNG có `btn-tao-moi`** ở toolbar tab Cấu trúc hồ sơ
   (cùng tài liệu, mục 2) → vai đó chỉ tạo được tài liệu qua **menu dòng của thư mục**
   (`createTaiLieu(..., { moTuMenuDongThuMuc: true })`).

---

## 2. Bảng vai → cách script dựng dữ liệu

Dựng qua `dungDuLieuTaiLieu()` trong [`1.4.2.setup.ts`](./1.4.2.setup.ts); mỗi test **tự dựng BHS
riêng** để chạy song song được.

| Vai QA nêu                            | Fixture     | Cách dựng                                                                                              | Trạng thái BHS |
| ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ | -------------- |
| Thủ thư                               | `librarian` | Chính nó gọi `dungDuLieuTaiLieu` → tự tạo BHS nên là **Owner**                                         | `Khai báo`     |
| ITAdmin                               | `admin`     | Như trên                                                                                               | `Khai báo`     |
| Người dùng được **Owner** BHS         | `ecm05`     | người tạo dựng + `quyenBoHoSo: { permTestId: DOC_PERM.OWNER, account: "ecm05" }` + `chuyenHoatDong`     | `Hoạt động`    |
| Người dùng được **Tạo mới** BHS       | `ecm05`     | như trên với `DOC_PERM.ADD`                                                                            | `Hoạt động`    |
| **Nhóm** được Owner / Tạo mới         | `ecm06`     | như trên nhưng `account: GROUP.ECM06` (`AUTO_GROUP_ECM06`, thành viên `ecm06`), thao tác bằng `ecm06`   | `Hoạt động`    |
| Chỉ có quyền **tại 1 thư mục**        | `ecm06`     | `quyenThuMuc: { permTestId: FOLDER_PICKER.OWNER \| ADD, account }` — thư mục đó **đặt quyền độc lập** rồi cấp quyền cho vai | `Hoạt động` |

### Dữ liệu `dungDuLieuTaiLieu` tạo ra

```
BHS  AT-UC23-<maCase>-<ts>            (Owner = người gọi; + quyenBoHoSo nếu có)
 └─ AT-UC23-<maCase>-<ts>-TM1         ← thư mục ở gốc BHS (quyền ĐỘC LẬP khi có quyenThuMuc,
                                        ngược lại KẾ THỪA quyền BHS)
```

Tên 4 tài liệu (`tenTaiLieu1`…`tenTaiLieu4`) **chỉ được sinh sẵn** — việc tạo tài liệu là phần
Thao tác của case nên nằm ở [`1.4.2.steps.ts`](./1.4.2.steps.ts).

⚠️ Tên thư mục / tài liệu dùng hậu tố khác nhau và **không tên nào là tiền tố của tên khác**:
`getCauTrucRow` / `getCodeCuaItemPhanQuyen` khớp theo **chuỗi con**.

---

## 3. Danh sách case của mục 1.4.2

| Mã  | UC   | Nội dung testcase                                                                | File                                       | Trạng thái                     |
| --- | ---- | -------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------ |
| 256 | UC23 | (chưa có nội dung)                                                               | [`1.4.2.256.spec.ts`](./1.4.2.256.spec.ts) | **File rỗng** — chưa viết      |
| 261 | UC23 | Kiểm tra thêm mới tài liệu **thành công** khi nhập đầy đủ các thông tin bắt buộc  | [`1.4.2.261.spec.ts`](./1.4.2.261.spec.ts) | 1 test. Viết 2026-08-04. Chạy sitdev 2026-08-04: qua hết thao tác 1–5, fail ở thao tác 6 do **assert vị trí quá chặt của script** (đã sửa) → **cần chạy lại** |
| 397 | UC23 | Kiểm tra **upload lần đầu** với 1 file định dạng bất kỳ thỏa mãn điều kiện cho phép | [`1.4.2.397.spec.ts`](./1.4.2.397.spec.ts) | 1 test (Admin). Viết 2026-08-05. Chưa chạy |

> Viết case mới → thêm 1 dòng vào bảng này (chỉ **nội dung testcase + file + trạng thái chạy**,
> không mô tả cách làm / kỳ vọng).