公司管理 API

公司管理是 AIDC Control Plane 的第一组核心 API：先创建 Company，再创建部门、Agent Cell、服务器 Runtime、数据源、权限与审计链。所有后续资源都必须挂在 Company 下面，不能脱离公司边界单独存在。

资源关系

Company
├── Departments
│   ├── Root Directory
│   ├── Human Owner
│   ├── Permission Baseline
│   └── Department Agents
├── Runtime / Servers
│   ├── Provider: aidc-hosted | customer-cloud | on-prem
│   ├── Region
│   ├── Health
│   └── Power Actions: start | stop | restart
├── Data Sources
│   ├── Drive / Folder / OA / ERP / MES
│   ├── Sync Jobs
│   └── Ingestion Status
├── Agents
│   ├── Role
│   ├── Model Policy
│   ├── Tool Policy
│   └── Memory Policy
└── Action Log
    ├── Provisioning
    ├── Permission Change
    ├── Runtime Operation
    └── Audit Trail

API 命名原则

开发文档统一使用 companies 作为标准资源名。当前代码中已有一部分历史控制台接口使用 customers / cell，后续保留兼容，但新 API 与 CLI 语义应向 company 收敛。

1. 创建 Company

1.1 操作目标

创建一个新的 Company，并完成公司级 Control Plane 初始化。这一步对应 Console 里的「创建公司 · 置备隔离 Agent Cell」。

CreateCompany
→ ValidateCompanyKey
→ CreateCompanyProfile
→ SelectDeploymentForm
→ ProvisionRuntimeCell
→ BootstrapDirectories
→ BootstrapDepartments
→ WriteActionLog
→ RunSmokeCheck

1.2 细分操作

1.3 HTTP Reference：创建 Company

POST /api/v1/control-plane/companies
Content-Type: application/json
Idempotency-Key: <uuid>

Request Body

{
  "nameZh": "<company-display-name-zh>",
  "nameEn": "<company-display-name-en>",
  "companyKey": "<company-key>",
  "industry": "manufacturing",
  "region": "ap-southeast-1",
  "deploymentForm": "aidc_hosted",
  "fdeOwner": "<fde-owner-id>",
  "humanOwner": {
    "name": "<owner-name>",
    "role": "<owner-role>"
  }
}

字段说明

Response

{
  "ok": true,
  "data": {
    "company": {
      "id": "cmp_01...",
      "companyKey": "<company-key>",
      "cellId": "cell-<company-key>-<suffix>",
      "nameZh": "<company-display-name-zh>",
      "nameEn": "<company-display-name-en>",
      "status": "provisioning",
      "deploymentForm": "aidc_hosted",
      "region": "ap-southeast-1",
      "adl": "ADL-1"
    },
    "nextActions": [
      "create_runtime_server",
      "bootstrap_departments",
      "run_smoke_check"
    ]
  },
  "meta": {
    "version": "v1",
    "requestId": "req_...",
    "generatedAt": "<iso-8601-timestamp>"
  }
}

CLI：创建 Company

aidc company create \
  --name "<company-display-name>" \
  --name-zh "<company-display-name-zh>" \
  --key <company-key> \
  --industry manufacturing \
  --region ap-southeast-1 \
  --deployment aidc-hosted \
  --fde-owner <fde-owner-id>

2. 开服务器 / Runtime

创建 Company 后，必须为 Company 绑定 Runtime。Runtime 可以是 AIDC 托管、客户云内或本地私有化。服务器操作属于运维动作，必须通过 service 与 provider adapter，不能在 route 层直接调用云资源。

创建服务器

POST /api/v1/control-plane/companies/{companyKey}/servers

{
  "serverId": "primary",
  "provider": "aws",
  "region": "ap-southeast-1",
  "runtimeKind": "control-plane-worker",
  "instanceType": "t3.medium",
  "networkProfile": "private-cell"
}

服务器操作

CLI 草案

aidc server create --company <company-key> --server primary --provider aws --region ap-southeast-1
aidc server health --company <company-key> --server primary
aidc server start --company <company-key> --server primary --reason "initial provisioning"
aidc server restart --company <company-key> --server primary --reason "runtime upgrade"

安全边界

• route 层不能直接调用 AWS、Vercel、Supabase 或其他 provider；
• 必须通过 server.service → provider adapter；
• provider 未配置时应返回 server_provider_not_configured；
• 高风险动作必须写入 Action Log；
• 停止 / 重启必须要求 reason；
• 生产客户环境必须支持 rollback / operation queue。

3. 创建 Department

Department 不是普通标签，而是 AIDC 的权限、目录、Agent Cell 和业务责任边界。一个 Department 至少应该包含 name、charter、rootDir、humanOwner、sensitivityBaseline、defaultPermissionPolicy、可选 Agent Cell 与 Action Log entry。

细分操作

HTTP Reference：创建 Department

POST /api/v1/control-plane/companies/{companyKey}/departments
Content-Type: application/json
Idempotency-Key: <uuid>

Request Body

{
  "name": "<department-display-name>",
  "departmentKey": "<department-key>",
  "charter": "<department-charter>",
  "rootDir": "/<department-root>/",
  "owner": "<owner-role-or-id>",
  "baseline": "internal",
  "createAgentCell": true
}

CLI：创建 Department

aidc department create \
  --company <company-key> \
  --name "<department-display-name>" \
  --key <department-key> \
  --charter "<department-charter>" \
  --root-dir /<department-root>/ \
  --owner <owner-role-or-id> \
  --baseline internal \
  --init-agent-cell

部门创建后的默认动作

1. 写入 Department profile；
2. 创建或绑定 root directory；
3. 设置默认权限基线；
4. 如果 createAgentCell=true，创建部门 Agent Cell；
5. 生成部门级 AGENT.md 或 Agent profile；
6. 写入 Action Log；
7. 返回下一步建议。

部门敏感级别

4. 管理 Company

管理 Company 是创建后的持续运营 API：查看状态、修改公司信息、管理部署、管理服务器、管理部门、查看审计、暂停或归档公司。

细分操作

Company 状态机

provisioning
  → pending_review
  → active
  → degraded
  → suspended
  → archived

查看 Company 详情

GET /api/v1/control-plane/companies/{companyKey}

{
  "ok": true,
  "data": {
    "company": {
      "companyKey": "<company-key>",
      "cellId": "cell-<company-key>-<suffix>",
      "status": "active",
      "adl": "ADL-2",
      "industry": "manufacturing",
      "region": "ap-southeast-1",
      "deploymentForm": "aidc_hosted"
    },
    "summary": {
      "departments": 10,
      "agents": 12,
      "servers": 2,
      "dataSources": 8,
      "pendingApprovals": 1,
      "health": "healthy"
    }
  }
}

暂停 Company

POST /api/v1/control-plane/companies/{companyKey}/suspend
Content-Type: application/json

{
  "reason": "<suspension-reason>",
  "requestedBy": "<requester-id>",
  "keepData": true,
  "stopRuntime": true
}

• 不删除数据；
• server 可停止或保持最低运行；
• Agent 不再接收新任务；
• Action Log 与导出仍可查询；
• 恢复时必须重新跑健康检查。

5. 错误码草案

6. 幂等策略

所有创建类 API 必须支持 Idempotency-Key。生产 SDK / CLI 默认必须自动生成。

7. 审计要求

Company Management 的所有写操作都要写入 Action Log。

{
  "actor": "<actor-id>",
  "actorType": "human",
  "actionType": "CreateCompany",
  "targetRef": "company:<company-key>",
  "riskLevel": "high",
  "approvalStatus": "pending",
  "result": "partial",
  "evidence": "cell created; server pending",
  "createdAt": "<iso-8601-timestamp>"
}

8. 当前实现状态

9. 记住几句

• Company 是 AIDC 的部署边界，不是 CRM 客户记录。
• 创建 Company = 创建可运行的隔离 Cell。
• Department 是权限、目录、Agent 和业务责任的共同边界。
• 服务器操作必须通过受控 provider adapter，不允许 route 直接调用云资源。
• 所有写操作都必须留下 Action Log。
• 未来 CLI 只是 API 的命令行外壳，不能另起一套语义。