315 lines
11 KiB
Markdown
315 lines
11 KiB
Markdown
# 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。
|
||
|
||
工程实现应优先保持边界清楚、可解释、可迭代；商业和运营决策则统一在飞书中维护。
|
||
|