docs: 补全README — 三模块/部署/配置完整文档

README.md

@@ -1,2 +1,125 @@
-# pipeline-app
+# Pipeline-App — 独立产线后端服务
 
+基于 ahserver 的独立产线管理后端，提供产线定义、运营管理和分销功能。
+
+## 架构
+
+- **部署模式**：独立 ahserver Web 应用（端口 9090）
+- **数据库**：`pipeline`（独立数据库，非 sage）
+- **认证**：复用 Sage RBAC（SAGE_RBAC_DB 环境变量指向 sage 库）
+- **模块数**：3 个业务模块
+
+## 业务模块
+
+### pipeline_core — 产线核心定义
+产线的创建、步骤编排和版本管理。
+
+| 表 | 说明 |
+|----|------|
+| `pipelines` | 产线主表（名称、描述、状态、owner） |
+| `pipeline_steps` | 步骤表（产线下的有序步骤，支持并行/串行） |
+| `pipeline_versions` | 版本表（产线快照，支持发布/回滚） |
+
+**API 端点**：pipelines/pipeline_steps/pipeline_versions 的 CRUD + pipeline_publish（发布版本）
+
+### pipeline_ops — 产线运营管理
+定价、供应量配置和使用记录。
+
+| 表 | 说明 |
+|----|------|
+| `pipeline_pricing` | 定价表（按产线+步骤+模型定价，单价/包量） |
+| `pipeline_capacity` | 供应量表（产线日/月配额，并发限制） |
+| `pipeline_usage_log` | 使用记录表（调用日志、用量统计） |
+
+**API 端点**：pricing/capacity/usage_log 的 CRUD + get_search_pipeline_id（下拉数据源）
+
+### pipeline_dist — 分销管理
+分销商管理和独立定价。
+
+| 表 | 说明 |
+|----|------|
+| `distributors` | 分销商表（名称、API 密钥、状态、配额） |
+| `distributor_pipeline` | 分销商-产线关联（独立定价、启用状态） |
+
+**API 端点**：distributors/distributor_pipeline 的 CRUD + generate_key（API 密钥生成）
+
+## 目录结构
+
+```
+pipeline-app/
+├── app/
+│   ├── pipeline_app.py          # ahserver 主入口
+│   └── global_func.py           # 全局函数（dbname 映射）
+├── conf/
+│   └── config.json              # 配置文件（端口/数据库/认证）
+├── pipeline_core/               # 产线核心模块
+│   ├── pipeline_core/           # Python 包
+│   ├── models/                  # 3 张表定义
+│   ├── json/                    # 3 个 CRUD 定义
+│   ├── wwwroot/                 # API 端点 + 前端
+│   ├── scripts/load_path.py     # RBAC 注册
+│   └── pyproject.toml
+├── pipeline_ops/                # 运营模块（同上结构）
+├── pipeline_dist/               # 分销模块（同上结构）
+├── build.sh                     # 构建脚本（venv + 依赖 + DDL + CRUD）
+├── start.sh / stop.sh           # 启停脚本
+└── README.md
+```
+
+## 部署步骤
+
+### 1. 创建数据库
+```sql
+CREATE DATABASE pipeline CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+### 2. 配置数据库密码
+编辑 `conf/config.json`，将数据库密码替换为实际值（当前为 `[REDACTED]`）。
+
+### 3. 构建
+```bash
+cd ~/test/pipeline-app
+bash build.sh
+```
+build.sh 会：创建 py3 venv → 安装依赖 → json2ddl 生成 DDL → xls2crud 生成 CRUD 界面
+
+### 4. 建表
+```bash
+# 每个模块分别生成并执行 DDL
+cd pipeline_core && ../py3/bin/json2ddl mysql models/ > mysql.ddl.sql
+cd pipeline_ops && ../py3/bin/json2ddl mysql models/ > mysql.ddl.sql
+cd pipeline_dist && ../py3/bin/json2ddl mysql models/ > mysql.ddl.sql
+# 在 MySQL 中执行所有 DDL
+```
+
+### 5. 初始化 RBAC
+```bash
+# 设置 SAGE_RBAC_DB 环境变量指向 sage 数据库
+export SAGE_RBAC_DB=sage
+# 运行各模块的 load_path.py
+cd pipeline_core && ../py3/bin/python scripts/load_path.py
+cd pipeline_ops && ../py3/bin/python scripts/load_path.py
+cd pipeline_dist && ../py3/bin/python scripts/load_path.py
+```
+
+### 6. 启动
+```bash
+cd ~/test/pipeline-app
+bash start.sh    # 启动服务（端口 9090）
+bash stop.sh     # 停止服务
+```
+
+## 技术要点
+
+- **数据库名**：所有模块共用 `pipeline` 数据库（通过 `global_func.py` 映射）
+- **sqlor API**：严格使用 `sor.C/U/D/R` 模式，`sor.U()` 只接受 2 个参数（id 在 data 字典中）
+- **dspy 规范**：零 import、零 print、零 uuid，使用预加载全局函数
+- **独立部署**：与 Sage 解耦，通过 HTTP API 对外提供服务
+- **分销密钥**：`distributor_generate_key.dspy` 生成随机 API 密钥供分销商调用
+
+## 文件统计
+
+- 数据表：8 张（core 3 + ops 3 + dist 2）
+- API 端点：29 个 dspy 文件
+- CRUD 管理：8 个（自动生成）
+- 总文件数：~80 个