@oj-module/cli 0.2.66 → 0.2.67

package/bin/.oj-version

@@ -0,0 +1 @@
+v0.1.123

package/bin/oj

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/bin/oj
+size: 126034368 bytes
+sha256: 6774d629abecdd96a84bed71ed220ce85ae46bbbe9a818819eca87a5b5d50be6

package/devkit/README.md

@@ -1,15 +1,22 @@
 # oj-module DevKit——模块开发手册 + agent skill
 
+> **你在哪读这份文件？** 两种视图，内容同一份：
+> - **业务工程里**（`.claude/skills/ojm-module-dev/`）：文件是随 `@oj-module/cli` 分发的**副本**，
+>   直接读 `SKILL.md` / `manual.md` / 两本企微手册 / `publish-walkthrough.md` 即可闭环；
+>   下文出现的 `docs/devkit/`、`packages/cli/` 是**框架仓库路径**，只用来解释文件怎么来的，
+>   你本地没有也不影响使用。
+> - **框架仓库里**（`docs/devkit/`）：这里才是源文件，改文档只改这一处。
+
 面向用 `ojm` 开发前后端一体工程的开发者与 AI agent。本目录是**源文件**，
 发布时由 cli 的 `prepack`（`packages/cli/scripts/sync-devkit.mjs`）把其中
-**ojm 侧的 10 个文件**同步进 `packages/cli/devkit/`，随 `@oj-module/cli`
+**ojm 侧的 11 个文件**同步进 `packages/cli/devkit/`，随 `@oj-module/cli`
 发布，再由 `ojm init` 分发到工程内。
 
 整棵树覆盖前后端两侧，但仍是**两套独立分发的 skill**（同名不同物，别混）：
 
 | 侧 | 本仓位置 | 用户工程里的落点 | 分发链 |
 |---|---|---|---|
-| ojm 模块开发（前端模块、契约、前后端对接） | 本目录顶层 10 个文件 | `.claude/skills/ojm-module-dev/` | `@oj-module/cli` 包（全部 10 个）→ `ojm init` 第 4b 步（只分发其中 6 个，见下） |
+| ojm 模块开发（前端模块、契约、前后端对接） | 本目录顶层 11 个文件 | `.claude/skills/ojm-module-dev/` | `@oj-module/cli` 包（全部 11 个）→ `ojm init` 第 4b 步（只分发其中 6 个，见下） |
 | oj API 开发（后端 handler、全局对象、配置、测试） | `oj-api-dev/` 子目录（快照） | `.claude/skills/oj-api-dev/` | **oj 二进制自带**（`bin/devkit/`）→ `ojm init` 第 4 步 / `ojm vendor` 装·升后同步（0.2.57 起共用 `syncOjDevkit`，全量 `.md` **覆盖**——文档始终与已装 oj 版本一致） |
 
 > **`oj-api-dev/` 子目录是快照，不是本仓维护的文档**：它与本机 oj 的
@@ -25,19 +32,20 @@
 |---|---|
 | `SKILL.md` | Claude Code 等 agent 的 skill 入口：工作流、红线、新模块 checklist、陷阱速查，按章节号引用手册 |
 | `manual.md` | 模块开发手册（14 章）：工程结构（module-root 单树 + 两处产物根；含 §1.7 handler 四红线——oj 运行时实测钉出，后端必读；§1.8 `#` 别名与 TS 投影）、写模块、契约与代码生成（含 §3.10 旧 contract.ts 工程迁移指南）、provider 接管（覆盖框架内置功能）、布局、i18n、构建发布、排查、CLI 子命令参考（ojm 原生命令 vs oj 透传命令）、方案包打包与分发（含 §11.1.1 引用式方案）、签名与信任、§13.1.1 web.route_prefix 自定义根路径、**§14 组织架构与通讯录**（内置部门/成员底座 + 共享读面 7 端点 + `scope` 两级门禁 + 归属权四条规则 + 源适配器接点，选人与按部门算人都读它） |
-| `publish-walkthrough.md` | 方案包发布全流程（**新手照做版**）：构建打包 → keygen 签名 → `market publish` 落 CDN → build-index → verify/trial 验证 → install + TOFU，含多人各自独立发包纪律与失败速查（手册 §11/§12 的过程版） |
+| `publish-walkthrough.md` | 方案包发布全流程（**新手照做版**）：构建打包 → **拿发布身份（「发布管理」申请凭证 → `ojm keygen --credential`；无站点才用离线 `--id`）** → 签名 → `market publish` 落 CDN → build-index → verify/trial 验证 → install + TOFU，含多人各自独立发包纪律与失败速查（手册 §11/§12 的过程版） |
 | `framework-dev.md` | 框架贡献者路线（**仅框架仓库**）：改 `packages/runtime`、`packages/cli` 时的入口与红线 |
 | `module-dev-and-cdn-playground.md` | 教学文档：开发态 ≠ 分发态、「怎么安装自己的模块 / 会不会重复」、本地 CDN 市场链路五步跑通（setup → publish → build-index → verify → 安装） |
 | `sql-builder-missing-capabilities-pr.md` | 构造器能力缺口 PR 参考（**仅框架仓库**）：7 项诉求的闭环记录 |
 | `menu-rules.md` | 方案菜单归组规则专题：单根模块约定、自定义根路径 `web.route_prefix`、`category` 三值语义、admin 重写与视觉归组（手册 §13 的展开版） |
 | `wecom-daikaifa.md` | 企业微信代开发集成：**凭据清单**（8 项 `vars`，按 Tier A/B/C 分层的来源与必填时序 + 可信域名/可信 IP 备案）、首次开通顺序（含 `suite_ticket` 依赖与引导期死锁的破法）、**用户 / 开发 / 部署三角色手册**、错误文案速查、与自建应用共存的语义变化 |
 | `wecom-internal-app.md` | 企业微信**企业内部应用（自建应用）**集成：5 项 `wecom_corp_*` 凭据 + 2 项复用、回调只填「通讯录同步」一处、「验证并接入」四步自检、可见范围与可信 IP/域名、单企业私有化的边界（自建应用收不到成员变更事件）、共存配置、故障速查 |
+| `wecom-multi-corp-links.md` | **平台运维 / 服务商运营**：一套部署服务 N 家企业的**专属登录链接运维清单**（方案一，运维零代码改动）——前置检查、逐企业接入 6 步、链接格式与参数、员工四入口、逐企业验收打勾、故障速查、日常运维；含企微工作台内早跳透传 `corp`/`agent` 的修复说明 |
 
-> 上表 9 项 + 本文件 `README.md` = 顶层 10 个文件，全部随 cli 包发货。
+> 上表 10 项 + 本文件 `README.md` = 顶层 11 个文件，全部随 cli 包发货。
 > `ojm init` 第 4b 步**只分发其中 6 个**给业务工程：`SKILL.md` / `manual.md` / `README.md` /
 > `wecom-daikaifa.md` / `wecom-internal-app.md` / `publish-walkthrough.md`。
-> 其余 4 个（`framework-dev.md`、`menu-rules.md`、`module-dev-and-cdn-playground.md`、
-> `sql-builder-missing-capabilities-pr.md`）是框架贡献者或专题材料，只在 cli 包内可取。
+> 其余 5 个（`framework-dev.md`、`menu-rules.md`、`module-dev-and-cdn-playground.md`、
+> `sql-builder-missing-capabilities-pr.md`、`wecom-multi-corp-links.md`）是框架贡献者或专题材料，只在 cli 包内可取。
 
 后端 handler 本身的写法（`json` 信封、`db` 查询、`manifest.yaml`、`oj test`）、
 站点挂载（`mounts`）、密钥信封（`secrets`）、vars、cors、schema 校验、broker/tasks/oidc/ws 等
@@ -121,6 +129,6 @@ flowchart LR
   框架贡献者要把本仓快照同步到新版：从 `~/.local/share/oj/devkit/` 整目录覆盖
   `docs/devkit/oj-api-dev/`（oj v0.1.116 起 12 个文件，保持逐字节一致以便对账）。
 
-> 本目录顶层 10 个文件是**自包含**的：业务工程拿到即可读懂，不需要工程仓库里的
+> 本目录顶层 11 个文件是**自包含**的：业务工程拿到即可读懂，不需要工程仓库里的
 > 其它文档。`oj-api-dev/` 子目录是 oj 侧快照，同样自包含（其自身 README 即索引），
 > 但不随 cli 包发货、仅本仓参考。维护者视角的内容来源整理在 `framework-dev.md`（仅本仓）。

package/devkit/SKILL.md

@@ -19,7 +19,8 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
    接管通知/上传/菜单 → §4；换布局或加插槽 → §5；排查 → §8；
    **组织架构 / 通讯录（选人、按部门算收件人、接 LDAP 等新来源）→ §14**；
    **接通企业微信（代开发 / 企业内部应用 / 两套共存）→ `wecom-daikaifa.md` + `wecom-internal-app.md`**；
-   **把方案包发出去（打包/签名/CDN/安装一条链，新手照敲）→ `publish-walkthrough.md`**。
+   **把方案包发出去（打包/签名/CDN/安装一条链，新手照敲）→ `publish-walkthrough.md`**
+   （发布身份走站点凭证见其 §2.1）。
 2. **建目录**：一个目录 = 一个模块——前端一侧 `src/<模块名>/web/`（`entry.ts` 必备，
    `pages/`、`locales/` 按需），后端一侧 `src/<模块名>/api/`（目录镜像路由的 `api.ts`，
    动词挂 `.schema`）。两侧可只存在一侧。
@@ -140,6 +141,30 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
   同步/事件增量与回调解密是**两条独立纪律**：回调必须回 `success`，而事件处理失败**也照样回 `success`**
   （重推补不回已判死的失败，兜底是下一轮全量同步）。
 
+## 发布身份（keygen 从哪来）
+
+签名前的第一件事是拿到一对 Ed25519 密钥。**两条路，二选一**：
+
+| 路径 | 命令 | 何时用 |
+|---|---|---|
+| 站点凭证（推荐） | `ojm keygen --credential <token>` | 站点有「方案市场 → 发布管理」页；key_id 由站点按产品名+账号下发（信任仍需首装核对） |
+| 离线自建（旁路） | `ojm keygen --id <publisher>.<key-name>` | 只在站点没有「发布管理」页（纯自建/离线 CDN）或 CI 临时密钥时用 |
+
+站点有「方案市场 → 发布管理」页时**不要自建 key_id**：站点侧没有这条身份记录，产品归属与申请人无从追溯，
+能不能装只能靠超管为陌生指纹手工放行。
+
+- 凭证是**一次性兑换令牌**：站点「方案市场 → 发布管理 → 申请发布凭证」填产品名 → 明文只显示一次 →
+  本机 `ojm keygen --credential <token>`（或 `OJM_PUBLISH_CREDENTIAL=<token> ojm keygen`，
+  免得令牌进 shell 历史）。兑换成功即作废，失败（已用/过期/撤销/网络不通）**不落任何密钥文件**。
+- 站点地址优先级：`--site-url` > `OJM_SITE_URL` > `http://127.0.0.1:9778`；兑换端点匿名可达，
+  **不需要 `--user/--pass`**。`--credential` 与 `--id` 互斥（同时给 exit 2）。
+- 下发的 key_id 形如 `<产品名>.<编码后用户名>`（例：`demo-solution.wecom-everpan`），CLI 不做推导；
+  它同时是 `~/.ojm/keys/<key_id>/` 的目录名——**不要拿它拼路径或改名**，否则签名侧找不到私钥。
+  凭证只解决「身份命名与归属」，**不预置信任**：公钥在本地生成，站点兑换时拿不到，首装照样
+  `needs_trust`，仍要核对指纹。
+- 两条路的私钥纪律完全一致：只活在 `~/.ojm/keys/<id>/`、不入仓不入包、一次发布固定一把。
+  签名/发布/安装全流程见 `publish-walkthrough.md`（§2 凭证、§2.1 离线旁路、§3 签名起）。
+
 ## 新模块 checklist
 
 - [ ] `src/<模块>/web/entry.ts` 默认导出 `defineModule({ name, version, routes, i18n?, lifecycle? })`
@@ -229,3 +254,7 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 五项 `wecom_corp_*` 从哪取、回调为什么只填「通讯录同步」一处、「验证并接入」的四步自检、
 可见范围 / 可信 IP / 可信域名的处置、单企业私有化的边界（自建应用收不到成员变更事件）、
 以及和代开发共存时的配置与页面差异。**接自建应用时先读它**。
+
+另有 `publish-walkthrough.md`（同目录）：从「代码写完」到「装进站点」的一条命令链——
+构建/打包 → 拿发布身份（凭证或离线）→ 签名 → 落 CDN → 重建索引 → verify/trial → install/TOFU，
+每步带期望输出与通过判据。**第一次发包照着它敲**。

package/devkit/framework-dev.md

@@ -15,9 +15,14 @@
 | 框架开发完整指南（契约层/运行时/宿主/工具链四章） | `docs/prd/framework-development-guide.md` |
 | 端到端可重复验证流程 | `docs/prd/framework-verification-playbook.md` |
 | 某特性的设计与评审记录 | `docs/prd/<日期>-<特性>-design.md` |
-| 各阶段实战记录（骨架→注入→认证→CRUD→release） | `apps/playground-oj/docs/phase*.md` |
+| 各阶段实战记录（骨架→注入→认证→CRUD→发布） | `docs/prd/framework-verification-playbook.md` 附录 A 基线表（playground 已下线） |
 | 后端 handler 写法 | `docs/devkit/oj-api-dev/api-manual.md`（`oj-api-dev` skill 的本仓快照；用户工程侧在 `.claude/skills/oj-api-dev/`，随 oj 二进制分发） |
 
+> **路径口径**：上表除 `CLAUDE.md` 与 `docs/devkit/oj-api-dev/` 外，都是**框架仓库内**的路径，
+> 不随 `@oj-module/cli` 发货。本文件只对「能进框架仓库的人」有用——如果你是在 cli 包或
+> 业务工程里读到这里，说明没有仓库上下文，那些链接按设计不可达，**不是坏链**：业务开发
+> 请回 `SKILL.md` + `manual.md`。
+
 > ⚠️ 那两份 guide 有**已知陈旧处**，以源码为准：
 > dev 端口实际是 **3333**（guide 写的 5173 已过时；注意与 `ojm dev` 的前端 devServer
 > **5174** 不是一回事——前者是本仓 vite，后者是业务工程 devServer）；包版本以
@@ -192,9 +197,10 @@ runtime → cli → registry 复核；`--dry-run` 只演练）。下面的手动
 
 ## 附：本 devkit 内容来源（维护者看）
 
-`docs/devkit/` 是**自包含**的交付文档（顶层 6 个文件，含
-`sql-builder-missing-capabilities-pr.md` 这份构造器能力缺口 PR 参考），业务工程拿到即可读懂，不依赖工程仓库里的其它文档。
-另有 `oj-api-dev/` 子目录是 oj 侧 devkit 的快照（10 文件，仅本仓参考、不发货），
+`docs/devkit/` 是**自包含**的交付文档（顶层 11 个文件，全部随 cli 包发货，其中 6 个随
+`ojm init` 进业务工程；含 `sql-builder-missing-capabilities-pr.md` 这份构造器能力缺口 PR 参考），
+业务工程拿到即可读懂，不依赖工程仓库里的其它文档。
+另有 `oj-api-dev/` 子目录是 oj 侧 devkit 的快照（oj v0.1.116 起 12 文件，仅本仓参考、不发货），
 结构说明见 `README.md`。
 下面的来源仅用于维护时追溯与同步，不参与交付：
 

package/devkit/manual.md

@@ -35,7 +35,6 @@
 ├── env.d.ts               # ImportMeta.env 类型补丁
 ├── types/oj-modules.d.ts  # `declare module "#*"` 别名兜底（非模块文件的 ambient 声明）
 ├── .ojm-api-exempt.json
-├── seed.mysql.sql / seed.pg.sql
 ├── vitest.config.ts       # 后端 BDD（include tests/**/*.spec.ts）
 ├── tests/                 # 后端 BDD 测试（node:sqlite 内存库 + 真实迁移建表）
 ├── src/
@@ -60,7 +59,9 @@
 │   │       ├── auth/      #   仅 __client（无页面）
 │   │       ├── _platform/ #   仅 __client（oj-market 引用）
 │   │       └── web/       #   仅 __client
-│   ├── oj-market/web/     # 解决方案市场（独立模块，删目录即下线）
+│   ├── oj-market/web/     # 解决方案市场（独立模块，删目录即下线；单根 /oj-market 挂三个子页）
+│   │   ├── entry.ts       #   routes 聚合：/oj-market 根（方案清单 index）+ 发布管理/发布历史子路由
+│   │   └── publish/       #   发布管理 + 发布历史（/oj-market/publish、/oj-market/history：routes + pages + locales + __client）
 ├── dist/api/              # 后端产物（release 根：<name>-<ver>/ + manifests.yaml + versions.json）—构建后才有
 ├── dist/web/              # 站点产物（shell + modules/ + modules.json）—构建后才有
 ├── bin/                   # oj 二进制 + plugins/ + devkit/（不入库）
@@ -198,11 +199,25 @@ src/<模块>/api/<路径...>/api.ts   →   /api/<模块>/<路径...>
 | 文件 | 何时生效 |
 |---|---|
 | `migrations/*.sql` | 启动（dev `migrate_on_start: auto`）；release 默认 `verify`，账本落后则**拒绝启动** |
-| `seed.sql` | **每次启动都重放**（sqlite 默认库）——必须幂等，用 `INSERT OR IGNORE` |
+| `seed.sql` / `seed.<方言>.sql` | **每次启动都重放**——方言件（`.sqlite` / `.mysql` / `.pg`）存在即胜出、`seed.sql` 兜底、绝不双跑（oj ≥ 0.1.121）；必须幂等 |
 | `schema.yaml` | 声明；加可空列 / 加表 reconcile 能收敛，但**改类型与改名必须走 migrations** |
 
 > `seed.sql` 按 `;` 朴素切分，**注释里不许出现分号字面量**，否则语法错。
 
+> **方言 seed 放好即生效（oj ≥ 0.1.121，已是 `ojm` 最低版本门禁）**：方言件按模块存放
+> （`src/app/api/<模块>/seed.mysql.sql` / `seed.pg.sql`，与基础件同表同条数），启动时按当前库
+> 方言自动选——方言件胜出、`seed.sql` 兜底、**绝不双跑**；成功日志打 `file=` / `dialect=`，
+> 模块只有别的方言件或文件名拼错（如 `seed.postgres.sql`）会 warn，`oj check` 的 seed 检查会报错。
+> 更早的 oj 只认字面 `seed.sql`（会把 sqlite 写法原样下发 mysql/pg → 1064），已低于门禁，
+> `ojm vendor` / `ojm info` 会直接拒绝。工程根**不再**有方言 seed 副本（历史上那份只含部分
+> 设置、且 mysql 侧裸写 `key`，已删除）。
+
+> **框架自带 `_platform` 模块的迁移已压平为单条基线**（`0001__baseline.sql` 及
+> `.mysql.sql` / `.pg.sql` 两个方言版）：新工程按基线一次建表，不再有 0002…0018 的增量链。
+> 老开发库的迁移账本里记着旧序号，**基线不会被重放**——若库结构落后（例如缺新列），
+> 直接删 `api/db.sqlite` 重启即可（dev 自动重跑迁移 + seed），本项目**不提供兼容 shim**。
+> 基线必须三方言同步：只写 sqlite 版会让同一模块在 mysql/pg 部署上建表失败。
+
 ### 1.7 handler 四红线（oj 运行时实测钉出，2026-10-16 RBAC 阶段）
 
 以下四条都是真机冒烟（`ojm init` + `ojm dev`/`build`）实测钉出的 oj 运行时行为，
@@ -1919,9 +1934,9 @@ module-root 下数据源是「扫描 + `web.config.ts` 登记」并集（未登
 一个脚手架可放多份用户方案（`ojm new` 逐个生成，各自一份 `src/<name>/solution.yaml`），
 `ojm build --bundle` 无参时全部打包、逐个校验独立出包；框架自带方案自动排除（名单见
 `src/.ojm-builtin.json`，`ojm info` 默认折叠自带模块）。
-**从开发到发布的完整过程视角（新手照做版，含签名/私钥纪律与多人各自发包纪律）见本目录**
-[`publish-walkthrough.md`](./publish-walkthrough.md)；仓内深度过程视角另见
-[`docs/guides/solution-dev-build-publish.md`](../guides/solution-dev-build-publish.md)（不随 cli 包发货）。
+**从开发到发布的完整过程视角（新手照做版，含签名/私钥纪律与多人各自发包纪律）见本目录
+[`publish-walkthrough.md`](./publish-walkthrough.md)**——那份文件同样随包分发、自包含，
+发布链路只读它 + 本章即可闭环。
 
 ### 11.1 打包：`ojm build --bundle`
 
@@ -2075,16 +2090,26 @@ flowchart LR
 ### 12.1 发布流程（作者侧，三步）
 
 ```bash
-# ① 一次性：生成 Ed25519 密钥对（私钥 ~/.ojm/keys/<id>/ 永不出目录——--out 指进工程树须 --yes）
-ojm keygen --id <publisher>.<key-name>
+# ① 一次性：拿发布身份。站点有「方案市场 → 发布管理」页时，用页面签发的一次性凭证兑换（key_id 由站点算好下发，
+#    CLI 不推导；兑换即作废；失败不落任何密钥文件；与 --id 互斥，同时给 exit 2）：
+ojm keygen --credential <token> [--site-url <站点>]
+OJM_PUBLISH_CREDENTIAL=<token> ojm keygen
 
-# ② 每次发布：签名（产物 = 同目录 <tgz>.sig；--check 离线自检，不必靠装失败发现签错）
-ojm sign dist/<name>-<version>.tgz --id <publisher>.<key-name> --check
+# ①' 旁路：只在没有「发布管理」页（纯自建/离线 CDN）或 CI 临时密钥时自建 key_id——
+#    站点侧没有这条身份记录，产品归属与申请人无从追溯，只能靠超管为陌生指纹手工放行：
+ojm keygen --id <publisher>.<key-name>   # 私钥 ~/.ojm/keys/<id>/ 永不出目录；--out 指进工程树须 --yes
+
+# ② 每次发布：签名（--id 填上一步拿到的 key_id；产物 = 同目录 <tgz>.sig；--check 离线自检）
+ojm sign dist/<name>-<version>.tgz --id <key_id> --check
 
 # ③ 安装/分发：.sig 自动探测随包上传
 ojm install dist/<name>-<version>.tgz --site-url <站点> --user superadmin --pass …
 ```
 
+凭证通道的站点地址：`--site-url` > `OJM_SITE_URL` > `http://127.0.0.1:9778`；兑换端点匿名可达，
+不需要 `--user/--pass`。key_id 形如 `<产品名>.<编码后用户名>`（例：`demo-solution.wecom-everpan`），
+由站点按申请时的产品名与账号算好。
+
 宿主验签六码（失败文案双语，`--locale` 切换）：`sig_missing`（缺签）/ `sig_alg`（算法
 不受接受）/ `sig_key`（key_id 命名空间违约）/ `tampered`（验签不过）/ `unknown_key`
 （信任库无此 key → **needs_trust 第五终态**）/ `sig_format`（.sig 结构违约）。
@@ -2093,8 +2118,9 @@ ojm install dist/<name>-<version>.tgz --site-url <站点> --user superadmin --pa
 
 **TOFU = Trust On First Use（首次使用即信任）**：陌生发布方的第一个包，安装器无法判断
 该不该信，于是把公钥指纹摆出来让人核对——核对通过才入库，之后同一 key_id 直接放行。
-信任的建立因此有两条路：**第一方**走模板内置公钥免核对（§12.3），**第三方**走本节的
-人工核对。
+信任的建立因此有两条路：**模板内置的 oj-market 方案**用内置公钥免核对（§12.3），其余来源
+（含你自己 keygen 的身份、站点凭证下发的身份）一律走本节的人工核对——凭证只定 key_id 归属，
+站点在兑换时拿不到你的公钥，无法代为建立信任。
 
 - 信任库 = `.solutions/trusted-keys.yaml`（key_id → 公钥 + added_at；首次绑定不可改，
   轮换 = 新增 key_id）。

package/devkit/publish-walkthrough.md

@@ -1,8 +1,7 @@
 # 方案包发布全流程——新手照做版
 
-适用 ojm ≥ 0.2.22（写作时 0.2.56）。本文自包含：从「代码写完了」到「装进站点」一条命令链照着敲，每步附期望输出与通过判据。
-字段规范与错误码全口径见 `manual.md` §11/§12；仓内深度过程视角另见
-`docs/guides/solution-dev-build-publish.md`（不随 cli 包发货）。
+适用 ojm ≥ 0.2.22（写作时 0.2.66）。本文自包含：从「代码写完了」到「装进站点」一条命令链照着敲，每步附期望输出与通过判据。
+字段规范与错误码全口径见同目录 `manual.md` §11/§12——**本文不引用包外文件**，照着读完即可完成发布。
 
 ---
 
@@ -11,7 +10,7 @@
 ```mermaid
 flowchart LR
   A["① 构建 ojm build"] --> B["② 打包 ojm build --bundle"]
-  B --> C["③ 身份 ojm keygen（一次性）"]
+  B --> C["③ 身份 方案市场→发布管理 申请凭证 → ojm keygen --credential"]
   C --> D["④ 签名 ojm sign --check"]
   D --> E["⑤ 发布 ojm market publish"]
   E --> F["⑥ 重建索引 ojm market build-index"]
@@ -20,18 +19,19 @@ flowchart LR
 ```
 
 信任链硬 fail-closed：未签、签错、key 不被信任的包一律拒装，没有「先装了再说」的开关。
-**开始前确认三件事**（缺一件打包就过不去）：
+**开始前确认三件事**：
 
 1. 方案契约在位：`src/<模块>/solution.yaml`（`name` / `version` / `summary`；纯前端可省 `api` 段，纯后端可省 `web` 段）；
-2. `web.config.ts` 的 `modules` 数组已登记该模块（否则构建不产出站点产物，打包报「缺少本方案的站点产物」）；
-3. 双语 locale 在位：`web/src/.../locales/zh-CN.json` 与 `en-US.json`。
+2. 前端入口在位：`src/<模块>/web/entry.ts`。module-root 布局（0.2.20+）以**扫描**为准，
+   `web.config.ts` 的 `modules` 登记只影响加载顺序，漏登记**不会**漏构建（登记了不存在的 entry 才会报错）；
+3. 双语 locale 在位：`src/<模块>/web/locales/{zh-CN,en-US}.json`（key 必须嵌套，如 `{"menu":{"main":"…"}}`）。
 
 ---
 
 ## 1. 构建与打包
 
 ```bash
-ojm build               # ① 站点产物 web/dist/ + 后端产物 api/dist/
+ojm build               # ① 站点产物 dist/web/ + 后端产物 dist/api/
 ojm build --bundle      # ② 打包全部用户方案 → dist/<name>-<version>.tgz
 ojm build --bundle crm  #    只打 src/crm/ 这一份（多方案工程用）
 ```
@@ -40,7 +40,7 @@ ojm build --bundle crm  #    只打 src/crm/ 这一份（多方案工程用）
 
 ```
 [ojm] 方案包已生成 → dist/<name>-<version>.tgz
-[ojm] sha256：…（确定性打包：同源同字节）
+[ojm] sha256：…（N 字节；确定性打包：同输入两次打包哈希一致）
 ```
 
 三个要点：
@@ -53,19 +53,58 @@ ojm build --bundle crm  #    只打 src/crm/ 这一份（多方案工程用）
 
 ---
 
-## 2. 一次性：生成发布身份（keygen）
+## 2. 一次性：拿发布身份（站点凭证）
 
-每个开发者/每个环境**各自生成一把** Ed25519 密钥对，只需做一次：
+发布身份 = 一把 Ed25519 密钥 + 一个**站点认可**的身份名（`<产品名>.<账号>`）。
+身份名不自拟：站点要靠它在「发布管理」页留档，说清「谁、为哪个产品」发的包。
+所以主流程是「先申请凭证，再在本机兑换」：
+
+> 站点保证的是 **key_id 唯一**（同一产品名 + 同一账号 → 同一个身份，同一身份换机重申请是允许的），
+> 不是产品名独占：不同账号申请同名产品会各自得到 `<产品名>.<自己的账号>`。
+> 所以「谁有资格发这个方案」仍靠团队约定与市场侧的包名/版本冲突拦截，不能指望站点替你裁决。
+
+> 谁能申请：**任何登录用户**，不要求超管。但新建账号首次登录处于「必须先改密」状态，
+> 此时除改密外的写接口一律 `403 password change required`——先在页面或 `PUT /api/auth/password`
+> 改掉临时口令，再申请凭证。
+
+1. 浏览器进 **方案市场 → 发布管理 → 申请发布凭证**，填产品名（如 `demo-solution`）；
+2. 复制弹窗里的凭证或整条命令（**只显示这一次**，关闭后只能撤销重申请）；
+3. 本机执行其中一条：
+
+```bash
+ojm keygen --credential <token>
+OJM_PUBLISH_CREDENTIAL=<token> ojm keygen     # 或走环境变量，避免令牌进 shell 历史
+```
+
+- key_id 由站点按 `<产品名>.<编码后用户名>` 算好下发（例：`demo-solution.wecom-everpan`），
+  CLI 不做任何推导；落点 `~/.ojm/keys/<key_id>/`：`private.pem`（0600）+ `public.hex`。
+- 期望输出里有一行 **`指纹（sha256(publicKey)，公布给宿主核对）：…`**——抄下来，首装核对要用（§6）。
+- 凭证**一次性**：兑换成功即作废；兑换失败（已用/已过期/已撤销/网络不通）**不写入任何密钥文件**。
+- 站点地址：`--site-url` > `OJM_SITE_URL` > `http://127.0.0.1:9778`；兑换端点匿名可达，不需要 `--user/--pass`。
+- `--credential` 与 `--id` 互斥（同时给 exit 2）；`--out` / `--yes` 仍按离线版规则生效
+  （`--out <dir>` 相对路径按**进程 cwd** 解析，指进当前工程树会要求 `--yes`——私钥入仓即泄露）。
+- **它不替你建信任**：公钥是本地生成的，站点在兑换时拿不到，所以首装仍是陌生 key →
+  `needs_trust`，仍要按 §6 逐字核对指纹后 `trust confirm`。凭证解决的是「身份命名与归属」，
+  不是「信任免检」。
+- 兑换完成后，「方案市场 → 发布管理」该条记录变为**已兑换**并显示 key_id。
+- 发版之后，「方案市场 → 发布历史」（`/oj-market/history`）按发布时间倒序列出所有产品/版本：
+  数据由站点从签名索引对账落库，**不需要 CLI 额外上报**；发布时间优先取分发包落 CDN 的
+  `Last-Modified`，源不提供时回落索引生成时间并标「索引时间」标签。
+
+### 2.1 没有站点时：离线自建身份（旁路）
+
+站点不可达、或你维护的是纯自建/离线 CDN（根本没有「发布管理」页）时，才自己起 key_id：
 
 ```bash
 ojm keygen --id acme.alice.macbook     # 例：<团队/产品>.<人名>.<环境>
 ```
 
-- 期望输出里有一行 **fingerprint**（`sha256(公钥)`）——**抄下来发给运维**，TOFU 核对要用（§8）。
-- 落点 `~/.ojm/keys/<id>/`：`private.pem`（权限 0600）+ `public.hex`。
-- key_id 必须**全小写、至少两段**（`<publisher>.<id>`），禁裸通用名如 `mykey`——违约包能签出来但装不进（`sig_key` 拒装）。
+- **站点不知道这个身份**：发布管理页没有它的记录，产品归属与申请人无从追溯；能不能装，
+  完全取决于超管愿不愿意为这枚指纹手工放行。有站点的市场请走 §2 凭证，不要自建。
+- 其余规则与凭证通道一致：key_id 必须**全小写、至少两段**（`<publisher>.<id>`），
+  禁裸通用名如 `mykey`——违约包能签出来但装不进（`sig_key` 拒装）。
 
-私钥纪律（逐条照做，违者 = 任何人都能以你的身份发包）：
+私钥纪律（两条路都适用，逐条照做，违者 = 任何人都能以你的身份发包）：
 
 | 纪律 | 原因 |
 |---|---|
@@ -80,12 +119,15 @@ ojm keygen --id acme.alice.macbook     # 例：<团队/产品>.<人名>.<环境>
 
 ```bash
 ojm sign dist/<name>-<version>.tgz \
-  --id acme.alice.macbook \
-  --key ~/.ojm/keys/acme.alice.macbook/private.pem \
+  --id <key_id> \
   --registry-id oj-registry \
   --check
 ```
 
+- `<key_id>` 就是上一步拿到的身份：走凭证是站点下发的 `demo-solution.xxx`，走离线旁路是
+  §2.1 里 `--id` 填的那个。私钥缺省取 `~/.ojm/keys/<key_id>/private.pem`；只有把 key 放到了
+  别处（如 `--out ./keys`）才需要再加 `--key <path>/private.pem`，且此时 `--id` 仍必须给
+  （`.sig` 按它记发布方）。
 - `--registry-id` **必填**：发布仓库的自拟标识（同一市场的所有发布方用同一个值，如 `oj-registry`）。它进签名规范串防「把 A 仓库的包重放到 B 仓库」；站点若配置了自身 registry 身份则必须与之一致（默认模板未配置，不比对）。
 - 产物 = 同目录 `<tgz>.sig` 侧车文件。**签了再改包 = 签名作废**；重打包必须重签。
 - `--check` 离线自检（本地验一遍），不必等安装失败才发现签错。期望输出：`[ojm] 自检通过…`。
@@ -100,13 +142,14 @@ CDN 就是**一个装着固定命名文件的目录**：`<name>-<version>.tgz`
 
 ```bash
 ojm market publish --real . \
-  --id acme.alice.macbook \
-  --key ~/.ojm/keys/acme.alice.macbook/private.pem \
+  --id <key_id> \
   --registry-id oj-registry \
   --rebuild-index
 ```
 
-期望输出：`[ojm] 包已落 CDN → cdn/<name>-<version>.tgz（N 字节）` + 发布方指纹。`cdn/` 下落齐六件：tgz / .tgz.sig / 索引两份 yaml（+ 各自 .sig）。
+期望输出：`[ojm] 包已落 CDN → cdn/<name>-<version>.tgz（N 字节）` + 发布方指纹。
+`cdn/` 是**三级索引**布局：`catalog.yaml`（+`.sig`）、`shards/<n>.yaml`（+`.sig`）、
+`<name>-<version>.tgz`（+`.tgz.sig`）；分片数随方案数增长，不要按固定文件数核对。
 
 > 引用式方案（契约 `api` 段省略 `tables`/`deps`）会打印「引用式方案…非漏配」提示——那是合法形态，不是错误。
 
@@ -116,9 +159,8 @@ ojm market publish --real . \
 
 ```bash
 ojm build --bundle crm                                            # ① 打包指定方案
-ojm sign dist/crm-1.0.0.tgz --id acme.alice.macbook \
-  --key ~/.ojm/keys/acme.alice.macbook/private.pem \
-  --registry-id oj-registry --check                              # ② 签名
+ojm sign dist/crm-1.0.0.tgz --id <key_id> \
+  --registry-id oj-registry --check                               # ② 签名（私钥缺省取 ~/.ojm/keys/<key_id>/）
 cp dist/crm-1.0.0.tgz dist/crm-1.0.0.tgz.sig cdn/                # ③ tgz + .sig 放进 cdn/
 ojm market build-index --id <维护者key> --check                   # ④ 重建索引（见 §4.3）
 ```
@@ -137,11 +179,16 @@ ojm market build-index --id <维护者key> --check                   # ④ 重
 ## 5. 验证发布（不起站点）
 
 ```bash
-ojm market verify --rebuild-index     # 五项自检：完整性/包级签/索引签×2/manifest 结构，全 ✓ 才算过
+ojm market verify --rebuild-index     # 逐项验：完整性 / 包级签 / manifest 结构 / 索引签（catalog+分片）/ 索引同代 / 索引时效 / 迁移一致性
 ojm market trial --fixture <name>@<version>       # 隔离站点跑完整安装，跑完即毁，不污染工程
-ojm market walkthrough --fixture <name>@<version> # 14 项 AC：主链 9 + 负向 5；报告落 logs/walkthrough-<ts>.md
+ojm market walkthrough --fixture <name>@0.1.0     # 14 项 AC：主链 9 + 负向 5；报告落 logs/walkthrough-<ts>.md
 ```
 
+- `verify` 的检查项数随包数与分片数变化，判据是**末行「全部校验通过（N 项）」且无未通过项**，
+  不要按固定条数核对。
+- `walkthrough` 的 fixture **必须是 `@0.1.0`**：主链的 upgrade/rollback 硬编码 0.1.0→0.2.0，
+  给别的版本这两项会 FAIL（是 fixture 选错，不是框架缺陷）。
+
 walkthrough 期望 `14 PASS / 0 FAIL`。负向 5 项是**预期失败口径**：防线没拦住（恶意包装成了）才算 FAIL。
 
 ---
@@ -149,24 +196,41 @@ walkthrough 期望 `14 PASS / 0 FAIL`。负向 5 项是**预期失败口径**：
 ## 6. 装到站点（运维侧）
 
 ```bash
+# ⓪ 先构建：release 形态服务的是产物，不先 build 会缺 dist/api（或装到旧产物）
+ojm build
+
 # ① 站点以 release 形态起（dev/preview 完不成安装的热更段）
+#    先把 config.yaml 的 platform.root 从 src 改成 dist/api——必须与 --api-path 同源，
+#    否则 oj serve 直接拒启：platform.root (...) must be mounted as an api mount
+#    再配 vars.canonical_origin（本地演练填 http://127.0.0.1:9778）：市场基址 /cdn 是相对路径，
+#    服务端要靠它补全成绝对 URL；缺了安装直接 503（REG-CS6 不读 Host 头，不会替你猜）
 oj serve -c config.yaml -b /api --api-path dist/api
 
-# ② 市场地址指向站点自供的 /cdn（默认即如此；外部真 CDN 才需要 setup 写绝对地址）
-ojm market setup --site-url http://127.0.0.1:9778 --user superadmin --pass … --new-pass <新口令>
+# ② 市场地址：本地自供 /cdn 是模板默认，**不需要 setup**；
+#    只有指向外部真 CDN 才要执行（首跑可能强制改密，故下一步的 --pass 用新口令）：
+#    ojm market setup --site-url http://127.0.0.1:9778 --user superadmin --pass <当前口令> --new-pass <新口令>
 
 # ③ 安装（从 CDN 拉：name[@version]；直传文件则给 tgz 路径，.sig 同目录自动随包）
-ojm install crm@1.0.0 --site-url http://127.0.0.1:9778 --user superadmin --pass <新口令>
+#    只对 release 站点装；别对着 `ojm dev` 装——dev 的文件监听会在安装器 reload 之前
+#    先吃掉 config 改动，安装器自己再 reload 时得到 unchanged，判 partial（reloading）
+ojm install crm@1.0.0 --site-url http://127.0.0.1:9778 --user superadmin --pass <口令>
 
 # ④ 首装陌生 key 必停在 needs_trust：响应 trust.fingerprint 与 §2 记下的指纹【逐字】核对
 #    核对通道用当面/电话/既有加密聊天——不要用 CDN 页面上的指纹（那正是攻击者能改的地方）
-ojm trust confirm --task <task-id> --site-url http://127.0.0.1:9778 --user superadmin --pass <新口令>
-ojm install crm@1.0.0 --site-url http://127.0.0.1:9778 --user superadmin --pass <新口令>   # 重跑续跑
+ojm trust confirm --task <task-id> --site-url http://127.0.0.1:9778 --user superadmin --pass <口令>
+ojm install crm@1.0.0 --site-url http://127.0.0.1:9778 --user superadmin --pass <口令>   # 重跑续跑
 ```
 
-通过判据：`dist/api/manifests.yaml` 出现 `<name>: <version>`；**重启一次 `oj serve`**（新方案路由要重启才注册，热更只覆盖 vars）后 `curl /api/<name>/ping` 返回 `code:0`。
+`<口令>` 就是登录站点用的那个：没跑过 `market setup` 时是脚手架种子口令（`superadmin / aA123456`），
+跑过则用 `--new-pass` 设的新口令。
+
+通过判据：`dist/api/manifests.yaml` 出现 `<name>: <version>`；**重启一次 `oj serve`**（新方案路由要重启才注册——reload 由 manifests 锁 diff 驱动装配，但新模块路由/模块注册属 restart_pending，热改不即时生效）后
+`curl -H 'X-TENANT-ID: default' /api/<name>/ping` 返回 `code:0`——**不带租户头会 400 `missing tenant header`**，
+那是缺参数，不是装失败。
 
-第一方方案走模板内置公钥（bootstrap key），首装免 TOFU；第三方走上面的人工核对。key 轮换 = 新 key_id 重发 + 站点 `trust add` 新公钥 + `trust revoke` 旧 key（吊销只阻断新装，不动已装方案）。
+TOFU 没有免检通道：**只有模板内置的 oj-market（第一方包）用内置 bootstrap 公钥首装免核对**；
+你自己 keygen 出来的任何身份——包括站点凭证下发的——首装都要人工核指纹。key 轮换 = 新 key_id
+重发 + 站点 `trust add` 新公钥 + `trust revoke` 旧 key（吊销只阻断新装，不动已装方案）。
 
 ---
 
@@ -176,15 +240,22 @@ ojm install crm@1.0.0 --site-url http://127.0.0.1:9778 --user superadmin --pass
 |---|---|---|
 | `sig_missing` | 没签，或 `.sig` 没随包在同目录 | `ojm sign --check` 后确认 `.sig` 与 tgz 同目录再装 |
 | `tampered` | 签完又动过包，或传输损坏 | 重打包重签；核对 sha256 |
-| `sig_key` | key_id 不是 `<publisher>.<id>` 全小写两段式 | 重新 keygen 合规 id，用新 key 重签 |
+| `sig_key` | key_id 不是 `<publisher>.<id>` 全小写两段式 | 凭证通道回「发布管理」重申请（产品名须小写合规）；离线旁路换合规 id 重 keygen 再重签 |
+| `keygen --credential` 报「发布凭证无效或已失效」 | 一次性令牌已兑换/已过期/已撤销，或站点地址不对 | 回「发布管理」重新申请；同一 token 不能给第二台机器 |
+| 申请凭证 403 `password change required` | 新建账号首次登录还在「必须先改密」悬挂期 | 先改密（页面或 `PUT /api/auth/password`），再申请 |
+| 安装 503 `安装需要站点 canonical origin` | `config.yaml` 的 `vars.canonical_origin` 没配，而市场基址是相对路径 `/cdn` | 配成站点对外地址（本地演练 `http://127.0.0.1:9778`）后重启 |
+| 安装 partial（stage `reloading`，`reloadConfig 返回 unchanged`） | 对着 `ojm dev` 装：dev 的文件监听先吃掉了 config 改动 | 换成 `oj serve` release 形态再装；别在 dev 上验证安装 |
+| 装完 `curl /api/<name>/ping` 返回 400 `missing tenant header` | 少了 `X-TENANT-ID` 头 | 加 `-H 'X-TENANT-ID: default'` 再探 |
 | `sig_alg` / `sig_format` | 签名算法/.sig 结构不符 | 用当前 ojm 重签（旧版本工具产物） |
 | `needs_trust`（第五终态，非成功） | 站点第一次见这个 key | 与发布方逐字核对指纹 → `trust confirm --task <id>` → 重跑 install |
 | publish 报「包冲突：…字节不一致」 | 同 name@version 已有字节不同的包 | **升 version 重发**；确需覆盖先删 CDN 旧 tgz |
 | publish 报「一次只发布一份方案」 | 多方案工程走了自动链路 | §4.2 显式四步 |
-| 打包报「缺少本方案的站点产物」 | `web.config.ts` 没登记 / 没先 `ojm build` | 登记后重跑构建再打包 |
+| 打包报「缺少本方案的站点产物」 | 没先 `ojm build`，或前端入口不在 `src/<模块>/web/entry.ts`（module-root 扫描不到；`web.config.ts` 漏登记**不是**原因） | 补 entry / 先构建再打包 |
 | 打包报「缺少 bundle 级契约」 | 没有 `solution.yaml` | 补契约（§0 前提 1） |
-| 装不到刚发的包 | 索引没重建 | `ojm market build-index`（§4.3 纪律 2），确认 CDN 六文件同步 |
+| 装不到刚发的包 | 索引没重建 | `ojm market build-index`（§4.3 纪律 2），确认 `cdn/` 的 catalog + 分片 + tgz(+sig) 已同步 |
 | 装成后 404 | 方案路由没注册 | 重启 `oj serve`（§6 通过判据） |
+| `oj serve` 报 `platform.root (...) must be mounted as an api mount` | release 起站了，但 config 的 `platform.root` 还是 `src` | 改成 `dist/api`（与 `--api-path dist/api` 同源）后重启 |
+| `oj serve` 报 `lock points to missing version dir: dist/api/<name>-<ver>` | 锁文件记着某个已装版本，但那个版本目录不在了（清过 dist / 换过机器） | 先 `ojm build`；锁与目录对不上时按站点安装记录重装该方案，别手改锁 |
 | 私钥误入工程 | 打包自检拦下 / 被外部拷走 | 立即 `trust revoke` 该 key → 换新 key_id 重发 |
 
 ---
@@ -194,6 +265,8 @@ ojm install crm@1.0.0 --site-url http://127.0.0.1:9778 --user superadmin --pass
 - [ ] `solution.yaml` 的 `version` 已升，与文件名一致；
 - [ ] `ojm build` + `ojm build --bundle` 均通过，sha256 记进发布单；
 - [ ] `ojm sign … --check` 通过，`.sig` 与 tgz 同目录；
-- [ ] 新 key 首次发布：fingerprint 已提前交给运维（免得卡在 needs_trust）；
-- [ ] `ojm market verify` 五项全 ✓；
+- [ ] 发布身份来自站点凭证（有发布管理页时），「方案市场 → 发布管理」页该条已变**已兑换**；
+- [ ] 发版后「方案市场 → 发布历史」能看到这次的 产品 / 版本 / 发布时间（时间来源为索引兜底时会标「索引时间」）；
+- [ ] 新 key 首次发布：指纹已提前交给运维（免得卡在 needs_trust）；
+- [ ] `ojm market verify` 末行「全部校验通过（N 项）」，无未通过项；
 - [ ] 多人团队：索引重建触发点已约定（维护者或 CI）。

package/devkit/wecom-internal-app.md

@@ -124,14 +124,19 @@
 > 通用回调配置（96238 §3.2）与「通讯录变更事件」（90967）都没写；服务端两种包体都收（XML / JSON
 > 都能归一），所以地址照文档写，不加参数。
 
-### 2.3 两项备案（都在企微后台，不写在代码里）
+### 2.3 三项备案（都在企微后台，不写在代码里）
 
 | 备案项 | 填在哪 | 填什么 | 不做的症状 |
 |---|---|---|---|
 | **可信域名**（网页授权 / JS-SDK） | 应用详情 → **网页授权及JS-SDK** | 站点域名（如 `example.com`），按企微要求上传校验文件到该域名根路径 | 企微授权页直接拒绝：`redirect_uri 需使用应用可信域名`；员工点了登录弹不出来 |
+| **授权完成回调域名**（扫码登录 / 企业微信授权登录） | 应用详情 → **企业微信授权登录** → 授权回调域 | **纯域名**（如 `example.com`）：不带 `https://`、不带路径、不带端口、不带尾斜杠 | 普通浏览器点「一键登录」后企微报 `redirect_uri 与配置的授权完成回调域名不一致`；**企微工作台内的静默登录不受影响** |
 | **可信 IP**（API 调用白名单） | 应用详情 → **企业可信IP** | 服务器的**出口**公网 IP（多机部署要全列） | 上游接口报 `errcode=60020 not allow to access from your ip` → 本站回 502 并把 errcode 透出 |
 
-> 菜单名随企微版本会变；认准**可信域名**与**企业可信IP**这两个词即可。
+> 菜单名随企微版本会变；认准**可信域名**、**授权完成回调域名**、**企业可信IP**这三处。
+> **可信域名 ≠ 授权完成回调域名**：前者给企微客户端内的 `snsapi_base` 静默授权用，后者给外部浏览器的
+> `qrConnect` 扫码登录用，是两处独立配置。工作台能登录只说明前者已配好，扫码是第一次真正走到后者。
+> 本站发出的 `redirect_uri` 由 `wecom_base_url` 派生，形如 `https://<站点>/api/auth/wecom/callback`，
+> 校验时只比对其中的域名部分，不要把这个完整地址填进回调域。
 > 回调与网页授权都要求 **https**：本地开发必须用内网穿透（见 §6.5），企微不会回调 http。
 
 还有一项**不是备案、但决定同步能拿到多少人**：