This is an automated email from the ASF dual-hosted git repository.
zyxxoo pushed a commit to branch refactor/rust-rewrite-design
in repository https://gitbox.apache.org/repos/asf/hugegraph.git
The following commit(s) were added to refs/heads/refactor/rust-rewrite-design
by this push:
new b22bc0b43 docs: mark Rust rewrite materials review ready
b22bc0b43 is described below
commit b22bc0b430243f47596a8aefb2ef1830391751cb
Author: vaughn <[email protected]>
AuthorDate: Thu Sep 10 01:22:17 2026 +0800
docs: mark Rust rewrite materials review ready
---
docs/rust-engineering-standard.md | 2 +-
docs/rust-rewrite-acceptance-matrix.md | 2 +-
docs/rust-rewrite-design.md | 6 ++++-
docs/rust-rewrite-partition-pilot.md | 47 ++++++++++++++++++++++++++++++++++
docs/rust-rewrite-test-inventory.md | 2 +-
5 files changed, 55 insertions(+), 4 deletions(-)
diff --git a/docs/rust-engineering-standard.md
b/docs/rust-engineering-standard.md
index 47b8ab130..a853ce87e 100644
--- a/docs/rust-engineering-standard.md
+++ b/docs/rust-engineering-standard.md
@@ -1,6 +1,6 @@
# HugeGraph Rust 工程规范
-状态：设计草案；Rust 子项目建立后应转为仓库级强制规范。
+状态：审核版；Rust 子项目建立后应转为仓库级强制规范。
本规范参考 TiKV、raft-rs 和 Tokio 的公开实践。TiKV
将格式化、Clippy、静态检查和多配置测试集中到开发门禁，并维护工具链、格式、Clippy 和依赖审计配置；raft-rs 对共识代码采用更严格的评审并要求
Clippy/rustfmt【https://github.com/tikv/tikv/blob/master/Makefile】【https://github.com/tikv/raft-rs/blob/master/CONTRIBUTING.md】。Tokio
明确 MSRV、语义化版本和长期支持策略，并使用 Loom 做并发排列测试、Miri
做未定义行为检查【https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md】【https://github.com/tokio-rs/tokio/blob/master/docs/contributing/pull-requests.md】。
diff --git a/docs/rust-rewrite-acceptance-matrix.md
b/docs/rust-rewrite-acceptance-matrix.md
index 69fe0213f..d4db67059 100644
--- a/docs/rust-rewrite-acceptance-matrix.md
+++ b/docs/rust-rewrite-acceptance-matrix.md
@@ -1,6 +1,6 @@
# Rust 重构验收矩阵
-状态：第一轮盘点完成；“已发现”不等于“已通过”。本矩阵是迁移的强制门禁。
+状态：审核版模板；“已发现”不等于“已通过”。本矩阵是迁移的强制门禁，实际通过状态须由 POC 和测试报告填写。
## 1. 现有测试资产覆盖盘点
diff --git a/docs/rust-rewrite-design.md b/docs/rust-rewrite-design.md
index 70291b09e..83f7ebf17 100644
--- a/docs/rust-rewrite-design.md
+++ b/docs/rust-rewrite-design.md
@@ -1,6 +1,6 @@
# HugeGraph Rust 重构设计
-状态：设计草案
+状态：审核版（POC 验证项已单独标注）
## 1. 背景与目标
@@ -168,6 +168,10 @@ Rust 实现只有在以下条件同时满足后才能接管一条生产路径：
只有当上述交付物通过恢复、兼容性和性能门槛后，才进入 Store 写路径迁移。
+## 12. 文档审核门
+
+本设计文档、测试资产盘点、验收矩阵和工程规范组成一套审核材料。审核人应逐项确认：目标与非目标清楚；迁移边界和阶段出口可执行；外部契约有对应
Oracle；现有测试入口已登记；Rust 工程规范可由 CI 强制；风险有回滚措施；所有依赖 POC 的结论已标注为待验证。文档审核通过只代表方案可进入
POC，不代表 Rust 实现已经满足生产验收。
+
## 11. 集成测试盘点与小步替换流程
重构开始前先做测试资产盘点，不能先写 Rust 实现再围绕实现补测试。盘点结果至少包括：现有测试覆盖的
API、Schema、索引、事务、后端、故障和权限场景；每个场景的前置数据、操作序列、断言类型、是否依赖时序以及是否能在独立环境重放。对测试按“契约测试、模型测试、回归测试、性能测试、故障测试”分类，并标记空白区域和仅验证实现细节的用例。
diff --git a/docs/rust-rewrite-partition-pilot.md
b/docs/rust-rewrite-partition-pilot.md
new file mode 100644
index 000000000..a20c668fc
--- /dev/null
+++ b/docs/rust-rewrite-partition-pilot.md
@@ -0,0 +1,47 @@
+# PD Partition 契约盘点试点
+
+状态：POC 计划（文档审核通过后执行）。本文定义验证方法和通过条件，不将计划当作已完成验证。
+
+这是将测试盘点方法落地的第一个试点边界。选择 Partition 是因为它同时包含状态变更、心跳、清理任务和合并操作，且存在 core/service
两层测试。
+
+## 1. 当前实际测试入口
+
+| 测试类 | 已发现方法 | 执行入口 |
+| --- | --- | --- |
+| `pd/core/PartitionServiceTest` |
`testCombinePartition`、`testCombinePartition2`、`testHandleCleanTask`、`testPartitionHeartbeat`
| `hg-pd-test`，`pd-core-test`（需用 Surefire 报告确认） |
+| `pd/service/PartitionServiceTest` |
`testCombinePartition`、`testCombinePartition2`、`testHandleCleanTask` |
`hg-pd-test`，service/rest 相关 profile（需确认） |
+| `pd/common/PartitionUtilsTest` | 以类中实际 `@Test` 方法为准 | common profile（需确认） |
+| `pd/common/PartitionCacheTest` | 以类中实际 `@Test` 方法为准 | common profile（需确认） |
+
+## 2. 独立契约与 Oracle
+
+| 契约 | 独立 Oracle | 现有状态 |
+| --- | --- | --- |
+| 分区合并不丢失或重复范围 | 分区范围不重叠、覆盖集合等价、版本单调 | 有测试，未见统一不变量比较器 |
+| 心跳更新只接受合法节点/版本 | 状态机不变量和拒绝矩阵 | 有测试，需补过期、乱序和重复心跳 |
+| 清理任务幂等 | 重复执行后的状态摘要相同 | 有测试，需补崩溃重试 |
+| 缓存失效后读到最新元数据 | 服务端状态与缓存结果等价 | 有测试，需补并发失效 |
+| 合并/迁移期间的故障恢复 | 操作日志重放后状态等价 | 缺少明确端到端故障 Oracle |
+
+## 3. 负向验证
+
+试点必须先加入能杀死错误实现的测试，再进行 Rust 实现。至少验证以下人为缺陷会失败：
+
+1. 合并时丢弃右侧分区；
+2. 接受更旧版本的心跳覆盖新状态；
+3. 清理任务重复执行产生重复副作用；
+4. 缓存失效通知丢失后继续返回旧元数据；
+5. 节点重启后恢复出不连续的分区范围。
+
+若任一缺陷无法被测试发现，应先修订 Oracle 或补测，不能把该边界标记为可迁移。
+
+## 4. 试点完成条件
+
+- 逐方法确认真实 profile 和 CI job；
+- 每个方法映射到契约编号和 Oracle 类型；
+- 补齐乱序、重复、崩溃、重启和恢复场景；
+- 完成至少五类错误注入并全部被测试捕获；
+- Java 基线与 Rust 实现通过相同确定性历史的规范化比较；
+- 产出包含输入、seed、配置、日志、差异和结论的报告。
+
+试点通过后，复制模板到 Store Snapshot、事务和 Raft 成员变更；试点未通过时，暂停生产路径迁移。
diff --git a/docs/rust-rewrite-test-inventory.md
b/docs/rust-rewrite-test-inventory.md
index 05bc63354..02fba88e3 100644
--- a/docs/rust-rewrite-test-inventory.md
+++ b/docs/rust-rewrite-test-inventory.md
@@ -1,6 +1,6 @@
# Rust 重构测试资产盘点（初版）
-状态：盘点进行中。本文记录可重复的现状扫描结果，不把测试数量当作完备性证明。
+状态：审核版底稿。本文记录可重复的现状扫描结果；方法级语义确认和 POC 结果不在本文件中冒充完成。
## 1. 可重复统计
