feat(m0): 后端骨架 + Web/安卓前端骨架 + 设计文档

- backend: FastAPI 应用工厂、统一错误信封、JWT、短信登录、工作区/成员/邀请、幂等中间件 - alembic 0001: workspace/member/invitation/audit_log/app_user + RLS 策略 + 双角色 GRANT - tests: 认证/工作区/租户隔离/幂等四组用例（尚未在本机执行） - web: React18+Vite 骨架（登录、工作区、邀请落地页） - android: Compose 骨架（登录、工作区列表） - 2.Design: PRODUCT-PLAN / ROADMAP-M0-M1 / NAMING / DEVELOPMENT
2026-10-28 02:38:53 +08:00
commit 0c53aa7062
72 changed files with 5320 additions and 0 deletions
@@ -0,0 +1,84 @@
+"""错误码与异常。错误码一旦对外发布就**不许改号**（客户端靠它做分支）。"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Any
+
+
+class ErrorCode(IntEnum):
+    OK = 0
+
+    # 1xxx 通用
+    BAD_REQUEST = 1001
+    VALIDATION_FAILED = 1002
+    NOT_FOUND = 1004
+    CONFLICT = 1009
+    PAYLOAD_TOO_LARGE = 1013
+    RATE_LIMITED = 1029
+    INTERNAL = 1500
+
+    # 2xxx 认证 / 账号
+    UNAUTHORIZED = 2001
+    TOKEN_EXPIRED = 2002
+    TOKEN_INVALID = 2003
+    SMS_CODE_INVALID = 2010
+    SMS_TOO_FREQUENT = 2011
+    ACCOUNT_DISABLED = 2012
+
+    # 3xxx 租户 / 权限
+    WORKSPACE_NOT_FOUND = 3001
+    NOT_A_MEMBER = 3003
+    INSUFFICIENT_ROLE = 3004
+    ALREADY_A_MEMBER = 3005
+    INVITATION_INVALID = 3010
+
+    # 4xxx 并发
+    VERSION_CONFLICT = 4009
+
+
+# 默认 HTTP 状态：业务码自己带语义，HTTP 只是传输层
+_HTTP_STATUS: dict[ErrorCode, int] = {
+    ErrorCode.OK: 200,
+    ErrorCode.BAD_REQUEST: 400,
+    ErrorCode.VALIDATION_FAILED: 422,
+    ErrorCode.NOT_FOUND: 404,
+    ErrorCode.CONFLICT: 409,
+    ErrorCode.PAYLOAD_TOO_LARGE: 413,
+    ErrorCode.RATE_LIMITED: 429,
+    ErrorCode.INTERNAL: 500,
+    ErrorCode.UNAUTHORIZED: 401,
+    ErrorCode.TOKEN_EXPIRED: 401,
+    ErrorCode.TOKEN_INVALID: 401,
+    ErrorCode.SMS_CODE_INVALID: 400,
+    ErrorCode.SMS_TOO_FREQUENT: 429,
+    ErrorCode.ACCOUNT_DISABLED: 403,
+    ErrorCode.WORKSPACE_NOT_FOUND: 404,
+    ErrorCode.NOT_A_MEMBER: 403,
+    ErrorCode.INSUFFICIENT_ROLE: 403,
+    ErrorCode.ALREADY_A_MEMBER: 409,
+    ErrorCode.INVITATION_INVALID: 400,
+    ErrorCode.VERSION_CONFLICT: 409,
+}
+
+
+class AppError(Exception):
+    """业务异常。__str__ 只用于日志，对外一律走 code + message。"""
+
+    def __init__(
+        self,
+        code: ErrorCode,
+        message: str | None = None,
+        *,
+        http_status: int | None = None,
+        details: Any = None,
+    ) -> None:
+        self.code = code
+        self.message = message or code.name
+        self.http_status = http_status or _HTTP_STATUS.get(code, 400)
+        self.details = details
+        super().__init__(f"[{int(code)}] {self.message}")
+
+
+def http_status_for(code: ErrorCode) -> int:
+    return _HTTP_STATUS.get(code, 400)