h3factory 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,224 @@
-# Temporary Holding Version
+# h3factory —— 氚云表单工厂
 
-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.
+把「需求文档 → 设计 → 建表 → 数据 → 代码」固化成流水线。**确定性部分（建表/导入/校验/骨架代码）全部脚本化，零 LLM 依赖；智能部分（需求→设计、业务规则代码）由 Claude Code 现场完成。** 两者靠一份表单 JSON 定义接起来。
+
+```
+需求文档
+   ↓  [AI 层] 按 docs/requirement_checklist.md 澄清 → 产出设计稿 + 表单 JSON → 人工过目
+projects/<名>/sheets/*.json + dicts.json
+   ↓  [工厂层] h3factory build <名>
+氚云线上表单（编码自动注册 registry.json）
+   ↓  h3factory verify <名>   ← 只读回读核对（字段/隐藏规则/一行多列/子表/布局项/位置设置/NameSchema）
+   ↓  h3factory gen <名> <表> ← .cs 提交时代码骨架（TODO 由 AI/人补业务规则）
+交付：代码 +「界面手工配置清单」（必填/审批流等 UI-only 项平台 API 配不了）
+```
+
+## 安装
+
+要求：**Node.js ≥ 16**、**Python ≥ 3.10**（只用标准库，无需 pip 安装依赖）。
+
+### 从 npm 安装（推荐）
+
+```bash
+npm install -g h3factory
+
+# 国内镜像（npmmirror 会同步公共 npm 包）
+npm install -g h3factory --registry https://registry.npmmirror.com
+```
+
+任何支持技能目录的 Agent 装完即用，无需额外配置。
+
+### 从 GitHub 私有仓库安装（内部/源码）
+
+私有仓库**不要**用 `github:账号/仓库` 简写——npm 会匿名请求 codeload，私有仓会返回 404。用完整 git 地址：
+
+```bash
+# SSH（需本机已配置 GitHub SSH key）
+npm install -g git+ssh://git@github.com/xiangduo10146814/h3factory.git
+
+# 若 22 端口不通，改用 SSH 443（GitHub 官方支持）
+git config --global url."ssh://git@ssh.github.com:443/".insteadOf "ssh://git@github.com/"
+npm install -g git+ssh://git@github.com/xiangduo10146814/h3factory.git
+
+# HTTPS + PAT（token 会留在 shell 历史，注意保密）
+npm install -g git+https://<TOKEN>@github.com/xiangduo10146814/h3factory.git
+```
+
+### 从本地 tarball 安装
+
+```bash
+npm pack                       # 生成 h3factory-0.2.0.tgz
+npm install -g ./h3factory-0.2.0.tgz
+```
+
+安装时 `postinstall` 会把 `skills/h3factory` 和 `skills/h3yun-dev-assistant` 复制到
+Claude Code / Codex / Cursor / OpenCode / QwenWork / Qoder / QoderWork / Mulerun
+的用户技能目录（不存在会创建）。技能更新由安装包管理，会覆盖本地修改。
+
+## 快速开始
+
+```bash
+mkdir D:\h3work && cd /d D:\h3work   # 任意工作区目录，别用 System32
+
+h3factory auth status --json   # Agent 第一步：检查凭据，ok=false 就先录 token
+h3factory init                 # 人类交互式录入（或由 Agent 用 auth set --json 写入）
+h3factory doctor               # 检查 Python / 配置 / JWT 是否过期 / 技能
+h3factory demo                 # 复制内置示例项目到 ./projects/demo
+h3factory check demo           # 离线校验，不联网
+```
+
+凭据字段：`baseUrl`、`engineCode`、`engineSecret`、`authorization`（Bearer JWT，**会过期**）、`appCode`。
+Agent 写凭据用 stdin，避免出现在命令行参数里：
+
+```bash
+h3factory auth set --json <<'JSON'
+{"authorization": "<JWT>"}
+JSON
+```
+
+`authorization` 过期后去氚云后台重新生成粘回，再跑 `h3factory auth status` 确认。
+
+## 工作区模型
+
+命令在**当前目录**执行，当前目录就是工作区：
+
+```
+<工作区>/
+├─ config.json              # 凭据（勿提交/分享）
+└─ projects/<项目名>/
+   ├─ config.json           # 可选，覆盖工作区凭据
+   ├─ dicts.json            # 枚举字典
+   ├─ groups.json           # 可选，表单分组与顺序
+   ├─ sheets/*.json         # 每张表单一个定义文件
+   ├─ registry.json         # 平台编码注册表，勿手改
+   ├─ logs/                 # verify/group 报告
+   └─ generated/            # .cs 代码骨架
+```
+
+配置查找顺序：`H3FACTORY_CONFIG` → `./config.json` → `~/.h3factory/config.json`。
+工作区也可用环境变量指定：`H3FACTORY_HOME=D:\h3work h3factory check demo`。
+
+## 命令
+
+| 命令 | 作用 | 联网 |
+|---|---|---|
+| `h3factory auth status [--json]` | **凭据门禁**：检查配置与 JWT 是否可用 | 否 |
+| `h3factory auth set --json` | 从 stdin 读 JSON 写入凭据（值不回显） | 否 |
+| `h3factory auth set-token` | 从 stdin 读 token 写入 | 否 |
+| `h3factory init [--no-input]` | 交互生成工作区 config.json | 否 |
+| `h3factory demo` | 复制内置示例项目 | 否 |
+| `h3factory doctor` | 检查运行时、配置、JWT、技能 | 否 |
+| `h3factory check <项目> [表..]` | 本地加载并校验表单定义 | 否 |
+| `h3factory list <项目>` | registry 各表编码与状态 | 否 |
+| `h3factory build <项目> [表..] [--force]` | 建表；已存在且结构一致则跳过 | 是 |
+| `h3factory verify <项目> [表..]` | LoadForm 只读回读比对 | 是 |
+| `h3factory group <项目> [表..]` | 建分组并归位（幂等） | 是 |
+| `h3factory import <项目> <表> <data.json> [--submit]` | 批量导数据 | 是 |
+| `h3factory gen <项目> <表>` | 生成 .cs 提交时代码骨架 | 否 |
+| `h3factory docs [名称]` | 列出/打印内置文档 | 否 |
+| `h3factory skill install [--tool all\|auto\|<工具>] [--scope user\|project]` | 安装/更新技能 | 否 |
+| `h3factory skill list` | 查看各工具已安装位置 | 否 |
+| `h3factory --version` | 版本 | 否 |
+
+源码目录内仍可用旧方式：`python -X utf8 cli.py <命令>`（Windows GBK 控制台必须带 `-X utf8`）。
+
+## 与各种 Agent 配合
+
+npm 安装后会把技能自动复制到以下用户级技能目录（目录不存在也会创建）：
+
+| Agent | 技能目录 |
+|---|---|
+| Claude Code | `~/.claude/skills/` |
+| Codex | `~/.codex/skills/` |
+| Cursor | `~/.cursor/skills/` |
+| OpenCode | `~/.opencode/skills/` |
+| QwenWork | `~/.qwenworkcn/skills/` |
+| Qoder / QoderWork | `~/.qoder/skills/`、`~/.qoderwork/skills/` |
+| Mulerun | `~/.mulerun/skills/` |
+
+随包安装两个技能：
+
+- `h3factory` —— 工厂总入口：凭据门禁、澄清需求、产出 sheets JSON、调用 CLI、交付清单。
+- `h3yun-dev-assistant` —— 氚云二开规范：C# 后端、ES5 前端、SQL、控件编码、平台限制。
+
+### Agent 会话第一步：录入 token
+
+技能里已写成硬门禁。Agent 每次会话先执行：
+
+```bash
+h3factory auth status --json     # 看 ok / missing / jwt_expired
+```
+
+`ok=false` 时向客户要 token，并通过 stdin 写入（不放进命令行参数、不回显）：
+
+```bash
+h3factory auth set --json <<'JSON'
+{"authorization": "<客户提供的 JWT>"}
+JSON
+```
+
+再次运行 `h3factory auth status --json`，`ok=true` 后才允许 `build/verify/group/import`。
+CLI 自身也会在 `build/verify/group/import` 启动时做同样的检查，token 缺失或过期会直接拒绝执行。
+
+**首选方式**：让客户在自己的终端运行 `h3factory auth set-token`（输入隐藏，token 不进入对话记录）；
+还缺其他字段就运行 `h3factory init`。只有客户主动在对话里贴 token 时，才用上面的 `auth set --json`。
+
+新需求直接对 Agent 说：
+
+```
+用 h3factory 帮我做这个需求：<需求文档/链接/文本>
+```
+
+技能会按 `docs/requirement_checklist.md` 澄清，产出 `projects/<新项目>/` 设计并停下来等你过目；确认后才建表。
+
+## 关键规则（血泪教训，详见 docs/platform_gotchas.md）
+
+- **verify 只读、可重复跑**；`build --force` 才整表重存 —— 重存 = 整体替换，会抹掉界面上手工配的必填/联动，慎用。
+- 界面手工活（必填、审批流、字段联动、只读）API 配不了，每次交付附「界面配置清单」。
+- 表单下拉存储「名称」，代码位另用字典表转换 —— 设计时就想清「存名称还是代码」。
+- 代码类、schema code 注册在 `projects/<名>/registry.json`，删了会发新编码、断关联。
+- `config.json` 含凭据：不提交、不分享、不让 AI 打印。
+
+## 源码结构
+
+```
+h3factory/
+├─ bin/h3factory.js          # npm 入口：探测 Python 3.10+ 并转调 cli.py
+├─ cli.py                    # init/demo/doctor/check/list/build/verify/group/import/gen
+├─ h3platform/               # 连接层：Console SaveForm/LoadForm + OpenAPI + 配置解析
+├─ h3design/                 # 设计层：控件工厂 / SaveForm 载荷 / JSON DSL
+├─ h3verify/verify.py        # LoadForm 只读回读比对
+├─ skills/                   # 随包安装到各 Agent 的技能
+├─ templates/controller.cs.tpl
+├─ docs/                     # workflow / schema_doc / requirement_checklist / platform_gotchas
+├─ scripts/postinstall.js    # 技能安装
+└─ projects/demo/            # 内置示例（打包时带上）
+```
+
+## 开发与发布
+
+```bash
+npm pack --dry-run     # 检查包内容：不得出现 config.json / 业务 projects / logs
+npm pack               # 生成 tarball
+npm install -g ./h3factory-0.2.0.tgz
+h3factory check demo   # 冒烟
+```
+
+发布到公共 npm（维护者）：
+
+```bash
+npm login --registry https://registry.npmjs.org
+npm publish                 # package.json 的 publishConfig 已指向 npmjs
+```
+
+代码仓库（私有）：<https://github.com/xiangduo10146814/h3factory>
+
+日常更新：
+
+```bash
+git add .
+git commit -m "feat: ..."
+git push origin main        # 本机 github.com:443 不通时，用 gh api / 代理推送
+```
+
+> 仓库默认不跟踪业务项目（`projects/*` 已忽略，仅保留 `projects/demo`），凭据文件也不会入库。

package/bin/h3factory.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * h3factory npm 入口：定位 Python 3.10+，以 UTF-8 模式转调 cli.py。
+ * 业务代码全部在 Python 内核里，这里只负责运行时探测和参数透传。
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync, spawn } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const CLI_PATH = path.join(PACKAGE_ROOT, 'cli.py');
+const rawArgs = process.argv.slice(2);
+
+function fail(message) {
+  console.error('[h3factory] ' + message);
+  process.exit(1);
+}
+
+if (rawArgs[0] === '--version' || rawArgs[0] === '-v' || rawArgs[0] === '-V') {
+  console.log(require(path.join(PACKAGE_ROOT, 'package.json')).version);
+  process.exit(0);
+}
+
+if (!fs.existsSync(CLI_PATH)) {
+  fail('安装不完整：找不到 ' + CLI_PATH + '，请重新安装。');
+}
+
+function works(cmd, baseArgs) {
+  const probe = spawnSync(
+    cmd,
+    baseArgs.concat([
+      '-c',
+      'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 3)',
+    ]),
+    { stdio: 'ignore', timeout: 8000, windowsHide: true }
+  );
+  return probe.status === 0;
+}
+
+const candidates = [];
+if (process.env.H3FACTORY_PYTHON) {
+  candidates.push({ cmd: process.env.H3FACTORY_PYTHON, args: [] });
+}
+if (process.platform === 'win32') {
+  candidates.push({ cmd: 'py', args: ['-3'] });
+  candidates.push({ cmd: 'python', args: [] });
+  candidates.push({ cmd: 'python3', args: [] });
+} else {
+  candidates.push({ cmd: 'python3', args: [] });
+  candidates.push({ cmd: 'python', args: [] });
+}
+
+let runtime = null;
+for (const candidate of candidates) {
+  if (works(candidate.cmd, candidate.args)) {
+    runtime = candidate;
+    break;
+  }
+}
+
+if (!runtime) {
+  fail(
+    '未找到 Python 3.10+。请安装 Python 并加入 PATH，' +
+      '或设置 H3FACTORY_PYTHON 指向解释器路径。'
+  );
+}
+
+const args = runtime.args.concat(['-X', 'utf8', CLI_PATH], rawArgs);
+const child = spawn(runtime.cmd, args, {
+  stdio: 'inherit',
+  windowsHide: false,
+  env: Object.assign({}, process.env, {
+    PYTHONUTF8: '1',
+    PYTHONIOENCODING: 'utf-8',
+  }),
+});
+
+child.on('error', (err) => fail('启动 Python 失败: ' + err.message));
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.exit(130);
+  }
+  process.exit(code === null ? 1 : code);
+});