From 28ecacdd42bb8e431d9c496ec11a602a04482c1b Mon Sep 17 00:00:00 2001 From: liuyun Date: Sun, 11 Oct 2026 22:42:35 +0800 Subject: [PATCH] =?UTF-8?q?docs(spec):=20=E5=BD=92=E6=A1=A3=20error-code-r?= =?UTF-8?q?egistry=20+=20=E5=90=8C=E6=AD=A5=E9=94=99=E8=AF=AF=E7=A0=81?= =?UTF-8?q?=E5=88=86=E6=AE=B5=E4=B8=BB=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .../2026-10-11-error-code-registry}/.openspec.yaml | 0 .../2026-10-11-error-code-registry}/design.md | 0 .../2026-10-11-error-code-registry}/proposal.md | 0 .../specs/shared/api-contract/spec.md | 0 .../2026-10-11-error-code-registry}/tasks.md | 0 openspec/specs/shared/api-contract/spec.md | 12 ++++++++++-- 6 files changed, 10 insertions(+), 2 deletions(-) rename openspec/changes/{error-code-registry => archive/2026-10-11-error-code-registry}/.openspec.yaml (100%) rename openspec/changes/{error-code-registry => archive/2026-10-11-error-code-registry}/design.md (100%) rename openspec/changes/{error-code-registry => archive/2026-10-11-error-code-registry}/proposal.md (100%) rename openspec/changes/{error-code-registry => archive/2026-10-11-error-code-registry}/specs/shared/api-contract/spec.md (100%) rename openspec/changes/{error-code-registry => archive/2026-10-11-error-code-registry}/tasks.md (100%) diff --git a/openspec/changes/error-code-registry/.openspec.yaml b/openspec/changes/archive/2026-10-11-error-code-registry/.openspec.yaml similarity index 100% rename from openspec/changes/error-code-registry/.openspec.yaml rename to openspec/changes/archive/2026-10-11-error-code-registry/.openspec.yaml diff --git a/openspec/changes/error-code-registry/design.md b/openspec/changes/archive/2026-10-11-error-code-registry/design.md similarity index 100% rename from openspec/changes/error-code-registry/design.md rename to openspec/changes/archive/2026-10-11-error-code-registry/design.md diff --git a/openspec/changes/error-code-registry/proposal.md b/openspec/changes/archive/2026-10-11-error-code-registry/proposal.md similarity index 100% rename from openspec/changes/error-code-registry/proposal.md rename to openspec/changes/archive/2026-10-11-error-code-registry/proposal.md diff --git a/openspec/changes/error-code-registry/specs/shared/api-contract/spec.md b/openspec/changes/archive/2026-10-11-error-code-registry/specs/shared/api-contract/spec.md similarity index 100% rename from openspec/changes/error-code-registry/specs/shared/api-contract/spec.md rename to openspec/changes/archive/2026-10-11-error-code-registry/specs/shared/api-contract/spec.md diff --git a/openspec/changes/error-code-registry/tasks.md b/openspec/changes/archive/2026-10-11-error-code-registry/tasks.md similarity index 100% rename from openspec/changes/error-code-registry/tasks.md rename to openspec/changes/archive/2026-10-11-error-code-registry/tasks.md diff --git a/openspec/specs/shared/api-contract/spec.md b/openspec/specs/shared/api-contract/spec.md index 0e2241f..5694d8e 100644 --- a/openspec/specs/shared/api-contract/spec.md +++ b/openspec/specs/shared/api-contract/spec.md @@ -18,11 +18,19 @@ - **THEN** 返回非 0 code 与可读 message，data 为空 ### Requirement: 错误码分段 -错误码 SHALL 与 HTTP 状态对齐分段：401xx 认证、403xx 授权、400xx 参数、404xx 资源、409xx 冲突、500xx 系统。 +错误码 SHALL 采用「业务域 + 错误序」分段：5 位数字 `[域码 2 位][序 3 位]`，域码集中登记于 `error-codes` 注册表（00 通用、10 认证、11 用户、12 角色、13 资源、14 组织、15 租户、16 字典、17 配置、20 会话、21 通知…）；HTTP 状态仍按语义返回（400/401/403/404/409/500），`code` 为业务码。 #### Scenario: 未登录 - **WHEN** 未携带有效 token 访问受保护接口 -- **THEN** HTTP 401，code 为 401xx 段 +- **THEN** HTTP 401，code 为认证域业务码（如 10002），无业务码时回退 40100 + +#### Scenario: 业务错误码 +- **WHEN** 业务处理失败（如用户名已存在） +- **THEN** 返回对应 HTTP 状态 + 注册表内的业务码与可读 message + +#### Scenario: 系统错误兜底 +- **WHEN** 非业务异常（框架/未知错误） +- **THEN** code 回退为 HTTP 状态 ×100 ### Requirement: 分页约定 列表接口 SHALL 使用 page/pageSize 分页，返回 `{ list, total, page, pageSize }`。