版本：v3.0 ｜ 状态：评审稿 上游依据：dev_docs/proposl.md（v1）→ dev_docs/proposal-v2.md（v2）＋ 可行性分析 v2 结论 本版变更：确定核心数据模型 项目 → 分支 → 分组 → item（结构项目级强一致、值按分支存储）， 新增跨项目共享库与分支管理（diff / 值提升）；变更说明见 §7
实现一个分布式的配置文档服务：以多实例集群方式运行，配置按 项目 → 分支 → 分组 → item 组织，向多语言应用提供配置的存取、共享、分支对比、变更推送、多格式输出，并以 单二进制、零外部依赖、内嵌管理控制台的方式交付。
- 主体服务：Rust 实现，单二进制交付
- SDK：TypeScript / Go / Python 三种官方 SDK
- 管理端 Web Admin UI 内嵌于服务二进制（R10）
项目 Project（如 order-service）
└── 结构 Structure（项目级，唯一事实源）
│ ├── 分支 Branch：dev（开发）/ test（测试）/ prod（生产）+ 自定义分支
│ ├── 分组 Group：redis / database / auth …
│ │ └── item：{ key, 类型, 校验规则, 是否敏感(secret) }
└── 值 Values（按分支存储）
├── dev ：redis.host = "127.0.0.1" …
├── test：redis.host = "10.0.0.5" …
└── prod：redis.host = "10.0.0.9" …
- 项目：顶级作用域，如 order-service
- 分支：环境维度，默认 dev / test / prod，允许自定义（如 灰度、预发）；新建分支自动继承项目结构
- 分组：配置的逻辑归类（redis、database、auth 等），可嵌套或平铺（v3 默认平铺一层，嵌套列入后续）
- item：最小配置单元：{ key, 类型, 校验规则, 是否敏感(secret), 各分支的值 }
- 结构（分组集合 + 每组的 item 集合）在项目级定义且只定义一次
- 值按分支存储：每个 (分支, item) 一个值，值可为空（未填）
- 不变量：任意时刻，一个项目下所有分支的分组与 item 完全一致，仅值不同
- 由系统保证而非人工维护：item 的新增/删除/改名/改类型均在项目级进行，自动对全部分支生效； 变更值只影响单个分支，变更结构影响全部分支（有预览与确认）
- 分支值完整性校验：必填项未填 → 警告 / 阻断发布（策略可配）
- 每个 (项目, 分支) 维护一个全局 revision：任何结构或值变更都推进该分支的 revision
- SDK 订阅粒度 = (项目, 分支)；watch 事件携带 item key、新值、revision
- 集群级共享配置库（公共账号、密码、基础服务地址等），与项目解耦
- 项目分组可引用共享库（组级或 item 级），渲染/输出时解析
- 共享项变更 → 引用它的所有 (项目, 分支) revision 递增并推送； 默认自动级联 + 审计，可配置为显式发布（防级联风暴）
string / int / float / bool / json / array / secret（secret 强制加密存储，见 R11）
描述：多实例运行；新实例仅需指定集群内任意实例的注册端点即可加入。
- AC1.1 任意实例通过
--join <已有实例端点>加入集群，无需手动同步成员列表 - AC1.2 首节点
--bootstrap自举；其余节点仅凭一个已有实例端点即可加入 - AC1.3 节点数 ≥3 时，任选一节点宕机，读写不中断（多数派存活）
- AC1.4 新节点自动追平历史数据（快照 + 日志回放）后参与服务
描述：集群内多实例共享全部数据，杜绝脑裂导致的数据不一致。
- AC2.1 任意时刻集群至多一个 leader 接受写请求
- AC2.2 写请求返回成功即已复制到多数派并持久化
- AC2.3 网络分区时少数派侧拒绝写入（防脑裂），恢复后数据自动一致
- AC2.4 读可路由任意节点；提供线性一致读选项
描述：SDK 连接失败时自动切换备选节点。
- AC3.1 SDK 接受多端点，连接失败/超时/RPC 错误时自动切换
- AC3.2 切换对业务代码透明（回调/事件通知，不抛业务异常）
- AC3.3 SDK 从服务端动态获取集群成员并更新端点池
- AC3.4 写请求命中非 leader 时服务端返回 leader 重定向，SDK 自动跟随
描述：SDK 订阅指定 (项目, 分支) 的配置，自动感知变更。
- AC4.1 订阅 (项目, 分支) 后，该分支任何 item 值变更或结构变更，SDK 在目标时延（默认 ≤1s）内收到事件
- AC4.2 事件携带 item key、新值、revision；断线重连后从 revision 断点续传，不丢变更
- AC4.3 支持一次订阅多个 (项目, 分支)；监听器动态注册注销
描述：见 §3.1–3.3。配置按项目→分支→分组→item 组织；结构项目级强一致，值按分支。
- AC5.1 项目/分支/分组/item 四级 CRUD
- AC5.2 结构（分组+item）在项目级定义；任意时刻全部分支结构完全一致（系统保证，非人工维护）
- AC5.3 分支可自定义创建/删除，默认提供 dev/test/prod；新建分支自动继承项目结构
- AC5.4 item 类型含 secret，secret 强制加密存储（R11）
- AC5.5 值可为空；分支值完整性校验（必填未填：警告/阻断发布，策略可配）
- AC5.6 结构变更（增删改 item/分组）提供影响预览（波及全部分支）与确认
描述：集群级共享项库，项目分组可引用，降低跨项目重复配置。
- AC6.1 共享项（分组+item）支持 CRUD，敏感项强制加密（R11）
- AC6.2 项目分组可引用共享库（组级/item 级），输出/发布时解析
- AC6.3 循环引用检测（共享项→共享项、项目→共享项）并拒绝发布
- AC6.4 共享项变更 → 引用方所有 (项目, 分支) revision 递增并推送；默认自动级联 + 审计，可配置显式发布
描述：分支间差异对比与值复制（promotion）。
- AC7.1 分支间值对比（diff）：同结构按 key 对比，展示差异与缺失值
- AC7.2 结构一致性校验：任意时刻可校验并展示"全部分支结构一致"状态（正常应恒等）
- AC7.3 值提升（promotion）：支持把源分支（如 dev）的值批量复制到目标分支（如 test/prod）， 复制前校验目标分支缺失项，操作记录审计日志（R13）
- AC7.4 支持单 item、整组、整分支三种粒度的值提升
描述：按 (项目, 分支) 生成完整配置文档，支持 YAML / TOML / JSON。
- AC8.1 按 (项目, 分支) 输出完整配置文档（分组→文档小节），支持 YAML/TOML/JSON
- AC8.2 三格式语义等价（等价性校验测试）
- AC8.3 支持按格式 URL 拉取（
/v1/projects/{p}/branches/{b}/config?format=yaml）与打包下载 - AC8.4 文档 schema 以 TOML 表达力为下限
描述：持续跟踪竞品并维护对比（当前对比见可行性分析 §6）。
- AC9.1 每季度更新竞品对比表
- AC9.2 竞品新功能上线时评估吸收或差异化
描述：管理端 Web UI 与主服务同进程、同端口部署，静态资源编译进二进制。
- AC10.1 单二进制同时提供数据面 API 与管理控制台（默认
/admin） - AC10.2 控制台功能：项目/分支/分组/item 树形管理、分支值编辑、分支对比（diff）、 值提升（promotion）、共享库管理、变更历史/审计、格式预览（YAML/TOML/JSON 三栏）
- AC10.3 默认启用鉴权（初始管理员凭证启动配置或首启自动生成）；同源免 CORS
- AC10.4 前端产物内嵌（基准 ≤5MB），无外链依赖，离线可用
描述：secret 类型 item 与共享库敏感项静态强加密；明文仅按需解密；展示与导出脱敏。
- AC11.1 静态加密使用 AEAD（AES-256-GCM 或 ChaCha20-Poly1305），每项独立数据密钥（信封加密）
- AC11.2 主密钥来源可配置：环境变量 / 密钥文件 / KMS（企业版）；主密钥不明文落盘
- AC11.3 支持主密钥轮换与数据密钥版本化，轮换不中断服务
- AC11.4 明文仅存在于解密瞬间；存储/备份/导出均为密文；界面与导出默认掩码展示
- AC11.5 secret 类型 item 与共享库敏感项的读取/导出触发审计日志（R13）
描述：单二进制、零外部依赖（无数据库、无消息中间件）、默认即用。
- AC12.1 仅两个核心启动参数即可跑通：
--bootstrap/--join <endpoint>，其余全部有默认值 - AC12.2 存储内嵌，不依赖外部数据库
- AC12.3 配置覆盖优先级：环境变量 > 配置文件 > 命令行参数
- AC12.4 基准目标：单机最小内存 ≤128MB；二进制 ≤50MB（含 Admin UI）
- AC12.5 提供 Docker 镜像与 docker compose 一键三节点示例
描述：健康检查、指标、结构化日志、审计日志。
- AC13.1 提供
/healthz与/readyz - AC13.2 Prometheus 指标：节点角色、Raft 状态、QPS/延迟、watch 连接数、成员数、 结构一致性状态（全部分支结构恒等）、共享库引用数
- AC13.3 结构化日志（可选 JSON）；管理操作 / 密钥访问 / 值提升 审计可查询
- AC13.4 可选 OpenTelemetry 追踪（企业版）
| 类别 | 要求（基准值，后续压测校准） |
|---|---|
| 性能 | 单节点写 QPS ≥ 10k；watch 并发连接 ≥ 10k；单项目分支数 ≤ 100 时结构校验延迟 < 100ms |
| 安全 | 全链路 TLS 可选（默认提示开启）；管理端强制鉴权；secret 项加密（R11） |
| 可移植性 | 静态编译；Linux x86_64 / arm64 为主，macOS 支持开发 |
| 兼容性 | 数据模型与 SDK 协议版本化（v1 起），向后兼容策略明确 |
| 可靠性 | 故障注入测试（分区/丢包/重启）通过后方可发布 |
- 分支级细粒度权限（如"生产分支仅运维可改"）——列入企业版（RBAC）
- 服务发现 / 注册中心：不承接 Nacos/Consul 的发现业务
- 完整密钥生命周期管理：动态密钥轮换、加密网关交给 Vault 类系统；本项目只做静态加密 + 脱敏
- 灰度发布、多租户、SSO、审计报表：企业版路线图，不进开源 MVP
| 变更 | 理由 / 决策 |
|---|---|
| 新增 §3 核心数据模型：项目→分支→分组→item | 本次用户决策：配置按 项目→分支 组织；分支默认 dev/test/prod 且可自定义 |
| 结构强一致：结构定义在项目级，值按分支存储 | 本次用户决策：由系统保证全部分支结构恒等，仅值不同 |
| 原 R5"共享配置项"拆分为 R5（项目内共享，由结构强一致天然满足）＋ R6（跨项目共享库） | 本次用户决策：共享项升级为集群级共享库，项目可引用 |
| R4 订阅粒度改为 (项目, 分支) | 与数据模型对齐 |
| 新增 R7 分支管理（diff / 值提升） | 结构强一致的直接衍生价值：分支对比与值复制 |
| R8 多格式输出改为按 (项目, 分支) 输出完整文档 | 文档 = 某项目某分支的全部配置 |
| R10 Admin UI 增加树形管理 / diff / promotion / 共享库管理 | 与数据模型对齐 |
| R11 加密覆盖 secret 类型 item 与共享库敏感项 | 与数据模型对齐 |
| R13 增加结构一致性指标 | 让"结构强一致"可观测可验证 |
| 编号整体后移：原 R8→R10、R9→R11、R10→R12、R11→R13 | 插入 R5–R7 后重新编号 |