Chuyển từ hệ khác

Các bộ văn phòng trực tuyến có nhiều khái niệm chung: cấu hình trình soạn thảo, định danh phiên bản tài liệu, callback khi lưu, dịch vụ chuyển đổi. Trang này ánh xạ các khái niệm đó sang API của O3O để việc chuyển sang O3O có lộ trình rõ ràng. Tên trường, cách ký và hành vi dưới đây là của riêng O3O.

Bảng ánh xạ khái niệm#

Khác biệt cần để ý#

• Callback chỉ có hai trạng thái, saved và closed, và gửi kèm URL tải có chữ ký. Tải tệp về trước khi URL hết hạn.
• Bộ nhận callback chỉ cần trả mã 2xx. O3O thử lại 3 lần (lần đầu, sau 10 giây, sau 60 giây), nên bộ nhận phải xử lý idempotent.
• Sau callback closed, lần mở kế tiếp phải dùng document.key mới.
• Chỉ nhận JWT HS256; thuật toán khác, kể cả none, bị từ chối.
• Chuyển đổi chỉ trong cùng một họ tài liệu (văn bản, bảng tính, trình chiếu); chế độ đồng bộ trả thẳng tệp.
• Kịch bản dựng tài liệu là JSON khai báo theo lược đồ o3oscript, không chạy mã do khách gửi.
• Phiên chỉ đọc không tính kết nối; chạm trần không ngắt ai, phiên mới mở ở chế độ chỉ đọc.

Các bước chuyển#

1. Kiểm kê

   Liệt kê nơi mở trình soạn thảo, bộ nhận callback, lời gọi chuyển đổi và kịch bản dựng tài liệu trong hệ thống hiện tại.

2. Dựng máy thử

   Chạy bản Docker theo Tự dựng máy chủ và thử trang /o3o/demo.

3. Ánh xạ cấu hình

   Dựng config O3O.Editor theo bảng trên; ký bằng JWT ở máy chủ của bạn.

4. Viết lại bộ nhận callback

   Kiểm chữ ký, xử lý idempotent, trả 2xx ngay, tải url ở nền.

5. Chuyển lời gọi xử lý tài liệu

   Chuyển đổi sang /v1/convert, dựng tài liệu sang o3oscript, trộn thư sang /v1/template/render.

6. Thử hạn mức

   Kiểm hành vi khi chạm trần bằng O3O_GATE_CONNECTION_CAP và xử lý 429 theo Hạn mức theo gói.

7. Chuyển dần

   Chạy song song hai hệ, chuyển từng phân hệ; đối chiếu tệp đã lưu trước khi tắt hệ cũ.

// Trình duyệt, sau khi nạp http://localhost:8080/o3o/api.js
const editor = new O3O.Editor("o3o-editor", {
  document: {
    url: "https://example.com/files/hop-dong.docx", // máy chủ O3O tải tệp này
    title: "Hợp đồng mẫu.docx",
    fileType: "docx",
    key: "hopdong-42-v7"                             // đổi key cho mỗi phiên bản nội dung
  },
  editor: {
    mode: "edit",
    lang: "vi",
    user: { id: "u-1001", name: "Nguyễn Văn A" },
    callbackUrl: "https://example.com/o3o/callback" // nhận saved và closed
  },
  token: tokenFromServer,                           // JWT do máy chủ của bạn ký
  events: {
    onSaved: (e) => console.log(e.version, e.url),
    onLimitReached: (e) => console.warn(e.message),
    onError: (e) => console.error(e.code, e.message)
  }
});

# Chuyển đổi đồng bộ: trả thẳng tệp PDF
curl -s http://localhost:8080/v1/convert \
  -H "Authorization: Bearer O3O_DEMO_KEY" \
  -F file=@bao-cao.docx -F to=pdf -o bao-cao.pdf

# Bất đồng bộ: nhận job, hỏi trạng thái, tải tệp
curl -s http://localhost:8080/v1/convert \
  -H "Authorization: Bearer O3O_DEMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/files/bao-cao.docx", "to": "pdf", "async": true}'
curl -s http://localhost:8080/v1/jobs/job_4f1c2a9b0d3e5f6a7b8c9d0e -H "Authorization: Bearer O3O_DEMO_KEY"
curl -s http://localhost:8080/v1/files/file_9a8b7c6d5e4f3a2b1c0d9e8f -H "Authorization: Bearer O3O_DEMO_KEY" -o bao-cao.pdf