13. 差距清单与演进建议
本章汇总前 12 章发现的所有问题，按优先级排序，并给出能力完成度评估与演进路线建议。
1. 能力完成度评估
1.1 SOVD 能力矩阵（22 项）
| 能力 |
状态 |
说明 |
版本发现 /version-info |
✅ |
含 vendor_info、include-schema |
| 实体集合（components/apps/areas） |
✅ |
含 tags 过滤 |
| 实体能力（capabilities） |
⚠️ |
字段齐全，仅填充约 9 项 |
| 关系 hosts / belongs-to / is-located-on / contains |
✅ |
双向一致性由 E2E 保证 |
| data（list/read/write/categories/groups） |
✅ |
含过滤与 schema |
| include-schema |
✅ |
但每次重算、list 丢弃 item schema |
| 错误模型 GenericError |
⚠️ |
15 个 error_code 仅用 5 个 |
| 传输：TCP / UDS / TLS / mTLS |
✅ |
含 systemd socket activation |
| CORS / 静态文件 / 自定义 Tower 层 |
✅ |
|
| 认证（JWT HS512/RS512） |
✅ |
但有 iss 绕过等缺陷 |
| 授权（Rego） |
⚠️ |
可用但 input 信息过少 |
| 客户端 SDK |
✅ |
缺超时默认值与重试 |
| MCP 集成 |
⚠️ |
仅 3 个只读 tool |
| 发现/聚合（DiscoveryProvider） |
⚠️ |
仅 trait + 测试 mock，无 mDNS |
functions 实体 |
❌ |
未建模 |
faults（DTC） |
❌ |
社区 issue 已列 |
operations（例程） |
❌ |
|
configurations |
❌ |
|
bulk-data |
❌ |
|
data-lists |
❌ |
|
modes / locks |
❌ |
|
logs / communication-logs / cyclic-subscriptions |
❌ |
无任何推送机制 |
updates（刷写） |
❌ |
|
subcomponents / subareas / depends-on |
❌ |
|
量化 ：24 项中完整实现 11 项（含传输与安全等基础设施），SOVD 业务能力 4/22 ≈ 18%。
1.2 成熟度总评
| 维度 |
评分 |
说明 |
| 工程与代码质量 |
★★★★☆ (4.5/5) |
87% 覆盖、严格 lint、完整 CI、容器与发布 |
| 架构设计 |
★★★★☆ (4.0/5) |
依赖单向、扩展点清晰；个别反向依赖与 trait 位置待优化 |
| 协议符合度 |
★★☆☆☆ (2.0/5) |
骨架完整、肌肉缺失 |
| 生产可用性 |
★★☆☆☆ (2.0/5) |
无持久化、无故障/操作能力、默认无安全、定位未收敛 |
| 性能与并发 |
★★★☆☆ (3.0/5) |
读锁跨 await、O(n) 删除、schema 重算、Rego 引擎克隆 |
2. 缺陷总表（按优先级）
P0 ------ 阻塞生产/安全或导致数据错误
| # |
问题 |
章节 |
影响 |
| 1 |
拓扑索引不对称清理（覆盖写入/删除/重插） |
04 |
查询结果自相矛盾；测试已错误固化行为 |
| 2 |
JWT 未强制 iss → 无 issuer 令牌可绕过 |
08 |
安全绕过 |
| 3 |
WriteRequest.signature 被解析但从不校验 |
05 |
车载写操作无完整性保护 |
| 4 |
默认 NoAuth + AllowAll（生产不设防） |
08 |
开箱即不安全 |
| 5 |
base_uri 硬编码 /sovd 与 http:// |
06 |
反代/TLS 部署链接错误 |
| 6 |
读锁跨 await（根因：Box<dyn DataProvider>） |
07 |
慢 provider 阻塞全部写入 |
| 7 |
客户端 connect() 无超时；查询串不编码 |
09 |
挂起 / 请求串被破坏 |
| 8 |
索引一致性无属性测试 |
12 |
缺陷无法被自动发现 |
| 9 |
is_readable/is_writable 未出现在 API |
03 |
客户端只能试探写 |
P1 ------ 显著影响可用性或正确性
| # |
问题 |
章节 |
| 10 |
事件系统：无快照订阅、容量 64、Drop 中持锁发送 |
04 |
| 11 |
remove_component 不级联、remove_area 留悬空引用 |
04 |
| 12 |
discovery 静默降级、无重连、无 panic 隔离 |
04 |
| 13 |
shift_remove 导致批量删除 O(N²) |
04 |
| 14 |
读 write-only 资源 → 500；写只读 → 400（应为 405） |
05 |
| 15 |
include-schema 每次重算；list 丢弃 item schema |
05 / 07 |
| 16 |
groups+categories 同传被静默丢弃 |
07 |
| 17 |
写请求体无 WithRejection，破坏统一错误格式 |
07 |
| 18 |
Rego input 信息过少（无 entity/data/peer） |
08 |
| 19 |
Rego 每请求克隆引擎 |
08 |
| 20 |
mTLS 证书身份未进入 identity；无速率限制/审计 |
08 |
| 21 |
MCP 错误全降级为 internal_error；instructions 与实际能力不符 |
11 |
| 22 |
覆盖率无门禁；写链路无正向用例 |
12 |
| 23 |
健康检查端点缺失；就绪通知偏早 |
10 |
| 24 |
opensovd-extra 反向依赖 server（trait 应下沉） |
02 |
| 25 |
JWT 密钥仅支持命令行传入 |
10 |
P2 ------ 改进体验与可维护性
| # |
问题 |
章节 |
| 26 |
App::component_id() 恒 Some，抽象冗余 |
03 |
| 27 |
Function 实体未建模（或需明确文档声明） |
03 |
| 28 |
EntityCollection 无去重、ID 无校验 |
03 |
| 29 |
DataError 变体不足（无 InvalidValue/Unauthorized/Unavailable） |
05 |
| 30 |
builder 后置修饰器静默失效 |
05 |
| 31 |
feature 泄漏（providers 硬依赖 schemars） |
02 |
| 32 |
nightly 锁定、无 MSRV、无 semver release |
02 |
| 33 |
Bearer 大小写敏感；无 JWKS/轮转 |
08 |
| 34 |
客户端无重试/熔断；关系查询返回类型不一致 |
09 |
| 35 |
MCP 工具名无前缀；resource 无分页/缓存 |
11 |
| 36 |
无 /metrics、无 request id 贯穿 |
06 / 10 |
3. 演进路线建议
阶段一：质量与正确性加固（1~2 个月）
目标：不新增能力，把已有能力做对、做稳。
- 修复 P0 全部 9 项（索引一致性、JWT iss、signature 校验入口、生产强制鉴权、base_uri 派生、
Arc<dyn DataProvider> + 放锁、客户端超时/编码、proptest、metadata 可写性字段）
- 为拓扑引入
proptest 不变量测试，并修正被错误固化的测试
- 覆盖率设门禁（如
--fail-under 85 且不允许下降）
验收：E2E 在反代 + TLS 场景下链接正确；拓扑随机操作后正/反查恒一致；无鉴权配置时生产模式拒绝启动。
阶段二：能力补齐第一步 ------ faults 与 operations（2~4 个月）
目标：让 OpenSOVD 从"数据网关"变成"能用的诊断服务"。
- 设计
FaultProvider（类比 DataProvider）：list/read/clear + 冻结帧/扩展数据记录
- 实现
/v1/{entity}/{id}/faults[/...] 路由，并在 EntityCapabilities 中填充 faults href
- 设计
OperationProvider：list + 启动/停止/查询状态（含异步操作状态机）
- 补充对应错误码映射（
precondition-not-fulfilled 等）
社区已有 issue：Improvement: implement the faults resource (ISO 17978-3)。这是收益最高的能力扩展------DTC 是诊断的第一诉求。
阶段三：生产化与生态（4~8 个月）
- 持久化：DTC/配置/历史的 NVM 落盘（当前全内存，重启即失）
- 发现实现 ：mDNS/SD 的
DiscoveryProvider（社区 issue 已列），打通真正的网关级联
- 推送机制 ：
cyclic-subscriptions（SSE 或 WebSocket），替代轮询
- 运维能力 ：
/metrics、/healthz、结构化审计日志、配置文件支持
- 客户端增强 ：重试/熔断、认证（issue 已列）、
capabilities()
- MCP 增强：数据读写 tool、能力查询 tool、elicitation 人工确认
- 发布治理：semver release + CHANGELOG + MSRV
阶段四：车规化（长期）
- 评估 nightly → stable 迁移
- 引入 fuzz 与变异测试
- 安全认证支撑（ISO 21434 / UNECE R155 相关证据：签名、审计、最小权限）
- 与
classic-diagnostic-adapter、uds2sovd-proxy、odx-converter 的端到端联调，形成"遗留 ECU → SOVD"完整链路
4. 对使用者的建议
| 你的目的 |
建议 |
| 学习 SOVD 协议与架构 |
强烈推荐：代码干净、能力模型完整、测试充分，是最好的 SOVD 活样本 |
| 作为数据面网关原型 / POC |
推荐 ：--mock 一条命令即可跑通全链路，MCP 集成可直接接 LLM |
| 二次开发（自定义 provider / 鉴权） |
推荐：扩展点设计清晰；注意先修复 P0 中的索引与 base_uri 问题 |
| 生产部署 |
不推荐直接使用：无持久化、默认无安全、能力覆盖不足，需完成阶段一 + 阶段二 |
| 作为完整诊断服务器 |
不适用：故障/例程/配置/刷写全部缺失 |
5. 附录：与社区 issue 的对应
| 社区 open issue（2026-09 抽样） |
本分析对应章节 |
Improvement: implement the faults resource (ISO 17978-3) |
阶段二 / 01 §4 |
feat: add mDNS discovery and gateway advertisement |
阶段三 / 04 §4.4 |
fix(server): derive advertised uris from the configured base uri |
P0-5 / 06 §4.3 |
feat(client): Add authentication / Add retry policy / add capabilities() |
09 §4.2/§4.4 |
feat(mcp): advertise output schema on list tools |
11 §4.1 |
feat: add support for data/docs |
05 §4 |
Clarification on SOVD Gateway vs SOVD Server Architectural Model |
定位问题，影响阶段二/三的取舍 |