NewPlatform/docs/project-handoff.md

AIwelink 项目交接说明

这份文档帮助新成员快速了解 AIwelink 要解决的问题。 文档也说明第一阶段要做什么，以及当前已经确定的工程规则。

当前状态：产品方向和主要技术选型已经确定。 代码目录处于初始化前阶段。 商业、市场和运营安排仍以飞书中的文件为准。

1. AIwelink 是什么

AIwelink 帮助大学生认识自己的能力，找到合适的学习或项目机会。 用户在真实合作中积累经验。

第一阶段从大学生竞赛和技术项目开始。平台长期要做的事情是：

了解自己
  -> 找到合适的机会
  -> 参加真实项目
  -> 和合适的人合作
  -> 得到项目结果和队友反馈
  -> 更新对自己的认识

这里的「个人画像」指对用户能力、偏好、目标和合作方式的结构化描述。 画像会随着项目反馈持续更新。

2. 产品要解决什么问题

2.1 把信息变成行动

校园墙擅长让信息被看见。 AIwelink 进一步把信息整理成可执行的项目机会，帮助合适的人开始合作并完成项目。

项目或竞赛机会应尽量写清楚：

• 要做什么，以及何时截止；
• 需要哪些角色和能力；
• 每个角色要投入多少时间；
• 用户下一步可以做什么；
• 最后能留下什么作品或结果。

平台重点关注有效申请、成功组队、持续合作和完成项目的队伍数量。

2.2 让画像随着实践更新

AI 自我认知助手（Agent）先给出阶段性判断。 用户参加项目后的行为、队友反馈和项目复盘，会帮助平台持续更新这份判断。

平台要帮助用户回答：

• 我擅长哪类任务？
• 我适合在项目中承担什么角色？
• 什么工作环境更适合我？
• 哪些环节可能让我的合作变困难？
• 下一步应该尝试什么，或补哪项能力？

2.3 社交从一起做事开始

平台的社交功能围绕共同目标展开。 第一阶段优先服务用户已经认识的朋友、同学和队友。 恋爱交友放到后续产品规划中。

推荐的合作过程是：

查看个人画像
  -> 邀请认识的人
  -> 双方明确同意共享内容
  -> 生成双方的合作建议
  -> 一起参加项目或挑战
  -> 根据结果建立长期合作关系

双方合作报告重点说明优势互补、分工建议和可能的冲突。 报告还会给出沟通方式和适合一起尝试的项目。

2.4 推荐要让用户知道原因

平台可以推荐竞赛、项目、学习内容、项目角色、合作对象、课程、导师和 AI 工具。 每条推荐都应说明原因，并同时提供三类选择：

1. 当前能力可以完成的机会；
2. 能补足短板的机会；
3. 有一定挑战、适合探索的机会。

这样的推荐会帮助用户理解自己，并保留尝试不同方向的空间。

2.5 首页先告诉用户下一步做什么

首页把机会和下一步行动放在最前面，首先展示：

1. 适合用户的机会和项目；
2. 用户正在参与的项目；
3. 自我认知和成长任务；
4. 已完成的作品和项目经验；
5. 用户遇到具体问题后再推荐课程、API 或导师服务。

首页要回答一个简单问题：「现在最值得做的下一件事是什么？」

3. 第一阶段要验证的完整流程

第一阶段先验证下面这条流程能否真正帮助用户完成项目：

自我认知助手
  -> 生成个人画像
  -> 推荐竞赛、项目和学习方向
  -> 邀请朋友并取得共享许可
  -> 生成双方合作建议
  -> 参加一次真实项目或挑战
  -> 记录项目行为和队友反馈
  -> 复盘并更新个人画像

免费自我认知助手可以作为推广入口。 用户完成报告后，可以分享由自己选择的安全摘要。 邀请朋友并完成有效合作行为后，可以获得积分。 积分可兑换深度报告、API 额度、课程优惠或挑战资格。

积分奖励绑定报告完成、授权共享、生成合作报告、参加项目和完成复盘等真实行为。

4. 商业方向

平台先提供免费的机会和自我认知服务。 用户进入项目并遇到真实需求后，再提供付费服务：

赛事和项目机会
  -> 组队并开始合作
  -> 产生 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 是两个独立应用，但第一阶段共用一个公网域名：

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 数据访问规则

代码按下面的顺序访问数据库：

Controller
  -> Application Service
  -> Repository Interface
  -> Drizzle Repository 或 SQL Repository
  -> PostgreSQL

普通增删改查和事务使用 Drizzle。 向量相似度、全文搜索、复杂推荐和报表使用参数化 SQL。 Controller 通过 Repository 访问数据库。

5.4 数据和文件怎么放

用户身份、测评原始回答、AI 生成的画像和项目行为，按敏感程度分开保存。 公开内容、授权记录也分别管理。 大表先用索引、归档和 PostgreSQL 分区处理。 跨数据库分片等数据规模明确后再安排。

简历、作品、报告和项目附件放在阿里云 OSS。 浏览器直接上传，API 负责签发临时凭证、记录文件信息和检查权限。 私有文件用短期签名 URL 访问，应用容器只负责传输和权限控制。

6. 代码仓库和文档放在哪里

项目使用一个 Git 仓库（Monorepo），计划采用下面的目录：

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. 先阅读本文件和当前知识与安排。 再阅读 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。 待决定的部分先保留接口，等真实需求出现后再选择。