OpenFlare/docs/design/development.md

开发约束

OpenFlare 1.0.0 之后的开发优先关注稳定性、升级与回滚链路可靠性、文档准确性、测试覆盖补强，以及既有边界内的小步迭代。

变更准入

新需求进入实现前，按以下顺序判断：

1. 是否符合产品边界。
2. 是否符合后端、Agent 与前端开发规范。
3. 是否会破坏发布、同步、回滚或升级主链路。
4. 是否需要同步更新部署、配置或 README 文档。

如果需求超出边界或引入新基础设施，应先更新设计文档，再开始实现。

数据库迁移

任何涉及表结构、索引、列类型、分表规则或内部持久化元数据的修改，都必须同步提升数据库版本号，并补充从上一版本升级到新版本的显式迁移方法。

迁移必须包含升级后的校验逻辑。迁移失败或校验失败时，启动流程必须中止，且不得提升数据库版本记录。

前端约束

前端以 openflare_server/web 为准：

• 页面路由与布局放在 app/。
• API 请求统一收敛到 lib/api/。
• 业务逻辑优先放在 features/。
• 服务端状态使用 TanStack Query。
• 表单使用 React Hook Form 与 Zod。
• 主题必须支持 light、dark、system。

测试与交付

关键业务逻辑必须有单元测试或等效回归测试。任何正式基线改动至少应保证不破坏 Agent 心跳、同步、发布与回滚主链路。