@plasosdk/yxt-miniprogram 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @plasosdk/yxt-miniprogram
+
+云学堂嵌入小程序侧能力：打开作业/课堂/课程 web-view，以及板书保存页。
+
+微信不允许 `npm i` 自动注册页面，所以安装后要跑一次 init（改 `app.json`、拷贝页面）。对方不用再零散拷文件。
+
+## 对方接入
+
+在**小程序根目录**（有 `app.json` 的那层）：
+
+```bash
+npm install @plasosdk/yxt-miniprogram
+npx yxt-mp-init
+```
+
+会得到：
+
+- `pages/yxtDownload/`（路径不要改，H5 固定跳这里）
+- `utils/openYxtModule.js`
+- `app.json` 登记该页面，并补上相册权限
+
+然后：
+
+```js
+const { openYxtModule } = require('../../utils/openYxtModule');
+this.setData({
+    src: openYxtModule({ env: 'www', module: 'liveclass', token: token, userid: userid }),
+});
+```
+
+```xml
+<web-view src="{{src}}" bindmessage="onTokenError"></web-view>
+```
+
+升级：再执行一次 `npm update @plasosdk/yxt-miniprogram && npx yxt-mp-init`。
+
+## 对方还要配的（微信后台，init 改不了）
+
+开发 → 开发设置 → 服务器域名：
+
+- **downloadFile 合法域名**、**request 合法域名**：`file.plaso.com`，以及板书图片所在 CDN / OSS
+
+真机预览会校验这些域名；开发者工具需勾选「不校验合法域名、web-view、TLS 版本」。

package/init.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * 在对方小程序根目录执行：npx yxt-mp-init
+ * 会写入 pages/yxtDownload、utils/openYxtModule.js，并改 app.json（pages + 相册权限）。
+ */
+var fs = require('fs');
+var path = require('path');
+
+var PAGE_PATH = 'pages/yxtDownload/yxtDownload';
+var ALBUM_DESC = '用于将课堂板书保存到相册';
+
+function argValue(flag) {
+    var index = process.argv.indexOf(flag);
+    if (index < 0 || !process.argv[index + 1]) {
+        return '';
+    }
+    return process.argv[index + 1];
+}
+
+function findAppRoot(start) {
+    var dir = start;
+    for (var i = 0; i < 10; i++) {
+        if (fs.existsSync(path.join(dir, 'app.json'))) {
+            return dir;
+        }
+        var parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return '';
+}
+
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    fs.readdirSync(src).forEach(function (name) {
+        var from = path.join(src, name);
+        var to = path.join(dest, name);
+        if (fs.statSync(from).isDirectory()) {
+            copyDir(from, to);
+        } else {
+            fs.copyFileSync(from, to);
+        }
+    });
+}
+
+function patchAppJson(appRoot) {
+    var file = path.join(appRoot, 'app.json');
+    var raw = fs.readFileSync(file, 'utf8');
+    var app = JSON.parse(raw);
+    app.pages = app.pages || [];
+    if (app.pages.indexOf(PAGE_PATH) < 0) {
+        app.pages.push(PAGE_PATH);
+    }
+    app.permission = app.permission || {};
+    if (!app.permission['scope.writePhotosAlbum']) {
+        app.permission['scope.writePhotosAlbum'] = { desc: ALBUM_DESC };
+    }
+    fs.writeFileSync(file, JSON.stringify(app, null, 4) + '\n');
+}
+
+var startDir = argValue('--root') || process.cwd();
+var appRoot = findAppRoot(path.resolve(startDir));
+if (!appRoot) {
+    console.error('[yxt-mp-init] 向上找不到 app.json，请在小程序根目录执行 npx yxt-mp-init');
+    process.exit(1);
+}
+
+var pkgRoot = __dirname;
+copyDir(path.join(pkgRoot, 'pages', 'yxtDownload'), path.join(appRoot, 'pages', 'yxtDownload'));
+fs.mkdirSync(path.join(appRoot, 'utils'), { recursive: true });
+fs.copyFileSync(path.join(pkgRoot, 'utils', 'openYxtModule.js'), path.join(appRoot, 'utils', 'openYxtModule.js'));
+patchAppJson(appRoot);
+
+console.log('[yxt-mp-init] 已安装到 ' + appRoot);
+console.log('  - ' + PAGE_PATH);
+console.log('  - utils/openYxtModule.js');
+console.log('  - app.json 已登记页面和相册权限');
+console.log('请在小程序后台配置 downloadFile / request 合法域名：file.plaso.com 以及板书图片 CDN');

package/package.json

@@ -1,6 +1,22 @@
-{
-  "name": "@plasosdk/yxt-miniprogram",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+    "name": "@plasosdk/yxt-miniprogram",
+    "version": "1.0.0",
+    "description": "云学堂小程序嵌入：openYxtModule + 板书下载页。安装后在小程序根目录执行 npx yxt-mp-init",
+    "main": "utils/openYxtModule.js",
+    "bin": {
+        "yxt-mp-init": "./init.js"
+    },
+    "files": [
+        "init.js",
+        "pages",
+        "utils"
+    ],
+    "license": "UNLICENSED",
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "scripts": {
+        "init": "node init.js"
+    }
+}

package/pages/yxtDownload/yxtDownload.js

@@ -0,0 +1,292 @@
+// 第三方小程序请原样拷贝本页，app.json 登记 pages/yxtDownload/yxtDownload（路径不要改）。
+// H5 经 wx.miniProgram.navigateTo 进来：单文件 k+u+n，多图 b+p+n，超长清单 m=manifestUrl。
+// downloadFile 合法域名需包含板书图片 CDN 以及 OSS 加速域名。
+
+function splitPipe(value) {
+    if (!value) {
+        return [];
+    }
+    return String(value).split('|');
+}
+
+/** web-view navigateTo 常常不解码 query，wx.downloadFile 不认 https%3A%2F%2F */
+function decodeHttpUrl(value) {
+    let url = String(value || '');
+    for (let i = 0; i < 3; i++) {
+        if (/^https?:\/\//i.test(url)) {
+            return url;
+        }
+        try {
+            const next = decodeURIComponent(url);
+            if (next === url) {
+                break;
+            }
+            url = next;
+        } catch (error) {
+            break;
+        }
+    }
+    return url;
+}
+
+function parseOptions(options) {
+    options = options || {};
+    if (options.m) {
+        return { manifest: decodeHttpUrl(options.m) };
+    }
+    if (options.b && options.p) {
+        const base = decodeHttpUrl(options.b);
+        const parts = splitPipe(options.p);
+        const names = splitPipe(options.n);
+        return {
+            files: parts.map(function (part, index) {
+                return {
+                    kind: 'image',
+                    url: base + part,
+                    name: names[index] || 'board_' + (index + 1) + '.png',
+                };
+            }),
+        };
+    }
+    if (options.u) {
+        return {
+            files: [
+                {
+                    kind: options.k === 'pdf' ? 'pdf' : 'image',
+                    url: decodeHttpUrl(options.u),
+                    name: options.n || (options.k === 'pdf' ? 'board.pdf' : 'board.png'),
+                },
+            ],
+        };
+    }
+    return { files: [] };
+}
+
+function ensureAlbumAuth() {
+    return new Promise(function (resolve, reject) {
+        wx.getSetting({
+            success: function (res) {
+                const setting = (res && res.authSetting) || {};
+                if (setting['scope.writePhotosAlbum']) {
+                    resolve();
+                    return;
+                }
+                if (setting['scope.writePhotosAlbum'] === false) {
+                    wx.openSetting({
+                        success: function (openRes) {
+                            if (openRes.authSetting && openRes.authSetting['scope.writePhotosAlbum']) {
+                                resolve();
+                            } else {
+                                reject(new Error('no album auth'));
+                            }
+                        },
+                        fail: reject,
+                    });
+                    return;
+                }
+                wx.authorize({
+                    scope: 'scope.writePhotosAlbum',
+                    success: function () {
+                        resolve();
+                    },
+                    fail: reject,
+                });
+            },
+            fail: reject,
+        });
+    });
+}
+
+function downloadToTemp(url) {
+    return new Promise(function (resolve, reject) {
+        if (!url || !/^https:\/\//i.test(url) && !/^http:\/\/(127\.0\.0\.1|localhost)/i.test(url)) {
+            reject({ errMsg: 'downloadFile:fail invalid url ' + String(url || '') });
+            return;
+        }
+        wx.downloadFile({
+            url: url,
+            success: function (res) {
+                if (res.statusCode === 200 && res.tempFilePath) {
+                    resolve(res.tempFilePath);
+                    return;
+                }
+                reject(new Error('download ' + (res.statusCode || 0)));
+            },
+            fail: reject,
+        });
+    });
+}
+
+function saveImage(filePath) {
+    return new Promise(function (resolve, reject) {
+        wx.saveImageToPhotosAlbum({
+            filePath: filePath,
+            success: function () {
+                resolve();
+            },
+            fail: reject,
+        });
+    });
+}
+
+function openPdf(filePath) {
+    return new Promise(function (resolve, reject) {
+        wx.openDocument({
+            filePath: filePath,
+            fileType: 'pdf',
+            showMenu: true,
+            success: function () {
+                resolve();
+            },
+            fail: reject,
+        });
+    });
+}
+
+function readJson(filePath) {
+    return new Promise(function (resolve, reject) {
+        wx.getFileSystemManager().readFile({
+            filePath: filePath,
+            encoding: 'utf8',
+            success: function (res) {
+                try {
+                    resolve(JSON.parse(res.data || '{}'));
+                } catch (error) {
+                    reject({ errMsg: 'json parse fail' });
+                }
+            },
+            fail: reject,
+        });
+    });
+}
+
+function requestJson(url) {
+    return new Promise(function (resolve, reject) {
+        wx.request({
+            url: url,
+            method: 'GET',
+            dataType: 'json',
+            success: function (res) {
+                if (res.statusCode === 200 && res.data) {
+                    resolve(res.data);
+                    return;
+                }
+                reject({ errMsg: 'request status ' + (res.statusCode || 0) });
+            },
+            fail: reject,
+        });
+    });
+}
+
+Page({
+    data: {
+        status: 'loading',
+        hint: '正在准备文件…',
+        files: [],
+    },
+    onLoad(options) {
+        const parsed = parseOptions(options);
+        this._leaveOnSuccess = true;
+        if (parsed.manifest) {
+            this.loadManifest(parsed.manifest);
+            return;
+        }
+        this.begin(parsed.files || []);
+    },
+    loadManifest(url) {
+        const self = this;
+        this._manifestUrl = url;
+        requestJson(url)
+            .catch(function () {
+                return downloadToTemp(url).then(readJson);
+            })
+            .then(function (data) {
+                self.begin((data && data.files) || []);
+            })
+            .catch(function (error) {
+                const msg = String((error && error.errMsg) || error || '');
+                console.error('[yxtDownload] manifest failed', url, error);
+                self.fail('清单下载失败\n' + msg + '\n' + String(url || ''));
+            });
+    },
+    begin(files) {
+        if (!files.length) {
+            this.fail('没有可保存的文件');
+            return;
+        }
+        this.setData({ files: files, hint: '共 ' + files.length + ' 个文件，正在保存…' });
+        this.runSave(files);
+    },
+    onTapSave() {
+        const files = this.data.files || [];
+        if (this._manifestUrl && !files.length) {
+            this.setData({ status: 'loading', hint: '正在准备文件…' });
+            this.loadManifest(this._manifestUrl);
+            return;
+        }
+        if (!files.length) {
+            this.fail('没有可保存的文件');
+            return;
+        }
+        this.setData({ status: 'loading', hint: '正在保存…' });
+        this.runSave(files);
+    },
+    runSave(files) {
+        const self = this;
+        if (!files || !files.length) {
+            this.fail('没有可保存的文件');
+            return;
+        }
+        const hasImage = files.some(function (item) {
+            return item.kind !== 'pdf';
+        });
+        const start = hasImage ? ensureAlbumAuth() : Promise.resolve();
+        start
+            .then(function () {
+                return self.saveAll(files);
+            })
+            .then(function () {
+                const onlyPdf = files.length === 1 && files[0].kind === 'pdf';
+                wx.showToast({ title: onlyPdf ? '已打开文件' : '已保存到相册', icon: 'success' });
+                self.setData({ status: 'done', hint: onlyPdf ? '可在预览里另存' : '已保存到相册' });
+                if (!onlyPdf && self._leaveOnSuccess) {
+                    setTimeout(function () {
+                        wx.navigateBack();
+                    }, 400);
+                }
+            })
+            .catch(function (error) {
+                const msg = String((error && error.errMsg) || error || '');
+                console.error('[yxtDownload] save failed', error, files && files[0] && files[0].url);
+                const needAuth = msg.indexOf('auth') >= 0;
+                const domainFail = msg.indexOf('domain') >= 0 || msg.indexOf('url not in') >= 0;
+                let hint = '保存失败，请点击重试';
+                if (needAuth) {
+                    hint = '需要相册权限才能保存，请点击重试';
+                } else if (domainFail) {
+                    hint = '图片域名未配到 downloadFile 合法域名';
+                }
+                if (msg) {
+                    hint += '\n' + msg;
+                }
+                self.setData({ status: 'error', hint: hint });
+            });
+    },
+    saveAll(files) {
+        let chain = Promise.resolve();
+        files.forEach(function (file) {
+            chain = chain.then(function () {
+                return downloadToTemp(file.url).then(function (filePath) {
+                    if (file.kind === 'pdf') {
+                        return openPdf(filePath);
+                    }
+                    return saveImage(filePath);
+                });
+            });
+        });
+        return chain;
+    },
+    fail(hint) {
+        this.setData({ status: 'error', hint: hint });
+    },
+});

package/pages/yxtDownload/yxtDownload.json

@@ -0,0 +1,4 @@
+{
+    "navigationBarTitleText": "保存板书",
+    "usingComponents": {}
+}

package/pages/yxtDownload/yxtDownload.wxml

@@ -0,0 +1,4 @@
+<view class="wrap">
+    <view class="hint">{{hint}}</view>
+    <button wx:if="{{status === 'error'}}" bindtap="onTapSave" type="primary">重试</button>
+</view>

package/pages/yxtDownload/yxtDownload.wxss

@@ -0,0 +1,13 @@
+.wrap {
+    padding: 80rpx 48rpx;
+    text-align: center;
+}
+
+.hint {
+    margin-bottom: 48rpx;
+    color: #595959;
+    font-size: 28rpx;
+    line-height: 1.6;
+    white-space: pre-wrap;
+    word-break: break-all;
+}

package/utils/openYxtModule.js

@@ -0,0 +1,80 @@
+/**
+ * 第三方小程序嵌入云学堂。推荐装包，不要零散拷文件：
+ *   npm install @plasosdk/yxt-miniprogram
+ *   npx yxt-mp-init
+ * 包目录：./yxt-miniprogram ，发布名为 @plasosdk/yxt-miniprogram
+ *
+ * 对方：
+ *   const { openYxtModule } = require('../../utils/openYxtModule');
+ *   this.setData({ src: openYxtModule({ env: 'dev', module: 'homework', token: token, userid: userid }) });
+ *   <web-view src="{{src}}" bindmessage="onTokenError" />
+ *
+ * module: homework | liveclass | course
+ * env: local | dev | test | itest | ftest | b | www
+ * 换域名时传 origin，不要改 module / appType。
+ *
+ * 板书下载：H5 会 navigateTo('/pages/yxtDownload/yxtDownload?...')。
+ * init 会登记该路径；downloadFile / request 合法域名仍需对方在微信后台配置。
+ */
+var HOSTS = {
+    local: 'http://localhost:9527',
+    dev: 'https://dev.plaso.cn',
+    test: 'https://test.plaso.cn',
+    itest: 'https://itest.plaso.cn',
+    ftest: 'https://ftest.plaso.cn',
+    b: 'https://b.plaso.cn',
+    www: 'https://www.plaso.cn',
+};
+
+var MODULES = {
+    homework: 1,
+    liveclass: 1,
+    course: 1,
+};
+
+function appendQuery(parts, key, value) {
+    if (value === undefined || value === null || value === '') {
+        return;
+    }
+    parts.push(encodeURIComponent(key) + '=' + encodeURIComponent(String(value)));
+}
+
+function openYxtModule(opts) {
+    opts = opts || {};
+    var env = opts.env || 'www';
+    var moduleName = opts.module;
+    var token = opts.token;
+    var userid = opts.userid;
+    var extra = opts.extra || {};
+    var origin = opts.origin || HOSTS[env];
+
+    if (!MODULES[moduleName]) {
+        throw new Error('openYxtModule: module 必须是 homework、liveclass 或 course');
+    }
+    if (!token) {
+        throw new Error('openYxtModule: token 必填');
+    }
+    if (userid === undefined || userid === null || userid === '') {
+        throw new Error('openYxtModule: userid 必填');
+    }
+    if (!origin) {
+        throw new Error('openYxtModule: 未知 env，或自行传入 origin');
+    }
+
+    var parts = [];
+    appendQuery(parts, 'appType', 'mpEmbed');
+    appendQuery(parts, 'module', moduleName);
+    appendQuery(parts, 'token', token);
+    appendQuery(parts, 'userid', userid);
+    Object.keys(extra).forEach(function (key) {
+        appendQuery(parts, key, extra[key]);
+    });
+    if (extra.withBack === undefined) {
+        appendQuery(parts, 'withBack', '0');
+    }
+
+    var path = env === 'local' ? '/?' : '/static/yxt/?';
+    return origin.replace(/\/$/, '') + path + parts.join('&');
+}
+
+module.exports = { openYxtModule, HOSTS, MODULES };