Metadata-Version: 2.4
Name: valar
Version: 2.0.10
Summary: valar for morghulis
Home-page: https://gitee.com/vmworkspace/valar_engine.git
Author: LYP
Author-email: liuyinpeng@buaa.edu.cn
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django<6.2,>=5.2.18
Requires-Dist: django-cors-headers<5.0,>=4.9.0
Requires-Dist: channels<5.0,>=4.3.2
Requires-Dist: asgiref<4.0,>=3.9.1
Requires-Dist: PyJWT<3.0,>=2.10.1
Requires-Dist: PyMySQL<2.0,>=1.1.2
Requires-Dist: minio<8.0,>=7.2.2
Requires-Dist: urllib3<3.0,>=2.5.0
Requires-Dist: daphne<5.0,>=4.2.3
Provides-Extra: daphne
Requires-Dist: daphne<5.0,>=4.2.3; extra == "daphne"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Valar

valar for morghulis

Valar 是面向 Morghulis 前端的 Django 后端组件，提供模型与视图元数据、通用数据操作、账户和菜单管理，以及通过 WebSocket
返回结果和进度的后台任务。

## 安装与创建项目

需要 Python 3.10 或更高版本。建议在虚拟环境中安装：

```shell
python -m pip install valar
```

已有 Django 项目可以直接接入。新项目使用 Django 创建：

```shell
python -m django startproject myproject
cd myproject
```

下面以 `myproject` 为项目包名。依赖版本范围见 [requirements.txt](requirements.txt)。

## 项目配置

### 1. settings.py

在现有配置中加入 Valar、Daphne、CORS 和 Channels，保留 Django 默认应用及业务应用。 **Valar 必须排在 Daphne 和
`django.contrib.staticfiles` 前面**，确保 Django 使用 Valar 的 `runserver`。

```python
INSTALLED_APPS = [
    'valar.apps.ValarConfig',
    'daphne',
    'corsheaders',
    'channels',
    # Django 默认应用和业务应用……
]

MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',
    # 原有中间件，包括 SessionMiddleware、CommonMiddleware 等……
    'valar.system.middleware.ValarMiddleware',
]

ASGI_APPLICATION = 'myproject.asgi.application'
VALAR_HANDLER_MAPPING = 'myproject.urls.channel_mapping'

CHANNEL_LAYERS = {
    'default': {
        'BACKEND': 'channels.layers.InMemoryChannelLayer',
    },
}
```

内存 channel layer 用于本地单进程开发。多个服务进程之间传递消息时，需要安装并配置共享的 channel layer 后端。

前后端跨域访问时，按实际前端地址配置允许的来源和请求头：

```python
from corsheaders.defaults import default_headers

CORS_ALLOWED_ORIGINS = ['http://localhost:5173']
CORS_ALLOW_HEADERS = (*default_headers, 'client', 'auth')
```

### 2. urls.py

**系统会自动挂载 `/valar/`，无需手动添加 Valar 路由。** 在项目 URL 配置中保留业务路由：

```python
from django.contrib import admin
from django.urls import path

urlpatterns = [
    # 其他业务路由……
]

channel_mapping = {}
```

自动挂载在 `ValarConfig.ready()` 中执行，目标是 `ROOT_URLCONF` 指向的模块。该模块需要提供列表形式的 `urlpatterns`。使用
`runserver`、`runserver --noreload` 或直接通过 ASGI/WSGI 服务器启动时，都会执行路由挂载。

如果根路由中已经存在路径为 `valar/` 的配置，系统会跳过添加。因此也支持显式配置：

```python
from django.urls import include, path

urlpatterns = [
    path('valar/', include('valar.urls')),
    # 其他业务路由……
]
```

### 3. asgi.py

HTTP 路由由 Valar 自动挂载，WebSocket 路由需要在 ASGI 应用中配置。先初始化 Django，再导入消费者：

```python
import os

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

from django.core.asgi import get_asgi_application

django_application = get_asgi_application()

from channels.routing import ProtocolTypeRouter, URLRouter
from django.urls import re_path
from valar.system.socket.consumer import ValarConsumer

application = ProtocolTypeRouter({
    'http': django_application,
    'websocket': URLRouter([
        re_path(r'(?P<client>\w+)/$', ValarConsumer.as_asgi()),
    ]),
})
```

## 启动服务

日常启动只需执行：

```shell
python manage.py runserver
```

`runserver` 会自动生成并执行 `valar` 应用的迁移。首次接入项目或其他应用有待执行的迁移时，还需要运行 `python manage.py migrate`，以创建或更新 Django 自带应用和业务应用的数据表。

默认服务地址为 `http://127.0.0.1:8000/`，Valar HTTP 接口前缀为 `/valar/`。没有配置首页时，访问 `/` 返回 404。

Valar 的 [runserver](src/valar/management/commands/runserver.py) 继承 Daphne。Django 应用加载完成后，在服务开始监听前执行
Valar 数据库迁移和元数据重建，再启动 HTTP 与 WebSocket 服务。

### 路由挂载与数据初始化

两项启动行为分别执行：

| 行为                   | 执行位置                | runserver | runserver --noreload | 直接启动 ASGI/WSGI |
|------------------------|-------------------------|-----------|----------------------|--------------------|
| 自动挂载 `/valar/`     | `ValarConfig.ready()`   | 执行      | 执行                 | 执行               |
| Valar 迁移和元数据重建 | `runserver.inner_run()` | 执行      | 执行                 | 不执行             |

默认 `runserver` 开启自动重载，监控进程和服务进程都会初始化 Django。路由挂载逻辑会分别运行，但两个进程各自维护独立的
`urlpatterns`，不会在服务进程中添加两份路由。同一进程再次执行时，也会检查已有的 `valar/` 路径并跳过。

需要关闭自动重载时使用：

```shell
python manage.py runserver --noreload
```

### 数据迁移与元数据刷新

每次 `runserver` 启动服务进程时，包括代码修改后的自动重载，都会：

1. 为 `valar` 应用生成并执行迁移。
2. 删除并重新生成 Valar 自身实体的元数据。
3. 重建字段工具和字段域配置。

初始化失败会中止服务启动。Valar 自身元数据的持久调整应写入模型或元数据定义，避免在下次启动时被重建覆盖。

业务应用的迁移需要自行生成和执行：

```shell
python manage.py makemigrations your_app
python manage.py migrate
```

WSGI 仅提供 HTTP 服务；使用 WebSocket 时需要按前面的示例配置并运行 ASGI 应用。

## 后台任务与 WebSocket

后台任务通过 HTTP 提交，Handler 在线程中运行，结果和进度通过 WebSocket 返回。

### 定义和注册 Handler

在 `myproject/handlers.py` 中定义接收 `ChannelSender` 的同步函数：

```python
from valar.data.channel.ChannelSender import ChannelSender


def echo(sender: ChannelSender):
    return {'message': sender.data.get('message', '')}
```

在 `myproject/urls.py` 中注册：

```python
from .handlers import echo

channel_mapping = {
    'echo': echo,
}
```

### 提交任务

先建立 WebSocket 连接：

```text
ws://127.0.0.1:8000/browser_001/
```

路径中的 `browser_001` 是客户端标识，应与 HTTP 请求头中的 `Client` 一致。连接建立后，通过登录流程将连接绑定到账户，再提交任务：

```http
POST /valar/channel/echo/request_001
Content-Type: application/json
Client: browser_001
Auth: 1
Authorization: Bearer <登录获得的 JWT>

{"data": {"message": "hello"}}
```

`request_001` 是用于关联任务回调的标识。HTTP 响应表示任务已提交，业务结果通过 WebSocket 返回，例如：

```json
{
  "__tag__": "channel",
  "handler": "echo",
  "token": "request_001",
  "callback": "onResponse",
  "data": {
    "message": "hello"
  }
}
```

回调类型如下：

| 回调         | 含义                       |
|--------------|----------------------------|
| `onStart`    | 任务开始                   |
| `onProceed`  | 进度更新                   |
| `onResponse` | 任务执行成功，返回结果     |
| `onError`    | 任务执行失败，返回错误信息 |
| `onStop`     | 任务结束                   |

Handler 中调用 `sender.tick(index, length)` 设置进度，再调用 `sender.process()` 发送进度消息。

存在账户 ID 时，消息按账户发送。服务端可以通过 `ValarSender().register(account_id, client)` 绑定连接；客户端发送任意
WebSocket JSON 不会自动完成绑定。相关实现见 [ChannelSender](src/valar/data/channel/ChannelSender.py)
和 [ValarSender](src/valar/system/socket/sender.py)。

## 数据与元数据接口

以下路径均以 `/valar/` 为前缀，不带尾部斜杠。`<entity>` 使用 `应用标签.模型名`，例如 `valar.Account`。

| 路径                                                   | 功能                   |
|--------------------------------------------------------|------------------------|
| `<entity>/insert_one`、`<entity>/save_one`             | 创建或保存单条数据     |
| `<entity>/fetch`、`<entity>/find_one`、`<entity>/find` | 按 ID 或条件读取数据   |
| `<entity>/values`、`<entity>/search/<code>`            | 指定字段查询或分页查询 |
| `<entity>/delete_one`、`<entity>/sync_delete_many`     | 单条或批量删除         |
| `<entity>/sync_save_many`、`<entity>/sync_update_many` | 批量保存或更新         |
| `<entity>/save_file`、`<entity>/remove_file`           | 上传或移除文件         |
| `metas`、`<entity>/<code>/meta_view`                   | 模型和视图元数据       |
| `sign`、`register`、`load_user`                        | 登录、注册与用户信息   |
| `load_menu`、`view_menu`                               | 菜单读取               |
| `channel/<handler_name>/<token>`                       | 提交后台任务           |
| `channel/batch/<entity>/<token>`                       | 提交批量数据任务       |

JSON 接口通常使用以下响应结构，`payload` 为业务返回值：

```json
{
  "payload": true,
  "message": null,
  "code": "info"
}
```

各接口的请求体和认证行为不同，完整定义见 [数据接口](src/valar/data/urls.py)、[元数据接口](src/valar/meta/urls.py)
和 [账户接口](src/valar/auth/urls.py)。业务权限控制需结合具体接口实现。

## 扩展业务用户模型

业务模型可以继承 Valar 的抽象用户模型，关联 Valar 账户：

```python
from django.db import models
from valar.models.auth import AbstractUser


class User(AbstractUser):
    description = models.TextField(null=True, verbose_name='备注')

    class Meta:
        verbose_name = '用户'
```

该类继承 Valar 基础字段及账户关联。添加模型后，按常规 Django 流程为业务应用生成并执行迁移。

## 可选配置

| 功能           | 配置方式                                                                                        |
|----------------|-------------------------------------------------------------------------------------------------|
| MySQL          | 在项目包的 `__init__.py` 中调用 `pymysql.install_as_MySQLdb()`，并配置 `DATABASES`              |
| MinIO 文件存储 | 配置 `BASE_APP` 和 `VALAR_MINIO_URL`，后者格式为 `s3://<access_key>:<secret_key>@<host>:<port>` |
| 邮件           | 配置 Django 邮件后端及 `EMAIL_HOST_USER` 等 SMTP 参数                                           |

## 本仓库开发

| 目录            | 内容                      |
|-----------------|---------------------------|
| `src/valar/`    | Valar 组件源码            |
| `valar_engine/` | Django 示例项目及撮合服务 |
| `ems/`          | 示例业务应用              |
| `tests/`        | 自动化测试                |

仓库示例项目使用 `src.valar.apps.ValarConfig` 从源码加载组件；安装包接入使用 `valar.apps.ValarConfig`。

在仓库根目录安装依赖并启动：

```shell
python -m pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
```

验证开发服务器启动及 WebSocket 消息收发：

```shell
python -m unittest tests.test_websocket_startup -v
```

撮合服务的架构和使用方式见 [MATCHING_ENGINE.md](MATCHING_ENGINE.md)。
