CLI 管理授权

「CLI 管理授权」为命令行工具（modstart-cli）提供后台管理能力接入：

• 在后台生成 CLI 凭证（一次性显示明文，服务端仅保存 sha256，可树状勾选可调用的接口）
• CLI 使用凭证登录后，直接调用 {adminPath}/cli/* 下的后台管理接口
• 各模块在 module/<Module>/AdminCli 中提供 CLI 控制器与 api.json 接口 schema，供 CLI / AI 发现

功能特性

• 后台生成 CLI 凭证：明文只显示一次，服务端仅保存 sha256，支持有效期、撤销与最近使用记录
• 授权接口按「模块 → 接口」树状勾选，必须显式勾选，不提供「全部接口」这种放权方式
• 运行时完全依赖凭证，不依赖后台角色、权限规则、Session 与 Cookie，每次请求只认 admin-cli-key
• 列表接口字段白名单与自动脱敏（密码、盐、token、openid、身份证 / 银行卡、真实姓名等不外泄）
• 写接口字段白名单，资金 / 订单类表默认拒绝金额、状态、统计字段，传入被拒字段会显式报错
• 命令行工具 modstart-cli 支持凭证登录、多站点、接口列表与 JSON 调用，输出统一为 code / msg / data

CLI 管理授权
    凭证
        后台生成
        一次性明文显示
        有效期 / 撤销
        仅创始人可创建
    接口授权
        模块 → 接口树状勾选
        按接口 key 精确授权
        founderOnly 接口仅创始人
    安全
        只认 admin-cli-key
        不依赖 Session / 角色
        列表字段脱敏
        写接口字段白名单
    客户端
        凭证登录
        多站点
        api list
        call 调用（JSON）

使用流程

1. 后台进入「系统设置 → 接口设置 → CLI 授权管理」，点击「新增」（仅创始人可创建）

• 填写设备名称
• 授权接口：树状勾选（模块 → 具体接口），至少勾选一个；不支持「全部接口」
• 有效期默认 90 天，0 表示永久

1. 提交后自动关闭弹窗，并弹出「CLI 凭证」复制窗口（凭证仅显示一次）
2. 在终端执行（--admin-url 填完整后台管理地址）：

modstart-cli login --admin-url=https://your-domain.com/admin --token=mscli_xxxxxxxx --name=MacBook

1. 登录成功后即可使用（所有命令统一输出 JSON，中文不转义）：

modstart-cli whoami
modstart-cli api list
modstart-cli call news.index '{"page":1,"pageSize":20}'
modstart-cli call news.add '{"title":"标题","content":"内容"}'
modstart-cli call news.category.index

call 的参数统一为 JSON 对象（也可用 --data '<json>'），会按接口定义在本地校验参数（必填、int/bool/json 类型），参数不合法会直接提示，不会发送到后台。

接口约定

所有 CLI 接口统一位于后台前缀下：/{adminPath}/cli/*。

所有 CLI 接口都必须携带 admin-cli-key 请求头，每次请求都会复验凭证状态（撤销/过期立即失效），后台面板 Cookie 不能单独访问 CLI；CLI 完全无状态，不读写 Session/Cookie，管理员身份始终取凭证绑定的 adminUserId；凭证创建时勾选的接口白名单会参与授权（未勾选的接口直接拒绝，也不出现在 api_list 中）。

模块适配（AdminCli）

业务模块在 module/<Module>/AdminCli/ 下提供三部分即可，不需要修改后台原控制器：

module/News/AdminCli/
├── Controller/
│   ├── NewsCliController.php
│   └── CategoryCliController.php
├── routes.php
└── api.json

控制器（@Api 注解 + 真实逻辑，标准 CRUD 可复用 CliCrud）：

<?php
namespace Module\News\AdminCli\Controller;

use Illuminate\Routing\Controller;
use ModStart\Admin\Auth\Admin;
use ModStart\Admin\Auth\AdminPermission;
use ModStart\Core\Dao\ModelUtil;
use ModStart\Core\Input\Response;
use Module\AdminCli\AdminCli\CliCrud;
use Module\News\Model\News;

class NewsCliController extends Controller
{
    use CliCrud;

    /**
     * @Api 新闻资讯 列表
     * @ApiDesc 分页查询，只返回白名单字段
     * @ApiMethod post
     * @ApiBodyParam page int 页码
     * @ApiBodyParam pageSize int 每页数量
     */
    public function index()
    {
        return $this->paginateModel(News::class, 'title', [], ['id', 'title', 'created_at']);
    }

    /**
     * @Api 新闻资讯 新增
     * @ApiMethod post
     * @ApiBodyParam title string required 标题
     * @ApiBodyParam content string 内容
     */
    public function add()
    {
        AdminPermission::demoCheck();
        // 写接口必须传 $allow 白名单，被拒参数会显式报错
        $data = $this->modelInput(News::class, ['id', 'created_at', 'updated_at'], ['title', 'content']);
        $id = ModelUtil::insert(News::class, $this->withRequiredDefaults(News::class, $data));
        Admin::addInfoLog(Admin::id(), 'CLI 新增新闻', ['ID' => $id]);
        return Response::generateSuccessData(['id' => $id]);
    }
}

路由（相对 {adminPath}/cli，由 AdminCli 自动挂载）：

<?php
/* @var \Illuminate\Routing\Router $router */
$router->match(['post'], 'news/index', 'NewsCliController@index');
$router->match(['post'], 'news/add', 'NewsCliController@add');

接口 schema（api.json，供 CLI / AI 发现）：

{
  "module": "News",
  "title": "新闻资讯",
  "apis": [
    {
      "key": "news.index",
      "title": "新闻资讯 列表",
      "method": "post",
      "url": "news/index",
      "scope": "news.read",
      "permission": "\\Module\\News\\Admin\\Controller\\NewsController@index",
      "params": [
        { "name": "page", "type": "int", "required": false, "desc": "页码" }
      ]
    }
  ]
}

字段说明：

返回 HTML 页面的接口（show 详情、login/logout、GET-only 的 param/dashboard/export 等）不要声明为 CLI 接口。

开发规范（必须遵守）

1. 三件套一一对应：routes.php 路由、控制器方法、api.json 缺任何一项都会被 fail-closed 拒绝。
2. 授权：创建凭证时树状勾选接口，运行时按接口 key 精确校验；不再使用后台角色与 *Manage 规则；无规则接口标 founderOnly。
3. 列表脱敏：paginateModel() 优先显式传字段白名单；不传时默认剔除 password/passwordSalt/secret/apiKey/token/openid/unionid/idCard/bankCard/realname 等；裸 key/token 列需在模块侧白名单排除。
4. 写白名单：资金/订单/会员类表（表名含 money|order|pay|charge|cash|credit|…）必须传 $allow；被拒参数显式报错，禁止静默丢弃；password/passwordSalt/remember_token 永远不可通过通用输入写入。
5. 审计与演示站：写方法调用 AdminPermission::demoCheck()，并 Admin::addInfoLog() 记录操作。
6. 测试：每个接口至少一条正向用例；未授权接口、无凭证、凭证撤销、founderOnly 等安全用例按负向断言补充。
7. 传模型类：ModelUtil::*、paginateModel()、modelInput()、withRequiredDefaults() 一律传 \Module\X\Model\Xxx::class，禁止字符串表名；表没有 Model 时先在 Model/ 补最小模型再写业务。

权限与安全

• 授权完全由凭证决定：创建时以树状结构勾选接口，保存到 admin_cli_token.apis；运行时不检查后台角色与权限规则
• 每次请求按接口 key 精确校验，未勾选的接口直接拒绝，也不出现在 api_list 中
• 后台无可授权规则的接口在 api.json 标 founderOnly，由中间件强制创始人校验，非创始人的授权树中也看不到
• scope 仅作为接口分类元数据，不参与授权
• 列表接口按字段白名单脱敏（默认剔除密码、盐、token、apiKey、openid、unionid、身份证/银行卡、真实姓名等），写接口按 $allow 白名单，被拒参数显式报错而不是静默丢弃
• 写方法调用 AdminPermission::demoCheck()（演示站禁止写操作）并 Admin::addInfoLog() 记录审计
• 凭证服务端仅保存 sha256，明文只在创建时显示一次；列表中的前缀由摘要派生，不泄露凭证内容
• 凭证绑定创建它的管理员，可随时在后台撤销；每次请求都会复验撤销/过期状态，撤销后立即失效
• 仅接受 admin-cli-key 请求头凭证，避免凭证出现在 URL / 请求体 / 访问日志中；CLI 请求完全无状态（array session driver，不写会话、不下发 Cookie），后台面板 Cookie 不能单独访问 CLI 接口

完整的 CLI 接口开发规范（三件套同步、凭证授权、脱敏、写白名单、测试要求）见 .agents/doc/cli.md。

• CLI 完全无状态：每次请求只认凭证，管理员身份来自凭证绑定的 adminUserId，不依赖 Session / Cookie
• 通用列表接口（CliCrud::paginateModel）自动剔除 password / passwordSalt / token / openid / apikey 等敏感字段，敏感模块可传字段白名单
• 资金 / 订单类表未显式传 $allow 时，金额、状态、统计字段不允许写入；客户端显式传入被拒字段会直接返回「不允许通过 CLI 写入」错误，不会静默忽略
• 会员新增/编辑走 MemberUtil 的唯一性校验与密码加密；会员 API Key 由服务端生成且列表不返回明文
• 后台未注册权限规则的接口（如 MemberApiKey、PayUnifiedClient）在 api.json 中标记 founderOnly：中间件强制校验创始人身份，非创始人的 api_list 也不会展示这些接口

使用场景

• 用命令行 / 脚本批量维护站点内容（文章、商品、订单查询等），不必手工点后台
• 交给 AI 编程助手调用后台能力：按 api list 发现接口，再 call 执行
• 多站点统一运维：一台机器配置多个站点凭证，按站点执行命令
• 需要「可审计、可撤销、最小授权」的后台接入场景

后台菜单

• 系统设置 → 接口设置 → CLI 授权管理

后台菜单

• 系统设置
• 系统设置 → 接口设置
• 系统设置 → 接口设置 → CLI 授权管理