# AIGEO AI内容生成平台 - 开发与接口文档

## 1. 项目概述

AIGEO AI内容生成平台是一个基于人工智能技术的内容生成系统，主要功能包括关键词扩展、话题发现、AI文章生成、落地页生成、网站构建等。系统采用多租户架构，支持企业级用户管理。

## 2. 技术架构

### 2.1 后端技术栈
- Java 17
- Spring Boot 3.x
- Spring Security
- Spring Data JPA
- MySQL 8.0
- Redis
- JWT认证
- Knife4j (Swagger文档)

### 2.2 前端技术栈
- Vue.js (根据vue.md文件推断)
- Element UI

### 2.3 第三方服务
- Dify AI API
- SearchAPI (百度、Google等搜索引擎API)

## 3. 核心模块

### 3.1 认证与授权模块

#### 3.1.1 接口列表

##### 用户登录
- **URL**: `POST /api/auth/login`
- **描述**: 用户使用用户名/邮箱和密码进行登录认证
- **请求参数**:
```json
{
  "username": "string", // 用户名或邮箱
  "password": "string"  // 密码
}
```

- **响应**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "string",       // JWT访问令牌
    "expiresIn": 0,          // 过期时间(秒)
    "user": {                // 用户信息
      "id": 0,
      "companyId": 0,
      "username": "string",
      "email": "string",
      "fullName": "string",
      "role": "string",
      "isActive": true
    }
  }
}
```


##### 用户注册
- **URL**: `POST /api/auth/register`
- **描述**: 新用户注册，可同时创建新公司
- **请求参数**:
```json
{
  "companyId": 0,         // 所属公司ID(可选)
  "companyName": "string",// 公司名称(创建新公司时使用)
  "username": "string",   // 用户名
  "email": "string",      // 邮箱
  "password": "string",   // 密码
  "confirmPassword": "string", // 确认密码
  "fullName": "string"    // 用户全名(可选)
}
```

- **响应**:
```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "token": "string",       // JWT访问令牌
    "expiresIn": 0,          // 过期时间(秒)
    "user": {                // 用户信息
      "id": 0,
      "companyId": 0,
      "username": "string",
      "email": "string",
      "fullName": "string",
      "role": "string",
      "isActive": true
    }
  }
}
```


### 3.2 公司管理模块

#### 3.2.1 接口列表

##### 创建公司
- **URL**: `POST /api/companies`
- **描述**: 创建新公司
- **请求参数**:
```json
{
  "name": "string",           // 公司名称
  "domain": "string",         // 公司域名(可选)
  "billingEmail": "string",   // 账单邮箱(可选)
  "contactPhone": "string",   // 联系电话(可选)
  "address": "string"         // 公司地址(可选)
}
```

- **响应**:
```json
{
  "code": 200,
  "message": "公司创建成功",
  "data": {
    "id": 0,
    "name": "string",
    "domain": "string",
    "status": "TRIAL",        // 公司状态(TRIAL/SUSPENDED/ACTIVE)
    "trialExpiryDate": "2023-01-01T00:00:00",
    "billingEmail": "string",
    "contactPhone": "string",
    "address": "string",
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取公司详情
- **URL**: `GET /api/companies/{id}`
- **描述**: 根据ID获取公司详情
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 0,
    "name": "string",
    "domain": "string",
    "status": "TRIAL",
    "trialExpiryDate": "2023-01-01T00:00:00",
    "billingEmail": "string",
    "contactPhone": "string",
    "address": "string",
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取公司列表
- **URL**: `GET /api/companies`
- **描述**: 获取所有公司列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "name": "string",
      "domain": "string",
      "status": "TRIAL",
      "trialExpiryDate": "2023-01-01T00:00:00",
      "billingEmail": "string",
      "contactPhone": "string",
      "address": "string",
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


### 3.3 用户管理模块

#### 3.3.1 接口列表

##### 创建用户
- **URL**: `POST /api/users`
- **描述**: 创建新用户
- **请求参数**:
```json
{
  "companyId": 0,         // 所属公司ID
  "username": "string",   // 用户名
  "email": "string",      // 邮箱
  "fullName": "string",   // 用户全名(可选)
  "phone": "string",      // 电话(可选)
  "role": "string",       // 角色(可选)
  "isActive": true        // 是否启用(可选)
}
```

- **响应**:
```json
{
  "code": 200,
  "message": "用户创建成功",
  "data": {
    "id": 0,
    "companyId": 0,
    "username": "string",
    "email": "string",
    "fullName": "string",
    "phone": "string",
    "role": "string",
    "isActive": true,
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取用户详情
- **URL**: `GET /api/users/{id}`
- **描述**: 根据ID获取用户详情
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 0,
    "companyId": 0,
    "username": "string",
    "email": "string",
    "fullName": "string",
    "phone": "string",
    "role": "string",
    "isActive": true,
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取用户列表
- **URL**: `GET /api/users`
- **描述**: 获取所有用户列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "companyId": 0,
      "username": "string",
      "email": "string",
      "fullName": "string",
      "phone": "string",
      "role": "string",
      "isActive": true,
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


##### 根据公司ID获取用户列表
- **URL**: `GET /api/users/company/{companyId}`
- **描述**: 根据公司ID获取用户列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "companyId": 0,
      "username": "string",
      "email": "string",
      "fullName": "string",
      "phone": "string",
      "role": "string",
      "isActive": true,
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


### 3.4 关键词管理模块

#### 3.4.1 接口列表

##### 创建关键词
- **URL**: `POST /api/keywords`
- **描述**: 创建新关键词
- **请求参数**:
```json
{
  "companyId": 0,         // 所属公司ID
  "keyword": "string",    // 关键词
  "language": "string",   // 语言(可选)
  "category": "string",   // 分类(可选)
  "usageCount": 0         // 使用次数(可选)
}
```

- **响应**:
```json
{
  "code": 200,
  "message": "关键词创建成功",
  "data": {
    "id": 0,
    "companyId": 0,
    "keyword": "string",
    "language": "string",
    "category": "string",
    "usageCount": 0,
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取关键词详情
- **URL**: `GET /api/keywords/{id}`
- **描述**: 根据ID获取关键词详情
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 0,
    "companyId": 0,
    "keyword": "string",
    "language": "string",
    "category": "string",
    "usageCount": 0,
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取关键词列表
- **URL**: `GET /api/keywords`
- **描述**: 获取所有关键词列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "companyId": 0,
      "keyword": "string",
      "language": "string",
      "category": "string",
      "usageCount": 0,
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


##### 根据公司ID获取关键词列表
- **URL**: `GET /api/keywords/company/{companyId}`
- **描述**: 根据公司ID获取关键词列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "companyId": 0,
      "keyword": "string",
      "language": "string",
      "category": "string",
      "usageCount": 0,
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


### 3.5 话题管理模块

#### 3.5.1 接口列表

##### 创建话题
- **URL**: `POST /api/topics`
- **描述**: 创建新话题
- **请求参数**:
```json
{
  "companyId": 0,         // 所属公司ID
  "name": "string",       // 话题名称
  "description": "string" // 话题描述(可选)
}
```

- **响应**:
```json
{
  "code": 200,
  "message": "话题创建成功",
  "data": {
    "id": 0,
    "companyId": 0,
    "name": "string",
    "description": "string",
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取话题详情
- **URL**: `GET /api/topics/{id}`
- **描述**: 根据ID获取话题详情
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 0,
    "companyId": 0,
    "name": "string",
    "description": "string",
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取话题列表
- **URL**: `GET /api/topics`
- **描述**: 获取所有话题列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "companyId": 0,
      "name": "string",
      "description": "string",
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


##### 根据公司ID获取话题列表
- **URL**: `GET /api/topics/company/{companyId}`
- **描述**: 根据公司ID获取话题列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "companyId": 0,
      "name": "string",
      "description": "string",
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


### 3.6 AI配置管理模块

#### 3.6.1 接口列表

##### 创建AI配置
- **URL**: `POST /api/ai-configs`
- **描述**: 创建新的AI配置
- **请求参数**:
```json
{
  "companyId": 0,         // 所属公司ID
  "provider": "string",   // AI提供商(DIFY/OPENAI等)
  "name": "string",       // 配置名称
  "baseUrl": "string",    // 基础URL
  "apiKey": "string",     // API密钥
  "modelName": "string",  // 模型名称
  "temperature": 0.7,     // 温度参数(可选)
  "maxTokens": 2048,      // 最大令牌数(可选)
  "isActive": true        // 是否启用(可选)
}
```

- **响应**:
```json
{
  "code": 200,
  "message": "AI配置创建成功",
  "data": {
    "id": 0,
    "companyId": 0,
    "provider": "string",
    "name": "string",
    "baseUrl": "string",
    "apiKey": "string",
    "modelName": "string",
    "temperature": 0.7,
    "maxTokens": 2048,
    "isActive": true,
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取AI配置详情
- **URL**: `GET /api/ai-configs/{id}`
- **描述**: 根据ID获取AI配置详情
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 0,
    "companyId": 0,
    "provider": "string",
    "name": "string",
    "baseUrl": "string",
    "apiKey": "string",
    "modelName": "string",
    "temperature": 0.7,
    "maxTokens": 2048,
    "isActive": true,
    "createdAt": "2023-01-01T00:00:00",
    "updatedAt": "2023-01-01T00:00:00"
  }
}
```


##### 获取AI配置列表
- **URL**: `GET /api/ai-configs`
- **描述**: 获取所有AI配置列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "companyId": 0,
      "provider": "string",
      "name": "string",
      "baseUrl": "string",
      "apiKey": "string",
      "modelName": "string",
      "temperature": 0.7,
      "maxTokens": 2048,
      "isActive": true,
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


##### 根据公司ID获取AI配置列表
- **URL**: `GET /api/ai-configs/company/{companyId}`
- **描述**: 根据公司ID获取AI配置列表
- **响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 0,
      "companyId": 0,
      "provider": "string",
      "name": "string",
      "baseUrl": "string",
      "apiKey": "string",
      "modelName": "string",
      "temperature": 0.7,
      "maxTokens": 2048,
      "isActive": true,
      "createdAt": "2023-01-01T00:00:00",
      "updatedAt": "2023-01-01T00:00:00"
    }
  ]
}
```


## 4. 安全配置

### 4.1 认证机制
系统使用JWT Token进行用户身份验证:
1. 用户通过`/api/auth/login`接口登录
2. 系统验证用户凭据后生成JWT Token
3. 客户端在后续请求中通过Authorization Header传递Token
4. 服务端通过JWT Filter验证Token有效性

### 4.2 权限控制
系统基于角色的访问控制(RBAC):
- ADMIN: 系统管理员，拥有所有权限
- EDITOR: 编辑者，可创建和管理内容
- VIEWER: 查看者，只能查看内容

### 4.3 安全接口
以下接口无需认证即可访问:
- `/api/auth/login` - 用户登录
- `/api/auth/register` - 用户注册
- `/api/companies` - 公司相关接口
- `/doc.html` - API文档
- `/webjars/**` - 静态资源
- `/v3/api-docs/**` - API文档接口

## 5. 数据库设计

### 5.1 核心表结构

#### 公司表(ai_companies)
```sql
CREATE TABLE `ai_companies` (
  [id](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\ai\entity\Feature.java#L15-L17) INT NOT NULL AUTO_INCREMENT COMMENT '公司主键ID',
  [name](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\ai\entity\Feature.java#L22-L23) VARCHAR(255) NOT NULL COMMENT '公司名称',
  [domain](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\CompanyDTO.java#L21-L22) VARCHAR(100) DEFAULT NULL COMMENT '公司域名，用于多租户访问',
  [status](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\CompanyDTO.java#L24-L25) ENUM('active','suspended','trial') DEFAULT 'trial' COMMENT '公司状态',
  `trial_expiry_date` DATE DEFAULT NULL COMMENT '试用到期日',
  `default_settings` JSON DEFAULT NULL COMMENT '企业默认设置（JSON）',
  `billing_email` VARCHAR(100) DEFAULT NULL COMMENT '账单邮箱',
  `contact_phone` VARCHAR(20) DEFAULT NULL COMMENT '联系电话',
  [address](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\CompanyDTO.java#L39-L40) TEXT DEFAULT NULL COMMENT '公司地址',
  `logo_url` VARCHAR(255) DEFAULT NULL COMMENT '公司Logo URL',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '最后更新时间',
  PRIMARY KEY ([id](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\CompanyDTO.java#L15-L16)),
  UNIQUE KEY `uk_companies_domain` ([domain](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\CompanyDTO.java#L21-L22))
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='公司表（多租户根）';
```


#### 用户表(ai_users)
```sql
CREATE TABLE `ai_users` (
  [id](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\CompanyDTO.java#L15-L16) INT NOT NULL AUTO_INCREMENT COMMENT '用户主键ID',
  `company_id` INT NOT NULL COMMENT '关联公司ID',
  [username](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L21-L22) VARCHAR(50) NOT NULL COMMENT '用户名',
  [email](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L24-L25) VARCHAR(100) NOT NULL COMMENT '邮箱',
  `password_hash` VARCHAR(255) NOT NULL COMMENT '密码哈希',
  `full_name` VARCHAR(100) DEFAULT NULL COMMENT '用户全名',
  `avatar_url` VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
  [phone](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L33-L34) VARCHAR(20) DEFAULT NULL COMMENT '电话',
  [role](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L36-L37) ENUM('admin','editor','viewer') DEFAULT 'editor' COMMENT '用户角色',
  `is_active` TINYINT(1) DEFAULT 1 COMMENT '是否启用',
  `last_login` TIMESTAMP NULL DEFAULT NULL COMMENT '最后登录时间',
  `last_password_change` TIMESTAMP NULL DEFAULT NULL COMMENT '最后密码修改时间',
  `failed_login_attempts` INT DEFAULT 0 COMMENT '登录失败次数',
  `locked_until` TIMESTAMP NULL DEFAULT NULL COMMENT '锁定截止时间',
  [timezone](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L54-L55) VARCHAR(50) DEFAULT 'Asia/Shanghai' COMMENT '时区',
  [preferences](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L57-L58) JSON DEFAULT NULL COMMENT '用户个性化设置（JSON）',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY ([id](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L15-L16)),
  UNIQUE KEY `uk_users_username` ([username](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L21-L22)),
  UNIQUE KEY `uk_users_email` ([email](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L24-L25)),
  KEY `idx_users_company_id` (`company_id`),
  CONSTRAINT `fk_users_company` FOREIGN KEY (`company_id`) REFERENCES `ai_companies` ([id](file://F:\AIGEO\aigeo\aigeo\src\main\java\com\aigeo\company\dto\UserDTO.java#L15-L16))
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='用户表';
```


## 6. 部署说明

### 6.1 环境要求
- Java 17+
- MySQL 8.0+
- Redis
- Maven 3.8+

### 6.2 配置文件
主要配置文件为`src/main/resources/application.yml`，包含:
- 服务器端口配置
- 数据库连接配置
- Redis配置
- JWT密钥配置
- 日志配置

### 6.3 构建与运行
```bash
# 构建项目
mvn clean package

# 运行项目
java -jar target/aigeo-1.0.0.jar
```


### 6.4 访问地址
- API接口: http://localhost:8080/api/
- API文档: http://localhost:8080/api/doc.html

## 7. 开发规范

### 7.1 代码结构
```
src/main/java/com/aigeo
├── AigeoApplication.java      # 应用启动类
├── ai/                        # AI配置模块
│   ├── controller/
│   ├── dto/
│   ├── entity/
│   ├── repository/
│   └── service/
├── article/                   # AI文章生成模块
│   ├── controller/
│   ├── dto/
│   ├── entity/
│   ├── repository/
│   └── service/
├── auth/                      # 认证模块
│   └── dto/
├── common/                    # 公共组件
│   ├── enums/                 # 枚举类
│   ├── exception/             # 异常处理
│   └── config/                # 配置类
├── company/                   # 公司与用户模块
│   ├── controller/
│   ├── dto/
│   ├── entity/
│   ├── repository/
│   └── service/
├── config/                    # 配置类
├── controller/                # 控制器层（旧结构，待迁移）
├── entity/                    # 实体类（旧结构，待迁移）
├── exception/                 # 异常处理
├── landingpage/               # 落地页生成模块
│   ├── controller/
│   ├── dto/
│   ├── entity/
│   ├── repository/
│   └── service/
├── repository/                # 数据访问层（旧结构，待迁移）
├── service/                   # 业务逻辑层（旧结构，待迁移）
├── util/                      # 工具类
└── website/                   # 网站构建模块（待实现）
```


### 7.2 编码规范
- 使用Lombok简化实体类代码
- 遵循RESTful API设计规范
- 使用JPA注解进行ORM映射
- 采用分层架构设计（Controller-Service-Repository）
- 统一异常处理和响应格式

## 8. 常见问题与解决方案

### 8.1 403 Forbidden错误
问题原因：请求路径不正确或缺少认证信息
解决方案：
1. 确认URL路径正确，应为`http://localhost:8080/api/[endpoint]`
2. 对于需要认证的接口，确保在请求头中添加`Authorization: Bearer [token]`

### 8.2 Content-Type错误
问题原因：请求的Content-Type不正确
解决方案：
1. 确保POST请求设置正确的Content-Type: application/json
2. 确保请求体为有效的JSON格式

### 8.3 数据库连接问题
问题原因：数据库配置不正确
解决方案：
1. 检查application.yml中的数据库连接配置
2. 确认MySQL服务正常运行
3. 确认数据库用户具有相应的权限

以上是AIGEO AI内容生成平台的详细开发文档和接口说明。如需更详细的信息，请参考具体的代码实现和数据库表结构。