# AIwelink 项目交接说明

> 用途：帮助新加入的开发者快速理解 AIwelink 的产品方向、设计理念、技术基线和文档协作边界。
>
> 当前状态：产品和技术方向已完成初步确认，尚未进入实际代码目录初始化阶段。
>
> 重要范围：本文记录的是产品设计与工程共识，不等同于完整的商业运营方案。商业和运营细节以飞书为准。

## 1. 项目一句话定义

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

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

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

## 2. 产品设计理念

### 2.1 不做校园墙

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

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

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

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

### 2.2 不做一次性人格测试

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

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

平台要帮助用户回答：

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

### 2.3 社交来自共同目标

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

推荐路径是：

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

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

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

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

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

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

推荐对象包括：

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

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

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

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

首页的核心问题应是：

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

推荐内容优先级：

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

## 3. 第一阶段业务闭环

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

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

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

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

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

## 4. 商业化方向

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

```text
赛事和项目机会
  -> 组队和真实协作
  -> 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 是两个独立应用，但第一阶段使用同一个公网域名：

```text
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 数据访问原则

```text
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。当前只确定结构，不立即创建全部目录。

```text
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。

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