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中填充faultshref - 设计
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 |
定位问题，影响阶段二/三的取舍 |