payment-platform/backend/docs/enterprise模块设计规范.md

Enterprise 模块设计规范

数据库表命名

• 表前缀：pay_
• 企业表：pay_enterprise

模块结构

app/plugin/module_payment/enterprise/
├── __init__.py
├── controller.py  # API 路由
├── crud.py       # 数据访问层
├── enums.py      # 枚举定义
├── model.py      # ORM 模型
├── schema.py     # Pydantic Schema
└── service.py    # 业务逻辑层

Schema 规范

命名规则

• EnterpriseCreateSchema - 创建请求
• EnterpriseUpdateSchema - 更新请求
• EnterpriseOutSchema - 详情响应
• EnterpriseListOutSchema - 列表响应
• EnterpriseInviteOutSchema - 邀请响应
• EnterpriseOperationOutSchema - 操作响应

字段类型

• 使用 Optional[T] 而非 T | None
• 所有字段使用 Field() 显式定义
• 必填字段：Field(description="...")
• 可选字段：Field(default=None, description="...")

校验

• 使用 @model_validator(mode="after") 进行自定义校验
• 校验方法添加详细文档注释

CRUD 规范

泛型参数

CRUDBase[EnterpriseModel, EnterpriseCreateSchema, EnterpriseUpdateSchema]

文档注释

参考 UserCRUD，包含：

• 方法功能描述
• 参数说明
• 返回值说明

Service 规范

返回类型

• 创建：EnterpriseOutSchema
• 邀请：EnterpriseInviteOutSchema
• 操作：EnterpriseOperationOutSchema 或 str（out_biz_no）

异步通知

• 解约、注销等操作不直接更新状态
• 由支付宝异步通知更新

API 路由

方法	路径	说明
POST	/enterprise	创建企业
GET	/enterprise/{out_biz_no}	查询详情
PUT	/enterprise/{out_biz_no}	更新企业
POST	/enterprise/{out_biz_no}/invite	申请邀请码
POST	/enterprise/{out_biz_no}/unsign	企业解约
POST	/enterprise/{out_biz_no}/delete	企业注销

状态枚举

class EnterpriseStatusEnum(str, Enum):
    ENTERPRISE_CREATE = "ENTERPRISE_CREATE"           # 企业入驻
    ENTERPRISE_ACTIVATED = "ENTERPRISE_ACTIVATED"    # 企业签约成功
    ENTERPRISE_UNSIGN = "ENTERPRISE_UNSIGN"          # 企业解约
    ENTERPRISE_WITHDRAW = "ENTERPRISE_WITHDRAW"     # 企业注销
    ENTERPRISE_AUTH = "ENTERPRISE_AUTH"              # 企业认证通过
    ENTERPRISE_AUTH_REJECTED = "ENTERPRISE_AUTH_REJECTED"  # 企业认证审核不通过

雪花算法

使用 app.utils.snowflake.get_snowflake_id() 生成唯一 ID

数据权限

• 使用 __permission_strategy__ 配置权限策略
• 默认 DATA_SCOPE