AI 阅读指南

受众：Cursor Agent、Copilot 及其他自动化开发 AI。
目标：读完后能正确选择文档、完成「新建资源服务」或「调用已有资源服务」两类任务。

文档地图（按任务选读）

你的任务	先读	再读
理解请求怎么走（架构/链路）	请求链路与调用说明	按场景选下方专项文档
开发新的资源服务（如车辆管理系统）	新建资源服务	Unified Auth 接入 → Gateway 接入
作为第三方调用 ME56（如调运单）	跨服务调用	ME56 第三方集成 → 运单 API
作为第三方调用 Fleet	跨服务调用	Fleet 第三方集成
作为第三方调用 Nexus	跨服务调用	Nexus 第三方集成
仅对接登录 / Token	Unified Auth AI 接入	OAuth2 API / API Key
查某服务全部接口	该服务 /api/overview	按模块拆分的 API 页

服务分类速查

# 机器可读：服务注册表摘要（与 services.ts 同步）
infra:
  - id: unified-auth
    role: 签发 JWT、OAuth2 Client、API Key 换票
    port: 9000
    gateway_prefix: /auth
  - id: gateway
    role: 统一入口、路由、API Key 自动换票
    port: 8990
    gateway_prefix: /

business:
  - id: nexus
    role: 物业管理业务 API
    port: 9300
    gateway_prefix: /nexus/core
  - id: me56
    role: 物流运输多微服务
    ports: "9108-9170（按模块）"
    gateway_prefix: /me56/{module}
  - id: fleet
    role: 车队管理（车队长工具，对接 ME56）
    port: 9170
    gateway_prefix: /me56/fleet

两套响应格式（勿混淆）

体系	成功标识	字段	使用服务
Auth / Gateway / Nexus	code: 200 或 "200"	code, message, data, timestamp	unified-auth、gateway、nexus
ME56 _legacy	ret: 0	ret, message, data, type	me56 各微服务

调用前先确认目标服务属于哪一套。

认证决策树

需要调用业务 API？
├─ 浏览器 / 用户登录
│   └─ OAuth2 授权码 → POST /auth/oauth2/token → Bearer JWT
├─ 服务端 / 脚本 / 定时任务（推荐）
│   └─ 创建 API Key → 经 Gateway 带 X-API-Key: sk_*（自动换票）
│       或 POST /auth/api-keys/exchange → Bearer JWT
└─ ME56 历史兼容
    └─ 见 /services/unified-auth/api/me56-compat（优先迁移到标准 OAuth2）

网关 URL 拼接规则

完整 URL = {GATEWAY_BASE} + {gateway_prefix} + {业务路径}

示例（本地）：
  GWAY = http://127.0.0.1:8990
  ME56 运单创建 = GWAY + /me56/waybill/createWaybill
  Nexus 用户列表 = GWAY + /nexus/core/iam/user/list
  换 Token      = GWAY + /auth/auth/token  或 /auth/oauth2/token

StripPrefix 已由网关处理，调用方路径必须带前缀（如 /me56/waybill/...），不要省略。

推荐阅读顺序（新建资源服务）

1. 新建资源服务清单 — 步骤与配置模板
2. Unified Auth 接入 — 注册 Client、Resource Server
3. Gateway 接入 — 注册路由
4. 编写本服务 docs/services/{id}/ 并注册 services.ts

推荐阅读顺序（第三方调用已有服务）

1. 跨服务调用约定 — 认证、URL、错误处理
2. 目标服务 guide/third-party-integration.md — 能力边界与示例场景
3. 目标服务 api/*.md — 具体接口参数

文档路径约定

docs/services/{service-id}/
├── guide/
│   ├── getting-started.md
│   ├── ai-integration.md          # 基础设施：被新服务依赖时读
│   └── third-party-integration.md # 业务系统：被第三方调用时读
└── api/
    ├── overview.md                # 统一约定 + 模块索引
    └── {module}.md

新增服务文档时请同时提供 ai-integration 或 third-party-integration（按服务类型二选一或两者皆有）。