# 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。
待决定的部分先保留接口，等真实需求出现后再选择。