# 嵌入式内存数据库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-110：核心需求：零拷贝访问**
作为 需要极致性能的应用程序开发者，我希望 数据库在执行查询和返回结果时，能够避免在数据库内部缓冲区与应用程序缓冲区之间进行任何不必要的数据拷贝，以便于 实现微秒级甚至纳秒级的低延迟数据访问，并让CPU的计算资源更多地用于业务逻辑而非数据搬运。
**详细规格与验收条件**
1. 读取路径零拷贝
· 需求描述：当应用程序通过API（如根据主键或索引查询单条记录）请求数据时，数据库应直接返回指向其内部内存存储位置的指针或引用，而非将数据复制到新的缓冲区。
· 验收条件：
· 查询返回的“行”或“记录”对象，本质上是一个内存视图或引用。
· 在返回此引用期间，数据库的内存管理机制（如垃圾回收、压缩）必须保证该内存区域的稳定性，不会被移动或释放。
· 性能指标：点查询操作（如 get_by_id）的延迟应接近纯内存指针解引用的开销，与数据大小无关。
2. 写入/更新路径的高效拷贝
· 需求描述：写入操作通常难以做到“零拷贝”，因为输入数据来自外部。但需求应优化为 “单次拷贝” ，即数据从应用程序传入后，仅被拷贝一次即到达其最终的存储位置，并在此过程中完成序列化（如果必需）。
· 验收条件：
· 提供接收连续内存布局（如C结构体、Rust的 #[repr(C)] 结构体）的写入接口。
· 写入时，数据库应能通过 memcpy 或类似机制，一次性地将数据从用户缓冲区搬运到其预分配好的存储槽位中。
· 避免任何中间格式的转换或多次拷贝。
3. 扫描/迭代的零拷贝
· 需求描述：当进行全表扫描或范围查询时，数据库应提供能够原地迭代的游标（Cursor）机制。该游标直接遍历数据库内部的存储页或连续内存块，逐条返回记录的引用。
· 验收条件：
· 迭代器每次 next() 调用返回一个指向当前记录的引用，而非拷贝。
· 支持在迭代过程中安全地更新或删除当前记录（需定义明确语义，如是否立即生效或影响后续迭代）。
· 验收条件：
· 在传输大型结果集（如批量查询、流式响应）时，CPU使用率显著降低。
** 必须考虑的关联约束与挑战 **
零拷贝带来了性能的极大提升，但也引入了复杂性和新的要求，必须与其他需求协同设计：
1. 内存管理：
· 必须与 US-104 静态内存池管理深度集成。使用预分配的、固定大小的内存池或对象池是实现零拷贝的基础。这确保了记录在内存中的位置长期稳定，指针不会失效。
· 当需要压缩或整理内存时（如应对碎片），需要采用写时复制或影子分页技术，并在后台平滑地迁移数据，同时更新所有活动的引用。
2. 并发控制与事务：
· 必须与 US-205（ACID事务） 集成，保证在事务存活期间必须该版本的数据被“钉住”（pin），不能被垃圾回收。
· 需要高效的版本生命周期管理和垃圾回收机制，确保在无事务引用时能及时回收旧版本数据。
3. 数据安全与隔离：
· 直接返回内部指针意味着应用程序可能意外修改数据库内部数据。解决方案包括：
· 返回只读视图（Rust的 &T 或 &[u8]）。
· 如果需要修改，提供专门的 update API，在内部处理拷贝和版本更新。
4. 序列化/反序列化成本消除：
· 这是零拷贝的最大收益点之一。数据库的内部存储格式应与应用程序的内存中的对象格式尽可能一致或兼容。
· 这与你的 US-210（编译期DDL生成） 完美契合：生成的Rust结构体 #[repr(C)] 可以直接映射为数据库的存储格式，访问时无需任何解析或转换。
** 总结：零拷贝的本质 **
零拷贝访问需求的本质，是让内存数据库从“数据存储服务”向“内存管理服务”演进。它不再仅仅负责安全地存放数据，更要高效地组织内存，使应用程序能像使用自己的堆内存一样，直接、安全、并发地访问数据库中的数据。这需要数据库在存储布局、并发控制、内存管理和API设计上进行高度协同的、精细化的设计，是实现百万级QPS目标（US-505）的基石技术之一。
### **阶段二：核心优化**
**持久化与可靠性**
#### **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-210：基于Rust过程宏的编译期DDL解析与零成本类型安全代码生成**
**作为** 使用Rust的嵌入式开发者，**我希望** 通过直观的Rust属性宏（`#[derive]` 风格）来声明数据库模式，支持内联和文件两种方式解析SQLite3语法兼容的DDL，并在编译期自动生成类型安全的Rust数据结构和数据库操作API，**以便于** 在获得SQL声明式便利的同时，实现与手动编写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解析与验证**
- 能够解析核心SQLite3 DDL语法：`CREATE TABLE`、列定义（`INTEGER`、`TEXT`、`REAL`、`BOOLEAN`）、`PRIMARY KEY`、`NOT NULL`、`UNIQUE`约束。不支持`BLOB`。
- 在编译期执行语法和语义检查（如重复表名、未知数据类型），并提供清晰错误信息，导致编译失败。
- 支持通过 `//` 或 `/* */` 注释。
3. **编译期代码生成**
- 为DDL中的**每张表**生成一个对应的Rust实体结构体（如 `User`），其字段名和类型（`i64`, `String`, `Vec<u8>` 等）与DDL严格映射。
- 生成一个**标记结构体的关联模块**，其中包含：
- 生成的实体结构体（如 `User`）。
- 类型安全的**表操作Trait约束**和**函数原型**（如 `fn insert(&self, entity: User) -> Result<()>`）。
- 静态的**表元数据**（表名、列信息、主键等），以 `const` 或 `static` 形式存储。
- 所有生成的代码必须通过 `rustc` 编译和 `clippy` 默认检查。
4. **类型安全与约束映射**
- 将SQL约束映射为Rust类型系统约束：
- `NOT NULL` -> 非 `Option` 类型（如 `String`）。
- 可为空的列 -> `Option<T>` 类型（如 `Option<String>`）。
- `PRIMARY KEY` 和 `UNIQUE` 约束信息存入元数据，供事务引擎用于运行时检查。
- 为每个表生成唯一的 `TableId` 类型，用于在编译期区分不同的表。
5. **零开销与编译时保障**
- **零运行时解析**：数据库引擎在启动时无需读取或解析DDL文件，所有结构信息已编译在二进制中。
- **生成的代码必须不依赖任何运行时反射**，所有类型信息在编译时确定。
- **内存布局等同手写代码**：生成的实体结构体 `#[repr(C)]`，其内存布局与手写结构体完全一致，无任何额外填充或隐藏字段。
- **编译时错误报告**：DDL语法错误、类型不支持的语义错误必须在编译时报告，并尽可能指向DDL中的行号和列号。
6. **性能与资源约束**
- 过程宏的执行时间：对于包含50张表的DDL，宏展开增加的编译时间应 **< 2秒**。
- 生成的代码量：每张表生成的额外代码（除实体结构体外）应 **< 5KB**（Rust源码体积）。
- 生成的代码本身**不得引入额外的内存开销**，数据结构的内存布局应与手动编写的等效Rust结构体完全一致。
- 支持至少 **128张表** 的定义。
**测试场景：**
1. **功能与集成测试**
- **内联模式测试**：编写一个包含2-3张表的内联DDL，验证宏能正确展开，生成的代码可编译，且实体结构体字段正确。
- **文件模式测试**：使用一个包含复杂外键（暂存为注释）和索引定义的外部DDL文件，验证宏能读取文件并正确生成所有表结构。
- **约束映射测试**：创建一个包含 `NOT NULL`、`UNIQUE` 和各种SQL类型的表，验证生成的Rust结构体字段类型是否符合预期（如 `NOT NULL TEXT` -> `String`, 可空 `INTEGER` -> `Option<i64>`）。
- 编写一个小型测试程序，使用生成的API插入数据，并通过数据库核心引擎验证数据能被正确存储和检索。
2. **编译期错误测试**
- **语法错误**：提供 `CREATE TBL ...` （错误关键字）的DDL，验证编译器会输出清晰的错误，并指向DDL字符串或文件中的具体位置。
- **语义错误**：定义重复的列名，验证编译会失败并提示 "duplicate column name 'x'"。
3. **性能与开销验证**
- **编译时间基准**：在一个干净的项目中，测量添加该宏依赖前后的 `cargo build --release` 编译时间差。
- **内存布局对比**：使用 `std::mem::size_of` 和 `align_of` 对比生成的 `User` 结构体与手动编写的、字段完全相同的结构体，确认两者大小和对齐方式一致。
- **代码膨胀测试**：检查最终二进制中，与生成的128张表元数据相关的只读数据（`.rodata`段）大小，评估其合理性。
- **性能基准测试**：对比使用生成的API与使用动态SQL字符串接口执行相同操作（如插入10000条记录）的性能差异，验证无抽象惩罚。
---
#### 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-213：多版本并发控制（MVCC）引擎**
**作为** 需要高并发读写能力的嵌入式应用开发者，**我希望** 数据库内核实现高效的多版本并发控制机制，**以便于** 读操作与写操作互不阻塞，在保证快照隔离级别的事务一致性的同时，提供接近无锁的读取性能，满足实时系统中的高并发数据访问需求。
**验收条件：**
1. **版本化存储与快照读**
* 任何数据行（记录）在被更新或删除时，必须保留其旧版本，并为该版本标记一个唯一的、全局递增的**创建事务ID**和**删除事务ID**。
* 当某个事务执行查询时，数据库需根据该事务启动时获取的**快照版本号**，自动筛选出对该事务可见的数据版本。可见性规则为：行的`创建事务ID` ≤ 事务快照号，且 (`删除事务ID` 为未提交 或 `删除事务ID` > 事务快照号)。
* **读取永不阻塞写入**：任何查询操作都无需获取行锁，而是直接访问已提交的、可见的数据版本。
2. **高效的版本存储与垃圾回收**
* 同一行的多个版本应以紧凑的**版本链**形式存储（如单向链表），链头为最新版本，以加速最新版本的访问。
* 必须实现**自动垃圾回收**机制，定期清理不再被任何活跃事务快照所引用的旧版本数据，防止内存无限增长。
* 垃圾回收必须是**非阻塞**和**增量式**的，其执行不应导致前端事务暂停。内存回收开销需限制在总事务时间的 **5%** 以内。
3. **写入并发控制与冲突解决**
* 写入操作（INSERT, UPDATE, DELETE）必须检测**写-写冲突**。当两个事务尝试修改同一行数据时，应通过行级锁或乐观锁（如检查版本号）来保证序列化。
* 提供**可配置的冲突解决策略**：支持乐观并发控制（先提交者胜出，后提交者事务回滚）或悲观并发控制（获取行锁）。
* 在32核模拟环境下，读写混合负载的吞吐量下降应低于**纯锁模型的30%**。
4. **与核心架构的深度集成**
* **与事务集成**：为每个事务自动分配单调递增的**唯一事务ID**，作为版本标记和快照依据。
* **与内存管理集成**：版本数据必须从**预分配的内存池**中分配，其生命周期由垃圾回收器管理，确保内存使用的确定性和无碎片化。
* **与持久化集成**：WAL日志必须记录足以重建完整版本链的信息，确保崩溃恢复后MVCC状态的一致性。
5. **资源与性能约束**
* MVCC元数据（事务ID、版本指针）带来的单行存储开销应 **< 16字节**。
* 单次点查询因MVCC版本链遍历引入的额外延迟应 **< 100纳秒**（在链长小于5时）。
* 支持维护至少 **1024个** 并发活跃事务的快照视图。
**测试场景：**
1. **快照隔离正确性测试**：
* 事务A读取一行数据，事务B修改并提交该行数据后，再次在事务A内读取，验证两次结果一致（不可重复读被防止）。
* 启动一个长时间运行的事务，在其执行期间，验证它能持续看到事务开始时的数据快照，不受后续已提交事务的影响。
2. **并发性能与压力测试**：
* 模拟典型读写混合负载（如80%读，20%写），在16个并发线程下持续运行，验证吞吐量和高位延迟（P99）符合预期，且无内存无限增长。
* 在持续高压力写入下，验证垃圾回收机制能有效工作，版本链平均长度被稳定控制在 **< 10**。
3. **恢复与完整性测试**：
* 在MVCC运行期间模拟数据库崩溃，重启后验证：1) 所有已提交事务的数据可见；2) 未提交事务的数据被完全回滚；3) 版本链状态完整。
---
🧠 设计要点说明
此MVCC设计（US-213）是你整个ACID事务（US-205）的**核心子模块和高级实现**，它直接解决了并发下的隔离性问题。
1. **与零拷贝的关系**：MVCC是实现**零拷贝读取**的理想伙伴。只读事务可以直接获得指向某个稳定版本的指针，无需加锁或拷贝。但这也要求版本在事务存活期内必须被“钉住”，这需要与**确定性内存管理（US-202）** 和**垃圾回收**精细协作。
2. **与编译期DDL的关系**：通过 **US-210 过程宏**生成的强类型结构体，可以直接作为版本存储的单元，使得版本化的数据访问依然是类型安全和高效的。
3. **嵌入式优化**：与通用数据库不同，此设计强调**预分配**和**确定性的GC**，以避免在资源受限环境下由垃圾回收引起的不确定延迟。版本链长度和事务快照数量都有明确上限，符合嵌入式设计哲学。
**实现提示**：在Rust中，可以利用 `Arc` 或自定义的引用计数结构来管理版本的生命周期，利用 `Pin` 确保版本内存位置稳定，以安全地支持零拷贝引用。垃圾回收器可以是一个后台任务，基于全局活跃事务快照列表来扫描和回收可释放的版本。
### **阶段三：高级功能**
**性能优化**
#### **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. 闪存磨损均衡：优化闪存写入模式
---
#### **US-404：时序数据全链路优化存储引擎**
**作为** 处理海量传感器与监控数据的嵌入式系统开发者，**我希望** 数据库提供一个从表定义、事务写入到持久化存储的完整时序数据优化方案，**以便于** 在资源受限的边缘设备上，实现高吞吐、低延迟、高压缩比的时序数据全生命周期管理，确保数据从录入到落盘全程高效、一致且节省空间。
**包含US-405嵌入式优化目标**：针对100MHz单核嵌入式CPU的高性能写入优化
**验收条件：**
1. **专用的时序表DDL扩展**
- 扩展DDL语法，支持 `CREATE TIMESERIES TABLE` 关键字。使用此语法创建的表，将自动获得一个 `NOT NULL` 的 `timestamp` 列作为隐式主键之一。
- 在DDL中支持声明时序专属属性：
- `WITH COMPRESSION = (algorithm='delta-delta', enabled=true)`：指定写入时压缩算法。
- `WITH TTL = '30 days'`：定义数据存活时间，过期数据块可被自动清理。
- 通过过程宏（US-210），这些属性将生成对应的 Rust 结构体与表元数据，供核心引擎调用。
2. **事务化的高性能批量写入接口**
- 提供 `write_timeseries_batch(table: &TimeseriesTable, data_points: &[DataPoint]) -> TransactionResult` 专用API。
- 该批量写入操作**必须**作为一个完整的ACID事务（US-205）来执行，确保一批数据要么全部成功插入并立即可见，要么全部回滚。
- 性能目标：
- 通用嵌入式硬件：单次批量写入1000个数据点延迟 **< 8毫秒**，吞吐量不低于 **12万点/秒**
- 100MHz单核嵌入式CPU：单次批量写入1000个数据点延迟 **< 5毫秒**，吞吐量达到 **> 20万点/秒**（US-405优化目标）
3. **多层压缩存储架构**
- **写入时内存压缩**：数据在内存中按列式组织，并应用指定的压缩算法（如Delta-of-Delta、Gorilla），形成不可变的压缩数据块。对典型规则采样的传感器数据，压缩比 **> 3:1**。
- **持久化存储压缩**：当压缩数据块通过WAL（US-107）持久化或创建快照时，**直接写入压缩后的格式**，避免解压再压缩的开销，使持久化I/O数据量减少 **60%** 以上。
- 提供 `COMPRESSION_SAVING_RATIO` 等元数据查询，供监控存储效率。
4. **资源效率与确定性**
- 整个时序数据通路（接收、压缩、事务管理、持久化）的内存使用必须有静态上限，可通过配置预分配。
- 压缩与持久化操作应在后台线程或异步任务中执行，不得阻塞前端实时数据写入管道。
- 压缩上下文内存占用 **< 每数据列 1KB**（US-405优化目标）
**测试场景：**
1. **全链路功能测试**：
- 使用扩展DDL创建一个带压缩和TTL的时序表，并通过过程宏验证生成的代码正确。
- 连续调用批量写入API插入数据，验证数据被自动添加时间戳、成功压缩，并可通过事务进行原子回滚。
- 触发持久化（检查点或日志），验证磁盘文件大小显著小于原始数据大小，并能在重启后正确恢复解压。
2. **性能与一致性基准测试**：
- **吞吐量与延迟**：在持续写入负载下，测量从调用写入API到数据被提交并完成内存压缩的全流程延迟分布（P99）。
- **压缩比验证**：写入不同类型时序数据（平稳、随机、周期性），计算内存和磁盘的实际压缩比，与目标值（如3:1）进行对比。
- **事务一致性**：在批量写入过程中模拟故障，重启后验证数据库处于一致状态，不会出现“半批次”数据。
3. **资源监控测试**：
- 长时间运行高负载写入，观察内存增长情况，确保无泄漏且符合预分配预期。
- 监控在开启压缩和持久化时，CPU使用率是否保持在可接受范围内（如比未开启时增加不超过15%）。
---
#### **US-405：面向嵌入式设备的高效时序数据写入（已合并至US-404）**
**状态：** 已合并至US-404，作为US-404的嵌入式硬件优化增强子需求
**核心优化内容已整合到US-404的以下部分：**
1. **批量写入性能优化**：针对100MHz单核嵌入式CPU的性能目标（延迟<5毫秒，吞吐量>20万点/秒）
2. **压缩效率优化**：压缩比>3:1的具体要求与压缩上下文内存占用限制
3. **资源效率优化**：预分配内存块避免碎片等内存管理策略
**剩余未整合内容：**
1. **自动时间戳管理**
- 在DDL中通过扩展语法（如 `TIMESTAMP AUTO`）为时序表指定时间戳列。
- 写入时，若该字段值为空，则由数据库引擎自动填充为**高精度单调递增时间戳**（微秒或纳秒级，取决于硬件支持）。
- 支持基于硬件RTC或系统时钟的时间源配置。
**事务标准对齐：**
- US-405原引用的US-031原子事务标准已对齐至US-404使用的US-205 ACID事务标准
- 批量写入操作统一遵循US-205定义的ACID事务要求
**测试场景：**
1. **批量写入性能测试**：模拟持续以每秒10万个数据点的速率写入，持续1分钟，验证吞吐量稳定且内存增长可控，无明显的性能下降。
2. **时间戳正确性测试**：在两个设备间进行高频率写入，验证自动生成的时间戳全局单调递增，且精度符合预期。
3. **压缩效率测试**：写入不同类型的数据（规则变化的整数、随机浮点数），验证压缩后内存占用符合预期比例，并测量压缩/解压操作对CPU使用率的影响（应 **< 5%**）。
4. **恢复与一致性测试**：在批量写入过程中模拟断电，重启后验证已持久化数据（若启用）的完整性和时间戳序列的连续性。
#### **US-406：面向实时分析的时序数据智能查询**
**作为** 需要在边缘端进行实时数据分析的工程师，**我希望** 数据库提供一套高度优化的时序数据查询原语，支持快速的范围过滤、聚合、降采样与智能插值，**以便于** 直接在数据产生的位置进行低延迟的实时统计与概要分析，而无需将原始数据全部传回云端。
**验收条件：**
1. **高效时间范围扫描**
- 为时间戳列自动创建并维护**专用时间索引**（如分层式时间索引或TST树）。
- 性能要求：在1亿个数据点的表中，查询任意1小时时间窗口内的所有数据，延迟 **< 100毫秒**。
- 查询计划能高效地利用时间索引，跳过不相关的数据块。
2. **内置流式聚合函数**
- 提供针对时序的内置聚合函数：`sum`, `avg`, `min`, `max`, `count`, `stddev`，以及针对非规则数据的 `first`, `last`。
- 支持在时间范围查询后进行**分组聚合**，例如“按每5分钟统计平均温度”。
- 聚合计算应充分利用预聚合数据（如有）或向量化执行，避免逐点计算。
3. **自动降采样查询**
- 提供 `SAMPLE BY` 子句，例如 `SELECT avg(value) FROM metrics SAMPLE BY 1h`。
- 引擎能够根据降采样粒度，自动从最合适的数据源获取数据（如从分钟级聚合物化视图中读取，而非扫描秒级原始数据）。
- 降采样查询性能应比扫描原始数据快 **1个数量级** 以上。
4. **智能插值处理**
- 为查询提供 `FILL` 子句，以处理时间序列中的缺失点，支持插值策略：`PREV`（前值）、`LINEAR`（线性）、`NEXT`（后值）、固定值。
- 插值逻辑在查询引擎层高效完成，避免对应用层暴露数据缺失的复杂性。
5. **资源可控的查询执行**
- 所有查询操作（特别是全时间范围扫描）的内存使用应有明确上限，防止因大查询导致内存耗尽。
- 提供查询超时机制，避免复杂查询长时间占用CPU。
**测试场景：**
1. **范围查询基准测试**：构建一个包含多年历史数据的超大型时序表，测试随机时间窗口查询的延迟，验证其不随数据总量线性增长，而是由索引效率决定。
2. **聚合准确性测试**：对同一数据集，分别使用数据库内置聚合和全量扫描后外部计算的结果进行对比，必须完全一致。
3. **降采样性能对比**：对同一查询，分别使用 `SAMPLE BY` 和不使用（在应用层处理）进行对比，验证数据库内置降采样在延迟和CPU使用上的优势。
4. **插值功能测试**：构造有规律缺失的数据序列，使用不同 `FILL` 策略查询，验证返回的结果符合该插值算法的预期，并且处理延迟可接受。
5. **混合负载测试**：在持续高吞吐数据写入的同时，并发执行多个复杂的时序聚合查询，验证查询性能保持稳定，写入性能不受显著影响（下降 **< 10%**）。
---
### **阶段五：服务器版**
**百万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小时）
- 极端场景测试（连接闪断、内存压力等）
---
## 基于STM32F4的高频数据采集程序示例
### **US-601：可靠的高频传感器数据采集与缓存**
**作为** 嵌入式数据采集系统开发者，**我希望** MCU能够利用DMA和双缓冲技术，可靠、不间断地采集多路高频传感器数据（例如≥1KS/s），并缓存在应用层队列中，**以便于** 为上层处理任务提供稳定、连续的数据流，确保在100%的CPU负荷下也不丢失任何采样点。
**验收条件：**
1. 使用ADC DMA配合定时器触发，实现不低于 **1KS/s/通道** 的采样率，且实际采样周期抖动小于 **1%**。
2. 实现**双缓冲DMA传输**，在半满/全满中断中，将数据快速搬移至应用层的无锁环形缓冲区，单次中断服务程序（ISR）执行时间小于 **10微秒**。
3. 应用层环形缓冲区容量至少能容纳 **100ms** 的原始采样数据，防止任务调度延迟导致数据溢出。
4. 提供缓冲区水位监控接口，当占用率超过 **75%** 时产生警告，超过 **90%** 时触发错误处理流程。
### **US-602：传感器数据的原子化事务存储**
**作为** 数据处理任务，**我希望** 能够将缓存的原始采样数据块，经过校准和格式化后，以原子事务的方式批量、高效地写入时序数据库，**以便于** 确保每批采集数据的完整性和一致性，并为后续查询提供高性能的访问接口。
**验收条件：**
1. 提供 `sensor_data_batch_insert(sensor_id, &[CalibratedData])` API，将至少 **256个** 数据点作为一批次进行写入。
2. 该API调用必须作为一个**ACID事务（US-205）** 执行，确保整批数据要么全部入库成功，要么全部回滚。
3. 从环形缓冲区读取一批数据，完成校准转换，到成功提交至 `remdb` 的总延迟，99分位线（P99）小于 **20毫秒**。
4. 写入过程应触发数据库的**实时压缩（US-405）**，对规整的传感器数据（如温度、电压）压缩比不低于 **3:1**。
### **US-603：采集数据的实时聚合与发布**
**作为** 监控客户端或边缘计算模块，**我希望** 能够对刚入库的传感器数据进行低延迟的聚合查询（如每秒平均值），并将结果实时发布给网络上的订阅者，**以便于** 实现系统状态的实时监控和快速闭环控制。
**验收条件：**
1. 提供 `query_realtime_aggregate(sensor_id, agg_func, time_window)` API，查询最近时间窗口（如1秒）内的聚合值，其端到端延迟（从查询调用到返回结果）小于 **50毫秒**。
2. 支持将指定的聚合查询结果，通过 **基于UDP的高可靠数据订阅与发布（US-208）** 自动、周期性地向预订阅的客户端组播。
3. 聚合发布任务与数据采集、存储任务的优先级需合理调度，确保发布任务不会阻塞数据采集的实时性。
4. 在网络带宽受限时，UDP发布机制应能保证 **心跳信号** 的优先传输，维持连接状态感知。
---
## 🎯 关键技术决策调整
### **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（如果开源）
---