Initial commit: GovAI 政务AI平台

PROJECT_ANALYSIS.md

@@ -0,0 +1,372 @@
+# 政智通 (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 |
+
+---
+
+*本文档由代码分析自动生成，如有疑问请参考源代码。*