# yh-platform-net

yunhai 基础平台的 .NET SDK（对齐 Java `yh-platform`），让 .NET 应用以与 Java 完全一致的方式接入平台核心能力：用户信息、`/oapi` 开放接口、应用签名鉴权（yh-app-auth）、CAS 单点登录（yh-auth）。

## 工程结构

```
BasePlatformDotnet/
├── src/
│   ├── Yh.Platform.Abstractions/   # 模型与契约：BoaUser/BoaGroup/BoaRoleInfo、ApiEnvelope、DException、IErrorCode
│   ├── Yh.Platform.AppAuth/        # 应用签名：SignUtil/SignCanonical/AppSignHandler/SignKeyResolver/ReplayGuard
│   ├── Yh.Platform.OpenApi/        # /oapi 客户端：用户/组织/应用三域 + 双形态门面（静态 YschBaseOpenApi / 实例 BaseOpenApi）
│   └── Yh.Platform.Auth/           # CAS SSO：CasServiceTicketValidator/CasAuthenticationHandler、BoaUserContext、UserContextHolder
├── tests/                          # xunit：Abstractions/AppAuth/OpenApi/Auth 四个测试工程
├── samples/Yh.Platform.Sample.Web/ # ASP.NET Core 集成示例
├── contract/                       # 跨语言契约工件
│   ├── sign-protocol.md            # 签名协议权威定义（Java/.NET 共同遵守）
│   ├── openapi-oapi.yaml           # UserBase /oapi OpenAPI 规范（38 个端点）
│   └── fixtures/                   # 信封样例与 13 组签名测试向量（tools/gen_sign_vectors.py 独立生成）
└── tools/gen_sign_vectors.py       # 签名向量生成器（独立 Python 实现做双向对拍）
```

## 多目标框架

`net5.0; net8.0`：net5.0 供存量 GrowthHealth 等老项目使用，net8.0 供新项目。依赖版本由 `Directory.Packages.props`（CPM，等价 Java BOM）统一管理，net5.0 走条件版本兜底。

## 快速开始

### 1. 注册服务

```csharp
builder.Services.AddYhOpenApi(builder.Configuration);   // yh:open 配置节
builder.Services.AddYhAuth(builder.Configuration);      // yh:sso 配置节（CAS）
```

```json
{
  "yh": {
    "open": {
      "BaseHost": "http://base.bestsch.com",
      "BasePath": "/userbase",
      "AppKey": "your-app-key",
      "AppSecret": "your-app-secret"
    },
    "sso": {
      "CasServerUrlPrefix": "https://sso.example.com/cas"
    }
  }
}
```

### 2. 调用开放接口

```csharp
// 静态门面（高频读）
var user = await YschBaseOpenApi.GetUserInfoAsync(loginName);
var tree = await YschBaseOpenApi.GetGroupTreeAsync();

// 实例客户端（低频写、需精细控制）
var role = await userClient.SwitchIdentityAsync(userId, roleId, schoolId);
```

响应解析为"信封感知"：成功返回裸数据；业务失败（HTTP 200 + `{code≠0, msg, data}`）抛 `DException`，`Code`/`Data` 原样携带服务端内容。

### 3. 应用签名（服务端验签 / 客户端签名）

```csharp
builder.Services.AddYhAppAuth(builder.Configuration);   // SignKeyResolver/ReplayGuard/AppAuthVerifier + 客户端 AppSignHandler
```

校验签名三件套（`X-App-Key` / `X-Timestamp` / `X-Signature`）：

```csharp
var ok = await verifier.VerifyAsync(appKey, timestamp, signature, "GET", "/oapi/user/byId?id=1", nonce);
```

签名规则见 [contract/sign-protocol.md](contract/sign-protocol.md)：
- 数据级：`HMAC_SHA256(secret, data + ts)` 小写 hex
- 请求级：`HMAC_SHA256(secret, METHOD\npath?sortedQuery\nts)` Base64

密钥解析链：Redis → MemoryCache → UserBase 兜底。

### 4. 用户上下文

```csharp
var boaUser = BoaUserContext.Get();          // 当前请求 BoaUser（AsyncLocal）
var login   = UserContextHolder.Get();       // 当前请求 LoginUser
```

## 测试

```bash
dotnet test yh-platform-net.sln
```

覆盖：模型双序列化对拍、签名向量对拍（13 组独立 Python 生成向量）、URL 规范化、信封解析（成功/业务失败/HTTP 错误）、CAS XML 提取、用户上下文生命周期。

## 与 Java 侧对应关系

| .NET | Java |
|---|---|
| Yh.Platform.Abstractions | yh-platform-utils（模型） |
| Yh.Platform.AppAuth | yh-app-auth-spring-boot-starter |
| Yh.Platform.OpenApi | yh-openapi-client |
| Yh.Platform.Auth | yh-auth-core + yh-auth-spring-boot-starter |