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.
- package/README.md +102 -183
- package/catalog/catalog-lock.draft.json +117 -117
- package/catalog/policies/policy.ai.change_plan_first.json +1 -1
- package/catalog/policies/policy.ai.fact_inference_separation.json +1 -1
- package/catalog/policies/policy.ai.read_search_verify_before_write.json +1 -1
- package/catalog/policies/policy.ai.rule_relaxation_approval.json +1 -1
- package/catalog/policies/policy.arch.adr_immutable_history.json +1 -1
- package/catalog/policies/policy.arch.no_convenience_over_boundary.json +1 -1
- package/catalog/policies/policy.arch.prefer_verifiable_option.json +2 -2
- package/catalog/policies/policy.authz.no_gating_proxy_trust.json +1 -1
- package/catalog/policies/policy.authz.permission_scope_expansion_gate.json +1 -1
- package/catalog/policies/policy.authz.server_five_factor_verification.json +1 -1
- package/catalog/policies/policy.be.conc.prefer_db_constraints.json +1 -1
- package/catalog/policies/policy.be.db.expand_migrate_contract.json +1 -1
- package/catalog/policies/policy.be.idem.key_payload_conflict.json +1 -1
- package/catalog/policies/policy.be.model.single_boundary_conversion.json +1 -1
- package/catalog/policies/policy.be.sql.index_for_known_queries.json +1 -1
- package/catalog/policies/policy.be.state.single_rule_source.json +1 -1
- package/catalog/policies/policy.be.txn.short_locks_compensation.json +1 -1
- package/catalog/policies/policy.bound.search_first_entry_only.json +1 -1
- package/catalog/policies/policy.boundary.validate_in_encode_out.json +1 -1
- package/catalog/policies/policy.cache.failure_mode_guards.json +1 -1
- package/catalog/policies/policy.cache.schema_versioning.json +1 -1
- package/catalog/policies/policy.cfg.config_attribute_completeness.json +1 -1
- package/catalog/policies/policy.cfg.key_rename_dual_read.json +1 -1
- package/catalog/policies/policy.cfg.no_secret_dispersal.json +1 -1
- package/catalog/policies/policy.cfg.production_safe_defaults.json +1 -1
- package/catalog/policies/policy.cfg.schema_backed_config.json +1 -1
- package/catalog/policies/policy.chg.no_unrelated_changes.json +1 -1
- package/catalog/policies/policy.contract.no_invented_facts.json +1 -1
- package/catalog/policies/policy.dep.build_path_supply_chain.json +1 -1
- package/catalog/policies/policy.dep.no_untrusted_source_no_lock_bypass.json +1 -1
- package/catalog/policies/policy.dep.time_boxed_urgent_exception.json +1 -1
- package/catalog/policies/policy.deploy.no_dev_env_as_production_fact.json +1 -1
- package/catalog/policies/policy.deploy.operational_capabilities.json +1 -1
- package/catalog/policies/policy.deploy.runtime_fact_record.json +1 -1
- package/catalog/policies/policy.err.failure_five_part_mapping.json +1 -1
- package/catalog/policies/policy.err.no_internal_detail_exposure.json +1 -1
- package/catalog/policies/policy.err.published_code_immutable.json +1 -1
- package/catalog/policies/policy.evid.acceptance_binds_verifiable_evidence.json +1 -1
- package/catalog/policies/policy.evid.no_silent_gate_removal.json +1 -1
- package/catalog/policies/policy.evid.no_unverifiable_pass.json +1 -1
- package/catalog/policies/policy.flag.cleanup_after_full_rollout.json +1 -1
- package/catalog/policies/policy.flag.consistent_off_state.json +1 -1
- package/catalog/policies/policy.flag.kill_switch.json +1 -1
- package/catalog/policies/policy.flag.lifecycle_metadata.json +1 -1
- package/catalog/policies/policy.flag.not_a_permission.json +1 -1
- package/catalog/policies/policy.gate.p0_non_bypassable.json +1 -1
- package/catalog/policies/policy.gate.risk_factors_confirmed.json +1 -1
- package/catalog/policies/policy.guard.no_check_weakening.json +2 -2
- package/catalog/policies/policy.integration.call_definition_minimum.json +1 -1
- package/catalog/policies/policy.integration.fault_containment.json +1 -1
- package/catalog/policies/policy.job.lifecycle_definition.json +1 -1
- package/catalog/policies/policy.job.no_unmanaged_execution.json +1 -1
- package/catalog/policies/policy.job.operational_features.json +1 -1
- package/catalog/policies/policy.obs.actionable_signals.json +1 -1
- package/catalog/policies/policy.obs.alert_with_owner.json +1 -1
- package/catalog/policies/policy.obs.context_field_baseline.json +1 -1
- package/catalog/policies/policy.obs.no_sensitive_or_unbounded_logging.json +1 -1
- package/catalog/policies/policy.obs.no_sensitive_raw_values.json +1 -1
- package/catalog/policies/policy.obs.signal_change_impact.json +1 -1
- package/catalog/policies/policy.obs.source_map_access_control.json +1 -1
- package/catalog/policies/policy.obs.telemetry_lifecycle_declared.json +1 -1
- package/catalog/policies/policy.obs.trace_correlation.json +1 -1
- package/catalog/policies/policy.perf.budget_change_retest.json +1 -1
- package/catalog/policies/policy.perf.evidence_binding.json +1 -1
- package/catalog/policies/policy.perf.observation_dimensions.json +1 -1
- package/catalog/policies/policy.proc.checklist_change_policy.json +2 -2
- package/catalog/policies/policy.proc.scope_drift_reclassify.json +1 -1
- package/catalog/policies/policy.prv.processing_scope_re_review.json +1 -1
- package/catalog/policies/policy.prv.sensitive_data_six_facts.json +1 -1
- package/catalog/policies/policy.registry.human_fields_validated_decorrelated.json +1 -1
- package/catalog/policies/policy.rel.no_irreversible_unmonitored_full_release.json +1 -1
- package/catalog/policies/policy.rel.observability_before_ship.json +1 -1
- package/catalog/policies/policy.rel.process_change_needs_drill_audit.json +1 -1
- package/catalog/policies/policy.rel.traceable_build.json +1 -1
- package/catalog/policies/policy.role.human_signs_for_ai.json +1 -1
- package/catalog/policies/policy.sec.authn_policy_unified.json +1 -1
- package/catalog/policies/policy.sec.no_client_side_trust.json +4 -1
- package/catalog/policies/policy.sec.no_longterm_security_disable.json +1 -1
- package/catalog/policies/policy.sec.no_script_readable_credentials.json +1 -1
- package/catalog/policies/policy.sec.no_secrets_in_client_surface.json +2 -2
- package/catalog/policies/policy.sec.relaxation_approval.json +1 -1
- package/catalog/policies/policy.sec.security_relaxation_gate.json +4 -1
- package/catalog/policies/policy.sec.trust_boundary_enforcement.json +4 -1
- package/catalog/policies/policy.sec.upload_download_server_recheck.json +1 -1
- package/catalog/policies/policy.sec.url_source_allowlist.json +1 -1
- package/catalog/policies/policy.spec.family_conflict_precedence.json +1 -1
- package/catalog/policies/policy.spec.freeze_before_use.json +1 -1
- package/catalog/policies/policy.spec.primary_source_basis.json +1 -1
- package/catalog/policies/policy.struct.module_entry_dependency_declared.json +1 -1
- package/catalog/policies/policy.struct.no_unexplained_top_level_dir.json +1 -1
- package/catalog/policies/policy.struct.reuse_proven_structure.json +1 -1
- package/catalog/policies/policy.test.control_nondeterminism_keep_diagnosis.json +1 -1
- package/catalog/policies/policy.test.isolation_and_cleanup.json +1 -1
- package/catalog/policies/policy.test.no_synthetic_stability.json +1 -1
- package/catalog/policies/policy.test.pyramid_and_ci_matrix.json +1 -1
- package/catalog/policies/policy.test.removal_justification.json +1 -1
- package/catalog/policies/policy.test.removal_needs_substitute_evidence.json +1 -1
- package/catalog/policies/policy.test.risk_driven_plan.json +1 -1
- package/catalog/policies/policy.test.stable_observable_assertions.json +1 -1
- package/catalog/policies/policy.tool.discoverable_toolchain.json +1 -1
- package/catalog/policies/policy.tool.no_hand_edit_generated_no_ci_drift.json +1 -1
- package/catalog/policies/policy.tool.no_vendored_body_edits.json +1 -1
- package/catalog/policies/policy.tool.upgrade_verify_lock_rollback.json +1 -1
- package/catalog/policies/policy.web.comp.no_trivial_or_god_component.json +1 -1
- package/catalog/policies/policy.web.comp.public_contract_completeness.json +1 -1
- package/catalog/policies/policy.web.copy.action_object_clarity.json +1 -1
- package/catalog/policies/policy.web.copy.enumerable_placement.json +1 -1
- package/catalog/policies/policy.web.copy.error_next_step.json +1 -1
- package/catalog/policies/policy.web.handoff.state_matrix_full.json +1 -1
- package/catalog/policies/policy.web.i18n.copy_key_discipline.json +1 -1
- package/catalog/policies/policy.web.i18n.raw_value_for_compute.json +1 -1
- package/catalog/policies/policy.web.page.region_consistency.json +1 -1
- package/catalog/policies/policy.web.track.attempt_result_correlation.json +1 -1
- package/catalog/policies/policy.web.track.no_synthetic_actions.json +1 -1
- package/catalog/policies/policy.web.track.typed_client_validation.json +1 -1
- package/catalog/policies/policy.wf.no_planned_as_verified.json +1 -1
- package/catalog/policies/policy.wf.task_facts_preconfirm.json +1 -1
- package/dist/bin.js +11233 -7336
- package/legal/THIRD_PARTY_NOTICES.md +461 -35
- package/package.json +1 -1
- package/seeds/aggregation-manifest.json +691 -0
- package/seeds/manifest.json +466 -1043
- package/seeds/specs/hard/stacks/antdesign/antdesign-ui-overlay.md +48 -0
- package/seeds/specs/hard/stacks/antdesign/index.md +20 -0
- package/seeds/specs/hard/stacks/css/css-system-overlay.md +52 -0
- package/seeds/specs/hard/stacks/css/index.md +20 -0
- package/seeds/specs/hard/stacks/geist/geist-design-system-overlay.md +48 -0
- package/seeds/specs/hard/stacks/geist/index.md +20 -0
- package/seeds/specs/hard/stacks/vue3/index.md +20 -0
- package/seeds/specs/hard/stacks/vue3/vue3-framework-overlay.md +71 -0
- package/seeds/specs/hard/themes/ai-generated-code.md +171 -0
- package/seeds/specs/hard/themes/api-contract-and-error-semantics.md +532 -0
- package/seeds/specs/hard/themes/architecture-and-module-boundaries.md +323 -0
- package/seeds/specs/hard/themes/data-and-transactions.md +582 -0
- package/seeds/specs/hard/themes/engineering-toolchain-and-dependencies.md +333 -0
- package/seeds/specs/hard/themes/environment-and-configuration.md +196 -0
- package/seeds/specs/hard/themes/frontend-state-and-client-data.md +342 -0
- package/seeds/specs/hard/themes/index.md +374 -0
- package/seeds/specs/hard/themes/integration-and-async-runtime.md +331 -0
- package/seeds/specs/hard/{frontend/38-internationalization-protocol.md → themes/internationalization-and-copywriting.md} +112 -5
- package/seeds/specs/hard/themes/observability-and-analytics.md +305 -0
- package/seeds/specs/hard/themes/page-composition-and-browser-environment.md +554 -0
- package/seeds/specs/hard/{frontend/31-performance-protocol.md → themes/performance-and-capacity.md} +95 -6
- package/seeds/specs/hard/themes/permission-and-authorization.md +168 -0
- package/seeds/specs/hard/themes/privacy-and-data-lifecycle.md +176 -0
- package/seeds/specs/hard/themes/release-and-feature-flags.md +237 -0
- package/seeds/specs/hard/{frontend/04-security-protocol.md → themes/security.md} +95 -6
- package/seeds/specs/hard/themes/task-governance-and-acceptance.md +554 -0
- package/seeds/specs/hard/themes/testing-and-verification.md +266 -0
- package/seeds/specs/hard/themes/ui-presentation-and-design.md +670 -0
- package/seeds/specs/hard/themes/value-semantics-and-domain-data.md +339 -0
- package/seeds/specs/hard/backend/01-architecture-governance-protocol.md +0 -68
- package/seeds/specs/hard/backend/02-project-structure-governance-protocol.md +0 -68
- package/seeds/specs/hard/backend/03-directory-boundary-protocol.md +0 -68
- package/seeds/specs/hard/backend/04-layering-architecture-protocol.md +0 -68
- package/seeds/specs/hard/backend/05-task-workflow-protocol.md +0 -68
- package/seeds/specs/hard/backend/06-ai-generated-code-protocol.md +0 -68
- package/seeds/specs/hard/backend/07-evidence-acceptance-protocol.md +0 -68
- package/seeds/specs/hard/backend/08-contract-change-protocol.md +0 -68
- package/seeds/specs/hard/backend/09-role-responsibility-protocol.md +0 -68
- package/seeds/specs/hard/backend/10-security-protocol.md +0 -68
- package/seeds/specs/hard/backend/11-environment-configuration-protocol.md +0 -67
- package/seeds/specs/hard/backend/12-api-contract-protocol.md +0 -68
- package/seeds/specs/hard/backend/13-privacy-data-lifecycle-protocol.md +0 -68
- package/seeds/specs/hard/backend/14-business-rules-state-protocol.md +0 -68
- package/seeds/specs/hard/backend/15-data-model-protocol.md +0 -68
- package/seeds/specs/hard/backend/16-error-code-protocol.md +0 -68
- package/seeds/specs/hard/backend/17-permission-authorization-protocol.md +0 -68
- package/seeds/specs/hard/backend/18-database-schema-migration-protocol.md +0 -68
- package/seeds/specs/hard/backend/19-query-index-sql-protocol.md +0 -68
- package/seeds/specs/hard/backend/20-transaction-boundary-protocol.md +0 -68
- package/seeds/specs/hard/backend/21-concurrency-locking-protocol.md +0 -68
- package/seeds/specs/hard/backend/22-idempotency-protocol.md +0 -68
- package/seeds/specs/hard/backend/23-cache-redis-consistency-protocol.md +0 -68
- package/seeds/specs/hard/backend/24-external-integration-resilience-protocol.md +0 -68
- package/seeds/specs/hard/backend/25-async-job-scheduler-protocol.md +0 -68
- package/seeds/specs/hard/backend/26-engineering-tooling-protocol.md +0 -68
- package/seeds/specs/hard/backend/27-dependency-supply-chain-protocol.md +0 -68
- package/seeds/specs/hard/backend/28-testing-protocol.md +0 -68
- package/seeds/specs/hard/backend/29-observability-logging-tracing-protocol.md +0 -68
- package/seeds/specs/hard/backend/30-performance-capacity-protocol.md +0 -68
- package/seeds/specs/hard/backend/31-runtime-deployment-protocol.md +0 -68
- package/seeds/specs/hard/backend/32-release-versioning-rollback-protocol.md +0 -68
- package/seeds/specs/hard/backend/index.md +0 -177
- package/seeds/specs/hard/frontend/01-development-checklist-protocol.md +0 -86
- package/seeds/specs/hard/frontend/02-ai-generated-code-protocol.md +0 -82
- package/seeds/specs/hard/frontend/03-acceptance-gate-protocol.md +0 -86
- package/seeds/specs/hard/frontend/05-environment-configuration-protocol.md +0 -80
- package/seeds/specs/hard/frontend/06-change-governance-protocol.md +0 -90
- package/seeds/specs/hard/frontend/07-frontend-backend-communication-protocol.md +0 -219
- package/seeds/specs/hard/frontend/08-role-responsibility-protocol.md +0 -80
- package/seeds/specs/hard/frontend/09-module-boundary-protocol.md +0 -81
- package/seeds/specs/hard/frontend/10-engineering-tooling-protocol.md +0 -89
- package/seeds/specs/hard/frontend/11-dependency-package-management-protocol.md +0 -87
- package/seeds/specs/hard/frontend/12-business-rules-protocol.md +0 -79
- package/seeds/specs/hard/frontend/13-monetary-precision-protocol.md +0 -81
- package/seeds/specs/hard/frontend/14-data-model-protocol.md +0 -85
- package/seeds/specs/hard/frontend/15-request-api-protocol.md +0 -87
- package/seeds/specs/hard/frontend/16-error-handling-protocol.md +0 -79
- package/seeds/specs/hard/frontend/17-permission-protocol.md +0 -79
- package/seeds/specs/hard/frontend/18-state-management-protocol.md +0 -88
- package/seeds/specs/hard/frontend/19-cache-protocol.md +0 -79
- package/seeds/specs/hard/frontend/20-testing-protocol.md +0 -88
- package/seeds/specs/hard/frontend/21-design-system-protocol.md +0 -79
- package/seeds/specs/hard/frontend/22-theme-protocol.md +0 -79
- package/seeds/specs/hard/frontend/23-accessibility-protocol.md +0 -189
- package/seeds/specs/hard/frontend/24-component-protocol.md +0 -80
- package/seeds/specs/hard/frontend/25-page-structure-protocol.md +0 -79
- package/seeds/specs/hard/frontend/26-style-layout-protocol.md +0 -80
- package/seeds/specs/hard/frontend/27-rendering-state-protocol.md +0 -81
- package/seeds/specs/hard/frontend/28-form-protocol.md +0 -88
- package/seeds/specs/hard/frontend/29-routing-url-protocol.md +0 -79
- package/seeds/specs/hard/frontend/30-data-grid-protocol.md +0 -83
- package/seeds/specs/hard/frontend/32-file-import-export-protocol.md +0 -80
- package/seeds/specs/hard/frontend/33-release-versioning-protocol.md +0 -79
- package/seeds/specs/hard/frontend/34-monitoring-logging-protocol.md +0 -128
- package/seeds/specs/hard/frontend/35-mock-protocol.md +0 -97
- package/seeds/specs/hard/frontend/36-feature-flag-protocol.md +0 -79
- package/seeds/specs/hard/frontend/37-browser-device-compatibility-protocol.md +0 -83
- package/seeds/specs/hard/frontend/39-copywriting-protocol.md +0 -79
- package/seeds/specs/hard/frontend/40-analytics-protocol.md +0 -98
- package/seeds/specs/hard/frontend/41-design-handoff-protocol.md +0 -80
- package/seeds/specs/hard/frontend/42-browser-runtime-lifecycle-protocol.md +0 -86
- package/seeds/specs/hard/frontend/43-time-temporal-protocol.md +0 -86
- package/seeds/specs/hard/frontend/44-privacy-data-lifecycle-protocol.md +0 -87
- package/seeds/specs/hard/frontend/45-browser-storage-protocol.md +0 -87
- package/seeds/specs/hard/frontend/index.md +0 -308
|
@@ -1,80 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
seed_source: pomaster/components/frontend-hard-spec/assets/universal/08-role-responsibility-protocol.md
|
|
3
|
-
seed_source_sha256: 732ac305cd16207e4a7bd4c95a6774d1aca33fb4e45cf29991ac0f6475605d6f
|
|
4
|
-
seed_version: B6B-1
|
|
5
|
-
lane: frontend
|
|
6
|
-
status: CURRENT
|
|
7
|
-
authority_scope: mixed_required_and_advisory
|
|
8
|
-
applies_to: [frontend]
|
|
9
|
-
related_evidence_specs: []
|
|
10
|
-
related_tools: []
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# 08 角色责任协议
|
|
14
|
-
|
|
15
|
-
## Scope
|
|
16
|
-
|
|
17
|
-
P0/P1 治理协议。定义需求、设计、前端、后端、测试、平台、安全、协议和 AI 协作中的责任边界。
|
|
18
|
-
|
|
19
|
-
## Non-Scope
|
|
20
|
-
|
|
21
|
-
不规定组织架构、职级、绩效或人员姓名,不替代项目管理系统。
|
|
22
|
-
|
|
23
|
-
## Terms
|
|
24
|
-
|
|
25
|
-
- Responsible:执行者。
|
|
26
|
-
- Accountable:最终责任者。
|
|
27
|
-
- Consulted:必须征询者。
|
|
28
|
-
- Informed:必须通知者。
|
|
29
|
-
- Approver:有权放行例外者。
|
|
30
|
-
|
|
31
|
-
## MUST
|
|
32
|
-
|
|
33
|
-
- 每个协议、公共组件、接口、业务规则和发布都有 Accountable Owner。
|
|
34
|
-
- 跨团队变更开发前确定 Reviewer 和通知范围。
|
|
35
|
-
- 无 Owner 的关键决策必须阻塞并升级。
|
|
36
|
-
- AI 输出必须由人类 Owner Review,AI 不得成为 Approver。
|
|
37
|
-
|
|
38
|
-
## MUST NOT
|
|
39
|
-
|
|
40
|
-
- MUST NOT 用“团队共同负责”隐藏无人负责。
|
|
41
|
-
- MUST NOT 让前端单方面决定后端契约、公式或数据权限。
|
|
42
|
-
- MUST NOT 让设计稿覆盖安全、可访问性或公共 API。
|
|
43
|
-
- MUST NOT 让 AI 代替业务、合规或上线签字。
|
|
44
|
-
|
|
45
|
-
## SHOULD
|
|
46
|
-
|
|
47
|
-
- SHOULD 为跨层能力维护轻量 RACI。
|
|
48
|
-
- SHOULD 为 Owner 缺席定义代理和升级路径。
|
|
49
|
-
|
|
50
|
-
## Contract
|
|
51
|
-
|
|
52
|
-
```text
|
|
53
|
-
ArtifactOrDecision, Responsible, Accountable,
|
|
54
|
-
Consulted[], Informed[], RequiredReviewers[], EscalationPath
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
## Checklist
|
|
58
|
-
|
|
59
|
-
- [ ] 各阶段 Owner 明确。
|
|
60
|
-
- [ ] 跨层 Reviewer 已确定。
|
|
61
|
-
- [ ] 例外有批准者。
|
|
62
|
-
- [ ] AI 输出有人类责任人。
|
|
63
|
-
|
|
64
|
-
## Examples
|
|
65
|
-
|
|
66
|
-
### 内容示例,可删除
|
|
67
|
-
|
|
68
|
-
业务 Owner 定义金额口径,后端负责权威计算,前端负责无损展示,QA 验证边界。
|
|
69
|
-
|
|
70
|
-
## Anti-patterns
|
|
71
|
-
|
|
72
|
-
接口含义未确认时由前端和 AI 自行解释,最终无人能判断哪个结果正确。
|
|
73
|
-
|
|
74
|
-
## Ownership
|
|
75
|
-
|
|
76
|
-
项目负责人维护角色模型,各领域 Owner 维护其 RACI,治理 Owner 处理无人归属。
|
|
77
|
-
|
|
78
|
-
## Change Policy
|
|
79
|
-
|
|
80
|
-
角色或批准边界变化必须通知协作者;临时代理必须有范围和期限。
|
|
@@ -1,81 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
seed_source: pomaster/components/frontend-hard-spec/assets/universal/09-module-boundary-protocol.md
|
|
3
|
-
seed_source_sha256: f9a3c194910bbb31cd322849cb277db5d2ae0fd74773eef7df34197b8ad89c4f
|
|
4
|
-
seed_version: B6B-1
|
|
5
|
-
lane: frontend
|
|
6
|
-
status: CURRENT
|
|
7
|
-
authority_scope: mixed_required_and_advisory
|
|
8
|
-
applies_to: [frontend]
|
|
9
|
-
related_evidence_specs: []
|
|
10
|
-
related_tools: []
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# 09 模块边界协议
|
|
14
|
-
|
|
15
|
-
## Scope
|
|
16
|
-
|
|
17
|
-
P0。定义顶层目录职责、依赖方向、公开入口、shared 下沉和跨模块协作。
|
|
18
|
-
|
|
19
|
-
## Non-Scope
|
|
20
|
-
|
|
21
|
-
不规定具体框架目录名,不替代组件、状态或业务规则协议。
|
|
22
|
-
|
|
23
|
-
## Terms
|
|
24
|
-
|
|
25
|
-
- Module:有明确职责、Owner 和公开入口的代码边界。
|
|
26
|
-
- Public API:允许其他模块依赖的最小出口。
|
|
27
|
-
- Internal:只允许模块内部使用的实现。
|
|
28
|
-
- Shared:无特定业务所有权且满足复用门槛的能力。
|
|
29
|
-
|
|
30
|
-
## MUST
|
|
31
|
-
|
|
32
|
-
- 顶层目录和模块职责必须文档化。
|
|
33
|
-
- 依赖方向和禁止方向必须可检查。
|
|
34
|
-
- 模块外部只能通过 Public API 引用。
|
|
35
|
-
- 跨模块流程进入明确的 orchestration/feature 层。
|
|
36
|
-
- shared 下沉必须证明稳定复用和低业务耦合。
|
|
37
|
-
- 循环依赖必须被工具检测并阻止。
|
|
38
|
-
|
|
39
|
-
## MUST NOT
|
|
40
|
-
|
|
41
|
-
- MUST NOT 引用其他模块内部文件。
|
|
42
|
-
- MUST NOT 把页面代码作为其他模块依赖。
|
|
43
|
-
- MUST NOT 因方便把业务能力放进 shared。
|
|
44
|
-
- MUST NOT 新建无职责说明的顶层目录。
|
|
45
|
-
|
|
46
|
-
## SHOULD
|
|
47
|
-
|
|
48
|
-
- SHOULD 每个模块维护 contract、owner 和 index/public exports。
|
|
49
|
-
- SHOULD 用依赖图和 lint 自动执行边界。
|
|
50
|
-
|
|
51
|
-
## Contract
|
|
52
|
-
|
|
53
|
-
```text
|
|
54
|
-
Module, Responsibility, Owner, PublicExports[],
|
|
55
|
-
AllowedDependencies[], ForbiddenDependencies[], InternalPaths[]
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
## Checklist
|
|
59
|
-
|
|
60
|
-
- [ ] 新文件归属可解释。
|
|
61
|
-
- [ ] 只通过公开入口依赖。
|
|
62
|
-
- [ ] shared 满足下沉条件。
|
|
63
|
-
- [ ] 无循环或越层引用。
|
|
64
|
-
|
|
65
|
-
## Examples
|
|
66
|
-
|
|
67
|
-
### 内容示例,可删除
|
|
68
|
-
|
|
69
|
-
两个业务域共同参与的导入流程放入 feature/orchestration 层,而不是让域 A 引用域 B 的页面。
|
|
70
|
-
|
|
71
|
-
## Anti-patterns
|
|
72
|
-
|
|
73
|
-
把带客户、订单、成本语义的组件放入 shared,再被多个模块反向耦合。
|
|
74
|
-
|
|
75
|
-
## Ownership
|
|
76
|
-
|
|
77
|
-
架构 Owner 维护顶层边界,模块 Owner 维护公开入口,Reviewer 阻止越层引用。
|
|
78
|
-
|
|
79
|
-
## Change Policy
|
|
80
|
-
|
|
81
|
-
新增顶层模块、改变依赖方向或扩大 Public API 必须经过架构评审和迁移说明。
|
|
@@ -1,89 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
seed_source: pomaster/components/frontend-hard-spec/assets/universal/10-engineering-tooling-protocol.md
|
|
3
|
-
seed_source_sha256: c628d47dcae1ddd58ea3651eeae9dd84ff5157365a3892a367bd7b5bf0af2b9d
|
|
4
|
-
seed_version: B6B-1
|
|
5
|
-
lane: frontend
|
|
6
|
-
status: CURRENT
|
|
7
|
-
authority_scope: mixed_required_and_advisory
|
|
8
|
-
applies_to: [frontend]
|
|
9
|
-
related_evidence_specs: []
|
|
10
|
-
related_tools: []
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# 10 工程工具协议
|
|
14
|
-
|
|
15
|
-
## Scope
|
|
16
|
-
|
|
17
|
-
P0。用类型、格式、Lint、契约、测试、示例、CI 和 ADR 固化团队协议。
|
|
18
|
-
|
|
19
|
-
## Non-Scope
|
|
20
|
-
|
|
21
|
-
不强制所有项目使用同一框架或供应商工具,不替代依赖评审。
|
|
22
|
-
|
|
23
|
-
## Terms
|
|
24
|
-
|
|
25
|
-
- Quality Command:本地与 CI 共用的标准检查入口。
|
|
26
|
-
- Generated Artifact:由可重复命令生成、禁止手改的文件。
|
|
27
|
-
- ADR:记录重要架构决策及后果的文档。
|
|
28
|
-
|
|
29
|
-
## MUST
|
|
30
|
-
|
|
31
|
-
- 项目明确 TypeScript/类型、Lint、Format、样式、测试和构建工具。
|
|
32
|
-
- 本地与 CI 使用相同标准命令。
|
|
33
|
-
- 接口契约和生成物必须可重复生成和校验。
|
|
34
|
-
- 公共组件必须有可运行示例。
|
|
35
|
-
- 重要架构和工具决策必须记录 ADR/RFC。
|
|
36
|
-
- 工具违规必须产生明确失败而非仅提示。
|
|
37
|
-
- 运行时、包管理器和关键构建工具版本必须被仓库内机器可读配置固定,并由 CI 校验。
|
|
38
|
-
- TypeScript 项目必须启用与代码库兼容的严格类型检查;暂不能启用的严格选项必须有范围、Owner、迁移计划和期限。
|
|
39
|
-
- 外部数据必须先经运行时校验再进入可信类型;类型断言和非空断言不得替代边界验证。
|
|
40
|
-
- 配置必须有单一有效来源,废弃配置应移除或显式失效,避免多个配置文件竞争生效。
|
|
41
|
-
|
|
42
|
-
## MUST NOT
|
|
43
|
-
|
|
44
|
-
- MUST NOT 只靠口头约定格式、类型、接口和组件用法。
|
|
45
|
-
- MUST NOT 手改生成物。
|
|
46
|
-
- MUST NOT 为局部问题关闭全局规则。
|
|
47
|
-
- MUST NOT 让 CI 与本地使用不同质量标准。
|
|
48
|
-
- MUST NOT 依赖开发机全局安装的工具或隐式环境状态完成构建和检查。
|
|
49
|
-
- MUST NOT 用项目级忽略、`any`、类型断言或关闭规则掩盖局部问题;例外必须最小化并可追踪。
|
|
50
|
-
|
|
51
|
-
## SHOULD
|
|
52
|
-
|
|
53
|
-
- SHOULD 自动检测依赖边界、契约漂移、包体、可访问性和视觉回归。
|
|
54
|
-
- SHOULD 提供一条命令执行常规质量门禁。
|
|
55
|
-
|
|
56
|
-
## Contract
|
|
57
|
-
|
|
58
|
-
```text
|
|
59
|
-
Tool, Purpose, VersionPolicy, Command,
|
|
60
|
-
Inputs, Outputs, FailureCondition, Owner
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
## Checklist
|
|
64
|
-
|
|
65
|
-
- [ ] 工具和命令明确。
|
|
66
|
-
- [ ] CI 可自动发现违规。
|
|
67
|
-
- [ ] 生成过程可重复。
|
|
68
|
-
- [ ] 公共组件有示例。
|
|
69
|
-
- [ ] 重要决策有记录。
|
|
70
|
-
- [ ] 运行时和工具版本可复现,未依赖全局安装。
|
|
71
|
-
- [ ] 类型严格度和例外有边界、Owner 与迁移计划。
|
|
72
|
-
|
|
73
|
-
## Examples
|
|
74
|
-
|
|
75
|
-
### 内容示例,可删除
|
|
76
|
-
|
|
77
|
-
类型、lint、单测和构建通过统一脚本运行,CI 直接调用相同脚本。
|
|
78
|
-
|
|
79
|
-
## Anti-patterns
|
|
80
|
-
|
|
81
|
-
开发者本地忽略类型错误,CI 又没有 typecheck,问题直到上线构建才暴露。
|
|
82
|
-
|
|
83
|
-
## Ownership
|
|
84
|
-
|
|
85
|
-
工程 Owner 维护工具链,模块 Owner 修复违规,CI Owner 保证门禁可靠。
|
|
86
|
-
|
|
87
|
-
## Change Policy
|
|
88
|
-
|
|
89
|
-
工具新增、替换或规则放宽必须评估迁移、性能和开发体验,并提供版本化配置。
|
|
@@ -1,87 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
seed_source: pomaster/components/frontend-hard-spec/assets/universal/11-dependency-package-management-protocol.md
|
|
3
|
-
seed_source_sha256: a0cc135edaf0dfd1f5122d2ff7298866143ef3a273ad4d45f5e1eff763691867
|
|
4
|
-
seed_version: B6B-1
|
|
5
|
-
lane: frontend
|
|
6
|
-
status: CURRENT
|
|
7
|
-
authority_scope: mixed_required_and_advisory
|
|
8
|
-
applies_to: [frontend]
|
|
9
|
-
related_evidence_specs: []
|
|
10
|
-
related_tools: []
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# 11 依赖与包管理协议
|
|
14
|
-
|
|
15
|
-
## Scope
|
|
16
|
-
|
|
17
|
-
P1。管理包管理器、锁文件、依赖引入、版本、许可证、安全、升级和删除。
|
|
18
|
-
|
|
19
|
-
## Non-Scope
|
|
20
|
-
|
|
21
|
-
不规定具体框架选型,不替代供应链扫描和法律审查。
|
|
22
|
-
|
|
23
|
-
## Terms
|
|
24
|
-
|
|
25
|
-
- Runtime Dependency:进入生产运行路径的依赖。
|
|
26
|
-
- Development Dependency:仅构建、测试或开发使用。
|
|
27
|
-
- Dependency Budget:包体、维护、安全和替换成本预算。
|
|
28
|
-
|
|
29
|
-
## MUST
|
|
30
|
-
|
|
31
|
-
- 固定包管理器、锁文件和受信 registry。
|
|
32
|
-
- 固定 runtime 与包管理器版本;仓库只能有一种生效锁文件,CI 使用 frozen/immutable 安装并在 manifest 与锁文件漂移时失败。
|
|
33
|
-
- 引入前检查现有能力、维护状态、许可证、安全、包体和替代方案。
|
|
34
|
-
- 依赖变更必须审查直接与传递依赖、完整性/来源、安装脚本、可执行代码、发布内容和锁文件差异。
|
|
35
|
-
- 正确区分 runtime/dev 并保证可重复安装。
|
|
36
|
-
- 升级审查 breaking changes、测试和回滚。
|
|
37
|
-
- 删除未使用依赖及其配置、适配和文档。
|
|
38
|
-
- 构建插件、CI action、代码生成器和远程脚本按供应链依赖治理;可变引用必须改为不可变版本或受控版本策略。
|
|
39
|
-
|
|
40
|
-
## MUST NOT
|
|
41
|
-
|
|
42
|
-
- MUST NOT 为简单函数引入大型库。
|
|
43
|
-
- MUST NOT 并存职责重复的核心库而无批准。
|
|
44
|
-
- MUST NOT 手改或绕过锁文件。
|
|
45
|
-
- MUST NOT 忽略高危漏洞和许可证冲突。
|
|
46
|
-
- MUST NOT 盲目执行依赖安装脚本、远程脚本或自动修复命令而不审查将执行和变更的内容。
|
|
47
|
-
- MUST NOT 只审查 `package.json` 而忽略锁文件、传递依赖和 CI/构建依赖变化。
|
|
48
|
-
|
|
49
|
-
## SHOULD
|
|
50
|
-
|
|
51
|
-
- SHOULD 选择维护活跃、tree-shakable、类型完整的依赖。
|
|
52
|
-
- SHOULD 通过 adapter 隔离高替换成本 API。
|
|
53
|
-
- SHOULD 自动执行依赖差异、安全、许可证和来源审查;发布包时生成可验证 provenance/SBOM,并检查发布内容不含凭据、测试身份或私有 source map。
|
|
54
|
-
|
|
55
|
-
## Contract
|
|
56
|
-
|
|
57
|
-
```text
|
|
58
|
-
Package, Purpose, AlternativesChecked, RuntimeOrDev,
|
|
59
|
-
VersionPolicy, LockfileImpact, TransitiveDiff, Integrity, Provenance,
|
|
60
|
-
InstallScripts, BundleImpact, License, Security, Owner, RemovalPlan
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
## Checklist
|
|
64
|
-
|
|
65
|
-
- [ ] 新增必要性已证明。
|
|
66
|
-
- [ ] 安全、许可、维护、包体已评估。
|
|
67
|
-
- [ ] 安装可重复。
|
|
68
|
-
- [ ] 有升级和移除策略。
|
|
69
|
-
- [ ] 传递依赖、安装脚本和构建/CI 依赖已审查。
|
|
70
|
-
|
|
71
|
-
## Examples
|
|
72
|
-
|
|
73
|
-
### 内容示例,可删除
|
|
74
|
-
|
|
75
|
-
引入表格引擎前比较现有组件、许可证、虚拟滚动、可访问性和长期维护,并通过 adapter 隔离。
|
|
76
|
-
|
|
77
|
-
## Anti-patterns
|
|
78
|
-
|
|
79
|
-
多个页面分别引入不同日期库,只为格式化日期,造成包体和时区行为不一致。
|
|
80
|
-
|
|
81
|
-
## Ownership
|
|
82
|
-
|
|
83
|
-
工程 Owner 维护策略,模块 Owner 负责新增,安全/法务裁决风险。
|
|
84
|
-
|
|
85
|
-
## Change Policy
|
|
86
|
-
|
|
87
|
-
新增或主版本升级需要评审记录;紧急安全升级可加速但必须补测试。
|
|
@@ -1,79 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
seed_source: pomaster/components/frontend-hard-spec/assets/universal/12-business-rules-protocol.md
|
|
3
|
-
seed_source_sha256: dda683a7c907989032c82a2c1c3e552b51226e0e0cd5bdf3b6068cc7f649c525
|
|
4
|
-
seed_version: B6B-1
|
|
5
|
-
lane: frontend
|
|
6
|
-
status: CURRENT
|
|
7
|
-
authority_scope: mixed_required_and_advisory
|
|
8
|
-
applies_to: [frontend]
|
|
9
|
-
related_evidence_specs: []
|
|
10
|
-
related_tools: []
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# 12 业务规则协议
|
|
14
|
-
|
|
15
|
-
## Scope
|
|
16
|
-
|
|
17
|
-
P1。定义领域校验、操作许可、状态流转、时间范围、金额规则入口和后端兜底关系。
|
|
18
|
-
|
|
19
|
-
## Non-Scope
|
|
20
|
-
|
|
21
|
-
不定义视觉呈现,不允许前端规则替代后端权威规则。
|
|
22
|
-
|
|
23
|
-
## Terms
|
|
24
|
-
|
|
25
|
-
- Domain Rule:不依赖具体页面的业务判断。
|
|
26
|
-
- State Machine:合法状态及转换集合。
|
|
27
|
-
- Authoritative Validation:决定业务结果的后端校验。
|
|
28
|
-
|
|
29
|
-
## MUST
|
|
30
|
-
|
|
31
|
-
- 规则集中存放、命名、测试并有 Owner。
|
|
32
|
-
- 页面和组件调用规则函数,不复制表达式。
|
|
33
|
-
- 状态转换声明来源、目标、条件、权限和失败码。
|
|
34
|
-
- 金额、比例、日期区间和操作限制有明确契约。
|
|
35
|
-
- 后端执行最终一致性和权威校验。
|
|
36
|
-
|
|
37
|
-
## MUST NOT
|
|
38
|
-
|
|
39
|
-
- MUST NOT 将同一规则散落在组件、文案和 API 回调。
|
|
40
|
-
- MUST NOT 以按钮禁用代替后端校验。
|
|
41
|
-
- MUST NOT 在无正式来源时发明状态或公式。
|
|
42
|
-
- MUST NOT 用展示文案作为规则返回值。
|
|
43
|
-
|
|
44
|
-
## SHOULD
|
|
45
|
-
|
|
46
|
-
- SHOULD 使用纯函数、schema 和状态机表达可测试规则。
|
|
47
|
-
- SHOULD 返回稳定原因码供 UI 映射文案。
|
|
48
|
-
|
|
49
|
-
## Contract
|
|
50
|
-
|
|
51
|
-
```text
|
|
52
|
-
RuleId, Inputs, Preconditions, Result,
|
|
53
|
-
ReasonCodes[], BackendEnforcement, Owner, Version
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
## Checklist
|
|
57
|
-
|
|
58
|
-
- [ ] 规则来源和 Owner 明确。
|
|
59
|
-
- [ ] 页面未复制规则。
|
|
60
|
-
- [ ] 状态与错误码完整。
|
|
61
|
-
- [ ] 后端有权威兜底。
|
|
62
|
-
|
|
63
|
-
## Examples
|
|
64
|
-
|
|
65
|
-
### 内容示例,可删除
|
|
66
|
-
|
|
67
|
-
`canApprove(entity, actor)` 返回允许状态和原因码,页面仅决定如何展示。
|
|
68
|
-
|
|
69
|
-
## Anti-patterns
|
|
70
|
-
|
|
71
|
-
三个页面分别用不同 if 判断“审批中不可编辑”,导致规则漂移。
|
|
72
|
-
|
|
73
|
-
## Ownership
|
|
74
|
-
|
|
75
|
-
业务/领域 Owner 定义语义,后端 Owner 保证权威执行,前端负责一致呈现。
|
|
76
|
-
|
|
77
|
-
## Change Policy
|
|
78
|
-
|
|
79
|
-
规则或状态变化必须版本化并同步 API、权限、审计、文案和测试。
|
|
@@ -1,81 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
seed_source: pomaster/components/frontend-hard-spec/assets/universal/13-monetary-precision-protocol.md
|
|
3
|
-
seed_source_sha256: 4930246c7dfed2751d3a71d617a21e24b46b376131723451b39152582c7a3d4f
|
|
4
|
-
seed_version: B6B-1
|
|
5
|
-
lane: frontend
|
|
6
|
-
status: CURRENT
|
|
7
|
-
authority_scope: mixed_required_and_advisory
|
|
8
|
-
applies_to: [frontend]
|
|
9
|
-
related_evidence_specs: []
|
|
10
|
-
related_tools: []
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# 13 金额精度协议
|
|
14
|
-
|
|
15
|
-
## Scope
|
|
16
|
-
|
|
17
|
-
P1。定义金额、单价、成本、汇率、比例和汇总的传输、计算、比较、展示与导出精度。
|
|
18
|
-
|
|
19
|
-
## Non-Scope
|
|
20
|
-
|
|
21
|
-
不定义业务公式、税务政策、币种范围或最终结算口径。
|
|
22
|
-
|
|
23
|
-
## Terms
|
|
24
|
-
|
|
25
|
-
- Amount:十进制定点值。
|
|
26
|
-
- Currency:正式币种标识。
|
|
27
|
-
- Scale:小数位数量。
|
|
28
|
-
- Rounding Mode/Stage:舍入方式与时点。
|
|
29
|
-
|
|
30
|
-
## MUST
|
|
31
|
-
|
|
32
|
-
- 金额声明 amount、currency、scale 和舍入规则。
|
|
33
|
-
- 传输使用十进制字符串或无歧义最小单位整数。
|
|
34
|
-
- 权威计算使用 Decimal/BigDecimal 等十进制能力。
|
|
35
|
-
- 区分原始、计算、展示和导出值。
|
|
36
|
-
- 汇总按正式顺序计算和舍入。
|
|
37
|
-
- 百分比声明传输倍率。
|
|
38
|
-
|
|
39
|
-
## MUST NOT
|
|
40
|
-
|
|
41
|
-
- MUST NOT 使用二进制浮点执行正式金额累计、乘除和相等比较。
|
|
42
|
-
- MUST NOT 用 `toFixed` 代替十进制计算。
|
|
43
|
-
- MUST NOT 混合币种直接求和。
|
|
44
|
-
- MUST NOT 页面、报表、导出各自决定精度。
|
|
45
|
-
|
|
46
|
-
## SHOULD
|
|
47
|
-
|
|
48
|
-
- SHOULD 使用统一 Money/Decimal 类型、parser 和 formatter。
|
|
49
|
-
- SHOULD 测试负数、极值、尾数 5、汇总和跨币种边界。
|
|
50
|
-
|
|
51
|
-
## Contract
|
|
52
|
-
|
|
53
|
-
```text
|
|
54
|
-
Money { amount: decimal-string, currency: string, scale: integer }
|
|
55
|
-
Rule { calculationScale, displayScale, roundingMode, roundingStage }
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
## Checklist
|
|
59
|
-
|
|
60
|
-
- [ ] amount/currency/scale/rounding 完整。
|
|
61
|
-
- [ ] 未使用浮点做正式计算。
|
|
62
|
-
- [ ] 展示、汇总和导出一致。
|
|
63
|
-
- [ ] 比例和跨币种语义明确。
|
|
64
|
-
|
|
65
|
-
## Examples
|
|
66
|
-
|
|
67
|
-
### 内容示例,可删除
|
|
68
|
-
|
|
69
|
-
保留接口金额字符串,通过统一 formatter 展示,不先转为浮点数。
|
|
70
|
-
|
|
71
|
-
## Anti-patterns
|
|
72
|
-
|
|
73
|
-
用 `parseFloat` 累加成本,再 `toFixed(2)` 生成正式报表。
|
|
74
|
-
|
|
75
|
-
## Ownership
|
|
76
|
-
|
|
77
|
-
业务/财务定义口径,后端负责权威计算,前端负责无损传输,QA 验证边界。
|
|
78
|
-
|
|
79
|
-
## Change Policy
|
|
80
|
-
|
|
81
|
-
精度、币种、舍入或比例语义变化属于破坏性契约变更,必须同步全链路。
|
|
@@ -1,85 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
seed_source: pomaster/components/frontend-hard-spec/assets/universal/14-data-model-protocol.md
|
|
3
|
-
seed_source_sha256: 7d4e31ef04a1f57d88e982c01dabc22c421bafc850b7295a73d084ec3c6fc838
|
|
4
|
-
seed_version: B6B-1
|
|
5
|
-
lane: frontend
|
|
6
|
-
status: CURRENT
|
|
7
|
-
authority_scope: mixed_required_and_advisory
|
|
8
|
-
applies_to: [frontend]
|
|
9
|
-
related_evidence_specs: []
|
|
10
|
-
related_tools: []
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# 14 数据模型协议
|
|
14
|
-
|
|
15
|
-
## Scope
|
|
16
|
-
|
|
17
|
-
P1。定义 API DTO、Adapter、Domain Model、ViewModel、FormModel 和 RowModel 的分层。
|
|
18
|
-
|
|
19
|
-
## Non-Scope
|
|
20
|
-
|
|
21
|
-
不定义接口传输协议或具体业务公式,不允许模型层承担页面布局。
|
|
22
|
-
|
|
23
|
-
## Terms
|
|
24
|
-
|
|
25
|
-
- DTO:接口原始结构。
|
|
26
|
-
- Adapter:边界转换函数。
|
|
27
|
-
- Domain Model:稳定业务语义模型。
|
|
28
|
-
- ViewModel:面向展示或交互的模型。
|
|
29
|
-
|
|
30
|
-
## MUST
|
|
31
|
-
|
|
32
|
-
- 使用 `DTO -> Adapter -> Domain Model -> View/Form/Row Model` 链路。
|
|
33
|
-
- 明确类型命名、位置、Owner 和公开边界。
|
|
34
|
-
- 空值、未知枚举、日期、金额和单位在边界统一处理。
|
|
35
|
-
- API、浏览器存储、跨窗口消息、运行时配置和第三方 SDK 等外部数据必须在信任边界执行 schema 校验后再转换;失败时保守降级并产生安全监控。
|
|
36
|
-
- opaque ID、超出 JavaScript safe integer 的整数和高精度数值必须使用不会静默丢失精度的传输与模型类型。
|
|
37
|
-
- 后端字段变化优先只影响契约和 adapter。
|
|
38
|
-
- adapter 有正常、空值、未知值和边界测试。
|
|
39
|
-
|
|
40
|
-
## MUST NOT
|
|
41
|
-
|
|
42
|
-
- MUST NOT 让 DTO 穿透公共组件、模板或列定义。
|
|
43
|
-
- MUST NOT 在页面重复字段转换和兜底。
|
|
44
|
-
- MUST NOT 使用万能对象代替类型。
|
|
45
|
-
- MUST NOT 在模型转换中隐藏正式业务计算。
|
|
46
|
-
- MUST NOT 用 TypeScript 类型、类型断言或生成类型替代运行时外部数据校验。
|
|
47
|
-
- MUST NOT 把 opaque ID 或大整数转成可能丢失精度的 `number`。
|
|
48
|
-
|
|
49
|
-
## SHOULD
|
|
50
|
-
|
|
51
|
-
- SHOULD 使用 schema 校验外部数据。
|
|
52
|
-
- SHOULD 为未知枚举保留安全兜底和监控。
|
|
53
|
-
|
|
54
|
-
## Contract
|
|
55
|
-
|
|
56
|
-
```text
|
|
57
|
-
SourceDTO, RuntimeSchema, Adapter, DomainModel, ConsumerModel,
|
|
58
|
-
NullPolicy, EnumPolicy, IdentifierPolicy, PrecisionPolicy, FormatPolicy, Owner
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## Checklist
|
|
62
|
-
|
|
63
|
-
- [ ] 模型层次明确。
|
|
64
|
-
- [ ] 外部数据已校验转换。
|
|
65
|
-
- [ ] 组件只消费稳定模型。
|
|
66
|
-
- [ ] adapter 测试完整。
|
|
67
|
-
- [ ] 外部数据校验失败和大整数/opaque ID 已覆盖。
|
|
68
|
-
|
|
69
|
-
## Examples
|
|
70
|
-
|
|
71
|
-
### 内容示例,可删除
|
|
72
|
-
|
|
73
|
-
API 的 snake_case DTO 经 adapter 转成稳定 Domain Model,再生成表格 RowModel。
|
|
74
|
-
|
|
75
|
-
## Anti-patterns
|
|
76
|
-
|
|
77
|
-
模板直接访问后端字段并在多个单元格各自处理 null 和枚举。
|
|
78
|
-
|
|
79
|
-
## Ownership
|
|
80
|
-
|
|
81
|
-
API Owner 维护 DTO,领域 Owner 维护 Domain Model,前端模块 Owner 维护 adapter/ViewModel。
|
|
82
|
-
|
|
83
|
-
## Change Policy
|
|
84
|
-
|
|
85
|
-
模型字段变化必须说明兼容、迁移和受影响消费者;公共模型不得静默改语义。
|
|
@@ -1,87 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
seed_source: pomaster/components/frontend-hard-spec/assets/universal/15-request-api-protocol.md
|
|
3
|
-
seed_source_sha256: b9489d69e35a19b8d5ba2442108190e7b99989ef471c8cf413d9e4e408ca2969
|
|
4
|
-
seed_version: B6B-1
|
|
5
|
-
lane: frontend
|
|
6
|
-
status: CURRENT
|
|
7
|
-
authority_scope: mixed_required_and_advisory
|
|
8
|
-
applies_to: [frontend]
|
|
9
|
-
related_evidence_specs: []
|
|
10
|
-
related_tools: []
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# 15 请求与 API 协议
|
|
14
|
-
|
|
15
|
-
## Scope
|
|
16
|
-
|
|
17
|
-
P1。定义正式契约进入前端后的请求封装、取消、重试、loading、错误归一化和 API 函数。
|
|
18
|
-
|
|
19
|
-
## Non-Scope
|
|
20
|
-
|
|
21
|
-
不定义后端接口本身,不负责页面错误文案和缓存业务规则。
|
|
22
|
-
|
|
23
|
-
## Terms
|
|
24
|
-
|
|
25
|
-
- HTTP Client:统一传输基础设施。
|
|
26
|
-
- Domain API:面向业务语义的请求函数。
|
|
27
|
-
- Request Context:认证、语言、trace、幂等等上下文。
|
|
28
|
-
|
|
29
|
-
## MUST
|
|
30
|
-
|
|
31
|
-
- 页面只调用封装的 Domain API。
|
|
32
|
-
- HTTP Client 统一处理 base URL、认证、超时、取消、trace 和 envelope。
|
|
33
|
-
- 请求函数使用稳定领域动词命名并有类型。
|
|
34
|
-
- 查询可取消和丢弃过期响应。
|
|
35
|
-
- mutation 明确幂等和重试边界。
|
|
36
|
-
- 错误转换为统一结构。
|
|
37
|
-
- 传输成功与业务成功必须分别判断;HTTP 非成功状态、契约解析失败、取消、超时、离线和业务错误不得混为一类。
|
|
38
|
-
- 重试必须服从幂等性、服务端 `Retry-After` 或受控退避,并能取消;取消或已被替代的请求不得提示为用户错误。
|
|
39
|
-
- 请求结果提交前必须验证身份、租户、权限、参数和请求版本,防止旧上下文结果写回。
|
|
40
|
-
- endpoint、redirect 和 base URL 只能来自受控配置或契约,不得由不可信 URL 参数直接拼接。
|
|
41
|
-
|
|
42
|
-
## MUST NOT
|
|
43
|
-
|
|
44
|
-
- MUST NOT 在页面直接写 fetch/axios 或拼 endpoint。
|
|
45
|
-
- MUST NOT 多处重复 token、错误码和重试逻辑。
|
|
46
|
-
- MUST NOT 对非幂等 mutation 默认自动重试。
|
|
47
|
-
- MUST NOT 让组件解析原始响应 envelope。
|
|
48
|
-
- MUST NOT 把“网络在线”提示当成请求成功证明,或假设 HTTP 404/500 一定以 Promise rejection 表现。
|
|
49
|
-
|
|
50
|
-
## SHOULD
|
|
51
|
-
|
|
52
|
-
- SHOULD 通过生成客户端或 typed adapter 对接正式契约。
|
|
53
|
-
- SHOULD 让 loading 来源唯一,避免重复状态。
|
|
54
|
-
|
|
55
|
-
## Contract
|
|
56
|
-
|
|
57
|
-
```text
|
|
58
|
-
FunctionName, InputType, OutputType, ErrorType,
|
|
59
|
-
StatusPolicy, Cancellation, Retry, RetryAfter, Idempotency,
|
|
60
|
-
ContextVersion, LateResultGuard, Trace
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
## Checklist
|
|
64
|
-
|
|
65
|
-
- [ ] 页面只使用 Domain API。
|
|
66
|
-
- [ ] 类型和错误统一。
|
|
67
|
-
- [ ] 取消、重试、幂等明确。
|
|
68
|
-
- [ ] 无重复 loading/认证逻辑。
|
|
69
|
-
- [ ] 状态判断、旧结果防护和 endpoint 来源明确。
|
|
70
|
-
|
|
71
|
-
## Examples
|
|
72
|
-
|
|
73
|
-
### 内容示例,可删除
|
|
74
|
-
|
|
75
|
-
`getEntityList(query, signal)` 返回稳定分页模型,调用方不认识 endpoint 和 envelope。
|
|
76
|
-
|
|
77
|
-
## Anti-patterns
|
|
78
|
-
|
|
79
|
-
每个页面各自创建请求实例、刷新 token 并比较 message。
|
|
80
|
-
|
|
81
|
-
## Ownership
|
|
82
|
-
|
|
83
|
-
平台 Owner 维护 HTTP Client,领域 Owner 维护 Domain API,契约 Owner 维护类型来源。
|
|
84
|
-
|
|
85
|
-
## Change Policy
|
|
86
|
-
|
|
87
|
-
客户端公共行为变化必须评估全部请求;函数破坏性变化提供迁移和弃用期。
|