docs: initialize AIwelink project
This commit is contained in:
@@ -0,0 +1,151 @@
|
||||
# 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 助手编排框架。
|
||||
|
||||
这些能力都保留后续空间。
|
||||
当前开发围绕用户找到机会、组成队伍并完成项目展开。
|
||||
Reference in New Issue
Block a user