互动与审核接入¶
App 单接口见 App 目录,管理员单接口见 后台目录。本页定义共享字段和业务流程,不替代各接口的请求契约。
动态、评论和公开资料中的作者昵称、avatarId、签名统一读取已通过资料,不公开本人待审/驳回草稿;avatarUrl的图片按下述Bearer查看身份选择。动态正文通过不等于作者新资料也通过。
审核与可见性¶
头像统一读取响应中的avatarUrl,业务身份仍以/api/v1/media/user-avatars/{userId}表示;真实加载地址与授权由统一mediaDelivery返回,不能假定avatarUrl始终是API相对路径。后台按当前查看者身份选择本人最新已保存绑定头像或他人最后审核通过头像;本人待审/驳回图不因此公开。各自没有对应引用时才返回API默认PNG,上传未保存不生效。公开资料avatarId仍只表示已审引用,客户端直接加载后台URL,私密鉴权交由公共加载组件;CDN/OSS不附带本站Bearer。原准入与双向屏蔽保持,媒体不可用时URL为null,缓存不得绕过当前权限。
动态、一级评论和二级回复默认 PENDING。话题配置保存即生效。动态、评论和回复的 POST 成功表示已保存并等待审核,客户端只能在本人内容中显示待审状态;不能把提交结果直接插入公开信息流或公开评论数。
| 当前状态 | 管理动作 | 新状态 | 规则 |
|---|---|---|---|
| PENDING | APPROVE | APPROVED | 明确人工通过;音视频动态额外确认已预览媒体 |
| PENDING | REJECT | REJECTED | reason 必须非空 |
| APPROVED | HIDE | HIDDEN | reason 必须非空,公开入口立即排除 |
| REJECTED / HIDDEN | REOPEN | PENDING | 重新送审不直接恢复公开 |
动态、评论和回复的审核携带 expectedVersion,只接受 JSON 非负整数;旧版本返回 409 POST_REVIEW_CONFLICT,客户端重新读取并让管理员核对,不能自动覆盖。审核和管理员审计在同一事务;审计只保存动作、对象和状态版本摘要。动态另有最近 50 条审核轨迹和完整轨迹数量。评论审批要求父动态、根评论及直接回复目标已审核且未删除。话题更新使用同一版本保护但保存后立即生效。
公开列表、他人详情、图片、视频、封面、语音、点赞、评论、翻译、举报目标均检查审核和删除状态、作者账号有效性及双向屏蔽。作者能查看自己的待审、驳回和下架动态及其媒体,但也不能点赞、评论、举报或翻译未通过内容。管理员使用独立 Cookie、CSRF、权限及 HTTPS;App Bearer 不能代替管理员身份。
删除动态立即移除正文和媒体引用、清空审核原因并保留幂等墓碑;删除评论清空正文,根或回复目标删除后相关回复不再公开。注销通过领域事务清理帖子、评论、举报、话题关系和文件,物理媒体由持久化删除队列重试。备份按既有保留策略处理,不宣称即时擦除备份。
UI 调用顺序¶
- 互动入口读取
community/catalog,世界流读取posts?feed=world,关注页读取feed=following;正常动态语音筛选使用media=voice。发现区原声音漫游已替换为独立远方明信片,不再把动态语音列表作为明信片收寄接口。世界流按publishedAt DESC,id DESC排序,是最近审核通过内容,不宣称个性化算法推荐。关注流包含真实已关注作者及本人已审核动态。 - 同频入口使用
interest=travel|cafe|language:旅行和语言匹配已生效话题分类;咖啡匹配cafe、coffee已生效话题。media=image包含 TEXT 和 IMAGE,video / voice 只含对应类型;筛选可组合。话题页使用topicId。 - 发布正文最多 1000 UTF-16 代码单元,话题 0–2 个。纯文本、最多 9 张图片、一个视频、一段语音互斥,纯媒体可空正文;文本和媒体不能同时为空。原文语言可选,不传为
und,不根据界面语言猜测。 - 图片、音视频先上传为私有暂存,拿到真实 ID 后提交动态。客户端草稿和录音 UI 状态留在本机;取消时调用对应暂存丢弃接口。一次投稿沿用同一
clientRequestId核实重试,但每次 HTTP/JWE 的X-Request-Id必须新生成。 - 评论根列表与根下回复分别分页。
commentPreview最多三条已审核根评论,commentCount是当前Bearer可见的根评论与回复完整总数:公开可见已审记录,加本人仍可回显的未公开记录。本人审核进度通过该动态的comments/mine查询。
“仅本人可见”中的本人是评论或回复的作者,动态发布者也没有查看他人未通过评论的特权。公开评论列表、二级回复、commentPreview及replyCount只采用已通过且仍可见的内容,自己的未通过记录也不混入公开列表或分页total。Post.commentCount按下文当前查看者规则计算。本人未通过正文和审核原因仅通过该动态的comments/mine恢复,作者身份取当前Bearer,不提供指定其他userId读取的能力;翻译或举报不能借已知UUID绕过审核。驳回、下架或重新送审后继续只供本人回查,授权管理员仍可通过独立后台权限审核。 6. 关注、取消关注、屏蔽和用户头像继续复用 关系接口,以服务器返回状态为准。 7. 举报截图使用 EVIDENCE 私有用途上传,提交后显示真实回执;处理举报不会自动下架内容或封号,管理员需要另行明确审核动作。
动态 Post¶
| 字段 | 类型 / 可空 | 含义 |
|---|---|---|
| id | UUID | 服务端动态 ID |
| clientRequestId | UUID / null | 仅作者返回,其他人 null |
| author | PublicProfile | userId UUID、publicId string、nickname string、country string、gender string、spokenLanguage string、learningLanguage string、introduction string、avatarId UUID/null、interests string[];不含联系方式、生日或私有相册 |
| avatarUrl | string或null | 统一交付后的加载地址;本人取已保存绑定图,他人取已审图,无引用时使用API默认图;无权或媒体故障为null,按mediaDelivery处理 |
| content | string | 最多 1000 UTF-16 原文,纯媒体可空,不作 HTML 执行 |
| photos | Photo[] | 0–9 张;id UUID、url string、sizeBytes 整数字节,按选择顺序 |
| kind | string | TEXT / IMAGE / VIDEO / VOICE,由服务器实际附件决定 |
| language | string | 原文语言标签,缺省 und |
| media | File / null | 视频或语音;与 photos 互斥 |
| topics | Tag[] | 当前已生效的话题配置;id string、title 当前界面语言 string、iconKey string;不返回未计算的参与数 |
| likeCount | integer | 持久化点赞数量 |
| liked / canDelete / following / vipActive | boolean | 本人点赞、本人可删、真实关注、作者实际有效 VIP 权益;不从渠道准入开关伪造 VIP |
| commentCount | integer | 当前Bearer可见的完整根评论与回复总数:公开可见APPROVED记录,加本人未删除的PENDING/REJECTED/HIDDEN回显记录,按评论ID去重 |
| commentPreview | Comment[] | 最多 3 条已审核根评论 |
| reviewStatus | string | PENDING / APPROVED / REJECTED / HIDDEN |
| reviewReason | string / null | 仅作者在 REJECTED / HIDDEN 时返回,其余 null |
| version | integer | 审核和删除共同递增版本 |
| createdAt | ISO8601 string | 首次提交时间 |
| reviewedAt / publishedAt | ISO8601 string / null | 最近审核动作 / 当前通过时间;未通过的 publishedAt 为 null |
PostPage 为 {items:Post[],total:integer,page:integer,pageSize:integer,hasMore:boolean}。page 默认 1、范围 1–100000;pageSize 默认 20、范围 1–100。本人和点赞列表按提交时间倒序;发现列表按审核通过时间倒序。空数组是真实无记录,不补设计数据。
我的点赞列表使用 LikedPostPage:{items:Post[],total:integer,allTotal:integer,page:integer,pageSize:integer,hasMore:boolean}。原五个分页字段保持,新增非空非负64位整数 allTotal;其他动态分页仍为 PostPage。可选 media=all|image|video|voice,省略或空值为 all,image 包含 TEXT 与 IMAGE,video/voice 各自只含对应类型,非法小写枚举以外的值400。SQL先分类再分页,排序保持 createdAt DESC,id DESC。total 与 hasMore 只属于当前分类,allTotal 不受分类及页码影响,复用 /api/v1/me/home.summary.likedPostsCount 的本人点赞、已通过、未删除、有效且已完成资料作者、双向屏蔽过滤;两种总数与 items 保持同一只读快照。空分类或超过末页不将 allTotal 清零。顶部总数直接采用 allTotal,各分类分别分页,不拉全量本地筛选。
Post.commentCount由服务端在同一读取快照计算完整总数,不受评论页数、pageSize、commentPreview长度或本机已加载数量影响。本人待审1条时本人看到1、他人看到0;通过后双方看到1,本人数值不重复增加;删除后移除。公开部分继续校验父动态、根/目标、作者账号、双向屏蔽和删除状态;本人补充部分只采用comments/mine中可回显的未删除未公开记录。根/目标失效不恢复其原文、昵称或已通过子回复;本人原本仍可回查的未公开提交继续只计本人。父动态未公开时只有有权读取的作者可获得自己的未公开计数,不计不可读的公开线程;父动态删除或对查看者不可见仍返回404。详情、发现/关注、用户动态、本人动态、点赞列表及返回Post的写回执共用该语义。Flutter直接展示此字段,提交或删除成功后重新读取现有动态详情更新;不本地加减、不用items.length或comments/mine.total叠加。
评论 Comment¶
| 字段 | 类型 / 可空 | 含义 |
|---|---|---|
| id / postId | UUID | 评论及所属动态 |
| clientRequestId | UUID / null | 仅本人返回 |
| author / avatarUrl | PublicProfile / string或null | 同Post的公开资料与统一媒体地址,媒体不可用时地址为null |
| content | string | 1–300 UTF-16 代码单元 |
| language | string | 声明原文语言,未知 und |
| rootId / replyTo | UUID / null | 根评论二者为 null;二级回复指向根及直接目标,回复另一条回复仍为二级 |
| replyToNickname | string / null | 当前可见回复目标的真实昵称,目标不可见则 null |
| replyCount | integer | 根评论下可见二级回复数,二级回复为 0 |
| canDelete | boolean | 仅作者为 true |
| vipActive | boolean | 本条评论/回复作者当前有效VIP权益,非空;未开通、未生效、过期或撤销为false,与查看者、动态作者及渠道准入开关无关;dev非prod沿用管理员测试覆盖 |
| reviewStatus / reviewReason | string / string 或 null | 审核状态;原因只返回本人 |
| version | integer | 审核/删除版本 |
| createdAt / reviewedAt | ISO8601 / ISO8601 或 null | 提交与最近审核时间 |
CommentPage 为 {items:Comment[],total,page,pageSize,hasMore},分页约束同 PostPage。total 指当前层级:无 rootId 为根评论数量,带 rootId 为该根下回复数量。按 createdAt ASC,id ASC 排序。本人提交列表按时间倒序,只列本人在指定动态下未删除的提交,包含已通过与待审/驳回/下架;不混入公开列表。
评论顶层vipActive覆盖一级、二级、comments/mine、POST提交与幂等回执,以及动态详情/发现/关注/用户动态/本人动态/点赞列表中的commentPreview。它表示读取时评论作者的有效权益,不固定为投稿时状态,不放入author对象,不借用外层动态的vipActive。评论页按去重作者一次批量读取,同一动态页的全部评论预览合并后批量读取;会员依赖失败返回503而非false,提交回执失败会回滚本次评论。Flutter仅按此布尔值渲染边框、昵称颜色和VIP图标,无需逐人补查;审核、屏蔽、删除和本人可见性继续按本文规则,VIP本身不参与计数。
投稿每用户每小时20次,评论/回复共60次,举报20次,点赞/取消点赞共240次;业务幂等重试使用同一clientRequestId,原请求已成功时不重复创建内容。超限返回AUTH_RATE_LIMITED,入口秒级限流另行生效。
文件 File¶
| 字段 | 类型 / 可空 | 含义 |
|---|---|---|
| id | UUID | 服务端文件 ID |
| kind | string | VIDEO / VOICE / EVIDENCE |
| url | string或null | 服务端生成的CDN/OSS/API地址,加载权限见统一mediaDelivery;不可用时为null |
| posterUrl | string / null | 已保存的视频PNG封面;旧视频、本地无截帧模式、语音和证据可为null |
| contentType | string | video/mp4、audio/mp4 或 image/png |
| sizeBytes / durationMillis | integer | 实际存储字节/客户端声明时长毫秒,证据为规范化图片字节且时长0 |
| width / height | integer | 证据为规范化后实际像素,视频和语音当前为0 |
| stagedExpiresAt | ISO8601 / null | 未绑定暂存到期时间,绑定后 null |
动态图单图最多 20MiB,PNG/JPEG/WebP,最长边 4096、像素数不超过 1600 万;规范化到最长边 1024 的 PNG 并去元数据,保持既有独立图片路径。图上传每小时 30 次,最多 30 暂存、300 有效图片。
音视频保留原始文件,不执行转码或可信时长/视频尺寸探测;durationMillis仍由客户端声明,width、height保持0。OSS新视频在上传确认中提取0毫秒画面,真实解码并保存规范化PNG封面;客户端只上传视频和元信息,不上传首帧。原列表/详情的media.posterUrl、本人主页recentPosts缩略索引及后台审核均引用已保存封面,不在列表请求中重新截帧。封面与视频同事务、同审核/屏蔽权限及删除队列;OSS公开交付仍只发布已审视频封面。旧视频或本地模式可为null,VOICE/EVIDENCE没有封面。确认失败与编码范围见上传确认,上传成功不表示内容审核通过。
EVIDENCE 输入最多 5MiB,PNG/JPEG/WebP,规范化图片后仅供本人和管理员读取。每份举报最多三张,不能绑定为动态。通用文件每小时 20 次,最多 10 个暂存、单用户总规范化文件最多 1GiB;未绑定文件 24 小时到期,后台每轮有界回收。绑定和过期清理使用行锁,已绑定文件不按暂存时限删除。
视频/语音原文件 GET 支持单一字节 Range,多范围或无效范围为 416,不是成功 JSON;封面与举报证据返回 PNG 资源。请求仍带认证和公共头;后台文件 GET 仅精确路径豁免 JWE。所有文件 Cache-Control:no-store。上传网络超时未拿到 ID 时不要伪造媒体已成功,可重新上传,旧暂存按规则回收。
话题与目录¶
| 模型 | 字段 |
|---|---|
| Topic | id 稳定 string;category 为 daily/travel/food/language/hobbies;title/hint 为当前界面语言 string;iconKey 已知素材键 string;featured boolean;postCount / participantCount 非负整数,仅统计已审核且当前可见的动态/去重作者 |
| TopicPage | items:Topic[]、total、page、pageSize、hasMore;featured 优先,再 sortOrder、id;q 按四语标题/ID字面搜索,最多80 UTF-16 |
| Catalog | categories:{id,name}[] 五类;interests:{id,name}[] 三类;dailyTopic:Topic/null;topicLimit=2、contentLimit=1000、commentLimit=300;translationAvailable boolean 仅表示配置可尝试,非供应商已验收 |
| TopicDetail(后台) | id、category、titles 与 hints 四语 string map(准确键 zh-CN/en/ja/ko);iconKey;featured;sortOrder;reviewStatus兼容字段(当前为APPROVED);reviewReason兼容字段(当前为null);version;createdAt、updatedAt |
当前 100 个 UI 话题作为已生效初始配置提供给App。后台话题配置页复用这100个UI话题的左侧图片,保存后的四语内容、分类、排序和今日话题设置立即生效。选中的文件以稳定iconKey保存,图片随管理网页静态资源发布,服务端不保存图片URL。标题每语最多60、引导每语最多200 UTF-16,均非空;未知界面语言回退英文。历史审核字段保留兼容读取;旧审核地址返回405,不能再下架或重新送审话题。V39保留已有正文与素材,将所有旧状态转为已生效并递增受影响版本;今日话题优先保留原本已公开的一项,否则按sortOrder、id选取一个候选,其余取消featured。保存时检查唯一今日话题,冲突返回TOPIC_FEATURED_CONFLICT;重复代码或旧版本返回TOPIC_CONFIGURATION_CONFLICT。切换今日话题先保存旧项featured=false,再保存新项featured=true。
举报与翻译¶
Receipt 保留id UUID、clientRequestId UUID、reason枚举SPAM/INAPPROPRIATE/HARASSMENT/OTHER、description string(0–300 UTF-16)、state枚举RECEIVED/PROCESSING/RESOLVED/DISMISSED、resolution string/null(最多500)、version非负long、createdAt/updatedAt ISO8601,并新增非空targetType=POST/COMMENT/USER及targetUserId UUID/null。POST时postId为真实动态、commentId与targetUserId为空;COMMENT时postId及commentId为真实内容、targetUserId为空;USER时targetUserId为真实用户,postId及commentId均null,不借动态ID表示用户。ReportPage为items:Receipt[]、total、page、pageSize、hasMore,按提交时间及UUID倒序。管理员ReportDetail为{report:Receipt,reporterId:UUID,evidence:File[],targetUser:Author/null,reporter:Author/null};后台evidence.url为独立受权地址。两个Author沿用后台当前账号最小投影:id UUID、publicId string、nickname string/null、status ACTIVE/DISABLED/DELETED、avatarId UUID/null、gender string/null、country string/null,不含联系方式、生日或介绍。targetUser按USER本人、POST作者、COMMENT作者解析,评论不回退父动态作者;资料缺失为null。按页去重、每批最多100人读取,不创建访客、不使用App公开已审资料回填后台候选。App Receipt及ReportPage不增加参与人字段,私有举报仍不向被举报者公开。
用户举报复用同一私有收件及证据事务。App及后台既有举报列表增加scope=CONTENT/USER/ALL,默认CONTENT仅动态与评论以兼容旧客户端;新版后台显式ALL,App需要用户/混合回执时显式USER/ALL。按回执ID读取仍只限本人或授权后台,不受列表scope限制。新建用户举报只允许正常可见或我方已屏蔽的有效目标,对方单独屏蔽或不可用统一404;回执幂等重试不再次检验目标可见性。所有三类共用举报者幂等键及每小时20次新收件额度;相同规范化内容重试原回执,不同类型、目标、原因、说明或有序证据409 POST_REVIEW_CONFLICT。原内容举报摘要不变。V41只追加独立用户目标列及互斥约束,旧记录不改写;注销先将举报者或用户目标相关证据加入清理队列,再清除相应举报。
举报收件可以进入 PROCESSING 或直接 RESOLVED/DISMISSED;处理中可以进入两种终态。终态不允许覆盖;仅RESOLVED处理完成必须有非空说明,DISMISSED驳回无需理由,resolution可为空字符串,不伪造默认说明;旧客户端显式提交的可选说明继续保留。App 只能查询本人回执,目标下架后仍可查处理进度。举报不自动触发处罚。
Translation 为 {postId:UUID,commentId:UUID/null,sourceLanguage:string,targetLanguage:string,translatedText:string}。目标支持资料目录十语,省略、null或空白按原始App界面语言→本人spokenLanguage→en回退,显式目标优先;规范值和地区变体见文字翻译规则。sourceLanguage仍为原记录标签,可为und或其他合法BCP47标签。每人每小时60次,原文只取已审可见记录。译文按普通文本渲染,不覆盖原文、不生成公开动态,也不宣称已人工审核。
已部署DeepSeek官方deepseek-flash非思考模式,语言决策、上下文、结构校验、失败及当前验收范围统一见文字翻译规则。配置缺失503 TRANSLATION_UNAVAILABLE,供应商网络、格式、超时或超限503 TRANSLATION_FAILED;客户端保留原文和重试入口,仅主动点击时翻译。返回前复核来源,不返回已删除/下架内容的旧译文。
后台审核模型¶
AdminPostItem:id UUID,author {id:UUID,publicId:string,nickname:string/null,status:string,avatarId:UUID/null,gender:male/female/null,country:string/null},excerpt string(最多120代码点),photoCount integer,likeCount integer,reviewStatus string,version integer,createdAt ISO8601,reviewedAt/deletedAt ISO8601/null,kind TEXT/IMAGE/VIDEO/VOICE。
后台author新增头像、性别和资料国家:与账号后台一致,avatarId为当前已保存头像引用、gender用于无头像时显示既有默认素材、country为资料中设置的国家代码;缺失返回null,不按IP推断。管理员投影允许查看当前候选头像,不表示其已通过公开审核;App公开资料的avatarId与昵称仍只取已通过值,头像媒体按本文Bearer查看身份选择。列表按本页去重作者一次批量补齐,不逐条请求用户详情;详情及审核返回保持相同author结构。头像文件复用后台用户头像读取及其独立读取权限、Cookie、公共头和PNG约束,JSON不携带图片字节或外部URL。
AdminPostDetail:post:AdminPostItem,content:string,reason:string,photos:{id,position,sizeBytes}[],history:Review[](最近50条倒序),historyTotal:integer,media:File/null(后台读取地址),topics:Tag[](仍已审核标签),language:string。
Review:id UUID,fromStatus/toStatus string,version integer,reason string,reviewerId UUID,reviewerName string,createdAt ISO8601。真实管理员由会话提供,客户端不可指定。已删除帖子正文、图片和原因清除,详情只留墓碑及无正文的轨迹。
Counts:total、pending、approved、rejected、hidden、deleted 均为非负整数;前四个状态之和等于 total(未删除),deleted 另计。
AdminCommentDetail:id/postId/userId UUID,content/language string,rootId/replyTo UUID/null,reviewStatus string,reviewReason string/null,version integer,createdAt ISO8601、reviewedAt/deletedAt ISO8601/null。 增加author与replyToAuthor,两者为{id:UUID,publicId:string,nickname:string/null,status:string,avatarId:UUID/null,gender:string/null,country:string/null}或null。author为当前评论作者的后台资料,replyToAuthor为直接replyTo目标的作者;rootId为null时是评论动态,非空时为回复,回复另一条回复也不改用根作者。当前昵称/头像可含已保存待审值,仅授权后台可读,不扩展App公开投影。缺失资料保留null,国家不按IP或头像推断;同页去重后每批最多100名作者,最大100行及100个直接目标共最多两批,不逐行读取用户详情。列表、详情及审核回执保持同一结构,回执资料读取失败会回滚本次审核和成功审计。
后台分页统一 {items:对应模型[],total:integer,page:integer,pageSize:integer},没有 hasMore;页数与大小约束同 App。动态按创建时间倒序,评论和举报队列按创建时间正序;后台话题按updatedAt倒序、id排序。后台写权限 ADMIN_POSTS_WRITE 只赋予 OWNER,VIEWER 只有 ADMIN_POSTS_READ。菜单可见不等于写授权。
验证范围¶
2026-11-17服务器完整回归及两组修正模拟后的定向复跑汇总1374项,零失败/错误、1项真实翻译条件跳过;新增10项首帧专项覆盖固定OSS参数、流关闭/大小限制、400/503、真实PNG规范化、幂等、失败回滚与重试、列表/主页、审核/屏蔽和删除。其他完整回归报告逐份保留核对,既有动态/评论/点赞分类、分页、VIP及权限继续覆盖。Mac真实30fps H.264视频直传OSS,确认后保存起始画面PNG,重复确认、本人待审动态列表/主页、下载授权、旧相对路径、无签名拒绝及注销清理11项通过;视频、封面与本次暂存键均确认404,合成账号正常注销,不批准或修改其他运行内容。API经保留系统CA与主机名校验的SSH域名TLS转发,OSS PUT/GET由Mac直连;尚未逐个发现/关注等入口重复真实视频验收,各列表共用Post投影。公网备案链路、Flutter实际页面与物理设备仍按各自任务验收,真实编码覆盖不扩大至任意格式。
管理员删除已通过动态¶
后台使用独立DELETE /api/v1/admin/posts/{id}与必填expectedVersion,只允许未删除APPROVED目标及ADMIN_POSTS_WRITE。删除与作者入口共用清理事务,递增审核版本和deletedAt墓碑,清正文/原因/点赞/媒体及话题引用,字节经持久队列回收;最小POST_DELETE管理员审计同事务。审核四态保持,删除不伪装HIDE或第五态;旧版本、其他状态或重复删除409,App父动态权限立即拒绝。成功刷新列表/统计,未知结果先只读核对;完整请求、错误、清理边界及实际验证以独立契约为准。
2026-11-20统一媒体交付已部署到唯一正式环境(运行配置仍为dev):已认证App成功JSON按需返回统一mediaDelivery,能力头不再选择格式,服务端决定CDN/OSS/API。业务ID和权限保持,文件通过返回的transport及授权加载;字段、缓存、单项失败与设备验收见统一媒体交付。后台网页仍使用独立管理员协议。