# fupan_server

**Repository Path**: kaikingg/fupan_server

## Basic Information

- **Project Name**: fupan_server
- **Description**: A股复盘-后端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ashare-backend

A股复盘后端服务，基于 Node.js + Express + SQLite（better-sqlite3，同步 API），ES Modules。

## 目录结构

```
ashare-backend/
├── app.js                    # Express 入口（中间件 + 启动 + 优雅关闭）
├── config/                   # 环境变量配置（环境变量优先，缺省值兜底）
├── db/                       # SQLite 连接管理 + schema.sql（核心表 DDL）
├── models/                   # 数据访问层：每张表一个 model
├── controllers/              # 业务逻辑：请求校验 → 调 model → 组装响应
├── routes/                   # 路由集中注册（含 notification / user-admin 子路由）
├── middleware/               # auth.js / publish-auth.js / bridge-auth.js
├── ws/                       # WebSocket 服务（ws-server.js）
├── services/                 # 后台任务（news-service 定时抓取资讯）
├── utils/                    # html-generator / publish-bridge / bridge-guard / jwt-service 等
├── scripts/                  # migrate.js / seed.js / migrate-notification.js 等
└── public/                   # 静态资源（头像上传目录）
```

架构约定：**routes 只做路由与鉴权注册，controllers 做业务，models 做数据**。新增功能遵循同一分层。

## 常用命令

| 命令 | 说明 |
|------|------|
| `npm install` | 安装依赖 |
| `npm run migrate` | 建核心表（幂等，schema 在 `db/schema.sql`） |
| `npm run seed` | 导入种子数据 |
| `npm start` | 启动服务（默认端口 3210） |
| `npm run dev` | 开发模式（`node --watch` 热重载） |
| `node scripts/migrate-notification.js` | 建系统通知表 |
| `node scripts/migrate-ws-push-schedule.js` | 建 WS 推送调度表 |
| `node scripts/migrate-desktop.js` | 建桌面组件/布局表 |

## 数据库

### 表清单

| 模块 | 表名 | 用途 |
|------|------|------|
| 复盘核心 | daily_review | 每日复盘主表（review_date 为主键，级联删除子表） |
| 复盘核心 | index_quote | 指数行情（上证/深证/创业板/科创50/沪深300/北证50） |
| 复盘核心 | sector_quote | 板块行情（领涨/领跌，含驱动逻辑） |
| 复盘核心 | fund_flow | 资金流向（主力净流入/流出，含个股备注） |
| 复盘核心 | hot_topic | 热点分析（标题+正文） |
| 复盘核心 | outlook | 明日展望（总体判断+关注要点） |
| 复盘核心 | publish_log | 发布日志（请求/响应/HTTP状态） |
| 桥接 | bridge_message | 搭子/龙虾双向通信消息 |
| 桥接 | bridge_log | 桥接请求日志 |
| 用户 | user | 用户（手机号/邮箱/密码/昵称/头像/角色） |
| 用户 | sms_code | 短信验证码 |
| 用户 | user_sector | 用户关注板块 |
| 用户 | user_stock | 用户自选股 |
| 资讯 | news_item | 新闻资讯 |
| 资讯 | user_news_read | 用户新闻已读记录 |
| 系统通知 | system_notification | 系统公告（类型/状态/置顶/受众过滤） |
| 系统通知 | user_notification_read | 用户通知已读记录 |
| WS 推送 | ws_push_schedule | 各频道推送开关（交易时段/非交易时段/休盘日） |
| 桌面 | desktop_component | 桌面组件注册表 |
| 桌面 | user_desktop_layout | 用户桌面布局（user_id=0 为全局默认） |

### 维护规则

- 核心表写在 `db/schema.sql`，用 `npm run migrate` 建表；系统通知、WS 推送调度、桌面表由各自 `scripts/migrate-*.js` 迁移脚本建表。
- 新增表先写进 schema/迁移脚本，再执行建表；不要直接对 SQLite 文件手改。
- 所有 `created_at` / `updated_at` 默认 `datetime('now','+8 hours')`（北京时间）。

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| ASHARE_PORT | 3210 | 服务端口 |
| ASHARE_HOST | 127.0.0.1 | 监听地址（本机监听，对外走 8099 反代） |
| ASHARE_DB_PATH | ./db/ashare.db | SQLite 文件路径 |
| PUBLISH_URL | http://106.52.4.93:8099/ | 发布服务器地址 |
| PUBLISH_PUBLIC_URL | https://fupan.kaiking.top | 复盘公网地址 |
| PUBLISH_TOKEN | (空) | 发布接口 token，必须通过环境变量注入 |
| PUBLISH_TIMEOUT | 60000 | 发布超时（毫秒） |
| JWT_SECRET | (开发默认值) | 用户 JWT 签名密钥，生产环境必须覆盖 |
| BRIDGE_DUMATE_TOKEN | (空) | 搭子桥接 token |
| BRIDGE_LOBSTER_TOKEN | (空) | 龙虾桥接 token |
| OPENCLAW_URL | http://127.0.0.1:36544 | OpenClaw 网关（本机回环，不暴露公网） |
| OPENCLAW_TOKEN | (空) | OpenClaw 网关 token |
| BRIDGE_TIMEOUT | 120000 | 桥接超时（毫秒） |
| BRIDGE_MAX_MSG | 4096 | 桥接消息最大长度 |
| BRIDGE_RATE_LIMIT | 10 | 桥接接口限流（次/分钟） |
| ALIYUN_SMS_ACCESS_KEY_ID | (空) | 阿里云短信 AccessKeyId |
| ALIYUN_SMS_ACCESS_KEY_SECRET | (空) | 阿里云短信 AccessKeySecret |
| ALIYUN_SMS_SIGN_NAME | A股复盘 | 短信签名 |
| ALIYUN_SMS_TEMPLATE_CODE | (空) | 短信模板 Code |
| ASK_AI_URL / ASK_AI_TOKEN | - | ask-ai 相关，当前停用 |

## API 接口

各接口的鉴权规则（token 类型、中间件、有效期）见 [AGENTS.md](AGENTS.md)「鉴权模型」，下表「鉴权」列为简要标注。

### 复盘

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | /api/reviews | 发布 token | 创建/更新复盘（含子表） |
| GET | /api/reviews | 公开 | 复盘列表（分页） |
| GET | /api/reviews/batch | 公开 | 批量摘要 |
| GET | /api/reviews/detail?date= | 公开 | 查询完整复盘（含所有子表） |
| DELETE | /api/reviews/detail?date= | 发布 token | 删除复盘（级联） |
| POST | /api/reviews/publish | 发布 token | 生成 HTML 并推送到 8099 |

子表（PUT 需发布 token，GET 公开）：GET 传 `?date=`，PUT 在 body 带 `date`。路径为 `/api/reviews/indexQuotes` / `sectorQuotes` / `fundFlows` / `hotTopics` / `outlooks` / `publishLogs`。

#### POST /api/reviews 请求体示例

```json
{
  "reviewDate": "2026-08-05",
  "title": "A股复盘 2026-08-05",
  "digest": "科创50暴涨4.78%，半导体材料全线爆发",
  "overview": "8月5日A股三大指数集体低开高走...",
  "totalVolume": 26799,
  "volumeChange": 4514,
  "advanceCount": 3725,
  "declineCount": 1621,
  "limitUpCount": 104,
  "limitDownCount": 1,
  "northboundNet": 210,
  "mainForceNet": 780,
  "marketSentiment": "回暖",
  "indexQuotes": [
    {"indexName": "上证指数", "closePrice": 3878.43, "changePct": 1.47, "turnover": 12087, "sortOrder": 1}
  ],
  "sectorQuotes": [
    {"sectorName": "电子", "direction": "up", "changePct": 5.66, "driver": "半导体材料爆发", "sortOrder": 1}
  ],
  "fundFlows": [
    {"direction": "inflow", "target": "电子板块", "amount": 284, "note": "工业富联净买入35亿", "sortOrder": 1}
  ],
  "hotTopics": [
    {"title": "1. 半导体材料", "content": "今日最强方向...", "sortOrder": 1}
  ],
  "outlooks": [
    {"summary": "预计震荡分化", "focusPoint": "1. 量能持续性...", "sortOrder": 1}
  ]
}
```

#### POST /api/reviews/publish

```json
{"date": "2026-08-05", "previewOnly": true}
```

自动从数据库读取结构化数据 → 生成 HTML → 推送到 8099 发布接口。

### 认证 / 用户

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | /api/auth/send-code | 限流 | 发送短信验证码 |
| POST | /api/auth/register | 公开 | 手机号注册 |
| POST | /api/auth/login | 公开 | 手机号登录 |
| POST | /api/auth/email/register | 公开 | 邮箱注册 |
| POST | /api/auth/email/login | 公开 | 邮箱登录 |
| GET / PUT | /api/auth/profile | 登录 | 获取/更新个人信息 |
| POST | /api/auth/avatar | 登录 | 上传头像 |
| POST | /api/auth/email/change-password | 登录 | 修改密码 |

### 自选股 / 股票行情 / 关注板块（均需登录）

- 自选股：`GET/POST /api/stocks`、`PUT /api/stocks/update`、`DELETE /api/stocks/remove?id=`、`POST /api/stocks/remove-by-code`、`GET /api/stocks/groups`、`POST /api/stocks/batch-sort`
- 行情：`GET /api/stocks/search`、`GET /api/stocks/getStockQuotes`、`GET /api/stocks/quote?code=`、`GET /api/stocks/klines?code=`、`GET /api/stocks/trends?code=`
- 交易日检查：`GET /api/market/trading-day`（公开）
- 关注板块：`GET/POST /api/sectors`、`DELETE /api/sectors/remove?id=`、`POST /api/sectors/remove-by-name`、`GET /api/sectors/check`

### 资讯

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET | /api/news | 公开 | 资讯列表 |
| GET | /api/news/categories | 公开 | 分类列表 |
| GET | /api/news/detail?id= | 公开 | 资讯详情 |
| POST / PUT / DELETE | /api/news、/update、/remove | 发布 token | 管理接口（暂用发布侧 token，body 带 id） |
| POST | /api/news/read | 登录 | 标记已读 |
| GET | /api/news/unread-count | 登录 | 未读数 |

### 桥接

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | /api/bridge/leave-message | authDumate | 搭子 → 龙虾 异步留言 |
| POST | /api/bridge/notify | authLobster | 龙虾 → 搭子 推送通知 |
| GET | /api/bridge/notify | authDumate | 搭子拉取待处理消息 |
| GET | /api/bridge/messages | authDumate | 通信历史 |
| GET | /api/bridge/logs | authDumate | 审计日志 |

### 桌面布局 / 系统通知 / 超管

- 桌面：`GET /api/desktop/components`、`GET /api/desktop/layout`（公开）；`POST / DELETE /api/desktop/layout`（登录）
- 系统通知（公开只读）：`GET /api/notifications`、`GET /api/notifications/unread-count`；登录：`POST /api/notifications/read-all`、`POST /api/notifications/read`；超管 CRUD：`POST /api/notifications/admin`、`GET /api/notifications/admin/detail?id=`、`PUT /api/notifications/admin/update`、`DELETE /api/notifications/admin/remove?id=`
- 用户管理（超管）：`GET /api/users/admin`、`GET /api/users/admin/detail?id=`、`PUT /api/users/admin/update`、`PUT /api/users/admin/changeRole`、`PUT /api/users/admin/resetPassword`
- WS 推送调度（超管）：`GET /api/admin/ws-push`、`PUT /api/admin/ws-push`（body 带 channel）
- 健康检查：`GET /api/health`

## 与云服务器AI的通信

`/ask-ai` 与 `/bridge/ask` 接口均已停用（路由不注册、注释保留）。原因是底层 chatCompletions 有路由 bug，指定 agent 会实际跑默认 agent（全工具权限）。

此为 [AGENTS.md](AGENTS.md)「安全红线」维护的结论，勿重新启用；除非有正确的安全修复方案（如全局 `tools.deny`）。恢复前只走发布接口 `POST http://106.52.4.93:8099/`。