明信片接入¶
当前 UI 使用远方明信片首页、拆信、阅读、收到列表、写卡、预览和举报页面。首页进入主动收件或写卡,收到列表固定读取本人收到的卡片。各 HTTP 方法与路径的完整契约分别维护在 App 目录 和 后台目录。设计人物、照片、回信和额度不注入业务数据。
页面调用顺序与旧入口¶
| 页面 | 数据与动作 |
|---|---|
| 明信片首页 | 一次读取 GET /api/v1/me/postcards/home,包含当前偏好、上海日额度、未读与写作灵感 |
| 收一张 | 显式 POST /api/v1/postcards/receive;只有真实已通过且未被领取的首信可分配,成功后才扣一次收件额度 |
| 信封与详情 | 领取响应或 GET /api/v1/postcards/{id};拆信及已读使用 /open,GET不自动写已读 |
| 写卡与预览 | 草稿、输入和预览留在App本机,按账号和回信对象隔离;不新增草稿或预览HTTP接口 |
| 照片 | 先上传私密 postcard-photos,提交时引用同账号未到期暂存;取消时丢弃 |
| 寄出与进度 | POST /api/v1/postcards 默认待审;详情和寄出信箱恢复真实人工结果、待领取、已领取、已拆开及已有回信状态 |
| 收到列表 | GET /api/v1/me/postcards?filter=received,固定读取本人收到的卡片;旧客户端仍可使用sent/pending分类 |
| 往来 | 首信详情加 /replies?scope=published 分页;发送回信走同路径POST,作者审核结果按需用 scope=mine 读取 |
| 旅行册 | /keep PUT/DELETE;GET /api/v1/me/postcard-album 一次返回保留分页、国家、全册统计和邮戳 |
| 偏好 | /me/postcard-preferences GET/PATCH,暂停只影响新收件,不中断已有往来 |
| 直接聊天 | 收件人完成 /open 后直接POST /api/v1/postcards/{id}/chat;旧邀请端点继续兼容历史客户端 |
| 文本聊天 | 每张已拆开的首信独立会话,消息、序号分页与已读独立于回信;旧已接受邀请也可恢复 |
| 翻译与举报 | 点击后按需调用,不在首屏自动翻译、预取举报或向供应商发送待审草稿 |
旧“声音漫游/语音漫游”没有独立后端业务路径,原先复用 GET /api/v1/posts?media=voice。发现区现用独立明信片流程,不能用语音动态列表代替信箱。该动态筛选、语音投稿与播放器仍有正常用途,保持已有契约。
人工审核与私密范围¶
首信和每条回信都必须人工审核通过后才投递。 POST成功只表示已保存待审;首信作者能查自己的未通过结果,其他用户不能读取。首信通过后进入可领取池,用户主动领取时才分配唯一收件者;回信通过后才分配投递序号、增加对方未读并计入邮戳。
| 状态 | 人工动作 | 结果 |
|---|---|---|
| PENDING | APPROVE | APPROVED;首信可领取,回信实际投递 |
| PENDING | REJECT | REJECTED,非空原因只向作者及授权管理员返回 |
| APPROVED | HIDE | HIDDEN,另一方的正文、照片、回信、未读与旅行册入口同步不可见 |
| REJECTED / HIDDEN | REOPEN | PENDING,仍须再次APPROVE才恢复 |
后台首信与回信使用 kind=CARD|REPLY;决定携带当前 expectedVersion,只接受JSON非负整数。人工结论、回信投递序号和管理员审计同事务,失败整体回滚。已分配首信重新通过保留原收件者,不进入池供第二个人领取。回信重新通过分配新的递增序号,旧已读边界不自动吞掉恢复内容。
首信或回信被审核通过都不表示公开:只有实际收寄双方可读,管理员经独立Cookie和权限读取。父卡未通过、非参与者、对方账号失效、双向屏蔽均不能绕过详情、图片、翻译或邀请读取原文。本人可查自己的回信审核结果,scope=published仍只含APPROVED。人物资料的avatarId和昵称继续使用已通过公开值;头像图片按媒体请求的Bearer身份选择,本人读最新已保存绑定图,对方读已审公开图。
每日新收、新寄各3张,按数据库事务时间的 Asia/Shanghai 日期独立统计。成功提交新首信即占一次新寄名额;人工驳回不返还当日名额。回信不扣新寄额度,但每用户每小时最多60次。暂停、空池、字段失败、附件失败和回滚都不扣名额。同一成功业务键重试不重复扣;HTTP请求/JWE追踪UUID每次仍须新生成。领取按符合语言和屏蔽条件的已通过队列先后选取,未指定目标,不宣称已实现个性化推荐。
首页 Home 与偏好 Preferences¶
| 字段 | 类型与含义 |
|---|---|
| preferences | {paused:boolean,language:string,version:integer};language=any/zh/en/ja/ko,默认false/any/0;保存须完整提交三字段 |
| quota | {day:YYYY-MM-DD,timeZone:"Asia/Shanghai",limit:3,received:integer,sent:integer,receiveRemaining:integer,sendRemaining:integer};均为当天真实记录 |
| unreadReplyCount | integer;已通过、当前可见、由对方发送且超出本人已读边界的回信数量 |
| unopenedCount | integer;本人已收到且尚未明确拆开的可见首信数量 |
| inspirations | {id,title,question}[];id为breakfast/window/smallJoy,title和question按Accept-Language四语返回,未知语言英文 |
| papers | string[];固定blue/yellow/pink |
| bodyLimit / questionLimit | integer;300 / 120个UTF-16代码单元 |
| photoMaxBytes | integer;5242880输入字节 |
| translationAvailable | boolean;只表示既有供应商配置可尝试,不表示已完成真实译文验收 |
| chatMessagingAvailable | boolean;本次专属文本会话服务可用时为true,不能推断其他通用IM或WebSocket消息能力 |
| unreadChatMessageCount | integer;当前可见会话中对方超出本人明确已读边界的消息数,独立于unreadReplyCount |
首信 Card、作者 Person 与照片 Photo¶
| 字段 | 类型 / 可空 | 含义 |
|---|---|---|
| id | UUID | 服务端首信编号 |
| clientRequestId | UUID / null | 仅寄件者返回其业务幂等键 |
| direction | string | 相对本人:sent / received |
| sender / recipient | Person / Person或null | recipient在真实领取前为null;Person为{profile:PublicProfile,avatarUrl:string或null,display:ProfileDisplay} |
| originCountry / destinationCountry | string / string或null | 寄出/实际领取时服务端公开资料国家快照,用于卡片邮戳和国家筛选,不按IP猜测 |
| body / question | string | 1–300 / 0–120 UTF-16原文,保存时去首尾空白;不执行HTML |
| language | string | 作者声明的BCP47标签,最多16字符,缺省und;不按App语言猜测 |
| paper | string | blue / yellow / pink,缺省blue |
| inspirationId | string / null | 可选breakfast/window/smallJoy,与社区话题独立 |
| photo | Photo / null | 新首信必须有单图,Photo为{id:UUID,url:string,sizeBytes:integer,stagedExpiresAt:ISO8601或null};历史无图首信保留null |
| status | string | PENDING_REVIEW / REJECTED / HIDDEN / QUEUED / DELIVERED / OPENED / REPLIED;由真实审核和投递事实计算 |
| createdAt | ISO8601 | 成功提交待审时间 |
| deliveredAt / openedAt | ISO8601 / null | 首次真实领取/明确拆开时间,未发生为null |
| version | integer | 首信状态、投递、阅读、回信通过及邀请更新版本;邀请和后台审核须用最新值 |
| lastSequence / readSequence | integer | 最大已投递回信序号/本人明确读到边界,首信本身不占序号 |
| unreadReplyCount / replyCount | integer | 对方超出本人已读边界的可见回信数/当前通过回信总数 |
| kept / canReply | boolean | 本人是否保留/首信通过且已投递时可回信 |
| canInvite | boolean,非空 | 旧邀请流程的兼容能力字段;当前UI不展示该动作 |
| canChat | boolean,非空 | 父卡已通过且已投递,收件人已拆信或历史邀请已接受时为true;进入会话仍逐次复核权限 |
| invitation | Invitation | 见下方聊天邀请模型 |
| reviewStatus | string | PENDING / APPROVED / REJECTED / HIDDEN |
| reviewReason | string / null | 当前原因,仅寄件作者可读;其他参与者null |
| reviewedAt | ISO8601 / null | 最近人工审核动作时间 |
PublicProfile字段为userId UUID、publicId string、nickname string、country string、gender string、spokenLanguage string、learningLanguage string、introduction string、avatarId UUID/null、interests string[],不包含联系方式、生日或私有相册。avatarUrl复用按登录身份读取头像:本人读最新已保存绑定头像,待审或驳回仍可见;其他人只读已审公开头像,无对应引用才返回后端默认图。始终加载avatarUrl,不因公开avatarId为空而跳过,不增加作者资料读取请求。
Person.display只包含这个参与者所选国家、会的语言和学习语言,不返回完整目录。结构为{language:string,country:Country/null,spokenLanguage:Language/null,learningLanguage:Language/null};language是当前请求归一化后的zh-CN/en/ja/ko,未知回退en。Country为{id,name,names:{zh-CN,en,ja,ko},flagUrl},Language为{id,name,names:{zh-CN,en,ja,ko},nativeName},所有值复用既有所选项目录;flagUrl沿用/api/v1/media/country-flags/{countryCode}。一页参与资料先去重批量读取、最多每批100人,同选择的本地目录展示去重补齐;不逐人读取完整资料或创建访客。历史未知代码保留profile原值,对应display项为null,不猜名称。
canChat表示当前卡片可以进入专属文本会话,收件人拆信后即可为双方建立同一会话。旧canInvite仍只服务历史邀请客户端,当前UI不展示邀请入口。实际进入和发送仍复核当前卡片、账号、屏蔽和审核状态。举报首信仅允许非作者的实际收件者;举报回信必须明确同卡对方已通过replyId,不能举报本人、第三方或草稿。屏蔽使用既有用户关系接口,目标只能是真实另一方账号;未领取首信没有可屏蔽的对方。不新增含义模糊的通用canReport或canBlock字段。
回信 Reply 与分页¶
Reply为{id:UUID,cardId:UUID,clientRequestId:UUID或null,author:Person,body:string,question:string,language:string,paper:string,photo:Photo或null,sequence:integer或null,createdAt:ISO8601,reviewStatus:string,reviewReason:string或null,version:integer,reviewedAt:ISO8601或null}。正文、问题、语言、信纸和照片约束同首信;回信不接受inspirationId。作者幂等键和审核原因只向作者返回。待审回信sequence为null;通过时分配序号,下架后保留历史序号,重新通过取得新序号。
Page<T>为{items:T[],total:integer,page:integer,pageSize:integer,hasMore:boolean}。page默认1,范围1–100000;pageSize默认20,范围1–100。空页是真实空数组。信箱按真实投递/提交时间和UUID倒序;已通过回信按投递序号正序,本人提交按创建时间和UUID倒序。每种scope独立total,待审不计入对方可见数量。
旅行册 Album 与邀请 Invitation¶
Album为{cards:Page<Card>,cardCount:integer,countryCount:integer,countries:string[],stamps:{country:string,earnedAt:ISO8601}[],countryDisplays:Country[]}。cards受country筛选,cardCount/countryCount/countries始终表示本人当前可见保留全册。countryDisplays只补齐全册countries及真实stamps涉及国家的去重同源名称和flagUrl,最多300个所选代码,不下发249国完整目录;取消保留后独立邮戳仍有元数据。历史未知代码仍保留在原countries/stamps,元数据不构造假名称。国家是对方在收寄发生时的资料快照。邮戳来自本人作为收件者第一次已通过回信的真实时间,不要求保留卡片;取消保留不会删除既有往来事实。下架、屏蔽或账号清理的不可见内容不计入。
Invitation为{state:string,inviterId:UUID或null,chatUserId:UUID或null,conversationId:UUID或null}。相对本人state为NONE/OUTGOING/INCOMING/ACCEPTED/DECLINED。只有本人已有已通过回信才可发起,受邀方才能ACCEPT/DECLINE,发起者不能代替同意。ACCEPTED且首信仍可交互时返回真实对方chatUserId;新接受决定与真实空会话创建同事务,失败时状态、版本及会话一起回滚。conversationId只返回已持久化会话;历史已接受但尚未进入的记录可为空,通过明确进入会话幂等创建。邀请或打开会话不自动互关、发出欢迎消息或标记已读。
明信片文本聊天¶
聊天界面举报对方账号复用已有用户举报契约,不能把聊天messageId当作明信片replyId;首信/回信举报仍使用原私密明信片规则。屏蔽复用既有PUT /api/v1/me/blocked-users/{userId},目标必须是实际另一方;成功后本段往来对双方不可见,客户端返回列表并重读。
每张首信独立一段双方文本会话。收件人明确拆信后即可进入,旧邀请接受路径继续可用。首信与回信仍先人工审核,专属文本消息按双方同意直接持久化,不混入回信人工审核。每次读取、发送、重试和已读都复核实际双方、已通过父卡、拆信或历史接受状态、账号存活与双向屏蔽;第三方无权仅凭UUID读取,父卡下架或重审后不可继续交互。会话/消息列表及首页未读排除当前不可见项。暂停新收件不影响既有聊天。任一方注销时随父卡级联清理整个会话与正文,历史备份仍按原保留规则。
Conversation为{id:UUID,cardId:UUID,peer:Person,lastSequence:integer,readSequence:integer,unreadMessageCount:integer,lastMessage:Message/null,createdAt:ISO8601,lastActivityAt:ISO8601}。peer是真实另一方最小公开资料及所选display,lastSequence为已提交消息的最大序号;readSequence只表示本人明确已读,不返回另一方边界。未读只计对方且sequence大于本人边界的消息,自己的消息不增加本人未读,也不代替本人阅读。lastMessage在空会话为null;最后活动仅随真实消息改变,GET和阅读不改变会话排序。
Message为{id:UUID,conversationId:UUID,senderId:UUID,clientRequestId:UUID/null,mine:boolean,type:"TEXT",sequence:integer,body:string,createdAt:ISO8601}。sequence是当前会话内严格递增正整数,事务回滚不留下成功序号;clientRequestId只向原发送者返回,mine按当前Bearer计算。body为1–2000 UTF-16代码单元纯文本,去首尾空白,不执行HTML;当前接口不接受照片、语音或自报消息状态。每人每固定服务器小时最多1200条新消息。相同会话+发送者+业务UUID、同规范化正文重试返回原消息,不同正文409;成功旧键重试不重复扣额或分配序号。
MessagePage为{items:Message[],pageSize:integer,hasMore:boolean,nextBeforeSequence:integer/null,nextAfterSequence:integer,lastSequence:integer,readSequence:integer,unreadMessageCount:integer}。items始终按sequence正序;首屏取最新一页,before取更早、after取更新,两个边界互斥,每页1–100条。默认/before模式的hasMore表示还有更早项,使用nextBeforeSequence;after模式表示还有更新项,使用nextAfterSequence。nextAfterSequence来自实际返回消息,空增量保持原after,空首屏为0;lastSequence是本次读取快照的最大消息,不表示全部内容已展示。
消息成功回执表示PostgreSQL事务已持久化,不表示对方在线、送达或已读;离线后仍用相同序号分页补拉。GET不标已读,客户端仅在实际展示后提交明确边界,旧边界不吞掉并发新消息。卡片version、回信sequence与聊天sequence互相独立,不能混用。本轮使用HTTP发送及前台增量读取,不新增WebSocket聊天帧或通用IM会话;既有长连接认证/心跳协议保持。完整六个独立契约见App目录。
举报、翻译与文件¶
Receipt为{id:UUID,cardId:UUID,replyId:UUID或null,clientRequestId:UUID,reason:string,description:string,state:string,resolution:string或null,version:integer,createdAt:ISO8601,updatedAt:ISO8601}。reason为SPAM/HARASSMENT/INAPPROPRIATE/OTHER,description最多300 UTF-16,可选默认空。只能举报对方已通过内容,不可举报本人、第三方、跨卡回信或草稿。每用户每小时20次;状态RECEIVED/PROCESSING/RESOLVED/DISMISSED,只向举报者返回本人回执。后台关闭须1–500 UTF-16说明,不自动封号或下架。
Translation为{cardId:UUID,replyId:UUID或null,sourceLanguage:string,targetLanguage:string,translatedBody:string,translatedQuestion:string}。目标可省略,支持十语并按App界面语言→本人spokenLanguage→en回退,明确目标优先;见文字翻译。sourceLanguage保持原记录标签。只翻译本人可读已审原文,每用户每小时60次;正文和问题由DeepSeek同次翻译,空问题仍为空,返回前复核私密可见性。配置缺失503 TRANSLATION_UNAVAILABLE,失败503 TRANSLATION_FAILED,不返回部分成功,实际验收状态见文字翻译规则。
单图输入最多5MiB,实际解码PNG/JPEG/WebP、最长边4096且最多1600万像素;规范化为最长边1024的PNG并去元数据。每小时30次、每人最多100张有效照片,其中暂存最多20张、规范化字节合计最多200MiB。暂存24小时到期,服务器每轮最多清100张,绑定与清理互斥。照片字节由服务端私有媒体存储管理,删除元数据后通过持久任务回收对象;JSON按统一媒体协议返回地址和交付项;CDN/OSS文件连接使用各自授权,API文件连接才携带本站公共头与Bearer。私密文件不落盘,业务JSON仍为no-store。另一方不能读取待审首信或回信照片;已绑定文件不能单独丢弃。
账号注销在同一领域事务中清理涉及双方的整段明信片、回信、照片、保留和举报,再移除个人暂存、偏好和日额度;存活方旧领取幂等回执保留空卡引用,旧键重试404,不能误领另一张。数据库备份沿既有保留规则,不宣称立即清除历史备份。
后台模型与验证范围¶
ReviewItem为{id:UUID,cardId:UUID,kind:CARD或REPLY,authorId:UUID,authorNickname:string或null,recipientId:UUID或null,body:string,question:string,language:string,paper:string,photoId:UUID或null,photoUrl:string或null,reviewStatus:string,reviewReason:string或null,version:integer,createdAt:ISO8601,reviewedAt:ISO8601或null,parentBody:string或null,parentReviewStatus:string或null}。回信附原始首信正文及审核状态;后台图片用精确的管理员专用路径。ReviewPage为{items:ReviewItem[],total,page,pageSize,counts:{pending,approved,rejected,hidden}},当前类型四状态统计与本页同一快照。
后台举报详情为{report:Receipt,reporterId:UUID,target:ReviewItem};后台举报分页使用Page
2026-11-18服务器完整回归1375项,0失败/0错误,1项按环境条件跳过;新增首信照片必填、拆信后直接聊天、会话查询兼容和原邀请路径回归全部通过。完整覆盖收寄、先审后投递、照片权限、幂等、消息序号、明确已读、屏蔽、注销、OSS媒体、JWE及迁移,正向收寄和聊天写入均使用隔离数据库与合成账号。 后台网页源码与静态资产保持最新已发布版本,本次不新增后台聊天读取或管理入口。
本次首信照片必填、canChat投影和拆信后直接建会话后端扩展已通过服务器验证;旧canInvite接口仍兼容,客户端按最新UI契约接入。Flutter明信片接入由独立客户端任务推进;DeepSeek真实供应商及首信/回信翻译已在服务器隔离场景验证,范围见文字翻译规则。后端完成不等同于App整套接入或物理真机验收。
2026-11-20统一媒体交付已部署到唯一正式环境(运行配置仍为dev):已认证App成功JSON按需返回统一mediaDelivery,能力头不再选择格式,服务端决定CDN/OSS/API。业务ID和权限保持,文件通过返回的transport及授权加载;字段、缓存、单项失败与设备验收见统一媒体交付。后台网页仍使用独立管理员协议。