NewPlatform/docs_old/project-handoff.md

AIwelink 项目交接说明

用途：帮助新加入的开发者快速理解 AIwelink 的产品方向、设计理念、技术基线和文档协作边界。

当前状态：产品和技术方向已完成初步确认，尚未进入实际代码目录初始化阶段。

重要范围：本文记录的是产品设计与工程共识，不等同于完整的商业运营方案。商业和运营细节以飞书为准。

1. 项目一句话定义

AIwelink 是一个帮助大学生认识自己、找到适合的学习或项目机会，并在真实协作中建立高质量关系的项目成长平台。

第一阶段从大学生竞赛和技术项目切入，但长期方向不局限于竞赛信息或组队，而是逐步形成：

认识自己
  -> 发现适合的机会
  -> 参与真实项目
  -> 与合适的人协作
  -> 获得项目反馈
  -> 更新个人认知和成长路径

2. 产品设计理念

2.1 不做校园墙

校园墙解决的是“让信息被看见”；AIwelink 要解决的是“让合适的人真正开始并完成一件事”。

因此平台内容应尽量绑定：

• 明确的竞赛、项目或挑战。
• 具体的角色和能力缺口。
• 时间投入和截止时间。
• 用户能够采取的下一步行动。
• 最终的作品、结果或复盘。

核心指标不应是发帖数和浏览量，而应逐步关注有效申请率、成队率、持续协作率和完成项目的队伍数量。

2.2 不做一次性人格测试

自我认知 Agent 不是为了给用户贴上固定人格标签，也不是心理疾病诊断工具。

测评或对话产生的结果应被视为当前阶段的“待验证假设”，后续通过真实项目行为、队友反馈和项目复盘逐渐修正。

平台要帮助用户回答：

• 我擅长什么类型的任务？
• 我适合承担什么项目角色？
• 我在什么工作环境中更容易发挥？
• 我可能在哪些环节遇到困难？
• 下一步应该尝试什么或补足什么能力？

2.3 社交来自共同目标

社交可以是平台的重要属性，但不应从泛聊天或陌生人浏览开始。

推荐路径是：

个人画像
  -> 邀请已认识的人
  -> 双方明确授权共享
  -> 生成双人合作报告
  -> 共同参加项目或挑战
  -> 通过结果建立长期关系

社交关系的核心不是“匹配指数”，而是：

• 彼此有哪些互补优势。
• 适合怎样分工。
• 可能在哪些地方产生协作摩擦。
• 应该采用什么沟通方式。
• 适合一起尝试什么项目。

第一阶段优先面向已经认识的朋友、同学和队友，降低信任和隐私风险。暂不以恋爱社交为主场景。

2.4 推荐应帮助用户理解自己

推荐系统不只是提高点击率的工具，而是帮助用户做选择和形成自我认知的导航系统。

推荐对象包括：

• 竞赛和项目。
• 学科和学习内容。
• 项目角色。
• 合作对象。
• 课程、导师和 AI 工具。

每条推荐应尽量解释“为什么推荐”，并同时提供适合当前能力的机会、补足短板的机会和带有挑战性的探索机会，避免把用户锁死在单一标签中。

2.5 首页以机会和下一步为中心

首页不以介绍产品、API 或课程为主，也不做简历瀑布流或泛校园信息流。

首页的核心问题应是：

用户现在最值得做的下一件事是什么？

推荐内容优先级：

1. 适合用户的机会和项目。
2. 用户正在参与的项目。
3. 自我认知和成长任务。
4. 真实项目成果和经验。
5. 在具体需求出现后推荐课程、API 或导师服务。

3. 第一阶段业务闭环

第一阶段优先验证以下闭环：

自我认知 Agent
  -> 生成个人画像
  -> 推荐竞赛、项目和学习方向
  -> 邀请朋友并授权共享画像
  -> 生成双人合作报告
  -> 参与一次真实项目或挑战
  -> 记录项目行为和队友反馈
  -> 复盘并更新画像

平台的推广入口可以是免费的自我认知 Agent：

• 用户完成个人认知报告。
• 用户分享安全、可控的摘要。
• 邀请朋友后解锁双人或团队分析。
• 完成有效邀请或项目行为后获得积分。
• 积分可兑换深度报告、API 额度、课程优惠或挑战资格。

邀请机制应围绕双方共同获得的价值设计，不应只奖励链接点击或虚假注册。

4. 商业化方向

平台本身先提供免费价值，再在真实需求出现时转化：

赛事和项目机会
  -> 组队和真实协作
  -> AI 工具与 API 使用
  -> 竞赛课程、训练营和导师服务
  -> 学校、赛事方和企业服务

主要商业化方向包括：

• 面向竞赛团队的模型 API 和工具包。
• 面向具体赛事的课程、训练营和作品辅导。
• 导师、作品评审和项目启动服务。
• 学校、社团和赛事方的组织管理服务。
• 企业命题赛、品牌赞助和人才发现。

API 和课程不应成为首页硬广告，而应在用户已进入项目或明确遇到问题时出现。

5. 技术总体基线

5.1 已确认选型

层	选型
Web	Next.js + React + TypeScript
业务 API	NestJS + Fastify Adapter
API 规范	RESTful API，路径前缀 /api/v1
数据访问	Drizzle ORM 为默认工具，复杂查询补充原生 SQL
主数据库	PostgreSQL
向量能力	PostgreSQL pgvector 扩展
缓存和队列基础设施	Redis
文件存储	阿里云 OSS
部署	自有 ECS + Docker Compose
后续部署	Kubernetes
身份系统	API 内部 Identity 模块
初期可用性监控	Uptime Kuma

Agent 的具体模型供应商、编排框架、异步任务实现和独立服务边界暂不定型。

5.2 Web 与 API 的关系

Web 和 API 是两个独立应用，但第一阶段使用同一个公网域名：

https://aiwelink.com/            -> Next.js Web
https://aiwelink.com/api/v1/*   -> NestJS REST API

通过 Nginx 或同类入口反向代理分流。第一阶段不要求 API 子域名，也不把核心业务逻辑写进 Next.js 页面接口。

5.3 API 设计原则

• 使用资源名词和复数路径。
• 使用标准 HTTP 方法和状态码。
• 使用 /api/v1 版本前缀。
• JSON 字段使用 camelCase，URL 使用小写短横线。
• 列表优先使用游标分页。
• 写操作按需支持 Idempotency-Key。
• 错误响应统一格式，并带 requestId。
• 权限必须在服务端校验，不能只依赖前端控制。
• 长任务建模为资源或任务，不能把所有功能写成动词接口。

5.4 数据访问原则

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

• 普通 CRUD 使用 Drizzle。
• 普通事务使用 Drizzle transaction。
• pgvector、全文搜索、复杂推荐和报表使用参数化原生 SQL。
• Controller 不直接访问数据库。
• 数据库结构必须通过版本化迁移维护。

5.5 数据分层原则

数据按业务和敏感性拆分，不提前进行跨数据库分片：

• 身份数据和登录方式。
• 基础资料和公开画像。
• 原始测评回答。
• AI 推测画像和画像版本。
• 项目行为和队友反馈。
• 公开共享结果。
• 授权记录和审计记录。

大型追加型表先通过索引、归档和后续 PostgreSQL 分区解决，实际需要出现前不引入多数据库分片。

5.6 文件存储原则

简历、作品、报告和项目附件使用阿里云 OSS。推荐浏览器直传 OSS，API 只负责签发临时凭证、记录元数据和校验权限。私有文件通过短期签名 URL 访问，应用容器不作为长期文件存储位置。

6. 代码仓库和文档协作约定

使用单 Git 仓库和 Monorepo。当前只确定结构，不立即创建全部目录。

AIwelink/
├─ apps/
│  ├─ web/                       # Next.js Web
│  ├─ api/                       # NestJS REST API
│  ├─ worker/                    # 异步任务，Agent 方案未定型
│  └─ admin/                     # 后续运营后台
├─ packages/
│  ├─ contracts/                 # OpenAPI、DTO、共享接口
│  ├─ db/                        # Drizzle Schema、迁移、种子
│  ├─ validation/               # 共享数据校验
│  ├─ ui/                        # 跨应用 UI
│  ├─ config/                    # 共享配置
│  └─ tooling/                  # 工程工具配置
├─ infra/
│  ├─ docker/                    # Compose、Nginx、脚本
│  ├─ ecs/                       # ECS 部署配置
│  ├─ k8s/                       # 后续 Kubernetes 配置
│  └─ docs/                      # 技术运维文档
├─ scripts/                      # 根级脚本
├─ docs/                         # 全局工程文档，进入 Git
├─ docs-local/                   # 临时文档，本地存在但 Git 忽略
└─ .github/                      # 后续 CI/CD

6.1 文档放置规则

内容	归属
总体架构、技术栈、工程规范	根目录 docs/，进入 Git
API 具体接口和模块实现	apps/api/docs/，进入 Git
数据库结构和迁移规范	packages/db/docs/，进入 Git
Docker、ECS、备份等技术运维	infra/docs/，进入 Git
临时需求、草稿和未确认讨论	docs-local/，Git 忽略
商业、市场、运营和合作	飞书，不进入 Git

如果商业或运营决策最终影响代码，只把脱敏后的技术结论记录到 docs/decisions/，不复制完整商业背景。

7. 开发者接手时的工作方式

新开发者开始实现前，应先确认：

1. 先阅读本文和根目录工程文档。
2. 不擅自改变已确认的 API、数据库和部署边界。
3. 新增 API 必须遵循 /api/v1 和 RESTful 资源设计。
4. 新增业务模块应放在 apps/api/src/modules/ 对应目录。
5. 数据库访问必须经过 Repository，不在 Controller 直接写查询。
6. 新的跨模块技术决策记录到 docs/decisions/。
7. 商业或运营内容不要提交到 Git，回到飞书维护。
8. Agent 方案属于未定型事项，先保持接口边界，不要提前绑定具体供应商或框架。

8. 当前明确不做的事情

第一阶段暂不提前引入：

• 微服务拆分。
• Kubernetes 生产部署。
• 独立向量数据库。
• Elasticsearch / OpenSearch。
• ClickHouse。
• MongoDB。
• 复杂机器学习推荐服务。
• 已定型的 Agent 编排框架。
• 过早的跨库分片。

选择这些边界的原因是：当前首先验证产品闭环和用户价值，而不是提前解决尚未出现的规模问题。

9. 交接结论

AIwelink 的核心不是“校园信息流”或“陌生人交友”，而是：

通过真实项目帮助年轻人认识自己、找到适合的机会，并与合适的人建立高质量协作关系。

技术上采用清晰的模块化 Monorepo，Web 和 REST API 分离但同域名提供，业务数据以 PostgreSQL 为中心，敏感数据分层存储，文件使用 OSS，第一阶段使用 ECS + Docker Compose。

工程实现应优先保持边界清楚、可解释、可迭代；商业和运营决策则统一在飞书中维护。