# 系统架构

## 后端架构

### 核心目录
```
jingrow/jingrow/
├── __init__.py        # 框架入口,全局对象
│   # jingrow.db/user/session/form_dict/flags/cache
├── hooks.py           # 应用钩子配置
├── app.py             # WSGI入口
├── handler.py         # 请求处理/路由分发
├── client.py          # 客户端API封装
├── permissions.py     # 权限系统
├── model/             # ORM层
│   ├── page.py        # Page基类(核心)
│   ├── base_page.py   # BasePage
│   ├── meta.py        # PageType元数据
│   ├── naming.py      # 命名规则
│   ├── db_query.py    # 数据库查询
│   └── workflow.py    # 工作流状态
├── core/pagetype/     # 系统PageType
│   ├── user/          # User
│   ├── role/          # Role
│   ├── file/          # File
│   ├── pagetype/      # PageType(元定义)
│   └── ...            # 更多系统PageType
├── api/               # REST API
│   ├── v1.py          # v1(旧版兼容)
│   └── v2.py          # v2(RESTful)
├── ai/                # AI模块
│   ├── pagetype/      # AI Agent/AI Node
│   ├── nodes/         # 节点实现
│   └── utils/         # AI工具
├── desk/              # 桌面应用
│   ├── pagetype/      # Event/ToDo/Notification等
│   ├── form/          # 表单加载逻辑
│   └── search.py      # 搜索功能
├── workflow/          # 工作流引擎
├── automation/        # 自动化任务
├── database/          # 数据库适配层(MariaDB)
└── public/            # 静态资源
    ├── frontend/      # 新版前端构建产物
    └── dist/          # 旧版前端产物
```

### 核心类

**Page (jingrow/model/page.py)**
所有数据文档的基类:
```python
pg = jingrow.get_pg("User", "admin@example.com")  # 获取
pg = jingrow.new_pg("User", email="new@example.com")  # 创建
pg.insert()  # 插入数据库
pg.save()    # 保存修改
pg.delete()  # 删除
```

**Meta (jingrow/model/meta.py)**
PageType元数据类:
```python
meta = jingrow.get_meta("PageType")
meta.fields      # 字段列表
meta.get_field("fieldname")  # 获取字段定义
meta.permissions # 权限定义
```

### 钩子系统 (hooks.py)

**页面事件钩子** (`pg_events`):
```python
pg_events = {
    "*": {  # 所有PageType
        "on_update": ["module.method"],
        "after_insert": ["module.method"],
        "on_cancel": ["module.method"],
        "on_trash": ["module.method"],
    },
    "Specific PageType": {
        "after_insert": "module.specific_handler",
    }
}
```

**调度任务** (`scheduler_events`):
```python
scheduler_events = {
    "cron": {"0/15 * * * *": ["module.method"]},
    "hourly": ["module.hourly_task"],
    "daily": ["module.daily_task"],
}
```

**权限钩子**:
- `permission_query_conditions` - 列表查询条件
- `has_permission` - 单文档权限检查

## 前端架构 (frontend/)

```
frontend/src/
├── app/
│   ├── main.ts        # 入口,Vue初始化
│   ├── router/        # 路由配置
│   │   ├── index.ts   # 路由定义
│   │   ├── listPage.ts   # 列表页动态加载
│   │   └── detailPage.ts # 详情页动态加载
│   └── layouts/       # 布局组件
├── core/              # 核心基础设施层(重要)
│   ├── components/    # 核心组件
│   ├── features/      # 核心功能模块
│   │   ├── flows/         # 流程编辑器
│   │   ├── form_builder/  # 表单构建器
│   │   ├── schema_builder/ # Schema编辑器
│   │   └── workspace_builder/ # 工作区构建器
│   ├── pagetype/      # PageType默认视图
│   │   ├── default.vue        # 默认详情页
│   │   ├── default_list.vue   # 默认列表页
│   │   └── default_single.vue # 单例视图
│   └── registry/      # 覆盖机制注册中心
│       ├── pagetypeOverride.ts # PageType视图覆盖
│       ├── controlOverride.ts  # 控件覆盖
│       └── sidebarOverride.ts  # 侧边栏覆盖
├── views/             # 页面组件
│   ├── auth/          # 登录/注册
│   ├── pagetype/      # PageType专用视图(覆盖core默认视图)
│   │   ├── user/      # User自定义视图
│   │   └── default/   # 默认视图
│   ├── flows/         # 流程编辑器
│   └── workspace/     # 工作区
└── shared/
    ├── api/           # API封装
    │   ├── common.ts  # 通用CRUD
    │   └── auth.ts    # 认证API
    ├── stores/        # Pinia状态
    │   ├── auth.ts    # 认证状态
    │   ├── permissions.ts
    │   └── menu.ts
    ├── utils/         # 工具函数
    └── i18n/          # 国际化
```

### 路由规则
```
/login              - 登录页
/app                - 仪表盘
/app/:entity        - PageType列表
/app/:entity/:id    - PageType详情
/workspace/:name    - 工作区
/flows              - 流程编辑器
```

### 状态管理 (Pinia)
- `useAuthStore` - 认证状态
- `usePermissionStore` - 权限状态
- `useMenuStore` - 菜单状态
- `useToolsStore` - 工具状态

## 数据流

```
前端 → REST API → handler.py → Page Controller → Database

请求路径:
  /api/action/{method}     → RPC调用
  /api/data/{pagetype}     → CRUD操作(v1)
  /api/v2/document/...     → RESTful API(v2)

响应格式:
  { "message": data, "exc_type": null }
```

## 权限模型

```
User → Role → PageType Permission
                  ↓
            read/write/create/delete/submit/cancel

字段级权限: PageField.permlevel (0-9)
用户权限: User Permission (过滤特定记录)
```

## 数据库设计

- 表名: `tab{PageType}` (如 `tabUser`, `tabFile`)
- 主键: `name` 字段
- 必有字段: `name`, `owner`, `creation`, `modified`, `modified_by`
- 子表: `parent`, `parenttype`, `parentfield`, `idx`
