@xiangyang9999/folib-server-scan-export-sync 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @xiangyang9999/folib-server-scan-export-sync
 
-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.
+`folib-server` 扫描报告异步/定时导出功能的**离线手工同步资料包**，用于受网络限制、只能手工输入代码的环境。**不是可直接加载到 folib-server 的业务功能插件**。
+
+- 来源 Git 提交：`a28ada525f48cf8b6ea3024d4f3eda83cc6d358a`
+- 仅包含该提交的相关变更；已排除 `tools/scan-export/` 全目录。
+- 涉及 50 个文件，保留原目录结构。
+- 安装或运行此包不会修改 `folib-server` 项目文件。
+
+## 包内文件
+
+| 包内路径 | 说明 |
+| --- | --- |
+| `payload/内网手工同步修改说明.docx` | Word 逐文件手敲说明：新增文件完整代码、现有文件的精确差异、同步顺序及检查项 |
+| `payload/涉及文件_按原路径.zip` | 50 个提交版本文件，另附文件清单；保持原有项目路径 |
+| `payload/完整变更补丁_供核对.patch` | 该提交相对父提交的完整变更，用于差异比对 |
+
+## 安装和提取
+
+使用 npm 包内命令，将三个资料文件复制到任意输出目录。**只复制资料，不直接把代码覆盖到项目中。**
+
+```bash
+# 已发布到可访问的 npm 仓库后：
+npx --yes --package @xiangyang9999/folib-server-scan-export-sync folib-scan-export-sync extract ./folib-sync
+
+# 或先安装，再执行：
+npm install @xiangyang9999/folib-server-scan-export-sync
+npx folib-scan-export-sync list
+npx folib-scan-export-sync extract ./folib-sync
+```
+
+命令默认不覆盖目标目录中已经存在的文件。如果需要覆盖，请显式加 `--force`：
+
+```bash
+npx folib-scan-export-sync extract ./folib-sync --force
+```
+
+在不能联网的机器上，也可将生成的 `.tgz` 拷贝进去，然后：
+
+```bash
+npm install ./xiangyang9999-folib-server-scan-export-sync-1.0.0.tgz
+npx folib-scan-export-sync extract ./folib-sync
+```
+
+## 发布到 npm 仓库（需要拥有对应 scope 的发布权限）
+
+在 **`npm-package` 目录** 内执行：
+
+```bash
+npm pack --dry-run
+npm pack
+```
+
+**优先使用内网私有 npm Registry**（例如公司已有的 npm 仓库，示例 URL 请替换）：
+
+```bash
+npm login --registry=https://npm.example.internal/
+npm publish --registry=https://npm.example.internal/
+```
+
+如果已经取得源码公开分发授权、确实打算发布到公开的 npmjs.com，才运行：
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+**重要提醒：本包包含项目源码及其修改差异。发布到公开 npm Registry 后，包内容可被任何人下载。发布前请确认源码授权、内部地址、凭据及其他敏感信息均允许分发。** 不要把 `--access public` 当作普通内网发布参数。
+
+更新源代码资料后，应同步更新 `payload/` 文件，修改 `package.json` 的 `version`，再重新打包发布；npm 不能覆盖已发布的同名同版本。
+
+## 手工同步顺序
+
+1. 按 Word 文档先处理数据库 Liquibase 变更和后端 Repository/Adapter。
+2. 录入后端 `export/`、Mapper、Controller 等新增文件及原代码修改。
+3. 录入前端 API、组件、国际化和页面修改。
+4. 对照 `.patch` 和 ZIP 源文件，核查手敲代码。
+5. 在内网独立进行编译、数据库迁移、权限和导出功能验证。
+
+本包只对源提交内容作离线整理，**不保证内网目标代码版本兼容，也不代表已经通过项目集成测试**。

package/bin/folib-scan-export-sync.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const files = [
+  '内网手工同步修改说明.docx',
+  '涉及文件_按原路径.zip',
+  '完整变更补丁_供核对.patch',
+];
+
+const sourceDir = path.resolve(__dirname, '..', 'payload');
+const args = process.argv.slice(2);
+
+function usage() {
+  process.stdout.write(
+    '用法:\n' +
+    '  folib-scan-export-sync list\n' +
+    '  folib-scan-export-sync extract <输出目录> [--force]\n' +
+    '  folib-scan-export-sync --help\n\n' +
+    'extract 只复制手工同步资料，默认拒绝覆盖已有文件。\n'
+  );
+}
+
+function main() {
+  const command = args[0] || '--help';
+  if (command === '--help' || command === '-h' || command === 'help') {
+    usage();
+    return;
+  }
+
+  for (const file of files) {
+    const src = path.join(sourceDir, file);
+    if (!fs.statSync(src).isFile()) {
+      throw new Error('缺少包内文件: ' + src);
+    }
+  }
+
+  if (command === 'list') {
+    for (const file of files) {
+      const bytes = fs.statSync(path.join(sourceDir, file)).size;
+      process.stdout.write(file + ' (' + bytes + ' bytes)\n');
+    }
+    return;
+  }
+
+  if (command !== 'extract' || !args[1] || args.some((a, i) => i >= 2 && a !== '--force')) {
+    usage();
+    process.exitCode = 2;
+    return;
+  }
+
+  const force = args.includes('--force');
+  const outDir = path.resolve(args[1]);
+  const targets = files.map((file) => ({ src: path.join(sourceDir, file), dst: path.join(outDir, file) }));
+
+  if (!force) {
+    const existing = targets.filter(({ dst }) => fs.existsSync(dst));
+    if (existing.length > 0) {
+      throw new Error('为避免覆盖，已停止。目标文件已存在: ' + existing.map(({ dst }) => dst).join(', ') + '；需要覆盖时加 --force');
+    }
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+  for (const { src, dst } of targets) {
+    fs.copyFileSync(src, dst, force ? 0 : fs.constants.COPYFILE_EXCL);
+    process.stdout.write('已复制: ' + dst + '\n');
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  process.stderr.write('错误: ' + err.message + '\n');
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@xiangyang9999/folib-server-scan-export-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Offline manual-sync bundle for folib-server artifact scan report export commit a28ada52 (Word, source archive and diff).",
+  "license": "UNLICENSED",
+  "bin": {
+    "folib-scan-export-sync": "./bin/folib-scan-export-sync.js"
+  },
+  "files": [
+    "bin/",
+    "payload/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "folib-server",
+    "scan-export",
+    "offline-sync",
+    "manual-migration",
+    "internal-code"
+  ]
+}