GovAI/PROJECT_ANALYSIS.md

# 政智通 (GovAI) — 项目架构分析报告

> 生成日期：2026-05-23

---

## 一、项目概述

**政智通**（内部代号 Aily）是一个面向政府部门的 AI 智能办公平台，旨在提升行政效能、赋能智慧政务。平台以"AI 应用商店"为核心形态，提供公文写作、政策解读、数据治理、PPT 生成等多种政务 AI 应用，支持多机构（委办局）多租户部署。

---

## 二、技术栈总览

| 层级 | 技术选型 |
|------|----------|
| 后端 API | Go 1.25+、Chi Router、sqlc（类型安全 SQL）、pgx v5 |
| 数据库 | PostgreSQL 17 + pgvector（向量检索） |
| 缓存/队列 | Redis 7 |
| 对象存储 | MinIO（S3 兼容） |
| 前端 | Next.js 16（App Router）、React 19、Tailwind CSS 4、shadcn/ui |
| 状态管理 | Zustand（客户端）、TanStack React Query（服务端状态） |
| AI 引擎 | 通义千问 Qwen（DashScope）/ OpenAI 兼容接口 / Anthropic Claude |
| 向量化 | DashScope text-embedding-v3（1024 维） |
| 知识库 | 自建 RAG（文档分块 + pgvector 检索）+ Dify 可选集成 |
| PPT 微服务 | Python（Flask）、PPT Master 引擎 |
| 容器化 | Docker Compose（开发/生产） |

---

## 三、项目结构

```
GovAI/
├── server/                    # Go 后端服务
│   ├── cmd/server/            # 入口（main.go + router.go）
│   ├── internal/
│   │   ├── config/            # 环境变量配置加载
│   │   ├── handler/           # HTTP 处理器（12 个文件）
│   │   ├── middleware/        # 认证、RBAC、限流、审计
│   │   ├── response/          # 统一响应格式
│   │   ├── service/           # 业务逻辑层
│   │   └── store/             # 数据访问层（sqlc 生成）
│   ├── pkg/
│   │   ├── auth/              # JWT 管理
│   │   ├── chunker/           # 文档分块器
│   │   ├── db/                # 数据库连接池
│   │   ├── dify/              # Dify API 客户端
│   │   ├── embedding/         # 向量化客户端
│   │   └── llm/               # LLM 多提供商抽象
│   └── migrations/            # 14 个迁移 + 多个种子数据文件
│
├── apps/web/                  # Next.js 前端
│   └── src/
│       ├── app/
│       │   ├── (auth)/        # 登录、注册页
│       │   ├── (portal)/      # 用户门户（商店、对话、工作台、创作、知识库）
│       │   └── (admin)/       # 管理后台（仪表盘、分析、审核、用户等）
│       ├── components/
│       │   ├── app-ui/        # 6 种应用交互界面
│       │   ├── chat/          # 对话组件
│       │   ├── editor/        # 编辑器
│       │   ├── layout/        # 布局（Header 等）
│       │   └── ui/            # shadcn/ui 基础组件
│       ├── hooks/             # 自定义 Hooks（SSE 流式等）
│       ├── lib/               # API 客户端、类型定义、工具函数
│       └── stores/            # Zustand 状态（auth）
│
├── ppt-worker/                # Python PPT 生成微服务
│   ├── app.py                 # Flask 入口
│   ├── pipeline.py            # 生成流水线
│   ├── worker.py              # 后台任务处理
│   ├── llm_client.py          # LLM 调用
│   ├── wanx_client.py         # 通义万相（AI 生图）
│   └── db.py                  # 数据库操作
│
└── docker/                    # Docker 编排
    ├── docker-compose.yml     # 开发环境（PG + Redis + MinIO + PPT Worker）
    ├── docker-compose.dify.yml # Dify 服务（可选）
    └── docker-compose.prod.yml # 生产环境
```

---

## 四、核心功能模块

### 4.1 AI 应用商店

- 10 个政务分类：公文写作、政策解读、政务宣传、数据治理、便民服务、信息化工具、组织人事、招商引资、翻译外事、综合应用
- 应用类型：对话型（chatbot）、补全型（completion）、工作流（workflow）、智能体（agent）、公文写作（doc_writer）、研判分析（analysis）、PPT 生成（ppt_generator）
- 应用生命周期：草稿 → 提交审核 → 审批/驳回 → 上架/下架

### 4.2 对话与 AI 推理

- 多 LLM 提供商支持（OpenAI 兼容 / Anthropic），可配置 fallback
- SSE 流式响应（Server-Sent Events）
- 对话历史管理（会话列表、消息记录、重命名、批量删除）
- Token 用量统计与成本估算

### 4.3 知识库（RAG）

- 文档上传（PDF、DOCX、TXT、MD、CSV、XLSX）
- 文档分块（chunker 包）
- 向量化嵌入（DashScope text-embedding-v3）
- pgvector 向量检索
- 支持重新索引和重新嵌入

### 4.4 公文写作

- 模板化公文生成（通知、请示、报告、会议纪要等）
- 字段配置（文本、下拉、多行文本）
- 流式生成输出

### 4.5 研判分析

- 多步骤向导式分析模板
- 支持多种报告类型
- 结构化字段输入 → AI 生成分析报告

### 4.6 PPT 生成

- 输入方式：纯文本、URL、文件上传（PDF/Word）
- 多种风格：通用、咨询、顶级咨询
- 多种格式：16:9、4:3、竖版
- 可选 AI 生图（通义万相）
- 输出原生可编辑 PPTX
- 异步任务模式（创建 → 轮询状态 → 下载）

### 4.7 多租户（机构管理）

- 支持多个政府机构（科技局、公安局、发改局、教育局等）
- 用户归属机构，可切换机构
- 应用和知识库按机构隔离
- 机构级别的数据可见性控制

### 4.8 管理后台

- 数据总览仪表盘
- 使用分析（用量趋势、成本统计）
- 应用管理与审核队列
- 人员管理（角色分配、状态控制）
- 审计日志（操作追踪）
- 模型管理（提供商配置、配额设置）

---

## 五、数据库设计

### 5.1 核心表（14 次迁移）

| 表名 | 用途 |
|------|------|
| `users` | 用户（UUID PK，支持 SSO，多角色） |
| `departments` | 部门（树形结构，path 编码） |
| `user_departments` | 用户-部门多对多关联 |
| `organizations` | 机构/委办局（多租户） |
| `categories` | 应用分类（10 个预置政务分类） |
| `applications` | AI 应用（完整元数据、配置、统计） |
| `app_reviews` | 应用审核流程 |
| `app_favorites` | 用户收藏 |
| `app_ratings` | 用户评分评价 |
| `app_usage_logs` | 使用日志（每次请求） |
| `app_usage_daily` | 日聚合统计 |
| `model_providers` | LLM 提供商配置 |
| `model_quotas` | 模型配额（全局/部门/用户级） |
| `knowledge_bases` | 知识库 |
| `knowledge_documents` | 知识库文档 |
| `audit_logs` | 审计日志 |
| `ppt_tasks` | PPT 生成任务 |
| `doc_templates` | 公文模板 |
| `conversations` | 对话会话 |

### 5.2 设计特点

- 全部使用 UUID 主键
- `updated_at` 自动更新触发器
- 全文搜索索引（`tsvector`）
- 向量索引（pgvector）
- CHECK 约束保证数据完整性
- 合理的索引覆盖（状态、外键、时间）

---

## 六、API 设计

### 6.1 路由结构（RESTful，/api/v1）

```
/api/v1/
├── auth/                    # 认证（登录、注册、刷新、登出、个人信息）
├── organizations            # 机构列表（公开）
├── store/                   # 应用商店（公开读取）
│   ├── categories
│   ├── apps / apps/{slug}
│   ├── featured / rankings / recent
├── apps/{id}/               # 应用使用（需认证）
│   ├── chat                 # SSE 流式对话
│   ├── completion           # 补全
│   ├── generate-doc         # 公文生成
│   ├── generate-analysis    # 研判分析
│   ├── conversations/       # 对话管理
│   ├── feedback / favorite / rating
├── doc-templates/           # 公文模板
├── analysis-templates/      # 分析模板
├── me/                      # 个人中心
├── creator/                 # 创作者工具
│   ├── apps (CRUD)
│   ├── submit-review / withdraw
├── knowledge/               # 知识库管理
│   ├── CRUD + documents + reindex
├── ppt/                     # PPT 生成
│   ├── tasks (创建/上传/列表/状态/下载)
└── admin/                   # 管理后台（需 admin 角色）
    ├── apps / reviews / users
    ├── analytics (overview/usage/cost)
    └── audit-logs
```

### 6.2 统一响应格式

```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

### 6.3 中间件链

1. RequestID → RealIP → Logger → Recoverer → Timeout(15min) → CORS
2. Auth（JWT 验证，注入 user_id/email/role 到 context）
3. RequireRole（RBAC 角色级别检查）
4. RateLimit（Redis 令牌桶，30 req/min）
5. AuditLog（管理操作审计记录）

---

## 七、认证与授权

| 特性 | 实现 |
|------|------|
| 认证方式 | JWT（Bearer Token + Cookie） |
| Token 有效期 | Access 24h / Refresh 7d |
| 角色体系 | user → creator → admin → super_admin（层级递增） |
| 权限控制 | 中间件级 RBAC（RequireRole） |
| SSO 支持 | Password / LDAP / OAuth2（可配置） |
| 机构切换 | 切换后重新签发 Token |
| 限流 | Redis 令牌桶（对话接口 30/min） |

---

## 八、前端架构

### 8.1 路由分组

| 分组 | 路径 | 说明 |
|------|------|------|
| (auth) | /login, /register | 公开认证页 |
| (portal) | /store, /chat, /workspace, /create, /knowledge | 用户门户 |
| (admin) | /dashboard, /analytics, /apps, /reviews, /users, /models, /audit, /security | 管理后台 |

### 8.2 应用交互界面（6 种）

| 组件 | 对应应用类型 |
|------|-------------|
| chatbot-ui | 对话型应用 |
| completion-ui | 补全型应用 |
| workflow-ui | 工作流应用 |
| agent-ui | 智能体应用 |
| doc-writer-ui | 公文写作 |
| analysis-ui | 研判分析 |

### 8.3 关键技术实现

- **SSE 流式渲染**：自定义 `use-sse-stream` Hook，实时展示 AI 生成内容
- **Markdown 渲染**：react-markdown + remark-gfm
- **主题切换**：next-themes（亮/暗模式）
- **命令面板**：cmdk（快捷搜索）
- **响应式布局**：移动端侧边栏折叠，桌面端固定侧栏

---

## 九、部署架构

### 9.1 开发环境

```
Docker Compose:
  ├── PostgreSQL 17 (pgvector) → :5432
  ├── Redis 7 Alpine → :6379
  ├── MinIO → :9000 (API) / :9001 (Console)
  └── PPT Worker (Python) → :8090

本地进程:
  ├── Go API Server → :8080
  └── Next.js Dev Server → :3000
```

### 9.2 生产环境

- `docker-compose.prod.yml` 全容器化部署
- Nginx 反向代理（SSE 需关闭 proxy_buffering）
- 前端 Next.js 独立构建

### 9.3 初始化流程

```bash
make setup  # 启动 Docker → 迁移数据库 → 导入种子数据
make dev-api  # 启动后端
make dev-web  # 启动前端
```

---

## 十、种子数据与预置内容

项目包含丰富的种子数据，覆盖多个政务场景：

| 种子文件 | 内容 |
|----------|------|
| seed.sql | 基础用户、分类、示例应用 |
| seed_ppt.sql | PPT 生成应用配置 |
| seed_keji.sql | 科技局专属应用 |
| seed_gongan_*.sql | 公安局应用、分类、知识库 |
| seed_fagaiju*.sql | 发改局文档和应用 |
| seed_legal*.sql | 法律法规知识库 |
| seed_xinfang*.sql | 信访回复应用 |
| seed_doc_templates.sql | 公文模板 |
| seed_analysis_templates.sql | 研判分析模板 |
| seed_multi_tenant_users.sql | 多机构用户 |

---

## 十一、架构亮点与设计决策

1. **LLM 提供商抽象**：Provider 接口统一 OpenAI/Anthropic，支持热切换和 fallback
2. **自建 RAG 替代 Dify**：从依赖 Dify 逐步迁移到自建知识库（chunker + embedding + pgvector）
3. **多租户隔离**：机构级数据隔离，用户可跨机构切换
4. **应用审核流程**：创作者提交 → 管理员审核 → 上架，保证内容质量
5. **流式优先**：对话、公文生成、分析报告均支持 SSE 流式输出
6. **配额管理**：支持全局/部门/用户三级 Token 配额控制
7. **审计追踪**：管理操作全量记录，含 IP 和 User-Agent

---

## 十二、潜在改进方向

| 方向 | 说明 |
|------|------|
| 测试覆盖 | 当前缺少前端测试和集成测试 |
| API 文档 | 缺少 OpenAPI/Swagger 规范文档 |
| 错误处理 | 部分 handler 错误处理可更细粒度 |
| 缓存策略 | 热门应用列表、分类等可加 Redis 缓存 |
| 消息队列 | PPT 生成等异步任务可引入 MQ 解耦 |
| 监控告警 | 缺少 Prometheus/Grafana 可观测性 |
| CI/CD | 未见自动化流水线配置 |
| 国际化 | 当前仅中文，未来可扩展多语言 |

---

## 十三、默认账号

| 角色 | 邮箱 | 密码 |
|------|------|------|
| 系统管理员 | admin@govai.gov.cn | admin123 |
| 科长 | wangke@govai.gov.cn | admin123 |
| 干事 | liganshi@govai.gov.cn | admin123 |

---

*本文档由代码分析自动生成，如有疑问请参考源代码。*