# Kiến trúc desktop automation trong DSCons

Tài liệu này mô tả cách DSCons dùng desktop automation cho các tác vụ cục bộ trên máy người vận hành, chủ yếu với Zalo PC trên macOS. Mục tiêu là giữ phần điều phối nghiệp vụ ở DSCons, còn thao tác giao diện dễ vỡ được tách ra thành một lớp riêng, có kiểm soát và có log.

## 1. Mục tiêu và phạm vi

### Mục tiêu
- hỗ trợ các tác vụ không có API ổn định nhưng vẫn cần trong vận hành nội bộ
- tự động hóa một số bước lặp lại trên desktop như mở chat, gửi tin, tải file
- kết nối file nhận từ desktop vào workflow hồ sơ công trình của DSCons
- giữ khả năng kiểm tra lại, giới hạn rủi ro gửi sai hoặc lưu sai chỗ

### Phạm vi nên dùng
Desktop automation chỉ nên dùng cho các việc sau:
- mở Zalo PC và chọn đúng cuộc hội thoại
- gửi tin nhắn nội bộ theo workflow đã xác định
- kiểm tra chat hiện tại trước khi gửi
- phát hiện file mới trong chat, tải về và chuyển vào thư mục công trình
- chụp màn hình, OCR, tìm mục tiêu theo text khi không có API khác

### Phạm vi không nên dùng
- không thay thế toàn bộ workflow nghiệp vụ của DSCons
- không là nguồn dữ liệu chính cho knowledge trong Qdrant
- không chứa logic điều hành dự án cốt lõi
- không nên lộ các thao tác thô như click tọa độ ra API công khai nếu không thật cần

## 2. Vai trò của desktop automation trong kiến trúc DSCons

DSCons hiện có nguyên tắc tách bạch:
- PostgreSQL giữ dữ liệu vận hành
- Qdrant giữ tri thức và ngữ cảnh
- API và dashboard là lớp tiêu thụ
- agent và service là lớp điều phối

Desktop automation nên được xem là một lớp công cụ cục bộ, đứng ngoài luồng chính của FastAPI. Lớp này chỉ làm nhiệm vụ:
- thao tác với ứng dụng desktop
- trả kết quả có cấu trúc cho DSCons
- không tự quyết định nghiệp vụ
- không lưu lẫn dữ liệu vận hành và tri thức

## 3. Kiến trúc đề xuất

### 3.1 Thành phần chính

| Thành phần | Vai trò |
| --- | --- |
| Desktop automation local service | thao tác desktop trên macOS, chụp màn hình, OCR, tải file, log cục bộ |
| Adapter trong DSCons | gọi local service, chuẩn hóa timeout, retry, lỗi và log |
| Service nghiệp vụ automation | ghép nhiều thao tác desktop thành workflow an toàn cho Zalo PC |
| API nội bộ của DSCons | chỉ mở các thao tác mức cao cho người dùng nội bộ hoặc agent |

### 3.2 Nguyên tắc tách lớp
- desktop automation chạy như một tiến trình cục bộ riêng
- DSCons chỉ gọi qua adapter mỏng
- logic nghiệp vụ vẫn nằm ở service của DSCons
- các thao tác mức thấp như click, hotkey, OCR không nên phát tán ra nhiều nơi trong code
- mọi workflow gửi tin hoặc tải file đều phải có bước xác minh

## 4. Phân chia trách nhiệm

### 4.1 Lớp desktop automation local service sở hữu
- focus ứng dụng và cửa sổ
- click chuột, gõ phím, hotkey
- chụp màn hình
- OCR và tìm text trên giao diện
- phát hiện file tải về
- di chuyển hoặc đổi tên file cục bộ
- ghi log thao tác mức máy

### 4.2 DSCons sở hữu
- ý định nghiệp vụ
- xác định gửi cho ai, theo công trình nào
- kiểm tra đầu vào từ API hoặc agent
- ánh xạ file vào đúng thư mục công trình
- ghi log workflow nghiệp vụ
- quyết định có cho phép gửi hoặc tải trong từng ngữ cảnh hay không

### 4.3 Ý nghĩa của cách tách này
- giảm rủi ro làm hỏng tiến trình FastAPI chính
- dễ khoanh vùng lỗi khi UI thay đổi
- dễ thay local service mà không phải sửa toàn bộ DSCons
- giữ đúng nguyên tắc tách tri thức và dữ liệu vận hành của dự án

## 5. Luồng dữ liệu chính

### 5.1 Luồng gửi tin nhắn qua Zalo PC
1. API hoặc agent gửi yêu cầu mức cao vào DSCons
2. service nghiệp vụ kiểm tra:
   - loại đích nhận
   - tên liên hệ hoặc `My Document`
   - nội dung tin
3. adapter gọi local service để:
   - mở Zalo
   - tìm chat
   - xác minh chat đang active
   - nhập nội dung
   - gửi tin
4. local service trả về kết quả có cấu trúc:
   - trạng thái
   - tên chat thực tế
   - bằng chứng OCR hoặc screenshot nếu có
5. DSCons ghi log workflow và trả kết quả cho lớp gọi

### 5.2 Luồng nhận file từ chat và đưa vào thư mục công trình
1. DSCons nhận yêu cầu lấy file từ một chat
2. service nghiệp vụ xác định:
   - tên liên hệ
   - `project_code`
   - đường dẫn công trình đích
3. adapter gọi local service để:
   - mở đúng chat
   - xác minh chat
   - tìm file gần vùng chat mới nhất
   - bấm tải file
   - theo dõi thư mục tải về
4. local service trả về đường dẫn file tải thành công
5. DSCons chuyển file vào thư mục công trình, ví dụ `incoming/zalo/`
6. DSCons ghi log để liên kết bước nhận file với workflow hồ sơ công trình

### 5.3 Vị trí của dữ liệu sau automation
- file tải về: lưu vào thư mục dự án nội bộ
- metadata vận hành: có thể ghi vào PostgreSQL
- tri thức tài liệu sau khi ingest: mới đưa vào Qdrant
- screenshot và log cục bộ: chỉ là bằng chứng vận hành, không mặc định coi là knowledge chính thức

## 6. Công cụ mức thấp cần có

Các khả năng tối thiểu của local service:

| Nhóm | Năng lực tối thiểu |
| --- | --- |
| Điều khiển app | focus app, focus window |
| Điều khiển input | click chuột, nhập text, bấm hotkey |
| Quan sát màn hình | screenshot, OCR, tìm text mục tiêu |
| Hỗ trợ Zalo | mở chat, xác minh chat, gửi tin |
| Xử lý file | phát hiện file mới tải, di chuyển file |
| Ghi vết | log hành động, trạng thái, bằng chứng |

Nguyên tắc:
- ưu tiên tìm mục tiêu theo text thay vì phụ thuộc tuyệt đối vào tọa độ
- chỉ dùng tọa độ như phương án dự phòng
- luôn trả kết quả có cấu trúc để DSCons xử lý tiếp

## 7. API nội bộ nên mở ở mức nào

DSCons nên chỉ mở các route mức cao, ví dụ:
- gửi tin cho liên hệ
- gửi tin vào `My Document`
- xác minh chat hiện tại
- tải file mới nhất từ chat vào thư mục công trình
- kiểm tra tình trạng kết nối local service

Không nên mở trực tiếp các API như:
- click tại tọa độ bất kỳ
- gõ phím tự do không gắn workflow
- đọc màn hình toàn cục không có kiểm soát

Lý do:
- giảm rủi ro thao tác sai
- dễ audit
- nhất quán với hướng “workflow AI nghiệp vụ ngắn gọn, thực dụng, có thể kiểm chứng” trong README

## 8. Điểm nối với các luồng dữ liệu hiện có

Desktop automation không tạo thêm một luồng dữ liệu chính mới. Nó là công cụ hỗ trợ cho các luồng đã có:

| Luồng trong `workflow.md` | Vai trò của desktop automation |
| --- | --- |
| Hồ sơ công trình | nhận file từ Zalo PC và đưa vào đúng thư mục trước khi ingest |
| Manifest và gap analysis | hỗ trợ bổ sung hồ sơ còn thiếu do người vận hành yêu cầu |
| Nhật ký nhân sự | có thể ghi ai đã gửi, nhận, tải file ở thời điểm nào |
| Con người và vai trò | hỗ trợ xác định đúng người phụ trách hoặc nhóm nhận thông tin |
| Điều hành dự án | dùng cho bước giao tiếp vận hành, không thay thế nguồn trạng thái chính |

## 9. Rủi ro chính

### 9.1 Rủi ro kỹ thuật
- giao diện Zalo PC thay đổi làm hỏng kịch bản
- OCR đọc sai tên người hoặc tên file
- cửa sổ không đúng focus
- thao tác chậm hoặc timeout
- file tải chưa xong nhưng đã bị di chuyển
- quyền macOS chưa cấp đủ cho automation

### 9.2 Rủi ro vận hành
- gửi nhầm người
- gửi đúng người nhưng sai nội dung
- lưu file vào sai công trình
- nhầm bản nháp với bản ký
- log không đủ để truy vết khi có sự cố

### 9.3 Rủi ro kiến trúc
- nhúng quá nhiều logic desktop vào FastAPI
- để knowledge và log thao tác lẫn nhau
- mở API quá thấp, khó kiểm soát
- phụ thuộc vào một máy cục bộ duy nhất mà không có hướng fallback

## 10. Kiểm soát bắt buộc

### 10.1 Kiểm soát trước khi gửi tin
- phải xác minh chat đang active
- so khớp tên đích nhận theo mức cho phép
- lưu bằng chứng text hoặc screenshot nếu cần
- chặn gửi nếu không xác minh được

### 10.2 Kiểm soát khi tải file
- xác minh đúng chat trước khi tải
- theo dõi file đến khi tải xong hoàn toàn
- chuẩn hóa thư mục đích theo công trình
- ghi lại `source_path` và `destination_path`

### 10.3 Kiểm soát quyền và môi trường
Trên macOS cần kiểm tra:
- Accessibility permission
- Screen Recording permission
- quyền đọc/ghi thư mục Downloads
- quyền đọc/ghi thư mục dự án

### 10.4 Kiểm soát log và truy vết
Mỗi workflow nên có tối thiểu:
- thời gian
- tên action
- trạng thái
- đích nhận
- `project_code` nếu có
- bằng chứng xác minh
- đường dẫn file nguồn và đích nếu có lỗi hoặc tải file

## 11. Nguyên tắc dữ liệu và audit

Desktop automation phải tuân theo các nguyên tắc chung của DSCons:
- không coi dữ liệu desktop là nguồn chân lý duy nhất
- mọi file nhận được cần đi qua bước phân loại và ingest riêng
- không đẩy screenshot hoặc OCR thô vào Qdrant một cách mặc định
- nếu cần lưu vận hành, ưu tiên lưu metadata vào PostgreSQL
- workflow phải rerunnable ở mức hợp lý và có giới hạn retry

## 12. Lộ trình triển khai gọn

### Giai đoạn 1 - Nền tảng tối thiểu
- dựng local service cho macOS
- có các thao tác: focus, hotkey, nhập text, screenshot, OCR, tìm text
- có log cục bộ

### Giai đoạn 2 - Workflow Zalo an toàn
- mở chat theo tên
- xác minh chat
- gửi tin nhắn mức cao
- chặn gửi nếu xác minh thất bại

### Giai đoạn 3 - Nhận file
- phát hiện file trong chat
- tải file mới nhất
- chuyển vào thư mục công trình
- ghi log đầu cuối

### Giai đoạn 4 - Gắn vào DSCons
- thêm adapter
- thêm service nghiệp vụ
- thêm API nội bộ mức cao
- sau đó mới cân nhắc cho agent gọi như một công cụ

## 13. Kết luận

Hướng phù hợp cho DSCons là:
- giữ desktop automation ở một local service riêng
- để DSCons làm lớp điều phối nghiệp vụ và kiểm soát
- chỉ mở workflow mức cao, không khuyến khích lộ thao tác thô
- bắt buộc có xác minh và log cho mọi bước gửi tin hoặc tải file

Cách này phù hợp với kiến trúc hiện tại của DSCons:
- tách bạch knowledge và operational data
- ưu tiên workflow rõ ràng, kiểm chứng được
- giảm tác động của phần UI automation vốn dễ vỡ lên hệ thống chính