ZGH/NewPlatform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: initialize AIwelink project

Browse Source
This commit is contained in:
赵冠豪
2026-08-23 00:16:15 +08:00
commit 28f4efd675
10 changed files with 2680 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/technology-stack-details.md
+403
View File
@@ -0,0 +1,403 @@
# AIwelink 技术实现规则
本文补充 [AIwelink 技术方案](./technology-stack.md)。
文档说明请求怎样进入系统、代码怎样分层、数据怎样保存。
文档也列出第一阶段的部署和测试要求。
## 1. Web 和 API 使用一个域名
### 1.1 请求路径
第一阶段对外使用一个公网域名：
```text
https://aiwelink.com/ -> Next.js Web
https://aiwelink.com/api/v1/... -> REST API
```
入口代理（例如 Nginx）按路径转发：
```text
客户端
|
v
Nginx
|-- /api/v1/* -> api:3000
|-- /* -> web:3000
```
NestJS 设置全局前缀 `/api/v1`。代理和应用要统一路径处理方式，避免请求出现两次 `/api/v1`。
### 1.2 这样安排的好处
- 浏览器通过同域名直接访问 API，开发和生产使用相同请求路径；
- HttpOnly Cookie 的会话处理更简单；
- 分享页、公开机会页和登录后的工作台使用同一域名；
- 本地、测试和生产环境可以使用相同的请求路径；
- 将来改用 `api.aiwelink.com` 时，资源路径仍可以保持稳定。
### 1.3 入口代理要配置的规则
- Web 和 API 使用各自的超时、缓存和安全策略；
- Next.js 负责页面，业务规则统一放在 API；
- Next.js 服务端调用 API 时优先走 Docker 内网；
- 未来接入 App、第三方赛事系统或开放平台时，再单独设计 CORS、Token 和 API 子域名；
- 未来使用 SSE 时，代理关闭响应缓冲，并设置足够长的连接超时。
## 2. NestJS 和 Fastify
NestJS 提供模块、依赖注入、Guard、拦截器、异常过滤器和 OpenAPI 集成。
Fastify Adapter 负责底层 HTTP 服务。
这个组合适合授权、项目、邀请、积分和订单等规则较多的业务。
代码按以下规则编写：
- 使用兼容 Fastify 的 NestJS 插件；
- Controller 只接收请求、调用应用服务并组织响应；
- 复杂业务规则放在应用服务；
- Guard 和资源归属检查共同完成权限校验；
- 所有输入使用 DTO 校验；
- API 响应使用专门的响应类型，数据库实体只在数据访问层使用；
- 错误格式统一，并带 `requestId`；
- API 路径使用 `/api/v1`，JSON 字段使用 `camelCase`，URL 使用小写短横线。
推荐的目录如下：
```text
src/
modules/
identity/
users/
profiles/
consents/
projects/
opportunities/
invitations/
points/
commerce/
recommendations/
operations/
common/
guards/
filters/
interceptors/
decorators/
infrastructure/
database/
storage/
cache/
```
## 3. REST API 规则
### 3.1 用资源设计路径
资源名使用名词和复数形式：
```text
GET /api/v1/projects
GET /api/v1/projects/{projectId}
POST /api/v1/projects
PATCH /api/v1/projects/{projectId}
DELETE /api/v1/projects/{projectId}
```
明确的从属关系使用嵌套资源：
```text
GET /api/v1/projects/{projectId}/members
POST /api/v1/projects/{projectId}/applications
```
生成报告等耗时动作建模为报告资源或任务资源。
客户端先创建任务，再查询任务进度和结果。
### 3.2 HTTP 状态码
| 状态码 | 使用场景 |
| --- | --- |
| `200` | 读取或更新成功 |
| `201` | 创建资源成功 |
| `202` | 异步任务已接受 |
| `204` | 成功且没有响应内容 |
| `400` | 请求格式错误 |
| `401` | 未登录或会话失效 |
| `403` | 当前用户没有权限 |
| `404` | 资源不存在 |
| `409` | 当前资源状态不允许这次操作 |
| `422` | 字段校验失败 |
| `429` | 请求频率超过限制 |
| `500` | 服务端出现未处理异常 |
### 3.3 响应和错误格式
成功响应统一使用 `data` 字段。列表响应在 `meta` 中返回游标和分页信息。
错误响应采用 `application/problem+json`。
响应至少包含 `type`、`title`、`status`、`code`、`detail` 和 `requestId`。
### 3.4 可重复提交的写操作
订单创建、积分发放、邀请接受、付费权益创建和报告任务等操作支持 `Idempotency-Key`。
服务端保存请求结果，客户端重试时返回同一结果。
权限由 API 服务端统一检查，前端按钮只负责展示状态。
## 4. Identity 身份模块
### 4.1 职责
`Identity` 负责用户身份和会话。
个人资料、能力画像、项目经历和测评结果由其他模块管理。
建议的核心表：
```text
users
user_identities
sessions
email_verifications
login_events
```
### 4.2 登录方式
- 微信扫码或授权登录作为主入口；
- 邮箱用于绑定、验证、通知和账号恢复；
- 登录方式和用户主体分开保存，同一用户可以绑定多种登录方式；
- 会话使用 HttpOnly、Secure Cookie；
- 服务端保存会话状态和撤销记录；
- 长期 Token 放在服务端会话中管理。
未来可以增加手机号、学校身份验证或其他第三方身份，统一挂在 `users` 用户主体下。
## 5. Drizzle 和原生 SQL
### 5.1 选择规则
| 场景 | 访问方式 |
| --- | --- |
| 普通增删改查 | Drizzle |
| 普通事务 | Drizzle transaction |
| JSONB 复杂筛选 | Drizzle + SQL |
| `pgvector` 相似度查询 | SQL Repository |
| 推荐排序 | SQL Repository |
| 全文搜索 | SQL Repository |
| 报表和聚合 | SQL Repository |
原生 SQL 使用参数绑定。查询条件和排序字段经过代码校验后再拼接。
### 5.2 数据访问顺序
```text
Controller
↓
Application Service
↓
Repository Interface
↓
Drizzle Repository 或 SQL Repository
↓
PostgreSQL
```
Controller 通过 Repository 读取数据，这样业务规则和具体数据库工具可以分别测试和替换。
### 5.3 数据库迁移
- 数据库结构用版本化迁移保存；
- 普通表由 Drizzle Schema 和迁移工具维护；
- `pgvector`、特殊索引、函数和分区可以使用手写迁移 SQL；
- 生产环境的每次表结构变化都要留下迁移记录。
## 6. PostgreSQL、JSONB 和 pgvector
### 6.1 PostgreSQL 保存什么
PostgreSQL 保存需要事务一致性的业务数据。
这些数据包括用户、身份、授权、项目、成员、申请、积分、订单、报告信息和推荐记录。
Redis 负责速度和临时状态。最终业务状态仍以 PostgreSQL 为准。
### 6.2 JSONB 适合保存什么
JSONB 适合保存：
- 灵活的用户偏好；
- AI 输出的结构化报告内容；
- 带版本号的推荐特征快照；
- 运营可以调整的配置字段。
用户身份、权限、订单金额和状态，使用结构化字段。
积分流水和项目成员关系，也使用结构化字段。
数据库约束负责保证这些关系的一致性。
### 6.3 pgvector 怎样使用
`pgvector` 用于项目、课程、学科和公开内容的语义检索。每条向量记录至少保存：
- 来源资源 ID；
- Embedding 模型名称；
- 模型版本；
- 向量维度；
- 生成时间；
- 来源内容版本。
测评原始回答等敏感数据的向量化需要单独评估，并保留可解释的推荐理由。
## 7. 数据表和生命周期
### 7.1 业务分层
建议按下面的业务层组织表：
```text
身份层：users、user_identities、sessions
资料层：profile_basics、profile_preferences、public_profiles
认知层：assessment_sessions、assessment_answers、insight_snapshots
证据层：insight_evidence、project_reviews、behavior_events
授权层：consent_grants、consent_audits
项目层：opportunities、projects、project_members、applications
增长层：referral_events、point_ledger
审计层：audit_logs
```
### 7.2 大表处理
现在按业务功能拆表，方便权限、索引和数据保存周期管理。
大型追加型表按以下顺序处理：
1. 建立合理索引；
2. 优化时间范围查询；
3. 归档冷数据；
4. 为特殊查询建立单独的 SQL Repository；
5. 数据量持续增长后，再评估 PostgreSQL 分区。
## 8. Redis 的用途
Redis 用于：
- 热点数据缓存；
- 请求限流；
- 短期验证码和临时状态；
- 异步任务队列；
- 幂等键状态；
- 短期排行榜。
最终积分余额、订单状态、授权记录和用户画像原始数据，统一从 PostgreSQL 读取。
项目成员关系也由 PostgreSQL 保存。
## 9. 阿里云 OSS 文件流程
```text
API 创建临时凭证
↓
浏览器直接上传 OSS
↓
上传完成后通知 API
↓
PostgreSQL 写入文件信息
↓
按需解析、审核或建立索引
```
数据库保存的文件信息包括：
```text
fileId
ownerId
objectKey
mimeType
size
hash
visibility
createdAt
```
私有文件通过短期签名 URL 访问。上传流程检查文件类型、大小、哈希和归属关系。
## 10. ECS 和 Docker Compose
### 10.1 第一阶段服务
```text
nginx
web
api
worker（AI 助手方案待决定）
postgres
redis
```
应用容器配置健康检查和自动重启。镜像推送到镜像仓库，生产环境使用固定版本标签。
### 10.2 为未来 Kubernetes 做准备
现在就按以下方式运行：
- Web、API 和 Worker 分开成容器；
- 应用服务保持无状态；
- 配置通过环境变量或 Secret 注入；
- 文件放在 OSS；
- 数据库迁移独立执行；
- 服务之间通过内部 DNS 或配置发现通信。
### 10.3 数据服务的运维要求
如果 PostgreSQL 和 Redis 运行在 ECS 上，至少准备独立数据盘，并安排：
- 自动备份；
- 备份保留周期；
- 恢复演练；
- 磁盘空间监控；
- 数据库升级和回滚方案。
## 11. Uptime Kuma 和测试
### 11.1 可用性检查
建议提供两个健康检查接口：
```text
GET /api/v1/health/live
GET /api/v1/health/ready
```
`live` 只检查进程是否存活。`ready` 检查 PostgreSQL、Redis 和必要配置是否可用。
Uptime Kuma 监控首页、两个健康接口、TCP 端口和 HTTPS 证书到期时间。
### 11.2 测试范围
第一阶段至少安排：
- TypeScript 类型检查；
- Lint；
- API 单元测试和集成测试；
- 关键流程端到端测试；
- 发布前数据库迁移检查。
核心流程按下面的顺序覆盖：
```text
微信登录
→ 绑定邮箱
→ 创建个人资料
→ 创建项目
→ 发送邀请
→ 授权共享
→ 提交项目申请
→ 记录积分流水
```
## 12. 仍需决定的技术事项
以下内容等产品流程和数据量更清楚后再决定：
- AI 助手使用的模型供应商和模型路由；
- AI 助手的对话编排框架；
- 长报告和复杂任务使用哪种队列；
- 推荐系统是否拆成独立服务；
- 是否引入专用搜索引擎；
- Kubernetes 的发行版和部署方式；
- 完整的日志、指标和链路追踪方案。
docs/architecture/technology-stack.md
+151
View File
@@ -0,0 +1,151 @@
# AIwelink 技术方案
本文说明第一阶段的 Web、业务 API、数据存储、文件存储、部署和基础监控方案。
AI 助手的模型供应商、对话编排方式和后台任务方案列为后续技术决定。
本文先约定接口和职责，具体实现等业务流程确定后再选。
## 1. 总体方案
第一阶段使用模块清楚、可以逐步扩展的架构：
- Web 页面和业务 API 分开部署；
- Web 和 API 通过一个域名对外提供服务，API 统一使用 `/api/v1` 路径；
- PostgreSQL 保存需要事务保证的数据，并使用 `JSONB`、全文搜索和 `pgvector`；
- Redis 处理缓存、限流和异步任务；
- 阿里云 OSS 保存简历、作品、报告和项目附件；
- Web、API 和任务程序都运行在 Docker 容器中；
- 第一阶段使用自有 ECS 和 Docker Compose，规模增长后再迁移到 Kubernetes；
- 用户身份、个人资料、项目行为和授权记录按敏感程度分开保存；
- 初期用 Uptime Kuma 检查网站和 API 是否可访问。
## 2. 已确定的技术选型
| 领域 | 当前选择 |
| --- | --- |
| Web 前端 | Next.js + React + TypeScript |
| 业务 API | NestJS + Fastify Adapter |
| API 形式 | REST API，路径前缀 `/api/v1` |
| 数据访问 | Drizzle ORM；复杂查询使用参数化原生 SQL |
| 主数据库 | PostgreSQL |
| 向量检索 | PostgreSQL 的 `pgvector` 扩展 |
| 缓存和任务队列 | Redis |
| 文件存储 | 阿里云 OSS |
| 运行环境 | Docker |
| 第一阶段部署 | 自有 ECS + Docker Compose |
| 后续部署 | Kubernetes |
| 身份系统 | API 内部的 `Identity` 模块 |
| 初期监控 | Uptime Kuma |
## 3. 服务怎样连接
```text
浏览器
|
v
Nginx 或其他入口代理
|-- / -> Next.js Web 容器
|-- /api/v1/* -> NestJS + Fastify API 容器
|
Drizzle / SQL Repository
|
PostgreSQL + pgvector
|
Redis
|
阿里云 OSS
```
Next.js 负责页面和交互。
NestJS 负责业务规则和 REST API。
浏览器通过同一个域名下的 `/api/v1/...` 路径调用 API。
## 4. API 内部模块
API 按业务模块组织，第一阶段至少包含：
- `Identity`：微信登录、邮箱绑定、会话和登录记录；
- `Users`：基础资料、学校、专业和年级；
- `Profiles`：个人画像、公开画像和画像版本；
- `Consents`：画像共享授权、撤销和授权记录；
- `Projects`：竞赛、项目、队伍、成员和申请；
- `Invitations`：邀请链接、接受记录和邀请关系；
- `Points`：积分流水、任务和兑换权益；
- `Commerce`：课程、API 权益、订单和退款记录；
- `Recommendations`：推荐内容、推荐理由和用户反馈；
- `Operations`：内容审核、举报、活动和运营配置。
AI 助手先通过独立接口接入。
模型、任务队列和报告生成流程确定后，再决定服务是否单独部署。
## 5. 数据怎样分层
数据按业务含义和敏感程度安排存储位置：
- 身份信息和联系方式；
- 原始测评回答；
- AI 生成的个人画像；
- 真实项目行为和合作证据；
- 用户主动公开的画像；
- 授权记录和审计记录。
大表先使用合理的表结构、索引和归档策略。
数据量和查询方式出现明确需求后，再评估 PostgreSQL 分区或其他存储方式。
## 6. 文件和媒体
简历、作品、报告和项目附件保存到阿里云 OSS，流程如下：
1. API 创建临时上传凭证；
2. 浏览器直接上传 OSS；
3. API 接收上传完成通知；
4. PostgreSQL 保存文件信息和权限关系；
5. 后台任务按需解析、审核或建立搜索索引。
应用服务器只处理上传授权和文件信息，不承担大文件的长期保存。
## 7. 部署和后续扩展
第一阶段用 Docker Compose 管理这些服务：
- Web 容器；
- API 容器；
- Worker 容器，用于异步任务；
- PostgreSQL；
- Redis。
生产环境逐步把应用容器和 PostgreSQL、Redis 分开部署，或改用托管服务。
同时设置备份、恢复和升级流程。
迁移 Kubernetes 时，应用服务保持无状态。
配置通过环境变量或 Secret 注入，文件继续放在 OSS，数据库迁移单独执行。
## 8. 监控和测试
Uptime Kuma 负责基础可用性检查：
- 首页是否能打开；
- `/api/v1/health/live` 是否返回进程存活；
- `/api/v1/health/ready` 是否确认 PostgreSQL、Redis 和必要配置可用；
- HTTPS 证书和端口是否正常。
测试单独建设，至少覆盖 TypeScript 类型检查、Lint、API 测试和关键流程端到端测试。
发布前还要检查数据库迁移。
核心流程包括登录、授权、邀请、项目申请和积分流水。
## 9. 第一阶段的工作重点
先完成用户登录、个人资料、自我认知、机会浏览、邀请共享、项目申请和积分记录。
再根据真实使用数据决定以下能力的时间：
- 微服务拆分；
- Kubernetes 生产部署；
- 独立向量数据库；
- Elasticsearch 或 OpenSearch；
- ClickHouse；
- MongoDB；
- 复杂机器学习推荐服务；
- 专门的 AI 助手编排框架。
这些能力都保留后续空间。
当前开发围绕用户找到机会、组成队伍并完成项目展开。
docs/current-knowledge-and-plan.md
+307
View File
@@ -0,0 +1,307 @@
# AIwelink 当前知识与开发安排
这份总览回答四个问题：
1. AIwelink 现在要做什么；
2. 哪些事情已经确定；
3. 哪些事情还需要拍板；
4. 开发应该按什么顺序推进。
原来的文档已经备份到 `docs_old/`。
当前版本放在 `docs/`，内容以容易阅读和实际执行为目标。
## 1. 当前状态
- 产品方向：帮助大学生认识自己、找到项目机会；
- 用户在真实合作中积累成长记录；
- 第一阶段从大学生竞赛和技术项目开始；
- 技术主线已经确定：Next.js、NestJS、PostgreSQL、Redis、OSS、Docker Compose；
- 代码目录处于初始化前阶段；
- AI 助手的模型、对话编排和任务队列列为待决定事项；
- 第一场重点竞赛、运营节奏和收费价格列为待安排事项；
- 商业、市场和运营资料继续放在飞书。
## 2. 我们已经知道什么
### 2.1 用户要完成的事情
用户进入平台后，应该可以完成下面的过程：
```text
登录
-> 填写资料并了解自己
-> 看到适合的竞赛或项目
-> 选择项目角色
-> 邀请朋友并授权共享
-> 生成双方的合作建议
-> 申请加入项目
-> 记录项目进展和队友反馈
-> 完成复盘并更新个人画像
```
平台的价值来自真实行动和结果。推荐、报告和积分都要服务于这条过程。
### 2.2 第一阶段的产品范围
第一阶段优先完成这些功能：
- 微信登录、邮箱绑定和会话管理；
- 基础资料和个人画像；
- 自我认知助手的提问、回答和报告；
- 竞赛、项目和招募信息；
- 项目角色、成员和申请；
- 邀请链接和双方共享许可；
- 双人合作建议；
- 项目进展、队友反馈和复盘；
- 积分流水和基础兑换；
- 推荐内容和推荐理由；
- 首页工作台和公开机会页。
运营后台、完整商业交易、复杂推荐模型和大规模数据服务放在后续阶段安排。
### 2.3 数据应该留下什么
核心业务数据集中在 PostgreSQL：
- 用户和登录身份；
- 基础资料和公开资料；
- 测评回答和个人画像版本；
- 项目、成员、申请和行为记录；
- 队友反馈和项目复盘；
- 邀请、共享许可和审计记录；
- 积分流水、订单和权益；
- 推荐内容、推荐理由和用户反馈。
Redis 处理缓存、限流、短期状态和任务队列。
阿里云 OSS 保存简历、作品、报告和项目附件。
## 3. 已确认的工程规则
### 3.1 应用和访问路径
- Web 使用 Next.js + React + TypeScript；
- API 使用 NestJS + Fastify Adapter；
- Web 和 API 共用一个域名；
- API 路径统一从 `/api/v1` 开始；
- Web 负责页面和交互，API 负责业务规则；
- 入口代理按路径把请求转给 Web 或 API。
### 3.2 代码分层
数据库访问按下面的顺序组织：
```text
Controller
-> Application Service
-> Repository
-> PostgreSQL
```
普通查询使用 Drizzle ORM。
向量检索、全文搜索、推荐排序和复杂报表使用参数化原生 SQL。
Controller 通过 Repository 访问数据库。
### 3.3 部署和基础设施
第一阶段的服务包括：
```text
nginx
web
api
worker
postgres
redis
```
这些服务使用 Docker Compose 部署到自有 ECS。
文件上传到 OSS。
Uptime Kuma 检查首页、健康接口、端口和 HTTPS 证书。
## 4. 还需要拍板的事项
这些决定会直接影响产品和代码，建议按顺序确认：
### 4.1 确定第一个用户场景
需要明确第一场重点竞赛或项目，并写出完整流程：
- 用户从哪里进入；
- 需要填写哪些信息；
- 怎样看到机会；
- 怎样邀请队友；
- 怎样提交申请；
- 怎样记录项目结果。
### 4.2 确定个人画像的内容
需要确定自我认知助手的输入和输出：
- 需要问哪些问题；
- 报告包含哪些部分；
- 哪些内容可以公开分享；
- 用户怎样修改或补充报告；
- 项目反馈怎样更新画像。
### 4.3 确定项目和申请规则
需要确定：
- 项目有哪些状态；
- 项目角色怎样定义；
- 谁可以发布项目；
- 申请怎样审核；
- 成员怎样加入和退出；
- 项目完成后需要提交哪些结果。
### 4.4 确定 AI 助手方案
需要选择：
- 第一阶段使用的模型供应商；
- 单轮问答还是多轮对话；
- 报告是否异步生成；
- 任务失败后的重试方式；
- 记录哪些提示词、版本和费用信息。
### 4.5 确定运行方式
需要确定：
- PostgreSQL 和 Redis 自建还是托管；
- 备份保留多久；
- 生产环境的域名和证书管理；
- 日志、指标和告警使用哪些工具；
- 发布和回滚由谁负责。
## 5. 建议的开发顺序
### 第一步：写清第一个场景
先用一页文档写完「用户参加一场竞赛并找到队友」的过程。
再把页面、接口、数据和成功条件列出来。
产出：
- 用户流程图；
- 页面清单；
- API 清单；
- 数据表草图；
- 第一阶段成功指标。
### 第二步：初始化单仓库
创建下面的基础目录：
```text
apps/web
apps/api
apps/worker
packages/contracts
packages/db
packages/validation
packages/ui
packages/config
infra/docker
docs/decisions
```
同时配置 TypeScript、Lint、测试命令、环境变量示例和数据库迁移流程。
### 第三步：先做最小 API
建议先完成：
1. 登录和会话；
2. 用户资料；
3. 机会和项目；
4. 项目成员和申请；
5. 邀请和共享许可；
6. 积分流水；
7. 健康检查接口。
这些接口先用固定测试数据跑通，再接入真实页面。
### 第四步：接入自我认知助手
先定义统一的输入、输出和任务状态：
- 输入：用户回答、资料和项目上下文；
- 输出：结构化个人画像、推荐理由和待确认建议；
- 状态：待处理、处理中、完成、失败；
- 记录：模型名称、版本、提示词版本、耗时和费用。
模型供应商确定后，只替换具体实现，不改变业务接口。
### 第五步：完成 Web 主流程
Web 先实现这些页面：
- 公开机会页；
- 登录页；
- 个人资料页；
- 自我认知助手页；
- 首页工作台；
- 项目详情页；
- 邀请和共享确认页；
- 双人合作建议页；
- 项目申请页；
- 项目进展和复盘页。
每个页面都要能回到明确的下一步操作。
### 第六步：联调和试用
按真实用户顺序测试：
```text
登录
→ 填写资料
→ 完成自我认知
→ 浏览机会
→ 邀请朋友
→ 确认共享
→ 申请项目
→ 记录进展
→ 完成复盘
```
记录用户在哪一步停下、哪些字段看不懂、推荐理由是否有帮助，再调整页面和数据结构。
## 6. 第一阶段完成标准
第一阶段完成时，至少要满足：
- 用户可以完成登录并保存资料；
- 用户可以完成一次自我认知并得到结构化报告；
- 用户可以浏览机会和项目，并看到推荐原因；
- 用户可以邀请朋友，双方可以明确选择共享内容；
- 用户可以生成双方合作建议；
- 用户可以申请加入项目并看到申请状态；
- 项目可以记录成员、进展、结果和队友反馈；
- 复盘结果可以形成新的个人画像版本；
- 积分流水可以追溯到具体行为；
- 关键接口有权限检查、错误格式和请求编号；
- 核心流程有自动化测试；
- 生产环境有健康检查、备份和恢复步骤。
## 7. 需要持续记录的知识
后续每次决定都记录在对应位置：
- 跨模块技术决定：`docs/decisions/`；
- API 接口和模块实现：`apps/api/docs/`；
- 数据库结构和迁移：`packages/db/docs/`；
- 部署、备份和恢复：`infra/docs/`；
- 临时讨论：`docs-local/`；
- 商业、市场、运营和合作：飞书。
每条决定写清楚「问题、选择、原因、影响和后续复查条件」。
这样新成员可以直接看懂，也方便以后修改。
## 8. 当前一句话结论
AIwelink 先做一个围绕真实竞赛和项目的成长平台。
用户从了解自己开始，找到机会和队友，完成项目，再用结果更新自己的认识。
开发先把这条用户流程跑通，再扩展 AI 助手、推荐系统、商业服务和更复杂的基础设施。
docs/discussion-summary.md
+291
View File
@@ -0,0 +1,291 @@
# AIwelink 讨论结果说明
这份文档把项目从最初想法到当前方案的变化讲清楚。
它帮助新成员理解每个决定是怎么来的。
当前状态：产品方向已经收敛到「自我认知 + 项目机会 + 真实合作 + 项目反馈」。
技术方案也已经确定第一阶段的主要工具。
代码目录、AI 助手和运营节奏还要继续安排。
## 1. 项目从哪里开始
最初的想法是做一个项目合作平台。
用户可以上传简历和资料、发布项目、发起组队，并寻找队友或协作者。
平台面向大学竞赛，也保留真实开发者项目的空间。
继续讨论后，团队发现单独提供资料、帖子和私聊，用户很难得到长期价值。
于是产品重点逐渐转向「帮助用户找到合适的任务和合作方式，并把项目做完」。
## 2. 第一阶段先服务大学生竞赛
第一阶段选择大学生竞赛和技术项目，原因有三点：
- 赛事有明确的报名和截止时间；
- 学校、社团和学生组织方便触达用户；
- 发布机会、申请组队和提交作品的过程容易观察。
初期重点关注 AI、软件、数据分析、创新创业等技术相关竞赛。
后续可以扩展到科研、开源、企业命题和创业项目。
## 3. 产品定位逐步明确
AIwelink 的核心场景是带着任务一起做事：
```text
明确的竞赛或项目
-> 找到需要的角色和能力
-> 发起申请并组队
-> 共同完成作品
-> 记录结果和合作反馈
```
平台沉淀的结果包括有效申请、成功组队、持续合作、作品完成、竞赛提交和项目复盘。
浏览、点赞和聊天只是辅助行为。
校园墙可以作为信息分发渠道。
校园墙负责本地触达，AIwelink 承接结构化报名、组队、工具使用和成果记录。
## 4. 商业方向怎样形成
团队把商业路径安排为：
```text
免费赛事与项目机会
-> 用户组队并开始真实项目
-> 用户出现 AI 工具和能力需求
-> 使用 API、工具包、课程或导师服务
-> 学校、赛事方和企业采购组织服务
```
当前重点方向包括：
1. 面向竞赛团队的模型 API 和场景工具包；
2. 赛事课程、训练营、作品评审和答辩辅导；
3. 学校、社团和赛事方的报名、组队与活动管理；
4. 企业命题赛、模型或算力赞助、品牌合作；
5. 基于真实项目经历的人才发现和项目推荐。
平台在用户进入项目、遇到具体困难或开始备赛后展示相关服务。
这样服务内容和用户当前任务直接相关。
## 5. 首页要呈现什么
首页围绕机会和下一步行动安排内容：
1. 适合用户的竞赛和项目；
2. 即将截止或正在招募的机会；
3. 用户正在参与的项目；
4. 自我认知和成长任务；
5. 已完成的作品和经验；
6. 与当前项目有关的 API、课程和导师服务。
登录可以分阶段要求：
- 未登录用户浏览部分公开机会；
- 用户收藏、报名、申请组队或开始个性化自我认知时登录；
- 微信作为主登录入口；
- 邮箱用于绑定、验证、通知和账号恢复。
## 6. 自我认知功能怎样形成
用户真正关心的是自己适合什么任务、角色和协作方式。
因此，个人画像需要随着行动持续更新：
```text
自我评估
-> 选择项目
-> 真实行动
-> 队友反馈
-> 项目复盘
-> 更新个人画像
```
AI 自我认知助手先给出阶段性建议。
真实项目行为、合作结果和队友反馈会成为后续更新的重要依据。
平台通过提问、项目记录和复盘帮助用户了解：
- 自己擅长什么；
- 适合承担什么角色；
- 适合怎样的工作环境；
- 哪些环节容易遇到困难；
- 下一步该学习或尝试什么。
## 7. 邀请、合作报告和积分
自我认知助手也可以作为推广入口：
```text
免费自我认知助手
-> 生成个人报告
-> 分享用户选择的安全摘要
-> 邀请朋友
-> 生成双方或团队的合作建议
-> 推荐适合一起参加的项目
```
双方取得明确许可后，合作报告可以包含：
- 互补优势；
- 分工建议；
- 可能发生摩擦的地方；
- 推荐的沟通方式；
- 适合一起参加的项目；
- 合作前需要约定的规则。
积分奖励绑定真实行为。
例如完成个人报告、完成共享许可、生成合作报告、参加项目和完成复盘。
积分可以兑换深度报告、API 额度、课程优惠、导师问答或挑战资格。
第一阶段先服务已经认识的朋友、同学和队友。
随着项目记录增加，再扩展到三至五人的团队合作建议。
## 8. 推荐系统的方向
推荐对象包括竞赛、项目、学科和学习内容。
也包括项目角色、合作对象、课程、导师和 AI 工具。
推荐会综合这些信息：
- 用户能力和目标；
- 可以投入的时间；
- 工作偏好；
- 完成或放弃过的项目；
- 项目中的真实行为；
- 队友反馈和复盘结果。
第一阶段先采用规则、标签、行为信号和必要的向量检索。
每条推荐带理由，让用户知道选择依据。
## 9. 技术方案怎样确定
### 9.1 后端语言
团队比较了 Go、TypeScript 和 Python。
第一阶段业务主要处理网络请求、数据库读写和第三方模型调用。
全栈 TypeScript 已经能够覆盖这些工作。
Go 留作未来独立高性能服务的选择。
Python 留作算法和数据分析任务的选择。
当前先保持一个主要语言，减少工程维护量。
### 9.2 Web 框架
React 负责 UI 组件，Next.js 负责完整 Web 应用。
平台需要公开机会页、分享页、搜索收录和登录后的工作台。
因此确定使用：
> Next.js + React + TypeScript
页面质量由设计系统、信息层级、动效、响应式布局和性能共同决定。
### 9.3 Web 和 REST API
Web 与业务 API 分开：
```text
https://aiwelink.com/ -> Next.js
https://aiwelink.com/api/v1/* -> 独立 REST API
```
同域名入口减少跨域和子域名配置工作，也保留未来独立扩展 API 的空间。
### 9.4 API 框架
后端采用 NestJS + Fastify Adapter。
NestJS 负责模块、依赖注入、权限 Guard、异常处理和 OpenAPI。
Fastify 负责 HTTP 服务。
### 9.5 数据访问
普通增删改查和事务使用 Drizzle ORM。
向量相似度、全文搜索、推荐排序和复杂报表通过 Repository 使用参数化原生 SQL。
### 9.6 数据和基础设施
- PostgreSQL 保存主要业务数据；
- `pgvector` 提供向量检索；
- Redis 负责缓存、限流和任务队列；
- 阿里云 OSS 保存简历、作品、报告和附件；
- Docker 运行 Web、API 和 Worker；
- 第一阶段部署在自有 ECS + Docker Compose；
- 后续根据规模迁移 Kubernetes；
- Uptime Kuma 负责基础可用性监控。
## 10. 单仓库和文档位置
项目使用单 Git 仓库（Monorepo），计划按以下目录组织：
- `apps/web`：Next.js Web；
- `apps/api`：NestJS REST API；
- `apps/worker`：异步任务；
- `apps/admin`：后续运营后台；
- `packages/contracts`：OpenAPI、DTO 和共享接口；
- `packages/db`：Drizzle Schema、迁移和种子数据；
- `infra`：Docker、ECS、备份和后续 Kubernetes 配置。
文档位置按内容分工：
| 文档内容 | 位置 |
| --- | --- |
| 总体架构、技术栈、工程规范 | 根目录 `docs/` |
| API 接口和模块实现 | `apps/api/docs/` |
| 数据库结构和迁移规范 | `packages/db/docs/` |
| 技术部署和备份 | `infra/docs/` |
| 临时需求和未确认讨论 | `docs-local/` |
| 商业、市场、运营和合作 | 飞书 |
## 11. 当前已经确定的事情
- 第一阶段服务大学生竞赛和技术项目；
- 产品由自我认知、机会推荐、真实合作和项目反馈组成；
- 首页围绕机会和下一步行动；
- 双方取得许可后生成合作建议；
- 推荐结果说明原因；
- 使用 Next.js + React + TypeScript；
- 使用独立 REST API，路径为 `/api/v1`；
- Web 和 API 共用一个域名；
- 使用 NestJS + Fastify Adapter；
- 使用 Drizzle 和参数化原生 SQL；
- API 内部建立 `Identity` 模块；
- 使用 PostgreSQL、`pgvector`、Redis 和阿里云 OSS；
- 第一阶段使用 ECS + Docker Compose；
- 商业和运营资料放在飞书。
## 12. 还要决定的事情
- AI 助手使用哪家模型和怎样路由模型；
- AI 助手使用哪种对话编排框架；
- 长报告和复杂任务使用哪种队列；
- 推荐系统是否拆成独立服务；
- 测试工具和日志、指标方案；
- 生产环境的 PostgreSQL 和 Redis 使用自建还是托管；
- 第一场重点竞赛、运营节奏和具体价格。
## 13. 给新成员的阅读顺序
1. 先读本文，了解产品方向的变化；
2. 再读 `docs/project-handoff.md`，了解工程规则；
3. 阅读 `docs/architecture/technology-stack.md`，掌握整体技术方案；
4. 阅读 `docs/architecture/technology-stack-details.md`，了解接口、数据和部署细节；
5. 开始实现对应模块前，再阅读模块文档和决定记录；
6. 遇到待决定的事项，先保持接口清楚，把选项和依据记录下来。
## 14. 讨论结论
项目方向从「项目合作平台」逐步明确为：
```text
项目合作平台
-> 大学生竞赛组队
-> 以任务为中心的协作
-> 以自我认知为长期能力
-> 推荐项目、学科和合作对象
-> 双方取得许可后生成合作建议
-> 通过真实项目积累成长和合作数据
-> 用 API、课程、导师和机构服务提供收入
```
技术安排遵循同一原则：先用清楚、稳定、可以持续修改的模块化架构验证用户价值。
等用户数量、项目数据和实际故障模式变得清楚后，再决定后续技术投入。
候选项包括 AI 助手编排、复杂推荐、Kubernetes 和专用基础设施。
docs/project-handoff.md
+289
View File
@@ -0,0 +1,289 @@
# 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。
待决定的部分先保留接口，等真实需求出现后再选择。