# Website TTHC dùng Google Sheets và Google Drive

Bộ mã hoàn chỉnh gồm Code.gs, Admin.gs, Index.html, Styles.html, App.html, Admin.html và appsscript.json.
Phần tra cứu đọc dữ liệu. Phần Admin có thể ghi vào bảng tính sau khi xác minh tài khoản quản trị; không thay đổi quyền Drive và không nhận hồ sơ cá nhân.

## 1. Nguồn dữ liệu

Đã cấu hình sẵn Google Sheets:
https://docs.google.com/spreadsheets/d/1yPpHb7N3fQyXvlcW3wYcm5ce-LQeGD6cbV4f3QI5SRM/edit

Tài khoản chạy ứng dụng phải có quyền chỉnh sửa bảng tính này. Nếu chuyển sang bảng khác, đổi CONFIG.spreadsheetId trong Code.gs. Giữ nguyên tên sheet và thứ tự cột. Không cần công khai bảng tính.

Các sheet được website sử dụng:
- Danh mục TTHC (A:Z): chỉ trả ra dòng có Trạng thái nguồn = active.
- Thành phần hồ sơ, Trình tự thực hiện, Cách nộp và thời hạn, Căn cứ pháp lý, Kết quả giải quyết, Nộp trực tuyến: liên kết bằng Mã TTHC ở cột A.
- Văn bản và biểu mẫu, Hỏi đáp, Phí lệ phí niêm yết: chỉ hiển thị dòng đánh dấu TRUE ở cột Hiển thị.
- Quyết định công bố: hiển thị các dòng trong sheet.
- Liên hệ và hướng dẫn: lấy thông tin địa chỉ, giờ làm việc và liên kết bản đồ.

Website không đọc sheet Dữ liệu gốc hay Cần rà soát. Đây là dữ liệu nghiệp vụ công khai; tránh đưa thông tin cá nhân vào các cột đang được hiển thị.

## 2. Tạo dự án Google Apps Script

1. Đăng nhập tài khoản Google sở hữu hoặc có quyền đọc bảng tính.
2. Mở https://script.google.com/home/start và tạo dự án mới; đặt tên “Sổ tay TTHC An Khánh”.
3. Thay nội dung tệp Code.gs mặc định bằng Code.gs trong bộ cài. Tạo thêm tệp Script tên Admin và dán Admin.gs.
4. Nhấn dấu + cạnh Files/Tệp, chọn HTML. Tạo lần lượt Index, Styles, App, Admin. Dán nội dung tương ứng Index.html, Styles.html, App.html, Admin.html. Google tự thêm đuôi .html; không nhập lại đuôi khi đặt tên.
5. Mở Project Settings/Cài đặt dự án, bật “Show appsscript.json manifest file in editor”. Quay lại trình biên tập, thay nội dung appsscript.json bằng tệp trong bộ cài.
6. Lưu tất cả. Chọn hàm adminPrepare và nhấn Run/Chạy.
7. Kiểm tra quyền được yêu cầu (đọc/ghi Google Sheets và nhận diện email tài khoản), chọn đúng tài khoản và cấp quyền nếu phù hợp. Nếu tài khoản cơ quan chặn Apps Script, nhờ quản trị viên hỗ trợ. Không bỏ qua cảnh báo bằng cách thay đổi chính sách bảo mật.
8. Nhật ký phải hiển thị các sheet hợp lệ và số thủ tục active. Không tiếp tục nếu thiếu sheet hoặc chưa có quyền truy cập.

## 3. Triển khai website

1. Chọn Deploy/Triển khai → New deployment/Hoạt động triển khai mới.
2. Chọn loại Web app/Ứng dụng web.
3. Execute as/Thực thi dưới dạng: Me/Tôi (tài khoản đã cấp quyền đọc/ghi).
4. Who has access/Ai có quyền truy cập: Only myself/Chỉ mình tôi để kiểm tra riêng trước. Lựa chọn có thể khác theo chính sách tài khoản.
5. Chọn Deploy, sao chép URL kết thúc bằng /exec và mở để dùng thử.
6. Kiểm tra tìm “khai sinh”, mở chi tiết, xem thành phần hồ sơ, xem căn cứ, lọc lĩnh vực và sử dụng trên điện thoại.
7. Chỉ khi đã rà soát nội dung cần công khai, đổi đối tượng truy cập phù hợp. Không cần mở quyền toàn bộ bảng tính. Bản chạy dưới quyền chủ sở hữu sẽ cung cấp các trường mà mã ứng dụng đã cho phép tới người có quyền truy cập website.

## 4. Tài liệu trên Google Drive

Tải các biểu mẫu, quyết định lên một thư mục Drive dành riêng cho tài liệu công khai. Với mỗi tệp cần cho người dân tải, đặt quyền xem phù hợp (ví dụ “bất kỳ ai có đường liên kết” khi đơn vị đã cho phép công khai), sao chép link và điền vào cột Link tài liệu trong sheet Văn bản và biểu mẫu. Không đổi quyền toàn bộ Drive hoặc thư mục chứa tài liệu nội bộ.

Cột ID thủ tục liên quan là mảng JSON, ví dụ ["dvc-1.001193"]. Cột Hiển thị đặt TRUE. Không có Link tài liệu thì website hiện “Nguồn chưa cung cấp tệp tải”. Quyền đọc bảng tính không tự cấp quyền xem tệp Drive; thử link bằng tài khoản người dùng dự kiến.

## 5. Vận hành, cập nhật

Sửa dữ liệu trong Google Sheets rồi chờ tối đa khoảng 60 giây để bộ nhớ đệm hết hạn; nhấn Làm mới trên website. Nút Làm mới đọc lại dữ liệu hiện có, không tự thu thập dữ liệu từ cổng An Khánh. Không có cơ chế đồng bộ nguồn tự động trong phiên bản này.

Khi sửa mã giao diện hoặc Code.gs, chọn Deploy → Manage deployments → Edit → New version để cập nhật cùng URL. Không cần triển khai phiên bản mới khi chỉ sửa nội dung bảng tính.

Mục yêu thích chỉ lưu trên trình duyệt, không ghi vào Drive. In thủ tục mở hộp thoại in của trình duyệt. URL nộp trực tuyến mở cổng dịch vụ công; website này không tiếp nhận hồ sơ.

## 6. Giới hạn và kiểm tra

- Phiên bản này giữ nguyên văn thông tin nguồn; chưa thẩm định độc lập hiệu lực văn bản hay thẩm quyền từng thủ tục.
- Không suy diễn ô trống hoặc giá trị 0 là miễn phí. Xem cách nộp và bảng niêm yết.
- Apps Script có hạn mức thực thi. Với nhiều lượt truy cập đồng thời cần đánh giá tải và chuyển phần phục vụ website sang hạ tầng phù hợp.
- Chức năng đọc sheet đã có kiểm thử bằng dữ liệu mô phỏng đúng cấu trúc và kiểm thử giao diện. Đã xác minh triển khai riêng tư trên tài khoản chủ dự án và đọc đủ 376 thủ tục từ Google Sheets. Đã thử tìm kiếm và đọc hồ sơ chi tiết trên bản chạy thật. Khả năng chịu tải lớn và quyền truy cập của người dùng khác chưa được kiểm thử.
- Giữ một bản sao lưu trước khi thay đổi cấu trúc sheet. Phiên bản này yêu cầu đúng tên sheet, đúng thứ tự cột như bảng đã cấu hình.

Tài liệu chính thức:
https://developers.google.com/apps-script/guides/web
https://developers.google.com/apps-script/guides/html/communication
https://developers.google.com/apps-script/guides/services/quotas

## 7. Quản trị kết hợp Google Sheets và website

Nguồn dữ liệu duy nhất là bảng tính đã cấu hình. Tài khoản levanthuykstn@gmail.com có quyền Editor trên bảng tính và được khai báo trong ADMIN_OWNERS_ ở mã máy chủ. Sheet Hướng dẫn Admin chỉ là hướng dẫn, không phải nơi tự cấp quyền.

Sau khi cài mã, cấp quyền và triển khai phiên bản mới, nút Quản trị Admin chỉ hiện khi máy chủ xác định được tài khoản hợp lệ. Email trống hoặc không có trong danh sách sẽ bị từ chối. Không dùng mật khẩu Admin tự tạo hoặc lưu mật khẩu trong sheet.

Admin hỗ trợ 12 nhóm: thủ tục, hồ sơ, trình tự, cách nộp, căn cứ, kết quả, link nộp, văn bản/biểu mẫu, phí, hỏi đáp, quyết định công bố và liên hệ. Có tìm kiếm, thêm, sửa và xem nhật ký. Tệp Drive được quản lý bằng đường dẫn HTTPS; không có chức năng tải tệp trực tiếp từ Admin. Bản ghi mới có cột Hiển thị mặc định ẩn để rà soát trước khi công bố. Không có nút xóa vĩnh viễn.

Mỗi lần lưu có kiểm tra định danh, kiểu dữ liệu, liên kết thủ tục và nội dung công thức. Thay đổi cùng nhật ký được gửi trong một batchUpdate. Khi bản ghi thay đổi từ lần mở, hệ thống từ chối lưu và yêu cầu tải lại. Cơ chế này giảm nguy cơ ghi đè; không khóa người đang sửa trực tiếp trên Sheets.

Nhật ký Admin ghi tài khoản, thời gian, bảng/dòng, trường trước và sau thay đổi. Chỉnh sửa trực tiếp trên Sheets cần kiểm tra bằng lịch sử phiên bản của Google; không tự xuất hiện trong nhật ký Admin. Người có quyền Editor cũng có thể sửa nhật ký, vì vậy đây không phải nhật ký chống can thiệp.

Quyền OAuth Google Sheets là quyền rộng theo API, dù mã ứng dụng chỉ thao tác bảng tính đã cấu hình. Hãy đọc màn hình cấp quyền trước khi đồng ý. Giữ bản triển khai Chỉ mình tôi cho đến khi rà soát đối tượng sử dụng.

Trạng thái bàn giao: mã Admin đã qua kiểm thử mô phỏng về phân quyền, lưu và nhật ký, gửi lại yêu cầu, xung đột, kiểm tra URL/ID/công thức. Chưa cài và xác minh Admin trên bản Google Apps Script đang chạy do cần khôi phục phiên đăng nhập. Bản tra cứu trước đó đã đọc được 376 thủ tục; không coi kiểm thử bản cũ là kiểm thử Admin.

## Chuyển tên đơn vị sang xã An Khánh, tỉnh Thái Nguyên
Giao diện và thông tin liên hệ đã đổi theo đơn vị mới. Dữ liệu gốc, tên văn bản pháp luật và cơ quan ban hành được bảo toàn để truy xuất nguồn; không thay tên tỉnh trong văn bản đã ban hành. Mức phí kế thừa chưa được xác nhận áp dụng tại An Khánh. Liên kết nộp hồ sơ đã bỏ bộ lọc địa bàn cũ; người dùng chọn đúng tỉnh/xã trên cổng dịch vụ công. Địa chỉ cụ thể, số điện thoại và giờ tiếp nhận cần xác minh tại cổng thông tin xã.

## Bản nâng cấp quản trị 06/11/2026

Lối vào: nút Đăng nhập / Admin trên đầu trang. Website Google có đường dẫn kết thúc /exec?page=admin để mở thẳng bảng quản trị sau khi đăng nhập Google. Không có mật khẩu riêng; tài khoản owner được kiểm tra ở máy chủ. Bản xem thử không ghi vào Google.

Nhóm Cấu hình giao diện: đổi tên, nhãn đơn vị, tiêu đề/mô tả đầu trang, chân trang, logo HTTPS, màu #RRGGBB và số dòng mỗi trang. Lưu rồi làm mới để xem. Không cho nhập HTML/CSS hoặc JavaScript tùy ý. Nhóm Liên hệ chỉnh sửa thông tin đơn vị; Nhóm Thông báo chỉnh tiêu đề, nội dung, trạng thái active.

Xác minh công khai: thêm nhóm dữ liệu (procedures, fees, publications, contact), mã bản ghi/khóa liên hệ, trạng thái verified và link căn cứ HTTPS. Hệ thống tự tạo mã, ngày và dấu kiểm dữ liệu. Mỗi bản ghi chỉ có một mục xác minh. Nếu bản ghi nguồn thay đổi thì xác minh cũ tự mất hiệu lực. Chọn pending để thu hồi công khai. Thông tin chưa xác minh hiện Đang được cập nhật.

Các bảng Chỉ dẫn cập nhật và Nhật ký phục vụ theo dõi. Không đặt quyền Admin bằng cách đổi dòng hướng dẫn. Xuất bản sao JSON gồm các bảng quản trị, không gồm dữ liệu gốc và lịch sử phiên bản Google. Khôi phục bằng Lịch sử phiên bản Google khi cần; không có nút khôi phục hàng loạt qua website. Không có chức năng tiếp nhận hồ sơ cá nhân hay xử lý hồ sơ của cổng dịch vụ công; nút nộp và phản ánh mở cổng chính thức.

Trạng thái: mã nguồn nâng cấp và cấu trúc Sheets đã chuẩn bị; kiểm thử máy chủ bằng mô phỏng và kiểm tra giao diện xem thử. Mã Apps Script đã được cài và đối chiếu sau khi nạp lại ngày 06/11/2026. Còn chấp thuận quyền Sheets/email, triển khai phiên bản và kiểm thử ghi dữ liệu trên bản thật; Google đang yêu cầu xác minh thiết bị của chủ tài khoản. Không coi bản xem thử là bản Admin ghi thật.

## Đăng nhập quản trị riêng (bản 5)
- Mở URL Apps Script hiện hành với `?page=admin`. Google chủ quản trị vẫn là lớp bảo vệ ngoài; không đổi quyền triển khai công khai.
- Lần đầu: tên gợi ý `admin` (có thể đổi khi tạo), chủ quản trị tự đặt mật khẩu ít nhất 8 ký tự, có ít nhất một chữ viết hoa và một ký tự đặc biệt và nhập lại. Không gửi mật khẩu qua chat. Sau khi tạo, đăng nhập bằng tài khoản vừa đặt.
- Mật khẩu được dẫn xuất trong trình duyệt bằng PBKDF2-SHA256, 600.000 vòng, salt riêng; máy chủ chỉ giữ bộ kiểm tra HMAC trong Script Properties. Không lưu mật khẩu hoặc khóa dẫn xuất nguyên văn trong Sheets, mã nguồn, bản sao JSON hay nhật ký.
- Phiên 30 phút, token chỉ ở bộ nhớ trang. Tải lại trang cần đăng nhập lại. Sai 5 lần trong 15 phút sẽ khóa đăng nhập 15 phút.
- Đổi mật khẩu cần mật khẩu hiện tại; đổi xong vô hiệu hóa mọi phiên cũ. Nút Đăng xuất thu hồi phiên hiện tại.
- Tài khoản này bổ sung cho chủ quản trị Google đã cho phép, chưa phải hệ thống tài khoản nhiều nhân viên hoặc đăng nhập độc lập không cần Google.
- Nếu quên mật khẩu: chủ dự án mở Cài đặt dự án > Thuộc tính tập lệnh, xóa duy nhất `ADMIN_AUTH_V1` và `ADMIN_AUTH_RATE`, mở lại trang để tự tạo lại. Không xóa các thuộc tính khác; không chia sẻ ảnh chứa thuộc tính xác thực.
- Kiểm thử tự động: `node test-auth.mjs`, `node test-admin.mjs`, `node test-backend.mjs`.

## Cấu hình website mở rộng
Sau khi đăng nhập, bấm **Giao diện website**. Có 111 cấu hình trong 10 nhóm: nhận diện, màu sắc, chữ, bố cục, giới thiệu, tra cứu/trang chủ, menu, hỗ trợ/thông báo, chân trang/liên kết, chi tiết/chia sẻ.
- Chọn thẻ có tên tiếng Việt, sửa bằng ô văn bản, chọn màu, số hoặc danh sách lựa chọn.
- **Xem thử trên trang** chỉ thay đổi trang đang mở, có thanh ghi rõ chưa lưu. Bấm **Quay lại chỉnh sửa** để trở lại dữ liệu đã lưu.
- **Dùng giá trị mặc định** chỉ điền biểu mẫu, cần bấm **Lưu thay đổi** để ghi vào Google Sheets.
- Thứ tự các khối trang chủ và menu dùng các phương án có sẵn; chưa có trình kéo thả tự do hoặc mã CSS/HTML tùy ý.
- Logo/ảnh minh họa/favicon dùng liên kết HTTPS được phép công khai; chưa tải tệp ảnh trực tiếp.
- Tiêu đề và mô tả SEO thay đổi trong trình duyệt. Google Apps Script có giới hạn việc bot tìm kiếm lấy thẻ metadata, không bảo đảm thứ hạng/ảnh xem trước của mạng xã hội.
- Giữ nguyên cơ chế Đang được cập nhật với dữ liệu chưa xác minh. Địa chỉ/giờ/biểu phí phải xác minh qua nhóm dữ liệu tương ứng.
- Các giá trị cũ được giữ lại; 101 cấu hình mới được bổ sung với mặc định. Nhật ký Admin theo dõi các lần lưu qua website.


## Nhập biểu mẫu từ Cổng DVC Quốc gia
- Chỉ liên kết khi mã trên trang chi tiết trùng mã thủ tục trong app.
- Tệp nguồn CSDL trả lỗi tải được giữ trạng thái Đang được cập nhật; app trỏ tới trang nguồn chính thức, không giả định đã lưu được Word/PDF.
- Danh mục biểu mẫu có tìm kiếm theo tên/mã thủ tục, lọc loại, phân trang 30 tài liệu/trang trong bản giao diện cập nhật.
- Nhật ký nguồn lưu tên tệp, URL tải gốc, trang thủ tục, HTTP, dung lượng, SHA-256 khi tải được và thời điểm kiểm tra.
- Không ghi ngày ban hành hoặc kết luận hiệu lực pháp lý khi nguồn chưa xác nhận. Mẫu điện tử dạng tài liệu mô tả không phải giao diện nộp hồ sơ tương tác của app.