# AIwelink 技术方案

本文说明第一阶段的 Web、业务 API、数据存储、文件存储、部署和基础监控方案。

AI 助手的模型供应商、对话编排方式和后台任务方案列为后续技术决定。
本文先约定接口和职责，具体实现等业务流程确定后再选。

## 1. 总体方案

第一阶段使用模块清楚、可以逐步扩展的架构：

- Web 页面和业务 API 分开部署；
- Web 和 API 通过一个域名对外提供服务，API 统一使用 `/api/v1` 路径；
- PostgreSQL 保存需要事务保证的数据，并使用 `JSONB`、全文搜索和 `pgvector`；
- Redis 处理缓存、限流和异步任务；
- 阿里云 OSS 保存简历、作品、报告和项目附件；
- Web、API 和任务程序都运行在 Docker 容器中；
- 第一阶段使用自有 ECS 和 Docker Compose，规模增长后再迁移到 Kubernetes；
- 用户身份、个人资料、项目行为和授权记录按敏感程度分开保存；
- 初期用 Uptime Kuma 检查网站和 API 是否可访问。

## 2. 已确定的技术选型

| 领域 | 当前选择 |
| --- | --- |
| Web 前端 | Next.js + React + TypeScript |
| 业务 API | NestJS + Fastify Adapter |
| API 形式 | REST API，路径前缀 `/api/v1` |
| 数据访问 | Drizzle ORM；复杂查询使用参数化原生 SQL |
| 主数据库 | PostgreSQL |
| 向量检索 | PostgreSQL 的 `pgvector` 扩展 |
| 缓存和任务队列 | Redis |
| 文件存储 | 阿里云 OSS |
| 运行环境 | Docker |
| 第一阶段部署 | 自有 ECS + Docker Compose |
| 后续部署 | Kubernetes |
| 身份系统 | API 内部的 `Identity` 模块 |
| 初期监控 | Uptime Kuma |

## 3. 服务怎样连接

```text
浏览器
  |
  v
Nginx 或其他入口代理
  |-- /              -> Next.js Web 容器
  |-- /api/v1/*      -> NestJS + Fastify API 容器
                              |
                      Drizzle / SQL Repository
                              |
                    PostgreSQL + pgvector
                              |
                            Redis
                              |
                          阿里云 OSS
```

Next.js 负责页面和交互。
NestJS 负责业务规则和 REST API。
浏览器通过同一个域名下的 `/api/v1/...` 路径调用 API。

## 4. API 内部模块

API 按业务模块组织，第一阶段至少包含：

- `Identity`：微信登录、邮箱绑定、会话和登录记录；
- `Users`：基础资料、学校、专业和年级；
- `Profiles`：个人画像、公开画像和画像版本；
- `Consents`：画像共享授权、撤销和授权记录；
- `Projects`：竞赛、项目、队伍、成员和申请；
- `Invitations`：邀请链接、接受记录和邀请关系；
- `Points`：积分流水、任务和兑换权益；
- `Commerce`：课程、API 权益、订单和退款记录；
- `Recommendations`：推荐内容、推荐理由和用户反馈；
- `Operations`：内容审核、举报、活动和运营配置。

AI 助手先通过独立接口接入。
模型、任务队列和报告生成流程确定后，再决定服务是否单独部署。

## 5. 数据怎样分层

数据按业务含义和敏感程度安排存储位置：

- 身份信息和联系方式；
- 原始测评回答；
- AI 生成的个人画像；
- 真实项目行为和合作证据；
- 用户主动公开的画像；
- 授权记录和审计记录。

大表先使用合理的表结构、索引和归档策略。
数据量和查询方式出现明确需求后，再评估 PostgreSQL 分区或其他存储方式。

## 6. 文件和媒体

简历、作品、报告和项目附件保存到阿里云 OSS，流程如下：

1. API 创建临时上传凭证；
2. 浏览器直接上传 OSS；
3. API 接收上传完成通知；
4. PostgreSQL 保存文件信息和权限关系；
5. 后台任务按需解析、审核或建立搜索索引。

应用服务器只处理上传授权和文件信息，不承担大文件的长期保存。

## 7. 部署和后续扩展

第一阶段用 Docker Compose 管理这些服务：

- Web 容器；
- API 容器；
- Worker 容器，用于异步任务；
- PostgreSQL；
- Redis。

生产环境逐步把应用容器和 PostgreSQL、Redis 分开部署，或改用托管服务。
同时设置备份、恢复和升级流程。

迁移 Kubernetes 时，应用服务保持无状态。
配置通过环境变量或 Secret 注入，文件继续放在 OSS，数据库迁移单独执行。

## 8. 监控和测试

Uptime Kuma 负责基础可用性检查：

- 首页是否能打开；
- `/api/v1/health/live` 是否返回进程存活；
- `/api/v1/health/ready` 是否确认 PostgreSQL、Redis 和必要配置可用；
- HTTPS 证书和端口是否正常。

测试单独建设，至少覆盖 TypeScript 类型检查、Lint、API 测试和关键流程端到端测试。
发布前还要检查数据库迁移。
核心流程包括登录、授权、邀请、项目申请和积分流水。

## 9. 第一阶段的工作重点

先完成用户登录、个人资料、自我认知、机会浏览、邀请共享、项目申请和积分记录。
再根据真实使用数据决定以下能力的时间：

- 微服务拆分；
- Kubernetes 生产部署；
- 独立向量数据库；
- Elasticsearch 或 OpenSearch；
- ClickHouse；
- MongoDB；
- 复杂机器学习推荐服务；
- 专门的 AI 助手编排框架。

这些能力都保留后续空间。
当前开发围绕用户找到机会、组成队伍并完成项目展开。