# 完整代码清单

本章汇总友链（Link）模块涉及的全部文件，便于开发时快速查阅和复制。

## 后端文件清单

### 1. 数据模型 `src/modules/link/models.py`

```python
# +======================================================================
# | 模块: 友链数据模型层
# | 说明: 定义友链表结构，继承 BaseModel 获得通用字段与序列化能力
# +======================================================================
"""友链数据模型。"""

from sqlalchemy import Column, Integer, String, text

from config.database import DB_PREFIX
from core.base_model import BaseModel


class Link(BaseModel):
    """友情链接模型"""
    __tablename__ = DB_PREFIX + "link"
    __table_args__ = {"comment": "友情链接表"}

    # 链接名称
    name = Column(String(255), nullable=False, index=True, comment="链接名称")
    # 链接类型
    type = Column(String(50), default="", comment="链接类型")
    # 链接来源
    form = Column(String(50), default="", comment="链接来源")
    # 链接图片
    image = Column(String(500), default="", comment="链接图片")
    # 链接地址
    url = Column(String(500), default="", comment="链接地址")
    # 状态：0-正常 1-停用
    status = Column(Integer, default=0, server_default=text("0"), comment="状态")
    # 排序
    sort = Column(Integer, default=0, server_default=text("0"), comment="排序")
```

### 2. 表单验证 `src/modules/link/schemas.py`

```python
# +======================================================================
# | 模块: 友链请求校验模型层
# | 说明: 定义友链创建/编辑与状态更新的 Pydantic 校验模型
# +======================================================================
"""友链请求校验模型。"""

from typing import Optional

from pydantic import BaseModel, Field

from core.base_schema import BaseSchema


class LinkSchema(BaseSchema):
    """友链创建/编辑表单"""
    # 链接名称
    name: str = Field(..., min_length=1, max_length=150, description="链接名称")
    # 链接类型
    type: Optional[str] = Field(default="", max_length=50, description="链接类型")
    # 链接来源
    form: Optional[str] = Field(default="", max_length=50, description="链接来源")
    # 链接图片
    image: Optional[str] = Field(default="", max_length=500, description="链接图片")
    # 链接地址
    url: Optional[str] = Field(default="", max_length=500, description="链接地址")
    # 状态
    status: Optional[int] = Field(default=0, ge=0, le=1, description="状态")
    # 排序
    sort: Optional[int] = Field(default=0, ge=0, le=99999, description="排序")


class LinkStatusSchema(BaseModel):
    """友链状态更新表单"""
    # 记录ID
    id: int = Field(..., gt=0, description="记录ID")
    # 状态
    status: int = Field(..., ge=0, le=1, description="状态")
```

### 3. 数据访问层 `src/modules/link/repository.py`

```python
# +======================================================================
# | 模块: 友链数据访问层
# | 说明: 定义友链仓储，继承 BaseRepository 获得通用 CRUD 与软删除能力
# +======================================================================
"""友链数据访问。"""

from core.base_repository import BaseRepository
from modules.link.models import Link


class LinkRepository(BaseRepository):
    """友链数据仓库"""
    model = Link
```

### 4. 业务逻辑层 `src/modules/link/service.py`

```python
# +======================================================================
# | 模块: 友链业务逻辑层
# | 说明: 定义友链服务，声明差异点（file_fields 自动处理图片），
# |       最后导出服务单例
# +======================================================================
"""友链业务逻辑。"""

from core.base_service import BaseService
from modules.link.models import Link
from modules.link.repository import LinkRepository
from modules.link.schemas import LinkSchema, LinkStatusSchema


class LinkService(BaseService):
    """友链服务"""

    # ============================================================
    # 基础声明
    # ============================================================
    model = Link
    repo_cls = LinkRepository

    # ============================================================
    # 差异点声明
    # ============================================================
    create_schema = LinkSchema
    update_schema = LinkSchema
    status_schema = LinkStatusSchema
    # 分页查询字段与排序
    page_like_fields = ("name",)
    page_eq_fields = ("type", "form", "status")
    page_order_by = (("sort", "asc"),)
    # 枚举显示名映射
    serialize_maps = {
        "type": "link_type",
        "form": "link_form",
    }
    # 文件字段：add/update 时自动 save_file，serialize 时自动补全 URL
    file_fields = ("image",)


# ======================================================================
# 服务单例
# ======================================================================
link_service = LinkService()
```

### 5. 请求处理器 `src/modules/link/handlers.py`

```python
# +======================================================================
# | 模块: 友链请求处理器层
# | 说明: 承接友情链接相关的 HTTP 请求，校验权限/演示模式并记录操作日志后，
# |       转交友链服务层处理（分页、详情、增删改、状态、批量删除等）
# +======================================================================
"""友链请求处理器。"""

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.link.service import link_service


# ======================================================================
# 查询友链分页数据
# ======================================================================
class LinkPageHandler(BaseHandler):
    """查询友链分页数据。"""

    @permission_required("sys:link:list")
    async def get(self):
        """GET 请求：返回友链分页列表。"""
        return await link_service.get_page(self)


# ======================================================================
# 查询友链详情
# ======================================================================
class LinkDetailHandler(BaseHandler):
    """查询友链详情。"""

    @permission_required("sys:link:detail")
    async def get(self, id):
        """GET 请求：按 ID 返回友链详情。"""
        return R.ok(self, data=link_service.get_detail(id))


# ======================================================================
# 添加友链
# ======================================================================
class LinkAddHandler(BaseHandler):
    """添加友链。"""

    @permission_required("sys:link:add")
    @check_demo
    @operation_log("友链管理", "添加")
    async def post(self):
        """POST 请求：新增友链。"""
        return await link_service.add(self)


# ======================================================================
# 更新友链
# ======================================================================
class LinkUpdateHandler(BaseHandler):
    """更新友链。"""

    @permission_required("sys:link:update")
    @check_demo
    @operation_log("友链管理", "更新")
    async def put(self):
        """PUT 请求：更新友链信息。"""
        return await link_service.update(self)


# ======================================================================
# 删除友链
# ======================================================================
class LinkDeleteHandler(BaseHandler):
    """删除友链。"""

    @permission_required("sys:link:delete")
    @check_demo
    @operation_log("友链管理", "删除")
    async def delete(self, id):
        """DELETE 请求：按 ID 删除友链（软删除）。"""
        return await link_service.delete(self, id)


# ======================================================================
# 设置友链状态
# ======================================================================
class LinkStatusHandler(BaseHandler):
    """设置友链状态。"""

    @permission_required("sys:link:status")
    @check_demo
    @operation_log("友链管理", "设置状态")
    async def put(self):
        """PUT 请求：修改友链状态。"""
        return await link_service.update_status(self)


# ======================================================================
# 批量删除友链
# ======================================================================
class LinkBatchDeleteHandler(BaseHandler):
    """批量删除友链。"""

    @permission_required("sys:link:delete")
    @check_demo
    @operation_log("友链管理", "批量删除")
    async def post(self):
        """POST 请求：批量删除友链（软删除）。"""
        return await link_service.batch_delete(self)
```

### 6. 路由定义 `src/api/v1/link.py`

```python
# +======================================================================
# | 模块: 友链路由层
# | 说明: 提供友情链接的增删改查、批量删除、状态管理等 API 接口
# +======================================================================
"""友链相关路由。"""

from modules.link.handlers import (
    LinkAddHandler, LinkBatchDeleteHandler, LinkDeleteHandler,
    LinkDetailHandler, LinkPageHandler, LinkStatusHandler,
    LinkUpdateHandler,
)

routes = [
    # 查询友链分页数据
    (r"/link/page", LinkPageHandler),
    # 查询友链详情
    (r"/link/detail/(\d+)", LinkDetailHandler),
    # 添加友链
    (r"/link/add", LinkAddHandler),
    # 更新友链
    (r"/link/update", LinkUpdateHandler),
    # 删除友链
    (r"/link/delete/(\d+)", LinkDeleteHandler),
    # 设置友链状态
    (r"/link/status", LinkStatusHandler),
    # 批量删除友链
    (r"/link/batchDelete", LinkBatchDeleteHandler),
]
```

### 7. 路由注册 `src/api/v1/router.py`

```python
# 在 _RESOURCE_MODULES 列表中追加 link 模块
from api.v1 import link

_RESOURCE_MODULES = [
    # ... 已有模块 ...
    link,
]
```

## 前端文件清单

| 文件 | 说明 |
|:-----|:-----|
| `ui/src/api/system/link.js` | 接口请求封装 |
| `ui/src/views/system/link/index.vue` | 列表页面 |
| `ui/src/views/system/link/edit.vue` | 编辑弹窗 |
| `ui/src/views/system/link/columns.js` | 表格列定义 |
| `ui/src/views/system/link/querySchemas.js` | 查询条件定义 |

## 文件关系图

```
src/modules/link/
├── models.py         ← 数据模型（继承 BaseModel）
├── schemas.py        ← 请求校验（继承 BaseSchema）
├── repository.py     ← 数据访问（继承 BaseRepository）
├── service.py        ← 业务逻辑（继承 BaseService）
└── handlers.py       ← 请求处理器（继承 BaseHandler）

src/api/v1/
├── link.py           ← 路由定义（routes 列表）
└── router.py         ← 路由注册（_RESOURCE_MODULES）
```