From 57b781a31656745645701f4127bbce9f484768f2 Mon Sep 17 00:00:00 2001
From: xRain <xrain@simcu.com>
Date: Tue, 18 Aug 2026 04:52:31 +0800
Subject: [PATCH] =?UTF-8?q?README:=20=E6=96=B0=E5=A2=9E=E5=BC=95=E5=85=A5?=
 =?UTF-8?q?=E7=AB=A0=E8=8A=82(=E4=B8=AD=E5=A4=AE=E4=BB=93=20+=20Git=20?=
 =?UTF-8?q?=E4=B8=A4=E7=A7=8D=E6=96=B9=E5=BC=8F),=20=E5=8C=85=E5=90=8D?=
 =?UTF-8?q?=E6=9B=B4=E6=96=B0=E4=B8=BA=20simcu::simapi=20/=20simcu::serial?=
 =?UTF-8?q?ization?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 64 +++++++++++++++++++++++++++++++++++++------------------
 cjpm.toml |  2 +-
 2 files changed, 44 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 2d1bcfa..98d6f22 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,28 @@
 
 ---
 
+## 引入
+
+两种方式任选其一：
+
+**方式一：中央仓**（需先 `cjpm publish` 发布 `simcu::simapi`）
+
+```toml
+[dependencies]
+"simcu::simapi" = "5.2.12"
+```
+
+**方式二：Git 仓库**
+
+```toml
+[dependencies]
+"simcu::simapi" = { git = "https://gitcode.com/simcu/simapi-cj.git", version = "5.2.12" }
+```
+
+> 本地开发也可用 path 依赖：`"simcu::simapi" = { path = "../simapi-cj" }`
+
+---
+
 ## 快速开始
 
 ```cangjie
@@ -16,9 +38,9 @@ import soulsoft_web_routing.*
 import soulsoft_web_hosting.*
 import soulsoft_extensions_logging.*
 import soulsoft_extensions_injection.*
-import simapi.*
-import simapi.communications.*
-import simapi.helpers.*
+import simcu::simapi.*
+import simcu::simapi.communications.*
+import simcu::simapi.helpers.*
 
 main(args: Array<String>) {
     let builder = WebHost.createBuilder(args)
@@ -59,7 +81,7 @@ main(args: Array<String>) {
 | 404  | 资源不存在 |
 | 500  | 服务器错误 |
 
-响应 JSON（经 simapi_serialization 反射序列化，字段**无下划线**）：
+响应 JSON（经 simcu::serialization 反射序列化，字段**无下划线**）：
 
 ```json
 { "code": 200, "message": "成功", "data": { ... } }
@@ -106,7 +128,7 @@ simapi-cj/
 ### 1. 错误处理 — SimApiError
 
 ```cangjie
-import simapi.helpers.*
+import simcu::simapi.helpers.*
 
 SimApiError.error(500, "服务器内部错误")          // 直接抛错
 SimApiError.errorWhen(amount <= 0, 400, "金额无效") // 条件为 true 时抛错
@@ -117,8 +139,8 @@ SimApiError.errorWhenNull(someOptional, 404, "用户不存在")
 ### 2. 认证 — SimApiAuth
 
 ```cangjie
-import simapi.helpers.*
-import simapi.communications.*
+import simcu::simapi.helpers.*
+import simcu::simapi.communications.*
 
 // 由 DI 注入（构造参数 options: SimApiOptions，从配置读 RedisConfiguration；未配则 InMemory）
 let auth: SimApiAuth = ...   // 例：控制器构造注入
@@ -141,7 +163,7 @@ auth.logoutAll("user-001")                      // 退出全部
 标注在控制器**方法或类**上，请求派发时自动执行鉴权（未登录 401 → 类型不匹配 403 → 遍历执行 `ISimApiAuthChecker`）：
 
 ```cangjie
-import simapi.annotations.{SimApiAuth}
+import simcu::simapi.annotations.{SimApiAuth}
 
 @SimApiAuth                    // 类级：整个控制器需登录
 public class MyController <: SimApiBaseController {
@@ -159,7 +181,7 @@ public class MyController <: SimApiBaseController {
 标注后跳过统一响应封装，接口返回什么就输出什么（对齐 C# `[OriginResponse]`）：
 
 ```cangjie
-import simapi.annotations.{OriginResponse}
+import simcu::simapi.annotations.{OriginResponse}
 
 @OriginResponse
 @HttpGet["raw"]
@@ -173,8 +195,8 @@ public func raw(): String {
 标注在控制器**方法或类**上，请求派发时自动验签（appId 提取 → 密钥获取 → timestamp 过期校验 → nonce 去重 → MD5 比对）：
 
 ```cangjie
-import simapi.annotations.{SimApiSign}
-import simapi.interfaces.{SimApiSignProviderBase}
+import simcu::simapi.annotations.{SimApiSign}
+import simcu::simapi.interfaces.{SimApiSignProviderBase}
 
 // 1. 继承 Provider 实现密钥获取（并注册到 DI）
 public class MySignProvider <: SimApiSignProviderBase {
@@ -195,8 +217,8 @@ public func signedAction(): String { "ok" }
 标注在**参数**上，请求派发时自动解密 `{"data":"密文"}` body 并反序列化为参数类型：
 
 ```cangjie
-import simapi.annotations.{AesBody}
-import simapi.interfaces.{AesBodyProviderBase}
+import simcu::simapi.annotations.{AesBody}
+import simcu::simapi.interfaces.{AesBodyProviderBase}
 
 public class MyAesProvider <: AesBodyProviderBase {
     public override func getKey(appId: ?String): ?String {
@@ -235,7 +257,7 @@ SimApiUtil.md5("text")       // 32 位十六进制
 SimApiUtil.sha1("text")      // 40 位
 SimApiUtil.base64Encode("text") / base64Decode("...")
 SimApiUtil.base64Encode(obj) // 对象 → JSON → Base64（对齐 C# Base64Encode(object)）
-SimApiUtil.json(obj)         // 对象 → JSON 字符串（simapi_serialization 反射）
+SimApiUtil.json(obj)         // 对象 → JSON 字符串（simcu::serialization 反射）
 SimApiUtil.escapeJson(s)     // JSON 字符串转义
 SimApiUtil.fromJson<T>(json) // JSON → T（对齐 C# FromJson<T>，任意类免约束）
 SimApiUtil.base64DecodeTo<T>(str)  // Base64 → JSON → T
@@ -243,7 +265,7 @@ SimApiUtil.checkCell("13800138000")   // 手机号
 SimApiUtil.checkEmail("a@b.com")      // 邮箱
 ```
 
-> JSON 序列化/反序列化统一走 **simapi_serialization**（`JsonSerializer.Serialize` / `Deserialize<T>`），任意类免标注、免接口约束。
+> JSON 序列化/反序列化统一走 **simcu::serialization**（`JsonSerializer.Serialize` / `Deserialize<T>`），任意类免标注、免接口约束。
 
 ### 4.1 AES 加解密 — SimApiAesUtil（对齐 C# SimApiAesUtil）
 
@@ -260,7 +282,7 @@ let plain = SimApiAesUtil.decrypt(encrypted, "key字符串")
 ### 4.2 实体基类 — SimApiBaseModel（对齐 C# SimApiBaseModel）
 
 ```cangjie
-import simapi.models.*
+import simcu::simapi.models.*
 
 public class User <: SimApiBaseModel {
     public var _name: String = ""
@@ -375,7 +397,7 @@ options.configureSimApiRoute { route =>
 实现后每次认证成功都会调用（配合 `@SimApiAuth` 注解或手动 `requireLogin`）：
 
 ```cangjie
-import simapi.interfaces.*
+import simcu::simapi.interfaces.*
 
 class MyAuthChecker <: ISimApiAuthChecker {
     public func run(loginItem: SimApiLoginItem, token: String): Unit {
@@ -407,7 +429,7 @@ SimApiExtensions.addSimApi(builder) { options =>
 | `SimApiAuthCenterMiddleware` | 网关透传：`X-SimApi-Gate-Auth/Time/Sign` 三头 MD5 校验 → Base64 解码 LoginInfo |
 
 ```cangjie
-import simapi.authsdk.*
+import simcu::simapi.authsdk.*
 
 let center = SimApiAuthCenter(client)     // client 从 DI 注入
 let groups = center.groupRelated(profileId)          // 群组列表
@@ -470,8 +492,8 @@ simapi 提供 Spire MVC 控制器（继承 `SimApiBaseController`），`addSimAp
 | `SimApiBaseController` | — | 基类：`loginInfo` / `loginToken` / `requireLogin()` / `getLogin()` |
 
 ```cangjie
-import simapi.controllers.*
-import simapi.annotations.{SimApiAuth}
+import simcu::simapi.controllers.*
+import simcu::simapi.annotations.{SimApiAuth}
 
 // 控制器写法：继承 SimApiBaseController，注解路由 + DI 注入
 @SimApiAuth                    // 类级鉴权（可选，替代 requireLogin）
@@ -512,7 +534,7 @@ public class MyController <: SimApiBaseController {
 | `soulsoft_extensions_logging` 系列 | 日志 |
 | `soulsoft_extensions_injection` | 依赖注入 |
 | `soulsoft_extensions_configuration` | 配置 |
-| `simapi_serialization`（path 依赖） | JSON 序列化（simapi 自研，反射免标注） |
+| `simcu::serialization`（path 依赖） | JSON 序列化（simapi 自研，反射免标注） |
 | `redis`（pkg.cangjie-lang.cn） | Redis 客户端（认证/缓存 Redis 模式） |
 | `stdx`（CANGJIE_STDX_PATH） | 标准扩展库（md5/sha1/base64/http/tls） |
 
diff --git a/cjpm.toml b/cjpm.toml
index 0d195f9..8101d1a 100644
--- a/cjpm.toml
+++ b/cjpm.toml
@@ -3,7 +3,7 @@
   name = "simapi"
   organization = "simcu"
   description = "SimApi 仓颉版：ASP.NET Core 风格 API 基础框架（统一响应/异常拦截/Token认证/缓存/工具集/HTTP客户端）"
-  version = "5.2.12"
+  version = "1.0.3"
   target-dir = ""
   output-type = "static"
   override-compile-option = ""