大更新

backend/library/DESIGN.md

@@ -366,7 +366,7 @@ Adminive 字段默认是 intrinsic read-only。
 
 同步、事务和适配器可以据此建立正确行为。
 
-## 7. 四种字段声明语义
+## 7. 五种字段声明语义
 
 ### 7.1 普通字段
 
@@ -432,6 +432,8 @@ intrinsic read-write
 
 适合配置加载、后台代码、服务内部更新等受控路径。
 
+`readable(false)`、`sensitive()`、`required()` 和 `include_default(false)` 是独立的消费/呈现策略，不改变 `.read_write()`、`.editable()`、`.creatable()` 建立的 intrinsic writable 事实。Gallery 的 Field Policy Matrix 直接从 Descriptor 类型生成这些策略，前端不维护第二份字段能力表。
+
 ### 7.5 `.unsynchronized()`
 
 ```cpp
@@ -754,6 +756,24 @@ CRUD schema
 
 前端可以拥有纯 UI 行为，但不应该成为第二份业务 Schema。
 
+### 17.1 Capability Case Registry
+
+示例画廊不能维护一份和真实实现脱离的 capability 字符串。每个可宣称的能力必须对应一个 Case，Case 至少绑定：
+
+```text
+id / group / title / summary
+C++ declaration
+View or Manifest JSON
+runtime or renderer JSON
+preview
+endpoints
+tags
+```
+
+总览能力矩阵、活文档和 endpoint 索引从 Case Registry 派生。这样“文档说支持”必须同时能指向协议、运行时入口或自动测试。新增能力如果没有 Case，就不应该自动出现在完整能力清单中。
+
+Collection 能力实验台也遵守这个原则：paging/sort/search/filter/row reorder/status 发送真实 HTTP；column reorder 属于前端表现状态，因此只消费 `column_reorderable` 授权，不伪造后端业务请求。协议边界页直接重复执行非法 Composition、Manifest、readonly、validation、polymorphic 和 Collection query，而不是复制预先写好的错误文字。
+
 ## 18. 编译期与运行期的分工
 
 Adminive 建议遵守以下规则：
@@ -970,6 +990,35 @@ Config Store persistence
 
 这些测试保护的是设计边界，而不仅是当前实现细节。
 
+### 23.6 Release-safe assertion contract
+
+测试断言不能依赖标准 `assert()`。Release 默认定义 `NDEBUG`，如果测试仍使用 `assert()`，CTest 通过并不能证明表达式被执行。Adminive 测试统一使用始终生效的 `ADMINIVE_CHECK`；`static_assert` 继续用于编译期契约。旧同步 API 的测试文件不保留兼容实现，有价值的并发、nested、unsynchronized 和 callback lifetime 用例迁移到当前 `Managed_Value` 测试。
+
+### 23.7 Transport 与安装黑盒测试
+
+Service 单元测试不能替代 transport 黑盒测试。Httplib adapter test 必须启动真实 localhost server，再通过 client 请求 descriptor/view/data/amis、Resource Context、Collection CRUD/query/reorder/status 和错误状态。Drogon 保持独立 adapter contract test。
+
+安装测试必须先执行 `cmake --install` 到构建目录内的固定 prefix，再从独立 consumer 工程只通过 `find_package(Adminive)` 配置和运行。测试 consumer 不允许使用源码 include path，否则无法发现 export/install 错误。
+
+### 23.8 Verification Gate
+
+发布前 Gate 至少包含：
+
+```text
+Debug full build + CTest
+Release full build + CTest
+ASan + UBSan
+TSan concurrency tests
+frontend unit tests
+frontend production build
+Playwright Chromium E2E
+Playwright Edge E2E on Windows
+install consumer
+real HTTP integration
+```
+
+CTest label 用于按 `unit/protocol/http/install/package/concurrency/frontend/e2e` 分层定位失败。ASan+UBSan 对 Core Adapter、Advanced Adapter、Safety、Managed、View Schema、Drogon 与真实 Httplib 运行 sanitizer 矩阵，TSan 单独覆盖并发 Managed 路径；Sanitizer 是测试配置，不改变 Core API。frontend E2E 验证同一 Manifest 五种布局、Form modes、Collection CRUD/query/reorder/status、422 nested validation、Sensitive 输出过滤、Object Adapter transaction counter、transaction rollback、状态序列、协议错误和缓存策略。Gate 使用确定的目录和端口，不依赖随机构建路径。
+
 ## 24. 设计判断清单
 
 在提交一个新设计前，可以快速检查：