Object Record

• Phiên bản: 1.3.0
• Ngày phát hành: 2026-10-21

Sub-agent thao tác bản ghi (record) của một Cogover Object; skill khác gọi skill này khi cần đọc/ghi record. Credential, header và quy ước response/lỗi chung: theo $cogover-api-auth. Các API record dùng /bapi/v1 với API Key Bearer; riêng upload file và gắn file vào record đã tồn tại dùng /api/v1 bằng phiên Web App (đổi từ API Key qua $cogover-api-auth; không tạo được phiên thì dừng và báo người dùng, không gọi /api/v1 bằng API Key).

Chuẩn bị

• Object ID, object_slug và fields của Object: lấy qua $object-info nếu chưa có. Với field file luôn lấy slug, fieldType và multiple từ metadata; không suy đoán từ tên hiển thị.
• Upload file/ảnh WYSIWYG: cần đường dẫn tuyệt đối tới file (tồn tại, không rỗng), metadata field đích và phiên Web App; chỉ cần ID bản ghi khi gắn vào record đã tồn tại.
• Các khả năng A–F độc lập, không cần gọi theo thứ tự.

A. Lấy danh sách — POST /bapi/v1/records/list

{
  "object_slug": "{OBJECT_SLUG}",
  "type": {TYPE},
  "logic_sequence": "{LOGIC_SEQUENCE}",
  "filters": [{FILTERS}],
  "sorts": [{"{SORT_FIELD}": {"order": "{SORT_ORDER}"}}],
  "order_direction": "next",
  "search_after": [],
  "size": {SIZE},
  "show_detail_on_record": false
}

• type (số, ở cấp cao nhất, luôn truyền tường minh, không dựa vào mặc định): 1 AND, 2 OR, 3 CUSTOM. Đã kiểm chứng: thiếu type trả HTTP 400, r: 27, msg: Invalid filter type; cùng request thêm type: 1 thành công. type khác filters[].fieldType; không sửa fieldType để chữa lỗi này.
• logic_sequence: "" khi type là 1/2; khi 3 là biểu thức như "1 AND (2 OR 3)" (số là thứ tự phần tử trong filters, bắt đầu từ 1).
• filters[]: {"field": "<slug>", "op": "<toán tử>", "params": <null | string | number | array>, "fieldType": "<fieldType từ $object-info>"}. Toán tử và kiểu params theo từng fieldType: records_filter_conditions.md; field và đường dẫn không lọc được: Trường hợp không hỗ trợ. Lấy tất cả bản ghi: {"field": "id", "op": "not null", "params": null, "fieldType": "short_text"}; lọc trạng thái: {"field": "status", "op": "in", "params": ["new", "nurturing"], "fieldType": "single_choice"}.
• sorts: field mặc định updated; order là desc (mới nhất trước) hoặc asc.
• size: mặc định 20, tối đa 100 (lớn hơn được hạ về 100); 0 chỉ trả data.total (đếm, không lấy bản ghi). Phân trang: lần đầu "search_after": [], các lần sau truyền data.search_after của response trước. Cần đếm hoặc thống kê theo nhóm thì dùng size: 0 hoặc F. Đếm và thống kê, không phân trang qua mọi bản ghi rồi tự tính.

Response: data.total (tổng bản ghi phù hợp), data.rows[] (mỗi bản ghi gồm id, name, created, updated, created_by{id,name} và các field theo Object), data.search_after (mảng, dùng cho trang tiếp); ngoài data còn personnelId, workspaceDomain, workspaceId. Giá trị trong rows:

• boolean: 0/1, không phải true/false.
• url: mảng object [{"alias": "", "url": "https://..."}], không phải mảng string.
• lookup_normal/reference: full object của bản ghi được lookup (id, name và các field khác).
• long_text: chuỗi thuần; field bật từ 2 định dạng trở lên trả chuỗi JSON "{\"text_type\":2,\"value\":\"<p>...</p>\"}" phải parse, xem Field long_text.

B. Tạo — POST /bapi/v1/records

{"object_slug": "{OBJECT_SLUG}", "data": {"{FIELD_SLUG}": {VALUE}}, "client_time_zone": "Asia/Saigon"}

data chứa các cặp field_slug: value đúng kiểu theo bảng dưới, gồm mọi field bắt buộc. Thành công: r: 0, data.id là ID bản ghi mới (dùng cho cập nhật/xoá); lỗi: r: 1 kèm msg.

Chế độ ghi write_mode (dùng cho B, C, D)

Tham số tuỳ chọn ở cấp cao nhất của body (cạnh object_slug/object_type), chữ thường; quyết định Process kích hoạt theo bản ghi chạy ngay hay chạy dần:

{"object_slug": "{OBJECT_SLUG}", "write_mode": "interactive", "data": {"{FIELD_SLUG}": {VALUE}}}

Giá trị khác trả HTTP 400, r: 100006. Phiên Web App đổi từ /bapi/v1/auth-token ghi bản ghi qua /api/v1 (như bước 5 của E) cũng mặc định import và nhận write_mode; phiên đăng nhập Web thường luôn là thao tác thường. Nhập dữ liệu từ file Excel luôn là import.

Giá trị theo kiểu trường (dùng cho B và C)

Field long_text

Lấy metaData.text_types của field qua $object-info trước khi ghi. Ba định dạng: 1 plain text, 2 rich text (HTML), 3 markdown; metaData.text_type là định dạng mặc định. Field tạo trước đây có thể không có text_types mà chỉ có text_type hoặc rich_text: "Yes": coi như bật đúng 1 định dạng.

• API không kiểm tra cấu trúc và vẫn trả r: 0 khi gửi sai: object vào field bật 1 định dạng bị lưu nguyên chuỗi JSON và UI hiển thị {"text_type":2,"value":...}; chuỗi thuần vào field bật từ 2 định dạng bị lưu thiếu text_type. Sau khi ghi phải đọc lại giá trị field, không chỉ dựa vào r: 0.
• Bỏ trống field bật từ 2 định dạng: gửi {"text_type": 1, "value": null} để đồng nhất với UI (API cũng chấp nhận null, khi đó field biến mất khỏi response). Khi đọc, coi là rỗng cả bốn trường hợp: thiếu key, null, JSON có "value": null, JSON có "value": "".
• Không ghi vào field bóng _hidden_<slug> (metadata originalId) mà hệ thống tạo kèm mỗi field long_text.

Tạo kèm file

Theo references/upload-file.md: upload riêng cho từng field đích bằng phiên Web App để lấy FILE_METADATA, rồi đưa metadata vào data của đúng một request create cùng các field thường và bắt buộc (field đơn: object, field đa: mảng). Không gọi thêm POST /api/v1/records sau khi create trả r: 0. Đọc lại record để xác minh.

Tạo kèm ảnh local trong long-text WYSIWYG

Theo references/wysiwyg-long-text-images.md: lấy ID field hệ thống _attachments và ID field WYSIWYG qua $object-info (không có _attachments thì dừng), upload ảnh bằng phiên Web App theo field ID và Object ID, rồi tạo record bằng đúng một request /bapi/v1/records với metadata ảnh trong data._attachments và HTML ảnh trong field WYSIWYG theo cấu trúc của Field long_text: chuỗi HTML khi field chỉ bật rich text, object {"text_type":2,"value":"<HTML>"} khi field bật từ 2 định dạng.

C. Cập nhật — PUT /bapi/v1/records/{RECORD_ID}

{"object_slug": "{OBJECT_SLUG}", "data": {"{FIELD_SLUG}": {VALUE}}}

data chỉ chứa các field cần cập nhật, giá trị theo bảng ở B; write_mode tuỳ chọn theo Chế độ ghi. RECORD_ID lấy từ kết quả A hoặc từ người dùng. Thành công: r: 0, data: {}. r: 1 với msg: "Record not existed": RECORD_ID sai hoặc bản ghi đã bị xoá; báo người dùng kiểm tra lại hoặc dùng A để tìm.

D. Xoá — POST /bapi/v1/records/delete

Hành động không thể hoàn tác. BẮT BUỘC liệt kê ID (và tên nếu có) các bản ghi sẽ xoá, hỏi và chỉ gọi API khi người dùng xác nhận đồng ý; người dùng từ chối thì huỷ và thông báo.

{"object_type": "{OBJECT_TYPE_ID}", "ids": ["{RECORD_ID_1}", "{RECORD_ID_2}"]}

object_type là ID của Object (ví dụ OT00000000011, lấy qua $object-info); ids nhận nhiều bản ghi cùng lúc; write_mode tuỳ chọn theo Chế độ ghi. Thành công: r: 0, data.deleted[] (đã xoá) và data.not_deleted[] (không xoá được). r: 1 với msg: "Record not existed": có ID sai hoặc đã bị xoá trước đó.

Record của Object mà backend App chuẩn duy trì số liệu (ví dụ chứng từ đang giữ chỗ ngân sách): xoá record có thể không hoàn lại số liệu backend đã cập nhật (quan sát: số giữ chỗ còn treo sau khi xoá chứng từ đang chờ duyệt). Ưu tiên huỷ, từ chối hoặc đóng bằng trạng thái/action của App; chỉ xoá khi người dùng xác nhận đã biết tác động. Hành vi từng App: $cogover-overview.

E. Gắn file vào bản ghi hiện có

Thực hiện bằng API, không dùng trình duyệt. Đọc references/upload-file.md trước khi gọi.

1. Xác định WORKSPACE_DOMAIN, OBJECT_SLUG và RECORD_ID từ URL bản ghi hoặc ngữ cảnh; xác minh file cục bộ tồn tại và không rỗng.
2. Dùng $object-info lấy OBJECT_TYPE_ID và xác minh từng field đích có fieldType=file; giữ nguyên FILE_FIELD_SLUG và cờ multiple từ metadata.
3. Tạo phiên Web App qua $cogover-api-auth cho các endpoint /api/v1.
4. Upload riêng cho từng field đích bằng POST /api/v1/file/upload/v2/client_upload; cùng một file gắn vào nhiều field vẫn cần mỗi field một request với field_slug tương ứng và một FILE_METADATA riêng. Chỉ tiếp tục khi upload trả HTTP 2xx, r: 0 và có object data.
5. Sau khi mọi upload thành công, gắn metadata bằng POST /api/v1/records; có thể gắn nhiều field trong cùng request, không tái sử dụng metadata cho field khác. Field đơn (multiple=false) gửi object, field đa (multiple=true) gửi mảng; nếu người dùng muốn thêm file mà không thay file cũ, đọc giá trị hiện tại và nối metadata mới trước khi gửi.
6. Hoàn tất chỉ khi request gắn file trả HTTP 2xx và r: 0 (kiểm tra cả body.r). Báo tên file, Object/field slug, cờ đơn/đa, ID bản ghi và kết quả từng bước.

F. Đếm và thống kê — POST /bapi/v1/records/aggregate

Đếm và tính số liệu theo nhóm trên toàn bộ bản ghi khớp bộ lọc trong một request. Cùng API Key Bearer và giới hạn tần suất như /records/list.

{
  "object_slug": "{OBJECT_SLUG}",
  "type": 1,
  "logic_sequence": "",
  "filters": [{"field": "status", "op": "in", "params": ["new"], "fieldType": "single_choice"}],
  "group_by": ["{GROUP_FIELD_SLUG}"],
  "stats": [{"type": "count"}, {"type": "sum", "field": "{NUMBER_FIELD_SLUG}"}],
  "group_limit": 1000
}

Response:

{"r":0,"msg":"OK","data":{"total":2095,"groups":[{"key":{"owner":{"id":"PER00000000003","name":"Nguyễn Văn A"}},"count":872,"sum_amount":1500000}],"truncated":false}}

• data.total: số bản ghi khớp bộ lọc trong phạm vi quyền của người gọi. Mỗi phần tử groups[] có key (slug field → giá trị), count và <type>_<field> cho mỗi chỉ số thêm (ví dụ sum_amount).
• Giá trị trong key: lookup/reference {id, name}; lựa chọn là slug option; boolean true/false; date chuỗi YYYY-MM-DD; date_time timestamp (ms); số là number; text là string, có thể trả về dạng chữ thường.
• Nhóm theo một field: bản ghi không có giá trị thành một nhóm có giá trị key là null. Nhóm theo nhiều field không có nhóm này; với field một giá trị, số bản ghi trống là total trừ tổng count.
• truncated: true khi số nhóm vượt group_limit: tăng group_limit hoặc thu hẹp bộ lọc trước khi kết luận về các nhóm nhỏ.
• Áp dụng quyền Object/record của người gọi; field bị ẩn với người gọi không dùng được trong group_by, stats, filters.
• Lỗi trả HTTP 400 với r: 80 body sai, 81 field không có hoặc không nhóm/tính được, 82 field bị ẩn với người gọi, 83 API Key không gắn nhân sự, 40 không có quyền xem Object, 1 Object không tồn tại; 14 lỗi tìm kiếm phía server (thử lại sau).

Chỉ cần tổng số thì dùng /records/list với size: 0. Báo cáo cần lưu lại, kết hợp nhiều Object hoặc dùng lại trên dashboard: dùng $report-builder.

Dữ liệu kiểm thử

Nguồn chung cho dữ liệu kiểm thử của bộ skill; skill khác chỉ ghi phần riêng.

• Tạo record test riêng, gắn marker dễ tìm trong field tìm kiếm được (ví dụ tiền tố [TEST] trong name); không chạy kịch bản thử trên record demo hoặc dữ liệu thật.
• Luồng làm thay đổi số liệu do backend duy trì (ngân sách, quỹ, công nợ, tồn kho): dùng số nhỏ và tài nguyên riêng cho test, chọn record tổng hợp ít dữ liệu thật, snapshot các record tổng hợp bị ảnh hưởng trước và sau.
• Trước khi chạy, liệt kê và hỏi người dùng về thao tác không hoàn tác được (chứng từ đã duyệt hoặc kích hoạt không huỷ được, phiếu thu chi đã hoàn thành, số liệu backend đã ghi, email hay thông báo thật, record bị Process khác cập nhật dây chuyền).
• Kết thúc chứng từ test bằng trạng thái nghiệp vụ (đóng, huỷ, từ chối), không xoá chứng từ đã giữ chỗ hoặc đã phát sinh bút toán (xem D. Xoá).
• Không sửa tay số liệu do backend hoặc module duy trì để "dọn": record tổng sẽ lệch với tổng record chi tiết còn lại (quan sát: xoá chứng từ đang chờ duyệt để lại số giữ chỗ; sửa tay làm lệch tổng). Phần dư không hoàn tác được báo người dùng kèm giá trị và record liên quan; chỉ sửa tay khi người dùng duyệt từng giá trị.
• Thử thao tác trên giao diện: layout Xem có thể tự lưu khi rời ô (inline edit); chỉ thao tác trên record test, lưu nhầm thì khôi phục qua API và báo lại.
• Persona, API key tạm và dọn dẹp sau kiểm thử quyền: theo $user-permission.

Trả kết quả

• Người dùng gọi trực tiếp: bảng hoặc danh sách dễ đọc. Danh sách: các trường quan trọng (id, name, status, created...); nhiều bản ghi thì tóm tắt và hỏi có xem thêm không. Thống kê: bảng nhóm kèm total, nêu rõ khi truncated: true. Tạo: kèm ID bản ghi mới. Xoá: nhấn mạnh bản ghi đã bị xoá vĩnh viễn. Upload: như bước 6 của E.
• Skill khác gọi: trả dữ liệu có cấu trúc để skill gọi dùng trực tiếp.

Xử lý lỗi