From 451a39c30a86e30369db41584a06c16d603f7345 Mon Sep 17 00:00:00 2001
From: Codex <codex@localhost>
Date: Mon, 6 Jul 2026 19:55:12 +0000
Subject: [PATCH] docs(business): explain Kingdee env variables

Expand the generated kingdee.env template with per-variable purpose and requiredness notes, including the direct access token testing option. Cover the generated guidance with Kingdee API tests.

Validation: python3 -m unittest discover -v; python3 -m compileall obsidian_wiki tests; git diff --check.
---
 obsidian_wiki/kingdee_api.py | 53 ++++++++++++++++++++++++++++++++----
 tests/test_kingdee_api.py    |  4 +++
 2 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/obsidian_wiki/kingdee_api.py b/obsidian_wiki/kingdee_api.py
index 7e158df..93a43c4 100644
--- a/obsidian_wiki/kingdee_api.py
+++ b/obsidian_wiki/kingdee_api.py
@@ -25,24 +25,67 @@ TOKEN_SKEW_SECONDS = 60
 Urlopen = Callable[[urllib.request.Request], Any]
 
 
-KINGDEE_CONFIG_TEMPLATE = f"""# Kingdee sales order API configuration.
-# This file is local-only; .runtime/ is ignored by git.
+KINGDEE_CONFIG_TEMPLATE = f"""# 金蝶销售订单 API 本地配置。
+# 这个文件只保存在本机；.runtime/ 已被 git 忽略，请不要提交密钥或 token。
+
+# 变量：KINGDEE_SALORDER_API_URL
+# 用途：查询销售订单 API 地址。
+# 是否必填：可选，默认已是当前项目使用的官方 querySalOrder 接口。
 KINGDEE_SALORDER_API_URL={DEFAULT_SALORDER_API_URL}
 
-# Token endpoint details from your Kingdee OpenAPI app.
+# 变量：KINGDEE_ACCESS_TOKEN
+# 用途：直接指定 access token，绕过自动登录/刷新流程。
+# 是否必填：可选，手动测试用；长期定时同步建议使用自动登录配置。
+KINGDEE_ACCESS_TOKEN=
+
+# 变量：KINGDEE_TOKEN_URL
+# 用途：获取 access token 的登录/token 接口地址。
+# 是否必填：自动登录时必填；如果只填 KINGDEE_ACCESS_TOKEN，则不用填。
 KINGDEE_TOKEN_URL=
+
+# 变量：KINGDEE_TOKEN_BODY_JSON
+# 用途：调用登录/token 接口时发送的 JSON 请求体，例如 app key、app secret、租户等。
+# 是否必填：自动登录时必填；必须是一行合法 JSON。
 KINGDEE_TOKEN_BODY_JSON=
+
+# 变量：KINGDEE_TOKEN_HEADERS_JSON
+# 用途：调用登录/token 接口时额外发送的请求头。
+# 是否必填：可选；没有额外 header 时保持 {{}}。
 KINGDEE_TOKEN_HEADERS_JSON={{}}
+
+# 变量：KINGDEE_TOKEN_FIELD
+# 用途：从 token 接口返回 JSON 中读取 access token 的字段路径。
+# 是否必填：可选，默认从 data.access_token 读取。
 KINGDEE_TOKEN_FIELD=data.access_token
+
+# 变量：KINGDEE_TOKEN_EXPIRES_IN_FIELD
+# 用途：从 token 接口返回 JSON 中读取有效期秒数的字段路径。
+# 是否必填：可选，默认从 data.expires_in 读取；读不到时按 3600 秒处理。
 KINGDEE_TOKEN_EXPIRES_IN_FIELD=data.expires_in
+
+# 变量：KINGDEE_REFRESH_TOKEN_FIELD
+# 用途：从 token 接口返回 JSON 中读取 refresh token 的字段路径。
+# 是否必填：可选；只有配置 refresh 流程时才有用。
 KINGDEE_REFRESH_TOKEN_FIELD=data.refresh_token
 
-# Optional refresh endpoint. Use {{refresh_token}} in the JSON body template.
+# 变量：KINGDEE_REFRESH_URL
+# 用途：refresh token 接口地址。
+# 是否必填：可选；不填时 token 过期会重新调用 KINGDEE_TOKEN_URL。
 KINGDEE_REFRESH_URL=
+
+# 变量：KINGDEE_REFRESH_BODY_JSON
+# 用途：调用 refresh 接口时发送的 JSON 请求体；可使用 {{refresh_token}} 占位符。
+# 是否必填：可选；填写 KINGDEE_REFRESH_URL 时通常需要填写。
 KINGDEE_REFRESH_BODY_JSON=
 
-# Required by the sales order API.
+# 变量：KINGDEE_ACGW_IDENTITY
+# 用途：销售订单 API 要求的 x-acgw-identity 请求头。
+# 是否必填：必填；不填无法调用销售订单查询 API。
 KINGDEE_ACGW_IDENTITY=
+
+# 变量：KINGDEE_PAGE_SIZE
+# 用途：销售订单 API 分页大小，对应请求体 pageSize。
+# 是否必填：可选，默认 100。
 KINGDEE_PAGE_SIZE={DEFAULT_PAGE_SIZE}
 """
 
diff --git a/tests/test_kingdee_api.py b/tests/test_kingdee_api.py
index 113252e..1e85e90 100644
--- a/tests/test_kingdee_api.py
+++ b/tests/test_kingdee_api.py
@@ -63,6 +63,10 @@ class KingdeeApiTests(unittest.TestCase):
         self.assertIn(f"KINGDEE_SALORDER_API_URL={DEFAULT_SALORDER_API_URL}", text)
         self.assertIn("KINGDEE_TOKEN_BODY_JSON=", text)
         self.assertIn("KINGDEE_TOKEN_URL=https://token.example", text)
+        self.assertIn("是否必填：自动登录时必填；如果只填 KINGDEE_ACCESS_TOKEN，则不用填。", text)
+        self.assertIn("用途：销售订单 API 要求的 x-acgw-identity 请求头。", text)
+        self.assertIn("是否必填：可选，手动测试用；长期定时同步建议使用自动登录配置。", text)
+        self.assertIn("是否必填：可选，默认从 data.access_token 读取。", text)
 
     def test_default_config_path_accepts_none(self):
         cwd = Path.cwd()