290 lines
10 KiB
Markdown
290 lines
10 KiB
Markdown
# AIwelink 项目交接说明
|
||
|
||
这份文档帮助新成员快速了解 AIwelink 要解决的问题。
|
||
文档也说明第一阶段要做什么，以及当前已经确定的工程规则。
|
||
|
||
当前状态：产品方向和主要技术选型已经确定。
|
||
代码目录处于初始化前阶段。
|
||
商业、市场和运营安排仍以飞书中的文件为准。
|
||
|
||
## 1. AIwelink 是什么
|
||
|
||
AIwelink 帮助大学生认识自己的能力，找到合适的学习或项目机会。
|
||
用户在真实合作中积累经验。
|
||
|
||
第一阶段从大学生竞赛和技术项目开始。平台长期要做的事情是：
|
||
|
||
```text
|
||
了解自己
|
||
-> 找到合适的机会
|
||
-> 参加真实项目
|
||
-> 和合适的人合作
|
||
-> 得到项目结果和队友反馈
|
||
-> 更新对自己的认识
|
||
```
|
||
|
||
这里的「个人画像」指对用户能力、偏好、目标和合作方式的结构化描述。
|
||
画像会随着项目反馈持续更新。
|
||
|
||
## 2. 产品要解决什么问题
|
||
|
||
### 2.1 把信息变成行动
|
||
|
||
校园墙擅长让信息被看见。
|
||
AIwelink 进一步把信息整理成可执行的项目机会，帮助合适的人开始合作并完成项目。
|
||
|
||
项目或竞赛机会应尽量写清楚：
|
||
|
||
- 要做什么，以及何时截止；
|
||
- 需要哪些角色和能力；
|
||
- 每个角色要投入多少时间；
|
||
- 用户下一步可以做什么；
|
||
- 最后能留下什么作品或结果。
|
||
|
||
平台重点关注有效申请、成功组队、持续合作和完成项目的队伍数量。
|
||
|
||
### 2.2 让画像随着实践更新
|
||
|
||
AI 自我认知助手（Agent）先给出阶段性判断。
|
||
用户参加项目后的行为、队友反馈和项目复盘，会帮助平台持续更新这份判断。
|
||
|
||
平台要帮助用户回答：
|
||
|
||
- 我擅长哪类任务？
|
||
- 我适合在项目中承担什么角色？
|
||
- 什么工作环境更适合我？
|
||
- 哪些环节可能让我的合作变困难？
|
||
- 下一步应该尝试什么，或补哪项能力？
|
||
|
||
### 2.3 社交从一起做事开始
|
||
|
||
平台的社交功能围绕共同目标展开。
|
||
第一阶段优先服务用户已经认识的朋友、同学和队友。
|
||
恋爱交友放到后续产品规划中。
|
||
|
||
推荐的合作过程是：
|
||
|
||
```text
|
||
查看个人画像
|
||
-> 邀请认识的人
|
||
-> 双方明确同意共享内容
|
||
-> 生成双方的合作建议
|
||
-> 一起参加项目或挑战
|
||
-> 根据结果建立长期合作关系
|
||
```
|
||
|
||
双方合作报告重点说明优势互补、分工建议和可能的冲突。
|
||
报告还会给出沟通方式和适合一起尝试的项目。
|
||
|
||
### 2.4 推荐要让用户知道原因
|
||
|
||
平台可以推荐竞赛、项目、学习内容、项目角色、合作对象、课程、导师和 AI 工具。
|
||
每条推荐都应说明原因，并同时提供三类选择：
|
||
|
||
1. 当前能力可以完成的机会；
|
||
2. 能补足短板的机会；
|
||
3. 有一定挑战、适合探索的机会。
|
||
|
||
这样的推荐会帮助用户理解自己，并保留尝试不同方向的空间。
|
||
|
||
### 2.5 首页先告诉用户下一步做什么
|
||
|
||
首页把机会和下一步行动放在最前面，首先展示：
|
||
|
||
1. 适合用户的机会和项目；
|
||
2. 用户正在参与的项目；
|
||
3. 自我认知和成长任务；
|
||
4. 已完成的作品和项目经验；
|
||
5. 用户遇到具体问题后再推荐课程、API 或导师服务。
|
||
|
||
首页要回答一个简单问题：「现在最值得做的下一件事是什么？」
|
||
|
||
## 3. 第一阶段要验证的完整流程
|
||
|
||
第一阶段先验证下面这条流程能否真正帮助用户完成项目：
|
||
|
||
```text
|
||
自我认知助手
|
||
-> 生成个人画像
|
||
-> 推荐竞赛、项目和学习方向
|
||
-> 邀请朋友并取得共享许可
|
||
-> 生成双方合作建议
|
||
-> 参加一次真实项目或挑战
|
||
-> 记录项目行为和队友反馈
|
||
-> 复盘并更新个人画像
|
||
```
|
||
|
||
免费自我认知助手可以作为推广入口。
|
||
用户完成报告后，可以分享由自己选择的安全摘要。
|
||
邀请朋友并完成有效合作行为后，可以获得积分。
|
||
积分可兑换深度报告、API 额度、课程优惠或挑战资格。
|
||
|
||
积分奖励绑定报告完成、授权共享、生成合作报告、参加项目和完成复盘等真实行为。
|
||
|
||
## 4. 商业方向
|
||
|
||
平台先提供免费的机会和自我认知服务。
|
||
用户进入项目并遇到真实需求后，再提供付费服务：
|
||
|
||
```text
|
||
赛事和项目机会
|
||
-> 组队并开始合作
|
||
-> 产生 AI 工具和能力需求
|
||
-> 使用 API、课程、训练营或导师服务
|
||
-> 为学校、赛事方和企业提供组织服务
|
||
```
|
||
|
||
可能的收入来源包括：
|
||
|
||
- 面向竞赛团队的模型 API 和工具包；
|
||
- 赛事课程、训练营、作品评审和答辩辅导；
|
||
- 导师、作品评审和项目启动服务；
|
||
- 学校、社团和赛事方的报名、组队与活动管理；
|
||
- 企业命题赛、品牌合作和人才发现。
|
||
|
||
API 和课程在用户进入项目或明确遇到问题后出现，与当前任务直接相关。
|
||
|
||
## 5. 已确定的技术方案
|
||
|
||
| 领域 | 当前选择 |
|
||
| --- | --- |
|
||
| Web | Next.js、React、TypeScript |
|
||
| 业务 API | NestJS + Fastify Adapter |
|
||
| API 形式 | REST API，路径统一以 `/api/v1` 开头 |
|
||
| 数据访问 | Drizzle ORM；复杂查询使用参数化原生 SQL |
|
||
| 主数据库 | PostgreSQL |
|
||
| 向量检索 | PostgreSQL 的 `pgvector` 扩展 |
|
||
| 缓存和任务队列 | Redis |
|
||
| 文件存储 | 阿里云 OSS |
|
||
| 第一阶段部署 | 自有 ECS + Docker Compose |
|
||
| 后续部署 | Kubernetes |
|
||
| 身份系统 | API 内部的 `Identity` 模块 |
|
||
| 初期可用性监控 | Uptime Kuma |
|
||
|
||
AI 助手使用哪家模型、怎样编排对话、是否拆成独立服务，列为后续技术决定。
|
||
当前实现先保留清晰的接口，模型和框架确定后再接入。
|
||
|
||
### 5.1 Web 和 API 如何访问
|
||
|
||
Web 和 API 是两个独立应用，但第一阶段共用一个公网域名：
|
||
|
||
```text
|
||
https://aiwelink.com/ -> Next.js Web
|
||
https://aiwelink.com/api/v1/* -> NestJS REST API
|
||
```
|
||
|
||
入口代理（例如 Nginx）根据路径把请求转给不同容器。
|
||
第一阶段沿用同一个域名，核心业务统一放在 NestJS API 中。
|
||
|
||
### 5.2 API 规则
|
||
|
||
- URL 使用小写短横线，JSON 字段使用 `camelCase`；
|
||
- 使用资源名词和复数路径，例如 `/projects`；
|
||
- 使用标准 HTTP 方法和状态码；
|
||
- 列表优先使用游标分页；
|
||
- 订单、积分发放等容易重复提交的写操作按需支持 `Idempotency-Key`；
|
||
- 错误返回统一格式，并带 `requestId`；
|
||
- 权限由服务端统一检查，前端按钮只负责展示状态；
|
||
- 长时间任务建成任务资源，客户端可以查询任务进度和结果。
|
||
|
||
### 5.3 数据访问规则
|
||
|
||
代码按下面的顺序访问数据库：
|
||
|
||
```text
|
||
Controller
|
||
-> Application Service
|
||
-> Repository Interface
|
||
-> Drizzle Repository 或 SQL Repository
|
||
-> PostgreSQL
|
||
```
|
||
|
||
普通增删改查和事务使用 Drizzle。
|
||
向量相似度、全文搜索、复杂推荐和报表使用参数化 SQL。
|
||
Controller 通过 Repository 访问数据库。
|
||
|
||
### 5.4 数据和文件怎么放
|
||
|
||
用户身份、测评原始回答、AI 生成的画像和项目行为，按敏感程度分开保存。
|
||
公开内容、授权记录也分别管理。
|
||
大表先用索引、归档和 PostgreSQL 分区处理。
|
||
跨数据库分片等数据规模明确后再安排。
|
||
|
||
简历、作品、报告和项目附件放在阿里云 OSS。
|
||
浏览器直接上传，API 负责签发临时凭证、记录文件信息和检查权限。
|
||
私有文件用短期签名 URL 访问，应用容器只负责传输和权限控制。
|
||
|
||
## 6. 代码仓库和文档放在哪里
|
||
|
||
项目使用一个 Git 仓库（Monorepo），计划采用下面的目录：
|
||
|
||
```text
|
||
AIwelink/
|
||
├─ apps/
|
||
│ ├─ web/ # Next.js Web
|
||
│ ├─ api/ # NestJS REST API
|
||
│ ├─ worker/ # 异步任务，AI 助手方案待决定
|
||
│ └─ admin/ # 后续运营后台
|
||
├─ packages/
|
||
│ ├─ contracts/ # OpenAPI、DTO、共享接口
|
||
│ ├─ db/ # Drizzle Schema、迁移、种子数据
|
||
│ ├─ validation/ # 共享数据校验
|
||
│ ├─ ui/ # 跨应用 UI
|
||
│ ├─ config/ # 共享配置
|
||
│ └─ tooling/ # 工程工具配置
|
||
├─ infra/ # Docker、ECS、备份和后续 Kubernetes 配置
|
||
├─ scripts/ # 根目录脚本
|
||
├─ docs/ # 进入 Git 的工程文档
|
||
├─ docs-local/ # 本地临时文档，Git 忽略
|
||
└─ .github/ # 后续 CI/CD 配置
|
||
```
|
||
|
||
文档放置规则：
|
||
|
||
| 内容 | 位置 |
|
||
| --- | --- |
|
||
| 总体架构、技术栈、工程规范 | 根目录 `docs/`，提交到 Git |
|
||
| API 接口和模块实现 | `apps/api/docs/`，提交到 Git |
|
||
| 数据库结构和迁移规范 | `packages/db/docs/`，提交到 Git |
|
||
| Docker、ECS、备份等运维说明 | `infra/docs/`，提交到 Git |
|
||
| 临时需求、草稿和未确认讨论 | `docs-local/`，不提交到 Git |
|
||
| 商业、市场、运营和合作 | 飞书，不复制到 Git |
|
||
|
||
如果商业或运营决定会影响代码，只在 `docs/decisions/` 记录脱敏后的技术结论。
|
||
|
||
## 7. 新成员开始开发前要做什么
|
||
|
||
1. 先阅读本文件和[当前知识与安排](./current-knowledge-and-plan.md)。
|
||
再阅读 `docs/architecture/` 下的技术文档。
|
||
2. 新 API 遵循 `/api/v1` 和资源式 REST 设计。
|
||
3. 新业务模块放在 `apps/api/src/modules/` 对应目录。
|
||
4. 数据库访问统一经过 Repository。
|
||
5. 新的跨模块技术决定写进 `docs/decisions/`。
|
||
6. 商业和运营内容回到飞书维护。
|
||
7. AI 助手方案列为待决定事项。先保留接口和任务范围，模型和框架确定后再接入。
|
||
|
||
## 8. 后续再安排的能力
|
||
|
||
下面这些能力等真实用户和数据出现后再安排：
|
||
|
||
- 微服务拆分；
|
||
- Kubernetes 生产部署；
|
||
- 独立向量数据库；
|
||
- Elasticsearch 或 OpenSearch；
|
||
- ClickHouse；
|
||
- MongoDB；
|
||
- 复杂的机器学习推荐服务；
|
||
- 已经定型的 AI 助手编排框架；
|
||
- 跨数据库分片。
|
||
|
||
当前先验证用户能找到机会、组队并完成项目。
|
||
基础设施的复杂度根据真实数据再增加。
|
||
|
||
## 9. 一句话总结
|
||
|
||
AIwelink 通过真实项目帮助年轻人认识自己、找到合适的机会，并和合适的人把事情做完。
|
||
|
||
技术上先使用模块清楚的单仓库、独立 Web 和 REST API。
|
||
数据使用 PostgreSQL、Redis 和 OSS，第一阶段部署在 ECS + Docker Compose。
|
||
待决定的部分先保留接口，等真实需求出现后再选择。
|