# 示例模块（Example）

:::tip 说明
`src/modules/example/` 是一个完整的示例模块，演示了标准 CRUD 模块的六文件结构和开发模式。开发者可以此为模板快速创建新业务模块。
:::

## 文件结构

```
src/modules/example/
├── __init__.py       # 模块声明
├── models.py         # 数据模型
├── schemas.py        # 参数验证
├── repository.py     # 数据访问层
├── service.py        # 业务逻辑层
└── handlers.py       # 请求处理器
```

## 各文件说明

### models.py — 数据模型

```python
from sqlalchemy import Column, String, Integer, text
from core.base_model import BaseModel

class Example(BaseModel):
    """示例模型"""
    __tablename__ = "example"
    __table_args__ = {"comment": "示例表"}

    name = Column(String(255), nullable=False, comment="名称")
    status = Column(Integer, default=0, server_default=text("0"), comment="状态")
    sort = Column(Integer, default=0, server_default=text("0"), comment="排序")
```

### schemas.py — 参数验证

```python
from pydantic import Field
from core.base_schema import BaseSchema, BaseStatusSchema

class ExampleSchema(BaseSchema):
    """示例表单"""
    name: str = Field(..., min_length=1, max_length=150, description="名称")
    status: int = Field(default=0, ge=0, le=1, description="状态")
    sort: int = Field(default=0, ge=0, le=99999, description="排序")

class ExampleStatusSchema(BaseStatusSchema):
    """状态更新表单"""
    pass
```

### repository.py — 数据访问层

```python
from core.base_repository import BaseRepository
from modules.example.models import Example

class ExampleRepository(BaseRepository):
    """示例数据仓库"""
    model = Example
```

### service.py — 业务逻辑层

```python
from core.base_service import BaseService
from modules.example.models import Example
from modules.example.repository import ExampleRepository
from modules.example.schemas import ExampleSchema, ExampleStatusSchema

class ExampleService(BaseService):
    """示例服务"""
    model = Example
    repo_cls = ExampleRepository
    create_schema = ExampleSchema
    update_schema = ExampleSchema
    status_schema = ExampleStatusSchema
    page_like_fields = ("name",)
    page_eq_fields = ("status",)
    page_order_by = (("sort", "asc"),)

example_service = ExampleService()
```

### handlers.py — 请求处理器

```python
from common.middleware.access_decorators import check_demo, permission_required
from common.middleware.operation_log import operation_log
from core import response as R
from core.base_handler import BaseHandler
from modules.example.service import example_service

class ExamplePageHandler(BaseHandler):
    @permission_required("sys:example:list")
    async def get(self):
        return await example_service.get_page(self)

class ExampleDetailHandler(BaseHandler):
    @permission_required("sys:example:detail")
    async def get(self, id):
        return R.ok(self, data=example_service.get_detail(id))

class ExampleAddHandler(BaseHandler):
    @permission_required("sys:example:add")
    @check_demo
    @operation_log("示例管理", "添加")
    async def post(self):
        return await example_service.add(self)

class ExampleUpdateHandler(BaseHandler):
    @permission_required("sys:example:update")
    @check_demo
    @operation_log("示例管理", "更新")
    async def put(self):
        return await example_service.update(self)

class ExampleDeleteHandler(BaseHandler):
    @permission_required("sys:example:delete")
    @check_demo
    @operation_log("示例管理", "删除")
    async def delete(self, id):
        return await example_service.delete(self, id)

class ExampleStatusHandler(BaseHandler):
    @permission_required("sys:example:status")
    @check_demo
    @operation_log("示例管理", "设置状态")
    async def put(self):
        return await example_service.update_status(self)

class ExampleBatchDeleteHandler(BaseHandler):
    @permission_required("sys:example:delete")
    @check_demo
    @operation_log("示例管理", "批量删除")
    async def post(self):
        return await example_service.batch_delete(self)
```

## 路由注册

```python
# src/api/v1/example.py
from modules.example.handlers import (
    ExamplePageHandler, ExampleDetailHandler, ExampleAddHandler,
    ExampleUpdateHandler, ExampleDeleteHandler, ExampleStatusHandler,
    ExampleBatchDeleteHandler,
)

routes = [
    (r"/example/page", ExamplePageHandler),
    (r"/example/detail/(\d+)", ExampleDetailHandler),
    (r"/example/add", ExampleAddHandler),
    (r"/example/update", ExampleUpdateHandler),
    (r"/example/delete/(\d+)", ExampleDeleteHandler),
    (r"/example/status", ExampleStatusHandler),
    (r"/example/batchDelete", ExampleBatchDeleteHandler),
]
```

```python
# src/api/v1/router.py — 在 _RESOURCE_MODULES 中追加
from api.v1 import example
_RESOURCE_MODULES = [..., example]
```

## 开发新模块的步骤

基于 Example 模块创建新模块的流程：

```
1. 复制 src/modules/example/ 为新目录
2. 修改 models.py 中的表名和字段
3. 修改 schemas.py 中的表单验证
4. 修改 repository.py 中的 model 引用
5. 修改 service.py 中的配置项
6. 修改 handlers.py 中的权限字符串和日志描述
7. 复制 src/api/v1/example.py 为新路由文件
8. 在 router.py 中注册新路由
9. 在菜单管理中配置权限节点
```

## 总结

Example 模块是标准 CRUD 模块的参考实现，包含 models → schemas → repository → service → handlers → 路由六层结构。开发新模块时以此为模板，修改差异点即可快速完成。