120 lines
3.1 KiB
Markdown
120 lines
3.1 KiB
Markdown
# Suanming Web Gateway
|
||
|
||
统一的算命网页入口：后端调用 suanming API 获取原始命理数据，再调用 DeepSeek LLM 输出自然语言解读，前端只需请求 `/api/fortune`。
|
||
|
||
## 功能概览
|
||
|
||
- `POST /api/fortune`：校验参数 → 调用 `suanming` → 调用 `DeepSeek` → 返回 `ai_text + raw_suanming`。
|
||
- Express 静态站点：单页表单，包含示例填充、请求状态、AI 文本展示、原始 JSON 展开、免责声明等。
|
||
- Token 自动管理：启动时自动登录获取 Token，过期后自动刷新，无需人工干预。
|
||
- `.env` 控制 suanming、DeepSeek、端口与超时。
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
Suanming-Web/
|
||
├── public/ # 静态前端资源（index.html / styles.css / app.js）
|
||
├── server.js # Express 网关及 API 实现
|
||
├── package.json # 项目依赖
|
||
└── .env # 环境变量配置
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
1. **安装依赖**
|
||
```bash
|
||
cd Suanming-Web
|
||
npm install
|
||
```
|
||
|
||
2. **配置环境变量**
|
||
```bash
|
||
# 创建 .env 文件，填入以下配置
|
||
```
|
||
|
||
```env
|
||
# HTTP 监听端口
|
||
PORT=4173
|
||
|
||
# suanming API 配置
|
||
SUANMING_API_BASE=http://localhost:3001/api
|
||
SUANMING_EMAIL=your-email@example.com
|
||
SUANMING_PASSWORD=your-password
|
||
SUANMING_TIMEOUT_MS=12000
|
||
|
||
# DeepSeek API 配置
|
||
DEEPSEEK_API_KEY=your-deepseek-api-key
|
||
DEEPSEEK_API_URL=https://api.deepseek.com
|
||
DEEPSEEK_MODEL=deepseek-chat
|
||
DEEPSEEK_TIMEOUT_MS=20000
|
||
```
|
||
|
||
3. **启动服务**
|
||
```bash
|
||
npm run dev
|
||
# 浏览器访问 http://localhost:4173
|
||
```
|
||
|
||
4. **PM2 生产部署**
|
||
```bash
|
||
pm2 start server.js --name suanming-web
|
||
pm2 save
|
||
```
|
||
|
||
## API 说明
|
||
|
||
```
|
||
POST /api/fortune
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"type": "bazi",
|
||
"name": "张三",
|
||
"birth_date": "1990-01-01",
|
||
"birth_time": "12:00",
|
||
"gender": "male",
|
||
"is_lunar": false,
|
||
"question": "想了解近期事业与财运",
|
||
"extra_options": { "focus": "career" }
|
||
}
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"ai_text": "DeepSeek 的自然语言解读",
|
||
"raw_suanming": { "...": "原始 suanming JSON" },
|
||
"meta": {
|
||
"type": "bazi",
|
||
"model": "deepseek-chat",
|
||
"elapsed_ms": 2143,
|
||
"warnings": []
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Token 自动管理
|
||
|
||
- **启动预热**：服务启动时自动登录获取 Token
|
||
- **自动刷新**：请求遇到 401 错误时自动刷新 Token 并重试
|
||
- **并发安全**：多个并发请求共用同一个登录 Promise，避免重复登录
|
||
|
||
## 自定义
|
||
|
||
- DeepSeek 调用通过 `openai` SDK 完成，`.env` 中的 `DEEPSEEK_API_URL` 只需设置到根域名（默认 `https://api.deepseek.com`）。
|
||
- 若暂未配置 DeepSeek Key，会返回提示并保留 `raw_suanming`，方便调试。
|
||
- 如需拓展 `name`、`fortune` 等类型，可在 `server.js` 的 `buildSuanmingRequest` 中补充对应 endpoint/payload。
|
||
- 前端使用原生 JS，便于在任何环境下部署，若后续需要组件化框架，可直接复用当前 API。
|
||
|
||
## 免责声明
|
||
|
||
页面底部及 DeepSeek Prompt 均包含"仅供娱乐参考"的提示，请在生产部署时继续保留。
|