# 嵌入式内存数据库remdb需求

[TOC]




## ✅ 用户故事与验收条件

### **阶段一：最小可行产品（MVP）**

**核心存储引擎**

#### **US-101：轻量级内存表存储**

作为嵌入式开发者，我希望数据以紧凑的二进制格式存储在预分配的内存区域中，以便实现可预测的内存占用和快速访问。

**验收条件：**
1. 支持编译时配置表结构和容量，内存占用可精确计算
2. 提供简单API：insert、delete、get_by_id，无动态内存分配
3. 在STM32F4（168MHz）上，单记录操作平均延迟<100μs（无持久化）
4. 支持至少4种基本数据类型：整数、浮点、定长字符串、布尔、时间戳

**技术约束：**

- 不支持运行时修改表结构
- 最大表数量：32个
- 单表最大记录数：65535条
- 单记录最大大小：512字节

---

#### **US-102：简单索引机制**

作为查询优化者，我希望为关键字段创建索引以加速查询，同时控制内存开销。

**验收条件：**
1. 支持主键索引（哈希）和1个辅助索引（有序数组）
2. 索引内存占用不超过数据大小的50%
3. 通过索引的查询比全表扫描快10倍以上（选择性>1%时）
4. 索引维护与数据操作保持原子性
5. 提供索引使用统计

**技术约束：**
- 每表最多2个索引
- 不支持复合索引
- 索引键最大长度：64字节

---

#### **US-103：基本事务支持**

作为应用开发者，我希望简单的原子操作支持，保证多步骤操作的一致性。

**验收条件：**
1. 支持begin/commit/rollback语义
2. 事务内操作要么全部成功，要么全部回滚
3. 提供默认的读已提交隔离级别
4. 事务嵌套深度：1层（不支持嵌套事务）
5. 事务开销：空事务<50μs

---

**嵌入式适配**

#### **US-104：可配置的内存管理**

作为资源受限设备开发者，我希望根据设备内存情况灵活配置数据库内存使用。

**验收条件：**
1. 仅支持动态内存块两种分配策略
2. 可配置内存使用上限，接近上限时触发警告
3. 内存碎片率<5%（长期运行测试）
4. 支持无堆模式，所有内存预分配
5. 提供内存使用统计API

---

#### **US-105：平台抽象层**

作为跨平台开发者，我希望数据库核心不依赖特定操作系统，便于移植。

**验收条件：**
1. 抽象时间、同步、内存分配接口
2. 提供POSIX和裸机两种实现
3. 在Linux和FreeRTOS上通过功能测试
4. 平台相关代码<总代码的5%
5. 支持交叉编译到ARM Cortex-M

---

#### **US-106：零外部依赖设计**

作为裸机开发者，我希望数据库不依赖任何操作系统功能（除基本内存分配），以便在无OS环境中运行。

**验收条件：**

1. 无标准库依赖
2. 平台抽象层：提供时间、内存分配、文件I/O（可选）的接口
3. 编译选项：可禁用所有非必需功能（如日志、调试）
4. 代码体积：最小配置下<50KB（ARM Thumb2）
5. 支持无堆（heap-less）模式，全部静态分配

---

#### **US-107：WAL与检查点机制**

作为数据安全负责人，我希望通过写前日志和定期检查点保证数据持久化，以便在崩溃后快速恢复。

**验收条件：**

1. WAL格式：包含CRC校验、事务ID、操作类型、数据
2. 支持同步/异步日志模式：同步模式确保持久化，异步模式提高性能
3. 检查点：定时（可配置，默认60s）将内存状态完整保存
4. 恢复时先加载最新检查点，再重放后续WAL
5. 日志空间预分配，避免运行时扩展

**测试场景：**

- 模拟崩溃恢复，验证数据完整性
- 测量日志写入性能：同步模式<100μs/事务，异步模式<20μs/事务
- 验证大事务（>1MB）的日志正确处理

---

#### **US-108：日志压缩与轮转**

作为长期运行系统管理员，我希望WAL能自动压缩和轮转，以免日志文件无限增长占用存储空间。

**验收条件：**

1. 日志分段：每段固定大小（默认16MB），写满后创建新段
2. 压缩：旧日志段可压缩存储（gzip/LZ4可选）
3. 清理策略：保留最近N个检查点对应的日志（默认3）
4. 日志元数据：记录检查点位置，加速恢复定位
5. 磁盘空间监控：超过阈值（默认90%）时警告

**测试场景：**

- 连续运行24小时，验证日志不会无限增长
- 验证压缩后日志可正确解压用于恢复
- 模拟磁盘满的情况，验证优雅处理

------

#### **US-109：快速启动恢复**

作为嵌入式设备开发者，我希望数据库能在系统重启后毫秒级恢复，以便满足设备快速启动要求。

**验收条件：**

1. 恢复时间：100MB数据在SSD上恢复时间<500ms
2. 恢复期间内存使用不超过运行时的120%
3. 支持恢复进度回调，可显示进度百分比
4. 恢复过程可中断，中断后数据仍处于一致状态
5. 提供恢复统计：读取字节数、应用事务数、耗时

**测试场景：**

- 不同数据量下的恢复时间测试（10MB-1GB）
- 模拟恢复中途断电，验证恢复可继续
- 恢复过程中并发访问尝试应被阻塞

### **阶段二：核心优化**

**持久化与可靠性**

#### **US-201：快照式持久化**

作为数据安全负责人，我希望定期将内存状态保存到非易失存储，以便在重启后恢复。

**验收条件：**
1. 支持手动触发和定时自动快照（可配置间隔）
2. 快照保存时间：1MB数据<500ms（SPI Flash）
3. 恢复时间：1MB数据<800ms
4. 快照存储格式紧凑，支持CRC32校验
5. 支持增量快照以减小存储开销（可选）

**技术约束：**
- 快照期间阻塞写操作，读操作可继续
- 不支持事务日志，仅支持快照恢复到最后一致状态

---

#### **US-202：并发访问优化**

作为多任务应用开发者，我希望数据库支持安全的并发访问，避免数据竞争。

**验收条件：**

1. 支持读写锁机制，读多写少场景下性能优化
2. 提供简单的乐观锁（版本号）机制
3. 死锁检测超时：默认100ms
4. 8个并发读线程时，吞吐量下降<30%
5. 2个并发写线程时，数据一致性100%保证

---

#### **US-203：内存保护机制**

作为安全敏感应用开发者，我希望设置内存使用硬上限，并在接近上限时触发回调，以便防止内存溢出。

**验收条件：**

1. 硬上限配置：全局内存上限和表级内存上限
2. 水位线警告：80%时警告回调，95%时严重警告
3. 超出上限处理：拒绝新插入或触发清理策略
4. 内存统计：实时监控各组件内存使用
5. 支持内存压力测试，验证上限有效性

---

#### **US-204：CPU缓存优化**

作为性能敏感应用开发者，我希望数据结构和访问模式优化CPU缓存命中率，以便减少内存访问延迟。

**验收条件：**

1. 数据布局：热字段集中存储，冷字段分离
2. 缓存行对齐：关键数据结构64字节对齐
3. 预取提示：对顺序扫描提供软件预取
4. 缓存感知算法：B+树节点大小为缓存行倍数
5. 性能提升：相比未优化版本，L1缓存命中率提升>20%

---

#### **US-205：嵌入式环境下的ACID事务支持**

作为嵌入式关键业务应用（如金融终端、工业控制）的开发者，我希望内存数据库提供完整的ACID事务支持，以便在资源受限的硬件上，安全、可靠地执行复杂的数据操作序列，确保数据的一致性和可靠性。

**验收条件：**

原子性实现

- 提供 begin(), commit(), rollback() 基础API。

- 事务内的所有数据修改（增、删、改）必须作为一个不可分割的整体：提交时全部生效，回滚时全部撤销，无中间状态。

- 实现写前日志或影子页/多版本机制来支持原子回滚。在事务过程中，原始数据必须被保护，直至提交。


一致性保证

- 事务必须将数据库从一个一致状态转换为另一个一致状态。

- 支持在数据模式中定义的基础约束（如主键唯一性、非空字段），并在事务提交时进行验证，违反约束将导致事务中止。

- 提供可选的应用程序定义的一致性检查回调函数。


隔离性控制

- 默认提供快照隔离 级别：每个事务开始时获取一个数据快照，在其整个执行过程中都基于此快照读取，避免脏读、不可重复读。

- 通过多版本并发控制 实现：数据修改创建新版本，旧版本根据事务存活情况由垃圾回收机制清理。

- 写操作（增、删、改）使用行级悲观锁或乐观锁（带冲突检测与重试）来保证序列化写入，防止丢失更新。


持久性策略

- 事务提交后，其修改必须得到持久化保证。

- 提供两种策略，由应用在初始化时选择：

- 全持久模式：事务提交时，相关修改必须同步写入持久化存储（如遵守US-107的WAL）。

- 延迟持久模式：事务提交立即在内存中生效，但允许将持久化操作异步批量执行，此模式下需提供 tx_sync() API 手动触发刷盘。


性能与资源约束

- 单次事务（含开始、若干操作、提交）的典型开销（空事务）应低于 50微秒（在100MHz级嵌入式CPU上）。

- 事务机制引入的内存开销（如版本存储、锁结构）不得超过数据库总内存占用的 15%。

- 支持至少 8个 并发活动事务。


测试场景：

原子性与回滚测试：

- 执行一个插入多条记录的事务，在提交前模拟失败并调用回滚，验证所有插入痕迹被完全清除。

- 测试嵌套操作（如插入后更新再删除同一记录）在回滚后的一致性。


隔离性与并发测试：

- 启动两个并发事务：事务A读取一行数据，事务B修改并提交该行数据。验证事务A的读取结果不受事务B影响（快照隔离）。

- 启动两个并发写事务尝试修改同一行数据，验证只有一个成功（通过锁或冲突检测机制）。


性能与压力测试：

- 创建16个线程，每个线程循环执行包含随机读写的小事务，持续运行1分钟，统计每秒完成的事务数，并检查最终数据一致性。

- 监控在长时间运行并发事务后，内存中版本链的增长情况，验证垃圾回收机制的有效性，防止内存无限增长。

**查询功能**

#### **US-206：条件查询引擎**

作为应用开发者，我希望通过条件表达式查询数据，而不仅仅是主键查询。

**验收条件：**
1. 支持简单的比较条件：=、!=、<、>、≤、≥
2. 支持AND操作，最多3个条件组合
3. 支持通过索引的查询自动优化
4. 查询执行计划可输出（调试版本）
5. 全表扫描性能：1000条记录<1ms

---

#### **US-207：Qt快照查看工具emdbui**

作为开发人员，我希望有一个图形化工具来查看remdb快照文件，以便直观地了解数据库状态和数据内容。

**验收条件：**
1. 支持打开和解析remdb快照文件
2. 显示数据库表的基本信息（表名、记录数、字段信息等）
3. 支持按表分页查看表数据
4. 提供数据导出功能（CSV格式）
5. 支持搜索和过滤记录
6. 界面友好，操作简单
7. 支持Windows/Linux跨平台运行

**技术约束：**
- 基于Qt 5.14.2框架开发
- 无其他外部依赖
- 支持查看至少10000条记录的表
- 响应时间：打开1MB快照文件<2秒

---

**外部接口**

#### **US-208：基于UDP的高可靠数据订阅与发布**

作为嵌入式实时系统开发者，我希望数据库内置一个基于UDP协议的轻量级数据发布/订阅机制，并对传输数据进行CRC校验，以便在局域网内实现高效、可靠的数据广播或组播，满足传感器数据分发、多节点状态同步等场景的需求。

**验收条件：**

协议与接口设计：

定义二进制协议帧，包含：帧头（魔术字、版本、类型）、序列号、主题ID、数据长度、CRC32校验和、载荷数据。

提供API：subscribe(topic_id, callback)用于订阅主题，publish(topic_id, data)用于发布数据。

支持单播、广播和组播（Multicast）模式，可通过配置切换。

**核心功能要求：**

- 数据完整性保障：每个发出的UDP数据包都必须包含基于载荷计算出的CRC32校验和。接收方必须验证校验和，丢弃无效包，并可选择性地请求重传（基于序列号）。

- 订阅管理：服务端维护主题-订阅者列表的动态映射。支持订阅者的动态加入与离开。

- 极低延迟发布：从调用publish API到数据进入网络栈的延迟小于100微秒（在100MHz级嵌入式CPU上）。

- 资源预配置：内存池、套接字缓冲区等资源均在初始化时静态分配，避免运行时动态内存分配。


**性能与资源约束：**

- 支持不少于32个不同的数据主题。

- 每个主题支持不少于16个并发订阅者。

- 在以太网（100Mbps）环境下，端到端（发布者到订阅者）数据延迟99分位线小于5ms。

- 协议头开销小于载荷数据的10%（针对小数据包优化）。

- 可靠性增强：

- 提供可选的、简单的否定确认（NACK）与重传机制，以应对偶发的UDP丢包。

- 支持“心跳”包，用于检测订阅者的存活状态，并清理无效订阅。


**测试场景：**

功能正确性测试：

- 验证一个发布者向一个主题发布带CRC的数据，多个订阅者能正确接收并验证通过。

- 验证发送故意损坏（CRC错误）的数据包会被订阅者静默丢弃。

- 验证动态订阅与取消订阅功能。


性能与资源测试：

- 在回环接口和真实交叉网线上，测试发布100字节载荷数据，达到1000 Hz发布频率时，CPU使用率不超过15%。

- 测量从publish调用到订阅者回调函数触发的端到端延迟分布。

- 监控在长时间运行下，内存池无泄漏、无碎片。

- 网络容错测试：

- 在存在网络抖动和丢包（可通过工具模拟）的环境中，测试启用重传机制后的数据最终交付成功率大于99.99%。

- 模拟订阅者意外宕机，验证发布者的“心跳”机制能正确清理其订阅状态。

---

#### **US-209：基于Rust的编译期DDL解析与类型安全代码生成**

作为使用Rust的嵌入式开发者，我希望有一个编译期工具，能够解析SQLite3语法兼容的DDL文件，并自动生成与之对应的、零开销的Rust数据结构定义及类型安全的数据库操作API，以便在获得SQL声明式便利的同时，实现与手动编写Rust结构体同等的运行时性能与内存效率。

**验收条件：**

1. **DDL解析与验证**
   - 能够解析核心SQLite3 DDL语法：`CREATE TABLE`、列定义（`INTEGER`、`TEXT`、`REAL`、`BOOLEAN`）、`PRIMARY KEY`、`NOT NULL`、`UNIQUE`约束。不支持`BLOB`。
   - 在编译期执行语法和语义检查（如重复表名、未知数据类型），并提供清晰错误信息，导致编译失败。
   - 支持通过 `//` 或 `/* */` 注释。
2. **Rust代码生成**
   - **生成强类型结构体**：为每张表生成一个对应的Rust `struct`，其字段名称、类型与DDL定义严格对应（如 `INTEGER` -> `i64`, `TEXT` -> `String` 或 `&str`）。
   - **生成元数据**：生成包含表名、列名、列类型等信息的静态元数据，供数据库运行时（如查询引擎）使用。
   - **生成类型安全的API原型**：为每张表生成基础CRUD函数原型（如 `insert_xxx`, `query_xxx_by_primary_key`），其参数和返回值类型均基于生成的Rust结构体。这些API将与数据库核心引擎的实现进行链接。
3. **编译期集成与零运行时开销**
   - 该工具需被设计为 **过程宏**。推荐使用过程宏（如 `#[derive(MemdbTable)]`），以获得更直观的用法。
   - 生成的代码必须**不依赖任何运行时反射**，所有类型信息在编译时确定。
   - 生成的Rust代码必须通过 `cargo clippy` 的严格检查，符合Rust惯用风格。
4. **性能与资源约束**
   - 代码生成过程对项目编译时间的增加应小于 **2秒**（针对包含约50张表的DDL）。
   - 生成的代码本身**不得引入额外的内存开销**，数据结构的内存布局应与手动编写的等效Rust结构体完全一致。
   - 支持至少 **128张表** 的定义。

**测试场景：**

1. **功能正确性测试**：
   - 给定一个包含多表和复杂约束的DDL文件，验证生成的Rust结构体能通过编译，且字段类型映射正确。
   - 编写一个小型测试程序，使用生成的API插入数据，并通过数据库核心引擎验证数据能被正确存储和检索。
   - 验证 `NOT NULL` 约束在生成的API层面通过 `Option<T>` 类型得到正确体现。
2. **编译期错误测试**：
   - 提供一个有语法错误的DDL文件（如错误的关键字），验证构建过程会失败并给出指向DDL文件的行列错误信息。
   - 提供一个有语义错误的DDL文件（如重复列名），验证构建过程会失败并给出明确的错误描述。
3. **性能基准测试**：
   - 对比使用生成的API与使用动态SQL字符串接口执行相同操作（如插入10000条记录）的性能差异，验证无抽象惩罚。
   - 测量并对比生成的结构体与等效手写结构体的内存占用，必须完全相同。

---



#### **US-210：基于Rust过程宏的零成本DDL集成**

**作为** 使用Rust的嵌入式开发者，**我希望** 通过直观的Rust属性宏（`#[derive]` 风格）来声明数据库模式，**以便于** 在编译期就将SQL DDL直接转化为类型安全的Rust代码和数据库元数据，实现声明式建模与零运行时开销的完美结合。

**验收条件：**

1. **声明式API设计**

   - 提供 `MemdbTable` 过程宏。用户通过在结构体上标注 `#[derive(MemdbTable)]` 和 `#[memdb_schema]` 属性来定义表。

   - 支持两种模式：

     - **内联模式**：直接在属性中编写DDL。

     rust

     ```
     #[derive(MemdbTable)]
     #[memdb_schema(ddl = "CREATE TABLE user (id INTEGER PRIMARY KEY, name TEXT NOT NULL);")]
     struct UserTable; // 此结构体为标记，其名称`UserTable`可用于命名空间
     ```

     

     - **文件模式**：关联外部的DDL文件。

     rust

     ```
     #[derive(MemdbTable)]
     #[memdb_schema(file = "schema.ddl")] // 文件内容可包含多个CREATE TABLE语句
     struct MyDatabase;
     ```

     

2. **编译期代码生成**

   - 为DDL中的**每张表**生成一个对应的Rust实体结构体（如 `User`），其字段名和类型（`i64`, `String`, `Vec<u8>` 等）与DDL严格映射。
   - 生成一个**标记结构体的关联模块**，其中包含：
     - 生成的实体结构体（如 `User`）。
     - 类型安全的**表操作Trait约束**和**函数原型**（如 `fn insert(&self, entity: User) -> Result<()>`）。
     - 静态的**表元数据**（表名、列信息、主键等），以 `const` 或 `static` 形式存储。
   - 所有生成的代码必须通过 `rustc` 编译和 `clippy` 默认检查。

3. **类型安全与约束映射**

   - 将SQL约束映射为Rust类型系统约束：
     - `NOT NULL` -> 非 `Option` 类型（如 `String`）。
     - 可为空的列 -> `Option<T>` 类型（如 `Option<String>`）。
     - `PRIMARY KEY` 和 `UNIQUE` 约束信息存入元数据，供事务引擎（US-031）用于运行时检查。
   - 为每个表生成唯一的 `TableId` 类型，用于在编译期区分不同的表。

4. **零开销与编译时保障**

   - **零运行时解析**：数据库引擎在启动时无需读取或解析DDL文件，所有结构信息已编译在二进制中。
   - **内存布局等同手写代码**：生成的实体结构体 `#[repr(C)]`，其内存布局与手写结构体完全一致，无任何额外填充或隐藏字段。
   - **编译时错误报告**：DDL语法错误、类型不支持的语义错误必须在编译时报告，并尽可能指向DDL中的行号和列号。

5. **性能与资源约束**

   - 过程宏的执行时间：对于包含50张表的DDL，宏展开增加的编译时间应 **< 1.5秒**。
   - 生成的代码量：每张表生成的额外代码（除实体结构体外）应 **< 5KB**（Rust源码体积）。
   - 支持 **128** 张表以上的模式定义。

**测试场景：**

1. **功能与集成测试**
   - **内联模式测试**：编写一个包含2-3张表的内联DDL，验证宏能正确展开，生成的代码可编译，且实体结构体字段正确。
   - **文件模式测试**：使用一个包含复杂外键（暂存为注释）和索引定义的外部DDL文件，验证宏能读取文件并正确生成所有表结构。
   - **约束映射测试**：创建一个包含 `NOT NULL`、`UNIQUE` 和各种SQL类型的表，验证生成的Rust结构体字段类型是否符合预期（如 `NOT NULL TEXT` -> `String`, 可空 `INTEGER` -> `Option<i64>`）。
2. **编译期错误测试**
   - **语法错误**：提供 `CREATE TBL ...` （错误关键字）的DDL，验证编译器会输出清晰的错误，并指向DDL字符串或文件中的具体位置。
   - **语义错误**：定义重复的列名，验证编译会失败并提示 “duplicate column name ‘x’”。
3. **性能与开销验证**
   - **编译时间基准**：在一个干净的项目中，测量添加该宏依赖前后的 `cargo build --release` 编译时间差。
   - **内存布局对比**：使用 `std::mem::size_of` 和 `align_of` 对比生成的 `User` 结构体与手动编写的、字段完全相同的结构体，确认两者大小和对齐方式一致。
   - **代码膨胀测试**：检查最终二进制中，与生成的128张表元数据相关的只读数据（`.rodata`段）大小，评估其合理性。

---

#### US-211：增量快照功能

作为数据安全负责人，我希望只保存自上次快照以来的变化数据，以便减少快照存储开销和生成时间，同时保持数据恢复能力。

**验收条件：**

1. 支持在全量快照基础上生成增量快照
2. 增量快照大小不超过全量快照的30%（数据变化率<20%时）
3. 增量快照生成时间比全量快照快50%以上
4. 支持从最新全量快照+所有后续增量快照恢复
5. 增量快照包含变化数据的CRC32校验
6. 支持配置最大增量快照数量，自动清理旧快照
7. 提供快照链完整性检查工具

**技术约束：**

- 仅支持基于时间点的增量快照
- 最大增量快照链长度：16个
- 增量快照与全量快照使用相同的存储接口
- 不支持跨设备的增量快照生成

---

#### **US-212：高级索引类型支持**

作为查询优化者，我希望数据库支持多种索引类型，以便根据不同查询场景选择最优索引，提高查询性能。

**验收条件：**

1. 支持B-Tree索引（适用于范围查询和顺序访问）
2. 支持T-Tree索引（适用于频繁更新的场景）
3. 索引类型可在编译时配置
4. B-Tree索引在范围查询时比有序数组索引快5倍以上（数据量>1000条）
5. T-Tree索引在随机更新场景下比B-Tree快3倍以上
6. 新索引类型的内存开销不超过数据大小的50%
7. 索引维护与数据操作保持原子性
8. 提供索引类型性能对比工具

**技术约束：**

- 每表最多支持3个索引（包括主键索引）
- 索引键最大长度：64字节
- 支持的索引类型：哈希（主键）、有序数组、B-Tree、T-Tree

---

#### 


### **阶段三：高级功能**

**性能优化**

#### **US-301：批处理操作**

作为数据采集应用开发者，我希望批量处理传感器数据以减少事务开销。

**验收条件：**
1. 支持批量插入API，一次插入最多256条记录
2. 批量操作的事务开销分摊到单条<20%
3. 批量操作失败时提供详细错误信息
4. 支持批量更新和删除（可选）
5. 内存使用优化：批量数据连续存储

---

#### **US-302：缓存感知优化**

作为性能敏感应用开发者，我希望数据访问模式优化CPU缓存利用率。

**验收条件：**

1. 热点数据自动聚集存储
2. 顺序扫描时预取下一个缓存行
3. 数据结构按缓存行对齐（64字节）
4. 缓存命中率比未优化版本提高15%以上
5. 提供缓存统计信息

---

#### **US-303：嵌入式高可用主从复制 (remdbHA)**

**作为** 关键任务嵌入式系统（如边缘网关、电信设备、工业控制器）的架构师，**我希望** 数据库提供内置的、低开销的主从复制与自动故障转移功能，**以便于** 在单个节点发生软件或硬件故障时，系统能自动、快速地将服务切换至备用节点，从而保障业务的连续性和数据的高可用性。

**验收条件：**

1. **复制拓扑与数据一致性**
   - 支持 **一主一从** 或 **一主多从** 的拓扑结构，所有数据修改仅在主节点进行。
   - 提供两种可配置的复制一致性模式：
     - **同步模式**：事务必须在主节点提交 *并* 在至少一个从节点持久化后，才向客户端返回成功。此模式提供强一致性（RPO=0），确保无数据丢失。
     - **异步模式**：事务在主节点提交后立即向客户端返回成功，随后异步传播至从节点。此模式提供更高吞吐量，但极端情况下可能有少量数据丢失风险。
   - 复制内容为物理日志（如US-107的WAL）或逻辑操作日志，确保从节点数据状态最终与主节点一致。
2. **自动故障检测与转移**
   - 实现基于**心跳机制**的故障检测。主从节点间定期交换心跳消息，当从节点在配置时间内未收到主节点心跳时，将触发故障判定。
   - 支持 **自动故障转移**：当确认主节点失效后，一个指定的从节点（优先副本）将自动提升为新的主节点，并开始接受写请求。
   - 提供客户端重定向机制（例如，通过轻量级服务发现或连接代理），使应用能在故障转移后自动或半自动地连接到新的主节点。
3. **节点恢复与数据同步**
   - 支持 **故障节点重新加入**：当旧主节点恢复后，能作为新的从节点自动重新加入集群，并从当前主节点同步缺失的数据。
   - 提供 **全量同步** 与 **增量同步** 机制。新加入或落后过多的从节点，可先通过全量快照进行基础同步，再通过增量日志追平。
4. **嵌入式资源约束与性能**
   - 复制机制的内存开销不得超过数据库总内存占用的 **10%**。
   - 在100Mbps以太网上，同步复制的平均事务提交延迟增加不超过 **200微秒**（相对于无复制的主节点本地提交）。
   - 故障检测到完成切换的总时间（即服务中断窗口）应小于 **2秒**。
   - 心跳与复制数据包需精简，并支持可选的CRC校验（与US-108的UDP CRC校验共用基础组件）。

**测试场景：**

1. **数据一致性测试**：

   - 在主节点执行一系列包含随机数据的并发事务，在同步复制模式下，验证所有从节点在事务提交后立即拥有完全一致的数据快照。
   - 在异步复制模式下，停止主节点，验证从节点上已复制的数据是主节点的一个一致前缀。

2. **故障转移演练**：

   - 在持续写入负载下，**模拟主节点进程崩溃**。验证：1) 从节点能在设定时间内（如1.5秒）检测到故障；2) 优先从节点自动成为新主；3) 客户端应用在重试后能向新主节点写入成功。
   - **模拟主节点网络隔离**（脑裂场景）。验证集群能通过预定义的仲裁策略（如仅当从节点间能相互通信时）安全地执行切换，避免出现“双主”导致数据混乱。

3. **恢复与同步测试**：

   - 将一台已失效一段时间、数据严重落后的旧主节点重新启动并配置为从节点。验证其能自动请求并从当前主节点同步数据，最终达到数据一致状态。
   - 测量在全量同步过程中，对主节点正常服务吞吐量的影响（下降应不超过20%）。

4. **资源与性能基准测试**：

   - 监控开启同步复制后，在不同负载下（如每秒1k/10k次事务），主节点的CPU使用率增长情况。
   - 在资源受限的嵌入式目标板上，验证复制功能与数据库其他核心功能（如事务处理、UDP发布）能稳定共存，无资源耗尽风险。

   ---

   

**监控与维护**

#### **US-304：运行时监控接口**

作为系统集成者，我希望监控数据库运行状态，便于系统调优和问题诊断。

**验收条件：**
1. 提供关键指标：内存使用、操作计数、缓存命中率
2. 监控开销<总CPU时间的2%
3. 支持指标重置和快照
4. 通过串口或日志输出统计信息
5. 支持健康检查API

---

#### **US-305：完整性验证工具**

作为测试工程师，我希望验证数据库内部一致性，确保长期运行可靠性。

**验收条件：**
1. 支持离线完整性检查（数据库不运行时）
2. 检查项：数据-索引一致性、内存泄漏、循环引用
3. 检查时间：1MB数据<200ms
4. 提供修复建议（不自动修复）
5. 检查结果可读性高

---

### **阶段四：可选扩展**

**领域特定优化**

#### **US-401：时间序列支持（可选）**

作为IoT开发者，我希望优化时间序列数据的存储和查询。

**验收条件：**
1. 时间戳自动索引，支持时间范围查询
2. 数据自动老化（基于时间或数量）
3. 时间窗口聚合函数（sum/avg/min/max）
4. 压缩存储：时间序列数据压缩率>50%
5. 专门的时间序列查询API

---

#### **US-402：低功耗模式（可选）**

作为电池供电设备开发者，我希望数据库在空闲时降低功耗。

**验收条件：**
1. 可配置的空闲检测时间（默认5s）
2. 低功耗模式电流降低>30%
3. 唤醒延迟<10ms
4. 支持深度睡眠模式
5. 功耗统计功能

---

####  **US-403：混合存储引擎（可选）**

作为大容量应用开发者，我希望将冷数据自动迁移到闪存，以便在有限内存中存储更多数据。

**验收条件：**

1. 冷热识别：基于访问频率和时间的自动识别
2. 迁移策略：可配置的迁移阈值和批次大小
3. 透明访问：冷数据访问自动加载回内存
4. 性能衰减：冷数据访问比热数据慢<10倍
5. 闪存磨损均衡：优化闪存写入模式

---


### **阶段五：服务器版**

**百万QPS**

#### **US-501：无锁高并发架构**

作为高性能应用开发者，我希望数据库核心使用无锁数据结构和细粒度并发控制，以便在32核服务器上实现百万级QPS。

**验收条件：**

1. 核心数据结构（哈希表、B+树）实现无锁版本
2. 支持多核并行查询，查询性能随核心数线性扩展（32核下至少25倍提升）
3. 内存操作使用RCU（Read-Copy-Update）或类似技术，实现零拷贝读取
4. 实现NUMA感知的内存分配和线程绑定
5. 支持线程本地缓存，减少跨核心数据共享
6. 单个查询延迟99分位线<50μs
7. 在32核/256GB内存服务器上，实现>100万QPS（混合读写场景）

**测试场景：**

- 32线程并发测试，验证线性扩展性
- 不同NUMA节点配置下的性能测试
- 长时间压力测试（24小时）验证无锁算法的正确性
- 与主流内存数据库（Redis、Memcached）的性能对比

------

#### **US-502：零拷贝网络栈优化**

作为网络敏感应用开发者，我希望数据库网络层实现零拷贝和批处理，以便最大化网络吞吐量并降低CPU使用率。

**验收条件：**

1. 实现基于io_uring的异步网络I/O（Linux 5.1+）
2. 支持零拷贝数据发送（sendfile、splice等技术）
3. RESP协议解析使用SIMD指令（AVX2/AVX-512）加速
4. 命令批处理：单次系统调用处理多个客户端请求
5. 支持内核旁路（Kernel Bypass）技术选项（如DPDK）
6. 网络吞吐量：单节点>40Gbps，CPU使用率<50%
7. 连接管理支持百万级并发连接

**测试场景：**

- 使用dpdk-testpmd测试网络吞吐量
- 高并发连接测试（100万并发连接）
- 网络延迟测试（P99延迟<100μs）
- 对比不同网络I/O模型性能（epoll vs io_uring）

------

#### **US-503：内存与缓存极致优化**

作为内存敏感应用开发者，我希望数据库内存访问模式极致优化，以便最大化CPU缓存命中率并减少内存带宽消耗。

**验收条件：**

1. 数据结构紧凑设计：记录头部压缩到8字节以内
2. 支持缓存行对齐（64字节）和内存页对齐（4KB）
3. 实现软件预取（prefetch）提示优化
4. 使用透明大页（THP）减少TLB缺失
5. 支持内存访问模式分析工具，指导数据结构布局优化
6. 内存带宽使用：随机读取场景下<80GB/s（DDR4-3200）
7. L1/L2缓存命中率>95%，TLB命中率>99%

**测试场景：**

- 使用Intel VTune或perf分析缓存命中率
- 不同内存对齐方式下的性能对比
- 透明大页开启/关闭的性能影响
- 内存带宽压力测试

------

#### **US-504：高效持久化与日志优化**

作为高吞吐持久化应用开发者，我希望持久化机制对性能影响最小化，以便在高QPS下仍能保证数据安全。

**验收条件：**

1. 实现组提交（Group Commit）：批量事务一次性写入日志
2. 支持异步持久化模式：数据先返回客户端，后台持久化
3. 日志写入使用O_DIRECT绕过内核页缓存
4. 支持SSD优化访问模式（对齐4KB，避免写入放大）
5. 持久化延迟：同步模式<100μs，异步模式<10μs
6. 日志压缩使用硬件加速（如Intel QAT）
7. 支持持久化内存（PMEM）作为日志存储

**测试场景：**

- 不同持久化模式下的性能对比
- 断电恢复测试，验证数据一致性
- SSD寿命测试（写入放大系数<1.2）
- PMEM与传统SSD的性能对比

------

#### **US-505：百万QPS性能测试框架**

作为性能工程师，我希望有完善的性能测试框架，以便准确测量和验证百万QPS性能。

**验收条件：**

1. 支持多种负载模式：只读、只写、混合、热点访问、随机访问
2. 可配置的客户端行为：连接数、并发数、请求模式
3. 实时性能监控：QPS、延迟分布、CPU使用、内存带宽
4. 自动化基准测试：一键运行完整性能测试套件
5. 支持分布式压力测试：多台客户端机器同时测试
6. 结果分析与报告生成：自动生成性能报告和对比图表
7. 支持与Redis、KeyDB、Dragonfly等竞品的性能对比

**测试场景：**

- 百万QPS验证测试（32核/256GB内存）
- 线性扩展性测试（1-32核心）
- 长时间稳定性测试（7*24小时）
- 极端场景测试（连接闪断、内存压力等）

---

## 🎯 关键技术决策调整

### **1. 存储模型：混合模式**
- **内存表**：核心热数据，固定结构，高效访问
- **对象缓存**：可选扩展，支持动态数据
- **权衡**：80%场景用内存表，20%复杂场景用对象缓存

### **2. 持久化策略：检查点为主**
- **主要**：定期全量/增量快照
- **辅助**：可选操作日志（针对关键操作）
- **恢复**：加载最新快照 + 重放关键日志

### **3. 并发模型：读写锁 + 乐观锁**
- **默认**：读写锁，简单可靠
- **可选**：乐观锁（版本号），高并发读场景
- **放弃**：完整MVCC，复杂度太高

### **4. 配置策略：编译时为主，运行时为辅**
- **核心参数**：表结构、内存大小等在编译时确定
- **运行参数**：快照间隔、缓存大小等可运行时调整
- **配置验证**：编译时检查配置合法性

---

## ⚠️ 风险与缓解措施

| 风险 | 可能性 | 影响 | 缓解措施 |
|------|--------|------|----------|
| 内存碎片问题 | 中 | 高 | 使用内存池+定期整理 |
| 持久化性能问题 | 高 | 中 | 增量快照+压缩 |
| 并发死锁 | 低 | 高 | 超时检测+自动回滚 |
| 跨平台兼容性 | 中 | 中 | 抽象层测试+CI/CD |
| 长期运行稳定性 | 中 | 高 | 内存泄漏检测+老化测试 |

---

## 🧪 测试策略调整

### **单元测试**
- 代码覆盖率>85%
- 每个模块独立的测试套件
- 内存泄漏检测集成到测试中

### **集成测试**
- 端到端功能测试
- 跨平台兼容性测试
- API稳定性测试

### **性能测试（Phase里程碑）**
- 基准测试：操作延迟、吞吐量、内存使用
- 对比测试：与SQLite内存模式对比
- 长期运行：72小时压力测试

### **真实场景测试**
- 嵌入式开发板实际部署
- 模拟传感器数据采集场景
- 功耗测量（电池供电场景）

---

## 📊 成功指标（KPI）

### **技术指标**
1. **性能**：点查询延迟<100μs（STM32F4）
2. **内存**：静态内存占用<50KB，每记录开销<额外8字节
3. **可靠性**：崩溃恢复成功率>99.9%
4. **可移植性**：支持至少3种架构+2种RTOS

### **项目指标**
1. **进度**：每Sprint完成计划用户故事的80%以上
2. **质量**：每千行代码bug数<5个
3. **文档**：API文档100%覆盖，示例代码充足

### **业务指标**
1. **易用性**：新用户2小时内完成第一个应用集成
2. **维护性**：平均问题修复时间<2天
3. **社区**：GitHub star>100（如果开源）

---