package com.gzzm.lobster.storage;

/**
 * ContentStore —— 统一大载荷文件存储接口 / Unified large-payload file store.
 *
 * <p>Artifact 正文、超长 tool result、工坊编辑状态、超长消息等外置到此。
 * 路径规范（推荐）：{@code {category}/{yyyy}/{MM}/{dd}/{userId}/{uuid}.{ext}}。
 *
 * <p>Backend holds: artifact bodies, oversize tool results, workshop editor
 * state, oversize messages. Path convention:
 * {@code {category}/{yyyy}/{MM}/{dd}/{userId}/{uuid}.{ext}}.
 */
public interface ContentStore {

    /** 写入内容，返回 content_ref / Write and return the content reference. */
    String write(String category, String userId, String content, String format);

    /** 写入二进制 / Write raw bytes. */
    String writeBinary(String category, String userId, byte[] bytes, String format);

    /** 读取全部内容 / Read full content. */
    String read(String contentRef);

    /** 分段读取（字符为单位）/ Paginated read (by char). */
    String read(String contentRef, int offset, int limit);

    /** 读取字节 / Read raw bytes. */
    byte[] readBinary(String contentRef);

    /** 分段读取字节 / Paginated read (by byte). limit &lt;= 0 表示读到末尾. */
    byte[] readBinary(String contentRef, int offset, int limit);

    /** 删除内容 / Delete content. */
    void delete(String contentRef);

    /** 获取大小 / Size in bytes. */
    long getSize(String contentRef);

    /** 是否存在 / Exists? */
    boolean exists(String contentRef);
}