# 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 规范

### 泛型参数
```python
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` | 企业注销 |

## 状态枚举

```python
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`