# Crawlful Hub - Node.js 后端技术指南 (V30.0)

## 1. 技术栈
- **Runtime**: Node.js v20+
- **Language**: TypeScript (Strict Mode)
- **Database**: MySQL 8.0 (Aliyun RDS)
- **Cache**: Redis 6.0 (Local)
- **ORM**: Knex.js
- **AI**: Gemini-3-Flash, CLIP, Sentiment Analysis

## 2. 目录结构
- `server/src/core/`: AGI 内核、算力调度、隐私审计。
- `server/src/domains/`: 业务领域模型（Trade, Finance, Product, Logistics 等）。
- `server/src/api/`: 外部与内部 API 路由。
- `server/src/workers/`: 异步任务与爬虫任务。

## 3. 本地开发环境搭建

### 3.1 前置条件
```bash
# 安装 Node.js v20+
node -v  # 应显示 v20.x.x

# 安装 pnpm (推荐)
npm install -g pnpm

# 安装 MySQL 8.0 (本地或 Docker)
docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=root mysql:8.0

# 安装 Redis 6.0
docker run -d -p 6379:6379 redis:6.0
```

### 3.2 项目初始化
```bash
# 安装依赖
cd server
pnpm install

# 复制环境变量配置
cp .env.example .env
# 编辑 .env 配置数据库连接、Redis 等

# 运行数据库迁移
pnpm migrate:latest

# 启动开发服务器
pnpm dev
```

### 3.3 常用命令
| 命令 | 功能 |
|------|------|
| `pnpm dev` | 启动开发服务器 (热重载) |
| `pnpm build` | 编译 TypeScript |
| `pnpm start` | 生产环境启动 |
| `pnpm migrate:make` | 创建数据库迁移 |
| `pnpm seed:run` | 运行数据填充 |
| `pnpm lint` | 代码风格检查 |

### 3.4 调试指南
- **VS Code 调试**：配置 `.vscode/launch.json` 使用 Node.js debugger
- **日志级别**：通过 `LOG_LEVEL` 环境变量控制 (debug/info/warn/error)
- **API 测试**：启动后访问 `http://localhost:3000/api/health` 检查服务状态

## 4. 代码规范
- **严格模式**：tsconfig.json 启用 `strict: true`
- **路径别名**：使用 `@/*` 引用 server/src 下的模块
- **命名规范**：
  - 文件：小写短横线 (kebab-case)
  - 类/接口：大驼峰 (PascalCase)
  - 变量/函数：小驼峰 (camelCase)

## 5. 核心模块说明
- **Core**: AGI 决策引擎、算力调度、隐私计算
- **Domains**: 业务领域服务 (Trade/Finance/Product/Logistics)
- **API**: RESTful 接口层，含外部 API 与内部 API
- **Workers**: BullMQ 异步任务、Crawler 爬虫任务

---
**版本记录**: V30.0 (AI-Native Overhaul)
**更新日志**: [AI-3 @ 2026-03-15] 补充本地开发环境搭建与常用命令