GovAI/docs/PROJECT-SUMMARY.md

# 政智通（GovAI）— 项目全景总结

> **文档编号**：DOC-MGT-009  
> **版本**：v1.1.0  
> **生成日期**：2026-05-23  
> **最后更新**：2026-05-23  
> **状态**：已发布（Published）

---

## 1. 项目概述

**政智通（GovAI）** 是一个面向政府部门的 AI 智能应用平台，旨在提升行政效能、赋能智慧政务。平台支持多机构多租户，内置知识库 RAG、多种 AI 应用类型（对话 / 补全 / 工作流 / 智能体 / PPT 生成），为不同政务场景提供一站式 AI 解决方案。

### 1.1 核心定位

| 维度 | 说明 |
|------|------|
| **品牌名称** | 政智通（GovAI），由企业版「Aily」演进而来 |
| **目标用户** | 政府各局委办工作人员（科技局、公安局、发改局、律所、信访局等） |
| **核心价值** | 一站式政务 AI 应用商店 + 知识库 + 创作者平台 |
| **部署模式** | 私有化部署，前后端分离 |

### 1.2 功能全景

```
┌─────────────────────────────────────────────────────┐
│                    政智通 平台                        │
├──────────┬──────────┬──────────┬─────────────────────┤
│ 应用商店  │  工作台   │ 创作中心  │   知识库管理         │
│ (Store)  │(Workspace)│ (Create) │  (Knowledge)        │
├──────────┴──────────┴──────────┴─────────────────────┤
│                   管理后台 (Admin)                     │
│  数据总览 │ 应用管理 │ 审核队列 │ 用户管理 │ 审计日志   │
├─────────────────────────────────────────────────────┤
│              AI 引擎层 (LLM / RAG / PPT)              │
│  通义千问 │ 向量嵌入 │ 知识库检索 │ PPT Master          │
└─────────────────────────────────────────────────────┘
```

---

## 2. 技术架构

### 2.1 整体架构

采用 **Go 后端 + Next.js 前端 + Python PPT Worker** 的三层架构：

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Next.js    │────▶│   Go API     │────▶│  PostgreSQL  │
│   前端       │     │   Server     │     │  (pgvector)  │
│   :3000      │     │   :8080      │     │              │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
                     ┌──────┴───────┐     ┌──────────────┐
                     │    Redis     │────▶│  PPT Worker  │
                     │   消息队列    │     │  (Python)    │
                     │              │     │   :8090      │
                     └──────────────┘     └──────────────┘
                                          ┌──────────────┐
                                          │    MinIO     │
                                          │  对象存储     │
                                          └──────────────┘
```

### 2.2 技术栈总览

| 层级 | 技术 | 版本 |
|------|------|------|
| **后端框架** | Go + Chi Router | Go 1.25、Chi v5 |
| **数据库** | PostgreSQL + pgvector | PG 17 |
| **缓存/队列** | Redis | 7.x |
| **ORM/SQL** | sqlc 代码生成 + pgx | pgx v5 |
| **前端框架** | Next.js (App Router) | 16.2.6 |
| **UI 框架** | React + TypeScript | React 19.2.4、TS 5 |
| **CSS 方案** | Tailwind CSS v4 | v4（CSS-first 配置） |
| **组件库** | shadcn/ui (base-nova) | v4.7.0 |
| **状态管理** | Zustand + TanStack React Query | Zustand 5、RQ 5 |
| **AI/LLM** | 通义千问 (DashScope) | OpenAI 兼容接口 |
| **向量嵌入** | text-embedding-v3 | DashScope |
| **PPT 引擎** | PPT Master (Python) | FastAPI + python-pptx |
| **对象存储** | MinIO | — |
| **认证** | JWT + 多机构切换 | golang-jwt v5 |

### 2.3 数据流

```
用户操作 → Next.js 前端
         → /api/* 代理 → Go API Server
                        → PostgreSQL（持久化）
                        → Redis（缓存/PPT队列）
                        → DashScope API（LLM推理）
                        → pgvector（向量检索/RAG）
         → SSE 流式响应 → 前端实时渲染
```

---

## 3. 项目目录结构

```
GovAI/
├── .cursorrules                  # Cursor IDE 工作流规则
├── .env.example                  # 根级环境变量模板
├── README.md                     # 项目主文档
├── run.md                        # 运行说明与测试账号
├── 政务AI平台调整方案.md           # 品牌/分类调整方案
├── Makefile                      # 开发/构建/迁移统一入口
│
├── server/                       # ========== Go 后端 ==========
│   ├── .env                      # 后端环境配置（已配置）
│   ├── go.mod / go.sum           # Go 依赖
│   ├── sqlc.yaml                 # sqlc 代码生成配置
│   ├── cmd/
│   │   ├── server/
│   │   │   ├── main.go           # 服务入口
│   │   │   └── router.go         # 路由定义（API v1）
│   │   └── embed-chunks/
│   │       └── main.go           # 文档分片/向量化 CLI 工具
│   ├── internal/
│   │   ├── config/config.go      # 配置加载
│   │   ├── handler/              # HTTP 处理器（13 个模块）
│   │   ├── middleware/           # 认证/RBAC/限流/审计中间件
│   │   └── response/response.go  # 统一响应格式
│   ├── pkg/
│   │   ├── auth/                 # JWT、密码哈希、SSO
│   │   ├── chunker/              # 文档分片器
│   │   ├── db/                   # 数据库连接 + sqlc 查询
│   │   ├── dify/                 # Dify 集成客户端
│   │   ├── embedding/            # 向量嵌入服务
│   │   └── llm/                  # LLM 提供商（OpenAI/Anthropic）
│   └── migrations/               # 迁移文件 + 种子数据（49 个）
│
├── apps/
│   └── web/                      # ========== Next.js 前端 ==========
│       ├── package.json          # 前端依赖
│       ├── next.config.ts        # Next.js + API 代理配置
│       ├── components.json       # shadcn/ui 配置
│       └── src/
│           ├── app/              # App Router 页面
│           │   ├── error.tsx     #   全局错误边界
│           │   ├── loading.tsx   #   全局加载状态
│           │   ├── not-found.tsx #   404 页面
│           │   ├── (auth)/       #   登录/注册
│           │   ├── (portal)/     #   商店/工作台/知识库/创作/聊天
│           │   │   ├── error.tsx  #    Portal 错误边界
│           │   │   └── loading.tsx#    Portal 加载状态
│           │   └── (admin)/      #   管理后台各页面
│           │       ├── error.tsx  #    Admin 错误边界
│           │       └── loading.tsx#    Admin 加载状态
│           ├── components/
│           │   ├── app-ui/       #   各应用类型 UI 组件
│           │   ├── app-card/     #   应用卡片组件
│           │   ├── layout/       #   Header 布局
│           │   └── ui/           #   shadcn 基础组件（20+）
│           ├── hooks/            # 可复用自定义 Hooks
│           │   ├── use-sse-stream.ts   #   SSE 流式解析
│           │   ├── use-copy-clipboard.ts# 剪贴板复制
│           │   ├── use-scroll-bottom.ts #  自动滚动
│           │   ├── use-file-export.ts  #   文件下载导出
│           │   ├── use-app-config.ts   #   应用配置解析
│           │   └── index.ts            #   统一导出
│           ├── lib/              # API 客户端、类型、工具函数
│           │   └── types.ts      #   统一类型定义（全局）
│           └── stores/auth.ts    # Zustand 认证状态
│
├── ppt-worker/                   # ========== PPT 生成服务 ==========
│   ├── app.py                    # FastAPI HTTP 入口
│   ├── worker.py                 # Redis 队列 Worker
│   ├── pipeline.py               # PPT Master 管线
│   ├── requirements.txt          # Python 依赖
│   └── Dockerfile                # 容器化配置
│
├── docker/                       # ========== Docker 配置 ==========
│   ├── docker-compose.yml        # PG + Redis + MinIO + PPT Worker
│   └── docker-compose.dify.yml   # Dify AI 引擎（可选）
│
└── docs/                         # ========== 项目文档 ==========
    ├── UI-STYLE-GUIDE.md         # UI 风格规范
    ├── APP-TYPE-STANDARD.md      # 应用类型标准
    ├── add-domain-guide.md       # 新增行业领域指南
    └── ...                       # 其他技术文档
```

---

## 4. 前端架构详解

### 4.1 路由结构

| 路由组 | 路径 | 页面 | 守卫 |
|--------|------|------|------|
| `(auth)` | `/login` | 登录页 | 无 |
| `(auth)` | `/register` | 注册页 | 无 |
| `(portal)` | `/store` | 应用商店首页 | 需登录 |
| `(portal)` | `/store/category/[slug]` | 分类应用列表 | 需登录 |
| `(portal)` | `/store/apps/[slug]` | 应用详情页 | 需登录 |
| `(portal)` | `/chat/[appId]` | 应用运行页 | 需登录 |
| `(portal)` | `/workspace` | 工作台（最近+收藏） | 需登录 |
| `(portal)` | `/create` | 创作中心 | 需登录 |
| `(portal)` | `/knowledge` | 知识库管理 | 需登录（creator/admin） |
| `(admin)` | `/dashboard` | 数据总览 | 需 admin |
| `(admin)` | `/apps` | 应用管理 | 需 admin |
| `(admin)` | `/reviews` | 审核队列 | 需 admin |
| `(admin)` | `/users` | 用户管理 | 需 admin |
| `(admin)` | `/analytics` | 使用分析 | 需 admin |
| `(admin)` | `/audit` | 审计日志 | 需 admin |
| `(admin)` | `/models` | 模型管理 | 需 admin |
| `(admin)` | `/security` | 安全管理 | 需 admin |

### 4.2 应用类型与对应 UI 组件

| 应用类型 | UI 组件 | 交互模式 | 核心能力 |
|----------|---------|----------|----------|
| **chatbot（对话型）** | `ChatbotUI` | SSE 流式多轮对话 | 文件上传、对话导出、历史管理 |
| **completion（补全型）** | `CompletionUI` | 单次输入→流式输出 | 格式模板选择、历史侧边栏 |
| **workflow（工作流）** | `WorkflowUI` | 多步骤表单→汇总生成 | 步骤引导、参数校验 |
| **agent（智能体）** | `AgentUI` | SSE 流式+工具调用 | 工具标记解析、执行状态展示 |
| **公文写作** | `DocWriterUI` | 模板→表单→流式生成 | Word/TXT 导出、后续对话修改 |
| **研判分析** | `AnalysisUI` | 模板→向导→流式生成 | Word/MD 导出、追问优化 |

### 4.3 状态管理

```
┌─────────────────────────────────────────┐
│           状态管理架构                    │
├────────────┬────────────┬───────────────┤
│  Zustand   │ React Query│ Component     │
│  全局认证   │ 服务端数据  │ 局部 UI 状态  │
├────────────┼────────────┼───────────────┤
│ • user     │ • 应用列表  │ • 表单数据     │
│ • token    │ • 分类数据  │ • 对话消息     │
│ • org      │ • 统计信息  │ • 流式状态     │
│ • login()  │ • 5min缓存  │ • 侧边栏切换   │
│ • logout() │ • retry=1  │ • 加载状态     │
│ • switchOrg│            │               │
└────────────┴────────────┴───────────────┘
```

### 4.4 自定义 Hooks

| Hook | 文件 | 用途 | 使用组件 |
|------|------|------|----------|
| `useSSEStream` | `use-sse-stream.ts` | SSE 流式响应解析（buffer 管理、事件解析、conversation_id 提取） | chatbot/agent/completion/workflow/doc-writer/analysis |
| `useCopyToClipboard` | `use-copy-clipboard.ts` | 剪贴板复制 + toast 提示 | chatbot/agent/completion/doc-writer/analysis |
| `useScrollToBottom` | `use-scroll-bottom.ts` | 消息列表自动滚动到底部 | chatbot/agent/doc-writer/analysis |
| `useFileExport` | `use-file-export.ts` | 文件下载导出（Blob + URL.createObjectURL） | chatbot/agent/doc-writer/analysis |
| `useAppConfig` | `use-app-config.ts` | 解析 app.app_config JSON 配置 | completion/workflow/agent |
| `useSuggestedPrompts` | `use-app-config.ts` | 解析 app.suggested_prompts | chatbot/agent |

工具函数：
- `updateLastAssistantMessage()` — 更新消息列表中最后一条 AI 消息的内容
- `setStreamErrorMessage()` — 流式失败时设置错误提示消息

### 4.5 错误边界与加载状态

| 文件 | 层级 | 功能 |
|------|------|------|
| `app/error.tsx` | 全局 | 捕获未处理的渲染错误，显示错误标识、重试和返回按钮 |
| `app/loading.tsx` | 全局 | 全屏加载 Spinner |
| `app/not-found.tsx` | 全局 | 404 页面，引导用户返回应用中心 |
| `app/(portal)/error.tsx` | Portal | 应用侧错误边界，保留 Header 导航 |
| `app/(portal)/loading.tsx` | Portal | 应用侧加载状态（适配 Header 高度 3.5rem） |
| `app/(admin)/error.tsx` | Admin | 管理后台错误边界 |
| `app/(admin)/loading.tsx` | Admin | 管理后台加载状态 |

### 4.6 统一类型定义

所有业务类型集中定义在 `lib/types.ts`，按模块分组：

| 分组 | 类型 |
|------|------|
| 核心业务 | `App`、`KnowledgeBase`、`Category`、`PaginatedResponse`、`ChatMessage`、`Conversation`、`Rating` |
| 对话/流式 | `Message`、`DeleteTarget` |
| 智能体 | `ToolCall` |
| 补全型 | `FormatTemplate` |
| 工作流 | `WorkflowStep` |
| 公文写作 | `DocTemplate`、`TemplateField`、`SelectOption` |
| 研判分析 | `AnalysisTemplate`、`TemplateStep`、`StepField`、`FieldOption` |
| 用户/认证 | `User`、`Organization` |
| 管理后台 | `AdminApp`、`Review`、`AuditLog`、`OverviewStats` |

### 4.7 前端依赖

| 类别 | 包名 | 版本 | 用途 |
|------|------|------|------|
| 框架 | `next` | 16.2.6 | SSR/SSG 框架 |
| 视图 | `react` / `react-dom` | 19.2.4 | UI 渲染 |
| 状态 | `zustand` | 5.0.13 | 全局状态管理 |
| 数据 | `@tanstack/react-query` | 5.100.9 | 服务端数据缓存 |
| UI | `shadcn` | 4.7.0 | 组件库 CLI |
| 样式 | `tailwindcss` | v4 | CSS 框架 |
| 样式 | `tailwind-merge` / `clsx` | 3.5.0 / 2.1.1 | 样式合并 |
| 图标 | `lucide-react` | 1.14.0 | 图标库 |
| 主题 | `next-themes` | 0.4.6 | 暗色模式 |
| Markdown | `react-markdown` / `remark-gfm` | 10.1.0 / 4.0.1 | Markdown 渲染 |
| 通知 | `sonner` | 2.0.7 | Toast 提示 |
| 命令面板 | `cmdk` | 1.1.1 | 搜索/命令 |
| 日期 | `date-fns` | 4.1.0 | 日期处理 |
| 动画 | `tw-animate-css` | 1.4.0 | CSS 动画 |

---

## 5. 后端架构详解

### 5.1 API 路由总览（`/api/v1`）

#### 认证模块
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/auth/register` | 用户注册 |
| POST | `/auth/login` | 用户登录 |
| POST | `/auth/refresh` | Token 刷新 |
| POST | `/auth/logout` | 用户登出 |
| GET | `/auth/me` | 获取当前用户 |
| PUT | `/auth/profile` | 更新用户信息 |
| POST | `/auth/switch-org` | 切换机构 |

#### 应用商店
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/store/categories` | 获取分类列表 |
| GET | `/store/apps` | 获取应用列表（分页/搜索） |
| GET | `/store/featured` | 推荐应用 |
| GET | `/store/rankings` | 热门排行 |
| GET | `/store/recent` | 最近使用 |

#### 应用交互
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/apps/{id}/chat` | 对话/智能体（SSE 流式） |
| POST | `/apps/{id}/completion` | 补全（SSE 流式） |
| POST | `/apps/{id}/generate-doc` | 公文生成（SSE 流式） |
| POST | `/apps/{id}/generate-analysis` | 研判报告（SSE 流式） |
| GET | `/apps/{id}/conversations` | 对话历史 |
| POST | `/apps/{id}/feedback` | 用户反馈 |
| POST | `/apps/{id}/favorite` | 收藏/取消 |
| POST | `/apps/{id}/rating` | 评分 |

#### 创作中心
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/creator/apps` | 创作者应用 CRUD |
| POST | `/creator/apps/{id}/submit-review` | 提交审核 |
| GET | `/creator/templates` | 应用模板 |

#### 知识库
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/knowledge` | 知识库 CRUD |
| POST | `/knowledge/{id}/documents` | 上传文档 |
| POST | `/knowledge/{id}/reindex` | 重建索引 |
| POST | `/knowledge/{id}/reembed` | 重建向量 |

#### 管理后台
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/admin/analytics` | 使用分析数据 |
| GET/PUT | `/admin/apps` | 应用上下架管理 |
| GET/PUT | `/admin/reviews` | 审核队列 |
| GET/PUT | `/admin/users` | 用户角色/状态管理 |
| GET | `/admin/audit-logs` | 审计日志 |

### 5.2 后端依赖

| 包 | 版本 | 用途 |
|----|------|------|
| `go-chi/chi` | v5.2.5 | HTTP 路由 |
| `go-chi/cors` | v1.2.2 | 跨域处理 |
| `golang-jwt/jwt` | v5.3.1 | JWT 认证 |
| `jackc/pgx` | v5.9.2 | PostgreSQL 驱动 |
| `redis/go-redis` | v9.19.0 | Redis 客户端 |
| `rs/zerolog` | v1.35.1 | 结构化日志 |
| `google/uuid` | v1.6.0 | UUID 生成 |
| `joho/godotenv` | v1.5.1 | 环境变量加载 |
| `golang.org/x/crypto` | v0.51.0 | 密码哈希 |

### 5.3 Handler 模块（13 个）

```
handler/
├── auth.go           # 认证（登录/注册/切换机构）
├── store.go          # 应用商店（列表/搜索/排行）
├── app_usage.go      # 应用使用（聊天/补全/生成）
├── conversation.go   # 对话历史管理
├── creator.go        # 创作中心
├── knowledge.go      # 知识库管理
├── ppt.go            # PPT 任务管理
├── admin_app.go      # 管理后台-应用
├── admin_review.go   # 管理后台-审核
├── admin_user.go     # 管理后台-用户
├── admin_analytics.go# 管理后台-统计
├── admin_audit.go    # 管理后台-审计
└── template.go       # 模板管理（公文/分析）
```

---

## 6. 数据库设计

### 6.1 迁移版本

| 版本 | 文件 | 内容 |
|------|------|------|
| 000001 | init | 用户表、部门表 |
| 000002 | categories_and_applications | 分类、应用、应用配置 |
| 000003 | reviews_and_favorites | 评价、收藏 |
| 000004 | usage_logs | 使用日志 |
| 000005 | models_quotas_audit | 模型、配额、审计日志 |
| 000006 | ppt_tasks | PPT 任务表 |
| 000007 | doc_templates | 公文模板 |
| 000008 | conversation_naming | 对话命名 |
| 000009 | knowledge_base_id | 知识库 ID 字段 |
| 000010 | document_content | 文档内容存储 |
| 000011 | usage_messages | 使用消息记录 |
| 000012 | organizations | 多机构表 |
| 000013 | multi_tenant | 多租户改造 |
| 000014 | — | 最新迁移 |

### 6.2 种子数据

| 文件 | 内容 |
|------|------|
| `seed.sql` | 基础分类、默认应用 |
| `seed_keji.sql` | 科技局专属数据 |
| `seed_gongan_*.sql` | 公安局应用与知识库 |
| `seed_fagaiju*.sql` | 发改局应用与知识库 |
| `seed_legal*.sql` | 律师事务所（14 个应用+4 个知识库） |
| `seed_xinfang*.sql` | 信访局（10 个应用+4 个知识库） |
| `seed_ppt.sql` | PPT 生成应用 |
| `seed_multi_tenant_users.sql` | 多机构用户账号 |
| `seed_doc_templates.sql` | 公文模板 |
| `seed_analysis_templates.sql` | 分析报告模板 |

---

## 7. PPT 生成服务

### 7.1 架构

```
用户提交 PPT 任务 → Go API → Redis 队列 → Python Worker → PPT Master
                                                          ↓
                                             MinIO 存储 ← 生成 PPTX
```

### 7.2 功能特性

| 特性 | 说明 |
|------|------|
| **输入格式** | PDF、Word、网页 URL、纯文本 |
| **演示风格** | 通用、咨询、顶级咨询 |
| **幻灯片格式** | 16:9 宽屏、4:3 传统、竖版 |
| **AI 生图** | 通义万相（可选） |
| **输出** | 原生可编辑 PPTX 文件 |

### 7.3 技术栈

- **Web 框架**：FastAPI + uvicorn
- **任务队列**：Redis
- **PPT 引擎**：PPT Master（外部项目）
- **PPT 生成**：python-pptx
- **图片生成**：通义万相 (wanx)
- **LLM**：通义千问（内容大纲生成）

---

## 8. 多机构多租户

### 8.1 支持的机构

| 机构 | 角色配置 | 专属应用数 |
|------|----------|-----------|
| 科技局 | super_admin + admin + creator + user | 默认应用集 |
| 公安局 | admin + creator + user | 专属应用 |
| 发改局 | admin + creator + user | 专属应用 |
| 教育局 | admin + user | — |
| 人社局 | admin + creator + user | — |
| 财政局 | admin + user | — |
| 住建局 | admin + creator + user | — |
| 市监局 | admin + creator + user | — |
| 律师事务所 | admin + creator + user | 14 个法律应用 |
| 信访局 | admin + creator + user | 10 个信访应用 |

### 8.2 角色权限模型

| 角色 | 权限 |
|------|------|
| `super_admin` | 全平台管理权限，跨机构管理 |
| `admin` | 机构管理权限（应用审核、用户管理、数据分析） |
| `creator` | 可创建和发布应用 |
| `user` | 使用应用和知识库 |

---

## 9. 应用分类体系

### 9.1 通用分类（10 个）

| 分类 | 说明 | 典型应用 |
|------|------|----------|
| 公文写作 | 公文拟稿、会议纪要、文件摘要 | 公文写作助手、会议纪要生成 |
| 政策解读 | 法规问答、政策影响分析 | 政策法规问答、政策影响分析 |
| 政务宣传 | 宣传稿件、信息发布 | — |
| 数据治理 | 数据分析、综合研判 | 综合研判助手 |
| 便民服务 | 群众来信回复、咨询答复 | 群众来信回复 |
| 信息化工具 | 开发辅助、系统运维 | — |
| 组织人事 | 干部考核、人事管理 | 干部考核助手 |
| 招商引资 | 项目评估、投资分析 | 招商项目评估 |
| 翻译外事 | 中英互译、外事用语 | 翻译助手 |
| 综合应用 | 其他政务场景 | — |

### 9.2 行业专属分类

- **律师事务所**：法律服务（对标 iCourt Alpha）
- **信访局**：信访受理、政策答复、矛盾调解、督查督办

---

## 10. 预置应用清单

### 10.1 通用应用（11 个）

| 应用 | 类型 | 分类 |
|------|------|------|
| 政策法规问答 | 对话型 | 政策解读 |
| 公文写作助手 | 对话型 | 公文写作 |
| 群众来信回复 | 对话型 | 便民服务 |
| 会议纪要生成 | 补全型 | 公文写作 |
| 公文摘要提取 | 补全型 | 公文写作 |
| 翻译助手 | 补全型 | 翻译外事 |
| 招商项目评估 | 工作流 | 招商引资 |
| 政策影响分析 | 工作流 | 政策解读 |
| 综合研判助手 | 智能体 | 数据治理 |
| 干部考核助手 | 智能体 | 组织人事 |
| 智能PPT生成 | PPT生成 | 综合应用 |

### 10.2 律师事务所应用（14 个）

| 应用 | 类型 | 增强等级 |
|------|------|----------|
| 法律法规检索 | 对话型 | P0（类案综述、参照标注） |
| 法律咨询助手 | 对话型 | P0（结构化报告、风险预测） |
| 合同条款审查 | 对话型 | P0（甲乙方立场、法规审查） |
| 法律文书生成 | 补全型 | P0（七大类模板、法条引用） |
| 法律阅卷助手 | 补全型 | P0（快捷阅卷+质证意见） |
| 合同条款生成 | 补全型 | 基础 |
| 案件风险评估 | 工作流 | 基础 |
| 尽职调查报告 | 工作流 | 基础 |
| 诉讼策略助手 | 智能体 | 基础 |
| 合规审查助手 | 智能体 | 基础 |
| 质证意见生成 | 补全型 | P1 新增 |
| 庭审提纲生成 | 补全型 | P1 新增 |
| 裁判趋势分析 | 对话型 | P1 新增 |
| 企业合规体检 | 工作流 | P1 新增 |

### 10.3 信访局应用（10 个）

| 应用 | 类型 | 分类 |
|------|------|------|
| 信访政策咨询 | 对话型 | 信访受理 |
| 来信来访登记 | 补全型 | 信访受理 |
| 信访件分类 | 补全型 | 信访受理 |
| 信访答复生成 | 补全型 | 政策答复 |
| 政策法规检索 | 对话型 | 政策答复 |
| 矛盾纠纷分析 | 工作流 | 矛盾调解 |
| 调解文书生成 | 补全型 | 矛盾调解 |
| 督查报告生成 | 工作流 | 督查督办 |
| 信访风险评估 | 智能体 | 督查督办 |
| 信访数据分析 | 智能体 | 督查督办 |

---

## 11. 知识库体系

### 11.1 知识库 RAG 流程

```
文档上传 → 文档分片(chunker) → 向量嵌入(text-embedding-v3) → pgvector 存储
                                                                   ↓
用户提问 → 查询向量化 → 相似度检索(pgvector) → 上下文注入 → LLM 生成回答
```

### 11.2 已配置知识库

| 机构 | 知识库 | 文档数 |
|------|--------|--------|
| 律师事务所 | 法律法规库 | 6 |
| 律师事务所 | 司法解释库 | 4 |
| 律师事务所 | 合同模板库 | 5 |
| 律师事务所 | 文书模板库 | 4 |
| 信访局 | 信访法规库 | 5 |
| 信访局 | 政策答复模板库 | 4 |
| 信访局 | 调解规程库 | 4 |
| 信访局 | 督查督办制度库 | 3 |

---

## 12. 环境配置

### 12.1 核心环境变量

| 变量 | 说明 | 示例值 |
|------|------|--------|
| `SERVER_HOST` | 后端监听地址 | `0.0.0.0` |
| `SERVER_PORT` | 后端端口 | `8080` |
| `DATABASE_URL` | PostgreSQL 连接串 | `postgres://...` |
| `REDIS_URL` | Redis 连接串 | `redis://localhost:6379` |
| `JWT_SECRET` | JWT 签名密钥 | — |
| `LLM_PROVIDER` | LLM 提供商 | `openai` |
| `OPENAI_API_KEY` | 通义千问 API Key | `sk-...` |
| `OPENAI_BASE_URL` | DashScope 兼容地址 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| `OPENAI_MODEL` | 默认模型 | `qwen-plus` |
| `EMBEDDING_MODEL` | 嵌入模型 | `text-embedding-v3` |
| `NEXT_PUBLIC_API_URL` | 前端 API 代理目标 | `http://localhost:8080` |
| `PPT_WORKER_URL` | PPT 服务地址 | `http://localhost:8090` |

### 12.2 Docker 服务

| 服务 | 镜像 | 端口 |
|------|------|------|
| PostgreSQL | pgvector/pgvector:pg17 | 5432 |
| Redis | redis:7 | 6379 |
| MinIO | minio | 9000/9001 |
| PPT Worker | 自建 | 8090 |

---

## 13. 开发与构建

### 13.1 Makefile 命令

| 命令 | 说明 |
|------|------|
| `make dev-api` | 启动后端开发服务器 |
| `make dev-web` | 启动前端开发服务器 |
| `make dev-ppt` | 启动 PPT Worker |
| `make build` | 构建全部 |
| `make test` | 运行测试 |
| `make lint` | 代码检查 |
| `make migrate` | 运行数据库迁移 |
| `make sqlc` | 生成 sqlc 代码 |
| `make seed` | 导入种子数据 |
| `make docker` | Docker 环境启动 |

### 13.2 快速启动步骤

```bash
# 1. 启动基础设施
docker compose -f docker/docker-compose.yml up -d

# 2. 运行数据库迁移
make migrate

# 3. 导入种子数据
make seed

# 4. 启动后端
cd server && go run cmd/server/main.go

# 5. 启动前端
cd apps/web && npm install && npm run dev

# 6. (可选) 启动 PPT Worker
make dev-ppt
```

---

## 14. 已有文档索引

| 路径 | 内容 |
|------|------|
| `README.md` | 项目概述、快速开始、预置应用 |
| `run.md` | 运行说明、多机构测试账号 |
| `政务AI平台调整方案.md` | 品牌/分类/应用调整方案 |
| `docs/UI-STYLE-GUIDE.md` | 政务蓝色彩体系、Lucide 图标规范 |
| `docs/APP-TYPE-STANDARD.md` | 5 种应用类型数据库字段与 UI 标准 |
| `docs/add-domain-guide.md` | 新增行业领域 13 步流程 |
| `docs/domain-legal.md` | 律师行业应用/知识库配置方案 |
| `docs/app-optimization-standard.md` | 55 个应用优化标准 |
| `docs/legal-domain-alpha-enhancement.md` | 律师域功能增强方案 |
| `server/migrations/seed_beihang.sql` | 北航教师 AI 应用中心种子数据 |
| `ppt-worker/README.md` | PPT Worker 技术文档 |

---

## 15. 关键观察与建议

### 15.1 当前状态

| 项目 | 状态 |
|------|------|
| 后端 API | 功能基本完整，部分 admin 接口为 `notImplemented` |
| 前端 UI | 功能完整，覆盖全部应用类型 |
| 多租户 | 已支持 11 个机构（含北京航空航天大学） |
| 知识库 | RAG 流程完整 |
| PPT 生成 | 独立微服务，功能完整 |
| 自定义 Hooks | 已抽取 5 个可复用 hook（SSE/剪贴板/滚动/导出/配置解析） |
| 类型定义 | 已统一到 `lib/types.ts`（含 25+ 个类型） |
| 错误边界 | 已完善（全局 + Portal + Admin 三层 error/loading/not-found） |
| 版本控制 | **未初始化 Git 仓库** |
| sqlc 生成 | 需手动执行 `make sqlc` |
| 生产部署 | `docker-compose.prod.yml` 缺失 |

### 15.2 技术亮点

1. **SSE 流式交互**：全部 AI 应用均支持流式输出，用户体验良好
2. **多应用类型**：5 种 UI 模式适配不同政务场景
3. **多租户架构**：机构级隔离，灵活的角色权限，已扩展至高校教育场景（北航）
4. **知识库 RAG**：基于 pgvector 的向量检索，支持文档上传与自动分片
5. **政务特色 Markdown**：定制渲染，支持知识库引用、应用推荐等特殊语法
6. **可复用 Hooks**：SSE 流式解析、剪贴板、自动滚动、文件导出等公共逻辑已抽取
7. **统一类型系统**：全部业务类型集中管理，按模块分组
8. **三层错误边界**：全局 / Portal / Admin 各层独立的错误捕获和加载状态

### 15.3 改进建议

1. **初始化 Git 仓库**，建立版本控制
2. **补全生产部署配置**（docker-compose.prod.yml）
3. **补充自动化测试**（前端单元测试 + 后端 API 测试）
4. ~~抽取可复用 Hooks~~ ✅ 已完成（v1.1.0）
5. ~~统一类型定义~~ ✅ 已完成（v1.1.0）
6. ~~完善错误边界~~ ✅ 已完成（v1.1.0）
7. **扩展更多行业机构**（教育、医疗等）— 北航已完成 ✅

---

## 16. 北京航空航天大学 AI 应用中心

### 16.1 概述

作为多租户架构的扩展案例，为北京航空航天大学教师提供专业的 AI 应用中心，包含 10 个教育专属分类和 20 个定制应用。

### 16.2 教育分类

| 分类 | slug | 应用数 |
|------|------|--------|
| 教学辅助 | edu-teaching | 4 |
| 科研助手 | edu-research | 3 |
| 论文写作 | edu-paper | 2 |
| 项目申报 | edu-grant | 3 |
| 学生指导 | edu-mentoring | 2 |
| 行政办公 | edu-admin | 2 |
| 学科建设 | edu-discipline | 1 |
| 国际交流 | edu-intl | 1 |
| 数据分析 | edu-data | 0 |
| 智慧工具 | edu-tools | 2 |

### 16.3 应用清单（20 个）

| 应用 | 类型 | 分类 | 特色 |
|------|------|------|------|
| 智能教案生成 | 补全型 | 教学辅助 | 多课型支持（理论/实验/实践） |
| 考试命题助手 | 工作流 | 教学辅助 | 4 步流程，自动组卷 |
| 课程设计咨询 | 对话型 | 教学辅助 | 北航课程体系+OBE 理念 |
| 教学评估报告 | 工作流 | 教学辅助 | 基于课程目标达成度分析 |
| 文献综述生成 | 补全型 | 科研助手 | 航空航天特色文献检索 |
| 实验方案设计 | 对话型 | 科研助手 | 工程实验/计算机实验 |
| 科研数据分析 | 智能体 | 科研助手 | 多工具调用，智能分析 |
| 论文润色助手 | 补全型 | 论文写作 | SCI 规范、学术规范 |
| 摘要与关键词生成 | 补全型 | 论文写作 | 中英双语 |
| 学术翻译 | 补全型 | 国际交流 | 航空航天专业术语 |
| 基金申请书助手 | 对话型 | 项目申报 | NSFC/科技部格式 |
| 项目结题报告 | 工作流 | 项目申报 | 3 步结构化生成 |
| 预算编制助手 | 补全型 | 项目申报 | 科研经费规范 |
| 论文评审意见 | 补全型 | 学生指导 | 建设性反馈 |
| 开题报告辅助 | 对话型 | 学生指导 | 硕博论文开题 |
| 高校公文写作 | 对话型 | 行政办公 | 高校公文格式规范 |
| 会议纪要生成 | 补全型 | 行政办公 | 学术会议/行政会议 |
| 学科规划报告 | 工作流 | 学科建设 | ESI/一流学科建设 |
| 学术PPT生成 | 补全型 | 智慧工具 | 学术风格模板 |
| 代码辅助 | 对话型 | 智慧工具 | 航空航天常用语言 |

### 16.4 部署方式

```bash
# 导入北航种子数据（在已有数据库上执行）
psql -U postgres -d govai -f server/migrations/seed_beihang.sql
```

种子脚本支持幂等执行（`ON CONFLICT DO NOTHING`），不会影响已有数据。

---

> **文档结束** — 此文档全面记录了政智通（GovAI）项目的技术架构、功能模块和开发现状。