feat: initial public release

docs/deployment.md

@@ -0,0 +1,150 @@
+# 部署与分发
+
+## 服务器形态
+
+统一网关是一个小型 Node.js 服务，监听 `127.0.0.1:3010`，由 Nginx 提供 HTTPS。它只调用钉钉与薪福通 API，不运行浏览器，通常 1 核 CPU、512 MB–1 GB 内存即可。
+
+需要：
+
+- Node.js 22.13+；
+- Nginx、Certbot 和固定域名；
+- 一个专用钉钉企业内部应用；
+- 薪福通正式 OpenAPI 应用。
+
+钉钉应用 OAuth 回调：
+
+```text
+https://approval.justconn.top/oauth/dingtalk/callback
+```
+
+钉钉应用需要用户登录/身份、通讯录个人信息读取（用于实时取得当前用户所属部门）、OA 审批待办与已处理工作记录、本人发起实例 ID、实例详情、模板 Schema、审批处理和发起实例所需权限。
+
+薪福通除已有的用户映射、本人待办、单据详情、审批历史和 pass/reject/back 权限外，发起审批还需要一次性开通：
+
+- `xft-member/openapi/xft-member/member/get/by-id`（查询企业成员详情，用于由当前登录身份安全取得本人花名册员工号）；
+- `itrip-gateway/v1/form/query-event-list`；
+- `itrip-gateway/v1/form/customFields/eventSeqId/{eventSeqId}`；
+- `itrip-gateway/v1/approve/recall`（单据撤回）；
+- `itrip-gateway/v1/bills/apply/travel/create`；
+- `itrip-gateway/v1/bills/apply/expense/create`；
+- `itrip-gateway/v1/bills/apply/entertainment/create`；
+- `itrip-gateway/v1/bills/apply/common/create`；
+- `itrip-gateway/v1/bills/apply/use-car/create`；
+- `itrip-gateway/v1/reimburse/bill/create`；
+- `itrip-gateway/v1/reimburse/bill/travel/create`。
+
+统一历史查询还会使用已开通的 `itrip-gateway/v1/bills/queryBillByCondition`（本人发起单据）和 `itrip-gateway/v1/bills/bill-list`（精简列表信息）。两者必须保留权限校验；`empId` 只能由网关从当前登录用户的成员档案派生。
+
+创建接口必须保持权限校验开启。网关统一提交 `APPRV_PEND`，并在写后实时读取本人单据状态：进入待审批时提供撤回引用；按企业流程规则即时通过时返回 `completed`，不提供撤回引用且禁止重复提交。
+
+`1.1.0-rc.8` 中薪福通撤回仍标记为实验能力：权限和调用契约已接通，但当前企业真实请求返回 `XFTSYS9999`，尚未取得成功样本。网关会写后复核并禁止自动重试。面向试用用户时必须保留这一说明；若业务要求撤回必须稳定可用，应等待薪福通定位后再升级为正式能力。
+
+## 首次凭证配置
+
+把钉钉 AppKey/AppSecret 保存为权限 `0600` 的 `.secrets/dingtalk.json`，把薪福通 AuthoritySecret 保存为权限 `0600` 的密钥文件。然后运行一次：
+
+```bash
+npm ci
+npm run build
+
+node dist/src/admin.js service configure \
+  --public-base-url https://approval.justconn.top \
+  --corp-id YOUR_CORP_ID \
+  --credentials-file .secrets/dingtalk.json \
+  --xft-open-api-app-id YOUR_XFT_APP_ID \
+  --xft-open-api-secret-file .secrets/xft-open-api.secret \
+  --xft-open-api-enterprise-id YOUR_XFT_ENTERPRISE_ID \
+  --port 3010
+```
+
+不要把这些企业凭证发给终端用户。
+
+`MCP_SESSION_SECRET_FILE` 与 `MCP_APPROVAL_REF_SECRET_FILE` 由管理命令生成，内容至少 32 字节且权限必须为 `0600`（或更严格）。手工配置环境变量时同样强制至少 32 字节；缺失时网关拒绝启动，不再临时生成会导致重启后引用失效的随机密钥。`MCP_PUBLIC_BASE_URL` 必须是无内嵌凭证、无额外路径/query/hash 的 HTTPS origin，端口范围为 1–65535。
+
+## 一键安装和更新
+
+首次发布还需要生成一对 Ed25519 发布密钥：
+
+```bash
+npm run release:keygen
+```
+
+私钥保存在 `.secrets/release-signing-private.pem`（`0600`），必须离线备份且禁止提交、复制到 Web 目录或提供给网关进程；公钥位于 `distribution/release-signing-public.pem` 并随客户端发布。密钥已经存在时脚本会拒绝覆盖，轮换必须另行设计交叉签名迁移，不能直接替换。
+
+首次配置完成后，每次安装、升级或 Bug 修复统一执行：
+
+```bash
+cd /path/to/dingMCP
+./deploy/install.sh
+```
+
+脚本自动测试、构建、用 Ed25519 私钥签署 schema v3 清单、重启服务、原子发布静态文件、安装 Nginx 配置并验证公网健康检查、OAuth 元数据和安装链接。首次签证书时，临时 HTTP 配置只开放 ACME challenge，其余请求返回 403；不会在明文 HTTP 上代理 OAuth、Token 或 MCP。证书通过 Certbot webroot 模式签发，正式配置启用 HTTPS 跳转与不带 `includeSubDomains` 的 HSTS。已有证书会自动复用；签名私钥缺失、权限不是 `0600` 或与固定公钥不匹配时发行会失败。
+
+发行物先复制到独立 staging 目录，再通过符号链接原子切换；客户端不会看到新清单配旧 artifact 的中间状态。服务器保留当前版本和最近两个旧版本用于排障，较老版本自动清理。`install.md`、清单、签名、安装器、Skill、校验文件和测试包均以 `no-cache` 提供；内容寻址的客户端 tgz 才使用 immutable 缓存。签名清单的 `createdAt` 超过 180 天时客户端拒绝安装，避免旧签名版本冻结攻击。
+
+卸载：
+
+```bash
+./deploy/uninstall.sh
+```
+
+这是服务器卸载命令，不是终端用户插件卸载。它默认保留凭证、OAuth 数据库和 Let's Encrypt 证书，重新安装无需重新录入企业密钥。自动化环境可使用 `./deploy/uninstall.sh --yes`。
+
+## 用户分发
+
+部署脚本会生成：
+
+```text
+release/
+├── install.md
+├── manifest.json
+├── manifest.sig
+├── SHA256SUMS
+├── dingtalk-approval-installer.mjs
+├── release-signing-public.pem
+├── dingtalk-approval-client-*.tgz
+├── dingtalk-approval-SKILL.md
+├── dingmcp-test-bundle.tar.gz
+└── agent-test-install.md
+```
+
+终端用户只需要把下面链接发给自己的 Agent：
+
+```text
+https://approval.justconn.top/downloads/dingmcp/install.md
+```
+
+Agent 只需校验安装器和公钥 SHA-256，再调用原生安装器。安装器验证 `manifest.sig` 和全部 artifact 哈希，将内置运行依赖的客户端以 npm 离线模式安装到稳定用户目录并返回标准 MCP 配置；终端安装过程不会从 npm registry 下载额外代码。Bridge 的稳定绝对路径不会包含 NVM 的具体 Node 版本，配置也不再携带 `--url`；网关地址由受签名保护的安装状态提供。
+
+安装器对每个下载设置 30 秒超时，并在流式读取时执行 25 MB 硬上限，不会先把无界响应完整缓冲到内存。Windows 必须能定位由当前 Node 安全启动的 `npm-cli.js`；不会退回到受 Node 安全加固影响的 `npm.cmd` 隐式执行。
+
+安装器不会识别 Agent 品牌或直接修改其配置。所有 Agent 都使用返回的 `skillPath` 和标准 `mcpConfig`，按自身官方方式安装 Skill、注册并信任名为 `dingtalk-approval` 的本地 stdio MCP；不能热加载连接器时再新建会话或重启。
+
+安装器在返回前通过已安装 Bridge 主动准备登录，并在 JSON 的 `postInstall` 中返回 `authenticated`、`authorization_required` 或 `unavailable`。Agent 必须立即显示其中的短期 `directUrl`，不得等待首次审批请求；网页授权后调用 `approval_login`，再按 `verifyTool` 用 `source=all` 做双来源只读验证。首次认证成功会返回一次性 onboarding 示例，普通文本宿主也可见。登录准备失败不回滚安装，且整个流程不提交 consent、不读取审批、不执行写操作。
+
+安装后可用稳定 CLI 自检或提取配置：`print-path bridge` 默认只输出路径，`print-config --format mcp-json` 输出可直接消费的标准 MCP JSON，`doctor --json` 同时检查 Node、npm、运行时、Skill、公钥和网关配置。后续更新直接执行安装结果中 `cliPath` 对应的 `update --json`，它会复用已固定的签名清单地址和本地公钥，并保留 OAuth 会话。更新完成后应重新连接该 MCP；Agent 不能单独重启连接器时，再新建会话或重启。
+
+客户端卸载使用安装结果返回的 `cliPath uninstall --yes --json`，默认删除 OAuth 会话，并安全清理由旧版手工删除留下的四个 npm 入口；只会删除名称精确匹配且目标属于 `dingtalk-approval-mcp` 的链接或 Windows shim。
+
+## 运维检查
+
+```bash
+systemctl --user status dingtalk-approval-mcp.service
+curl --fail http://127.0.0.1:3010/healthz
+curl --fail https://approval.justconn.top/healthz
+curl --fail https://approval.justconn.top/downloads/dingmcp/manifest.json
+curl --fail https://approval.justconn.top/downloads/dingmcp/manifest.sig
+```
+
+备份时必须把 `.runtime/auth.sqlite`、同路径派生的 `.runtime/auth.sqlite.invoice-dedup.sqlite` 与 `.secrets/oauth-session.key` 一并迁移。发票查重库只含不可逆 HMAC 和最小状态元数据；审批正文不落库，不需要备份。
+
+每个候选版和正式版发布前执行 [发布检查清单](release-checklist.md)。
+
+只读 E2E 脚本没有生产默认地址，也不会自动挑选第一张审批：
+
+```bash
+DINGTALK_APPROVAL_MCP_URL=https://staging.example.com/mcp \
+  node scripts/e2e-approval-mcp.mjs dingtalk
+```
+
+读取指定单据时加 `--business-no EXACT`。只有已取得真实写入授权时，才可再加 `--execute-real-write`；脚本要求精确业务编号，并在写后重新列待办复核。任何 `outcome_uncertain` 均不得重试。