王明 / Food-Labeling-Management-Platform

  # 2026-07-23 泰额版：平台端操作公司级账号逻辑说明
  
  本文档说明 **泰额版** 平台管理端如何操作「公司级」账号与权限：架构、接口、写库路径、与公司端登录的关系，以及**不得影响美国版**的隔离约束。
  
  相关文档：
  
  - `2026-07-21代码优化.md`：公司列表 / 改密 / SaaS 菜单与角色菜单接口细节  
  - `2026-07-23泰额版当前登录账号菜单接口.md`：平台 vs 公司「当前登录人菜单」  
  - `th-tenant-menu-seed.sql` / `th-platform-user-role-seed.sql`：平台主库菜单与 User/Role 种子  
  
  ---
  
  ## 一、角色与库分层
  
  | 端 | 登录 | 用户库 | 典型能力 |
  |----|------|--------|----------|
  | **平台端** | `POST /api/app/account/login` | 主库 `antis-foodlabeling-host`.`user` | 公司列表、改公司管理员、分配 SaaS 菜单、改公司角色菜单、开通/删除公司 |
  | **公司端** | `POST /api/app/th-web-auth/login`（须 `tenantId`） | 该公司业务库 `user` | 业务功能；`GET /api/app/auth-session/my-menus` |
  
  **公司 = 租户**：主库表 `YiTenant`（前端常把 `name` 当 `companyName`）。
  
  ```mermaid
  flowchart LR
    subgraph platform [平台端]
      PLogin[account/login]
      PHost[(antis-foodlabeling-host)]
      PLogin --> PHost
    end
    subgraph company [公司端]
      CLogin[th-web-auth/login]
      CBiz[(租户业务库)]
      CLogin --> CBiz
    end
    PHost -->|YiTenant.TenantConnectionString| CBiz
    PHost -->|改 admin / 角色菜单| CBiz
  ```
  
  ### 1.1 库职责
  
  | 库 | 配置来源 | 平台操作相关表 |
  |----|----------|----------------|
  | **主库** `antis-foodlabeling-host` | `DbConnOptions.Url` | `YiTenant`、`fl_th_tenant_admin_credential`、`fl_th_tenant_menu_permission`、平台 `user`/`role`/`menu`/`userrole`/`rolemenu` |
  | **租户业务库** `antis-foodlabeling-{key}` | `YiTenant.TenantConnectionString` | 公司 `User`（登录哈希）、`Role`/`RoleMenu`/`Menu`、业务表 |
  | **美国版库** `antis-foodlabeling-us` | 美版 `appsettings`；泰额 **Default** 租户连接串也指向此库 | **禁止**当作泰额新公司业务库去写平台种子；对 Default 改 admin/角色会动到美版数据 |
  
  ### 1.2 两层「菜单」勿混淆
  
  | 层 | 存储 | 接口 | 语义 |
  |----|------|------|------|
  | **SaaS 公司开通模块** | 主库 `fl_th_tenant_menu_permission`（`menuPermissionKeys`） | `menu-permission-tree` / `company-menus` | 该公司「能开哪些产品模块」 |
  | **公司 RBAC 菜单** | 租户库 `Menu` + `RoleMenu` | `company-roles` / `company-role-menus`；公司端 `auth-session/my-menus` | 该公司内角色能看哪些业务菜单 |
  
  平台主库种子菜单（`th-menu-*`）服务于**平台端自身路由**，不是公司业务库菜单。
  
  ---
  
  ## 二、平台端操作公司账号：能力总览
  
  实现类：`ThMultiTenancyAppService`（路由前缀 `/api/app/th-multi-tenancy/`）。  
  开通公司：`ThTenantProvisioningAppService`（`/api/app/th-tenant-provisioning/`）。
  
  | 能力 | 方法 / 路径 | 主要读写 |
  |------|-------------|----------|
  | 登录页租户下拉（匿名） | `GET .../tenant-select` | 读主库租户 + 凭据（无 Id） |
  | 公司分页列表 | `GET .../company-list` | 读主库租户 + 凭据 + SaaS keys |
  | 改公司管理员账号/密码 | `PUT .../company-admin` | 写**租户库 User** + 写主库凭据表 |
  | SaaS 权限树 | `GET .../menu-permission-tree` | 代码目录，无库 |
  | 查/设公司 SaaS 菜单 | `GET/PUT .../company-menus` | 读写主库 `fl_th_tenant_menu_permission` |
  | 查公司角色 | `GET .../company-roles` | 读租户库 `Role`/`RoleMenu` |
  | 设公司角色菜单 | `PUT .../company-role-menus` | 写租户库 `RoleMenu` |
  | 开通公司 | `POST /th-tenant-provisioning/provision` | 写主库 `YiTenant` + 建业务库/Init |
  | 删除公司 | `DELETE .../company/{tenantId}` | 软删主库租户；可选 DROP 业务库 |
  
  鉴权：除 `tenant-select` 外，平台管理接口需 **平台 Token**（`account/login`）。
  
  ---
  
  ## 三、核心数据流
  
  ### 3.1 开通公司（产生「公司级账号」）
  
  ```text
  平台管理员
    → POST /api/app/th-tenant-provisioning/provision
    → 主库写入 YiTenant（Name + TenantConnectionString）
    → EnsureDatabaseCreated（物理建库）
    → 后台 InitAsync：业务库 CodeFirst + Seed
         └─ 默认 User.UserName = admin，密码 = RbacOptions.AdminPassword（哈希）
  ```
  
  要点：
  
  - 开通**不会**自动写 `fl_th_tenant_admin_credential`。  
  - 列表回显密码：无凭据行时用配置默认密码现场 AES 加密；平台首次 `PUT company-admin` 后才持久化可回显密文。  
  - Init 异步未完成时，立刻改 admin / 公司登录可能失败。
  
  ### 3.2 平台改公司管理员（重点）
  
  接口：`PUT /api/app/th-multi-tenancy/company-admin`
  
  ```text
  1. CurrentTenant=null（主库 scope）
     读 YiTenant、fl_th_tenant_admin_credential（当前 LoginAccount，默认 admin）
  2. 若有 password + passwordSalt：AES 解密得明文
  3. 用 YiTenant.TenantConnectionString 建独立 SqlSugarClient（直连业务库，不靠 Change(tenantId) 切仓储）
  4. 在业务库 User 上：
     - 可选改 UserName（查重）
     - 可选 ApplyPlainPassword → 写 Password/Salt 哈希
  5. Upsert 主库 fl_th_tenant_admin_credential（LoginAccount + AES 密文 + IV）
  ```
  
  | 写入位置 | 字段语义 |
  |----------|----------|
  | 租户库 `User.Password/Salt` | **登录校验用哈希**（不可逆） |
  | 主库 `PasswordCipher/PasswordIv` | **列表回显用 AES 密文**（可逆，密钥 `FoodLabeling:TenantSelectCrypto`） |
  
  前端改密必须先按约定 AES 加密再提交，**禁止**明文密码直传。
  
  ### 3.3 平台分配公司 SaaS 菜单
  
  ```text
  GET  menu-permission-tree     → 静态 Key 树（ThSaasMenuPermissionCatalog）
  GET  company-menus?tenantId=  → 读主库已分配 keys
  PUT  company-menus            → 主库先删后插 fl_th_tenant_menu_permission
  ```
  
  不写租户库 `Menu`/`RoleMenu`。非法 key 会校验失败。
  
  ### 3.4 平台配置公司内角色菜单
  
  ```text
  GET  company-roles?tenantId=  → 直连租户库读 Role + RoleMenu.menuIds
  PUT  company-role-menus       → 直连租户库覆盖 RoleMenu（校验 Menu 存在）
  ```
  
  这与公司员工登录后看到的 `auth-session/my-menus` 同源（租户库 RBAC）。
  
  ### 3.5 删除公司
  
  ```text
  DELETE /api/app/th-multi-tenancy/company/{tenantId}?dropDatabase=true
    → 禁止删除 Default 租户
    → DROP 业务库时禁止库名 host / us（及受保护库）
    → 软删 YiTenant
    → 删凭据表、SaaS 菜单权限、租户缓存
  ```
  
  ---
  
  ## 四、跨库访问约定（实现要点）
  
  | 约定 | 说明 |
  |------|------|
  | 主库表 | 实体带 `[DefaultTenantTable]`；读写前 `CurrentTenant.Change(null)`，连接走 `DbConnOptions.Url`（host） |
  | 租户业务库 | `TenantBusinessDatabaseAccessor`：按 `YiTenant` 连接串 **独立 SqlSugarClient**，避免空连接串误连主库 |
  | 不信任 JWT 租户 | 平台改公司数据时以入参 `tenantId` + 主库登记的连接串为准，不以「当前登录租户」替代目标公司 |
  
  ---
  
  ## 五、与美国版隔离（强制）
  
  | 规则 | 说明 |
  |------|------|
  | 平台种子只写 **host** | `menu` / `user` / `role` 等平台数据禁止写入 `antis-foodlabeling-us` |
  | Default 租户 = US 业务库 | host 中 Default 的 `TenantConnectionString` 指向 `antis-foodlabeling-us`；对该租户执行 `company-admin` / `company-role-menus` **会改美版库** |
  | 新公司必须独立库 | Provision 使用 `antis-foodlabeling-{tenant}` 模板；勿把新公司指到 `us` |
  | 删除保护 | 不可删 Default；不可 DROP `host`/`us` |
  | Token 隔离 | 平台 Token 调公司 `my-menus` 会因无租户失败；公司 Token 勿当平台管理凭证 |
  
  **建议**：平台运营界面操作公司时，只选择泰额独立业务库租户（如 `中国麦当劳公司` → `antis-foodlabeling-t46d56528`），避免点选 Default。
  
  ---
  
  ## 六、接口速查（含 curl）
  
  Base：`http://127.0.0.1:19002`（以环境为准）。
  
  ```bash
  # 平台登录
  curl -X POST "http://127.0.0.1:19002/api/app/account/login" \
    -H "Content-Type: application/json" \
    -d "{\"userName\":\"admin@example.com\",\"password\":\"123456\"}"
  
  # 公司列表（含加密账号密码）
  curl -G "http://127.0.0.1:19002/api/app/th-multi-tenancy/company-list" \
    --data-urlencode "skipCount=0" --data-urlencode "maxResultCount=20" \
    -H "Authorization: Bearer <platform-token>"
  
  # 改公司管理员（password 为前端 AES 密文）
  curl -X PUT "http://127.0.0.1:19002/api/app/th-multi-tenancy/company-admin" \
    -H "Authorization: Bearer <platform-token>" \
    -H "Content-Type: application/json" \
    -d "{\"tenantId\":\"<guid>\",\"loginAccount\":\"admin\",\"password\":\"<cipher>\",\"passwordSalt\":\"<iv>\"}"
  
  # 公司 SaaS 菜单
  curl -G "http://127.0.0.1:19002/api/app/th-multi-tenancy/company-menus" \
    --data-urlencode "tenantId=<guid>" \
    -H "Authorization: Bearer <platform-token>"
  
  # 公司角色
  curl -G "http://127.0.0.1:19002/api/app/th-multi-tenancy/company-roles" \
    --data-urlencode "tenantId=<guid>" \
    -H "Authorization: Bearer <platform-token>"
  ```
  
  公司端自测登录（验证平台改密是否生效）：
  
  ```bash
  curl -X POST "http://127.0.0.1:19002/api/app/th-web-auth/login" \
    -H "Content-Type: application/json" \
    -d "{\"tenantId\":\"<guid>\",\"userName\":\"admin\",\"password\":\"新明文密码\"}"
  ```
  
  ---
  
  ## 七、关键代码路径
  
  | 模块 | 路径 |
  |------|------|
  | 平台多租户服务 | `FoodLabeling.Th.Application/Services/ThMultiTenancyAppService.cs` |
  | 开通租户 | `FoodLabeling.Th.Application/Services/ThTenantProvisioningAppService.cs` |
  | 业务库直连 | `FoodLabeling.Th.Application/MultiTenancy/TenantBusinessDatabaseAccessor.cs` |
  | AES 凭据 | `FoodLabeling.Th.Application/MultiTenancy/TenantSelectCredentialCipher.cs` |
  | SaaS Key 目录 | `FoodLabeling.Th.Application/MultiTenancy/ThSaasMenuPermissionCatalog.cs` |
  | 主库凭据实体 | `FoodLabeling.Th.Domain/Entities/ThTenantAdminCredentialEntity.cs` |
  | 主库 SaaS 菜单实体 | `FoodLabeling.Th.Domain/Entities/ThTenantMenuPermissionEntity.cs` |
  | 公司 Web 登录 | `FoodLabeling.Th.Application/Services/ThWebAuthAppService.cs` |
  | 平台登录 | `Yi.Framework.Rbac.Application/Services/AccountService.cs` |
  
  ---
  
  ## 八、风险与自检
  
  | 风险 | 应对 |
  |------|------|
  | 对 Default 改密 / 改角色 → 写 US | 运营禁操作 Default；删除已有保护，改密无同等硬拦 |
  | 凭据表可逆 AES | 保护 `TenantSelectCrypto:SecretKey`；仅平台管理员可见列表 |
  | 开通未写凭据表 | 改密走平台接口后才会与列表回显一致 |
  | Init 未完成就改 admin | 等「后台初始化完成」或调 `initialize-tenant-database` |
  | SaaS keys ≠ RBAC 菜单 | 配置完 `company-menus` 后，公司内角色仍需 `company-role-menus` / 公司端角色管理 |
  
  自检清单：
  
  - [ ] 平台用 `account/login`（host `admin`），公司用 `th-web-auth/login`  
  - [ ] `company-list` 能看到目标公司 Id 与加密凭据  
  - [ ] `company-admin` 后，公司端可用新密码登录；主库凭据表有对应行  
  - [ ] `company-menus` 只改 host；`company-role-menus` 只改目标租户库  
  - [ ] `antis-foodlabeling-us` 的 user/role 数量未因平台种子脚本变化  
  - [ ] 未对 Default / `database=us` 执行 DROP  
  
  ---
  
  ## 九、小结
  
  平台端操作公司级账号的本质是：
  
  1. **元数据与回显凭据**放在主库 host；  
  2. **真正能登录的公司账号**在各公司业务库 `User`；  
  3. 平台通过 `tenantId` + 直连连接串跨库改公司 admin / 角色菜单；  
  4. SaaS 模块开关与公司内 RBAC 是两层模型；  
  5. **永远不要把美国版库当成泰额平台种子库或随意操作 Default 租户。**