水木拾光是一款面向水木社区用户的第三方水木客户端，目标是在iphone手机上提供丝滑好用的论坛体验。
扫码下载水木拾光 iPhone 版
在 App Store 打开
本文档描述产品设计、信息架构、交互方式、客户端模块划分、状态管理、缓存策略、安全与合规设计。
本文档不包含任何网络接口路径、请求参数、响应字段或协议细节。
水木社区本身是典型的 BBS 形态：版面强、帖子长、楼层关系密集、用户身份与社区语境重要。qSMTH-iOS 的设计重点不是把 BBS 改造成信息流，而是在保留论坛阅读节奏的基础上，让移动端操作更自然。
核心定位：
- 移动优先的水木社区阅读器：首页、版面、帖子详情、搜索、消息、个人页都围绕 iPhone 单手阅读与快速跳转设计。
- 轻交互社区客户端：支持登录、发帖、回复、私信、关注、收藏、拉黑、举报等常用社区动作。
- 本地体验增强层：通过本地缓存、浏览记录、收藏、版面排序、主题设置、账号切换等能力，减少重复等待和重复操作。
- 合规友好的 UGC 客户端：登录前展示用户协议与隐私政策，提供举报、拉黑、内容处理与账号信息删除入口。
非目标：
- 不提供账号注册入口。
- 不作为水木社区官方客户端陈述。
- 不在 README 中暴露底层网络协议、接口地址、请求参数或响应结构。
- 不把论坛内容改造成算法推荐流，核心仍是版面、帖子、回复和用户关系。
| 目标 | 设计含义 |
|---|---|
| 阅读效率 | 首页快速看热点，版面页快速扫列表，详情页支持楼主视角、从头看、看最新、只看某人。 |
| 操作克制 | 常用动作就近出现，危险动作使用确认，临时上下文使用 sheet，避免打断主阅读流。 |
| 移动适配 | 键盘弹出、底部浮动按钮、右滑返回、图片查看、长帖滚动都按手机手势优化。 |
| 本地优先 | 浏览历史、收藏、版面排序、账号登录信息、黑名单、缓存内容优先在本地维护。 |
| 主题一致 | 亮色、暗色、终端风格等主题通过统一语义色和组件样式驱动。 |
| 安全合规 | UGC 场景内置用户协议、隐私政策、举报、拉黑、内容屏蔽和删除本地登录信息。 |
- 已有水木账号，希望在手机上更方便地看帖、回帖、私信的用户。
- 高频浏览固定版面的用户，例如长期关注职业、生活、技术、校园等版面。
- 需要在碎片时间阅读长帖、追踪回复、切换版面的用户。
- 希望界面更现代、主题更舒适、交互更贴近 iOS 的用户。
- 看热点：打开 App 后快速进入首页十大和常用版面。
- 逛版面：在全部版面、收藏版面、搜索中找到目标版面，并进入版面时间线。
- 读长帖：在帖子详情页按不同排序查看回复，快速回到顶部或继续回复。
- 只看重点：只看楼主、只看某位用户、查看某位用户在本帖里的所有回复。
- 参与讨论：发帖、回复楼主、回复楼层、带附件、失败后保留草稿继续编辑。
- 处理关系：查看个人资料、关注、私信、拉黑、查看粉丝和关注。
- 处理消息：查看系统通知、私信会话、标记已读并继续回复。
- 管理自己：切换账号、删除本地登录信息、查看我的帖子、收藏、拉黑用户列表、设置主题。
qSMTH-iOS 使用四个主入口组织信息：
| 主入口 | 职责 | 关键页面 |
|---|---|---|
| 首页 | 展示热点内容与常用版面入口 | 热点帖子、顶部版面快捷栏、搜索入口、帖子详情 |
| 版面 | 管理收藏版面和全部版面目录 | 我的收藏版面、全部版面、版面搜索、版面时间线 |
| 消息 | 聚合站内通知和私信 | 消息列表、通知列表、会话详情、私信编辑 |
| 我的 | 管理账号、个人内容和设置 | 账号信息、账号切换、我的帖子、收藏、关注/粉丝、拉黑用户、设置 |
跨入口页面：
- 搜索页：复用同一套搜索能力，支持文章、版面、用户等不同目标；从版面入口进入时自动聚焦到版面搜索。
- 帖子详情页：从首页、版面、搜索、我的帖子、收藏、消息等场景进入。
- 用户资料页：从帖子作者、回复作者、消息联系人、关注/粉丝列表、版主列表进入。
- 设置与协议页：承载主题、字号、用户协议、隐私政策、联系我们等低频但重要功能。
首次启动展示轻量引导页，突出主题风格和基础体验。引导页同时触发首页内容预热，降低用户完成引导后看到空白或长时间 loading 的概率。
设计原则：
- 引导不承载复杂功能说明。
- 主题选择与 App 氛围前置。
- 内容预热只作为体验优化，不阻塞用户理解产品。
登录页强调“已有账号登录”，不提供注册入口。登录按钮下方展示勾选项：
我已阅读并同意《用户协议》和《隐私政策》
登录设计：
- 用户必须勾选协议后才能继续登录。
- 用户协议和隐私政策可点击查看。
- 不展示忘记密码入口，避免引导到 App 无法完整承接的账号流程。
- 登录失败时不反复弹出验证窗口，避免进入打扰循环。
- 已保存的非当前账号允许删除本地登录信息。
首页负责“快速看内容”和“快速跳到常去版面”。
页面组成：
- 顶部常用版面快捷栏。
- 当前分组标题和帖子列表。
- 下拉刷新。
- 首页浮动搜索按钮。
- 进入帖子详情、版面和用户资料的导航链路。
设计细节：
- “十大”等固定数量内容不展示“继续下拉加载更多”。
- 首页搜索按钮使用浮动入口，减少对主列表标题区域的占用。
- 浏览过的帖子进入本地历史，便于后续从“我的”找回。
全部版面页承担“找版面”和“管理收藏版面”的职责。
页面结构：
- 顶部标题为“所有版面”。
- 标题右侧提供放大镜图标，点击后从右侧进入全站搜索页，并自动定位到版面搜索。
- “我的收藏版面”和“全部版面”分区展示。
- 分区刷新按钮放在对应标题右侧，和标题形成明确关联。
交互设计：
- 页面内不常驻搜索输入框，减少列表首屏占用。
- 搜索页自动聚焦输入框，减少一次点击。
- 收藏版面优先展示，全部版面作为完整目录补充。
版面列表页展示某个版面的帖子时间线，是从版面到帖子详情的核心过渡页面。
页面设计：
- 导航标题显示版面名。
- 标题下方以 subtitle 形式展示“版主 >”入口。
- 上拉滚动时隐藏 subtitle，给内容更多空间。
- 点击“版主 >”从底部弹出 sheet，标题为“本版版主”。
- 版主列表中的用户可点击进入个人资料页。
- 如果没有版主，sheet 中显示“版主待招募”。
发帖入口：
- 版面页提供发帖入口。
- 发帖编辑器支持正文、标题、附件和发送状态。
- 发送失败后保留编辑内容，用户可以继续修改或重试。
帖子详情页是阅读和互动密度最高的页面，需要兼顾长内容、楼层关系、附件、操作菜单和回复编辑。
内容结构：
- 楼主主帖。
- 回复列表。
- 回复排序控制。
- 底部回复入口。
- 右下角回到顶部与回复浮动按钮。
回复视角：
- 看楼主：只看楼主在本帖中的内容。
- 从头看：按正序浏览回复。
- 看最新：按最新回复优先浏览。
- 只看 TA：在某条回复的更多菜单中进入，展示该作者在本帖的全部回复。
只看 TA sheet：
- 不全屏展示，使用约 75% 屏幕高度，保留当前帖子上下文。
- 顶部左侧显示“查看TA的所有回复(xx条)”。
- 顶部右侧显示关闭按钮。
- 正文是回复 ScrollView。
- sheet 内的回复卡片支持回复和更多菜单。
- sheet 内触发删除确认或回复编辑时，不收起当前 sheet。
帖子操作：
- 顶部更多菜单支持分享、删除、举报等动作。
- 回复更多菜单支持复制、回复、删除、只看 TA 等动作。
- 删除使用确认 alert，避免误操作。
- 复制通过菜单触发，不依赖长按整段选择。
附件与图片查看：
- 图片附件点击后进入大图查看。
- 大图查看支持双指缩放和双击缩放。
- 支持更自然的关闭方式，例如下滑、点击背景或保留右上角关闭按钮。
- 首次打开图片应保持适配屏幕的初始比例，不应默认放大。
底部浮动按钮：
- 回到顶部和回复按钮整体上移，避免遮挡最后一条回复的操作入口。
- 仅在有内容可操作时展示。
编辑器在发帖和回复中复用，但根据场景调整标题和默认文案。
设计要点：
- 回复楼主时标题为“回复楼主帖子”。
- 回复某条评论时保留评论上下文，但编辑体验和回复楼主一致。
- 引用内容作为引用保留，不混入用户正在编辑的正文。
- 支持附件选择。
- 支持“以图片形式发送”选项：用户正常输入文字，发送时将正文渲染为白底文字图片，并作为附件优先加入；引用仍作为引用，不放入图片。
- 如果发送失败，编辑窗口保留内容和附件状态，方便继续编辑。
消息页聚合站内通知与私信会话。
页面设计：
- 消息入口在主 Tab 中单独出现，避免埋在“我的”里。
- 列表展示消息摘要和未读状态。
- 会话详情页展示往来消息，并提供回复入口。
- 进入会话后可根据需要标记已读。
“我的”页面承担账号管理、个人内容入口和设置入口。
主要模块：
- 当前账号信息。
- 账号切换与本地登录信息管理。
- 我的帖子。
- 收藏帖子。
- 粉丝、关注。
- 拉黑用户。
- 更多 APP。
- 设置、联系我们。
设计细节：
- “拉黑用户”入口使用灰色系图标，避免和强警告态混淆。
- “更多 APP”入口位于“联系我们”下方，并在需要提示时在文字右上角显示小红点；用户点过后小红点消失。
- 非当前账号右侧提供删除按钮，用于删除本地保存的登录信息。
用户资料页展示用户身份、头像、等级、发帖活动、关注关系和私信入口。
交互设计：
- 右上角显示三点更多入口。
- 更多入口中包含拉黑选项。
- 拉黑前使用 alert 确认，提供“取消”和“拉黑”两个按钮。
- 确认文案说明拉黑后双方不能互相关注、私信、Like 和回复当前用户文章等影响。
- 已拉黑用户隐藏私信和关注入口，改为展示“已拉黑”标签。
启动 App
-> 引导页
-> 首页内容预热
-> 进入主界面
-> 需要互动时引导登录
设计理由：
- 不把登录作为进入 App 的前置条件，降低只读用户门槛。
- 互动行为再触发登录，更符合论坛浏览习惯。
- 引导页轻量，避免把产品说明做得过重。
打开登录页
-> 阅读并勾选协议
-> 输入账号密码
-> 如需安全验证，完成验证
-> 登录成功后更新账号状态与本地账号列表
失败处理：
- 密码错误或其他失败直接显示失败信息。
- 不反复弹出安全验证。
- 密码输入保持安全输入状态，避免短暂明文显示。
- 键盘弹出时布局尽量稳定，不因为输入框聚焦产生明显跳动。
首页 / 版面 / 搜索 / 我的
-> 选择帖子
-> 进入详情页
-> 读取主帖和回复
-> 切换看楼主 / 从头看 / 看最新
-> 回复、点赞、复制、分享、举报或删除
设计理由：
- 同一个帖子详情承接多入口来源。
- 排序切换是阅读意图切换，而不是进入另一个页面。
- 回复、删除、复制等局部动作放在对应楼层附近，减少手指移动。
点击回复
-> 打开回复 sheet
-> 编辑正文和附件
-> 可选以图片形式发送
-> 提交
-> 成功后按当前阅读模式刷新或定位
-> 失败则保留编辑现场
设计理由：
- 回复是临时任务，用 sheet 承载比全屏切换更轻。
- 失败后不清空内容，避免用户损失输入。
- 当前页已读到第几页时，不强行改变用户上下文；刷新策略应服务于“确认刚才的回复是否成功”。
进入用户资料页或内容菜单
-> 点击拉黑 / 举报
-> 展示确认或反馈
-> 更新本地状态
-> 立即隐藏不适合继续操作的入口
设计理由：
- UGC 客户端必须让用户能处理骚扰和不适内容。
- 拉黑是关系层面的强动作，必须确认。
- 拉黑后界面立即反馈，不等待用户重新进入页面。
qSMTH-iOS 采用 SwiftUI 为主的客户端架构，以 View、Store、Service、Persistence、Theme 分层组织。
App Entry
-> ContentView
-> LaunchIntroView
-> RootView
-> HomeView
-> AllBoardsView
-> MessagesView
-> MineView
Feature Views
-> Feature Stores / App Store
-> Data Source
-> Backend Services
-> Request Gateway
-> Network Client
Stores
-> Cache Stores
-> Session Store
-> Preference Stores
Views
-> Theme System
-> Shared Components
App 层负责生命周期、启动引导、主题注入和主导航。
ContentView：决定展示引导页还是主界面，并维护当前主题时间状态。RootView：承载四个主 Tab、主导航路径、首页浮动搜索入口和全局 toast。- App 启动时预热部分内容，降低首屏等待。
View 层负责界面结构与交互表达，不直接处理底层数据细节。
主要特征：
- 使用 SwiftUI 声明式构建。
- 复杂页面拆成多个子视图，降低单文件复杂度。
- 通过 sheet、alert、menu、toolbar、toast 等 iOS 原生交互模式组织临时任务。
- 共享组件包括头像、帖子卡片、用户行、加载视图、toast、附件选择、登录提示等。
Store 层负责页面状态、数据加载、缓存读取、错误提示和本地状态合并。
核心职责：
- 管理登录状态和账号资料。
- 管理首页分组、版面目录、帖子列表、加载更多状态。
- 管理收藏版面、收藏帖子、浏览历史、拉黑状态。
- 协调数据源请求和缓存策略。
- 在用户动作完成后触发局部刷新或缓存失效。
Store 层以 ObservableObject 驱动 SwiftUI 更新，并尽量把异步任务、加载状态和错误信息收敛在页面外部。
Service 层将业务能力抽象为清晰的客户端动作，例如：
- 获取首页和版面帖子。
- 获取帖子详情和指定视角回复。
- 登录、发帖、回复、删除、点赞。
- 获取消息与会话。
- 获取用户资料、用户动态、关注关系、版主信息。
- 搜索文章、版面、用户。
- 获取和更新收藏版面。
- 拉黑用户、关注用户。
这些能力通过统一数据源协议暴露给 Store。README 不描述任何底层网络细节，只描述业务边界。
Persistence 层用于保存本地体验状态和缓存数据。
本地持久化内容包括：
- 帖子列表缓存。
- 帖子详情缓存。
- 收藏版面缓存。
- 消息缓存。
- 版面目录缓存。
- 账号会话与账号资料缓存。
- 浏览历史与收藏帖子。
- 版面排序。
- 本地拉黑用户。
- 主题、字号、协议同意、更多 APP 提示状态等偏好。
设计原则：
- 用户隐私相关数据尽量只存在本地。
- 可恢复体验优先使用缓存展示，再后台刷新。
- 用户主动删除本地账号信息后，应清理对应本地状态。
Theme 层通过语义化 token 管理颜色、字体、形状、阴影和组件样式。
主题目标：
- 亮色、暗色、终端风格切换一致。
- alert、sheet、按钮、卡片、列表、导航栏等组件都使用主题色，而不是散落硬编码颜色。
- 文本层级明确：主文本、次级文本、弱提示、危险操作、强调色各自稳定。
- 输入、按钮边框、确认框按钮在不同主题下都有足够辨识度。
开发态提供网络调试浮层和调试状态存储，用于观察请求、错误和页面状态。调试能力只服务开发，不作为用户功能入口。
客户端以论坛核心对象为中心建模：
| 模型 | 含义 |
|---|---|
| 版面 | 论坛内容的基本组织单元，包含名称、标识、分组等信息。 |
| 帖子摘要 | 列表中展示的主题信息，包括标题、作者、回复数、附件数、时间等。 |
| 帖子详情 | 一个主题下的主帖、回复、分页和是否还有更多内容。 |
| 回复 | 楼层内容，包含作者、正文块、引用、附件、点赞、时间、状态等。 |
| 用户资料 | 用户主页展示需要的信息，包括昵称、头像、等级、积分、关注状态等。 |
| 消息 | 通知和私信摘要，以及会话中的消息项。 |
| 附件 | 图片、文件等与帖子或回复关联的内容。 |
设计重点：
- 列表模型和详情模型分离，避免列表页承担详情页负担。
- 回复内容支持文本块、图片块、引用和附件，给未来扩展留空间。
- 删除或不可见内容在最终展示阶段过滤，分页判断不依赖过滤后的显示数量。
- 用户路由使用轻量资料做预填充，进入详情后再补全。
页面统一使用以下状态表达：
idle：尚未加载。loading：正在加载。loaded：已加载成功。failed：加载失败并携带错误信息。
这样的状态模型让页面可以稳定展示骨架屏、空态、错误提示、缓存内容和重试入口。
缓存策略遵循“先可读，再更新”的原则：
- 有可用缓存时优先展示缓存。
- 缓存过期时后台刷新。
- 用户主动下拉刷新时强制更新。
- 内容变更后清理或更新相关缓存。
适合缓存的内容：
- 首页和版面帖子列表。
- 帖子详情。
- 全部版面目录。
- 收藏版面。
- 消息列表。
- 用户资料和用户动态。
远端内容与本地状态需要在展示前合并：
- 本地删除标记影响帖子列表展示。
- 本地拉黑状态影响用户资料页按钮和标签。
- 本地浏览历史影响“我的”入口。
- 本地收藏状态影响收藏按钮和收藏列表。
- 本地账号切换影响收藏版面、消息、个人资料等认证相关内容。
- 主结构使用 Tab。
- 每个主入口内部使用独立导航栈。
- 帖子、版面、用户资料、搜索等页面通过统一路由表达。
- 点击当前 Tab 时回到该 Tab 根页面。
适合使用 sheet 的场景：
- 回复编辑。
- 版主列表。
- 只看 TA。
- 点赞编辑。
- 附件选择。
- 私信编辑。
设计原则：
- sheet 承载临时上下文，不轻易打断当前阅读位置。
- sheet 内的二级动作如果仍属于当前上下文，优先在 sheet 内处理。
- 删除确认、拉黑确认等强动作使用 alert，不因为 alert 出现而收起原 sheet。
适合使用 alert 的场景：
- 拉黑用户。
- 删除帖子或回复。
- 放弃未保存编辑。
- 其他不可轻易撤销的动作。
设计原则：
- 至少包含取消选项。
- 危险按钮使用破坏性样式。
- 文案说明动作后果，而不仅写“确定吗”。
- alert 文本与按钮边界适配不同主题。
手势优先级设计：
- 列表滚动应保持最稳定。
- 图片查看允许缩放、双击缩放和轻量关闭。
- 帖子详情右滑返回不应被内部横向手势过度拦截。
- 文本选择需要通过长按触发，避免普通点击误选。
- App 不提供账号注册入口。
- 登录只面向已有水木账号。
- 保存的登录信息用于本机快捷登录和账号切换。
- 非当前账号可以在账号切换页删除本地保存信息。
- 退出或清理账号后，本地会话状态应随之更新。
- 登录前展示协议勾选项。
- 用户协议说明不容忍违法、冒犯、骚扰、辱骂、色情、仇恨、垃圾信息等内容和滥用用户。
- 隐私政策说明本地保存的信息类型和用途。
- 协议入口在登录页和设置页都可访问。
UGC 相关能力包括：
- 内容举报。
- 用户拉黑。
- 删除自己可删除的帖子或回复。
- 拉黑后即时隐藏私信和关注入口。
- 拉黑用户列表可在“我的”页面查看。
- 浏览历史、收藏、账号列表、拉黑状态等以本地体验为主。
- 不增加额外开发者服务器来收集社区内容或用户行为。
- 分享帖子时只分享公开可访问的帖子信息，不额外附加用户本地隐私数据。
错误处理设计强调“可继续”和“少损失”：
- 列表加载失败时，如果有缓存，继续显示缓存并提示刷新失败。
- 详情加载失败时，如果已有可展示内容，不清空当前阅读。
- 发帖或回复失败时保留编辑内容、附件和选项。
- 登录失败时显示明确提示，不自动重复弹出验证。
- 删除、拉黑等动作失败时保持原状态，并通过 toast 或提示文案反馈。
- 搜索无结果时展示空态，而不是空白列表。
性能策略：
- 长列表使用懒加载布局。
- 首页和引导阶段预热首屏内容。
- 帖子列表、详情、版面目录和消息使用缓存减少重复请求。
- 图片展示避免在列表中做不必要的大图加载。
- 大图查看时按展示需要加载和缩放。
- 避免在 SwiftUI
body中进行重解析、重计算或副作用操作。 - 对重复加载使用协调器或状态判断，减少同一页面重复触发任务。
基础要求：
- 主要按钮提供清晰可点区域。
- 图标按钮提供语义标签。
- 主题切换后文字对比度保持可读。
- 键盘弹出时登录页和编辑器不应遮挡主要内容。
- 危险操作的确认按钮和取消按钮边界清楚。
- 重要状态通过文字和视觉共同表达，不只依赖颜色。
建议测试重点：
- 登录页协议勾选、协议跳转、登录失败、安全验证。
- 首页、版面、搜索进入帖子详情的导航路径。
- 帖子详情的三种排序、只看 TA、删除、复制、回复。
- 只看 TA sheet 内触发回复和删除时不收起 sheet。
- 图片查看的初始尺寸、双指缩放、双击缩放、关闭手势。
- 发帖和回复失败后的草稿保留。
- 拉黑后的按钮隐藏和“已拉黑”标签。
- 主题切换后的 alert、sheet、按钮、列表和标题颜色。
- 删除本地登录信息后的账号列表更新。
开发态调试：
- 保留网络和状态调试浮层。
- 对加载状态、缓存命中、失败恢复、分页状态进行日志化。
- 对核心流程保留足够的本地可复现路径。
可演进方向：
- 更完善的离线阅读和离线收藏。
- 更细的帖子详情定位能力，例如快速跳到最后一页、跳到指定楼层。
- 更完整的附件体验，例如视频附件播放、文件预览。
- 更细粒度的屏蔽规则，例如屏蔽关键词、屏蔽版面、屏蔽用户内容。
- 更完整的辅助功能测试，包括 VoiceOver、动态字体和降低动画。
- 更稳定的系统分享卡片表现。
- 更自动化的 UI 回归测试，覆盖主题、键盘、sheet、alert 和大图查看。
| 取舍 | 选择 | 原因 |
|---|---|---|
| 注册 | 不提供注册入口 | App 无法完整承接账号创建与删除闭环，且主要用户已有水木账号。 |
| 搜索入口 | 版面页标题右侧图标进入搜索 | 减少列表首屏占用，同时保持搜索可发现。 |
| 回复编辑 | sheet 而非整页 | 回复是临时任务，sheet 更适合保留阅读上下文。 |
| 拉黑确认 | alert | 拉黑是强关系动作，需要明确后果和取消路径。 |
| 只看 TA | 75% 高度 sheet | 保留原帖上下文，同时给回复列表足够空间。 |
| 删除状态过滤 | 展示阶段过滤 | 分页和加载更多应基于原始列表判断，避免整页都是不可见内容时误判。 |
| 主题系统 | 语义 token | 降低硬编码颜色导致的暗色模式和终端风格适配问题。 |
qSMTH-iOS is a third-party iOS client for ShuiMu Community. It focuses on mobile-first forum reading, lightweight posting and messaging, local-first preferences, and safer user-generated-content workflows.
This README is a design document rather than a protocol reference. It intentionally avoids network endpoint paths, request parameters, response schemas, and other low-level integration details.
The app is organized around four main tabs:
- Home for hot topics and quick board shortcuts.
- Boards for favorite boards, the full board directory, and board search.
- Messages for notifications and private conversations.
- Mine for account state, local login records, user content, blocked users, settings, and legal pages.
The client architecture follows a SwiftUI-oriented layering model:
- Views describe screens and interactions.
- Stores coordinate loading state, local state, cache reads, and user actions.
- Services expose domain-level capabilities without leaking transport details into views.
- Persistence stores local session, cache, preferences, browsing history, favorites, and blocked users.
- A semantic theme layer keeps colors, typography, shapes, shadows, sheets, alerts, and buttons consistent across light, dark, and terminal-style themes.
The product deliberately removes account registration, requires users to agree to the Terms and Privacy Policy before login, and provides reporting, blocking, destructive-action confirmation, local account deletion, and other UGC safety measures.