外观
VMax 项目执行标准
1. 适用范围与依据
本标准适用于 VMax 的产品设计、iOS 客户端、消息服务端、协议与接口、推送网关、部署、文档、测试和发布工作。当前产品依据为 需求与技术设计/需求说明/VMax_iOS加密通信App_产品需求与技术规格说明书_v1.1.docx。原件保持只读；只有用户明确要求时才修改。
说明书中的 MUST 是首个可发布版本的验收要求，SHOULD 和 COULD 按版本规划处理，WONT 不进入当前阶段。说明书给出的推荐技术栈和密码协议组合仍须经过对应 ADR、实现可行性验证、许可证评估及独立审计；不能把建议方案写成已经验证的安全结论。后续若有获批准的新版本说明书，应同步更新本标准中的依据和冲突项。
2. 每项任务的工作顺序
- 先完整读取本标准；再按任务范围查阅说明书、相关 ADR、接口契约和现有实现。不得仅凭文件名或旧会话记忆判断当前状态。
- 明确本次目标、涉及的产品线路、版本范围、重要数据与信任边界。修改前检查 Git 状态，保留已有改动。
- 对可能影响安全、协议兼容、数据迁移、隐私或公开接口的选择，先形成可比较的方案和验证方法；需要长期生效的选择记入对应 ADR。缺少关键证据时标明待决，不擅自宣称已定案。
- 只实施本次任务所需的变更。优先保持模块边界清楚、接口可版本化、配置可替换、错误可恢复，避免为未立项功能提前建立复杂抽象。
- 根据风险验证真实行为和数据变化，并检查正常、边界、失败及重试路径。结束时说明完成内容、验证证据、未验证条件和下一步依赖。
3. 产品与版本边界
- 首版闭环是同一实例、单设备、一对一文本加密通信，以及身份创建、联系人验证、离线投递、加密备份、私有服务器配置和本地双密码入口。
- 假密码进入独立空白空间；假密码触发本地格式化是可选能力，默认关闭。
- 群聊、语音视频、多设备同时在线、跨实例联邦、公开用户目录等不属于首版；本项目当前明确不建设 Web 管理后台。后续平台和功能须独立评估协议、密钥和运维影响。
- 官方实例、普通私有实例和完全主权部署是不同部署模式。不得把依赖官方 Push Gateway 描述为完全主权；独立 APNs 模式需要独立 Bundle ID 和凭据。
4. 安全与隐私底线
- 不自行发明未经审计的密码原语或协议，不把模拟引擎、占位密文或未审计实现作为生产加密。协议版本、密码套件、规范化编码和测试向量必须明确；未知版本与不安全降级应拒绝。
- 服务端、对象存储和 Push Gateway 不接触消息明文或私钥。Push 只传最小化的无内容唤醒信息。认证使用设备签名；主密码和假密码只在本机使用，不参与服务端登录。
- 消息、私钥、备份密码、完整地址、APNs token 及可逆口令材料不得进入日志、分析、崩溃报告、诊断导出或 Git。密钥、证书和生产配置使用受控的秘密管理，不依赖
.gitignore作为唯一防线。 - 各服务器 Profile 的身份、数据库、Keychain 命名空间和通知路由必须隔离。真实空间与伪装空间不得共享可暴露真实数据的容器或模型。
- 格式化只能在用户事先启用、完成明确警告与二次确认，且精确命中假密码时触发。普通输错、Face ID 失败、取消、退后台或系统终止都不得触发。执行以销毁关键密钥为先，并验证中断恢复及残留；不得承诺 iPhone 闪存物理覆写或删除 App 外部备份。
- 安全宣传以已验证证据为依据，不使用“绝对安全”等表述。生产发布前完成说明书规定的独立密码学审计、渗透测试、隐私与合规检查。
5. 架构与通用性
- 保持 iOS 客户端、消息服务端、协议与接口、Push Gateway、部署配置之间的责任边界。客户端负责端到端加解密；消息服务端负责密文路由与短期离线投递。
- 用户本次确定的技术路线是 iOS 使用 Swift + SwiftUI、后端使用 Go + Docker、PostgreSQL 为首选持久化数据库、Redis + 队列承担缓存/限流/异步任务等职责、S3 兼容对象存储作为文件存储接口；不建设管理后台。iOS 最低系统版本、具体密码/数据库/队列/对象存储实现、依赖版本与许可仍须 ADR 和可用性验证。技术选型不自动扩大首版范围：图片、视频和附件功能依版本规划决定，Redis 不能成为密文消息的唯一持久化副本。
- OpenAPI 3.1 应成为客户端与服务端接口的共享契约。协议对象使用确定性编码与跨语言测试向量；接口、存储格式和迁移具备版本策略，不静默复用旧 Profile 或降低密码套件。
- 实例地址、品牌、保留期和部署策略通过明确配置管理；不把官方服务器、官方推送或单一云服务写死在核心业务中。保持自托管可部署、可备份、可恢复、可升级。
6. 体验与设计
- 采用 Apple 原生交互和一致的设计系统，优先保证可理解的身份验证等级、密钥变化警告、消息状态、实例归属与错误恢复。视觉效果不能遮挡这些信息。
- 同时检查深浅模式、动态字体、VoiceOver、高对比度、减少动态效果、弱网和离线状态。权限在需要时申请，并用用户能理解的语言说明原因。
- 伪装空间、通知预览、App 切后台快照及诊断界面不得暴露真实空间痕迹。安全设置必须讲清不可逆影响和能力边界。
- 参考系统设计规范，不复制其他 App 的私有动画、资源或受保护视觉资产。
- 当阶段依赖、功能范围、部署模式、数据关系或信任边界难以用简短文字看清时，提供最小而准确的路线图、功能图、关系图、模型图或架构图；不为了装饰而画图。审阅入口先呈现图和待确认问题，再提供可追溯的正文与 ADR。
7. 验证与发布
- 测试优先覆盖身份与权限、协议向量、密钥变化、消息幂等与 ACK、备份恢复、Profile 隔离、双密码路由、格式化误触与中断恢复。断网、乱序、重放、并发、磁盘满、迁移失败和 APNs 不可用属于关键故障场景。
- 断言加解密、状态、持久化和删除结果；接口成功响应本身不足以证明业务正确。对安全关键解析做长度与版本边界测试和模糊测试。
- 任何“已达到发布门槛”的结论都要有对应证据。独立审计、许可证与 SBOM、隐私清单、加密出口合规、TestFlight、备份恢复和事故响应按照说明书的硬门槛核对，未完成不得表述为已通过。
8. 文档与开源维护
- 空白 Markdown 文件只是主题占位，不代表决策已作出。只在有负责人、问题、结论或验证证据时填写；避免重复记录同一事实。
- 产品边界记录在产品文档，跨模块技术决策记录在 ADR，接口契约记录在共享规格，操作步骤记录在运维文档。变更影响这些事实时同步更新相应位置。
- 对外发布前检查历史提交、构建产物、示例配置和文档中的秘密及个人数据；确认第三方许可兼容、开源许可证、贡献与漏洞披露流程。许可决策文档存在不等于项目已取得开源许可证，只有获批并发布的 LICENSE 才能明确授权范围。
- 图示须与正文同版本维护，保留可编辑图源和本地可预览成果，并提供替代文字与正文链接。待决设计在图中显式标注，图不得把建议、模拟结果或未审计方案表现为已实现或已获安全验证。