- BubblePilot 是面向 BlueBubbles 的自托管消息自动化、内容归档和 AI Bot 平台。
- BlueBubbles 是外部消息网关，不是工作流定义、执行历史或归档消息元数据的权威来源。
- 应用数据库是聊天、消息、Bot 事件、工作流、执行记录、凭据元数据和审计记录的权威来源。
- 首期采用模块化单体和进程内执行队列；消息队列和 Worker 边界必须通过接口隔离，以便未来演进为分布式部署。
- 在没有明确的负载或隔离需求前，不提前引入微服务、Kafka 或任意脚本运行时。
- 所有入站消息必须先转换为带版本的统一消息信封，再进行匹配和工作流执行。
- 工作流节点必须实现稳定的节点合同，并通过节点注册表注册；不要在编排控制器中堆积节点类型分支。
- 节点配置是数据，激活前必须校验；无效或停用的工作流不能接收生产消息。
- 每次执行以外部事件键和工作流版本保证幂等；重试不得产生重复出站消息。
- 执行记录和节点轨迹必须足以解释消息在哪里被接收、转换、跳过、失败或回复。
- BlueBubbles REST 和 Webhook 细节必须封装在项目自有适配器中，业务模块不能直接调用供应商 API。
- 禁止提交包含凭据的 BlueBubbles URL、密码、API Token、OpenAI Key、真实消息内容或生产数据库导出。
- 测试 Fixture 必须使用虚构对话和虚构标识。
- 归档消息属于敏感数据，默认对消息正文和凭据脱敏，不写入普通日志。
- 登录认证和敏感操作二次密码是两个独立控制项，不能只使用前端检查作为安全边界。
- 删除、批量导出、工作流激活和凭据修改必须显式授权并写入审计记录。
- 文档导航和维护规则：
doc/README.md。 - 产品范围、用户闭环、验收标准和后续方向：
doc/产品与范围.md。 - 技术栈、架构、模块依赖、数据生命周期和安全边界：
doc/技术设计.md。 - 工作流和节点合同：
doc/事件与工作流设计.md。 - BlueBubbles 行为和假设：
doc/BlueBubbles集成说明.md。 - API 和配置合同：
doc/接口与配置契约.md。 - 首次配置、生产部署、备份、升级和故障处理：
doc/部署与运维.md。 - 开发验证、迁移、分支、Commit、PR、文档和发布：
doc/开发与发布.md。 - Web 异步交互审查、停止条件和可靠性演练证据：
doc/验收与演练.md。
实现与文档不一致时，必须在同一个变更中更新对应的权威文档。
- 创建 Pull Request 前检查 Markdown 本地链接和仓库结构。
- 运行
doc/开发与发布.md中记录的验证命令。 - 任何 Schema、环境变量、认证或数据库迁移变化都必须同步文档和回归测试计划。