Machi Web 与统一后端同步指南

Machi Web 和 Machi iOS 共享同一套账号、数据库、API 和核心业务状态。Web 不是宣传页，而是产品系统的另一端：它需要承接 Feed、发帖、评论、互动、私信、通知、媒体、设置、会员和支付状态。

系统组成

• Web 客户端：Next.js 15、React 19、TypeScript、Tailwind CSS、Zustand、TanStack Query。
• 统一后端：Python 标准库服务，集中承载 REST API 与 SSE。
• 数据库：SQLite，包含 19 张业务表、索引、WAL、soft delete 和 cursor 分页。
• 实时通道：Server-Sent Events，用于通知与私信状态更新。

同步原则

后端是唯一真相源。Web 和 iOS 可以拥有不同的页面结构、组件密度和交互方式，但账号、用户、帖子、评论、点赞、收藏、转发、私信、通知、会员与支付状态必须一致。

API 契约

Machi 后端覆盖 auth、users、feed、posts、comments、search、topics、notifications、conversations、messages、media、settings、devices、drafts、events、membership 和 payment 等模块。接口返回会补充兼容字段，确保 Web 与 iOS 的 DTO 都能稳定解码。

Web 客户端策略

Web 端用 TanStack Query 管理远端请求与缓存，用 Zustand 承接轻量全局状态，用 Tailwind 对齐 iOS 视觉 token。桌面端偏三栏信息密度，移动端保留底部导航，让 Web 也有接近 App 的使用节奏。

复盘重点

双端同步最难的不是多写一个页面，而是持续维护数据契约。只要序列化字段、分页规则、删除语义、权限边界和实时事件没有统一，Web 与 iOS 很快就会变成两个彼此打架的产品。