@fui-org/mlis-cli 0.0.0-stage → 0.5.0

package/skills/mlis/references/viewpage-structure.md

@@ -0,0 +1,105 @@
+# Cấu trúc ViewPage và cách site chọn trang
+
+## Site chọn trang nào để hiển thị (Default.aspx.vb)
+
+1. Mỗi thư mục (category) trong /admin có trường **PageStyle** (trang của thư mục, ví dụ `LHUENB4/@HomePage`, `LHUENB4/DefaultPageCatalog`) và **PageRead** (trang dùng khi đọc tin trong thư mục, ví dụ `LHUENB4/@ReadPage`). Xem bằng `mlis category tree` / `mlis category pages <thư mục ViewPage>`.
+2. Khi mở `/<CatID>/…` site nạp `ViewPage/<PageStyle>/default.ascx`; khi đọc tin `/<CatID>/<NewsID>/…` dùng trang đọc của thư mục (PageRead). Việc chọn PageStyle/PageRead nằm trong stored procedure, CLI không đổi được — người dùng gán trong /admin → Thư mục.
+3. Khi URL là một route có tên (`/more-list/…`, `/more-news/…`, `/more-related/…`, `/search/…`, …), site nạp `ViewPage/<site>/_<tên-route>/default.ascx`, trong đó `<site>` là phần đầu của PageStyle. Ví dụ `/more-list/…` → `ViewPage/LHUENB4/_more-List/default.ascx`.
+4. Phần `<head>` luôn nạp thêm `ViewPage/<site>/_assets/HeaderOfSite.ascx`.
+5. Ảnh chia sẻ (og:image) là `ViewPage/<site>/_assets/default_image.png`, favicon là `ViewPage/<site>/_assets/favicon.ico` — phải đúng tên này (thay bằng `mlis push` như file khác, cần server đã có API `UploadFile`).
+
+Trang route `_<Tên>` không có `default.ascx`, thư mục hay tin không tồn tại → **mã 404** ngay tại URL (trang lỗi có `noindex`). Thư mục có PageStyle trỏ tới thư mục ViewPage không tồn tại → trang báo "Hệ thống không tìm thấy trang … để hiển thị". Lỗi biên dịch .ascx → chuyển tới `/error` (mã 500).
+
+## Nhiều tên miền dùng chung một hệ thống
+
+- Mọi tên miền con (tuyensinh.lhu.edu.vn, sinhvientuonglai.lhu.edu.vn…) chạy chung một site IIS, chung thư mục ViewPage. Tên miền chọn **thư mục trang chủ** của nó (thư mục có Liên kết `{ten-mien}`); site trong ViewPage là phần đầu PageStyle của thư mục trang chủ đó. Nhiều tên miền có thể dùng chung một site (ví dụ `LHUVNB4`) với trang chủ khác nhau (`LHUVNB4/@HomePage`, `LHUVNB4/SinhVienTuongLai`…).
+- Mọi thư mục mở được trên mọi tên miền (menu tên miền con có thể trỏ thư mục dùng chung). Thư mục **thuộc** tên miền nào là theo cây: tổ tiên gần nhất có Liên kết `{ten-mien}` (`mlis category show <CatID>` → `domain`). Nền tảng đặt canonical về tên miền chủ, sitemap của mỗi tên miền chỉ chứa thư mục và bài thuộc cây của nó.
+- Hệ quả khi thiết kế: control trong trang chủ của tên miền con với `CatID="0"` lấy dữ liệu của trang chủ **tên miền đó**; muốn lấy tin của thư mục dùng chung thì ghi số CatID cụ thể.
+
+## Những gì nền tảng tự làm (designer không thêm trùng)
+
+Default.aspx tự thêm vào `<head>` của mọi trang: `<title>`, `meta description`, `og:title/description/image/site_name/type/url`, `twitter:card`, `<link rel="canonical">`, JSON-LD `BreadcrumbList`; trang đọc tin thêm JSON-LD `NewsArticle` và `article:published_time/modified_time`; trang thư mục thêm `<link rel="alternate" type="application/rss+xml">`. **Không** viết các thẻ này trong HeaderOfSite hay trang ascx (sẽ trùng, sai). HeaderOfSite chỉ nên chứa css/js chung, analytics, và JSON-LD tổ chức (`CollegeOrUniversity` có `@id .../#organization` — đã có trên LHUVNB4).
+
+Các file cho máy đọc **không** nằm trong ViewPage và không cần designer: `/robots.txt` (robotsTxt.aspx), `/sitemap.xml` + `/sitemap-pages.xml` + `/sitemap-news-N.xml` (sitemapXml.aspx), `/llms.txt` (llmsTxt.aspx, tự sinh từ tên, mô tả, menu chính, tin mới của tên miền — điền "Mô tả" thư mục trong /admin để llms.txt và meta description tốt hơn), `/rss/{CatID}/…` (rssFeeds.aspx). Đừng tạo thư mục `_robots`, `_llms`… trong ViewPage.
+
+## Thư mục trong một site (ví dụ `LHUENB4/`)
+
+| Thư mục | Vai trò |
+|---|---|
+| `_assets/` | `HeaderOfSite.ascx` (thẻ `<link>`, `<script>` trong `<head>`: bootstrap/mdb, font-awesome, owlCarousel, analytics…), `default_image.png`, `favicon.ico`, định dạng chung toàn site |
+| `_default/` | `Header.ascx`, `Footer.ascx`, `StyleDefault.css`, `StyleHeaderFooter.css`, thư mục `Image/` — phần dùng chung, các trang nạp qua `LoadPage` |
+| `@HomePage/` | trang chủ |
+| `@ReadPage/`, `@ReadPageEvent/` | trang đọc tin / đọc sự kiện (dùng `NewsDetail`, `NewsOther`) |
+| `@…` khác | các trang chính riêng (landing, event, home news…) |
+| `DefaultPage*/` | bố cục chung cho thư mục: `DefaultPageCatalog`, `DefaultPage2Column`, `DefaultPage3Column`, `DefaultPageCat`… |
+| `_more-List/`, `_more-News/`, `_more-Related/`, `_Event/` | trang "xem thêm" theo route |
+| `_Search/`, `_RSS/`, `_Index/` | tìm kiếm, RSS, chỉ mục A–Z |
+| Thư mục tên riêng (`KhoaCNTT/`, `BilingualProgram/`…) | trang riêng của từng đơn vị/chuyên đề, gán qua PageStyle |
+| `_images/`, `_Images/`, `_fonts/`, `_icons/`, `_bk/` bên trong một trang | tài nguyên (hình, font) hoặc bản sao lưu của trang đó |
+
+Mỗi thư mục trang thường có `Default.ascx` (hoặc `default.ascx` — server Windows không phân biệt hoa thường) và một hay nhiều `*.css` được nạp bằng `LoadPage CssFolder`.
+
+## Quy ước đặt tên thư mục (tiền tố `_` và `@`)
+
+Tiền tố `_` có ý nghĩa thật trong code, không chỉ là thói quen:
+
+1. **Không phải là "trang" để gán cho thư mục (category).** Ô chọn *Trang chủ* (PageStyle) và *Trang đọc* (PageRead) trong /admin → Thư mục (`Admin/Controls/foldersUpdate.ascx.vb`, `SetListControl`) liệt kê các thư mục ViewPage ở cấp 2 và 3 (`<site>/<trang>`, `<site>/<trang>/<trang con>`), **bỏ qua mọi thư mục bắt đầu bằng `_`** ở bất kỳ cấp nào. Vì vậy:
+   - `_default`, `_assets`, `_images`, `_fonts`, `_bk`… là thư mục hỗ trợ (phần dùng chung, tài nguyên, sao lưu), không ai chọn nhầm làm trang được.
+   - Một site đặt tên bắt đầu bằng `_` thì toàn bộ trang bên trong bị ẩn khỏi ô chọn.
+   - Trang muốn gán cho thư mục phải **không** bắt đầu bằng `_`, nằm ở cấp 2 hoặc 3, và đường dẫn `<site>/<trang>[/<con>]` dài **không quá 50 ký tự**; sâu hơn hoặc dài hơn thì không chọn được.
+2. **Trang theo route.** `Default.aspx.vb` (`LoadUserControl`): khi URL có dạng `/<Tên>/…` (route `{PageStyle}/{*Param}` trong `Global.asax.vb`, `<Tên>` chỉ gồm chữ, số, `_`), site nạp `ViewPage/<site>/_<Tên>/default.ascx`, với `<site>` lấy từ PageStyle của trang chủ tên miền. Các route có sẵn: `/more-list/…` → `_more-List`, `/more-news/…` → `_more-News`, `/more-related/…` → `_more-Related`, `/Search/…` → `_Search`, `/Index/…` → `_Index`, `/Event/…` → `_Event`, `/RSS` → `_RSS`. Không có thư mục tương ứng → chuyển tới `/error/FileNotFound`.
+   - Muốn có trang mới theo URL riêng mà không cần tạo thư mục (category), ví dụ `https://lhu.edu.vn/LienHe`: tạo `ViewPage/<site>/_LienHe/default.ascx`. Tên sau `_` không được có dấu `-` hay khoảng trắng.
+3. **Tên cố định trong `_assets`**: `HeaderOfSite.ascx` (luôn nạp vào `<head>`), `default_image.png` (og:image), `favicon.ico`. Đổi tên là site mất phần đó.
+
+Tiền tố `@` (`@HomePage`, `@ReadPage`, `@ReadPageEvent`, `@LandingPage`…) **không** được code xử lý riêng: đó là các trang bình thường, chọn được trong PageStyle/PageRead. `@` chỉ là quy ước để các trang chính nằm đầu danh sách, tách khỏi trang bố cục `DefaultPage*` và trang riêng của đơn vị.
+
+Tóm tắt khi tạo mới:
+- Trang gán cho thư mục: `LHUENB4/TenTrang/Default.ascx` (không `_`).
+- Trang theo URL riêng: `LHUENB4/_TenRoute/default.ascx`.
+- Phần dùng chung nạp bằng `LoadPage Src`: `LHUENB4/_default/…`.
+- Hình/font của một trang: `LHUENB4/TenTrang/_images/…`, `…/_fonts/…`; link trong css bằng đường dẫn tương đối (`url(_images/bg.webp)`) hoặc `/ViewPage/LHUENB4/TenTrang/_images/bg.webp`.
+
+## File tĩnh trong ViewPage (hình, font, media, pdf)
+
+Server có API `UploadFile`/`DownloadFile` (WebApiViewPageController.vb) cho các đuôi: png, jpg, jpeg, gif, webp, svg, ico, bmp, avif, woff, woff2, ttf, otf, eot, mp4, webm, mp3, pdf — tối đa 10 MB mỗi file. `mlis pull`/`push`/`rm`/`history` xử lý chúng như file code (diff chỉ báo khác/giống). Đuôi khác (đặc biệt .aspx, .ashx, .config, .dll, .html) bị từ chối. Server chưa cập nhật API thì CLI vẫn làm được với .ascx/.css/.js và báo cần deploy khi đẩy hình.
+
+## Khung một trang
+
+```aspx
+<%@ Register TagPrefix="MLIS" Namespace="MLIS" %>
+<MLIS:LoadPage CssFolder="ViewPage/LHUENB4/@HomePage" runat="server" />
+<MLIS:LoadPage CssFolder="ViewPage/LHUENB4/_default" Src="ViewPage/LHUENB4/_default/Header.ascx" runat="server" />
+
+<div class="container">
+    <div class="row">
+        <div class="col-md-12">
+            <MLIS:CatShow CssClass="CatShow" CatFormat="<h2>{1}</h2>" runat="server" />
+        </div>
+    </div>
+    <div class="row">
+        <div class="col-md-7">
+            <MLIS:NewsList Location="2" NewsNumber="0" NewsOther="4" ViewMore="Tin khác"
+                ListFormat="<div class='NewsList'>{0}<ul class='NewsOther row'>{2}</ul><div class='view-more'>{3}</div></div>"
+                CatFormat="<h3 class='CName'><a>{1}</a></h3>"
+                OtherFormat="<li class='col-md-6'>{1}</li>"
+                runat="server" />
+        </div>
+        <div class="col-md-5">
+            <MLIS:CatShow CatFormat="<div>{2}</div><div class='CatHTML'>{5}</div>" runat="server" />
+        </div>
+    </div>
+</div>
+
+<MLIS:LoadPage Src="ViewPage/LHUENB4/_default/Footer.ascx" runat="server" />
+```
+
+- Không có `<html>`, `<head>`, `<body>`: trang là một phần của Default.aspx. Thẻ `<link>`/`<script>` chung đặt ở `_assets/HeaderOfSite.ascx`; css riêng của trang đặt trong thư mục trang để `CssFolder` nạp.
+- Giao diện dùng Bootstrap 4 (mdb) + Font Awesome 4.2 + jQuery có sẵn từ HeaderOfSite; dùng class `container`, `row`, `col-md-*`, `card`… thay vì tự viết grid.
+- Các class mà control sinh ra để định dạng: `NImg`, `NTitle`, `NTime`, `NIntro`, `NContent`, `NKey`, `NSource`, `NUpdate`, `NCounter`, `CIco`, `CPic`, `CName`, `Selected`.
+- Đường dẫn trong `Src`/`CssFolder` bắt đầu bằng `ViewPage/` (không có `/` đầu); link ảnh/css trong HTML dùng `/ViewPage/...` hoặc `/Data/...` (từ `mlis cdn upload`).
+- Không viết code server (`<% %>`, `<script runat="server">`) trừ khi người dùng yêu cầu rõ: ViewPage chỉ nên chứa markup và control MLIS.
+
+## Cache sau khi push
+
+- Khách chưa đăng nhập: HTML trang được cache trong bộ nhớ server **60 giây** (HtmlPageCache). Người có cookie `jwtAuth` (đã đăng nhập admin) luôn thấy bản mới.
+- CSS nạp qua `CssFolder` có hậu tố `?<version>` cố định theo phiên bản site — trình duyệt có thể giữ bản cũ; dùng Ctrl+F5 khi kiểm tra.