Machi Web 与统一 Python 后端

项目背景

Machi Web 是和 iOS App 并行的 Web 客户端，同时也承载统一后端。它不是单独的宣传页，而是实际产品系统的一部分。

技术架构

• Web：Next.js 15、React 19、TypeScript、Tailwind、Zustand、TanStack Query。
• 后端：Python 标准库单文件服务，按 REST API 暴露业务能力。
• 数据：SQLite，包含 19 张表、WAL、索引、soft delete 和 cursor 分页。
• 实时：SSE 用于私信和通知更新。
• 部署：支持 systemd、Nginx、Caddy、Amazon Linux 2023。

API 能力

统一后端覆盖 auth、users、feed、posts、comments、search、topics、notifications、messages、media、settings、devices、drafts、events、membership 和 payment 等模块。

双端同步

Web 和 iOS 可以有不同界面，但必须共享同一套数据事实。为此我在序列化层补充兼容字段，让新旧客户端都能稳定工作。

结果与复盘

这个项目训练的是端到端产品系统能力：不仅要写页面，还要处理认证、安全、数据一致性、实时事件、支付边界、双端 DTO 和部署运维。

产品判断

Machi Web 与 iOS 不需要长得一样，但必须相信同一套事实。账号、帖子、互动、私信、通知、会员和支付状态一旦分裂，产品体验就会失去信任。

技术架构

Next.js Web 客户端承载浏览和交互，Python 后端提供 80+ REST 端点和 SSE，SQLite 负责早期产品的数据真相源，Nginx 和 systemd/PM2 负责生产运行边界。

核心挑战

双端同步的关键是契约稳定。DTO 字段、分页规则、soft delete、权限判断和实时事件都要能被 Web 与 iOS 同时理解。