# Jingrow AI开发文档

## 项目概述

Jingrow是一个全栈低代码Web框架，核心理念是"一切皆Page"。

**技术栈**:
- 后端: Python 3.10+ / MariaDB / Redis / Werkzeug / jingrow ORM
- 旧版前端: jQuery / Bootstrap 4 / Vue 3内嵌
- 新版前端: Vue 3 / Naive UI / Pinia / Vue Router / Vite / TypeScript

## 目录结构

```
jingrow/
├── jingrow/              # 后端核心
│   ├── __init__.py       # 框架入口,全局对象(db/user/session/flags)
│   ├── hooks.py          # 应用钩子配置
│   ├── app.py            # WSGI入口
│   ├── handler.py        # 请求处理器
│   ├── model/            # ORM层
│   │   ├── page.py       # Page基类(核心)
│   │   ├── base_page.py  # BasePage
│   │   ├── meta.py       # PageType元数据
│   │   └── db_query.py   # 数据库查询
│   ├── core/pagetype/    # 系统PageType(User/File/Role等)
│   ├── api/              # REST API
│   │   ├── v1.py         # v1(旧版兼容)
│   │   └── v2.py         # v2(RESTful,推荐)
│   ├── ai/               # AI模块
│   │   ├── pagetype/     # AI Agent/AI Node
│   │   └── nodes/        # 节点实现
│   ├── desk/             # 桌面应用
│   ├── workflow/         # 工作流引擎
│   └── public/           # 静态资源(含前端构建产物)
├── frontend/             # 新版独立前端
│   ├── src/
│   │   ├── app/          # 应用入口层
│   │   │   ├── main.ts   # 应用初始化和启动
│   │   │   ├── router/   # 路由配置
│   │   │   │   ├── index.ts      # 主路由配置
│   │   │   │   ├── detailPage.ts # 详情页路由
│   │   │   │   └── listPage.ts   # 列表页路由
│   │   │   └── layouts/  # 页面布局组件
│   │   │       ├── AppHeader.vue     # 应用头部
│   │   │       ├── AppLayout.vue     # 应用布局
│   │   │       ├── AppSidebar.vue    # 应用侧边栏
│   │   │       └── BackToTop.vue     # 返回顶部
│   │   ├── assets/       # 静态资源
│   │   ├── core/         # 核心基础设施层
│   │   │   ├── components/   # 核心组件
│   │   │   ├── features/     # 核心功能模块
│   │   │   ├── pagetype/     # PageType默认视图
│   │   │   └── registry/     # 覆盖机制注册中心
│   │   ├── shared/       # 共享模块
│   │   │   ├── api/      # API封装
│   │   │   │   ├── common.ts     # 通用CRUD操作
│   │   │   │   ├── auth.ts       # 认证API
│   │   │   │   ├── system.ts     # 系统API
│   │   │   │   ├── workspace.ts  # 工作区API
│   │   │   │   ├── agents.ts     # AI代理API
│   │   │   │   ├── nodes.ts      # AI节点API
│   │   │   │   ├── embedding.ts  # 嵌入API
│   │   │   │   ├── localJobs.ts  # 本地任务API
│   │   │   │   ├── scheduledJobs.ts # 定时任务API
│   │   │   │   └── translations.ts  # 翻译API
│   │   │   ├── stores/   # Pinia状态管理
│   │   │   ├── composables/ # Vue组合式函数
│   │   │   ├── components/  # 共享UI组件
│   │   │   ├── utils/    # 工具函数
│   │   │   ├── types/    # TypeScript类型定义
│   │   │   ├── extensions/ # 扩展机制
│   │   │   ├── i18n/     # 国际化
│   │   │   └── index.ts  # 共享模块入口
│   │   ├── views/        # 页面视图层
│   │   │   ├── auth/     # 认证相关页面
│   │   │   │   ├── Login.vue
│   │   │   │   ├── Signup.vue
│   │   │   │   └── SetupWizard.vue
│   │   │   ├── pagetype/ # PageType专用视图
│   │   │   ├── workspace/    # 工作区页面
│   │   │   ├── flows/        # 流程编辑器
│   │   │   ├── tools/        # 工具页面
│   │   │   ├── permissions/  # 权限管理
│   │   │   ├── localJobs/    # 本地任务
│   │   │   ├── scheduledJobs/ # 定时任务
│   │   │   ├── dev/          # 开发工具
│   │   │   ├── Dashboard.vue # 仪表盘
│   │   │   ├── SearchResults.vue # 搜索结果
│   │   │   └── Tools.vue     # 工具列表
│   │   └── locales/      # 本地化文件（已弃用，当前使用后端的zh.po保存中文翻译）
│   ├── package.json      # 依赖配置
│   ├── vite.config.ts    # 构建配置
│   ├── tsconfig.json     # TypeScript配置
│   └── index.html        # HTML模板
└── ai-pgs/              # 本文档
```

## 核心概念

### PageType (页面类型)
- 定义数据库表结构和行为
- JSON定义: `{module}/pagetype/{name}/{name}.json`
- 控制器: `{module}/pagetype/{name}/{name}.py`
- 数据库表名: `tab{PageType}`

### Page (页面/文档)
- PageType的实例,对应数据库记录
- 基类: `jingrow.model.page.Page`
- 获取: `jingrow.get_pg(pagetype, name)`
- 创建: `jingrow.new_pg(pagetype, **kwargs).insert()`

### 全局对象 (jingrow模块)
```python
jingrow.db      # 数据库连接
jingrow.user    # 当前用户名(字符串)
jingrow.session # 会话数据
jingrow.form_dict # 请求参数
jingrow.flags   # 运行时标志
jingrow.cache   # Redis缓存
```

## 文档索引

| 文档 | 说明 |
|------|------|
| [架构设计](guides/architecture.md) | 系统架构/数据流/目录结构 |
| [PageType详解](guides/pagetype.md) | PageType定义/字段类型/控制器 |
| [后端API](backend/api.md) | REST API/RPC/Python API |
| [前端API](frontend/api.md) | API封装/状态管理/组件 |
| [开发规范](guides/best-practices.md) | 代码规范/常见模式/调试 |
