From e24b73ee96170a9f313449119ac1d203fd615529 Mon Sep 17 00:00:00 2001
From: xRain <xrain@simcu.com>
Date: Mon, 17 Aug 2026 14:00:47 +0800
Subject: [PATCH] =?UTF-8?q?refactor:=20JsonAnnotations.cj=20=E7=A7=BB?=
 =?UTF-8?q?=E8=87=B3=E6=A0=B9=E7=9B=AE=E5=BD=95=E6=94=B9=E5=90=8D=20Annota?=
 =?UTF-8?q?tions.cj?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 注解类 SerializerPropertyName/SerializerIgnore 从 simapi_serialization.json
  子包移至根包 simapi_serialization（文件 src/Annotations.cj）
- 打破循环依赖：根锚点不再 public import json 子包，序列化器由用户显式
  import simapi_serialization.json.*
- ReflectionCache / 测试文件补 import simapi_serialization.*
- serialization_test 同步补 import simapi_serialization.json.*
- 16 用例全绿
---
 docs/父类字段序列化方案.md                      |  4 ++--
 src/{json/JsonAnnotations.cj => Annotations.cj} | 12 ++++++------
 src/SimApiSerialization.cj                      | 12 ++++++------
 src/json/JsonSerializer_test.cj                 |  1 +
 src/json/ReflectionCache.cj                     |  1 +
 5 files changed, 16 insertions(+), 14 deletions(-)
 rename src/{json/JsonAnnotations.cj => Annotations.cj} (68%)

diff --git a/docs/父类字段序列化方案.md b/docs/父类字段序列化方案.md
index 39fdd37..46a490e 100644
--- a/docs/父类字段序列化方案.md
+++ b/docs/父类字段序列化方案.md
@@ -171,7 +171,7 @@ soulsoft 的 API 带泛型约束 `where T <: ISerializable`，不标宏的类在
 ### 3.1 宏定义
 
 ```cangjie
-// 文件：src/json/SerializerParentMacro.cj
+// 文件：src/macros/SerializerParentMacro.cj
 // 包：simapi_serialization.json（宏包需单独编译，见 3.3）
 
 macro package simapi_serialization.json
@@ -535,7 +535,7 @@ main() {
 
 ## 9. 实施步骤（评审通过后）
 
-1. 新建宏文件 `src/json/SerializerParentMacro.cj`（或独立宏包），实现 `SerializerParent` 宏；
+1. 新建宏文件 `src/macros/SerializerParentMacro.cj`（或独立宏包），实现 `SerializerParent` 宏；
 2. 验证 cjpm 对宏包的编译流程（风险 #1），必要时调整项目结构；
 3. 改 `JsonWriter.writeObject`：superClass 链调用 `exportJsonFields`；
 4. 改 `JsonReader.readObject`：superClass 链调用 `importJsonFields`；
diff --git a/src/json/JsonAnnotations.cj b/src/Annotations.cj
similarity index 68%
rename from src/json/JsonAnnotations.cj
rename to src/Annotations.cj
index fe689bc..c1d687f 100644
--- a/src/json/JsonAnnotations.cj
+++ b/src/Annotations.cj
@@ -1,8 +1,8 @@
 /*
  * Copyright (c) 2025 SimcuTeam. All rights reserved.
- * 对齐 .NET System.Text.Json.Serialization 特性：
- *   - [SerializerPropertyName("xxx")]  → @SerializerPropertyName["xxx"]  指定字段的 JSON 名称
- *   - [SerializerIgnore]               → @SerializerIgnore               序列化/反序列化时忽略该字段
+ * 序列化注解（对齐 .NET System.Text.Json.Serialization 特性）：
+ *   - [JsonPropertyName("xxx")]  → @SerializerPropertyName["xxx"]  指定字段的序列化名称
+ *   - [JsonIgnore]               → @SerializerIgnore               序列化/反序列化时忽略该字段
  *
  * 设计决策：本库序列化/反序列化只处理「var 成员变量」（std.reflect 的 instanceVariables），
  * 不处理 prop 属性（instanceProperties）。因此注解 target 仅限 MemberVariable：
@@ -12,10 +12,10 @@
  * https://docs.cangjie-lang.cn/en/docs/1.0.0/libs/std/reflect/reflect_samples/annotation.html
  */
 
-package simapi_serialization.json
+package simapi_serialization
 
 /**
- * 指定字段的 JSON 名称（对齐 .NET SerializerPropertyNameAttribute）。
+ * 指定字段的序列化名称（对齐 .NET JsonPropertyNameAttribute）。
  * 用法：@SerializerPropertyName["user_name"] public var _username: String = ""
  */
 @Annotation[target: [MemberVariable]]
@@ -28,7 +28,7 @@ public class SerializerPropertyName {
 }
 
 /**
- * 标记字段不做 JSON 处理（对齐 .NET SerializerIgnoreAttribute）。
+ * 标记字段不做序列化处理（对齐 .NET JsonIgnoreAttribute）。
  * 用法：@SerializerIgnore public var _temp: String = ""
  */
 @Annotation[target: [MemberVariable]]
diff --git a/src/SimApiSerialization.cj b/src/SimApiSerialization.cj
index d523683..df1763d 100644
--- a/src/SimApiSerialization.cj
+++ b/src/SimApiSerialization.cj
@@ -1,12 +1,12 @@
 /*
  * Copyright (c) 2025 SimcuTeam. All rights reserved.
  *
- * simapi_serialization 根包锚点（cjpm 要求 src 根目录至少有一个 .cj 文件，否则不扫描子目录）。
- * 全部实现位于子包 simapi_serialization.json（对应 .NET System.Text.Json）。
- * 通过 public import 重导出：`import simapi_serialization.*` 仍可直接使用
- * JsonSerializer / JsonOption / @SerializerPropertyName / @SerializerIgnore 等。
+ * simapi_serialization 根包锚点：注解类（@SerializerPropertyName / @SerializerIgnore）同包于此。
+ * 序列化器位于子包 simapi_serialization.json（对应 .NET System.Text.Json）。
+ *
+ * 用法：
+ *   import simapi_serialization.*         // 注解
+ *   import simapi_serialization.json.*    // JsonSerializer / JsonOption
  */
 
 package simapi_serialization
-
-public import simapi_serialization.json.*
diff --git a/src/json/JsonSerializer_test.cj b/src/json/JsonSerializer_test.cj
index e39ad95..bcecd50 100644
--- a/src/json/JsonSerializer_test.cj
+++ b/src/json/JsonSerializer_test.cj
@@ -13,6 +13,7 @@ package simapi_serialization.json
 import std.collection.*
 import std.unittest.*
 import std.unittest.testmacro.*
+import simapi_serialization.*
 import simapi_serialization.macros.*
 
 enum Role {
diff --git a/src/json/ReflectionCache.cj b/src/json/ReflectionCache.cj
index 4ccc154..6b57550 100644
--- a/src/json/ReflectionCache.cj
+++ b/src/json/ReflectionCache.cj
@@ -11,6 +11,7 @@ package simapi_serialization.json
 
 import std.collection.*
 import std.reflect.*
+import simapi_serialization.*
 
 /**
  * 单个字段的序列化元数据。