docs(webapp-deploy): 模块安装四步规范（json2ddl建表→json/build.sh→wwwroot软链→数据导入）；模块一律clone进pkgs禁mv

skills_library/all/webapp-deploy/SKILL.md

@@ -41,16 +41,51 @@ version: 1.0.0
 - **硬性约束：build.sh 必须 fail-fast**——脚本开头 `set -e`（或每步显式检查返回码），任何一步失败（建表/插种子/pip install/xls2ui）立即 `exit 1` 终止，**禁止报错后继续执行后续步骤或假装成功**。特别：init_data.py 插种子失败（JSON 解析错误/表缺失）时，若 build.sh 仍继续 `start app`，会导致应用带缺表/缺种子启动、/healthz 失败，且部署日志里同时出现报错和「done」造成「看似成功」的假象。build.sh 末尾的 start 必须只在前面所有步骤都成功后才执行。
 
 1. 创建独立 venv: `python3 -m venv py3`
-2. clone 基础共享包到 pkgs/（apppublic, sqlor, ahserver, rbac, xls2ddl, appbase, bricks-for-python）
-3. 构建 bricks 前端: `mkdir -p bricks/dist` → `cd bricks/bricks && bash build.sh` → `ln -sf ../pkgs/bricks/dist wwwroot/bricks`
-4. 本地业务模块 mv 到 pkgs/
-5. clone 外部业务模块到 pkgs/
-6. `pip install` 所有 pkgs/ 模块
-7. `xls2ui` 从 json/ 生成 CRUD
-8. 模块 wwwroot **软链接**（非 cp）: `ln -sf ../pkgs/$mod/wwwroot wwwroot/$mod`
-9. 下划线→连字符软链接: `ln -sf pipeline-sdlc wwwroot/pipeline_sdlc`
-10. 修复 created_by: sed 注入 `ns['created_by'] = userorgid`
-11. 创建 runtime 目录
+2. build.sh 创建 `pkgs/` 目录并 `cd pkgs`，**将所有模块 git clone 进来**：
+   - 基础共享包：apppublic, sqlor, ahserver, rbac, xls2ddl, appbase, bricks-for-python, bricks
+   - 本项目业务模块：**必须先提交到远端仓库再 clone，禁止 mv/复制源码进 pkgs/**（模块开发完成即须推送远端，部署端只认远端仓库）
+3. 构建 bricks 前端: `cd pkgs/bricks/bricks && bash build.sh`（生成 ../dist）→ 应用目录 `ln -sf ../pkgs/bricks/dist wwwroot/bricks`
+4. `pip install` 所有 pkgs/ 模块（xls2ddl 提供 json2ddl/xls2ui/dbloader 三个 CLI，装进 venv 后 `${VENV}/bin/` 下可用）
+5. **逐模块执行四步安装**（见下节「模块安装四步」，每个业务模块都走一遍，顺序不可跳）
+6. 模块 wwwroot **软链接**（非 cp，四步③已含）: `ln -sf ../pkgs/$mod/wwwroot wwwroot/$mod`
+7. 下划线→连字符软链接: `ln -sf pipeline-sdlc wwwroot/pipeline_sdlc`
+8. 修复 created_by: sed 注入 `ns['created_by'] = userorgid`
+9. 创建 runtime 目录
+
+## 模块安装四步（每个业务模块必走，一键部署代码必须包含）
+
+模块代码到位后，逐个模块按以下四步安装，**任何一步失败即终止**（配合上方 fail-fast 约束）：
+
+```bash
+MOD=<模块名>   # 如 world
+# ① 建表：进 models 执行 json2ddl 生成 DDL → 建表
+cd "pkgs/${MOD}/models"
+"${VENV}/bin/json2ddl" mysql . > "/tmp/${MOD}_ddl.sql"
+mysql -h "${DB_HOST}" -P "${DB_PORT}" -u "${DB_USER}" -p"${DB_PASSWORD}" "${DB_NAME}" < "/tmp/${MOD}_ddl.sql"
+cd - >/dev/null
+
+# ② CRUD 页面：进 json 执行 build.sh（标准内容一行：
+#    xls2ui -m ../models -o ../wwwroot <模块名> *.json）
+cd "pkgs/${MOD}/json"
+bash build.sh
+cd - >/dev/null
+
+# ③ wwwroot 软链（非 cp）：ln -sf ../pkgs/${MOD}/wwwroot wwwroot/${MOD}
+ln -sf "../pkgs/${MOD}/wwwroot" "wwwroot/${MOD}"
+
+# ④ 初始化数据：模块有 data/*.xlsx 时用 dbloader 导入（无则跳过）
+if [ -d "pkgs/${MOD}/data" ] && ls pkgs/${MOD}/data/*.xlsx >/dev/null 2>&1; then
+  cd "pkgs/${MOD}/data"
+  for f in *.xlsx; do "${VENV}/bin/dbloader" "${DEPLOY_DIR}" "${DB_NAME}" "$f"; done
+  cd - >/dev/null
+fi
+```
+
+要点：
+- **①先于②**：xls2ui 生成页面时会读 models 定义，建表失败不拦住会让应用带缺表启动
+- **②的 json/build.sh 是模块仓库自带文件**（标准内容就一行 `xls2ui -m ../models -o ../wwwroot <模块名> *.json`），模块开发时就必须生成它，部署端只执行不现编
+- **④的 dbloader 参数**：`dbloader <应用部署目录> <库名> <xlsx文件>`，在模块 data/ 目录下逐个执行
+- 基础框架表（users/organization/role/permission 等）不在此四步内——它们在应用自己的 `scripts/ddl.sql` 里一次建好（全新库必备，否则 rbac 查询报错）
 
 ## 部署前置
 - 手工创建应用独立数据库（如 `CREATE DATABASE pipeline CHARACTER SET utf8mb4`）