pomaster 0.4.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/README.md +102 -183
  2. package/catalog/catalog-lock.draft.json +117 -117
  3. package/catalog/policies/policy.ai.change_plan_first.json +1 -1
  4. package/catalog/policies/policy.ai.fact_inference_separation.json +1 -1
  5. package/catalog/policies/policy.ai.read_search_verify_before_write.json +1 -1
  6. package/catalog/policies/policy.ai.rule_relaxation_approval.json +1 -1
  7. package/catalog/policies/policy.arch.adr_immutable_history.json +1 -1
  8. package/catalog/policies/policy.arch.no_convenience_over_boundary.json +1 -1
  9. package/catalog/policies/policy.arch.prefer_verifiable_option.json +2 -2
  10. package/catalog/policies/policy.authz.no_gating_proxy_trust.json +1 -1
  11. package/catalog/policies/policy.authz.permission_scope_expansion_gate.json +1 -1
  12. package/catalog/policies/policy.authz.server_five_factor_verification.json +1 -1
  13. package/catalog/policies/policy.be.conc.prefer_db_constraints.json +1 -1
  14. package/catalog/policies/policy.be.db.expand_migrate_contract.json +1 -1
  15. package/catalog/policies/policy.be.idem.key_payload_conflict.json +1 -1
  16. package/catalog/policies/policy.be.model.single_boundary_conversion.json +1 -1
  17. package/catalog/policies/policy.be.sql.index_for_known_queries.json +1 -1
  18. package/catalog/policies/policy.be.state.single_rule_source.json +1 -1
  19. package/catalog/policies/policy.be.txn.short_locks_compensation.json +1 -1
  20. package/catalog/policies/policy.bound.search_first_entry_only.json +1 -1
  21. package/catalog/policies/policy.boundary.validate_in_encode_out.json +1 -1
  22. package/catalog/policies/policy.cache.failure_mode_guards.json +1 -1
  23. package/catalog/policies/policy.cache.schema_versioning.json +1 -1
  24. package/catalog/policies/policy.cfg.config_attribute_completeness.json +1 -1
  25. package/catalog/policies/policy.cfg.key_rename_dual_read.json +1 -1
  26. package/catalog/policies/policy.cfg.no_secret_dispersal.json +1 -1
  27. package/catalog/policies/policy.cfg.production_safe_defaults.json +1 -1
  28. package/catalog/policies/policy.cfg.schema_backed_config.json +1 -1
  29. package/catalog/policies/policy.chg.no_unrelated_changes.json +1 -1
  30. package/catalog/policies/policy.contract.no_invented_facts.json +1 -1
  31. package/catalog/policies/policy.dep.build_path_supply_chain.json +1 -1
  32. package/catalog/policies/policy.dep.no_untrusted_source_no_lock_bypass.json +1 -1
  33. package/catalog/policies/policy.dep.time_boxed_urgent_exception.json +1 -1
  34. package/catalog/policies/policy.deploy.no_dev_env_as_production_fact.json +1 -1
  35. package/catalog/policies/policy.deploy.operational_capabilities.json +1 -1
  36. package/catalog/policies/policy.deploy.runtime_fact_record.json +1 -1
  37. package/catalog/policies/policy.err.failure_five_part_mapping.json +1 -1
  38. package/catalog/policies/policy.err.no_internal_detail_exposure.json +1 -1
  39. package/catalog/policies/policy.err.published_code_immutable.json +1 -1
  40. package/catalog/policies/policy.evid.acceptance_binds_verifiable_evidence.json +1 -1
  41. package/catalog/policies/policy.evid.no_silent_gate_removal.json +1 -1
  42. package/catalog/policies/policy.evid.no_unverifiable_pass.json +1 -1
  43. package/catalog/policies/policy.flag.cleanup_after_full_rollout.json +1 -1
  44. package/catalog/policies/policy.flag.consistent_off_state.json +1 -1
  45. package/catalog/policies/policy.flag.kill_switch.json +1 -1
  46. package/catalog/policies/policy.flag.lifecycle_metadata.json +1 -1
  47. package/catalog/policies/policy.flag.not_a_permission.json +1 -1
  48. package/catalog/policies/policy.gate.p0_non_bypassable.json +1 -1
  49. package/catalog/policies/policy.gate.risk_factors_confirmed.json +1 -1
  50. package/catalog/policies/policy.guard.no_check_weakening.json +2 -2
  51. package/catalog/policies/policy.integration.call_definition_minimum.json +1 -1
  52. package/catalog/policies/policy.integration.fault_containment.json +1 -1
  53. package/catalog/policies/policy.job.lifecycle_definition.json +1 -1
  54. package/catalog/policies/policy.job.no_unmanaged_execution.json +1 -1
  55. package/catalog/policies/policy.job.operational_features.json +1 -1
  56. package/catalog/policies/policy.obs.actionable_signals.json +1 -1
  57. package/catalog/policies/policy.obs.alert_with_owner.json +1 -1
  58. package/catalog/policies/policy.obs.context_field_baseline.json +1 -1
  59. package/catalog/policies/policy.obs.no_sensitive_or_unbounded_logging.json +1 -1
  60. package/catalog/policies/policy.obs.no_sensitive_raw_values.json +1 -1
  61. package/catalog/policies/policy.obs.signal_change_impact.json +1 -1
  62. package/catalog/policies/policy.obs.source_map_access_control.json +1 -1
  63. package/catalog/policies/policy.obs.telemetry_lifecycle_declared.json +1 -1
  64. package/catalog/policies/policy.obs.trace_correlation.json +1 -1
  65. package/catalog/policies/policy.perf.budget_change_retest.json +1 -1
  66. package/catalog/policies/policy.perf.evidence_binding.json +1 -1
  67. package/catalog/policies/policy.perf.observation_dimensions.json +1 -1
  68. package/catalog/policies/policy.proc.checklist_change_policy.json +2 -2
  69. package/catalog/policies/policy.proc.scope_drift_reclassify.json +1 -1
  70. package/catalog/policies/policy.prv.processing_scope_re_review.json +1 -1
  71. package/catalog/policies/policy.prv.sensitive_data_six_facts.json +1 -1
  72. package/catalog/policies/policy.registry.human_fields_validated_decorrelated.json +1 -1
  73. package/catalog/policies/policy.rel.no_irreversible_unmonitored_full_release.json +1 -1
  74. package/catalog/policies/policy.rel.observability_before_ship.json +1 -1
  75. package/catalog/policies/policy.rel.process_change_needs_drill_audit.json +1 -1
  76. package/catalog/policies/policy.rel.traceable_build.json +1 -1
  77. package/catalog/policies/policy.role.human_signs_for_ai.json +1 -1
  78. package/catalog/policies/policy.sec.authn_policy_unified.json +1 -1
  79. package/catalog/policies/policy.sec.no_client_side_trust.json +4 -1
  80. package/catalog/policies/policy.sec.no_longterm_security_disable.json +1 -1
  81. package/catalog/policies/policy.sec.no_script_readable_credentials.json +1 -1
  82. package/catalog/policies/policy.sec.no_secrets_in_client_surface.json +2 -2
  83. package/catalog/policies/policy.sec.relaxation_approval.json +1 -1
  84. package/catalog/policies/policy.sec.security_relaxation_gate.json +4 -1
  85. package/catalog/policies/policy.sec.trust_boundary_enforcement.json +4 -1
  86. package/catalog/policies/policy.sec.upload_download_server_recheck.json +1 -1
  87. package/catalog/policies/policy.sec.url_source_allowlist.json +1 -1
  88. package/catalog/policies/policy.spec.family_conflict_precedence.json +1 -1
  89. package/catalog/policies/policy.spec.freeze_before_use.json +1 -1
  90. package/catalog/policies/policy.spec.primary_source_basis.json +1 -1
  91. package/catalog/policies/policy.struct.module_entry_dependency_declared.json +1 -1
  92. package/catalog/policies/policy.struct.no_unexplained_top_level_dir.json +1 -1
  93. package/catalog/policies/policy.struct.reuse_proven_structure.json +1 -1
  94. package/catalog/policies/policy.test.control_nondeterminism_keep_diagnosis.json +1 -1
  95. package/catalog/policies/policy.test.isolation_and_cleanup.json +1 -1
  96. package/catalog/policies/policy.test.no_synthetic_stability.json +1 -1
  97. package/catalog/policies/policy.test.pyramid_and_ci_matrix.json +1 -1
  98. package/catalog/policies/policy.test.removal_justification.json +1 -1
  99. package/catalog/policies/policy.test.removal_needs_substitute_evidence.json +1 -1
  100. package/catalog/policies/policy.test.risk_driven_plan.json +1 -1
  101. package/catalog/policies/policy.test.stable_observable_assertions.json +1 -1
  102. package/catalog/policies/policy.tool.discoverable_toolchain.json +1 -1
  103. package/catalog/policies/policy.tool.no_hand_edit_generated_no_ci_drift.json +1 -1
  104. package/catalog/policies/policy.tool.no_vendored_body_edits.json +1 -1
  105. package/catalog/policies/policy.tool.upgrade_verify_lock_rollback.json +1 -1
  106. package/catalog/policies/policy.web.comp.no_trivial_or_god_component.json +1 -1
  107. package/catalog/policies/policy.web.comp.public_contract_completeness.json +1 -1
  108. package/catalog/policies/policy.web.copy.action_object_clarity.json +1 -1
  109. package/catalog/policies/policy.web.copy.enumerable_placement.json +1 -1
  110. package/catalog/policies/policy.web.copy.error_next_step.json +1 -1
  111. package/catalog/policies/policy.web.handoff.state_matrix_full.json +1 -1
  112. package/catalog/policies/policy.web.i18n.copy_key_discipline.json +1 -1
  113. package/catalog/policies/policy.web.i18n.raw_value_for_compute.json +1 -1
  114. package/catalog/policies/policy.web.page.region_consistency.json +1 -1
  115. package/catalog/policies/policy.web.track.attempt_result_correlation.json +1 -1
  116. package/catalog/policies/policy.web.track.no_synthetic_actions.json +1 -1
  117. package/catalog/policies/policy.web.track.typed_client_validation.json +1 -1
  118. package/catalog/policies/policy.wf.no_planned_as_verified.json +1 -1
  119. package/catalog/policies/policy.wf.task_facts_preconfirm.json +1 -1
  120. package/dist/bin.js +11233 -7336
  121. package/legal/THIRD_PARTY_NOTICES.md +461 -35
  122. package/package.json +1 -1
  123. package/seeds/aggregation-manifest.json +691 -0
  124. package/seeds/manifest.json +466 -1043
  125. package/seeds/specs/hard/stacks/antdesign/antdesign-ui-overlay.md +48 -0
  126. package/seeds/specs/hard/stacks/antdesign/index.md +20 -0
  127. package/seeds/specs/hard/stacks/css/css-system-overlay.md +52 -0
  128. package/seeds/specs/hard/stacks/css/index.md +20 -0
  129. package/seeds/specs/hard/stacks/geist/geist-design-system-overlay.md +48 -0
  130. package/seeds/specs/hard/stacks/geist/index.md +20 -0
  131. package/seeds/specs/hard/stacks/vue3/index.md +20 -0
  132. package/seeds/specs/hard/stacks/vue3/vue3-framework-overlay.md +71 -0
  133. package/seeds/specs/hard/themes/ai-generated-code.md +171 -0
  134. package/seeds/specs/hard/themes/api-contract-and-error-semantics.md +532 -0
  135. package/seeds/specs/hard/themes/architecture-and-module-boundaries.md +323 -0
  136. package/seeds/specs/hard/themes/data-and-transactions.md +582 -0
  137. package/seeds/specs/hard/themes/engineering-toolchain-and-dependencies.md +333 -0
  138. package/seeds/specs/hard/themes/environment-and-configuration.md +196 -0
  139. package/seeds/specs/hard/themes/frontend-state-and-client-data.md +342 -0
  140. package/seeds/specs/hard/themes/index.md +374 -0
  141. package/seeds/specs/hard/themes/integration-and-async-runtime.md +331 -0
  142. package/seeds/specs/hard/{frontend/38-internationalization-protocol.md → themes/internationalization-and-copywriting.md} +112 -5
  143. package/seeds/specs/hard/themes/observability-and-analytics.md +305 -0
  144. package/seeds/specs/hard/themes/page-composition-and-browser-environment.md +554 -0
  145. package/seeds/specs/hard/{frontend/31-performance-protocol.md → themes/performance-and-capacity.md} +95 -6
  146. package/seeds/specs/hard/themes/permission-and-authorization.md +168 -0
  147. package/seeds/specs/hard/themes/privacy-and-data-lifecycle.md +176 -0
  148. package/seeds/specs/hard/themes/release-and-feature-flags.md +237 -0
  149. package/seeds/specs/hard/{frontend/04-security-protocol.md → themes/security.md} +95 -6
  150. package/seeds/specs/hard/themes/task-governance-and-acceptance.md +554 -0
  151. package/seeds/specs/hard/themes/testing-and-verification.md +266 -0
  152. package/seeds/specs/hard/themes/ui-presentation-and-design.md +670 -0
  153. package/seeds/specs/hard/themes/value-semantics-and-domain-data.md +339 -0
  154. package/seeds/specs/hard/backend/01-architecture-governance-protocol.md +0 -68
  155. package/seeds/specs/hard/backend/02-project-structure-governance-protocol.md +0 -68
  156. package/seeds/specs/hard/backend/03-directory-boundary-protocol.md +0 -68
  157. package/seeds/specs/hard/backend/04-layering-architecture-protocol.md +0 -68
  158. package/seeds/specs/hard/backend/05-task-workflow-protocol.md +0 -68
  159. package/seeds/specs/hard/backend/06-ai-generated-code-protocol.md +0 -68
  160. package/seeds/specs/hard/backend/07-evidence-acceptance-protocol.md +0 -68
  161. package/seeds/specs/hard/backend/08-contract-change-protocol.md +0 -68
  162. package/seeds/specs/hard/backend/09-role-responsibility-protocol.md +0 -68
  163. package/seeds/specs/hard/backend/10-security-protocol.md +0 -68
  164. package/seeds/specs/hard/backend/11-environment-configuration-protocol.md +0 -67
  165. package/seeds/specs/hard/backend/12-api-contract-protocol.md +0 -68
  166. package/seeds/specs/hard/backend/13-privacy-data-lifecycle-protocol.md +0 -68
  167. package/seeds/specs/hard/backend/14-business-rules-state-protocol.md +0 -68
  168. package/seeds/specs/hard/backend/15-data-model-protocol.md +0 -68
  169. package/seeds/specs/hard/backend/16-error-code-protocol.md +0 -68
  170. package/seeds/specs/hard/backend/17-permission-authorization-protocol.md +0 -68
  171. package/seeds/specs/hard/backend/18-database-schema-migration-protocol.md +0 -68
  172. package/seeds/specs/hard/backend/19-query-index-sql-protocol.md +0 -68
  173. package/seeds/specs/hard/backend/20-transaction-boundary-protocol.md +0 -68
  174. package/seeds/specs/hard/backend/21-concurrency-locking-protocol.md +0 -68
  175. package/seeds/specs/hard/backend/22-idempotency-protocol.md +0 -68
  176. package/seeds/specs/hard/backend/23-cache-redis-consistency-protocol.md +0 -68
  177. package/seeds/specs/hard/backend/24-external-integration-resilience-protocol.md +0 -68
  178. package/seeds/specs/hard/backend/25-async-job-scheduler-protocol.md +0 -68
  179. package/seeds/specs/hard/backend/26-engineering-tooling-protocol.md +0 -68
  180. package/seeds/specs/hard/backend/27-dependency-supply-chain-protocol.md +0 -68
  181. package/seeds/specs/hard/backend/28-testing-protocol.md +0 -68
  182. package/seeds/specs/hard/backend/29-observability-logging-tracing-protocol.md +0 -68
  183. package/seeds/specs/hard/backend/30-performance-capacity-protocol.md +0 -68
  184. package/seeds/specs/hard/backend/31-runtime-deployment-protocol.md +0 -68
  185. package/seeds/specs/hard/backend/32-release-versioning-rollback-protocol.md +0 -68
  186. package/seeds/specs/hard/backend/index.md +0 -177
  187. package/seeds/specs/hard/frontend/01-development-checklist-protocol.md +0 -86
  188. package/seeds/specs/hard/frontend/02-ai-generated-code-protocol.md +0 -82
  189. package/seeds/specs/hard/frontend/03-acceptance-gate-protocol.md +0 -86
  190. package/seeds/specs/hard/frontend/05-environment-configuration-protocol.md +0 -80
  191. package/seeds/specs/hard/frontend/06-change-governance-protocol.md +0 -90
  192. package/seeds/specs/hard/frontend/07-frontend-backend-communication-protocol.md +0 -219
  193. package/seeds/specs/hard/frontend/08-role-responsibility-protocol.md +0 -80
  194. package/seeds/specs/hard/frontend/09-module-boundary-protocol.md +0 -81
  195. package/seeds/specs/hard/frontend/10-engineering-tooling-protocol.md +0 -89
  196. package/seeds/specs/hard/frontend/11-dependency-package-management-protocol.md +0 -87
  197. package/seeds/specs/hard/frontend/12-business-rules-protocol.md +0 -79
  198. package/seeds/specs/hard/frontend/13-monetary-precision-protocol.md +0 -81
  199. package/seeds/specs/hard/frontend/14-data-model-protocol.md +0 -85
  200. package/seeds/specs/hard/frontend/15-request-api-protocol.md +0 -87
  201. package/seeds/specs/hard/frontend/16-error-handling-protocol.md +0 -79
  202. package/seeds/specs/hard/frontend/17-permission-protocol.md +0 -79
  203. package/seeds/specs/hard/frontend/18-state-management-protocol.md +0 -88
  204. package/seeds/specs/hard/frontend/19-cache-protocol.md +0 -79
  205. package/seeds/specs/hard/frontend/20-testing-protocol.md +0 -88
  206. package/seeds/specs/hard/frontend/21-design-system-protocol.md +0 -79
  207. package/seeds/specs/hard/frontend/22-theme-protocol.md +0 -79
  208. package/seeds/specs/hard/frontend/23-accessibility-protocol.md +0 -189
  209. package/seeds/specs/hard/frontend/24-component-protocol.md +0 -80
  210. package/seeds/specs/hard/frontend/25-page-structure-protocol.md +0 -79
  211. package/seeds/specs/hard/frontend/26-style-layout-protocol.md +0 -80
  212. package/seeds/specs/hard/frontend/27-rendering-state-protocol.md +0 -81
  213. package/seeds/specs/hard/frontend/28-form-protocol.md +0 -88
  214. package/seeds/specs/hard/frontend/29-routing-url-protocol.md +0 -79
  215. package/seeds/specs/hard/frontend/30-data-grid-protocol.md +0 -83
  216. package/seeds/specs/hard/frontend/32-file-import-export-protocol.md +0 -80
  217. package/seeds/specs/hard/frontend/33-release-versioning-protocol.md +0 -79
  218. package/seeds/specs/hard/frontend/34-monitoring-logging-protocol.md +0 -128
  219. package/seeds/specs/hard/frontend/35-mock-protocol.md +0 -97
  220. package/seeds/specs/hard/frontend/36-feature-flag-protocol.md +0 -79
  221. package/seeds/specs/hard/frontend/37-browser-device-compatibility-protocol.md +0 -83
  222. package/seeds/specs/hard/frontend/39-copywriting-protocol.md +0 -79
  223. package/seeds/specs/hard/frontend/40-analytics-protocol.md +0 -98
  224. package/seeds/specs/hard/frontend/41-design-handoff-protocol.md +0 -80
  225. package/seeds/specs/hard/frontend/42-browser-runtime-lifecycle-protocol.md +0 -86
  226. package/seeds/specs/hard/frontend/43-time-temporal-protocol.md +0 -86
  227. package/seeds/specs/hard/frontend/44-privacy-data-lifecycle-protocol.md +0 -87
  228. package/seeds/specs/hard/frontend/45-browser-storage-protocol.md +0 -87
  229. package/seeds/specs/hard/frontend/index.md +0 -308
@@ -0,0 +1,532 @@
1
+ ---
2
+ seed_source: packages/cli/seeds/aggregation-manifest.json
3
+ seed_source_sha256: 039b637ccffacdfe3ce30d85e193f4b38928fcdfb16efdc4eb255e35e05af91f
4
+ seed_version: B7-THEME
5
+ lane: [frontend, backend]
6
+ status: CURRENT
7
+ authority_scope: mixed_required_and_advisory
8
+ applies_to: [frontend, backend]
9
+ related_evidence_specs: []
10
+ related_tools: []
11
+ legacy_id: theme:api-contract-and-error-semantics
12
+ criticality: critical # 聚合注记:取源最高;info 性注记非执行语义
13
+ injection_mode: triggered # 聚合注记:来源同值;info 性注记非执行语义
14
+ stages: [prepare, implement, check] # 聚合注记:来源 stages 并集;info 性注记非执行语义
15
+ triggers: [api-contract, api-change, error-code, error-handling] # 聚合注记:来源 triggers 并集;info 性注记非执行语义
16
+ requires: [] # 聚合注记:来源 requires 并集(全空)
17
+ x-aggregation: # 聚合来源(D6):逐源 vendor pin(sha256 与卡 vendor_pin 同值)
18
+ - seed_source: pomaster/components/frontend-hard-spec/assets/universal/07-frontend-backend-communication-protocol.md
19
+ sha256: b14d2f8281198ff663e6e21e58df2e429c4683907cb77b6ebcdb6609d37f72d2
20
+ seed_version: B6B-1
21
+ - seed_source: pomaster/components/frontend-hard-spec/assets/universal/15-request-api-protocol.md
22
+ sha256: b9489d69e35a19b8d5ba2442108190e7b99989ef471c8cf413d9e4e408ca2969
23
+ seed_version: B6B-1
24
+ - seed_source: pomaster/components/frontend-hard-spec/assets/universal/16-error-handling-protocol.md
25
+ sha256: 0c6adc425e01a003e1f3c83fcf51f1d287767c95a4da50c15f5f639d9104f07f
26
+ seed_version: B6B-1
27
+ - seed_source: pomaster/components/backend-hard-spec/assets/universal/12-api-contract-protocol.md
28
+ sha256: 35519d81548cabff729de888e0bf9e0d5b40a0274c9fa3684641b50e75938ca0
29
+ seed_version: B6C
30
+ - seed_source: pomaster/components/backend-hard-spec/assets/universal/16-error-code-protocol.md
31
+ sha256: aa80ee60f7431e14859f61e563784e71b2002f35e220964170a779800fdde090
32
+ seed_version: B6C
33
+ x-language-sections: # 语言节同步源(R-J 资产层唯一权威;注入面为同步副本)
34
+ - overlay: pomaster/components/backend-hard-spec/assets/stacks/spring-mvc/spring-mvc-web-overlay.md
35
+ sha256: 19a75e281d7406d4ce38accd4aa528496e9cb666a8d123bc489c7404cb67fcb6
36
+ attach: primary
37
+ ---
38
+
39
+ # API 契约与错误语义
40
+
41
+ > **聚合纪律**:本文档 12 节正文规则行逐字取自 frontmatter x-aggregation 所列来源协议(节内按「端 → 源编号升序」以加粗来源行分块,源内标题与层级原样保留),零新增、零改写、零删除;新增文本仅限文档标题、本注记与逐节来源行。
42
+ 文末「语言与栈节」为 stacks overlay 资产 Scope/Rules/Checklist 的逐字节同步副本(标题降 2 级,正文零改动)——资产层为唯一权威,改规则只改 overlay、本区随同步。
43
+
44
+ ## Scope
45
+
46
+ **源:FE 07 前后端通信协议(pomaster/components/frontend-hard-spec/assets/universal/07-frontend-backend-communication-protocol.md)**
47
+
48
+ P0。定义前后端共同确认的接口、认证、错误、幂等、并发、文件、任务、实时通信和版本契约。
49
+
50
+ **源:FE 15 请求与 API 协议(pomaster/components/frontend-hard-spec/assets/universal/15-request-api-protocol.md)**
51
+
52
+ P1。定义正式契约进入前端后的请求封装、取消、重试、loading、错误归一化和 API 函数。
53
+
54
+ **源:FE 16 错误处理协议(pomaster/components/frontend-hard-spec/assets/universal/16-error-handling-protocol.md)**
55
+
56
+ P1。定义认证、权限、资源、冲突、校验、限流、服务、网络和部分失败的前端呈现与恢复。
57
+
58
+ **源:BE 12 API 契约协议(pomaster/components/backend-hard-spec/assets/universal/12-api-contract-protocol.md)**
59
+
60
+ 规范请求响应、版本、字段、权限、错误、幂等、分页、兼容与 TraceId。
61
+
62
+ **源:BE 16 错误码协议(pomaster/components/backend-hard-spec/assets/universal/16-error-code-protocol.md)**
63
+
64
+ 规范错误分类、稳定错误码、状态映射、字段错误、重试性与安全消息。
65
+
66
+ ## Non-Scope
67
+
68
+ **源:FE 07 前后端通信协议**
69
+
70
+ 不规定前端请求库实现、页面错误呈现或具体后端框架。
71
+
72
+ **源:FE 15 请求与 API 协议**
73
+
74
+ 不定义后端接口本身,不负责页面错误文案和缓存业务规则。
75
+
76
+ **源:FE 16 错误处理协议**
77
+
78
+ 不定义后端错误码本身,不替代监控采集和业务校验。
79
+
80
+ **源:BE 12 API 契约协议**
81
+
82
+ 不替代领域规则、最终鉴权或具体 endpoint 事实。
83
+
84
+ **源:BE 16 错误码协议**
85
+
86
+ 不负责日志采样、告警或业务规则本身。
87
+
88
+ ## Terms
89
+
90
+ **源:FE 07 前后端通信协议**
91
+
92
+ - Formal Contract:可版本化、可校验的 OpenAPI 或等价契约。
93
+ - Idempotency:重复请求不产生重复业务结果。
94
+ - Optimistic Concurrency:通过 version/ETag 防止静默覆盖。
95
+ - TraceId:贯穿请求、任务和日志的问题定位标识。
96
+
97
+ **源:FE 15 请求与 API 协议**
98
+
99
+ - HTTP Client:统一传输基础设施。
100
+ - Domain API:面向业务语义的请求函数。
101
+ - Request Context:认证、语言、trace、幂等等上下文。
102
+
103
+ **源:FE 16 错误处理协议**
104
+
105
+ - Field Error:可定位到字段/单元格的错误。
106
+ - Recover Action:登录、刷新、重试、重载、联系管理员或解决冲突。
107
+ - Error Boundary:隔离渲染失败的边界。
108
+
109
+ **源:BE 12 API 契约协议**
110
+
111
+ 正式契约是 OpenAPI 或项目明确指定的等价权威来源。
112
+
113
+ **源:BE 16 错误码协议**
114
+
115
+ 稳定错误码是调用方可依赖且不暴露内部实现的机器语义。
116
+
117
+ ## MUST
118
+
119
+ **源:FE 07 前后端通信协议 · §MUST**
120
+
121
+ - 每个 endpoint 定义 URL、Method、参数位置、类型、响应、错误、权限和 owner。
122
+ - 分页、筛选、排序、空值、枚举、单位和时间语义必须明确。
123
+ - 写操作定义幂等、并发版本和缓存影响。
124
+ - 文件、异步任务和实时消息使用正式 schema。
125
+ - 破坏性变更必须版本化并提供迁移期。
126
+ - 所有错误和任务链路可通过 TraceId 追踪。
127
+ - 错误码到 UI 状态的映射必须维护在单一事实源 `outputs/frontend/10_planned/api-error-mapping.yaml`,并与契约版本同步。
128
+
129
+ **源:FE 15 请求与 API 协议 · §MUST**
130
+
131
+ - 页面只调用封装的 Domain API。
132
+ - HTTP Client 统一处理 base URL、认证、超时、取消、trace 和 envelope。
133
+ - 请求函数使用稳定领域动词命名并有类型。
134
+ - 查询可取消和丢弃过期响应。
135
+ - mutation 明确幂等和重试边界。
136
+ - 错误转换为统一结构。
137
+ - 传输成功与业务成功必须分别判断;HTTP 非成功状态、契约解析失败、取消、超时、离线和业务错误不得混为一类。
138
+ - 重试必须服从幂等性、服务端 `Retry-After` 或受控退避,并能取消;取消或已被替代的请求不得提示为用户错误。
139
+ - 请求结果提交前必须验证身份、租户、权限、参数和请求版本,防止旧上下文结果写回。
140
+ - endpoint、redirect 和 base URL 只能来自受控配置或契约,不得由不可信 URL 参数直接拼接。
141
+
142
+ **源:FE 16 错误处理协议 · §MUST**
143
+
144
+ - 将原始错误归一化为稳定 code、trace、fieldErrors、retryable 和 recoverAction。
145
+ - 401、403、404、409、422、429、5xx 和网络错误分别处理。
146
+ - 字段错误定位字段,部分失败提供逐项明细。
147
+ - 分层设置错误边界,局部失败不得导致整页白屏。
148
+ - 用户知道发生什么、能否恢复和下一步。
149
+
150
+ **源:BE 12 API 契约协议 · §MUST**
151
+
152
+ - method、path、字段、状态码、错误码、权限和兼容策略必须与实现一致。
153
+
154
+ **源:BE 16 错误码协议 · §MUST**
155
+
156
+ - 失败必须映射到稳定 code、适当状态、可选字段错误、retryable 与 TraceId。
157
+
158
+ ## MUST NOT
159
+
160
+ **源:FE 07 前后端通信协议 · §MUST NOT**
161
+
162
+ - MUST NOT 用口头、截图、Mock 或示例替代正式契约。
163
+ - MUST NOT 依赖 message 文本表达业务错误。
164
+ - MUST NOT 用按钮 loading 代替后端幂等。
165
+ - MUST NOT 未版本化地修改字段、枚举、分页或错误语义。
166
+
167
+ **源:FE 15 请求与 API 协议 · §MUST NOT**
168
+
169
+ - MUST NOT 在页面直接写 fetch/axios 或拼 endpoint。
170
+ - MUST NOT 多处重复 token、错误码和重试逻辑。
171
+ - MUST NOT 对非幂等 mutation 默认自动重试。
172
+ - MUST NOT 让组件解析原始响应 envelope。
173
+ - MUST NOT 把“网络在线”提示当成请求成功证明,或假设 HTTP 404/500 一定以 Promise rejection 表现。
174
+
175
+ **源:FE 16 错误处理协议 · §MUST NOT**
176
+
177
+ - MUST NOT 用一个 Toast 处理所有错误。
178
+ - MUST NOT 吞掉字段错误、冲突或 TraceId。
179
+ - MUST NOT 展示技术堆栈、敏感参数或原始 HTML。
180
+ - MUST NOT 自动重试不安全 mutation。
181
+
182
+ **源:BE 12 API 契约协议 · §MUST NOT**
183
+
184
+ - 不得把 Mock、聊天记录或调用方猜测当作正式契约。
185
+
186
+ **源:BE 16 错误码协议 · §MUST NOT**
187
+
188
+ - 不得向调用方返回堆栈、SQL、secret 或不稳定内部异常文本。
189
+
190
+ ## SHOULD
191
+
192
+ **源:FE 07 前后端通信协议 · §SHOULD**
193
+
194
+ - SHOULD 以机器可读契约生成类型、Mock 和校验。
195
+ - SHOULD 对任务进度优先使用 SSE,双向场景再用 WebSocket。
196
+
197
+ **源:FE 15 请求与 API 协议 · §SHOULD**
198
+
199
+ - SHOULD 通过生成客户端或 typed adapter 对接正式契约。
200
+ - SHOULD 让 loading 来源唯一,避免重复状态。
201
+
202
+ **源:FE 16 错误处理协议 · §SHOULD**
203
+
204
+ - SHOULD 区分页面错误、字段错误、后台任务和短暂反馈。
205
+ - SHOULD 在错误恢复后刷新受影响数据。
206
+
207
+ **源:BE 12 API 契约协议 · §SHOULD**
208
+
209
+ - 应对新增字段、分页、重试和版本演进采用向后兼容默认值。
210
+
211
+ **源:BE 16 错误码协议 · §SHOULD**
212
+
213
+ - 应区分认证、鉴权、未找到、冲突、校验、限流和服务失败。
214
+
215
+ ## Contract
216
+
217
+ **源:FE 07 前后端通信协议 · §Contract**
218
+
219
+ ### 接口元数据
220
+
221
+ ```text
222
+ Endpoint, Method, Auth, Permission, RequestSchema,
223
+ ResponseSchema, ErrorSchema, Idempotency,
224
+ Concurrency, Cache, RateLimit, Version, Owner
225
+ ```
226
+
227
+ 每个接口还必须记录用途、所属领域、稳定 operation id、超时、弃用状态和变更历史。口头约定、Mock、抓包结果和前端临时类型只能作为评审输入,不能成为主契约。
228
+
229
+ ### URL 与 Method
230
+
231
+ - URL 使用稳定资源名和层级,不把页面动作或展示标题编码进路径。
232
+ - GET 只读且可安全重试;POST/PUT/PATCH/DELETE 的创建、替换、部分更新和删除语义必须明确。
233
+ - 提交、审批、归档、计算等非 CRUD 动作使用明确领域动作,不使用 `doAction` 等万能端点。
234
+ - Path 参数标识资源,Query 表达分页/筛选/排序,Header 表达协议上下文,Body 表达命令或资源数据。
235
+
236
+ ### 请求参数
237
+
238
+ 每个字段必须定义:名称、位置、类型、必填、nullable、默认值、长度/范围、格式、枚举、单位、时区、示例和未知值策略。空字符串、null、缺失字段和空数组的语义不得混用。
239
+
240
+ ### 响应结构
241
+
242
+ - 成功响应必须声明 HTTP status、内容类型、数据 schema、可空性和 TraceId。
243
+ - 列表必须固定数据数组、页码或游标、pageSize、total/hasNext 的语义。
244
+ - 删除、提交、异步创建等操作必须明确同步结果、任务标识或无内容响应。
245
+ - 前端不得为同一业务同时兼容多个未版本化 envelope。
246
+
247
+ ### 错误结构
248
+
249
+ ```text
250
+ Error {
251
+ httpStatus,
252
+ code,
253
+ safeMessage?,
254
+ traceId,
255
+ fieldErrors?,
256
+ itemErrors?,
257
+ retryable,
258
+ retryAfter?,
259
+ conflictVersion?
260
+ }
261
+ ```
262
+
263
+ - HTTP status 表达认证、权限、资源、冲突、校验、限流和服务状态。
264
+ - 业务 code 必须稳定且可枚举,message 仅用于展示或诊断,不能驱动逻辑。
265
+ - 字段错误包含稳定 field key、错误码和参数;批量错误包含对象/行标识。
266
+ - 409 返回冲突实体或重新获取方式;429 返回明确退避信息;5xx 不代表所有请求均可重试。
267
+
268
+ ### DTO、Adapter 与 ViewModel
269
+
270
+ 接口契约定义 DTO。前端通过 Adapter 转成稳定 Domain Model/ViewModel;公共组件、表格列和模板不得直接依赖 DTO。字段重命名、null、枚举、日期和金额转换只能在边界完成。
271
+
272
+ ### 分页、筛选与排序
273
+
274
+ - 页码起点或游标语义、pageSize 上限、total 是否精确必须固定。
275
+ - 筛选字段采用允许列表,并定义操作符、组合逻辑、空值和时间区间。
276
+ - 排序字段和方向采用允许列表;需要稳定结果时声明次排序。
277
+ - 导出必须复用列表筛选语义,并明确当前页、选中项或符合条件的全量范围。
278
+
279
+ ### 权限通信
280
+
281
+ - 接口声明认证要求、操作权限和数据范围。
282
+ - 后端只返回调用方有权访问的数据;前端隐藏入口不能替代鉴权。
283
+ - 字段可见、脱敏、编辑和导出权限必须有稳定 contract。
284
+ - 权限变化后 token、缓存和已打开页面如何失效必须明确。
285
+
286
+ ### 认证与 Token
287
+
288
+ 必须定义 access/refresh token 生命周期、传输位置、刷新、撤销、退出、多标签同步、并发 401 合并和 CSRF 策略。Token 不得出现在 URL、日志、埋点或业务组件。
289
+
290
+ ### 幂等性
291
+
292
+ - 创建、提交、审批、批量动作、导入、导出和计算等可能重复执行的命令必须声明幂等支持。
293
+ - 幂等键的生成方、作用域、有效期、重复请求响应和冲突行为必须固定。
294
+ - 前端按钮禁用和 loading 只是体验保护,不构成业务幂等。
295
+
296
+ ### 并发与数据冲突
297
+
298
+ - 可编辑资源返回 version、updatedAt 或 ETag,并在更新命令携带预期版本。
299
+ - 冲突必须显式返回,不允许静默 last-write-wins。
300
+ - 契约声明刷新、放弃本地修改、重新提交和字段 diff 所需数据。
301
+
302
+ ### 缓存与刷新
303
+
304
+ 接口声明可缓存性、ETag/version、数据实时性和写操作影响资源。权限、BOM、成本、审批等高风险数据不得由调用方擅自延长缓存;mutation 必须提供足够信息完成准确失效。
305
+
306
+ ### 文件上传与下载
307
+
308
+ - 上传声明 multipart 字段、类型、大小、数量、文件名、校验阶段和安全错误。
309
+ - 下载声明内容类型、文件名编码、权限、数据范围、有效期和断点/大文件策略。
310
+ - 文件 URL 不得成为永久越权入口,下载时必须重新授权。
311
+
312
+ ### 异步任务
313
+
314
+ ```text
315
+ Job {
316
+ taskId, type, status, progress,
317
+ message?, result?, error?, traceId,
318
+ createdAt, updatedAt
319
+ }
320
+ ```
321
+
322
+ 必须定义创建、查询、取消、重试、结果、错误明细、过期和幂等。状态机至少区分 pending、running、success、failed、cancelled;新增状态需契约变更。
323
+
324
+ ### 实时通信
325
+
326
+ - 服务端单向进度和通知优先 SSE;双向协作才使用 WebSocket;轮询为降级。
327
+ - 消息至少包含 messageId、type、payload、timestamp、version 和 TraceId。
328
+ - 必须定义鉴权、心跳、断线重连、重复、乱序、丢失、回放、完成终止和降级行为。
329
+
330
+ ### 版本兼容
331
+
332
+ - 新增可选字段通常向后兼容;删除、改名、类型、枚举或语义变化属于破坏性变更。
333
+ - 未知枚举必须安全兜底,但不得静默赋予业务含义。
334
+ - 破坏性变化提供新版本、调用方清单、迁移期、弃用日期和回滚。
335
+ - 生成类型、Adapter、Mock、导入导出和测试必须随契约同步。
336
+
337
+ ### 联调流程
338
+
339
+ 正式流程为:契约提案 -> 示例/Mock -> 前后端与业务评审 -> 冻结 -> 类型生成/Adapter -> 联调 -> 非理想态验收 -> 发布。联调不能只验证 200,至少覆盖 401、403、409、422、429、5xx、超时和部分成功。
340
+
341
+ ### TraceId
342
+
343
+ 客户端操作、HTTP 请求、异步任务、实时消息、后端日志和用户可见错误应能关联 TraceId/OperationId。TraceId 不携带敏感信息,并在跨服务时保持或建立明确父子关系。
344
+
345
+ ### 错误码到 UI 状态映射
346
+
347
+ `outputs/frontend/10_planned/api-error-mapping.yaml` 是每个项目必须维护的事实源,字段包括:
348
+
349
+ ```text
350
+ ErrorCode, HttpStatus, UIState, RecoverAction, DefaultMessage, TraceIdRequired, ContractVersion
351
+ ```
352
+
353
+ - 每个稳定业务 code 必须映射到唯一 UI 状态(idle/loading/error/success/retry/conflict/permission)。
354
+ - 映射必须随契约版本升级;破坏性 code 变化属于契约变更。
355
+ - UI 不得直接按 message 文本或 HTTP status 推导状态;未映射 code 必须进入兜底状态并记录。
356
+
357
+ **源:FE 15 请求与 API 协议 · §Contract**
358
+
359
+ ```text
360
+ FunctionName, InputType, OutputType, ErrorType,
361
+ StatusPolicy, Cancellation, Retry, RetryAfter, Idempotency,
362
+ ContextVersion, LateResultGuard, Trace
363
+ ```
364
+
365
+ **源:FE 16 错误处理协议 · §Contract**
366
+
367
+ ```text
368
+ Error { status?, code, safeMessage, traceId?,
369
+ fieldErrors?, retryable, recoverAction? }
370
+ ```
371
+
372
+ **源:BE 12 API 契约协议 · §Contract**
373
+
374
+ 每个接口必须定义输入、输出、失败、幂等、权限、追踪与版本语义。
375
+
376
+ **源:BE 16 错误码协议 · §Contract**
377
+
378
+ 错误注册项必须包含语义、状态映射、消息边界、重试性和所有者。
379
+
380
+ ## Checklist
381
+
382
+ **源:FE 07 前后端通信协议 · §Checklist**
383
+
384
+ - [ ] 请求/响应和错误完整。
385
+ - [ ] 参数位置、空值、枚举、单位和时间语义明确。
386
+ - [ ] 分页、筛选、排序和导出语义一致。
387
+ - [ ] 权限、幂等、并发明确。
388
+ - [ ] 文件/任务/实时契约完整。
389
+ - [ ] 兼容和 TraceId 可验证。
390
+ - [ ] 类型、Adapter、Mock 和错误场景随契约同步。
391
+ - [ ] api-error-mapping.yaml 已维护并与契约版本一致。
392
+
393
+ **源:FE 15 请求与 API 协议 · §Checklist**
394
+
395
+ - [ ] 页面只使用 Domain API。
396
+ - [ ] 类型和错误统一。
397
+ - [ ] 取消、重试、幂等明确。
398
+ - [ ] 无重复 loading/认证逻辑。
399
+ - [ ] 状态判断、旧结果防护和 endpoint 来源明确。
400
+
401
+ **源:FE 16 错误处理协议 · §Checklist**
402
+
403
+ - [ ] 错误分类和位置正确。
404
+ - [ ] 恢复动作可执行。
405
+ - [ ] TraceId 可定位。
406
+ - [ ] 敏感信息未泄露。
407
+
408
+ **源:BE 12 API 契约协议 · §Checklist**
409
+
410
+ - [ ] 契约、实现、生成客户端、测试和 handoff 已同步。
411
+
412
+ **源:BE 16 错误码协议 · §Checklist**
413
+
414
+ - [ ] 新错误已验证客户端恢复、日志关联和兼容行为。
415
+
416
+ ## Examples
417
+
418
+ **源:FE 07 前后端通信协议 · §Examples**
419
+
420
+ ### 内容示例,可删除
421
+
422
+ 更新实体携带预期 version;冲突返回 409、稳定错误码、服务器版本和 TraceId。批量导入返回 taskId,进度消息使用固定 Job/Realtime schema,完成后按契约刷新受影响资源。
423
+
424
+ **源:FE 15 请求与 API 协议 · §Examples**
425
+
426
+ ### 内容示例,可删除
427
+
428
+ `getEntityList(query, signal)` 返回稳定分页模型,调用方不认识 endpoint 和 envelope。
429
+
430
+ **源:FE 16 错误处理协议 · §Examples**
431
+
432
+ ### 内容示例,可删除
433
+
434
+ 409 保留本地编辑,提示比较最新版本,而不是自动覆盖。
435
+
436
+ **源:BE 12 API 契约协议 · §Examples**
437
+
438
+ - 冲突返回稳定错误码与 TraceId,而不是泄露内部异常。
439
+
440
+ **源:BE 16 错误码协议 · §Examples**
441
+
442
+ - 乐观锁冲突返回稳定冲突 code,并明确客户端是否可重试。
443
+
444
+ ## Anti-patterns
445
+
446
+ **源:FE 07 前后端通信协议 · §Anti-patterns**
447
+
448
+ 前端按 Mock 猜字段,后端改名后页面同时兼容多种响应并比较错误 message;创建、导入和审批只靠按钮 loading 防重;轮询、SSE 和 WebSocket 又各自定义一套任务状态。
449
+
450
+ **源:FE 15 请求与 API 协议 · §Anti-patterns**
451
+
452
+ 每个页面各自创建请求实例、刷新 token 并比较 message。
453
+
454
+ **源:FE 16 错误处理协议 · §Anti-patterns**
455
+
456
+ 所有失败统一 Toast“操作失败”,字段输入被清空且无错误编号。
457
+
458
+ **源:BE 12 API 契约协议 · §Anti-patterns**
459
+
460
+ - 修改响应字段但不更新正式契约和调用方兼容测试。
461
+
462
+ **源:BE 16 错误码协议 · §Anti-patterns**
463
+
464
+ - 所有异常都返回 HTTP 200 或统一未知错误。
465
+
466
+ ## Ownership
467
+
468
+ **源:FE 07 前后端通信协议 · §Ownership**
469
+
470
+ 前后端 API Owner 共同负责,业务 Owner 确认语义,安全 Owner 确认认证和权限。
471
+
472
+ **源:FE 15 请求与 API 协议 · §Ownership**
473
+
474
+ 平台 Owner 维护 HTTP Client,领域 Owner 维护 Domain API,契约 Owner 维护类型来源。
475
+
476
+ **源:FE 16 错误处理协议 · §Ownership**
477
+
478
+ 契约 Owner 定义错误码,平台 Owner 维护归一化,页面 Owner 负责上下文呈现。
479
+
480
+ **源:BE 12 API 契约协议 · §Ownership**
481
+
482
+ Backend 维护服务端契约,消费者确认联调与兼容结果。
483
+
484
+ **源:BE 16 错误码协议 · §Ownership**
485
+
486
+ Backend 维护错误注册表,API 消费方按稳定语义处理。
487
+
488
+ ## Change Policy
489
+
490
+ **源:FE 07 前后端通信协议 · §Change Policy**
491
+
492
+ 契约先评审、再冻结、后实现;破坏性变化必须有版本、调用方清单、迁移和退役日期。
493
+
494
+ **源:FE 15 请求与 API 协议 · §Change Policy**
495
+
496
+ 客户端公共行为变化必须评估全部请求;函数破坏性变化提供迁移和弃用期。
497
+
498
+ **源:FE 16 错误处理协议 · §Change Policy**
499
+
500
+ 错误码或恢复语义变化必须同步契约、映射、文案、Mock、监控和测试。
501
+
502
+ **源:BE 12 API 契约协议 · §Change Policy**
503
+
504
+ 破坏性 API 变化必须按契约变更协议执行版本与迁移。
505
+
506
+ **源:BE 16 错误码协议 · §Change Policy**
507
+
508
+ 已发布错误码不得复用;废弃必须保留兼容说明。
509
+
510
+ ## 语言与栈节(overlay 资产同步区)
511
+
512
+ > 本区各小节 = stacks/ overlay 资产 Scope/Rules/Checklist 的**逐字节同步副本**(标题降 2 级,正文零改动)。资产层(overlay 文件,catalog 在册、research 锚、bound 语义挂点)为唯一权威;本区为注入面副本,改规则只改 overlay、本区随同步。x-research-anchors 留在 overlay 资产 frontmatter,不复制进本主题文档(防双锚漂移)。
513
+
514
+ ### spring-mvc(源:stacks/spring-mvc/spring-mvc-web-overlay.md · T10 主挂点)
515
+
516
+ #### Scope
517
+
518
+ 本 Overlay 具体化 Servlet 请求链、Controller、参数绑定、异常映射和线程模型。
519
+
520
+ #### Rules
521
+
522
+ - Controller 必须保持传输层职责,业务规则进入明确的应用或领域边界。
523
+ - 阻塞调用、上传下载和异步请求必须声明超时、资源与安全约束。
524
+ - 与 WebFlux 并存时必须记录模块、端口或应用边界。
525
+
526
+ #### Checklist
527
+
528
+ - [ ] Java 与 Spring Boot 依赖已显式选择。
529
+ - [ ] API、错误码、权限和测试证据与实现一致。
530
+
531
+
532
+ > **缺席诚实**:php / python(后端语言)无 overlay 资产,不落语言节。