资源 CRUD 通用参数
本文整理 collection/resource 风格接口在增删改查时常见的通用参数。接口形态通常是：
调用接口时还需要提供符合许可证要求的 Origin 或 Referer。本文的 curl 示例使用 Referer，完整规则请参考 API 请求来源与许可证校验。
例如：
/api/yiask_report:list
/api/yiask_report:get
/api/yiask_report:create
/api/yiask_report:update
/api/yiask_report:destroy
resource 不是普通 query 参数，而是资源名或集合名。:list、:get、:create、:update、:destroy 是动作名。
通用请求头
查询列表：list
用于查询多条记录，返回数组和分页信息。
示例：
curl -G 'http://localhost:13000/api/yiask_report:list' \
-H 'Authorization: Bearer <token>' \
-H 'Referer: http://localhost:13000/' \
-H 'x-spaces: sinopharm' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20' \
--data-urlencode 'sort[]=-createdAt' \
--data-urlencode 'appends[]=allowUsers'
也可以用逗号形式：
/api/yiask_report:list?page=1&pageSize=20&sort=-createdAt&fields=id,fileName,createdAt
查询单条：get
用于查询单条记录。通常通过 filterByTk 指定主键或目标键。
示例：
curl 'http://localhost:13000/api/yiask_report:get?filterByTk=123' \
-H 'Authorization: Bearer <token>' \
-H 'Referer: http://localhost:13000/' \
-H 'x-spaces: sinopharm'
带关联：
/api/yiask_report:get?filterByTk=123&appends[]=allowUsers&appends[]=session
新增：create
POST /api/{resource}:create
用于创建记录。字段值放在 JSON body 里。
示例：
curl 'http://localhost:13000/api/yiask_report:create' \
-H 'Authorization: Bearer <token>' \
-H 'Referer: http://localhost:13000/' \
-H 'x-spaces: sinopharm' \
-H 'Content-Type: application/json' \
--data '{
"fileName": "report.xlsx",
"mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"fileType": "report",
"pureMode": false
}'
只允许写入部分字段：
/api/yiask_report:create?whitelist[]=fileName&whitelist[]=mimeType
更新：update
POST /api/{resource}:update
用于更新记录。目标记录通常由 filterByTk 或 filter 指定，更新值放在 JSON body 里。
注意：更新操作至少应提供 filterByTk 或 filter 之一，否则容易变成无目标更新，通常会被框架拦截。
示例：
curl 'http://localhost:13000/api/yiask_report:update?filterByTk=123' \
-H 'Authorization: Bearer <token>' \
-H 'Referer: http://localhost:13000/' \
-H 'x-spaces: sinopharm' \
-H 'Content-Type: application/json' \
--data '{
"memo": "已确认",
"pureMode": true
}'
限制只更新 memo：
/api/yiask_report:update?filterByTk=123&whitelist[]=memo
删除：destroy
POST /api/{resource}:destroy
用于删除记录。目标记录通常由 filterByTk 或 filter 指定。
注意：删除操作至少应提供 filterByTk 或 filter 之一。批量删除可以传多个 filterByTk，具体编码方式取决于调用端。
删除单条：
curl -X POST 'http://localhost:13000/api/yiask_report:destroy?filterByTk=123' \
-H 'Authorization: Bearer <token>' \
-H 'Referer: http://localhost:13000/' \
-H 'x-spaces: sinopharm'
删除多条的一种常见写法：
/api/yiask_report:destroy?filterByTk[]=123&filterByTk[]=456
也可能使用逗号形式，是否支持要看当前资源解析逻辑：
/api/yiask_report:destroy?filterByTk=123,456
参数格式说明
sort、fields、appends、except、whitelist、blacklist 通常支持数组或逗号字符串两种形式。
数组形式：
fields[]=id&fields[]=fileName
appends[]=allowUsers
sort[]=-createdAt
逗号形式：
fields=id,fileName
appends=allowUsers
sort=-createdAt
filter 是对象参数，建议用 curl -G --data-urlencode 或客户端 SDK 传递，避免手写 URL 编码出错。
以 yiask_report 为例
yiask_report 的普通字段包括：
id
assistantMessageId
sessionId
createdAt
createdById
spaceName
relativePath
fileName
mimeType
size
memo
fileType
pureMode
可用于 appends 的关联字段包括：
createdBy
space
message
session
allowUsers
例如查询报告列表并带出可访问用户：
/api/yiask_report:list?appends[]=allowUsers&sort[]=-createdAt&page=1&pageSize=20
常见状态码判断
