# 开发约束

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 心跳、同步、发布与回滚主链路。