we0-cms-pgsql-api/README.md

A CMS API package for Next.js applications with dynamic table management

# we0-cms-api

A powerful CMS API package for Next.js applications with dynamic table management and PostgreSQL support.

## Features

- 🚀 Dynamic table creation and management
- 📊 RESTful API for models and data operations
- 🔧 TypeScript support with full type definitions
- 💾 PostgreSQL database with Sequelize ORM
- 🎯 Easy integration with Next.js API routes
- 📝 Comprehensive CRUD operations

## Installation

```bash
npm install we0-cms-api
# or
yarn add we0-cms-api
# or
pnpm add we0-cms-api
```

### Peer Dependencies

Make sure you have the following peer dependencies installed:

```bash
npm install next sequelize pg pg-hstore
```

## Quick Start

### 1. Database Configuration

First, initialize the database connection in your Next.js app:

```typescript
// lib/cms-config.ts
import { DatabaseConfig, initializeDatabase } from "we0-cms-api"

const dbConfig: DatabaseConfig = {
  host: process.env.DB_HOST || "localhost",
  port: parseInt(process.env.DB_PORT || "5432"),
  database: process.env.DB_NAME || "cms_db",
  username: process.env.DB_USER || "postgres",
  password: process.env.DB_PASSWORD || "password",
  logging: process.env.NODE_ENV === "development",
}

// Initialize database connection
initializeDatabase(dbConfig)
```

### 2. Create API Routes

#### Models Management API

Create `app/api/cms/models/route.ts`:

```typescript
import { createModelRoute } from "we0-cms-api"

export const { GET, POST, PUT, DELETE } = createModelRoute()
```

#### Dynamic Data Management API

Create `app/api/cms/data/[tableName]/route.ts`:

```typescript
import { createDynamicDataRoute } from "we0-cms-api"

export const { GET, POST, PUT, DELETE } = createDynamicDataRoute()
```

#### Alternative: One-liner Setup

Use the convenience function to create all routes at once:

```typescript
// app/api/cms/models/route.ts
import { createCmsRoutes } from "we0-cms-api"

const routes = createCmsRoutes()
export const { GET, POST, PUT, DELETE } = routes.models
```

```typescript
// app/api/cms/data/[tableName]/route.ts
import { createCmsRoutes } from "we0-cms-api"

const routes = createCmsRoutes()
export const { GET, POST, PUT, DELETE } = routes.data
```

## API Usage

### Models API

#### GET `/api/cms/models` - Get all models

```bash
curl "http://localhost:3000/api/cms/models?page=1&limit=10&name=user"
```

#### POST `/api/cms/models` - Create a new model

```bash
curl -X POST "http://localhost:3000/api/cms/models" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "用户模型",
    "table_name": "users",
    "json_schema": {
      "fields": [
        {
          "name": "name",
          "type": "string",
          "required": true,
          "maxLength": 100,
          "comment": "用户姓名"
        },
        {
          "name": "email",
          "type": "email",
          "unique": true,
          "required": true,
          "comment": "用户邮箱"
        },
        {
          "name": "age",
          "type": "integer",
          "comment": "年龄"
        }
      ]
    }
  }'
```

#### PUT `/api/cms/models` - Update a model

```bash
curl -X PUT "http://localhost:3000/api/cms/models" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "更新的用户模型"
  }'
```

#### DELETE `/api/cms/models?id=1` - Delete a model

```bash
curl -X DELETE "http://localhost:3000/api/cms/models?id=1"
```

### Data API

#### GET `/api/cms/data/users` - Get table data

```bash
curl "http://localhost:3000/api/cms/data/users?page=1&limit=10&search=john"
```

#### POST `/api/cms/data/users` - Create new data

```bash
curl -X POST "http://localhost:3000/api/cms/data/users" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30
  }'
```

#### PUT `/api/cms/data/users` - Update data

```bash
curl -X PUT "http://localhost:3000/api/cms/data/users" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "John Smith",
    "age": 31
  }'
```

#### DELETE `/api/cms/data/users?id=1` - Delete data

```bash
curl -X DELETE "http://localhost:3000/api/cms/data/users?id=1"
```

## Advanced Usage

### Custom Service Usage

```typescript
import {
  DatabaseConfig,
  getDynamicTableService,
  initializeCmsModel,
  initializeDatabase,
} from "we0-cms-api"

// Initialize database
const dbConfig: DatabaseConfig = {
  /* your config */
}
initializeDatabase(dbConfig)

// Use the dynamic table service directly
const tableService = getDynamicTableService()

// Create a custom table
await tableService.createTable("custom_table", {
  fields: [
    { name: "title", type: "string", required: true },
    { name: "content", type: "text" },
  ],
})

// Use the CMS model directly
const CmsModel = initializeCmsModel()
const models = await CmsModel.findAll()
```

### Type Definitions

```typescript
import type {
  ApiResponse,
  CmsModelAttributes,
  JsonSchema,
  PaginatedResponse,
  SchemaField,
} from "we0-cms-api"

// Define your schema
const userSchema: JsonSchema = {
  fields: [
    {
      name: "username",
      type: "string",
      required: true,
      unique: true,
      maxLength: 50,
    },
    {
      name: "profile",
      type: "json",
    },
  ],
}
```

## Environment Variables

Create a `.env.local` file in your project root:

```env
DB_HOST=localhost
DB_PORT=5432
DB_NAME=cms_db
DB_USER=postgres
DB_PASSWORD=your_password
```

## Field Types

Supported field types for JSON schema:

- `string` - Variable length string
- `text` - Long text
- `integer` - Integer number
- `float` - Floating point number
- `boolean` - True/false value
- `date` - Date only
- `datetime` - Date and time
- `json` - JSON object
- `email` - Email string (validated as string)

## Error Handling

All API responses follow a consistent format:

```typescript
interface ApiResponse<T = any> {
  success: boolean
  message?: string
  data?: T
  error?: string
}
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT

## Support

For support, please open an issue on the GitHub repository or contact the maintainers.