@microi.net/cli 5.8.5 → 5.8.7

package/skills/v8-saas-multi-tenant/SKILL.md

@@ -1,305 +1,305 @@
----
-name: v8-saas-multi-tenant
-description: Microi V8 SaaS 多租户指南。用于处理租户隔离、主租户推广中心、按用户开通推广分享链接、匿名试用空库及 OsClient 三参数配置。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi V8 SaaS 多租户引擎
-
-你正在为 Microi 吾码平台编写多租户（SaaS）相关代码。每个租户使用独立数据库账号；Redis、对象存储、RabbitMQ、MQTT 和搜索集群可以共享基础设施，但必须使用租户命名空间与独立服务凭据，**所有 V8 代码都在租户上下文中运行**。
-
-## 核心概念
-
-Microi 多租户 = **`OsClient` + `OsClientType` + `OsClientNetwork`** 三参数模型：
-
-| 参数 | 说明 | 示例 |
-|------|------|------|
-| `OsClient` | 租户标识（系统Key） | `tenant_a`, `tenant_demo` |
-| `OsClientType` | 租户类型 | `Normal` / `App` / `Wechat` |
-| `OsClientNetwork` | 网络环境 | `Intranet`（内网）/`Outernet`（外网） |
-
-主租户不是固定字符串 `master`，而是由当前部署的环境变量 `OsClient` 或 `AppSettings:OsClient` 决定。租户记录存放在受保护的 `sys_osclients` 表中；普通业务角色和普通 V8 不得直接查询、复制或修改该表。
-
-标准 MCP 连接必须保持 API 与这三个租户坐标一致。`MICROI_OS_CLIENT_TYPE`、`MICROI_OS_CLIENT_NETWORK` 是 MCP 进程的可选连接配置，显式设置时必须绑定非空 `MICROI_OS_CLIENT`；它们随 Login 表单、Refresh 正文、所有 API Header 和流式 multipart 表单传输，普通 JSON 业务正文与 GET 查询不额外注入 Type/Network。省略可选项保持原协议。SSE 对应 `X-Microi-OsClient`、`X-Microi-OsClientType`、`X-Microi-OsClientNetwork`，每个连接独立绑定身份；单次请求与已配置坐标冲突、重复或含非法标识时发送前拒绝。
-
-连接或恢复后先执行 `initialize`、`tools/list`、`microi_get_status`，按服务端实际 API、OsClient、Type、Network 核验目标分区，再读基线或写入。Token 文件的四段键不能证明 HTTP 已选中该分区；不匹配时修复连接传输，不修改 SaaS 租户网络记录、跨分区借用身份或更换原业务请求键。
-
-API 必须指向目标分区的真实节点。三参数 Header 只声明连接目标，不能切换节点可信运行分区或发布门禁；Header 已正确而 status 仍不匹配时停止写入并修正节点地址，禁止修改 SaaS/gate、借其它分区任务或用请求头强迫节点切区。
-
-## 上下文变量
-
-```javascript
-V8.OsClient            // 当前租户标识，如 'tenant_demo'
-V8.OsClientType        // 'Normal' / 'App' / 'Wechat'
-V8.OsClientNetwork     // 'Intranet' / 'Outernet'
-V8.OsClientModel       // 当前租户 SaaS 配置的脱敏副本
-V8.ClientModel         // OsClientModel 的兼容别名，同样是脱敏副本
-V8.SysConfig           // 当前租户系统配置根对象；不存在 PublicSettings 属性
-```
-
-前端 V8 的 `V8.SysConfig` 是匿名 `GetSysConfig` 的独立脱敏 `sys_config` 副本；`mci_system_setting` 的任何记录都不会进入浏览器。后端接口引擎与后端 V8 事件的 `V8.SysConfig` 包含当前租户完整、独立的 `sys_config`，后端私密设置统一位于 `V8.SysConfig.ServerPrivateSettings`，其中 Secret 由可信后端解密。两端都不存在 `PublicSettings` 包装层。后端可使用 Secret，但严禁返回前端、写日志或写审计。子租户显式传其它 `OsClient` 仍会被强制改回当前租户。
-
-### V8.OsClientModel 常用字段
-
-```javascript
-V8.OsClientModel.SysTitle              // 租户系统标题
-V8.OsClientModel.DbType                // 非敏感数据库类型
-V8.OsClientModel.HDFS                  // 'Aliyun' / 'MinIO' / 'S3'
-V8.OsClientModel.AliOssPublicDomain    // 可公开的文件域名
-// 当前租户自行扩展的业务字段只作存量兼容；新增公开配置使用 sys_config，后端私密参数使用 mci_system_setting
-
-// 以下基础设施字段不会注入 V8：
-// DbConn / DbReadConn / AuthSecret
-// RedisHost / RedisPwd / MinIOSecretKey / AliOss*AccessKey*
-// MQHost / MQUserName / MQPassword / MqttPwd / SearchEngineApiKey
-```
-
-## 平台级配置与主租户规则
-
-### 推广中心与匿名空库开通
-
-- 主租户现有 `V8.FormEngine` 允许显式指定子租户；子租户被 `V8TenantContext.EnforceOsClient`
-  强制限制到自身。主租户业务员的业务范围须由接口引擎再次授权，不能仅凭主租户上下文放行全部租户。
-- SaaS 官方应用唯一拥有三个 Managed Key：`platform-saas-promotion`、`platform-saas-public-trial`、
-  `platform-saas-public-trial-worker`。内置微服务的 `/saas-promotion` 归系统引擎，公开 `/saas-trial`
-  仅固定主租户、固定应用可匿名解析，禁止用 src/appKey/routePath 查询参数扩大匿名宿主范围。
-- `V8.Method.AuthorizeSaasPromotion()` 仅绑定推广接口，重新读取有效账号、角色、菜单与管理角色。
-  默认业务员范围为 `ReferralUserId=当前sys_user.Id`；管理角色可读全局，平台管理员才可配置。
-  `V8.Method.ReadSaasTenantUsage({TenantIds,Refresh})` 只绑定同一接口，最多20个已授权子租户，无任意SQL或连接参数。
-- 统计使用目标库主库固定聚合，缓存60秒、刷新至少15秒、并行最多4库。缺失或失败显示未知，
-  近7/30天登录用户与日期分布来自 `LastLoginTime`，不能声称获得历史登录次数。旧租户归属和期限为空
-  时保持未分配/未登记；试用结束不代替许可证，也不自动停库。
-- `V8.Method.CreateSaasReferralCapability(linkId)` 只为授权推荐人或管理者签发绑定主租户与分区的链接票据。
-- `V8.Method.ResumeSaasPublicTrialTask(taskId)` 仅供同一推广接口的原推荐人或授权管理者恢复失败申请。
-  保留原幂等键和加密数据库检查点，最多执行三次；不得重新分配已有数据库账号密码。
-  公开空库使用主租户提供的启动地址，`DomainName` 保持未绑定，不能把含下划线的租户标识拼成独立域名。
-- 公开接口通过 `V8.Method.SaasPublicTrialAtom` 校验主配置、签名链接、推荐人、验证码和额度，冻结单向密码哈希
-  与受认证加密的限开通票据。Worker 设置 `StopHttp=1`，`V8.Method.ProvisionPublicSaasTrial` 验证固定Key、
-  持久任务身份与 fencing token，不接受伪造管理员。相同UUID和相同输入复用任务，不同输入拒绝。
-  DDL 前持久化加密账号检查点；强杀后恢复同一任务，已有账号必须使用检查点原凭据通过验证，禁止覆盖密码。
-  进度只用独立短期票据和安全结果投影，不能暴露连接、密码、任务正文或票据密钥。
-- 公开开关与额度字段 `SaasPublicTrial*`、管理角色 `SaasPromotionManagerRoleIds` 仅当前主租户分区有效；
-  推荐Id、请求Id、完成检查点、试用期限、联系与跟进字段不得从主租户复制给子租户。
-- `platform-saas-promotion-hook` 为 CreateIfMissing，仅 `BeforeCreateLink/Assign/UpdateFollowup` 脱敏事件。
-  不直接修改 Managed 接口保存个性化代码。更新 SaaS 应用和基础空库包两条链，并验证真实业务员、
-  管理员、匿名开库、同UUID重复提交、暂停后恢复及子租户越权，不以离线测试代替。
-- 复用标准 MCP `microi_get_db_schema`、`microi_add_field`、`microi_create_table_index`、`microi_create_engine`、
-  `microi_save_engine_code`、`microi_create_module`、`microi_run_engine` 及应用源码/流式发布工具；
-  先完整回读、计划和dryRun，再按已授权范围写入。已有推广Hook采用CreateIfMissing，不覆盖。
-
-#### 通过 AI + MCP 为指定用户开通推广链接
-
-用户说“为某个业务员创建推广链接”时，使用现有接口完成配置和签发，不创建一次性维护引擎，也不直接改推广表。先通过 `profiles` 选择用户自己的主租户连接，执行 `microi_get_status` 核对节点、主租户及 Type/Network；普通用户的主租户不固定为官方 iTdos。
-
-1. 用 `microi_get_engine_code` 完整读取 `platform-saas-promotion` 和 `platform-saas-public-trial`，有分页时拼齐并核对完整 SHA-256。再通过 `microi_run_engine` 执行 `{Action:'Bootstrap'}`，读取 `Actor/Users/Settings/Roles`，确认当前会话有创建权限。按准确 Account 或 Id 解析活跃推荐人；姓名重名时先澄清，禁止猜测用户 Id。管理员可以为活跃用户创建，业务员默认只为自己创建。
-2. 执行 `{Action:'Links'}`，先查该推荐人的活动。已有符合请求且启用、未过期的链接可复用，保留其他活动与业务数据。只有平台管理员的 `Actor.CanConfigure=true` 才能配置公开开通。配置缺失且用户已授权启用时，通过 `SaveSettings` 写入真实主租户前端 HTTPS 地址；不要把 API 域名、临时测试端口或别人的平台地址当成 WebBase。仅创建链接不隐含修改已经设定的开通策略。
-
-   ```javascript
-   // microi_run_engine：apiEngineKey='platform-saas-promotion'
-   // params 为下列对象；confirmExecution 使用同一 ApiEngineKey。
-   { Action:'SaveSettings', Enabled:true, WebBase:'https://<主租户前端域名>',
-     TrialDays:14, DailyLimit:20, LinkLimit:50, ManagerRoleIds:[] }
-   ```
-
-   上例为未配置时的默认值。已有试用天数、每日额度、单链接额度和管理角色应从 Bootstrap 回读并保留，除非用户明确要求调整；`ManagerRoleIds` 使用真实角色 Id 数组。保存后再次 Bootstrap 核对本分区配置。
-3. 无合适活动时执行下列请求。`ReferralUserId` 必须来自第 1 步的权威用户目录；业务员额度和试用天数不能超过主租户设定值。
-
-   ```javascript
-   { Action:'CreateLink', Title:'<推广活动名称>', ReferralUserId:'<sys_user.Id>',
-     TrialDays:14, MaxTenants:50, ValidDays:30, Remark:'<可选活动说明>' }
-   ```
-
-   创建超时先按推荐人、活动名称和时间回读 Links，确认是否已创建；禁止盲目重试导致重复活动。取得 `Data.Id` 后执行 `{Action:'ShareLink', Id:'<活动Id>'}`，返回 `Data.Url` 才是可分享地址。不要手拼 `ref=<用户Id>` 或将活动 Id 代替 `LinkToken`；票据绑定推荐人、活动、运行分区、到期时间和版本。切换链接启停状态会撤销旧地址，之后需重新签发。
-4. 回读 Links 核对归属、启用状态、期限、试用天数和额度。在全新、未登录的浏览器 context 打开 `Data.Url`，核对匿名 `platform-saas-public-trial` 的 Bootstrap 成功、表单与图形验证码可用。验收链接不需要实际创建客户租户；只有明确授权开库后才提交真实申请，并按同一 RequestId 回读任务、租户归属和登录地址，保留幂等及精确清理证据。
-
-最终交付可点击的分享地址、推荐人、试用天数、链接到期时间及额度，并区分“链接已可访问”和“客户租户已实际开通”。若接口不存在或平台版本不足，走官方 SaaS 应用与内置微服务更新，不通过临时 SQL 绕过鉴权。
-
-制作空数据库时，角色、账号绑定和权限快照必须作为同一初始模板处理。只保留明确声明的初始角色，按权威角色重建保留账号的 `RoleIds` 与等级；删除业务角色及孤立菜单权限，清空包含源业务菜单的角色权限快照。初始角色缺失、删除或等级不符时停止制作，不得根据账号现有角色列表、角色名称或高等级推测哪些角色应保留。
-
-组织数据属于同一空库模板边界：只保留明确声明的初始组织和部门，将保留账号的部门绑定与名称同步归一，并清理旧版账号关系表。保护这些平台表的物理结构，初始组织缺失或已删除时停止制作；验收必须在新租户查看真实组织树，不能只检查角色数量。清理只能作用于制作过程的隔离副本。
-
-安装历史只有能对应保留平台应用的稳定身份才可继承：非空 `StoreId` 优先，旧记录没有该字段时再核对非空应用身份；不能凭名称或前缀保留孤立记录。SQL 预览、临时副本执行、公开空库文件更新与新租户登录验收是不同证据层；源主库和既有测试租户都不能作为清理执行目标。
-
-主库 `sys_osclients` 保存租户数据库/Redis/存储路由及影响整个 API 进程的平台级配置；目标租户建立上下文后，`sys_config` 和 `mci_system_setting` 从该租户自己的数据库读取。平台级配置必须遵守“主租户为准、子租户只能降额隔离”的规则：
-
-- 所有可变业务逻辑默认必须由接口引擎编排，包括但不限于租户开通、开库、初始化、归属修复、官网个人中心、付费额度等 SaaS 业务流程。C# 后端只暴露原子 V8 能力，例如建库、导入空库模板、复制 `sys_config`、刷新 SaaS 缓存、补偿回滚、字段兜底等；不要把可变业务分支写死到 Controller 或 `TenantProvisioningService` 这类后端定制代码里。接口引擎缺少能力时，优先扩展 `V8.Method`/V8 引擎原子函数，再由接口引擎调用。
-- 官方租户开通固定由 SaaS 包的 `platform-create-tenant` 编排：`platform-runtime-custom-hook` 的 Before 阶段可以阻断，`AuthorizeCurrentUserTenantProvisioning` / `ProvisionCurrentUserTenant` 只从可信主租户 DiyToken 派生所有者与密码材料；创建完成后的 Hook/审计失败只能返回 Warning，不能诱导重复创建。系统账号偏好/资料与租户系统设置分别由 `app.microi.sys_user`、`app.microi.sys-config` 单一拥有，SaaS/Store 不得复制这些 Managed ApiEngineKey。
-- 租户开库失败时，先核对编排 `OsClientDbConn` 的真实账号与权限。业务库账号通常不能开库、创建用户或授权；应使用已有正确授权的管理账号更新编排，不通过 SQL/MCP 手工修复业务数据库。管理员页面必须同时显示中文原因、失败阶段、可执行的处理方法，以及可展开且已脱敏的原始异常链；区分密码/来源认证失败与数据库权限不足，不能只显示笼统失败或隐藏驱动原始错误。
-- 旧版 UniApp 的 `microi-init` 是 SaaS 包继续托管的 Managed 兼容门面。匿名阶段只组合 `platform-os-client-by-domain` 与 `platform-sys-config` 的公开投影；原始 DiyToken 必须由 `GetCurrentToken` 和 `RefreshLoginUser(..., rawToken)` 在后端重新验证且绑定当前租户，菜单再由只允许该固定 Key 调用的 `GetLegacyInitMenuTree(rawToken, osClient?)` 复用 `SysMenuLogic` 权威角色过滤。禁止在匿名 V8 中直接通过 FormEngine 读取 `sys_menu`；域名解析到其它租户时返回目标 `OsClient` 并要求重试，禁止匿名跨租户读取配置或菜单。
-- 主租户由运行环境决定：优先读取环境变量 `OsClient`，其次读取 `appsettings.json` 的 `AppSettings:OsClient`。只有这条主租户 `sys_osclients` 数据中的平台级字段会作为全局配置生效。
-- 同一个主租户可以同时运行在 `Product/Internal`、`Product/Internet` 等多个分区；租户目录、后台任务领取、通知和批量平台应用维护都必须按当前节点的 `OsClientType + OsClientNetwork` 隔离。一次全量维护只证明当前分区，事故恢复必须先盘点所有活跃分区，再从各分区对应节点分别执行并等待 `SucceededCount=ExpectedCount、FailedCount=0`，随后各自以新幂等键做零安装／零更新复跑。禁止临时改租户网络字段、跨分区借用任务或并发维护可能指向同一物理库的重复租户记录。
-- 大范围启动事故只允许受信后台编排器使用 `MaintenanceScope=StartupDependencies`，精确闭包固定为 `app.microi.store + app.microi.saas-engine`，并可显式启用 `StartupDependencyBootstrapOnly=true`。编排器必须先用权威当前分区目录校验 `TargetOsClients`，再在子任务仍为 `Pending` 时原子写入并强回读两应用范围与只自举标志；失败即取消，禁止退化为完整安装。工作器只从官方不可变包补齐 `platform-sys-menu` 和六项 SaaS 启动门面，七项物理契约强回读通过后终止，不写安装版本。该模式只恢复可登录性，不代表 API 进程的完整运行时已经就绪；新版后端接收流量前还必须从九个内置官方基础应用包补齐并回读全部接口引擎，后续完整应用更新仍走普通商城任务。未带标志的任务行为不得改变。
-- API 启动配置只有十项白名单：`OsClient`、`OsClientType`、`OsClientNetwork`、`OsClientDbType`、`OsClientDbConn`、`OsClientRedisHost`、`OsClientRedisPort`、`OsClientRedisPwd`、`OsClientRedisDataBase`、`OsClientDbMongoConn`。除这十项外，部署/节点级运行参数与基础设施秘密从主控 `sys_osclients` 读取；允许子租户自行维护且需要浏览器判断的业务开关、入口显示和公开交互配置使用该租户 `sys_config` 实体字段，OAuth/第三方集成的凭据、RP/Origin/Issuer/Scope 与仅后端参数使用 `mci_system_setting`，未配置时使用代码安全默认值。官方 License 恢复次数/间隔与固定私钥挂载 `/app/microi_private.pem` 是信任链例外。禁止再增加 `MICROI_*`、`DOS_ORM_*`、自定义 `AppSettings` 节点或动态名称的环境变量读取。节点身份由平台自动生成。
-- 存量畅捷通/微信 OAuth C# 协议网关有一组已发布到 SaaS 引擎的兼容字段：`OAuthReturnUrlOrigins`、`ChanjetOAuthState`、`ChanjetAesKey`、`ChanjetAppKey`、`WeChatTemplateAppId`、`WeChatTemplateAppSecret`、`WeChatTemplateId`、`WeChatMiniProgramAppId`。只能通过 Core 的租户绑定协议设置原子按请求权威 `OsClient` 读取，禁止使用主租户 `ConfigHelper` RuntimeConfigurationReader；整组字段不得复制给新租户，其中 OAuthState/AES Key/AppKey/AppSecret 不得进入 `V8.OsClientModel` 或前端投影且必须在审计中掩码。新集成不得继续扩展该兼容集合，仍使用当前租户 `mci_system_setting` + Managed ApiEngine。
-- `ASPNETCORE_*`、`DOTNET_*` 仅用于 .NET 宿主；构建、安装、测试、MCP、发布脚本可使用自身进程变量，但 API 生产代码不得把它们当业务配置。新增 SaaS 运行字段必须配套独立或既有 Tab、幂等升级、缓存刷新、敏感字段脱敏、子租户不继承和源码扫描测试。
-- 文件上传的租户业务开关与额度按“当前租户 `sys_osclients` → 代码默认值”解析；现行负向字段 `DisableFileUpload` 默认关闭/空值即允许上传，只有 `1/true` 才禁止。旧 `FileUploadEnabled` 只在新物理字段尚不存在的滚动升级节点回退读取，并须在新版 SaaS 表单隐藏。平台固定灾难保护、HTTP/Multipart/Form 和反向代理上限不可由租户覆盖，也不要求安装者维护额外上传环境变量。
-- 类似 MQTT 端口、PressureGuard、V8Limits、OrmLimits、StartupLimits、SecurityGuard 这类影响整进程资源的配置，不能让每个子租户各自抬高全局上限。子租户同名隔离字段只能降低自己的并发、等待时间或资源额度，用于隔离弱租户、试用租户或异常租户。
-- 修改 `sys_osclients` 的表、字段、数据源或配置值后，必须刷新 SaaS 引擎运行缓存，并回读验证字段 `Component`、`Data`、`Config`、实际数据值和前端真实消费结果。不要只看 MCP 写入成功。
-- SaaS 配置只在启动、管理员保存 `sys_osclients` 或显式租户刷新时发布到共享 Redis。初始化数据库会话、创建 `V8.Dbs` 运行态对象、普通 FormEngine 请求和表单设计器保存不得冒充配置变更反复发布。
-- JWT Key 由可信后端生成并持久化；SaaS 表单只读显示配置状态，不允许普通表单或 V8 写入 `AuthSecret`。手动接入旧库的 NULL/空白值必须支持原子写回，多节点竞争后回读持久胜者；重复刷新不能轮换有效 Key。只读状态查询不得初始化目标租户数据库。验收只记录是否已配置、是否稳定，不输出密钥原文。
-- 扩展库缓存必须区分“尚未加载”和“已加载但为 0 条”；后者是有效结果。没有配置 `microi_database` 的租户不能在每次 V8 执行时重复查询、调用 `AddOrUptClient` 或打印“缓存 OsClient 配置到 Redis”。
-- 多节点的缓存失效订阅只做本节点失效与数据库回源，禁止收到消息后再次发布形成回声。进程内初始化标记仅是可丢失优化，真正租户配置仍以共享数据库/Redis 为准。
-- 新增平台级字段时，字段名建议保持英文稳定，例如 `PressureGlobalMaxConcurrentRequests`、`PressureV8MaxConcurrentExecutions`、`PressureOrmMaxConcurrentConnectionOpens`；字段标签和说明必须中文，说明中写清楚“主租户有效/子租户仅可降低”。
-- 新租户记录不得复制主租户的数据库、鉴权、Redis/对象存储密钥或 MQ/MQTT/Search 凭据。共享基础设施地址与管理密钥只在服务端运行时解析，不持久化到子租户记录，也不进入 V8 投影。
-- RabbitMQ 子租户必须使用独立 user/vhost/ACL，MQTT 必须使用独立账号密码，Search 必须使用限制到 `{osClient}_*` 的 API Key/用户。外部资源尚未真实创建时保持空凭据并失败关闭，禁止把主租户管理员凭据复制过去冒充完成。
-- `V8.Cache`、`V8.HDFS`、RabbitMQ、MQTT、Search 分别强制 `Microi:{OsClient}:*`、`/{osClient}/...`、`microi.{osClient}.*`、`tenant/{osClient}/...`、`{osClient}_*` 命名空间。body/query 中的 `OsClient` 不能覆盖登录 Token 或 V8 上下文。
-
-## 接口调用区分租户的三种方式
-
-### 方式 1：Token 自动识别（最常用）
-
-请求头携带 `Token`，平台自动识别用户所属租户。
-
-```bash
-GET /apiengine/get-products
-Token: xxx-token-xxx
-```
-
-### 方式 2：URL 参数
-
-```bash
-GET /apiengine/get-products?OsClient=tenant_demo
-```
-
-### 方式 3：特殊 URL 格式（无 Token、无参数）
-
-```bash
-GET /apiengine/get-products--OsClient--tenant_demo--
-GET /apiengine/get-products--OsClient--tenant_demo--OsClientType--App--
-```
-
-> 适用于第三方回调（无法添加 Header）、支付/微信回调等场景。
-
-## 跨租户操作（仅可信控制面）
-
-普通 V8 的 `FormEngine`、`DataSourceEngine`、`TranslateEngine`、`WFEngine`、`Cache`、`HDFS`、MQ/MQTT、Search 和 `Dbs` 都必须绑定当前 Token/V8 上下文中的 `OsClient`。请求 body/query 里传入其它租户不能切换连接，也不能读取其它租户凭据。
-
-租户开通、迁移、备份或平台管理员代维只能走明确的控制面服务/接口引擎：
-
-- 调用者必须是 `Level >= 9999`，并再次校验目标租户白名单和操作类型；
-- 使用专用原子能力，不通过通用 FormEngine 读取完整 `sys_osclients` 记录；
-- 不把数据库、认证、Redis、存储、MQ/MQTT、搜索等连接与密钥投影进 V8；
-- 每次操作写安全审计、幂等键和补偿状态，并对目标租户回读验收；
-- 多节点部署使用共享租约和业务幂等，不能依赖进程静态锁。
-
-### SaaS 数据库 ZIP 开库的进度与租约
-
-通过 SaaS 引擎上传数据库 ZIP 创建租户时，必须把上传和还原建模为两个独立阶段：
-
-- 上传使用分片会话并显示真实字节进度；暂停或网络中断后复用同一文件指纹续传，不能把上传百分比冒充数据库导入进度。
-- 上传完成后提交平台持久后台任务。租户开通进度总数使用后端共享契约的固定 13 步，接口引擎、可信宿主原子和前端不得各自维护不同分母。
-- 第 2 步是数据库 ZIP 校验与还原。该阶段应按真实 SQL 读取量推进总百分比，并显示已读取/总字节、SQL 百分比、已执行语句数、当前批次与语句类型、平均吞吐和动态预计剩余时间；不能长时间只显示静态的 `2 / 13`。
-- 进度状态仅在距上次更新约 2 秒或新增约 16MB 数据时刷新；执行日志只记录阶段里程碑和 SQL 每跨过约 5% 的进度，前端只渲染最近 200 条。禁止按 SQL 行或每条语句推送日志，避免几十万条数据把共享任务表、SignalR 或浏览器 DOM 拖垮。
-- 页面同时显示服务端心跳。单个百分比短时不变不等于卡死，应综合心跳、字节、语句数、批次和消息判断；失败、取消或中断必须保留最后真实进度和错误原因，只有成功终态才算开库完成。
-
-租户开库使用平台可信后台上下文中的可续租共享锁：`Timeout` 是单次 Redis 租期，当前开库最长保护边界为 12 小时。普通 HTTP/V8 请求传入 `_BackgroundTaskId`、`_TrustedServerInvocation` 或伪造用户对象不能开启续租。持有者令牌不匹配、锁过期、Redis 所有权/续租确认失败或达到最长租约都必须失败关闭并停止推进；不能为了避免报错而把真实锁丢失降级成成功或 Warning。
-
-自动续租只解决“正常长任务不因短 TTL 自然过期”，不能代替业务幂等、检查点、补偿状态和 fencing token。大库导入完成但域名绑定未完成时，应保留已经成功创建的租户和数据库，进入明确的域名补偿状态；不能因数据面域名失败重新导入整个数据库。接口引擎的通用锁配置读取 `../v8-api-config/SKILL.md`，长任务按钮和检查点读取 `../v8-menu-buttons/references/progressive-02-8-模式-f-后台任务按钮-长任务.md`。
-
-## 缓存按租户隔离
-
-```javascript
-// 推荐传逻辑 Key；服务端自动添加当前租户前缀
-var key = 'Product:' + V8.Param.id;
-V8.Cache.Set(key, value, 600);
-
-// 完整当前租户 Key 继续兼容
-var fullKey = 'Microi:' + V8.OsClient + ':Product:' + V8.Param.id;
-
-// 其它租户的 Microi: 前缀会被服务端拒绝
-```
-
-## 接口引擎中针对不同租户走不同逻辑
-
-```javascript
-// 租户差异应来自当前租户的非敏感业务配置，不要硬编码某个“主租户”字符串
-if (V8.OsClientModel.OrderApprovalMode === 'Direct') {
-  V8.FormEngine.UptFormData('Order', { Id: id, Status: 'Approved' });
-} else {
-  await V8.WFEngine.StartWork({ FlowDesignId: 'order-flow', TableRowId: id });
-}
-
-// App 端 vs PC 端不同返回
-if (V8.OsClientType === 'App') {
-  return { Code: 1, Data: simplifiedList };
-}
-return { Code: 1, Data: fullList };
-
-// 内网外网走不同 ERP 网关
-var erpUrl = (V8.OsClientNetwork === 'Intranet')
-  ? 'http://192.168.1.10/erp/api'
-  : 'https://erp.public.com/api';
-```
-
-## 第三方密钥放租户动态设置（不要硬编码）
-
-```javascript
-// ❌ 危险：密钥写在代码里，所有租户共用，无法独立轮换
-var ak = 'AKIDxxxxxxxx';
-
-// ✅ 浏览器需要判断的开关：使用 sys_config 实体字段
-var giteeEnabled = V8.SysConfig.GiteeLoginEnabled === 1;
-
-// ✅ 后端 V8 可读取当前租户 Secret 并直接调用供应商
-var privateSettings = V8.SysConfig.ServerPrivateSettings || {};
-var secret = privateSettings['Login.Gitee.ClientSecret'];
-// 禁止 return secret、console.log(secret) 或写入前端可读字段。
-```
-
-> `mci_system_setting` 位于每个租户自己的数据库，只保存不能公开或仅供后端执行的配置；普通值与 Secret 都不会下发浏览器。Secret 保存认证密文，只在后端 V8 的当前租户 `ServerPrivateSettings` 中解密使用。能力开关和入口显示必须建成 `sys_config` 实体字段，禁止通过 `IsPublic` 或其它运行时勾选把私密记录公开。前端 V8、普通 FormEngine HTTP、匿名/访问密钥会话不能读取私密设置，后端 V8 也不能获得通用解密器。`sys_osclients` 自定义业务字段只保留存量兼容；共享基础设施字段由服务端强制移除，不能用自定义同义字段绕过安全代理。
-
-## 用户扩展字段访问（同理）
-
-平台 `sys_user` 也由表单引擎驱动。如给 `sys_user` 添加 `Wife` 字段：
-
-```javascript
-// V8 代码中可访问
-V8.CurrentUser.Wife;
-
-// SQL 数据源中可访问
-SELECT * FROM Contact WHERE OwnerId = $CurrentUser.Id$ AND Spouse = $CurrentUser.Wife$
-```
-
-## 常见错误
-
-- 旧库升级的内置应用包包含定时任务时，升级内核按“资源独立提交 → 幂等保存并回读 Quartz/任务元数据 → 确认安装版本”执行。仅程序集白名单包及不可伪造的宿主授权可进入该兼容流程；普通应用安装仍必须使用持久后台任务分片。任一阶段失败不推进 ServerVersion，修复后从原升级入口重试，不手动抬高版本或伪造任务信封。
-
-❌ 绕开 `V8.Cache` 使用底层 Redis → 租户数据串号（V8 已不再暴露底层句柄）
-❌ MongoDB DbName 不带 OsClient → 数据混淆  
-❌ 把 OsClientModel 字段直接返回给前端 → 密钥泄漏  
-❌ 查询 `mci_system_setting.SecretCipher` 或给 V8 暴露通用解密器 → 密钥边界失效  
-❌ 在前端硬编码 OsClient → 一改全改，应通过 token/URL 自动识别  
-❌ 跨租户操作不验证当前用户权限 → 越权风险  
-❌ 子租户缺少 MQ/MQTT/Search 独立凭据时回退主账号 → 全平台越权
-
-## 检查清单
-
-- 子租户授权使用官方 SaaS 应用的 `sys_osclients.LicenseProductType` 与 `LicenseExpirationDate`（UTC）字段；两项留空继承主授权。只允许主租户超级管理员设置，不能超过已验签主授权的版本和日期；运行时再次裁剪。两项不得通过主配置合并自动复制到子租户。不要在可编辑 V8 里代替可信授权边界。
-- 授权到期文案和提前天数在消息通知页设置。官方与主租户策略分别触发，不能因官方已触发或未触发而跳过主租户检查。签发帐号 `sys_user.LicenseExpirationDate` 未设置表示永久有效，但可签发版本及请求日期仍需校验。
-
-- [ ] 缓存只通过 `V8.Cache` 使用逻辑 Key 或当前租户完整 Key
-- [ ] 所有 MongoDB DbName 都包含 `V8.OsClient`
-- [ ] 当前租户自有的业务集成密钥可放 `V8.OsClientModel`，共享 Redis/存储/MQ/MQTT/Search 凭据只能由服务端托管
-- [ ] 跨租户操作前校验权限
-- [ ] 不向前端返回 `V8.OsClientModel`
-- [ ] 子租户数据库账号只授权本租户库，MQ/MQTT/Search 独立凭据已真实创建
-- [ ] 文件、队列、Topic、索引均由服务端规范为当前租户命名空间
-- [ ] 无扩展库租户重复执行 V8 时不会重复刷新 SaaS 配置；真实 `sys_osclients` 保存后各节点能按租户失效并回源
-- [ ] ZIP 开库区分上传与还原进度，使用固定 13 步、低频明细、服务端心跳和有界日志
-- [ ] 开库锁只由可信持久后台任务自动续租；真实租约丢失失败关闭，所有副作用仍具备幂等、检查点和 fencing token
-
-## Microi.AI 中转站租户凭据
-
-- `mic_ai` 的 `Microi.AI中转站.ApiKey` 是租户调用吾码官方中转站的用户凭据。运行时不得因为该字段为空而静默创建、回退到当前用户字段或绕过校验，否则管理员无法判断真实配置来源。
-- 老租户由用户在吾码官网个人中心复制 ApiKey 后填写到本租户的 `mic_ai` 中转站记录；空值应返回明确配置错误。
-- 官网创建新 SaaS 租户时，必须先取得当前官网账号的 ApiKey，再由租户初始化服务写入新库 `mic_ai` 的 `Microi.AI中转站` 记录。该自动写入只发生在受控开库流程，不得散落到普通 AI 对话请求中。
-- 开库入口把 ApiKey 传给后台 worker 后，worker 还必须继续显式传入最终的原子初始化方法；不能只在父接口或中间参数中“带过”。每个异步/后台边界都应对空值立即失败，避免租户创建成功但 `mic_ai.ApiKey` 静默为空。
-- 自动化验收必须通过新租户 `admin` 登录回读 `mic_ai`，只输出“非空、长度、与官网账号 ApiKey 是否一致”等布尔结果，不得把真实 ApiKey 写入日志、截图或测试报告。
-- 中转模型公开目录只返回模型 Id、显示名、厂商等非敏感字段，可匿名读取；严禁把官方上游模型的 ApiKey、Endpoint 私密配置随模型列表返回前端。
-
-### 旧结构空库制作验收
-
-空库脱敏生成器应只读实际物理列；组织机构旧表缺少可选父级名称列时，只写已有父级 Id，不为制作模板修改主库结构。物理字段发现失败应在输出清理 SQL 前失败关闭。验收同时覆盖有该列、缺少该列及读取失败，最终检查隔离副本和官方空库下载包。
-
-应用文件与版本清理不得在 MySQL 5.7 的 DELETE 外连接中用 `Id = AppId OR AppKey = AppId`。先在隔离副本内物化带主键的 Id/AppKey 保留集合，分别覆盖当前商城 Id、历史 AppKey、业务应用、孤立记录与 NULL；验证新旧结果一致，源主库只读。真实 SQL 耗时与 Node 生成器测试需分别记录。
+---
+name: v8-saas-multi-tenant
+description: Microi V8 SaaS 多租户指南。用于处理租户隔离、主租户推广中心、按用户开通推广分享链接、匿名试用空库及 OsClient 三参数配置。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi V8 SaaS 多租户引擎
+
+你正在为 Microi 吾码平台编写多租户（SaaS）相关代码。每个租户使用独立数据库账号；Redis、对象存储、RabbitMQ、MQTT 和搜索集群可以共享基础设施，但必须使用租户命名空间与独立服务凭据，**所有 V8 代码都在租户上下文中运行**。
+
+## 核心概念
+
+Microi 多租户 = **`OsClient` + `OsClientType` + `OsClientNetwork`** 三参数模型：
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `OsClient` | 租户标识（系统Key） | `tenant_a`, `tenant_demo` |
+| `OsClientType` | 租户类型 | `Normal` / `App` / `Wechat` |
+| `OsClientNetwork` | 网络环境 | `Intranet`（内网）/`Outernet`（外网） |
+
+主租户不是固定字符串 `master`，而是由当前部署的环境变量 `OsClient` 或 `AppSettings:OsClient` 决定。租户记录存放在受保护的 `sys_osclients` 表中；普通业务角色和普通 V8 不得直接查询、复制或修改该表。
+
+标准 MCP 连接必须保持 API 与这三个租户坐标一致。`MICROI_OS_CLIENT_TYPE`、`MICROI_OS_CLIENT_NETWORK` 是 MCP 进程的可选连接配置，显式设置时必须绑定非空 `MICROI_OS_CLIENT`；它们随 Login 表单、Refresh 正文、所有 API Header 和流式 multipart 表单传输，普通 JSON 业务正文与 GET 查询不额外注入 Type/Network。省略可选项保持原协议。SSE 对应 `X-Microi-OsClient`、`X-Microi-OsClientType`、`X-Microi-OsClientNetwork`，每个连接独立绑定身份；单次请求与已配置坐标冲突、重复或含非法标识时发送前拒绝。
+
+连接或恢复后先执行 `initialize`、`tools/list`、`microi_get_status`，按服务端实际 API、OsClient、Type、Network 核验目标分区，再读基线或写入。Token 文件的四段键不能证明 HTTP 已选中该分区；不匹配时修复连接传输，不修改 SaaS 租户网络记录、跨分区借用身份或更换原业务请求键。
+
+API 必须指向目标分区的真实节点。三参数 Header 只声明连接目标，不能切换节点可信运行分区或发布门禁；Header 已正确而 status 仍不匹配时停止写入并修正节点地址，禁止修改 SaaS/gate、借其它分区任务或用请求头强迫节点切区。
+
+## 上下文变量
+
+```javascript
+V8.OsClient            // 当前租户标识，如 'tenant_demo'
+V8.OsClientType        // 'Normal' / 'App' / 'Wechat'
+V8.OsClientNetwork     // 'Intranet' / 'Outernet'
+V8.OsClientModel       // 当前租户 SaaS 配置的脱敏副本
+V8.ClientModel         // OsClientModel 的兼容别名，同样是脱敏副本
+V8.SysConfig           // 当前租户系统配置根对象；不存在 PublicSettings 属性
+```
+
+前端 V8 的 `V8.SysConfig` 是匿名 `GetSysConfig` 的独立脱敏 `sys_config` 副本；`mci_system_setting` 的任何记录都不会进入浏览器。后端接口引擎与后端 V8 事件的 `V8.SysConfig` 包含当前租户完整、独立的 `sys_config`，后端私密设置统一位于 `V8.SysConfig.ServerPrivateSettings`，其中 Secret 由可信后端解密。两端都不存在 `PublicSettings` 包装层。后端可使用 Secret，但严禁返回前端、写日志或写审计。子租户显式传其它 `OsClient` 仍会被强制改回当前租户。
+
+### V8.OsClientModel 常用字段
+
+```javascript
+V8.OsClientModel.SysTitle              // 租户系统标题
+V8.OsClientModel.DbType                // 非敏感数据库类型
+V8.OsClientModel.HDFS                  // 'Aliyun' / 'MinIO' / 'S3'
+V8.OsClientModel.AliOssPublicDomain    // 可公开的文件域名
+// 当前租户自行扩展的业务字段只作存量兼容；新增公开配置使用 sys_config，后端私密参数使用 mci_system_setting
+
+// 以下基础设施字段不会注入 V8：
+// DbConn / DbReadConn / AuthSecret
+// RedisHost / RedisPwd / MinIOSecretKey / AliOss*AccessKey*
+// MQHost / MQUserName / MQPassword / MqttPwd / SearchEngineApiKey
+```
+
+## 平台级配置与主租户规则
+
+### 推广中心与匿名空库开通
+
+- 主租户现有 `V8.FormEngine` 允许显式指定子租户；子租户被 `V8TenantContext.EnforceOsClient`
+  强制限制到自身。主租户业务员的业务范围须由接口引擎再次授权，不能仅凭主租户上下文放行全部租户。
+- SaaS 官方应用唯一拥有三个 Managed Key：`platform-saas-promotion`、`platform-saas-public-trial`、
+  `platform-saas-public-trial-worker`。内置微服务的 `/saas-promotion` 归系统引擎，公开 `/saas-trial`
+  仅固定主租户、固定应用可匿名解析，禁止用 src/appKey/routePath 查询参数扩大匿名宿主范围。
+- `V8.Method.AuthorizeSaasPromotion()` 仅绑定推广接口，重新读取有效账号、角色、菜单与管理角色。
+  默认业务员范围为 `ReferralUserId=当前sys_user.Id`；管理角色可读全局，平台管理员才可配置。
+  `V8.Method.ReadSaasTenantUsage({TenantIds,Refresh})` 只绑定同一接口，最多20个已授权子租户，无任意SQL或连接参数。
+- 统计使用目标库主库固定聚合，缓存60秒、刷新至少15秒、并行最多4库。缺失或失败显示未知，
+  近7/30天登录用户与日期分布来自 `LastLoginTime`，不能声称获得历史登录次数。旧租户归属和期限为空
+  时保持未分配/未登记；试用结束不代替许可证，也不自动停库。
+- `V8.Method.CreateSaasReferralCapability(linkId)` 只为授权推荐人或管理者签发绑定主租户与分区的链接票据。
+- `V8.Method.ResumeSaasPublicTrialTask(taskId)` 仅供同一推广接口的原推荐人或授权管理者恢复失败申请。
+  保留原幂等键和加密数据库检查点，最多执行三次；不得重新分配已有数据库账号密码。
+  公开空库使用主租户提供的启动地址，`DomainName` 保持未绑定，不能把含下划线的租户标识拼成独立域名。
+- 公开接口通过 `V8.Method.SaasPublicTrialAtom` 校验主配置、签名链接、推荐人、验证码和额度，冻结单向密码哈希
+  与受认证加密的限开通票据。Worker 设置 `StopHttp=1`，`V8.Method.ProvisionPublicSaasTrial` 验证固定Key、
+  持久任务身份与 fencing token，不接受伪造管理员。相同UUID和相同输入复用任务，不同输入拒绝。
+  DDL 前持久化加密账号检查点；强杀后恢复同一任务，已有账号必须使用检查点原凭据通过验证，禁止覆盖密码。
+  进度只用独立短期票据和安全结果投影，不能暴露连接、密码、任务正文或票据密钥。
+- 公开开关与额度字段 `SaasPublicTrial*`、管理角色 `SaasPromotionManagerRoleIds` 仅当前主租户分区有效；
+  推荐Id、请求Id、完成检查点、试用期限、联系与跟进字段不得从主租户复制给子租户。
+- `platform-saas-promotion-hook` 为 CreateIfMissing，仅 `BeforeCreateLink/Assign/UpdateFollowup` 脱敏事件。
+  不直接修改 Managed 接口保存个性化代码。更新 SaaS 应用和基础空库包两条链，并验证真实业务员、
+  管理员、匿名开库、同UUID重复提交、暂停后恢复及子租户越权，不以离线测试代替。
+- 复用标准 MCP `microi_get_db_schema`、`microi_add_field`、`microi_create_table_index`、`microi_create_engine`、
+  `microi_save_engine_code`、`microi_create_module`、`microi_run_engine` 及应用源码/流式发布工具；
+  先完整回读、计划和dryRun，再按已授权范围写入。已有推广Hook采用CreateIfMissing，不覆盖。
+
+#### 通过 AI + MCP 为指定用户开通推广链接
+
+用户说“为某个业务员创建推广链接”时，使用现有接口完成配置和签发，不创建一次性维护引擎，也不直接改推广表。先通过 `profiles` 选择用户自己的主租户连接，执行 `microi_get_status` 核对节点、主租户及 Type/Network；普通用户的主租户不固定为官方 iTdos。
+
+1. 用 `microi_get_engine_code` 完整读取 `platform-saas-promotion` 和 `platform-saas-public-trial`，有分页时拼齐并核对完整 SHA-256。再通过 `microi_run_engine` 执行 `{Action:'Bootstrap'}`，读取 `Actor/Users/Settings/Roles`，确认当前会话有创建权限。按准确 Account 或 Id 解析活跃推荐人；姓名重名时先澄清，禁止猜测用户 Id。管理员可以为活跃用户创建，业务员默认只为自己创建。
+2. 执行 `{Action:'Links'}`，先查该推荐人的活动。已有符合请求且启用、未过期的链接可复用，保留其他活动与业务数据。只有平台管理员的 `Actor.CanConfigure=true` 才能配置公开开通。配置缺失且用户已授权启用时，通过 `SaveSettings` 写入真实主租户前端 HTTPS 地址；不要把 API 域名、临时测试端口或别人的平台地址当成 WebBase。仅创建链接不隐含修改已经设定的开通策略。
+
+   ```javascript
+   // microi_run_engine：apiEngineKey='platform-saas-promotion'
+   // params 为下列对象；confirmExecution 使用同一 ApiEngineKey。
+   { Action:'SaveSettings', Enabled:true, WebBase:'https://<主租户前端域名>',
+     TrialDays:14, DailyLimit:20, LinkLimit:50, ManagerRoleIds:[] }
+   ```
+
+   上例为未配置时的默认值。已有试用天数、每日额度、单链接额度和管理角色应从 Bootstrap 回读并保留，除非用户明确要求调整；`ManagerRoleIds` 使用真实角色 Id 数组。保存后再次 Bootstrap 核对本分区配置。
+3. 无合适活动时执行下列请求。`ReferralUserId` 必须来自第 1 步的权威用户目录；业务员额度和试用天数不能超过主租户设定值。
+
+   ```javascript
+   { Action:'CreateLink', Title:'<推广活动名称>', ReferralUserId:'<sys_user.Id>',
+     TrialDays:14, MaxTenants:50, ValidDays:30, Remark:'<可选活动说明>' }
+   ```
+
+   创建超时先按推荐人、活动名称和时间回读 Links，确认是否已创建；禁止盲目重试导致重复活动。取得 `Data.Id` 后执行 `{Action:'ShareLink', Id:'<活动Id>'}`，返回 `Data.Url` 才是可分享地址。不要手拼 `ref=<用户Id>` 或将活动 Id 代替 `LinkToken`；票据绑定推荐人、活动、运行分区、到期时间和版本。切换链接启停状态会撤销旧地址，之后需重新签发。
+4. 回读 Links 核对归属、启用状态、期限、试用天数和额度。在全新、未登录的浏览器 context 打开 `Data.Url`，核对匿名 `platform-saas-public-trial` 的 Bootstrap 成功、表单与图形验证码可用。验收链接不需要实际创建客户租户；只有明确授权开库后才提交真实申请，并按同一 RequestId 回读任务、租户归属和登录地址，保留幂等及精确清理证据。
+
+最终交付可点击的分享地址、推荐人、试用天数、链接到期时间及额度，并区分“链接已可访问”和“客户租户已实际开通”。若接口不存在或平台版本不足，走官方 SaaS 应用与内置微服务更新，不通过临时 SQL 绕过鉴权。
+
+制作空数据库时，角色、账号绑定和权限快照必须作为同一初始模板处理。只保留明确声明的初始角色，按权威角色重建保留账号的 `RoleIds` 与等级；删除业务角色及孤立菜单权限，清空包含源业务菜单的角色权限快照。初始角色缺失、删除或等级不符时停止制作，不得根据账号现有角色列表、角色名称或高等级推测哪些角色应保留。
+
+组织数据属于同一空库模板边界：只保留明确声明的初始组织和部门，将保留账号的部门绑定与名称同步归一，并清理旧版账号关系表。保护这些平台表的物理结构，初始组织缺失或已删除时停止制作；验收必须在新租户查看真实组织树，不能只检查角色数量。清理只能作用于制作过程的隔离副本。
+
+安装历史只有能对应保留平台应用的稳定身份才可继承：非空 `StoreId` 优先，旧记录没有该字段时再核对非空应用身份；不能凭名称或前缀保留孤立记录。SQL 预览、临时副本执行、公开空库文件更新与新租户登录验收是不同证据层；源主库和既有测试租户都不能作为清理执行目标。
+
+主库 `sys_osclients` 保存租户数据库/Redis/存储路由及影响整个 API 进程的平台级配置；目标租户建立上下文后，`sys_config` 和 `mci_system_setting` 从该租户自己的数据库读取。平台级配置必须遵守“主租户为准、子租户只能降额隔离”的规则：
+
+- 所有可变业务逻辑默认必须由接口引擎编排，包括但不限于租户开通、开库、初始化、归属修复、官网个人中心、付费额度等 SaaS 业务流程。C# 后端只暴露原子 V8 能力，例如建库、导入空库模板、复制 `sys_config`、刷新 SaaS 缓存、补偿回滚、字段兜底等；不要把可变业务分支写死到 Controller 或 `TenantProvisioningService` 这类后端定制代码里。接口引擎缺少能力时，优先扩展 `V8.Method`/V8 引擎原子函数，再由接口引擎调用。
+- 官方租户开通固定由 SaaS 包的 `platform-create-tenant` 编排：`platform-runtime-custom-hook` 的 Before 阶段可以阻断，`AuthorizeCurrentUserTenantProvisioning` / `ProvisionCurrentUserTenant` 只从可信主租户 DiyToken 派生所有者与密码材料；创建完成后的 Hook/审计失败只能返回 Warning，不能诱导重复创建。系统账号偏好/资料与租户系统设置分别由 `app.microi.sys_user`、`app.microi.sys-config` 单一拥有，SaaS/Store 不得复制这些 Managed ApiEngineKey。
+- 租户开库失败时，先核对编排 `OsClientDbConn` 的真实账号与权限。业务库账号通常不能开库、创建用户或授权；应使用已有正确授权的管理账号更新编排，不通过 SQL/MCP 手工修复业务数据库。管理员页面必须同时显示中文原因、失败阶段、可执行的处理方法，以及可展开且已脱敏的原始异常链；区分密码/来源认证失败与数据库权限不足，不能只显示笼统失败或隐藏驱动原始错误。
+- 旧版 UniApp 的 `microi-init` 是 SaaS 包继续托管的 Managed 兼容门面。匿名阶段只组合 `platform-os-client-by-domain` 与 `platform-sys-config` 的公开投影；原始 DiyToken 必须由 `GetCurrentToken` 和 `RefreshLoginUser(..., rawToken)` 在后端重新验证且绑定当前租户，菜单再由只允许该固定 Key 调用的 `GetLegacyInitMenuTree(rawToken, osClient?)` 复用 `SysMenuLogic` 权威角色过滤。禁止在匿名 V8 中直接通过 FormEngine 读取 `sys_menu`；域名解析到其它租户时返回目标 `OsClient` 并要求重试，禁止匿名跨租户读取配置或菜单。
+- 主租户由运行环境决定：优先读取环境变量 `OsClient`，其次读取 `appsettings.json` 的 `AppSettings:OsClient`。只有这条主租户 `sys_osclients` 数据中的平台级字段会作为全局配置生效。
+- 同一个主租户可以同时运行在 `Product/Internal`、`Product/Internet` 等多个分区；租户目录、后台任务领取、通知和批量平台应用维护都必须按当前节点的 `OsClientType + OsClientNetwork` 隔离。一次全量维护只证明当前分区，事故恢复必须先盘点所有活跃分区，再从各分区对应节点分别执行并等待 `SucceededCount=ExpectedCount、FailedCount=0`，随后各自以新幂等键做零安装／零更新复跑。禁止临时改租户网络字段、跨分区借用任务或并发维护可能指向同一物理库的重复租户记录。
+- 大范围启动事故只允许受信后台编排器使用 `MaintenanceScope=StartupDependencies`，精确闭包固定为 `app.microi.store + app.microi.saas-engine`，并可显式启用 `StartupDependencyBootstrapOnly=true`。编排器必须先用权威当前分区目录校验 `TargetOsClients`，再在子任务仍为 `Pending` 时原子写入并强回读两应用范围与只自举标志；失败即取消，禁止退化为完整安装。工作器只从官方不可变包补齐 `platform-sys-menu` 和六项 SaaS 启动门面，七项物理契约强回读通过后终止，不写安装版本。该模式只恢复可登录性，不代表 API 进程的完整运行时已经就绪；新版后端接收流量前还必须从九个内置官方基础应用包补齐并回读全部接口引擎，后续完整应用更新仍走普通商城任务。未带标志的任务行为不得改变。
+- API 启动配置只有十项白名单：`OsClient`、`OsClientType`、`OsClientNetwork`、`OsClientDbType`、`OsClientDbConn`、`OsClientRedisHost`、`OsClientRedisPort`、`OsClientRedisPwd`、`OsClientRedisDataBase`、`OsClientDbMongoConn`。除这十项外，部署/节点级运行参数与基础设施秘密从主控 `sys_osclients` 读取；允许子租户自行维护且需要浏览器判断的业务开关、入口显示和公开交互配置使用该租户 `sys_config` 实体字段，OAuth/第三方集成的凭据、RP/Origin/Issuer/Scope 与仅后端参数使用 `mci_system_setting`，未配置时使用代码安全默认值。官方 License 恢复次数/间隔与固定私钥挂载 `/app/microi_private.pem` 是信任链例外。禁止再增加 `MICROI_*`、`DOS_ORM_*`、自定义 `AppSettings` 节点或动态名称的环境变量读取。节点身份由平台自动生成。
+- 存量畅捷通/微信 OAuth C# 协议网关有一组已发布到 SaaS 引擎的兼容字段：`OAuthReturnUrlOrigins`、`ChanjetOAuthState`、`ChanjetAesKey`、`ChanjetAppKey`、`WeChatTemplateAppId`、`WeChatTemplateAppSecret`、`WeChatTemplateId`、`WeChatMiniProgramAppId`。只能通过 Core 的租户绑定协议设置原子按请求权威 `OsClient` 读取，禁止使用主租户 `ConfigHelper` RuntimeConfigurationReader；整组字段不得复制给新租户，其中 OAuthState/AES Key/AppKey/AppSecret 不得进入 `V8.OsClientModel` 或前端投影且必须在审计中掩码。新集成不得继续扩展该兼容集合，仍使用当前租户 `mci_system_setting` + Managed ApiEngine。
+- `ASPNETCORE_*`、`DOTNET_*` 仅用于 .NET 宿主；构建、安装、测试、MCP、发布脚本可使用自身进程变量，但 API 生产代码不得把它们当业务配置。新增 SaaS 运行字段必须配套独立或既有 Tab、幂等升级、缓存刷新、敏感字段脱敏、子租户不继承和源码扫描测试。
+- 文件上传的租户业务开关与额度按“当前租户 `sys_osclients` → 代码默认值”解析；现行负向字段 `DisableFileUpload` 默认关闭/空值即允许上传，只有 `1/true` 才禁止。旧 `FileUploadEnabled` 只在新物理字段尚不存在的滚动升级节点回退读取，并须在新版 SaaS 表单隐藏。平台固定灾难保护、HTTP/Multipart/Form 和反向代理上限不可由租户覆盖，也不要求安装者维护额外上传环境变量。
+- 类似 MQTT 端口、PressureGuard、V8Limits、OrmLimits、StartupLimits、SecurityGuard 这类影响整进程资源的配置，不能让每个子租户各自抬高全局上限。子租户同名隔离字段只能降低自己的并发、等待时间或资源额度，用于隔离弱租户、试用租户或异常租户。
+- 修改 `sys_osclients` 的表、字段、数据源或配置值后，必须刷新 SaaS 引擎运行缓存，并回读验证字段 `Component`、`Data`、`Config`、实际数据值和前端真实消费结果。不要只看 MCP 写入成功。
+- SaaS 配置只在启动、管理员保存 `sys_osclients` 或显式租户刷新时发布到共享 Redis。初始化数据库会话、创建 `V8.Dbs` 运行态对象、普通 FormEngine 请求和表单设计器保存不得冒充配置变更反复发布。
+- JWT Key 由可信后端生成并持久化；SaaS 表单只读显示配置状态，不允许普通表单或 V8 写入 `AuthSecret`。手动接入旧库的 NULL/空白值必须支持原子写回，多节点竞争后回读持久胜者；重复刷新不能轮换有效 Key。只读状态查询不得初始化目标租户数据库。验收只记录是否已配置、是否稳定，不输出密钥原文。
+- 扩展库缓存必须区分“尚未加载”和“已加载但为 0 条”；后者是有效结果。没有配置 `microi_database` 的租户不能在每次 V8 执行时重复查询、调用 `AddOrUptClient` 或打印“缓存 OsClient 配置到 Redis”。
+- 多节点的缓存失效订阅只做本节点失效与数据库回源，禁止收到消息后再次发布形成回声。进程内初始化标记仅是可丢失优化，真正租户配置仍以共享数据库/Redis 为准。
+- 新增平台级字段时，字段名建议保持英文稳定，例如 `PressureGlobalMaxConcurrentRequests`、`PressureV8MaxConcurrentExecutions`、`PressureOrmMaxConcurrentConnectionOpens`；字段标签和说明必须中文，说明中写清楚“主租户有效/子租户仅可降低”。
+- 新租户记录不得复制主租户的数据库、鉴权、Redis/对象存储密钥或 MQ/MQTT/Search 凭据。共享基础设施地址与管理密钥只在服务端运行时解析，不持久化到子租户记录，也不进入 V8 投影。
+- RabbitMQ 子租户必须使用独立 user/vhost/ACL，MQTT 必须使用独立账号密码，Search 必须使用限制到 `{osClient}_*` 的 API Key/用户。外部资源尚未真实创建时保持空凭据并失败关闭，禁止把主租户管理员凭据复制过去冒充完成。
+- `V8.Cache`、`V8.HDFS`、RabbitMQ、MQTT、Search 分别强制 `Microi:{OsClient}:*`、`/{osClient}/...`、`microi.{osClient}.*`、`tenant/{osClient}/...`、`{osClient}_*` 命名空间。body/query 中的 `OsClient` 不能覆盖登录 Token 或 V8 上下文。
+
+## 接口调用区分租户的三种方式
+
+### 方式 1：Token 自动识别（最常用）
+
+请求头携带 `Token`，平台自动识别用户所属租户。
+
+```bash
+GET /apiengine/get-products
+Token: xxx-token-xxx
+```
+
+### 方式 2：URL 参数
+
+```bash
+GET /apiengine/get-products?OsClient=tenant_demo
+```
+
+### 方式 3：特殊 URL 格式（无 Token、无参数）
+
+```bash
+GET /apiengine/get-products--OsClient--tenant_demo--
+GET /apiengine/get-products--OsClient--tenant_demo--OsClientType--App--
+```
+
+> 适用于第三方回调（无法添加 Header）、支付/微信回调等场景。
+
+## 跨租户操作（仅可信控制面）
+
+普通 V8 的 `FormEngine`、`DataSourceEngine`、`TranslateEngine`、`WFEngine`、`Cache`、`HDFS`、MQ/MQTT、Search 和 `Dbs` 都必须绑定当前 Token/V8 上下文中的 `OsClient`。请求 body/query 里传入其它租户不能切换连接，也不能读取其它租户凭据。
+
+租户开通、迁移、备份或平台管理员代维只能走明确的控制面服务/接口引擎：
+
+- 调用者必须是 `Level >= 9999`，并再次校验目标租户白名单和操作类型；
+- 使用专用原子能力，不通过通用 FormEngine 读取完整 `sys_osclients` 记录；
+- 不把数据库、认证、Redis、存储、MQ/MQTT、搜索等连接与密钥投影进 V8；
+- 每次操作写安全审计、幂等键和补偿状态，并对目标租户回读验收；
+- 多节点部署使用共享租约和业务幂等，不能依赖进程静态锁。
+
+### SaaS 数据库 ZIP 开库的进度与租约
+
+通过 SaaS 引擎上传数据库 ZIP 创建租户时，必须把上传和还原建模为两个独立阶段：
+
+- 上传使用分片会话并显示真实字节进度；暂停或网络中断后复用同一文件指纹续传，不能把上传百分比冒充数据库导入进度。
+- 上传完成后提交平台持久后台任务。租户开通进度总数使用后端共享契约的固定 13 步，接口引擎、可信宿主原子和前端不得各自维护不同分母。
+- 第 2 步是数据库 ZIP 校验与还原。该阶段应按真实 SQL 读取量推进总百分比，并显示已读取/总字节、SQL 百分比、已执行语句数、当前批次与语句类型、平均吞吐和动态预计剩余时间；不能长时间只显示静态的 `2 / 13`。
+- 进度状态仅在距上次更新约 2 秒或新增约 16MB 数据时刷新；执行日志只记录阶段里程碑和 SQL 每跨过约 5% 的进度，前端只渲染最近 200 条。禁止按 SQL 行或每条语句推送日志，避免几十万条数据把共享任务表、SignalR 或浏览器 DOM 拖垮。
+- 页面同时显示服务端心跳。单个百分比短时不变不等于卡死，应综合心跳、字节、语句数、批次和消息判断；失败、取消或中断必须保留最后真实进度和错误原因，只有成功终态才算开库完成。
+
+租户开库使用平台可信后台上下文中的可续租共享锁：`Timeout` 是单次 Redis 租期，当前开库最长保护边界为 12 小时。普通 HTTP/V8 请求传入 `_BackgroundTaskId`、`_TrustedServerInvocation` 或伪造用户对象不能开启续租。持有者令牌不匹配、锁过期、Redis 所有权/续租确认失败或达到最长租约都必须失败关闭并停止推进；不能为了避免报错而把真实锁丢失降级成成功或 Warning。
+
+自动续租只解决“正常长任务不因短 TTL 自然过期”，不能代替业务幂等、检查点、补偿状态和 fencing token。大库导入完成但域名绑定未完成时，应保留已经成功创建的租户和数据库，进入明确的域名补偿状态；不能因数据面域名失败重新导入整个数据库。接口引擎的通用锁配置读取 `../v8-api-config/SKILL.md`，长任务按钮和检查点读取 `../v8-menu-buttons/references/progressive-02-8-模式-f-后台任务按钮-长任务.md`。
+
+## 缓存按租户隔离
+
+```javascript
+// 推荐传逻辑 Key；服务端自动添加当前租户前缀
+var key = 'Product:' + V8.Param.id;
+V8.Cache.Set(key, value, 600);
+
+// 完整当前租户 Key 继续兼容
+var fullKey = 'Microi:' + V8.OsClient + ':Product:' + V8.Param.id;
+
+// 其它租户的 Microi: 前缀会被服务端拒绝
+```
+
+## 接口引擎中针对不同租户走不同逻辑
+
+```javascript
+// 租户差异应来自当前租户的非敏感业务配置，不要硬编码某个“主租户”字符串
+if (V8.OsClientModel.OrderApprovalMode === 'Direct') {
+  V8.FormEngine.UptFormData('Order', { Id: id, Status: 'Approved' });
+} else {
+  await V8.WFEngine.StartWork({ FlowDesignId: 'order-flow', TableRowId: id });
+}
+
+// App 端 vs PC 端不同返回
+if (V8.OsClientType === 'App') {
+  return { Code: 1, Data: simplifiedList };
+}
+return { Code: 1, Data: fullList };
+
+// 内网外网走不同 ERP 网关
+var erpUrl = (V8.OsClientNetwork === 'Intranet')
+  ? 'http://192.168.1.10/erp/api'
+  : 'https://erp.public.com/api';
+```
+
+## 第三方密钥放租户动态设置（不要硬编码）
+
+```javascript
+// ❌ 危险：密钥写在代码里，所有租户共用，无法独立轮换
+var ak = 'AKIDxxxxxxxx';
+
+// ✅ 浏览器需要判断的开关：使用 sys_config 实体字段
+var giteeEnabled = V8.SysConfig.GiteeLoginEnabled === 1;
+
+// ✅ 后端 V8 可读取当前租户 Secret 并直接调用供应商
+var privateSettings = V8.SysConfig.ServerPrivateSettings || {};
+var secret = privateSettings['Login.Gitee.ClientSecret'];
+// 禁止 return secret、console.log(secret) 或写入前端可读字段。
+```
+
+> `mci_system_setting` 位于每个租户自己的数据库，只保存不能公开或仅供后端执行的配置；普通值与 Secret 都不会下发浏览器。Secret 保存认证密文，只在后端 V8 的当前租户 `ServerPrivateSettings` 中解密使用。能力开关和入口显示必须建成 `sys_config` 实体字段，禁止通过 `IsPublic` 或其它运行时勾选把私密记录公开。前端 V8、普通 FormEngine HTTP、匿名/访问密钥会话不能读取私密设置，后端 V8 也不能获得通用解密器。`sys_osclients` 自定义业务字段只保留存量兼容；共享基础设施字段由服务端强制移除，不能用自定义同义字段绕过安全代理。
+
+## 用户扩展字段访问（同理）
+
+平台 `sys_user` 也由表单引擎驱动。如给 `sys_user` 添加 `Wife` 字段：
+
+```javascript
+// V8 代码中可访问
+V8.CurrentUser.Wife;
+
+// SQL 数据源中可访问
+SELECT * FROM Contact WHERE OwnerId = $CurrentUser.Id$ AND Spouse = $CurrentUser.Wife$
+```
+
+## 常见错误
+
+- 旧库升级的内置应用包包含定时任务时，升级内核按“资源独立提交 → 幂等保存并回读 Quartz/任务元数据 → 确认安装版本”执行。仅程序集白名单包及不可伪造的宿主授权可进入该兼容流程；普通应用安装仍必须使用持久后台任务分片。任一阶段失败不推进 ServerVersion，修复后从原升级入口重试，不手动抬高版本或伪造任务信封。
+
+❌ 绕开 `V8.Cache` 使用底层 Redis → 租户数据串号（V8 已不再暴露底层句柄）
+❌ MongoDB DbName 不带 OsClient → 数据混淆  
+❌ 把 OsClientModel 字段直接返回给前端 → 密钥泄漏  
+❌ 查询 `mci_system_setting.SecretCipher` 或给 V8 暴露通用解密器 → 密钥边界失效  
+❌ 在前端硬编码 OsClient → 一改全改，应通过 token/URL 自动识别  
+❌ 跨租户操作不验证当前用户权限 → 越权风险  
+❌ 子租户缺少 MQ/MQTT/Search 独立凭据时回退主账号 → 全平台越权
+
+## 检查清单
+
+- 子租户授权使用官方 SaaS 应用的 `sys_osclients.LicenseProductType` 与 `LicenseExpirationDate`（UTC）字段；两项留空继承主授权。只允许主租户超级管理员设置，不能超过已验签主授权的版本和日期；运行时再次裁剪。两项不得通过主配置合并自动复制到子租户。不要在可编辑 V8 里代替可信授权边界。
+- 授权到期文案和提前天数在消息通知页设置。官方与主租户策略分别触发，不能因官方已触发或未触发而跳过主租户检查。签发帐号 `sys_user.LicenseExpirationDate` 未设置表示永久有效，但可签发版本及请求日期仍需校验。
+
+- [ ] 缓存只通过 `V8.Cache` 使用逻辑 Key 或当前租户完整 Key
+- [ ] 所有 MongoDB DbName 都包含 `V8.OsClient`
+- [ ] 当前租户自有的业务集成密钥可放 `V8.OsClientModel`，共享 Redis/存储/MQ/MQTT/Search 凭据只能由服务端托管
+- [ ] 跨租户操作前校验权限
+- [ ] 不向前端返回 `V8.OsClientModel`
+- [ ] 子租户数据库账号只授权本租户库，MQ/MQTT/Search 独立凭据已真实创建
+- [ ] 文件、队列、Topic、索引均由服务端规范为当前租户命名空间
+- [ ] 无扩展库租户重复执行 V8 时不会重复刷新 SaaS 配置；真实 `sys_osclients` 保存后各节点能按租户失效并回源
+- [ ] ZIP 开库区分上传与还原进度，使用固定 13 步、低频明细、服务端心跳和有界日志
+- [ ] 开库锁只由可信持久后台任务自动续租；真实租约丢失失败关闭，所有副作用仍具备幂等、检查点和 fencing token
+
+## Microi.AI 中转站租户凭据
+
+- `mic_ai` 的 `Microi.AI中转站.ApiKey` 是租户调用吾码官方中转站的用户凭据。运行时不得因为该字段为空而静默创建、回退到当前用户字段或绕过校验，否则管理员无法判断真实配置来源。
+- 老租户由用户在吾码官网个人中心复制 ApiKey 后填写到本租户的 `mic_ai` 中转站记录；空值应返回明确配置错误。
+- 官网创建新 SaaS 租户时，必须先取得当前官网账号的 ApiKey，再由租户初始化服务写入新库 `mic_ai` 的 `Microi.AI中转站` 记录。该自动写入只发生在受控开库流程，不得散落到普通 AI 对话请求中。
+- 开库入口把 ApiKey 传给后台 worker 后，worker 还必须继续显式传入最终的原子初始化方法；不能只在父接口或中间参数中“带过”。每个异步/后台边界都应对空值立即失败，避免租户创建成功但 `mic_ai.ApiKey` 静默为空。
+- 自动化验收必须通过新租户 `admin` 登录回读 `mic_ai`，只输出“非空、长度、与官网账号 ApiKey 是否一致”等布尔结果，不得把真实 ApiKey 写入日志、截图或测试报告。
+- 中转模型公开目录只返回模型 Id、显示名、厂商等非敏感字段，可匿名读取；严禁把官方上游模型的 ApiKey、Endpoint 私密配置随模型列表返回前端。
+
+### 旧结构空库制作验收
+
+空库脱敏生成器应只读实际物理列；组织机构旧表缺少可选父级名称列时，只写已有父级 Id，不为制作模板修改主库结构。物理字段发现失败应在输出清理 SQL 前失败关闭。验收同时覆盖有该列、缺少该列及读取失败，最终检查隔离副本和官方空库下载包。
+
+应用文件与版本清理不得在 MySQL 5.7 的 DELETE 外连接中用 `Id = AppId OR AppKey = AppId`。先在隔离副本内物化带主键的 Id/AppKey 保留集合，分别覆盖当前商城 Id、历史 AppKey、业务应用、孤立记录与 NULL；验证新旧结果一致，源主库只读。真实 SQL 耗时与 Node 生成器测试需分别记录。