From 11e395aa0feee3540c57388780228a3ad50c492d Mon Sep 17 00:00:00 2001 From: SugarChes <103551815+SugarChes@users.noreply.github.com> Date: Thu, 30 Jul 2026 14:49:39 +0800 Subject: [PATCH] docs: plan browser JSON complex field compatibility --- ...0-browser-json-datatable-complex-values.md | 478 ++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-30-browser-json-datatable-complex-values.md diff --git a/docs/superpowers/plans/2026-07-30-browser-json-datatable-complex-values.md b/docs/superpowers/plans/2026-07-30-browser-json-datatable-complex-values.md new file mode 100644 index 0000000..54940ad --- /dev/null +++ b/docs/superpowers/plans/2026-07-30-browser-json-datatable-complex-values.md @@ -0,0 +1,478 @@ +# 浏览器 JSON 复杂字段兼容 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 让旧 WinForms 浏览器桥接能够把任意对象或数组字段保留为紧凑 JSON 字符串，并继续安全转换为 `DataTable`。 + +**Architecture:** 在 `Lskj.Util.JsonUtil` 增加一个只供明确调用方选用的转换入口：先扫描整批 JSON 行，确定复杂列，再把这些列统一字符串化，最后复用 Newtonsoft.Json 原有 `DataTableConverter`。`Lskj.Control` 只在网页右键和返回行两个边界调用新入口，其他 JSON 转换和 WPF 宿主保持不变。 + +**Tech Stack:** .NET Framework 4.0、C# 7.3、Newtonsoft.Json 13.0.1、`System.Data.DataTable`、MSBuild、无第三方测试框架的控制台回归测试程序。 + +## Global Constraints + +- 保留对象和数组字段，不删除 `$styles` 或其他未来字段。 +- 复杂值必须转换成无缩进的紧凑 JSON 字符串。 +- 从未出现对象或数组的标量列继续使用现有 Newtonsoft.Json 类型推断。 +- 不修改现有 `JsonUtil.ToDataTable` 和 `JsonUtil.ToDataRow` 的语义。 +- 不修改全局 Newtonsoft.Json 设置，不替换项目中的其他 `DeserializeObject` 调用。 +- 不修改 WPF、数据库、菜单查找、参数替换或 DLL 加载逻辑。 +- 只接入 `BsOpenModuleHandler.OpenRightModule` 和 `BsOpenModuleHandler.AddReturnRow`。 +- 现有两个目标源码文件只有 CRLF/LF 换行差异；执行前必须确认没有语义差异，再机械归一化，避免产生整文件噪声提交。 + +--- + +### Task 1: 建立回归测试并实现公共转换器 + +**Files:** +- Create: `插件库/Lskj.Util.Tests/Lskj.Util.Tests.csproj` +- Create: `插件库/Lskj.Util.Tests/Program.cs` +- Modify: `插件库/Lskj.Util/JsonUtil.cs:1-190` + +**Interfaces:** +- Consumes: Newtonsoft.Json `JToken`、`JArray`、`JObject` 和现有 `DataTableConverter`。 +- Produces: `public static DataTable JsonUtil.ToDataTablePreservingComplexValues(string json)`；接受顶层对象或对象数组，返回保留所有字段的 `DataTable`。 + +- [ ] **Step 1: 确认目标源码没有未提交的语义改动** + +Run: + +```bash +git diff --ignore-space-at-eol --exit-code -- \ + '插件库/Lskj.Util/JsonUtil.cs' \ + '插件库/Lskj.Control/BrowserSetting/BsOpenModuleHandler.cs' +``` + +Expected: exit code `0`，无输出。当前普通 `git diff --numstat` 显示的是 CRLF/LF 差异，不代表业务代码变化。 + +- [ ] **Step 2: 机械归一化两个目标源码的换行符** + +只有 Step 1 成功后执行： + +```bash +perl -pi -e 's/\r$//' \ + '插件库/Lskj.Util/JsonUtil.cs' \ + '插件库/Lskj.Control/BrowserSetting/BsOpenModuleHandler.cs' +git diff --check -- \ + '插件库/Lskj.Util/JsonUtil.cs' \ + '插件库/Lskj.Control/BrowserSetting/BsOpenModuleHandler.cs' +``` + +Expected: `git diff --check` 无输出；此时两个文件不再显示整文件换行差异。 + +- [ ] **Step 3: 创建不依赖测试框架的回归测试项目** + +Create `插件库/Lskj.Util.Tests/Lskj.Util.Tests.csproj`: + +```xml + + + + Debug + AnyCPU + {8E501869-816F-4E3E-81EE-A3BF9C223D61} + Exe + Lskj.Util.Tests + Lskj.Util.Tests + v4.0 + + + true + full + bin\Debug\ + AnyCPU + + + + + + + False + ..\..\引用DLL\Newtonsoft.Json.dll + True + + + + + + + + {A51BF642-6543-4DE3-8948-83F558B72BD4} + Lskj.Util + + + + +``` + +Create `插件库/Lskj.Util.Tests/Program.cs`: + +```csharp +using Lskj.Util; +using Newtonsoft.Json; +using System; +using System.Data; + +namespace Lskj.Util.Tests +{ + internal static class Program + { + private static int Main() + { + try + { + PreservesStylesObjectAsCompactJson(); + PreservesArrayAsCompactJson(); + NormalizesEveryValueInAMixedComplexColumn(); + LeavesScalarColumnsEquivalentToExistingConverter(); + AcceptsSingleObject(); + RejectsInvalidTopLevelValues(); + Console.WriteLine("PASS: JsonUtil complex-value conversion tests"); + return 0; + } + catch (Exception ex) + { + Console.Error.WriteLine(ex); + return 1; + } + } + + private static void PreservesStylesObjectAsCompactJson() + { + const string json = "[{\"id\":1,\"$styles\":{\"rowstyle\":\"{color:'#FFFF00','background-color':'#FF0000'}\"}}]"; + DataTable table = JsonUtil.ToDataTablePreservingComplexValues(json); + AssertEqual(1, table.Rows.Count, "styles row count"); + AssertEqual("{\"rowstyle\":\"{color:'#FFFF00','background-color':'#FF0000'}\"}", + table.Rows[0]["$styles"].ToString(), "styles JSON"); + } + + private static void PreservesArrayAsCompactJson() + { + const string json = "[{\"id\":1,\"items\":[{\"code\":\"A\"},{\"code\":\"B\"}]}]"; + DataTable table = JsonUtil.ToDataTablePreservingComplexValues(json); + AssertEqual("[{\"code\":\"A\"},{\"code\":\"B\"}]", + table.Rows[0]["items"].ToString(), "array JSON"); + } + + private static void NormalizesEveryValueInAMixedComplexColumn() + { + const string json = "[" + + "{\"id\":1,\"payload\":5}," + + "{\"id\":2,\"payload\":{\"code\":\"A\"}}," + + "{\"id\":3,\"payload\":[1,2]}," + + "{\"id\":4,\"payload\":null}," + + "{\"id\":5,\"payload\":\"ready\"}]"; + DataTable table = JsonUtil.ToDataTablePreservingComplexValues(json); + AssertEqual(typeof(string), table.Columns["payload"].DataType, "mixed column type"); + AssertEqual("5", table.Rows[0]["payload"].ToString(), "numeric scalar text"); + AssertEqual("{\"code\":\"A\"}", table.Rows[1]["payload"].ToString(), "object text"); + AssertEqual("[1,2]", table.Rows[2]["payload"].ToString(), "array text"); + AssertTrue(table.Rows[3].IsNull("payload"), "null remains null"); + AssertEqual("ready", table.Rows[4]["payload"].ToString(), "string remains string"); + } + + private static void LeavesScalarColumnsEquivalentToExistingConverter() + { + const string json = "[{\"id\":1,\"title\":\"A\",\"active\":true},{\"id\":2,\"title\":\"B\",\"active\":false}]"; + DataTable expected = JsonConvert.DeserializeObject(json); + DataTable actual = JsonUtil.ToDataTablePreservingComplexValues(json); + AssertEqual(expected.Columns.Count, actual.Columns.Count, "scalar column count"); + AssertEqual(expected.Rows.Count, actual.Rows.Count, "scalar row count"); + foreach (DataColumn column in expected.Columns) + { + AssertEqual(column.DataType, actual.Columns[column.ColumnName].DataType, + "scalar column type " + column.ColumnName); + for (int rowIndex = 0; rowIndex < expected.Rows.Count; rowIndex++) + { + AssertEqual(expected.Rows[rowIndex][column.ColumnName], + actual.Rows[rowIndex][column.ColumnName], + "scalar value " + column.ColumnName + " row " + rowIndex); + } + } + } + + private static void AcceptsSingleObject() + { + const string json = "{\"ProductId\":\"P001\",\"meta\":{\"source\":\"web\"}}"; + DataTable table = JsonUtil.ToDataTablePreservingComplexValues(json); + AssertEqual(1, table.Rows.Count, "single object row count"); + AssertEqual("P001", table.Rows[0]["ProductId"].ToString(), "single object scalar"); + AssertEqual("{\"source\":\"web\"}", table.Rows[0]["meta"].ToString(), "single object nested JSON"); + } + + private static void RejectsInvalidTopLevelValues() + { + AssertThrows(delegate { JsonUtil.ToDataTablePreservingComplexValues(" "); }, "empty input"); + AssertThrows(delegate { JsonUtil.ToDataTablePreservingComplexValues("{"); }, "invalid JSON"); + AssertThrows(delegate { JsonUtil.ToDataTablePreservingComplexValues("[1]"); }, "non-object row"); + } + + private static void AssertThrows(Action action, string name) where TException : Exception + { + try { action(); } + catch (TException) { return; } + throw new InvalidOperationException("Expected " + typeof(TException).Name + ": " + name); + } + + private static void AssertTrue(bool value, string name) + { + if (!value) throw new InvalidOperationException("Assertion failed: " + name); + } + + private static void AssertEqual(T expected, T actual, string name) + { + if (!object.Equals(expected, actual)) + { + throw new InvalidOperationException(name + ": expected <" + expected + ">, actual <" + actual + ">"); + } + } + } +} +``` + +- [ ] **Step 4: 构建测试项目并确认它先失败** + +Run in Windows PowerShell from `E:\lserp_project\lserp_cs_6.0`: + +```powershell +$msbuild = Get-ChildItem "${env:ProgramFiles(x86)}\Microsoft Visual Studio\2022\*\MSBuild\Current\Bin\MSBuild.exe" | + Select-Object -First 1 -ExpandProperty FullName +if (-not $msbuild) { $msbuild = "$env:WINDIR\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe" } +& $msbuild "插件库\Lskj.Util.Tests\Lskj.Util.Tests.csproj" /t:Rebuild /p:Configuration=Debug /p:Platform=AnyCPU +``` + +Expected: build fails with `CS0117` because `JsonUtil.ToDataTablePreservingComplexValues` does not exist yet. Dependency or SDK errors do not satisfy this step。 + +- [ ] **Step 5: 实现复杂字段归一化方法** + +Add `using System.Globalization;` to `插件库/Lskj.Util/JsonUtil.cs`, then add this method to `JsonUtil` without changing existing methods: + +```csharp +public static DataTable ToDataTablePreservingComplexValues(string json) +{ + if (string.IsNullOrWhiteSpace(json)) + { + throw new ArgumentException("网页行 JSON 不能为空。", "json"); + } + + JToken root = JToken.Parse(json); + JArray rows; + if (root.Type == JTokenType.Array) + { + rows = (JArray)root; + } + else if (root.Type == JTokenType.Object) + { + rows = new JArray(root); + } + else + { + throw new JsonSerializationException("网页行 JSON 的顶层必须是对象或对象数组。"); + } + + HashSet complexColumns = new HashSet(StringComparer.OrdinalIgnoreCase); + foreach (JToken rowToken in rows) + { + if (rowToken.Type != JTokenType.Object) + { + throw new JsonSerializationException("网页行 JSON 数组中的每一项都必须是对象。"); + } + + foreach (JProperty property in ((JObject)rowToken).Properties()) + { + if (property.Value.Type == JTokenType.Object || property.Value.Type == JTokenType.Array) + { + complexColumns.Add(property.Name); + } + } + } + + foreach (JObject row in rows.Children()) + { + foreach (JProperty property in row.Properties().ToList()) + { + if (!complexColumns.Contains(property.Name) + || property.Value.Type == JTokenType.Null + || property.Value.Type == JTokenType.Undefined) + { + continue; + } + + string text; + if (property.Value.Type == JTokenType.Object || property.Value.Type == JTokenType.Array) + { + text = property.Value.ToString(Formatting.None); + } + else if (property.Value.Type == JTokenType.String) + { + text = property.Value.Value(); + } + else + { + JValue scalar = property.Value as JValue; + text = scalar == null || scalar.Value == null + ? null + : Convert.ToString(scalar.Value, CultureInfo.InvariantCulture); + } + + property.Value = text == null ? JValue.CreateNull() : new JValue(text); + } + } + + return JsonConvert.DeserializeObject(rows.ToString(Formatting.None)); +} +``` + +- [ ] **Step 6: 构建并运行转换级回归测试** + +```powershell +& $msbuild "插件库\Lskj.Util.Tests\Lskj.Util.Tests.csproj" /t:Rebuild /p:Configuration=Debug /p:Platform=AnyCPU +if ($LASTEXITCODE -ne 0) { throw "Lskj.Util.Tests build failed" } +& "插件库\Lskj.Util.Tests\bin\Debug\Lskj.Util.Tests.exe" +if ($LASTEXITCODE -ne 0) { throw "Lskj.Util.Tests failed" } +``` + +Expected: build succeeds and executable prints `PASS: JsonUtil complex-value conversion tests`. + +- [ ] **Step 7: 提交公共转换器和回归测试** + +```bash +git add \ + '插件库/Lskj.Util/JsonUtil.cs' \ + '插件库/Lskj.Util.Tests/Lskj.Util.Tests.csproj' \ + '插件库/Lskj.Util.Tests/Program.cs' +git diff --cached --check +git commit -m 'fix(util): preserve complex JSON values in data tables' +``` + +Expected: commit only contains the new test project and the focused `JsonUtil` method. + +--- + +### Task 2: 在旧浏览器桥接的两个入口接入转换器 + +**Files:** +- Modify: `插件库/Lskj.Control/BrowserSetting/BsOpenModuleHandler.cs:101-116` +- Modify: `插件库/Lskj.Control/BrowserSetting/BsOpenModuleHandler.cs:322-334` + +**Interfaces:** +- Consumes: `JsonUtil.ToDataTablePreservingComplexValues(string json)` from Task 1。 +- Produces: `OpenRightModule` 和 `AddReturnRow` 对任意对象/数组字段的兼容行为；其他菜单及模块调用接口不变。 + +- [ ] **Step 1: 将右键入口切换到公共转换器** + +Replace: + +```csharp +DataTable dataTable = JsonConvert.DeserializeObject(arrayItem); +``` + +with: + +```csharp +DataTable dataTable = JsonUtil.ToDataTablePreservingComplexValues(arrayItem); +``` + +Do not change the `BaseImpl.GetDataRowResult` query, `GridRightMenuModel`, `DynamicModel` or `menu.ExecRightMenu` calls. + +- [ ] **Step 2: 将网页返回行入口切换到公共转换器并删除冗余包装** + +Replace: + +```csharp +JObject rowObject = JsonConvert.DeserializeObject(rowdata); +JArray jArray = new JArray(); +jArray.Add(rowObject); +DataTable dataTable = JsonConvert.DeserializeObject(JsonConvert.SerializeObject(jArray)); +``` + +with: + +```csharp +DataTable dataTable = JsonUtil.ToDataTablePreservingComplexValues(rowdata); +``` + +Remove the now-unused `using Newtonsoft.Json;` and `using Newtonsoft.Json.Linq;`. Keep product-prefix renaming and `StaticControl.ReturnRowLisy.Add` unchanged. + +- [ ] **Step 3: 静态检查浏览器桥接范围** + +```bash +rg -n 'DeserializeObject\s*<\s*DataTable\s*>|ToDataTablePreservingComplexValues' \ + '插件库/Lskj.Control/BrowserSetting/BsOpenModuleHandler.cs' +git diff --check -- '插件库/Lskj.Control/BrowserSetting/BsOpenModuleHandler.cs' +``` + +Expected: only two `ToDataTablePreservingComplexValues` calls remain in this file；没有直接的 `DeserializeObject`，且 `git diff --check` 无输出。 + +- [ ] **Step 4: 重跑转换级测试并构建 Lskj.Control** + +```powershell +& "插件库\Lskj.Util.Tests\bin\Debug\Lskj.Util.Tests.exe" +if ($LASTEXITCODE -ne 0) { throw "Lskj.Util.Tests failed" } +& $msbuild "插件库\Lskj.Control\Lskj.Control.csproj" /t:Rebuild /p:Configuration=Debug /p:Platform=AnyCPU +if ($LASTEXITCODE -ne 0) { throw "Lskj.Control build failed" } +``` + +Expected: tests print `PASS`；`Lskj.Control` build succeeds without new warnings or errors and refreshes `Debug\Lskj.Control.dll` plus referenced `Lskj.Util.dll`. + +- [ ] **Step 5: 提交浏览器桥接改动** + +```bash +git add '插件库/Lskj.Control/BrowserSetting/BsOpenModuleHandler.cs' +git diff --cached --check +git commit -m 'fix(browser): accept nested values in row callbacks' +``` + +Expected: commit only changes the two intended browser callback conversions and removes the two unused Newtonsoft `using` directives. + +--- + +### Task 3: 最终构建与业务验收交接 + +**Files:** +- Verify: `Debug/Lskj.Util.dll` +- Verify: `Debug/Lskj.Control.dll` +- Verify: `Debug/Ls_NERP.exe` + +**Interfaces:** +- Consumes: Task 1 的转换器和 Task 2 的浏览器接入。 +- Produces: 可由用户分别从旧 WinForms 和 WPF 宿主进行验收的 Debug 运行目录。 + +- [ ] **Step 1: 执行最终自动验证** + +```powershell +& $msbuild "插件库\Lskj.Util.Tests\Lskj.Util.Tests.csproj" /t:Rebuild /p:Configuration=Debug /p:Platform=AnyCPU +if ($LASTEXITCODE -ne 0) { throw "Lskj.Util.Tests build failed" } +& "插件库\Lskj.Util.Tests\bin\Debug\Lskj.Util.Tests.exe" +if ($LASTEXITCODE -ne 0) { throw "Lskj.Util.Tests failed" } +& $msbuild "插件库\Lskj.Control\Lskj.Control.csproj" /t:Rebuild /p:Configuration=Debug /p:Platform=AnyCPU +if ($LASTEXITCODE -ne 0) { throw "Lskj.Control build failed" } +Get-Item "Debug\Lskj.Util.dll", "Debug\Lskj.Control.dll" | + Select-Object FullName, Length, LastWriteTime +``` + +Expected: both builds succeed, test executable prints `PASS`, and both runtime DLL timestamps reflect the current build. + +- [ ] **Step 2: 核对最终差异和提交历史** + +```bash +git diff --check +git status --short +git log -4 --oneline --decorate +``` + +Expected: no uncommitted implementation changes；历史包含设计提交、公共转换器提交和浏览器桥接提交。构建输出和原有忽略文件不应进入 Git。 + +- [ ] **Step 3: 交给用户执行业务验收** + +Provide this exact checklist: + +```text +1. 从 WPF 宿主启动，进入同一待办任务页面并点击“待办任务”。 +2. 确认不再出现 Path '[0].$styles' / StartObject 的 DataTable 反序列化错误。 +3. 确认右键配置继续解析到 PUR_4004，并正常进入原有客户端模块加载流程。 +4. 使用一个不包含对象/数组字段的旧网页右键功能，确认行为未变化。 +5. 如可用，再从旧 WinForms 入口重复步骤 1-4，确认两个宿主行为一致。 +6. 验证网页返回行功能，确认 ProductId 前缀和原有回填逻辑未变化。 +``` + +No additional source commit is required for this manual acceptance step.