# markdown

**Repository Path**: 3433/markdown

## Basic Information

- **Project Name**: markdown
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown 微信分享阅读工具

AI 生成的 `.md` 文件在微信中转发后对方无法直接阅读。本工具提供：微信扫码/静默登录 → 上传 `.md` → 生成分享链接 → 微信内一键卡片式分享 → 服务端渲染 GitHub 风格阅读页。

详细需求见 [SPEC.md](./SPEC.md)。

## 技术栈

| 层 | 选型 |
|----|------|
| 后端 | webman (PHP / Workerman 常驻内存) + think-orm + MySQL |
| 微信 SDK | w7corp/easywechat v6（EasyWeChat 6） |
| Markdown | league/commonmark（GFM）服务端渲染 + highlight.js（CDN） |
| 前端 | uni-app H5（Vue3 + TS + Vite） |

## 目录结构

```
markdown/
├── server/                 # webman 后端
│   ├── app/
│   │   ├── controller/      # Auth / WechatServer / File / View / OgImage
│   │   ├── model/           # User / File / ReadLog
│   │   ├── service/         # Wechat / Jwt / Url / File / MarkdownRenderer / storage/*
│   │   ├── middleware/      # JwtAuth
│   │   ├── process/         # ExpireCleaner 定时清理
│   │   └── view/            # SSR 阅读页 read/expired/notfound.html
│   ├── config/              # think-orm / app_custom / wechat / route / process
│   ├── database/schema.sql  # 建表脚本
│   └── .env                 # 后端配置（微信/DB/JWT/存储）
├── web/                    # uni-app H5 前端
│   └── src/
│       ├── api/             # 接口封装
│       ├── store/           # 用户状态
│       └── pages/           # index(登录+上传) / list / settings
└── deploy/nginx.conf.example
```

## 快速开始

### 1. 数据库

```bash
mysql -uroot < server/database/schema.sql   # 建库 md_viewer + 三张表
```

### 2. 后端配置

编辑 `server/.env`：

- `WECHAT_APP_ID` / `WECHAT_APP_SECRET`：公众号凭证
- `WECHAT_OPEN_APP_ID` / `WECHAT_OPEN_APP_SECRET`：**可选**，配了走开放平台 snsapi_login 扫码；不配则回退「公众号带参二维码 + 轮询」
- `WECHAT_TOKEN`：公众号消息服务器 Token（带参二维码扫码登录需要）
- `DB_MYSQL_*`：数据库连接
- `JWT_SECRET`：**务必改为随机串**
- `APP_BASE_URL`：主域名；`APP_OAUTH_URL`：授权域名（见下）
- `STORAGE_DRIVER`：`local`（前期仅实现本地磁盘）

### 3. 启动后端

```bash
cd server
php start.php start        # 调试；生产用 php start.php start -d
# 监听 0.0.0.0:8787，含 expire-cleaner 定时清理进程
```

### 4. 构建前端

```bash
cd web
npm run build:h5           # 产物在 web/dist/build/h5
# 联调可用 npm run dev:h5（api/index.ts 中 BASE 自动指向 127.0.0.1:8787）
```

### 5. 部署

参考 `deploy/nginx.conf.example`：
- 前端 H5 产物由 nginx 在主域名根目录直出
- `/v/`、`/api/`、`/oauth/` 反代到 webman:8787

## 授权域名反代（核心约束）

当公众号已配置的「网页授权域名」被其它项目占用时，无需改动该项目：在其 nginx 配置里把 `/oauth/` 反代到本服务即可复用授权。

- `APP_OAUTH_URL=https://www.hjuyun.com/oauth` → 授权回调走授权域名，nginx 再反代回 webman
- 留空 → 授权回退到主域名 `APP_BASE_URL/oauth`

微信公众号后台「网页授权域名 / JS 接口安全域名」填写实际承载回调的域名（配了授权域名则填授权域名，否则填主域名）。

## 关键设计

- **去重**：同一用户上传相同 sha256 内容复用原 `file_key`（`files.uk_user_hash` 唯一索引）
- **存储抽象**：`app/service/storage/`，`StorageManager` 按 `STORAGE_DRIVER` 切换；`Db`/`Oss` 已留接口占位
- **微信凭证缓存**：access_token / jsapi_ticket 由 Symfony FilesystemAdapter 持久化到 `runtime/easywechat`，常驻进程共享
- **OG 卡片图**：`/api/og-image` 用 gd 绘制渐变 + 中文标题 PNG，按 title hash 缓存到 `runtime/og`