Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 QiuSW
|
e91fc0cc28 | ||
|
QiuSW
|
003ab38a36 |
@@ -1,11 +1,17 @@
|
||||
# Agent 开发规则
|
||||
|
||||
本仓库采用精简的单人 DevHarness 工作流：Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的唯一事实来源；Gitea Wiki 只维护长期产品、架构、契约、业务规则、安全边界和运行说明；Git 保存源码、迁移、测试、版本绑定资料和 Wiki 的本地镜像。`docs/` 中显式映射的 Markdown 是 Wiki 只读镜像；既有 Wiki 任务归档和 `docs/task/` 仅作历史兼容，只有用户明确要求专项快照时才创建或导出。
|
||||
本仓库采用轻量治理的精简单人 DevHarness 工作流：需要工单的任务以 Gitea 工单作为单次需求、变化、实现、测试、提交和验收的事实来源；Gitea Wiki 只维护长期产品、架构、契约、业务规则、安全边界和运行说明；Git 保存源码、迁移、测试、版本绑定资料和 Wiki 的本地镜像。`docs/` 中显式映射的 Markdown 是 Wiki 只读镜像；既有 Wiki 任务归档和 `docs/task/` 仅作历史兼容，只有用户明确要求专项快照时才创建或导出。
|
||||
|
||||
当前文档规则参考 DevHarness 提交 `4bbacf4d7fb265984396bb5589c544105043fa0b`，但所有模板内容都必须按 GoAuto 事实改写。开始工作前阅读任务涉及目录中的 `AGENTS.md`。不同交付单元规则不同时，在 `server/`、`web/` 或 `android/` 下增加更具体的 `AGENTS.md`；目录越深的规则越具体，但不得削弱上级安全规则。
|
||||
当前文档规则参考 DevHarness 提交 `ecab899`，但所有模板内容都必须按 GoAuto 事实改写。开始工作前阅读任务涉及目录中的 `AGENTS.md`。不同交付单元规则不同时，在 `server/`、`web/` 或 `android/` 下增加更具体的 `AGENTS.md`；目录越深的规则越具体，但不得削弱上级安全规则。
|
||||
|
||||
[项目档案](docs/00-project-profile.md) 按需阅读，不作为每次任务的固定前置。出现下列情况之一时必须读：需要环境、配置或凭据来源；需要确认目录边界；需要判断子项目与交付单元划分；需要 DevHarness 来源与基线；需要项目专用验收要求。只为查命令不必打开项目档案。涉及采集、采购或设备行为时另读 `docs/03-business-rules-and-glossary.md` 和当前工单。
|
||||
|
||||
## 语言与术语
|
||||
|
||||
- 用户可以使用中文、英文或合理的中英混合语言交流；默认使用中文分析、回复、编写工单和维护内部项目文档。
|
||||
- 代码标识符、命令、参数、路径、文件名、API 名称、协议名、日志和错误原文保持原样；必要时补充简短中文解释。
|
||||
- 用户明确要求某次回复或交付物使用其他语言时，按该次要求执行，不改写接口契约或影响搜索和执行的原文。
|
||||
|
||||
## 常用命令
|
||||
|
||||
所有命令默认从仓库根目录执行。
|
||||
@@ -16,6 +22,7 @@
|
||||
| 检查模板结构 | `python dev_scripts/harness.py check --strict` |
|
||||
| 导出核心 Wiki 镜像 | `python dev_scripts/harness.py sync` |
|
||||
| 检查核心 Wiki 镜像 | `python dev_scripts/harness.py sync --check` |
|
||||
| 深度检查核心 Wiki 镜像 | `python dev_scripts/harness.py sync --deep-check` |
|
||||
| 导出并完整校验 | `python dev_scripts/harness.py sync --verify` |
|
||||
| 创建可选任务快照 | `python dev_scripts/harness.py archive 123 "修复登录超时"` |
|
||||
| 增量导出已有快照 | `python dev_scripts/harness.py export` |
|
||||
@@ -40,18 +47,28 @@
|
||||
- 测试结果必须真实；未执行或无法覆盖的真机、多设备、云环境和高风险行为必须明确记录。
|
||||
- 高风险修改必须停止并等待人工确认：创建订单、权限、安全、并发、数据库迁移、删除数据、发布和其他不可逆操作。
|
||||
|
||||
### 项目治理模式与明确授权后的执行
|
||||
|
||||
- GoAuto 默认采用轻量治理：文案、注释、格式、局部样式或布局、预期行为明确的小 Bug，以及不改变接口、数据结构、权限和安全边界的单模块低风险调整可以直接实施，无需为了留痕补建工单。完整独立需求、新页面、跨模块功能，以及涉及 API、数据结构、权限、安全、迁移或范围不明确的变化必须建单。
|
||||
- 采购、创建订单、权限、安全、并发、数据库迁移、删除数据、发布和其他不可逆操作按高风险任务处理；未取得有效人工授权时必须停止。
|
||||
- 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据，不要求把同一授权重复复制到工单后再次确认。
|
||||
- 授权必须能识别操作、对象和范围；Agent 自动生成的工单、草稿、摘要或对用户意图的转述不能单独构成人工授权。
|
||||
- 获得有效授权后，只核对准确目标、授权范围和当前状态等最小必要前提，不得仅因操作不可逆而重复询问或拒绝。
|
||||
- 授权不自动覆盖相邻对象或后续任务；环境、对象、范围或影响发生实质变化时必须重新确认。平台自身强制的审批、安全策略或权限限制继续有效。
|
||||
|
||||
## 2. 哪些改动需要工单
|
||||
|
||||
新功能、缺陷修复、重构，以及接口、数据库、权限、并发、状态机、安全或用户界面变化必须先有单元工单。
|
||||
完整独立需求、新页面、跨模块功能、范围不明确的变化，以及接口、数据库、权限、并发、状态机或安全边界变化必须先有单元工单。采购、创建订单、数据库迁移、删除数据、发布和其他不可逆操作无论规模大小都必须建单。
|
||||
|
||||
以下小改动只有在范围明确、容易回退且不涉及上面的必须建单项时才可以直接提交：
|
||||
以下低风险改动在范围明确、容易回退、不改变接口、数据结构、权限或安全边界，且不属于上述高风险事项时可以直接提交：
|
||||
|
||||
- 只改错别字、注释或文档措辞；
|
||||
- 只做格式化、导入排序或不跨文件的内部变量改名；
|
||||
- 补充类型标注或文档字符串且不改变行为；
|
||||
- 补充不改变产品行为的测试；
|
||||
- 删除已经确认无人使用的死代码；
|
||||
- 修复单文件、低风险且只恢复已有明确行为的缺陷；
|
||||
- 修复预期行为明确、影响局限于单个模块的低风险缺陷；
|
||||
- 不改变对外行为、入口、配置和验证方式的局部内部重构；
|
||||
- 只修改用户看到的界面显示文案，并且满足本文件「工单与设计证据双门禁」的全部豁免条件。
|
||||
|
||||
直接提交仍须保护无关改动、执行受影响范围的最小验证并写清提交说明。有任何不确定，或涉及接口、数据库、状态、权限、安全、并发、用户界面时，必须退回单元工单流程。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用豁免。
|
||||
@@ -184,6 +201,7 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明
|
||||
- 提交只包含当前工单相关文件，提交信息引用工单号。
|
||||
- 优先运行项目档案记录的格式、单元、契约和集成测试。
|
||||
- Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不得仅为设置编码重复启动一层 PowerShell。
|
||||
- Windows 命令不得默认套用 Bash 语法。复杂正则优先使用变量或 `rg -e`；包含引号和换行的脚本正文优先使用单引号 PowerShell here-string；`foreach`、`if` 等语句块保持在同一个 PowerShell 解析上下文中；`rg` 使用真实目录配合 `-g/--glob`，不要把 Bash 风格通配路径作为目录参数。
|
||||
- 文本文件读写在命令支持时显式指定 UTF-8；文件解码和控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才设置当前进程的输出编码或 Python UTF-8 环境变量。
|
||||
- 不得默认使用 `-ExecutionPolicy Bypass`；只有可信 `.ps1` 确实被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。
|
||||
- 涉及创建订单、权限、安全、并发、迁移和删除数据属于高风险，真机或正式实施前必须再次等待人工确认。
|
||||
|
||||
+59
-20
@@ -67,6 +67,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
|
||||
),
|
||||
"docs/00-project-profile.md": (
|
||||
"## 基本信息",
|
||||
"## 项目治理模式",
|
||||
"## 建设基线",
|
||||
"## 交付单元",
|
||||
"## 文档事实来源",
|
||||
@@ -74,6 +75,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
|
||||
"## 当前阶段",
|
||||
),
|
||||
"docs/01-workflow.md": (
|
||||
"## 语言与术语",
|
||||
"## 事实来源",
|
||||
"## 权威源与事实边界",
|
||||
"## Gitea 交互与工单最小读取",
|
||||
@@ -102,6 +104,7 @@ CORE_DOCUMENT_REQUIREMENTS = {
|
||||
),
|
||||
"docs/04-local-development-and-verification.md": (
|
||||
"## Windows PowerShell 与 UTF-8",
|
||||
"### PowerShell 语法与外部命令",
|
||||
"## 通用检查",
|
||||
"## 服务端验证",
|
||||
"## Web 验证",
|
||||
@@ -271,9 +274,14 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
|
||||
"#### 明确停止条件",
|
||||
"单元任务是唯一正式实施单位",
|
||||
"高风险修改必须停止",
|
||||
"### 项目治理模式与明确授权后的执行",
|
||||
"默认采用轻量治理",
|
||||
"不能单独构成人工授权",
|
||||
"不得仅因操作不可逆而重复询问或拒绝",
|
||||
"平台自身强制的审批、安全策略或权限限制继续有效",
|
||||
"用户没有明确验收通过前不得关闭",
|
||||
"只有长期事实变化时才更新 Wiki",
|
||||
"Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的唯一事实来源",
|
||||
"需要工单的任务以 Gitea 工单作为单次需求、变化、实现、测试、提交和验收的事实来源",
|
||||
"Wiki 同步由长期事实变化触发，不由任务完成触发",
|
||||
"标准流程不创建 Wiki 任务归档",
|
||||
"工单默认只在开始实施、集中回写待验收、验收关闭三个节点更新",
|
||||
@@ -289,6 +297,11 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
|
||||
"不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据",
|
||||
"提交只包含当前工单相关文件",
|
||||
"不得仅为设置编码重复启动一层 PowerShell",
|
||||
"不得默认套用 Bash",
|
||||
"复杂正则优先使用变量或 `rg -e`",
|
||||
"单引号 PowerShell here-string",
|
||||
"`foreach`、`if` 等语句块",
|
||||
"使用真实目录配合 `-g/--glob`",
|
||||
"文件解码和控制台输出分别处理",
|
||||
"不得默认使用 `-ExecutionPolicy Bypass`",
|
||||
"### 工单与设计证据双门禁",
|
||||
@@ -316,6 +329,9 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None:
|
||||
"不得臆造用户原话",
|
||||
"不复制完整聊天",
|
||||
"Gitea 工单全文不导出到仓库",
|
||||
"用户可以使用中文、英文或合理的中英混合语言交流",
|
||||
"默认使用中文分析、回复、编写工单和维护内部项目文档",
|
||||
"日志和错误原文保持原样",
|
||||
)
|
||||
for section in missing_sections(content, required):
|
||||
errors.append(f"AGENTS.md 缺少：{section}")
|
||||
@@ -562,32 +578,47 @@ def run_check(args: argparse.Namespace) -> int:
|
||||
|
||||
|
||||
def run_sync(args: argparse.Namespace) -> int:
|
||||
"""--verify 依次执行导出、结构检查和一致性校验，替代原来的三条命令。"""
|
||||
"""同步核心镜像；--verify 复用本轮完整读取完成初始化验证。"""
|
||||
|
||||
if args.verify:
|
||||
steps = (
|
||||
("同步", lambda: run_sync(
|
||||
argparse.Namespace(check=False, verify=False, config=args.config))),
|
||||
("结构检查", lambda: run_check(argparse.Namespace(strict=True))),
|
||||
("一致性校验", lambda: run_sync(
|
||||
argparse.Namespace(check=True, verify=False, config=args.config))),
|
||||
)
|
||||
for name, step in steps:
|
||||
code = step()
|
||||
if code != 0:
|
||||
print(f"错误：{name}未通过，已停止")
|
||||
return code
|
||||
try:
|
||||
config = load_config(Path(args.config).resolve())
|
||||
messages = sync_all(
|
||||
config, WikiClient(config), check=False, deep_check=True
|
||||
)
|
||||
except WikiDocsError as exc:
|
||||
print(f"错误：{exc}")
|
||||
return 1
|
||||
for message in messages:
|
||||
print(message)
|
||||
code = run_check(argparse.Namespace(strict=True))
|
||||
if code != 0:
|
||||
print("错误：结构检查未通过，已停止")
|
||||
return code
|
||||
print("Wiki 镜像初始化验证通过")
|
||||
return 0
|
||||
|
||||
try:
|
||||
config = load_config(Path(args.config).resolve())
|
||||
messages = sync_all(config, WikiClient(config), check=args.check)
|
||||
deep_check = getattr(args, "deep_check", False)
|
||||
messages = sync_all(
|
||||
config,
|
||||
WikiClient(config),
|
||||
check=args.check or deep_check,
|
||||
deep_check=deep_check,
|
||||
)
|
||||
except WikiDocsError as exc:
|
||||
print(f"错误：{exc}")
|
||||
return 1
|
||||
for message in messages:
|
||||
print(message)
|
||||
print("Wiki 镜像检查通过" if args.check else "Wiki 镜像同步完成")
|
||||
print(
|
||||
"Wiki 镜像深度检查通过"
|
||||
if deep_check
|
||||
else "Wiki 镜像检查通过"
|
||||
if args.check
|
||||
else "Wiki 镜像同步完成"
|
||||
)
|
||||
return 0
|
||||
|
||||
|
||||
@@ -652,13 +683,21 @@ def main() -> int:
|
||||
p_check.set_defaults(func=run_check)
|
||||
|
||||
p_sync = sub.add_parser("sync", help="从 Gitea Wiki 单向同步核心 docs 镜像")
|
||||
p_sync.add_argument(
|
||||
"--check", action="store_true", help="只检查 Wiki 与镜像是否一致，不写文件"
|
||||
sync_mode = p_sync.add_mutually_exclusive_group()
|
||||
sync_mode.add_argument(
|
||||
"--check",
|
||||
action="store_true",
|
||||
help="按 revision 快速检查 Wiki 与镜像，不写文件",
|
||||
)
|
||||
p_sync.add_argument(
|
||||
sync_mode.add_argument(
|
||||
"--deep-check",
|
||||
action="store_true",
|
||||
help="下载全部 Wiki 正文并逐页检查镜像，不写文件",
|
||||
)
|
||||
sync_mode.add_argument(
|
||||
"--verify",
|
||||
action="store_true",
|
||||
help="依次执行导出、check --strict 和一致性校验",
|
||||
help="完整读取并导出 Wiki，再执行 check --strict 初始化验证",
|
||||
)
|
||||
p_sync.add_argument(
|
||||
"--config", default=str(DEFAULT_CONFIG), help="Wiki 页面映射 JSON 文件"
|
||||
|
||||
+137
-14
@@ -8,6 +8,7 @@ import os
|
||||
import re
|
||||
import subprocess
|
||||
import tempfile
|
||||
import time
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path, PurePosixPath
|
||||
@@ -26,6 +27,7 @@ HEADER_PATTERN = re.compile(
|
||||
rf"{re.escape(MIRROR_END)}\n\n(?P<body>.*)\Z",
|
||||
re.DOTALL,
|
||||
)
|
||||
RATE_LIMIT_RETRY_DELAYS = (1.0, 2.0, 4.0)
|
||||
|
||||
|
||||
class WikiDocsError(RuntimeError):
|
||||
@@ -142,11 +144,33 @@ class WikiClient:
|
||||
data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
|
||||
headers["Content-Type"] = "application/json"
|
||||
request = Request(url, data=data, headers=headers, method=method)
|
||||
try:
|
||||
with urlopen(request, timeout=30) as response:
|
||||
body = response.read()
|
||||
except HTTPError as exc:
|
||||
if self.token and method == "GET" and exc.code in {401, 403, 404}:
|
||||
request_error: HTTPError | URLError | None = None
|
||||
body = b""
|
||||
for attempt in range(len(RATE_LIMIT_RETRY_DELAYS) + 1):
|
||||
try:
|
||||
with urlopen(request, timeout=30) as response:
|
||||
body = response.read()
|
||||
request_error = None
|
||||
break
|
||||
except HTTPError as exc:
|
||||
if (
|
||||
method == "GET"
|
||||
and exc.code == 429
|
||||
and attempt < len(RATE_LIMIT_RETRY_DELAYS)
|
||||
):
|
||||
exc.close()
|
||||
time.sleep(RATE_LIMIT_RETRY_DELAYS[attempt])
|
||||
continue
|
||||
request_error = exc
|
||||
break
|
||||
except URLError as exc:
|
||||
request_error = exc
|
||||
break
|
||||
else: # pragma: no cover - for 循环必定通过成功或异常分支退出
|
||||
raise WikiDocsError(f"Gitea API {method} {api_path} 请求失败")
|
||||
|
||||
if isinstance(request_error, HTTPError):
|
||||
if self.token and method == "GET" and request_error.code in {401, 403, 404}:
|
||||
# 公共仓库可能可匿名读取，而当前 shell 中的通用令牌属于
|
||||
# 另一个实例或已失效。只对只读请求安全降级为匿名访问。
|
||||
anonymous_headers = {"Accept": "application/json"}
|
||||
@@ -167,12 +191,13 @@ class WikiClient:
|
||||
f"无法连接 Gitea：{anonymous_exc.reason}"
|
||||
) from anonymous_exc
|
||||
else:
|
||||
detail = exc.read().decode("utf-8", errors="replace")
|
||||
detail = request_error.read().decode("utf-8", errors="replace")
|
||||
raise WikiDocsError(
|
||||
f"Gitea API {method} {api_path} 返回 {exc.code}: {detail}"
|
||||
) from exc
|
||||
except URLError as exc:
|
||||
raise WikiDocsError(f"无法连接 Gitea：{exc.reason}") from exc
|
||||
f"Gitea API {method} {api_path} 返回 "
|
||||
f"{request_error.code}: {detail}"
|
||||
) from request_error
|
||||
elif isinstance(request_error, URLError):
|
||||
raise WikiDocsError(f"无法连接 Gitea：{request_error.reason}") from request_error
|
||||
if not body:
|
||||
return None
|
||||
try:
|
||||
@@ -381,8 +406,73 @@ def check_mirror(mapping: Mapping, page: WikiPage, path: Path) -> list[str]:
|
||||
return errors
|
||||
|
||||
|
||||
def sync_all(config: Config, client: WikiClient, *, check: bool = False) -> list[str]:
|
||||
"""检查或写入所有显式映射；绝不处理映射外的文件。"""
|
||||
def _metadata_revision(metadata: dict[str, Any]) -> str | None:
|
||||
last_commit = metadata.get("last_commit")
|
||||
revision = last_commit.get("sha") if isinstance(last_commit, dict) else None
|
||||
return revision if isinstance(revision, str) and revision else None
|
||||
|
||||
|
||||
def _find_page_metadata(
|
||||
pages: list[dict[str, Any]], page_name: str
|
||||
) -> dict[str, Any]:
|
||||
metadata = next(
|
||||
(
|
||||
item
|
||||
for item in pages
|
||||
if item.get("title") == page_name or item.get("sub_url") == page_name
|
||||
),
|
||||
None,
|
||||
)
|
||||
if metadata is None:
|
||||
raise WikiDocsError(
|
||||
f"Wiki 页面不存在：{page_name}；不会自动删除或重命名本地镜像"
|
||||
)
|
||||
return metadata
|
||||
|
||||
|
||||
def _metadata_identity(
|
||||
config: Config, metadata: dict[str, Any], fallback_title: str
|
||||
) -> tuple[str, str] | None:
|
||||
title = metadata.get("title")
|
||||
sub_url = metadata.get("sub_url")
|
||||
if not isinstance(title, str) or not title:
|
||||
title = fallback_title
|
||||
if not isinstance(sub_url, str) or not sub_url:
|
||||
return None
|
||||
url = (
|
||||
f"{config.gitea_url}/{quote(config.owner, safe='')}/"
|
||||
f"{quote(config.repository, safe='')}/wiki/{quote(sub_url, safe='%')}"
|
||||
)
|
||||
return title, url
|
||||
|
||||
|
||||
def _local_revision(
|
||||
path: Path, *, expected_title: str, expected_url: str
|
||||
) -> str | None:
|
||||
if not path.is_file():
|
||||
return None
|
||||
try:
|
||||
metadata, _body = parse_mirror(path.read_text(encoding="utf-8"))
|
||||
except (OSError, UnicodeDecodeError, WikiDocsError):
|
||||
return None
|
||||
if (
|
||||
metadata.get("wiki_page") != expected_title
|
||||
or metadata.get("wiki_url") != expected_url
|
||||
or not metadata.get("synchronized_at")
|
||||
):
|
||||
return None
|
||||
revision = metadata.get("wiki_revision")
|
||||
return revision if revision else None
|
||||
|
||||
|
||||
def sync_all(
|
||||
config: Config,
|
||||
client: WikiClient,
|
||||
*,
|
||||
check: bool = False,
|
||||
deep_check: bool = False,
|
||||
) -> list[str]:
|
||||
"""检查或写入所有显式映射；写入前先完成全部远端读取。"""
|
||||
|
||||
if not check:
|
||||
dirty = dirty_mirror_paths(config)
|
||||
@@ -392,10 +482,43 @@ def sync_all(config: Config, client: WikiClient, *, check: bool = False) -> list
|
||||
"已映射的本地镜像存在未提交改动，已停止以防覆盖：\n" + details
|
||||
)
|
||||
|
||||
messages: list[str] = []
|
||||
pages = client.list_pages()
|
||||
resolved: list[tuple[Mapping, Path, WikiPage | None, str | None]] = []
|
||||
for mapping in config.mappings:
|
||||
page = client.get_page(mapping.page)
|
||||
metadata = _find_page_metadata(pages, mapping.page)
|
||||
target = ROOT / PurePosixPath(mapping.path)
|
||||
remote_revision = _metadata_revision(metadata)
|
||||
identity = _metadata_identity(config, metadata, mapping.page)
|
||||
local_revision = (
|
||||
_local_revision(
|
||||
target, expected_title=identity[0], expected_url=identity[1]
|
||||
)
|
||||
if identity is not None
|
||||
else None
|
||||
)
|
||||
if not deep_check and remote_revision and local_revision == remote_revision:
|
||||
action = "一致" if check else "无变化"
|
||||
resolved.append(
|
||||
(
|
||||
mapping,
|
||||
target,
|
||||
None,
|
||||
f"{action}：{mapping.path} <- "
|
||||
f"{mapping.page}@{remote_revision[:12]}",
|
||||
)
|
||||
)
|
||||
continue
|
||||
|
||||
page = client.get_page_from_metadata(metadata, mapping.page)
|
||||
resolved.append((mapping, target, page, None))
|
||||
|
||||
messages: list[str] = []
|
||||
for mapping, target, page, skip_message in resolved:
|
||||
if skip_message is not None:
|
||||
messages.append(skip_message)
|
||||
continue
|
||||
if page is None: # pragma: no cover - resolved 元组由上面的单一路径构造
|
||||
raise WikiDocsError(f"Wiki 页面未解析：{mapping.page}")
|
||||
if check:
|
||||
errors = check_mirror(mapping, page, target)
|
||||
if errors:
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Project-Profile
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Project-Profile.-
|
||||
wiki_revision: 6207da4ffac6b5821eda7869b9ea335b7585826d
|
||||
synchronized_at: 2026-08-31T16:06:21Z
|
||||
wiki_revision: 7468b9fbdd4d0bbbb9a73580c22ec868b3085753
|
||||
synchronized_at: 2026-09-05T04:06:47Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 项目档案
|
||||
@@ -21,16 +21,20 @@ synchronized_at: 2026-08-31T16:06:21Z
|
||||
| 后续设计范围 | 从 SYB 创建采购任务、创建待付款订单、物流采集与自动回填 |
|
||||
| 预计规模 | 20 台 Android；每天约 100 个采集任务、200 个采购任务 |
|
||||
|
||||
## 项目治理模式
|
||||
|
||||
GoAuto 默认采用轻量治理：文案、注释、格式、局部样式或布局、预期行为明确的小 Bug，以及不改变接口、数据结构、权限和安全边界的单模块低风险调整可以直接实施，无需为了留痕补建工单。完整独立需求、新页面、跨模块功能，以及涉及 API、数据结构、权限、安全、迁移或范围不明确的变化必须建立单元工单。采购、创建订单、真实个人或生产数据、权限、安全、并发、迁移、删除、发布和不可逆操作始终升级为高风险，必须具备对象和范围明确的人工授权；已有有效授权时不机械重复确认，范围或环境发生实质变化时重新确认。永久禁止付款以及设备、隐私、AI 和真机安全红线不可裁剪。
|
||||
|
||||
## 建设基线
|
||||
|
||||
| 基线 | 来源与版本 | 许可证 / 使用方式 | GoAuto 适配 |
|
||||
|---|---|---|---|
|
||||
| DevHarness | `D:\OPC\dev_harness`，目标提交 `4bbacf4d7fb265984396bb5589c544105043fa0b` | 开发流程与文档模板 | 2026-08-27 升级（#114）：在 #76 已采用的单人工单事实源基础上，增量加入部署模板、Gitea MCP 与最小工单读取、线上原型默认审核与按需 HTML 导出、PowerShell UTF-8/ExecutionPolicy 边界；继续保留 GoAuto 专用安全与设计门禁 |
|
||||
| DevHarness | `D:\OPC\dev_harness`，目标提交 `ecab899` | 开发流程与文档模板 | 2026-09-05 升级（#221）：在既有单人工单事实源基础上，选择性加入轻量治理、明确授权边界、中文默认沟通、Windows PowerShell 安全规则，以及按 revision 增量同步与显式深度检查；继续保留 GoAuto 专用高风险与安全门禁 |
|
||||
| 服务端 | `go-admin` v2.3.0 | 上游开源管理端基线；升级时复核许可证和安全公告 | 保留认证、菜单、配置和管理端基础能力，新增 GoAuto 业务模块 |
|
||||
| 管理端 | `go-admin-ui` v3.0.0，`web/package.json` 标注 MIT | Vue 管理界面基线 | 保留应用外壳与通用组件，新增 GoAuto 页面 |
|
||||
| Android | 原生 Kotlin Agent | 自研业务客户端 | 通过管理员明确配置的 HTTP 或 HTTPS Origin 直连服务端，不保留 Windows 桌面 Client/ADB 作为生产拓扑 |
|
||||
|
||||
升级必须比较当前记录的目标提交与新的明确提交，不能笼统复制“最新版”。本次上一基线为 `bfdf648962d11a8024f62768380d8571e1f45f68`，目标为 `4bbacf4d7fb265984396bb5589c544105043fa0b`，区间共 13 个提交；更早基线 `b1f500128d6eb100985792d4a715db8b6b5ae203` 的适配见 #47。模板内容一律按 GoAuto 事实改写：不复制 DevHarness 的项目事实、任务记录、占位部署参数或历史归档；`harness.py` 继续校验 GoAuto 实际核心页面与产品 README，GoAuto 更严格的付款、订单、设备、数据和真机门禁继续优先。
|
||||
升级必须比较当前记录的目标提交与新的明确提交，不能笼统复制“最新版”。本次上一基线为 `4bbacf4d7fb265984396bb5589c544105043fa0b`，目标为 `ecab899`，选择性适配其后的 7 个提交；更早基线适配见 #47 与 #114。模板内容一律按 GoAuto 事实改写：不复制 DevHarness 的项目事实、任务记录、占位部署参数或历史归档；`harness.py` 继续校验 GoAuto 实际核心页面与产品 README，GoAuto 更严格的付款、订单、设备、数据和真机门禁继续优先。
|
||||
|
||||
## 交付单元
|
||||
|
||||
|
||||
+22
-3
@@ -2,12 +2,18 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Development-Workflow
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Development-Workflow.-
|
||||
wiki_revision: 3167457d79824afe532dd5560990af8a485a57d1
|
||||
synchronized_at: 2026-08-27T09:37:51Z
|
||||
wiki_revision: 62ddbe4469740c02ce4a6ca2fd1966a89a79322f
|
||||
synchronized_at: 2026-09-05T04:06:53Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 开发工作流
|
||||
|
||||
## 语言与术语
|
||||
|
||||
- 用户可以使用中文、英文或合理的中英混合语言交流；默认使用中文分析、回复、编写工单和维护内部项目文档。
|
||||
- 代码标识符、命令、参数、路径、文件名、API 名称、协议名、日志和错误原文保持原样；必要时补充简短中文解释。
|
||||
- 用户明确要求某次回复或交付物使用其他语言时，按该次要求执行，不改写接口契约或影响搜索和执行的原文。
|
||||
|
||||
## 事实来源
|
||||
|
||||
| 信息 | 唯一事实来源 |
|
||||
@@ -18,7 +24,7 @@ synchronized_at: 2026-08-27T09:37:51Z
|
||||
| 源码、迁移、测试、版本绑定分析、本地原型和核心 Wiki 镜像 | Git |
|
||||
| 可编辑交互设计 | QuantUX；App ID、版本、链接和确认状态记录在工单 |
|
||||
|
||||
核心页面通过 `wiki-docs.json` 显式映射，固定执行 Wiki → `docs/` 单向同步。既有 Wiki 任务归档和 `docs/task/` 只作历史兼容；标准任务不创建或导出，只有用户明确要求专项快照时才使用 `archive` / `export`。
|
||||
核心页面通过 `wiki-docs.json` 显式映射，固定执行 Wiki → `docs/` 单向同步。日常 `sync` 与 `sync --check` 先比较页面 revision，revision 未变化时不重复下载正文；疑似镜像损坏或需要完整核对时显式使用 `sync --deep-check`。既有 Wiki 任务归档和 `docs/task/` 只作历史兼容；标准任务不创建或导出，只有用户明确要求专项快照时才使用 `archive` / `export`。
|
||||
|
||||
## 权威源与事实边界
|
||||
|
||||
@@ -53,6 +59,19 @@ synchronized_at: 2026-08-27T09:37:51Z
|
||||
- 每个核心页面写入后必须在线回读并取得 revision。页面缺失、回读失败或没有 revision 时停止初始化。
|
||||
- 产品编码前运行 `python dev_scripts/harness.py sync --verify`；全部成功才表示初始化完成。
|
||||
|
||||
## 项目治理模式与不可裁剪底线
|
||||
|
||||
GoAuto 默认采用轻量治理。文案、注释、格式、局部样式或布局、预期行为明确的小 Bug，以及不改变接口、数据结构、权限和安全边界的单模块低风险调整可以直接实施，无需为了留痕补建工单。完整独立需求、新页面、跨模块功能，以及 API、数据结构、权限、安全、迁移或范围不明确的变化必须建单。
|
||||
|
||||
采购、创建订单、真实个人或生产数据、权限、安全、并发、数据库迁移、删除数据、发布和其他不可逆操作始终升级为高风险。无论任务采用何种最小门禁，凭据保护、永久禁止付款、个人与生产数据最小化、设备互斥、Agent 禁止 OCR/VLM、控件树与整屏截图禁存、工作区保护、真实测试和人工验收均不可裁剪。
|
||||
|
||||
### 明确授权后的执行
|
||||
|
||||
- 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据，不要求把同一授权重复复制到工单后再次确认。
|
||||
- 授权必须能识别操作、对象和范围；Agent 自动生成的工单、草稿、摘要或对用户意图的转述不能单独构成人工授权。
|
||||
- 获得有效授权后，只核对准确目标、授权范围和当前状态等最小必要前提，不得仅因操作不可逆而重复询问或拒绝。
|
||||
- 授权不自动覆盖相邻对象或后续任务；环境、对象、范围或影响发生实质变化时重新确认。平台自身强制的审批、安全策略或权限限制继续有效。
|
||||
|
||||
## 工单与设计证据双门禁
|
||||
|
||||
正式实施前先判断是否需要工单，再判断需要什么设计证据。工单不能替代原型确认，原型也不能替代技术方案、安全检查和单元工单。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Architecture-and-Code-Map
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Architecture-and-Code-Map.-
|
||||
wiki_revision: a8ea0f6ae4c4a05b10ba047516fda23cfb188d13
|
||||
synchronized_at: 2026-09-02T15:05:31Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 架构与代码地图
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Business-Rules-and-Glossary
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary.-
|
||||
wiki_revision: a60c48f56ec7cad6f886df78a644fbabb92d288f
|
||||
synchronized_at: 2026-09-02T13:23:12Z
|
||||
wiki_revision: f8a2e64acaf245066d55d4a0f1e928d672712270
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 业务规则与术语
|
||||
@@ -31,7 +31,7 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
- 关联 PDD 商品时校验目标存在且非 `disabled`；不提供手工输入商品 ID 的入口，只能通过搜索选择。
|
||||
- 参考售价 `sale_price_cent` 为整数分，`currency` 为 ISO 4217 代码；币种取系统配置默认值，不逐商品选择，缺省回退为 `TWD`。
|
||||
- 规格值来源分 `import`（SYB 导入，不可人工删除，只能清除映射）与 `manual`（人工添加，可删除）；导入与人工值按「维度 + 名称」合并，不重复创建。
|
||||
- 映射来源分 `manual`（人工，允许创建时即为已确认）、`exact_match`（名称标准化后唯一一致）、`ai_match`（AI 建议）。通用 `SetMapping` 入口仍将 `exact_match` 与 `ai_match` 一律写为 `pending`，必须人工确认后才生效；#188 的 SYB 商品页批量 AI 匹配与 #194 的 Admin 蝦皮商品详情一键匹配是两个独立例外。#188 的进入条件已由 #190 放开：只要蝦皮与 PDD 关联完整、PDD 当前为 `active` 且能给出可选颜色/尺码候选、并且已解析出至少一个目标颜色或尺码，即可进入批量匹配。解析状态（含 `parse_status=uncertain` 与 `failed`）、PDD 含颜色尺码之外的可选规格、蝦皮档案中未找到目标颜色或尺码、缺少完整可售 SKU 组合证据，自 #190 起都不再阻断匹配；本项目为内部系统，由此产生的“以错误目标规格进行匹配并保存映射”的风险由人工承担。唯一确定性 `exact_match` 不调用外部 AI，可直接保存为 `confirmed`；其余结果只有在 `ai_match` 置信度存在且达到服务端阈值、理由非空、返回值属于当前可选候选并命中同一个可售颜色+尺码组合时，才可直接持久化为 `confirmed`。低置信度、无组合证据、无效组合或 Provider 异常不得改写现有映射。
|
||||
- 映射来源分 `manual`（人工，允许创建时即为已确认）、`exact_match`（名称标准化后唯一一致）、`ai_match`（AI 建议）。通用 `SetMapping` 入口仍将 `exact_match` 与 `ai_match` 一律写为 `pending`，必须人工确认后才生效；#188 的 SYB 商品页批量 AI 匹配与 #194 的 Admin 蝦皮商品详情一键匹配是两个独立例外。#188 的进入条件已由 #190 放开：只要蝦皮与 PDD 关联完整、PDD 当前为 `active` 且能给出可选颜色/尺码候选、并且已解析出至少一个目标颜色或尺码，即可进入批量匹配。解析状态（含 `parse_status=uncertain` 与 `failed`）、PDD 含颜色尺码之外的可选规格、蝦皮档案中未找到目标颜色或尺码、缺少完整可售 SKU 组合证据，自 #190 起都不再阻断匹配；本项目为内部系统，由此产生的“以错误目标规格进行匹配并保存映射”的风险由人工承担。唯一确定性 `exact_match` 不调用外部 AI，可直接保存为 `confirmed`；SYB 商品页批量 `ai_match` 只要 Provider 成功返回规格结果且理由非空、返回值属于当前可选候选即可直接持久化为 `confirmed`，置信度仅记录供审计、不作为放行门槛。若当前 PDD 档案存在完整可售颜色+尺码 SKU 组合证据，结果还必须命中其中同一个组合；人工录入或外部导入导致组合证据缺失时不阻断保存或创建采购。无结果、已有组合证据中的无效组合或 Provider 异常不得改写现有映射。
|
||||
- 颜色映射只能从关联 PDD 商品当前可选颜色中选择，不允许自由输入；未使用颜色优先显示，已被其他蝦皮颜色使用的颜色仍可选择并显示占用者，因此支持多对一。
|
||||
- Admin 蝦皮商品详情只保留一个“一键匹配颜色和尺码”入口。已确认且目标仍存在的映射保留；名称标准化后的唯一确定结果直接写为 `exact_match + confirmed`；其余只有在 AI 置信度达到服务端当前阈值、理由非空、返回值仍属于当前可选候选时才写为 `ai_match + confirmed`。低置信度或无结果保持未匹配；Provider 失败、AI 未启用、关联或规格上下文变化时本次不写入。操作前有未保存的人工修改时禁用一键匹配；保存只改映射，不改蝦皮或 PDD 原始规格。
|
||||
- PDD 重新采集或更换关联后，目标规格仍存在则映射继续有效；目标规格消失时详情标记“已失效”，服务端拒绝保存不存在的目标，采购预检和创建也拒绝使用失效映射并提示重新选择。
|
||||
@@ -41,6 +41,8 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
|
||||
- 一行对应 SYB 一条明确的商品/颜色/尺码/数量明细；唯一键为「蝦皮订单号 `code` + 来源明细 `id`」组合，不是全局唯一 ID（未在多货运单样本中验证过全局唯一性）。
|
||||
- `productSpec` 自由文本解析：按最后一个逗号切分为颜色/尺码 → 剥离【】备注 → 判断残留分隔符；解析状态分 `success`/`uncertain`/`failed`，永不猜测原文中不存在的颜色或尺码。
|
||||
|
||||
- 采购放行不以 uncertain 单独阻断：success 与已提取出至少一个非空颜色或尺码的 uncertain 明细，都可继续进入规格匹配和采购预检；只有 failed 或颜色、尺码均为空的异常明细才要求人工处理。uncertain 状态与解析说明继续保留供审计，不会自动猜测规格。
|
||||
- 只有 `success` 状态的解析结果会合并进虾皮商品档案的规格值（来源标记 `import`）；`uncertain`/`failed` 只停留在明细行上供人工复核，不污染共享档案。
|
||||
- 金额单位按接口分别定义：`/am/stock/detail/listByStock` 的 `productPrice` 是十进制金额，与 `/am/stock/list` 的 `amtOrder`（×100 整数）不是同一套换算，不可共用。
|
||||
- 关联虾皮商品档案：命中存活记录直接关联；命中软删除记录则复活并保留原有人工映射；均不存在时创建最小档案。命中既有档案时只补写为空的参考图与售价，不覆盖人工修改过的标题、店铺和映射。
|
||||
@@ -62,6 +64,7 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
## SYB 店铺过滤
|
||||
|
||||
- `syb_shop` 保存允许导入的 SYB 店铺；店铺名比较前统一去除首尾空白、转换全角/半角字符并忽略大小写。规范化后同名的店铺只能保留一条有效记录。
|
||||
- 版本迁移会对历史存活店铺回填 `normalized_name = Normalize(display_name)`；回填只改匹配键且可重复执行。若两个存活店铺回填后会得到同一键，迁移必须整体失败并保留原数据，管理员先人工消除歧义后再执行，不能静默合并、删除或改变店铺启用状态。
|
||||
- 店铺可以从 SYB 真实货运单列表发现，也允许管理员手工补充。只有管理员可以新增、改名、启停和软删除，采购员等其他角色只读。
|
||||
- 没有任何启用店铺时，导入必须在读取凭据、建立会话、验证码 OCR 和任意 SYB 网络请求之前失败，并给出“请先启用店铺”的可读提示。
|
||||
- 同步必须先拉取并校验当天原始全量列表的总数、分页和唯一 ID，再按本次同步开始时固定的启用店铺快照过滤；过滤不能降低完整性校验的请求范围或容量上限。
|
||||
@@ -73,7 +76,7 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
- 导入由管理员创建，创建成功后立即转入后台执行；页面关闭不取消任务。采购员等其他已登录角色可以查看同步记录，不能开始导入。
|
||||
- 系统同一时刻只运行一个 SYB 导入任务。`syb_sync_run` 的唯一执行槽负责跨进程互斥，内存锁减少同一进程内的竞争；服务重启后遗留的执行中记录标记为“已中断”。
|
||||
- 导入失败或中断时保留已写入商品，记录明确的失败原因和已处理进度；重新导入相同范围按「订单号 + 明细 ID」覆盖，不产生重复商品。
|
||||
- 每条同步记录保存本次启用店铺集合的 SHA-256 哈希以及各店铺“已导入/已跳过”数量，不保存账号、密码、Cookie、验证码图片或 SYB 原始响应。
|
||||
- 创建同步记录时冻结本次启用店铺的规范化匹配集合、展示名称快照及 SHA-256 哈希；后台执行必须只使用这一份快照，不得在开始后重新读取 `syb_shop`。同步详情保存并返回快照可用标记、快照店铺名称、哈希及各店铺“已导入/已跳过”数量。#212 之前的历史记录只有哈希和统计，明确标记为无完整快照。上述记录不保存账号、密码、Cookie、Token、验证码图片或 SYB 原始响应。
|
||||
- 后台任务创建前的内部失败仍向普通用户显示“服务端处理失败”，但使用稳定错误码区分阶段：店铺预检为 `SYNC_SHOP_PREFLIGHT_FAILED`，同步记录创建为 `SYNC_RUN_CREATE_FAILED`。服务端只记录阶段和经过脱敏、截断的底层原因，不记录请求体、凭据、Cookie、Token、验证码或原始响应。
|
||||
|
||||
## 采集规则
|
||||
@@ -84,12 +87,14 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
- 删除采用软删除；删除后不能创建新任务，但已有任务继续执行自身快照。
|
||||
- 商品详情步骤应声明精确 `activityName`，并与包名和唯一控件共同作为页面证据；进入 PDD 登录 Activity 必须返回 `PDD_LOGIN_REQUIRED`，不能提交采集成功。
|
||||
- 唯一文字节点不可点击时，Agent 只可点击其最近的可点击父容器；不得改点兄弟节点或相似文字。
|
||||
- 商品页规格入口只接受带明确选择语义的规格摘要，或底部真实“购买/拼单”文字按钮；评价、评论、晒单、问答区域及其父容器一律排除。商品评价页与详情页共用 Activity 时，首次误触只允许安全返回并重新定位一次，重复误触明确失败；点击无变化、误入评价页和面板结构无法确认使用不同错误码。
|
||||
- 商品页规格入口只接受带明确选择语义的规格摘要，或底部真实“购买/拼单”文字按钮。若“请选择”和颜色/尺码语义分散在同一可点击父容器的子节点中，也只能在该容器唯一、位于非底部动作区且同时具备两类语义时作为规格入口；规则别名只能收窄已识别的安全候选，不能按页面原始文字扩张。底部购买入口在通过全部安全过滤后仍存在多个候选时，按最右优先（`centerX` 降序，并列时可点击面积升序）确定性选出唯一入口，不再因候选不唯一直接失败；该情形记为 `bottom_purchase_rightmost`，唯一候选仍记为 `bottom_purchase`。“单独购买”与“发起拼单”打开同一规格面板，但对应不同成交形态与价格，最右优先是经人工确认的取舍。评价、评论、晒单、问答、订单、提交订单、支付和付款区域及其父容器一律排除。商品评价页与详情页共用 Activity 时，首次误触只允许安全返回并重新定位一次，重复误触明确失败；点击无变化、误入评价页和面板结构无法确认使用不同错误码。
|
||||
- v2 规则使用类型化动作和固定阶段钩子。已由 Agent 支持的选择器、别名、超时、滑动方向和有限次数可以只更新规则；新增动作类型或页面算法才需要升级 Agent。
|
||||
- v2 任务首次未进入精确商品详情页时，可以按规则显式重开同一浏览器 URL 一次；登录、验证码、风控、无效链接和详情页内采集失败不触发该恢复。
|
||||
- 假售罄恢复只使用主商品规格/购买强证据判断页面是否正常；顶部“相似商品”可以作为受控兜底证据，推荐卡片的标题、价格和销量不得冒充主商品证据。
|
||||
- 商品规格遍历必须用已识别规格节点锁定横向颜色容器和纵向面板容器；颜色按视觉行蛇形遍历，滑动完成后重新读取节点，尺码只读并允许在标题滚出后沿已锁定容器续页。
|
||||
- PDD 已选规格的订单确认形态只可由详情页、选择摘要、唯一数量控件、支付区、唯一底部提交动作和唯一主要滚动容器的组合证据确认；底部提交动作只读且永久禁止点击。Agent 只在该已确认容器内最多三次向下拖动回顶，每次重新读取节点；“参考分类”作为尺码的精确标题别名处理。
|
||||
|
||||
- PDD 完整规格选择器若无主滚动容器且尚未选择规格而没有已选摘要，仍可识别为非滚动规格面板，但必须同时出现至少两个已解析维度、至少两个可选项、唯一数量控件和唯一底部订单动作；缺少其中任一强证据时保持未识别。该订单动作仍仅作页面证据，永久禁止点击。
|
||||
- Agent 可扩展，但规则必须按任务类型授权：采集规则不能创建订单，采购规则只能使用独立审核的创建订单能力。当前项目不实现支付动作、入口或测试；支付、下单和订单相关文字可以作为只读页面证据配置，但不得成为点击目标。后续支付能力必须单独评估并至少具备显式能力位、服务端开关、单笔金额上限和人工授权。
|
||||
|
||||
## 采集任务
|
||||
@@ -135,27 +140,27 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
- 演练规则在服务端契约层拒绝改地址、创建订单和核单动作；正式动作还必须通过版本化能力协商。规则只包含类型化动作，禁止任意脚本。
|
||||
- 价格保护保存参考单价、最低单价、最高单价和币种，执行时以 PDD App 实际单价判断；价格越界明确失败，不考虑优惠券。
|
||||
- Admin 从 SYB 当前页选择商品，可在“创建采购”和“重新解析”两种批量用途间切换；采购模式只允许选择预检合格行，表头全选不跨页。批量预检和正式创建均最多 100 条并逐条重新校验，每条 SYB 明细只创建一个独立任务；部分失败不回滚其他成功项。
|
||||
- SYB 商品列表在列表数据返回后立即展示，采购准备状态独立异步加载；只读批量预检只执行批量数据库读取、已确认映射和本地确定性识别，禁止调用 AI Provider。未保存的确定性结果仍显示“规格待匹配”，不能作为“可创建采购”的依据。SYB 批量创建采购按最新数据完整复核，只有目标颜色和尺码都已保存为确认映射，且共同命中最近一次成功或部分成功采集中的完整可售 SKU 组合时才允许创建；否则必须先执行批量 AI 匹配或人工确认，不能把未匹配明细带入采购任务内的人工匹配步骤。
|
||||
- SYB 商品列表在列表数据返回后立即展示，采购准备状态独立异步加载；只读批量预检只执行批量数据库读取和本地确定性识别，禁止调用 AI Provider。自 #215 起，未保存或已失效的长期规格映射不再阻断创建采购；满足商品关联、PDD 状态、价格、规则、设备和订单安全门禁后即可创建任务，每个新 SYB 采购任务都在首个 attempt 以当次 PDD 页面候选重新决策。
|
||||
- SYB 商品页的 PDD 采集资格独立于采购处理阶段：只要已关联的 PDD 商品未停用、没有 `pending` / `running` 采集任务且存在可用采集规则，即可创建采集任务；因此已完成采集并进入“可创建采购”的商品也可以重新采集。相同 PDD 商品在批量创建前按商品去重，服务端创建时仍按最新状态复核。
|
||||
- 批量创建读取管理员选定的当前采购规则并重新执行契约校验，每条任务保存不可变快照；当前规则缺失或无效时明确阻断，不回退到代码常量。设备默认人工指定，也可以留空由符合能力的空闲设备领取。
|
||||
- 批量创建的价格保护来自 PDD 商品档案而不是 SYB/Shopee 的 TWD 售价：当前采购规则可用 `priceGuard.minRatio`（0.1～1.0）和 `maxRatio`（1.0～3.0）配置比例，缺省仍为 0.2 / 1.5；最低价向下取整、最高价向上取整到人民币分。已确认颜色映射时按该颜色计算，待规格探测时以全部可用颜色的最低/最高价计算，参考价取最高价；没有可用颜色价格时不能创建。
|
||||
- 地址后缀为 `_cg{purchase_task.id}`。选好规格和数量后，Agent 仍停留在当前规格/下单面板；若收货地址被面板裁切，只允许在唯一、可见且占据主要宽度的纵向滚动容器内有限向下拉动来显示地址，禁止按页面最大滚动区域盲目滑动。Agent 只在唯一地址入口、唯一修改按钮和唯一详细地址输入框均成立时修改；脱敏手机号文字本身不可点击时，仍以该唯一文字节点的中心坐标执行一次精确手势点击，不沿用可能覆盖整个下单面板的可点击祖先。“修改”“保存”和“提交订单”等文字节点即使依赖可点击父节点，也必须保留原始文字节点作为每次重新定位的锚点，父节点只用于验证存在可点击路径。近乎完全重叠的无障碍重复节点按一个目标处理，仍有多个独立目标或页面切换超时则明确失败。按首个 `-` 或 `_` 截取地址主体后追加当前后缀，保存后必须回读完整新地址。修改或回读失败时禁止创建订单，地址全文和控件树不落库。
|
||||
- 地址后缀为 `_cg{purchase_task.id}`。精确规格、数量、价格和摘要核验通过后，若仍处于已识别的规格面板，Agent 只允许点击唯一、可见、启用、可点击且文案精确命中“确定/确认”别名的规格确认控件；不得点击提交订单、确认购买、付款、支付、地址修改或地址保存控件，也不使用中心手势兜底。点击后必须重新读取并确认已出现订单确认页或地址入口强证据，否则明确失败。进入订单确认页后，若收货地址被面板裁切，只允许在唯一、可见且占据主要宽度的纵向滚动容器内有限向下拉动来显示地址，禁止按页面最大滚动区域盲目滑动。Agent 只在唯一地址入口、唯一修改按钮和唯一详细地址输入框均成立时修改；脱敏手机号文字本身不可点击时，仍以该唯一文字节点的中心坐标执行一次精确手势点击，不沿用可能覆盖整个下单面板的可点击祖先。“修改”“保存”和“提交订单”等文字节点即使依赖可点击父节点，也必须保留原始文字节点作为每次重新定位的锚点，父节点只用于验证存在可点击路径。近乎完全重叠的无障碍重复节点按一个目标处理，仍有多个独立目标或页面切换超时则明确失败。按首个 `-` 或 `_` 截取地址主体后追加当前后缀，保存后必须回读完整新地址。修改或回读失败时禁止创建订单，地址全文和控件树不落库。
|
||||
- 地址编辑页可以同时存在收货人、手机号和详细地址等多个输入框；Agent 只选择与“详细地址”标签纵向重叠且位于其右侧的唯一输入框，不能用页面输入框总数或顺序猜测。
|
||||
- 点击创建订单前，Agent 必须先在本地事务保存 `order_submit_started`、不可逆时间、稳定请求 ID 和不含地址全文的最终确认快照，再用同一请求 ID通知服务端；两侧成功后才允许精确点击唯一创建订单按钮一次。
|
||||
- 进入不可逆边界后，进程重启、断网、点击结果不明或无法取得唯一订单号/下单时间时只允许只读核单并进入 `order_result_unknown`，禁止再次点击；任务与订单正式关联仍以完整 PDD 订单号为准。
|
||||
- 创建订单后出现 Android 多微信应用选择器时，Agent 只有在系统包和 `ChooserActivity` / `ResolverActivity` 白名单、已知选择器标题、微信候选三类证据同时成立时，才允许按一次返回，绝不点击微信候选。若已进入真实微信包 `com.tencent.mm`，Agent 不点击、不输入、不登录、不支付、不强制停止微信，只允许用一次无参数 PDD 启动 Intent 把既有 PDD 任务栈拉回前台；第二次仍见微信或拉起失败即保持结果未知。回到 PDD 已知支付 Activity 或明确支付动作页面后最多再返回一次，再只读读取唯一订单号和下单时间；任一页面不在白名单、恢复动作重复、无法到达订单详情或结果不唯一时保持 `order_result_unknown`，禁止重下单或支付。
|
||||
- 创建订单后出现 Android 多微信应用选择器时，Agent 只有在系统包和 `ChooserActivity` / `ResolverActivity` 白名单、已知选择器标题、微信候选三类证据同时成立时，才允许按一次返回，绝不点击微信候选。若已进入真实微信包 `com.tencent.mm`，Agent 不点击、不输入、不登录、不支付、不强制停止微信，只允许用一次无参数 PDD 启动 Intent 把既有 PDD 任务栈拉回前台；第二次仍见微信或拉起失败即保持结果未知。回到 PDD 已知支付 Activity 或明确支付动作页面后最多再返回一次，再只读读取唯一订单号和下单时间；下单成功页仅可点击唯一、精确的“查看订单”或“订单详情”入口一次，进入 PDD 订单详情后才允许有限向上手势下翻读取折叠内容。PDD 页面出现“待付款”“待支付”“订单编号”或“下单时间”等订单结果信号时，该只读信号优先于复用的支付 Activity 名称：允许在唯一主要纵向容器内有限下翻并重新读取，仍不得点击支付；没有任何订单结果信号的支付页或未知页面不得盲目滑动。入口缺失或不唯一、点击后未出现详情证据、任一页面不在白名单、恢复动作重复或结果不唯一时保持 `order_result_unknown`，禁止重下单或支付。
|
||||
- Agent 本地 SQLite/Outbox 负责断网和重启恢复，服务端以 `task_id + task_attempt_id` 幂等接收并保存最终事实。
|
||||
- 人工支付复核只记录 `paid` / `unpaid`；系统不执行或识别支付。快递单号与回填状态属于采购任务，后续物流工单实现。
|
||||
- 采购任务领取时同时占用设备租约和可选 PDD 账号租约；租约过期后才可释放并重新领取。设备还存在采集任务时不能领取采购任务。
|
||||
- 采购规格由服务端按顺序决策：先使用已确认的人工映射；否则仅在同一规格角色的可选 PDD 原始标签中做唯一确定性匹配（繁体转简体、空格/全半角/大小写统一，以及公斤/斤换算）；仍无唯一结果才调用已启用的服务端 AI。AI 必须返回候选集中的原始标签，候选不完整、歧义、AI 无结果或服务不可用均明确失败，不派发第二趟、更不创建订单。
|
||||
- 自 #215 起，每个新 SYB 采购任务无论是否存在已确认长期映射，都先由 Agent 在当次 PDD 规格面板内有界遍历颜色和尺码并回传原始候选。服务端只以任务冻结的 SYB 目标规格与当次候选先做唯一确定性匹配（繁体转简体、空格/全半角/大小写统一，以及公斤/斤换算），仍无唯一结果才调用已启用的服务端 AI。AI 必须逐字返回当次候选集中的原始标签；候选不完整、集合外返回、歧义、AI 无结果或服务不可用均明确失败，不派发第二趟、更不创建订单。
|
||||
- Agent 选择服务端下发的精确颜色或尺码时，只能在已确认打开的规格面板内有限纵向滑动、每次重新读取可选节点并按完整原始文字点击；连续没有新证据或达到上限即停止，不得点击相近规格。第一趟探测并固化规格后，第二趟仍无法精确选择而再次提交探测时，服务端必须明确失败并释放活动槽，保留第一次决策证据，禁止清空决策、循环派发或进入地址与创建订单动作。
|
||||
- 采购 Agent 在确认进入 PDD 商品页后、打开规格前，复用采集侧的假售罄识别；规格面板已打开且当前解析到的规格值全部不可选时也按售罄处理。两种情况都只允许关闭规格面板后对商品页执行一次有界恢复（默认下拉 2 次、间隔 1000 毫秒、等待 2000 毫秒），恢复动作失败或恢复后仍售罄时返回 `PDD_GOODS_SOLD_OUT`，恢复后商品页证据丢失时按页面规则不匹配失败；不得继续选择规格、修改地址或创建订单。该失败码继续进入既有替代商品资格判定。
|
||||
- 规格映射不完整、已保存的确认映射对当前 PDD 档案失效、确定性匹配失败、PDD 档案为待采集或没有规格时，规则必须具有 `purchase.spec-probe.v1`；自 #190 起前两种情况不再拒绝创建，而是把 `spec_source` 降级为 `unresolved` 并交由规格探测解析，规则不具备该能力时仍然拒绝创建；第一趟只探测规格并释放租约，服务端固化同一 attempt 的决策后才派发第二趟。Android 不自行匹配或猜测；其只接收服务端已经固化的精确原始规格标签。
|
||||
- 所有新 SYB 采购任务的规则都必须具有 `purchase.spec-probe.v1`；创建时任务级 `mappedColor` / `mappedSize` 为空且 `spec_source=unresolved`，长期映射和 PDD 档案候选都不能跳过首趟探测。第一趟只探测规格并释放租约，服务端固化同一 attempt 的决策后才派发第二趟；探测阶段从服务端拒绝进入 `order_submit_started`。Android 不自行匹配或猜测，只在第二趟接收并精确选择服务端固化的当次 PDD 原始标签。
|
||||
- Agent 提交的相同 attempt 最终结果只能写入一次；相同请求重放返回原事实，不同内容拒绝覆盖。`order_result_unknown` 不参与自动派发，只能人工解除。
|
||||
- 已创建订单默认禁止再次采购；管理员或采购员可以做一次性重新采购授权，新任务创建成功时在同一事务消耗授权，旧任务和旧订单保留。已标记为已支付的订单不能授权或创建重新采购任务。
|
||||
- 人工回填候选只允许从已支付订单选择；同一 SYB 明细后来选择的订单覆盖旧候选，但不删除旧订单事实。
|
||||
- Admin 采购管理只查看和处理已有任务，不提供创建入口或支付按钮；单条和批量采购任务都从 SYB 商品列表发起。订单结果未知时必须先人工核对并解除；处于该状态时页面不提供重新采购授权。
|
||||
- 采购失败任务可在采购管理当前页批量勾选重试，最多 100 条。重试不修改旧任务，而是用当前 SYB/PDD 档案、当前规格映射、当前价格保护和当前采购规则创建新的 `pending` 任务，并生成新任务编号与地址后缀；来源蝦皮订单号沿用失败任务的不可变快照。
|
||||
- 采购失败任务可在采购管理当前页批量勾选重试，最多 100 条。重试不修改旧任务，而是用当前 SYB/PDD 档案、目标规格、当前价格保护和当前采购规则创建新的 `pending` 任务，并生成新任务编号与地址后缀；来源蝦皮订单号沿用失败任务的不可变快照。新任务不复用旧任务或长期档案的执行规格，仍必须先完成当次真机规格探测。
|
||||
- 只有正式采购、未进入不可逆边界、没有订单号或下单时间、且仍是同一 SYB 最新记录的 `failed` 任务可重试。原设备离线、停用、忙碌或能力不足时该项失败且不自动换机；未指定设备时仍由空闲设备领取。
|
||||
- 批量重试逐项处理并允许部分成功；同一请求幂等重放不会重复创建。失败任务不再使用一次性重新采购授权，该授权只保留给已经创建过订单且满足条件的任务。
|
||||
|
||||
@@ -251,16 +256,14 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
|
||||
## Agent 受控重试采购
|
||||
|
||||
- 当前设备只可就地重跑自身最近 30 天内、服务端标记 `retryable=true` 的正式采购失败任务；列表和详情都只能发起单任务重试，不支持多选、批量或自动重试。
|
||||
- 普通“重试采购”复用原 `purchase_task.id`，不新建任务，不改变商品、虾皮/SYB 身份、目标规格、已映射规格、价格保护、地址后缀与其他业务快照。重试只把任务恢复为 `pending`，清理错误、租约和运行守卫。
|
||||
- 重试时刷新服务端当前采购规则及其类型、schema 和能力要求。#127 尚未实施前，当前规则仍为服务端内置规则；#127 完成后才切换为数据库单例设置，不能在本工单提前引入第二事实源。
|
||||
- 新规则下发前必须重新校验原设备在线、空闲且具备全部能力。规则不可用或能力不匹配时拒绝重试，原任务保持失败状态。
|
||||
- 已出现 `order_submit_started` 证据，或存在不可逆时间、订单提交请求、PDD 订单号、下单时间的任务一律拒绝就地重试，并提示走既有“授权重新采购”流程，防止重复下单。
|
||||
- 每次成功受理就地重试都会为同一任务预建一个新的 `pending` attempt，保存本次规则哈希；正常 Start 复用并转为 `running`。因此尝试次数、每次规则哈希和失败原因均可追溯，且不限制人工重试次数。
|
||||
- `requestId` 按“任务 + 请求”幂等；相同请求重放不重复修改任务或增加 attempt。
|
||||
- Agent 详情显示已尝试次数与上次失败原因。确认界面必须说明同一任务使用最新规则重跑、可能创建待付款订单且系统不会支付。
|
||||
- “继续采购”与普通“重试采购”语义不同：替代商品匹配完成后的“继续采购”继续调用既有 `AgentRetry → BatchRetry → Create`，保留旧任务并按当前替代商品档案创建新任务；Admin 批量重试同样继续创建新任务。二者均不得改成就地更新旧任务。
|
||||
- 取消订单、修改既有订单和支付仍禁止；真机重跑可能进入创建待付款订单流程，执行前必须再次取得人工授权。
|
||||
- 当前设备只可重试自身最近 30 天内、服务端标记 `retryable=true` 的正式采购失败任务；列表和详情都只能发起单任务重试，不支持多选、批量或自动重试。
|
||||
- 普通“重试采购”调用既有 `AgentRetry → BatchRetry → Create`：原失败任务及其商品、目标规格、执行规格、价格和执行记录保持不可变；服务端根据当前 SYB、虾皮/PDD 档案、当前采购规则和当前设备创建不同 `purchase_task.id` 的新任务。
|
||||
- 新 SYB 采购任务继续遵循 #215 的强制当次规格探测，首趟不得直接使用历史任务的规格决策；当前档案、规则、价格、设备或能力门禁不通过时拒绝创建，旧任务保持失败状态。
|
||||
- 已出现 `order_submit_started` 证据，或存在不可逆时间、订单提交请求、PDD 订单号、下单时间的任务一律拒绝重试，并提示走既有“授权重新采购”流程，防止重复下单。
|
||||
- `requestId` 按“来源任务 + 请求”幂等；相同请求重放返回同一新任务，不重复创建。
|
||||
- Android 只在服务端 `retryable=true` 且状态为 `failed` 时显示普通“重试采购”。确认和成功反馈必须说明旧任务保留、新任务读取当前档案和规则、可能创建待付款订单且系统不会支付。
|
||||
- 历史兼容的就地 `/reset` 服务端入口不得把“目标规格存在但对应执行规格为空”的任务恢复到正式采购阶段；此类异常快照必须拒绝，并提示创建新任务。Android 普通重试不再调用该入口。
|
||||
- 替代商品匹配完成后的“继续采购”和 Admin 批量重试继续使用同一新任务语义；取消订单、修改既有订单和支付仍禁止。真机重试可能进入创建待付款订单流程，执行前必须再次取得人工授权。
|
||||
|
||||
## Agent 状态页手动检查任务
|
||||
|
||||
@@ -331,12 +334,16 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
- 自动确认必须保存来源、实际置信度和脱敏限长原因；人工确认完成后同步对应分项及主表总体状态。worker 不得覆盖已由人工改变的映射。
|
||||
- 纠错不能简单执行 B→C；必须把原 A→B 记录置为 `superseded`，建立 A→C，并只处理原记录冻结的虾皮商品影响集合。
|
||||
|
||||
## 创建采购任务时的异步规格匹配（#148）
|
||||
## 历史：创建采购任务时的异步规格匹配（#148，#215 后仅兼容存量）
|
||||
|
||||
- 创建任务继续同步使用已确认映射和唯一确定性 `exact_match`；只有需要外部 AI 时，任务与 `purchase_spec_match_work_item` 在同一事务创建，接口立即返回。活动工作项或 `manual_required` 未处理前，`Next`、`Claim`、`Start` 均拒绝任务。
|
||||
- AI 结果只固化到采购任务快照，不自动写回虾皮商品长期规格映射。`ai_match` 必须达到设置阈值、严格属于当前候选、原因非空且写入前输入指纹未变化；否则转人工，Agent 不猜测。
|
||||
- provider 网络、超时或 5xx 按 30 秒、2 分钟、10 分钟退避，最多尝试 3 次；预算内恢复会自动继续，耗尽后转 `manual_required`。Admin 可重新入队或从当前候选人工选择。
|
||||
- 异步 provider 单次调用最长 60 秒，即 `min(配置超时, 60 秒)`；设置页测试连接仍使用完整配置超时。取消任务会同时终结活动工作项，输入变化会关闭旧工作项并要求重新入队。
|
||||
- #215 起，新建 SYB 采购任务不再根据 PDD 档案创建 `purchase_spec_match_work_item`，也不在首次派发前调用外部 AI；规格决策统一来自首趟真机探测的当次候选。
|
||||
- 部署前已存在的匹配工作项继续保留审计、恢复、重试和人工处理能力；其 AI 封闭候选、置信度、输入指纹、退避和最长 60 秒调用边界不变，但不能成为新任务跳过当次探测的依据。
|
||||
|
||||
## SYB 采购强制当次规格探测（#215）
|
||||
|
||||
- 每个新 SYB 采购任务固定执行“首趟只读探测 → 服务端确定性优先/必要时 AI → 固化任务级精确规格 → 第二趟正式采购”。首趟只打开一次浏览器商品链接；匹配期间当前设备保留给同一任务，不领取其他采购或采集任务；第二趟复用 PDD 当前页，不再次打开链接，也不严格核验标题、goodsId 或页面指纹，但仍要求 PDD 包名与商品/规格/订单页面结构安全证据。已有长期映射只作商品档案事实，不直接进入任务执行规格。
|
||||
- 首趟候选与 `taskId`、`taskAttemptId`、`deviceId`、规则快照哈希和幂等结果哈希关联；第二趟失败不得回到首趟循环探测。备货 `stock/direct_select` 没有 SYB 目标规格，继续使用用户逐字选择的档案规格，不进入本规则。
|
||||
- 候选和 Provider 结果仅保存颜色、尺码原始标签及结构化决策，不保存控件树、整屏截图、账号、地址、订单或支付数据；付款仍永久禁止。
|
||||
|
||||
## Agent 手动采集替代商品（#130）
|
||||
|
||||
@@ -386,6 +393,13 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
- Agent APK 版本由管理员在设备页抽屉中上传、核对并显式设为当前。服务端从 APK Manifest 读取整数 `versionCode` 和 `versionName`，保存 SHA-256、大小、说明和创建人；APK 位于非公开目录，Admin 与设备下载均需认证。
|
||||
- Agent 只以整数 `versionCode` 判断更新。启动时静默检查一次，设置页可手动检查、显示下载进度并取消；下载完成必须校验大小和 SHA-256。设备有活动任务时禁止检查、下载和安装；安装始终交给 Android 系统确认，项目不绕过未知来源权限。
|
||||
|
||||
## Android 采购规格动作安全执行（#214）
|
||||
|
||||
- 规格入口与精确规格选择统一按“重新定位唯一目标 → 执行一次无障碍点击 → 读取新页面验证”执行；不得复用旧无障碍节点，不选择相近规格，也不在多候选时默认点击第一个。
|
||||
- 无障碍点击后页面完全无变化时，只允许对解析器已确认的安全规格入口或服务端下发且唯一命中的精确规格执行一次中心手势兜底。目标必须可见、启用、边界有效，手势后仍须以规格面板强证据或精确选中证据确认结果。
|
||||
- 页面发生变化但规格面板强证据不足时，不再继续手势或猜测页面，明确失败并只记录面板类型、候选数量和证据布尔值等无敏感标量。原始控件树、节点文字集合和整屏截图仍不得保存或上传。
|
||||
- 规格已处于精确选中状态时不得重复点击。规格查找只在解析器唯一识别的规格面板容器内有限滚动，每次滚动后重新定位容器与目标；容器缺失、歧义、到边或验证失败均 fail-closed。
|
||||
- 中心手势兜底不得用于修改/保存地址、创建或提交订单、订单详情入口以及任何支付/付款目标；正式创建订单的一次性不可逆门禁与永久禁止支付规则不变。
|
||||
## PDD 商品反向关联与继续订单采购（#161）
|
||||
|
||||
- 一个 PDD 商品可被多个虾皮商品共用。PDD 详情返回全部关联虾皮商品摘要；订单行由独立统一分页接口读取，不按虾皮商品伪造嵌套分页。
|
||||
@@ -409,3 +423,9 @@ synchronized_at: 2026-09-02T13:23:12Z
|
||||
- AI 只在关联蝦皮商品的封闭候选集合中返回原始颜色/尺码，并必须提供达到当前自动确认阈值的置信度和非空理由；集合外值、缺失角色、低置信度、歧义、无结果和输入漂移都不得确认。
|
||||
- `parse_status` 保留确定性解析器结论；AI 与人工确认分别记录，人工优先级最高。重复同步不得覆盖人工值；完全相同输入保留 AI 值，来源或关联变化会清除旧 AI 确认。
|
||||
- 同一输入的低置信度或无结果不重复调用 Provider；临时故障至少 60 分钟后重试，最多 3 次。任务不创建采集/采购任务、订单，不执行 Android 动作或付款。
|
||||
|
||||
## 设备身份恢复
|
||||
|
||||
- 管理员可在设备管理对未停用设备发起“重置设备身份”。此动作不删除设备记录、不改变设备 ID、能力或已绑定的待领取任务；它立即使旧 Token 无效，并只生成一次、有效期 10 分钟的恢复码。
|
||||
- 恢复码仅显示给发起操作的管理员一次，服务端只保存摘要；不得进入列表、日志、任务记录、Android 持久化或普通接口。手机操作员必须在同一安装实例的 Agent 设置中手动输入。
|
||||
- 服务端只接受同一 `installId`、未过期且尚未使用的恢复码完成重新注册，成功后签发新 Token 并使恢复码失效。过期、重复使用、installId 不符或停用均明确失败；不能通过清空数据、直接改库或“吊销 Token”恢复原任务归属。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Local-Development-and-Verification
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Local-Development-and-Verification.-
|
||||
wiki_revision: 0bb8d63fe2a3c6b1021bfa18800f5062de726868
|
||||
synchronized_at: 2026-08-31T16:06:55Z
|
||||
wiki_revision: 835494c4a63a1494601658561fde1ab76657be3d
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 本地开发与验证
|
||||
@@ -24,6 +24,32 @@ T01 已建立可执行的三端骨架。建议从仓库根目录运行统一脚
|
||||
- 不得仅为设置编码重复启动一层 PowerShell；嵌套进程会增加启动时间、转义复杂度和错误定位成本。
|
||||
- 代码发现优先使用项目配置的代码图工具；检索字符串、配置和非代码文件，或图工具不足时使用 `rg`。
|
||||
|
||||
### PowerShell 语法与外部命令
|
||||
|
||||
- Windows 命令不得默认套用 Bash 语法；复杂正则优先先赋给变量或使用 `rg -e`，避免在多层引号中继续嵌套。
|
||||
- 多行 Python 或 JSON 正文使用单引号 PowerShell here-string，避免 `$()`、反引号和变量被 PowerShell 提前展开：
|
||||
|
||||
```powershell
|
||||
$script = @'
|
||||
print("保持原文")
|
||||
'@
|
||||
$script | python -
|
||||
```
|
||||
|
||||
- `foreach`、`if` 等语句块应保留在同一个 PowerShell 解析上下文中；需要收集表达式结果时使用数组表达式：
|
||||
|
||||
```powershell
|
||||
$items = @(foreach ($path in $paths) {
|
||||
if (Test-Path -LiteralPath $path) { Get-Item -LiteralPath $path }
|
||||
})
|
||||
```
|
||||
|
||||
- `rg` 使用真实目录配合 `-g/--glob`，不要把 Bash 风格通配路径作为目录参数：
|
||||
|
||||
```powershell
|
||||
rg -n -g '*.md' 'sync --check' docs
|
||||
```
|
||||
|
||||
### 文件编码与控制台输出
|
||||
|
||||
文件解码和控制台输出是两个边界。读取 UTF-8 文本时，在命令支持的情况下显式指定字面路径与编码：
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Common-Changes
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Common-Changes.-
|
||||
wiki_revision: b7d5520da954c544248e979c4ababb86d2784a43
|
||||
synchronized_at: 2026-08-27T09:38:36Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 常见修改指南
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Troubleshooting
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting
|
||||
wiki_revision: a8d4790811aa825c78830cb9c71c6b21723e4584
|
||||
synchronized_at: 2026-08-28T03:35:05Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 故障排查
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Product-Requirements-Overview
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Product-Requirements-Overview.-
|
||||
wiki_revision: 0d9924b4566e567edf167ba678fedde28a41cfd3
|
||||
synchronized_at: 2026-08-28T02:27:12Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 产品需求总览与当前 MVP
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Android-Agent-API-Contract
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.-
|
||||
wiki_revision: 75cebdfb2408d35e59d05d5755068b6d8cd126f5
|
||||
synchronized_at: 2026-09-02T13:24:29Z
|
||||
wiki_revision: 08a65eb49d3d1091f0be30e6f6d1a9372f6e5b37
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# MVP 共享 API 契约
|
||||
@@ -49,18 +49,15 @@ DELETE /api/admin/v1/shopee-products/{productId}/specs/mapping
|
||||
POST /api/admin/v1/shopee-products/{productId}/specs/mapping/confirm
|
||||
POST /api/admin/v1/shopee-products/{productId}/specs/mapping/confirm-exact-matches
|
||||
POST /api/admin/v1/shopee-products/{productId}/specs/mapping/preview-auto-size
|
||||
POST /api/admin/v1/shopee-products/{productId}/specs/mapping/auto-match
|
||||
POST /api/admin/v1/shopee-products/batch-delete
|
||||
```
|
||||
|
||||
创建与关联/映射相关写操作均提交 `requestId` 做幂等重放；重放请求返回相同结果并标记 `replayed`。创建请求提交 `shopeeItemId`、`title`、`shopName`，可选 `pddProductId` 和 `specs`；`shopeeItemId` 重复时返回 `SHOPEE_ITEM_ID_EXISTS` 和已存在商品 ID。`link-pdd` 校验 PDD 商品存在且非 `disabled`，否则分别返回 `PDD_PRODUCT_NOT_FOUND` 或 `PDD_PRODUCT_DISABLED`；关联成功后返回值包含 `sharedByPddCount`，表示当前共用同一 PDD 商品的虾皮商品数。
|
||||
|
||||
`specs` 结构同 PDD 商品的维度/规格值形状，但规格值额外携带 `source`（`import` / `manual`）与可选的 `mapping`（`pddValue`、`source`、`status`、`confidence`、`reason`）。新增规格值固定为 `manual` 来源；删除规格值仅允许 `manual` 来源，`import` 来源返回 `SPEC_VALUE_NOT_MANUAL`。设置映射时，`exact_match` 与 `ai_match` 来源一律写入 `pending` 状态，与请求体中的 `status` 无关；只有 `manual` 来源可以直接写入 `confirmed`。`confirm-exact-matches` 仅确认 `source=exact_match` 且状态为 `pending` 的映射，不影响 `ai_match`。该通用入口不因 #188 或 #194 改变；两者只能通过各自独立的服务端写入路径，将唯一确定性 `exact_match` 或通过高置信度门槛的 `ai_match` 写入 `confirmed`。
|
||||
`specs` 结构同 PDD 商品的维度/规格值形状，但规格值额外携带 `source`（`import` / `manual`）与可选的 `mapping`（`pddValue`、`source`、`status`、`confidence`、`reason`）。新增规格值固定为 `manual` 来源；删除规格值仅允许 `manual` 来源，`import` 来源返回 `SPEC_VALUE_NOT_MANUAL`。设置映射时，`exact_match` 与 `ai_match` 来源一律写入 `pending` 状态，与请求体中的 `status` 无关；只有 `manual` 来源可以直接写入 `confirmed`。`confirm-exact-matches` 仅确认 `source=exact_match` 且状态为 `pending` 的映射，不影响 `ai_match`。该通用入口不因 #188 改变；#188 仅通过下述采购批量规格匹配接口的独立写入路径，将唯一确定性 `exact_match` 或通过高置信度门槛的 `ai_match` 写入 `confirmed`。
|
||||
|
||||
`preview-auto-size` 是只读计算接口（使用 `POST` 触发计算，不写数据库），无需 `requestId`。它读取当前蝦皮尺码与关联 PDD 的可选尺码，只返回格式统一后唯一确定的匹配；响应含 `items[]`（`valueName`、可选 `pddValue`、`status=preserved|matched|pending`、`reason`）、`pddValues`、`matchedCount` 和 `pendingCount`。已确认且目标仍存在的映射标为 `preserved`；无唯一结果标为 `pending`。Admin 的显式“保存修改”仍通过既有设置/确认接口落库。
|
||||
|
||||
`auto-match` 是 Admin 蝦皮商品详情一键匹配颜色和尺码的独立写入接口。请求体必须提交 UUID `requestId` 和详情返回的 `specContextVersion`。服务端在事务外完成必要的 Provider 调用，入事务后重新锁定蝦皮商品与 PDD 商品，复核关联、完整规格上下文、当前可选候选、AI 开关和最新置信度阈值。保留有效的已确认映射；唯一确定结果直接保存为 `exact_match + confirmed`；置信度达标、理由非空且候选仍有效的 AI 结果保存为 `ai_match + confirmed`；其余项保持未匹配。响应含 `product`、`items[]`（`dimension`、`role`、`valueName`、可选 `pddValue`、`status=confirmed|preserved|unmatched`、可选 `source`、`confidence`、`reason`）、`confirmedCount`、`preservedCount`、`unmatchedCount` 和 `replayed`。同一 `requestId` 幂等重放；Provider 异常或 AI 未启用返回 `AI_MATCHING_UNAVAILABLE`，关联或规格变化返回 `SPEC_CONTEXT_VERSION_STALE`，两者都不写入本次结果。
|
||||
|
||||
设置映射时，`pddValue` 必须是关联 PDD 商品同角色下当前可选的原始规格标签，否则返回 `INVALID_REQUEST`。PDD 重新采集后旧目标消失时，Admin 标记失效；采购预检与任务创建返回 `PURCHASE_SPEC_MAPPING_REQUIRED` 和“规格匹配已失效，请重新选择 PDD 规格”，不得把旧标签下发给 Agent。
|
||||
|
||||
`batch-delete` 提交 `requestId` 和 `ids`（1～500 个），逐条校验引用后返回每条的 `status`（`deleted` / `skipped`）与 `reason`；引用检查覆盖 SYB 明细（#41）与采购任务（#33/#34），两张表落地前恒不阻塞删除。`restore` 恢复一条已软删除商品，恢复后原有 PDD 关联与规格映射保持不变。列表接口 `status=deleted` 筛选已删除商品，默认只返回存活商品。
|
||||
@@ -408,7 +405,7 @@ POST /api/agent/v1/tasks/{taskId}/fail
|
||||
|
||||
- `executionMode` 只能是 `rehearsal` 或 `live`，创建后不可修改。
|
||||
- 正式 `live` 任务必须引用一条 `syb_product`；无副作用的 `rehearsal` 可以不引用 SYB。
|
||||
- 创建时固化 SYB、蝦皮订单号、虾皮商品、PDD 商品、目标规格、映射规格、数量、价格区间、币种、URL、`goods_id`、规则和可选 PDD 账号引用。正式任务的 `shopeeOrderNoSnapshot` 来自创建时的 `syb_product.order_code`；同一订单号可对应多条任务，之后来源商品修改不会改写任务快照。
|
||||
- 创建时固化 SYB、蝦皮订单号、虾皮商品、PDD 商品、目标规格、数量、价格区间、币种、URL、`goods_id`、规则和可选 PDD 账号引用。新建 SYB 任务的执行映射初始为空，首趟当次 PDD 规格探测决策成功后才固化 `mappedColor` / `mappedSize`；正式任务的 `shopeeOrderNoSnapshot` 来自创建时的 `syb_product.order_code`，之后来源商品修改不会改写任务快照。
|
||||
- Android 无法可靠读取当前 PDD 账号，因此 `pddAccountId` 和 `pddAccountRefSnapshot` 均可空。已知账号时参与账号级串行，未知时不阻止任务。
|
||||
- 地址后缀由任务 ID 唯一确定为 `_cg{taskId}`；#34 创建任务时必须在同一事务内回写快照。
|
||||
- 一个任务最多对应一个 PDD 订单；重新采购必须新建任务，旧任务和旧订单保留。
|
||||
@@ -418,7 +415,7 @@ POST /api/agent/v1/tasks/{taskId}/fail
|
||||
| 状态 | 含义 | 是否占用 SYB 活动槽 |
|
||||
|---|---|---|
|
||||
| `pending` | 待执行 | 是 |
|
||||
| `spec_probe_pending` | 第一趟探测结束，待服务端固化规格并重新派发 | 是 |
|
||||
| `spec_probe_pending` | 第一趟探测结束，服务端规格匹配中；当前设备保留同任务连续流程且不得领取其他任务 | 是 |
|
||||
| `running` | Agent 执行中 | 是 |
|
||||
| `rehearsal_completed` | 演练安全结束，未改地址、未创建订单 | 否 |
|
||||
| `order_submit_started` | 不可逆标记已落库，只能核单，禁止再次点击 | 是 |
|
||||
@@ -496,6 +493,16 @@ POST /api/agent/v1/tasks/{taskId}/fail
|
||||
|
||||
演练规则必须包含 `purchase.rehearsal.v1`，并且不能包含 `updateShippingAddress`、`createOrder`、`readOrderResult`。正式规则必须包含 `purchase.live.v1`；改地址和创建订单还分别要求 `purchase.address-update.v1`、`purchase.order-create.v1`。`probeSpecs` 要求 `purchase.spec-probe.v1`。任意模式下，尚未实现的 `pay`、名称包含 `payment` 的动作以及未知动作一律拒绝；服务端不下发任意脚本。
|
||||
|
||||
### Android 规格动作执行边界（#214）
|
||||
|
||||
本工单不改变采购规则 schema、Agent HTTP 字段或能力标识，只收紧 Android 对 `openSpecPanel` 与 `selectSpec` 的执行语义：
|
||||
|
||||
- 每次操作从最新 `rootInActiveWindow` 重新定位；规格入口必须是解析器已接受的唯一安全候选，规格值必须逐字等于任务固化的服务端映射值且在当前维度唯一、可用。
|
||||
- 动作前先检查后置条件；规格已精确选中时直接成功，不重复点击。否则最多分发一次 `ACTION_CLICK`，再从新快照验证规格面板强证据或精确选中证据。
|
||||
- `ACTION_CLICK` 后页面结构完全无变化时，Android 可以重新定位同一唯一目标，并在目标可见、启用、中心点位于屏幕内且边界有效时执行一次中心手势。手势后仍未取得后置证据时明确失败，不继续点击。
|
||||
- 点击后页面已变化但面板分类仍为未知时返回 `PURCHASE_SPEC_PANEL_EVIDENCE_NOT_MATCHED`；两种点击后页面均无变化时返回 `PURCHASE_SPEC_ENTRY_CLICK_NO_EFFECT`。诊断只携带面板类型、滚动容器数、标题数、选项数及证据布尔值，不携带节点文字或完整控件树。
|
||||
- 有界查找规格时只使用当前解析结果中的唯一 `specPanelContainer`；每次滚动前重新定位该容器，优先使用节点滚动动作，失败后才在容器边界内使用手势。缺少唯一容器时停止，不回退到全页面最大滚动区域。
|
||||
- 受控中心手势接口固定拒绝地址、保存地址、创建/提交/确认订单、确认购买和支付/付款语义；`updateShippingAddress`、`createOrder`、`readOrderResult` 不使用该兜底。创建订单的一次性不可逆状态机与禁止支付契约不变。
|
||||
### 管理端接口
|
||||
|
||||
| 方法 | 路径 | 幂等键 / 说明 |
|
||||
@@ -504,7 +511,7 @@ POST /api/agent/v1/tasks/{taskId}/fail
|
||||
| `GET` | `/api/admin/v1/purchase-tasks/{taskId}` | 只读任务详情与 attempt 历史；不返回规则原文、Token、凭据、完整地址、控件树或截图 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks` | `requestId`；单条创建 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/stock` | 创建备货采购；`requestId`、`executionMode`、`pddProductId`、可选 `deviceId` / `pddAccountId`、`color`、可选 `size`、`quantity`、`minUnitPriceCent`、`maxUnitPriceCent`。服务端使用内置规则并从所选颜色归档派生参考价；相同 `requestId` 幂等返回原任务 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/batch-preview` | `sybProductIds`（1～100）和可选 `deviceId`；逐条返回采购是否可创建、价格区间、原因和下一步，并独立返回 PDD 采集资格 `collectionEligible` / `collectionDisabledReason` 与规格匹配资格 `aiMatchEligible` / `aiMatchDisabledReason`，不创建任务。只有目标颜色和尺码已保存为确认映射，且共同命中最近一次成功或部分成功采集中的完整可售 SKU 组合时，`eligible` 才为 `true`；只在内存中得到的确定性结果不算采购就绪 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/batch-preview` | `sybProductIds`（1～100）和可选 `deviceId`；逐条返回采购是否可创建、价格区间、原因和下一步，并独立返回 PDD 采集资格 `collectionEligible` / `collectionDisabledReason` 与长期规格匹配资格 `aiMatchEligible` / `aiMatchDisabledReason`，不创建任务且不调用 AI Provider。自 #215 起，长期映射缺失或失效不再单独使 `eligible=false`；新任务会在首趟当次 PDD 页面探测中决定执行规格 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/batch-spec-match` | `sybProductIds`（1～100）；仅处理服务端预检 `aiMatchEligible=true` 的明细，其他明细按具体禁用原因返回 `skipped`，并逐条返回 `auto_confirmed` / `pending` / `failed` / `skipped`。资格要求 SYB 采购规格解析成功、蝦皮与 PDD 关联完整、PDD 当前规格可用，且最近一次成功或部分成功采集存在完整可售 SKU 组合证据；未人工确认的 `parse_status=uncertain` 不进入自动确认，`manuallyConfirmed=true` 与 `parse_status=success` 同等视为可信规格。唯一确定性 `exact_match` 不调用 Provider，直接通过独立路径保存为 `confirmed`；其余结果只有 `ai_match` 置信度达到 `autoConfirmMinConfidence`、理由非空、返回值属于当前候选且颜色+尺码命中同一个可售 SKU 组合时才保存为 `confirmed`。低置信度、无效组合和 Provider 异常不改写现有映射 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/batch` | 批次 `requestId`、`sybProductIds`（1～100）和可选 `deviceId`；每条派生稳定幂等键并独立创建，部分失败不回滚成功项 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/{taskId}/authorize-repurchase` | 一次性授权；创建新任务后自动消耗 |
|
||||
@@ -522,17 +529,17 @@ Admin 列表与详情由 #35 实现；#67 增加 `shopeeOrderNoSnapshot` 的列
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/agent/v1/purchase-tasks/next` | 返回与设备能力兼容的指定任务或空闲任务 |
|
||||
| `GET` | `/api/agent/v1/purchase-tasks/next` | 优先返回当前设备的运行任务；存在 `spec_probe_pending` 时返回同一等待任务以阻止其他任务插队，否则返回能力兼容的指定任务或空闲任务 |
|
||||
| `POST` | `/api/agent/v1/purchase-tasks/{taskId}/claim` | `requestId` 原子领取，并建立设备/可选账号租约 |
|
||||
| `POST` | `/api/agent/v1/purchase-tasks/{taskId}/start` | 创建不可变 `taskAttemptId` |
|
||||
| `POST` | `/api/agent/v1/purchase-tasks/{taskId}/order-submit-started` | 创建订单前先落不可逆标记；演练任务永远拒绝 |
|
||||
| `POST` | `/api/agent/v1/purchase-tasks/{taskId}/order-submit-started` | 创建订单前先落不可逆标记；演练任务和 `spec_probe` attempt 永远拒绝 |
|
||||
| `POST` | `/api/agent/v1/purchase-tasks/{taskId}/result` | 请求体携带 `taskAttemptId` 和 `requestId`；幂等提交演练、规格探测、订单或失败结果 |
|
||||
|
||||
创建阶段需要外部 AI 的任务会先以 `pending` 与持久匹配工作项同事务创建并立即返回 Admin。工作项处于 `pending`、`running`、`retry_wait` 或 `manual_required` 时，`next` 不返回该任务，直接调用 `claim` 或 `start` 也会返回状态冲突。匹配完成后 Agent 仍只接收服务端固化的精确 PDD 原始标签；Android 接口和请求体不新增 AI、候选或人工决策字段。
|
||||
自 #215 起，新建 SYB 采购任务不再从 PDD 档案创建持久匹配工作项，也不在首次派发前调用外部 AI；部署前已存在的 `purchase_spec_match_work_item` 继续按原状态兼容处理。新任务首次 `start` 固定得到 `phase=spec_probe`，Android 通过浏览器打开任务链接一次并经既有结果字段回传当次候选；匹配成功后的第二次 `start` 才得到 `phase=purchase` 和服务端固化的精确 PDD 原始标签。第二阶段直接复用首趟保留的 PDD 页面，不再次打开浏览器链接，也不以标题、goodsId 或页面指纹做严格同页校验；仍必须通过 PDD 包名和商品/规格/订单页面结构安全证据。Android 不接收 AI 配置或自由决策权限。
|
||||
|
||||
结果提交至少关联 `taskId`、`taskAttemptId`、`deviceId`、规则快照哈希和结构化结果。相同 attempt 的相同结果重复提交返回同一事实；不同内容拒绝覆盖。慢路径第一趟提交规格后释放设备与已知账号租约，任务进入 `spec_probe_pending`；服务端先使用已确认人工映射，否则对实时/档案可选规格做繁简、空白/全半角/大小写及公斤/斤的唯一确定性匹配，仍无唯一结果才调用 AI。第二趟只会收到服务端已固化的精确 PDD 原始标签；Agent 只在已打开的规格面板内做有限纵向滑动，每次重新读取节点并按完整规范化文字精确点击，连续没有新证据或达到上限即停止。尺码的任务目标与页面值在选择边界使用同一安全尾价规范化；不改写任务快照，规范化为空、仍含货币符号或多个原始候选折叠为同一值时安全失败。
|
||||
结果提交至少关联 `taskId`、`taskAttemptId`、`deviceId`、规则快照哈希和结构化结果。相同 attempt 的相同结果重复提交返回同一事实；不同内容拒绝覆盖。每个新 SYB 采购任务的第一趟只读遍历当次 PDD 规格面板并提交颜色、尺码原始候选，随后释放数据库租约和已知账号运行守卫并进入 `spec_probe_pending`，但服务端调度与 Agent 必须把当前设备保留给同一采购流程：`next` 返回该等待任务，Agent 只轮询等待，不领取其他采购或采集任务。服务端只以任务冻结的 SYB 目标和当次候选先做繁简、空白/全半角/大小写及公斤/斤的唯一确定性匹配，仍无唯一结果才调用 AI。AI 的颜色和尺码必须逐字属于当次对应候选，否则按无匹配失败。第二趟只会收到服务端固化的精确 PDD 原始标签；Agent 复用首趟仍打开的页面，只在已打开的规格面板内做有限纵向滑动，每次重新读取节点并按完整规范化文字精确点击，连续没有新证据或达到上限即停止。尺码的任务目标与页面值在选择边界使用同一安全尾价规范化；不改写任务快照，规范化为空、仍含货币符号或多个原始候选折叠为同一值时安全失败。
|
||||
|
||||
任务 payload 新增必传布尔字段 `specResolutionAllowed`，它是 Android 是否可以把一次 `PURCHASE_SPEC_TARGET_NOT_VISIBLE` 转为 `spec_probe_completed` 的唯一资格事实。服务端仅在 `taskType=syb_order`、规则声明 `purchase.spec-probe.v1`、没有固化 `SpecDecisionRequestID` 且规格来源允许既有慢路径时返回 `true`；`stock`、`direct_select`、已固化规格决策、能力缺失及其他组合均返回 `false`。普通就地重试保留 `SpecDecisionRequestID`、目标规格、映射规格和规格决策快照，不能恢复探测资格。Android 不得根据映射是否非空、执行 phase、错误文字或本地判断扩大资格。
|
||||
任务 payload 的必传布尔字段 `specResolutionAllowed` 是 Android 是否可以提交规格探测的唯一资格事实。新建 `taskType=syb_order` 任务必须由声明 `purchase.spec-probe.v1` 的规则创建，初始 `SpecDecisionRequestID` 为空且 `specSource=unresolved`，首趟返回 `true`；当次决策固化后返回 `false`。`stock`、`direct_select`、已固化规格决策、能力缺失及其他组合均返回 `false`。历史兼容的就地 `/reset` 保留 `SpecDecisionRequestID`、目标规格、映射规格和规格决策快照，不能恢复探测资格；映射不完整时必须拒绝，不能进入正式采购阶段。普通 Agent 重试创建新任务并重新取得一次探测资格。Android 不得根据映射是否非空、错误文字或本地判断扩大资格。
|
||||
|
||||
Android 规格失败使用五个稳定阶段：`PURCHASE_SPEC_TARGET_NOT_VISIBLE`、`PURCHASE_SPEC_TARGET_AMBIGUOUS`、`PURCHASE_SPEC_SAFE_TARGET_MISSING`、`PURCHASE_SPEC_CLICK_FAILED` 和 `PURCHASE_SPEC_SELECTION_UNCONFIRMED`。`PURCHASE_SPEC_CLICK_FAILED` 的 `errorMessage` 只允许稳定子原因 `root_unavailable`、`target_stale`、`no_clickable_ancestor`、`action_click_false` 或 `unknown`；其他阶段的消息不得包含规格原文、坐标、控件树或截图。只有 `PURCHASE_SPEC_TARGET_NOT_VISIBLE && specResolutionAllowed=true` 可以提交规格探测，其他四态直接提交真实失败，服务端原样保留稳定阶段/子原因。旧 Agent 在资格已用尽后再次提交 `spec_probe_completed` 时，服务端以 `PURCHASE_SPEC_REPROBE_REJECTED` fail-closed，释放租约并保留第一次规格决策，不再冒充新的选择根因或再次派发。无匹配、候选不完整、歧义或 Provider 异常同样使任务失败。`order_result_unknown` 只允许管理员或采购员人工解除，永不自动重派。
|
||||
|
||||
@@ -610,12 +617,12 @@ Content-Type: application/json
|
||||
- 响应返回 `taskId`、`attemptNumber`、`status` 和可选的 `replayed`，不返回规则快照、URL、Token、控件树或截图。
|
||||
- 设备离线、任务非终态、设备忙、规则不可用或同商品存在活动任务时返回明确冲突，不支持离线排队。
|
||||
|
||||
## Agent 受控采购重试（#95、#157）
|
||||
## Agent 受控采购重试（#95、#157、#217）
|
||||
|
||||
普通失败任务的“重试采购”改为就地重跑：
|
||||
普通失败任务的“重试采购”和替代商品匹配完成后的“继续采购”统一调用新任务接口：
|
||||
|
||||
```http
|
||||
POST /api/agent/v1/purchase-tasks/{taskId}/reset
|
||||
POST /api/agent/v1/purchase-tasks/{taskId}/retry
|
||||
Authorization: Bearer <device-token>
|
||||
Content-Type: application/json
|
||||
|
||||
@@ -627,37 +634,35 @@ Content-Type: application/json
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"taskId": 12,
|
||||
"taskNo": "CG-12",
|
||||
"attemptNumber": 2,
|
||||
"status": "pending",
|
||||
"sourceTaskId": 12,
|
||||
"sourceTaskNo": "CG-12",
|
||||
"taskId": 13,
|
||||
"taskNo": "CG-13",
|
||||
"replayed": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 原任务必须属于当前 Device Token、在最近 30 天内、状态为 `failed`，且是分配给该设备的正式 SYB 采购任务；跨设备或超期按任务不存在处理。
|
||||
- 任务不得存在 `irreversibleAt`、`orderSubmitRequestId`、PDD 订单号或下单时间。已有任何不可逆证据时返回 `PURCHASE_RETRY_UNSAFE`，提示走“授权重新采购”，不得恢复为待执行。
|
||||
- 服务端在同一事务锁定任务和设备，确认同一 SYB 商品没有更新任务、设备在线且空闲，然后读取当前服务端采购规则，重新校验 schema、动作安全边界与设备能力。
|
||||
- 成功时复用原 `purchase_task.id`，只刷新 `ruleSnapshot`、`ruleType`、`ruleSchemaVersion`、`requiredCapabilities`，清除错误、租约和运行守卫并恢复 `pending`。商品、Target、Mapped、价格保护、数量、地址后缀及其他业务快照逐字段保持不变。
|
||||
- 每次受理创建该任务的新 `pending` attempt 并记录规则哈希；Start 复用该 attempt 转为 `running`，不会重复创建执行记录。相同 `requestId` 重放返回相同 attempt 且 `replayed=true`；不同请求可在任务再次失败后继续重试，不限制次数。
|
||||
- 采购详情新增 `attemptCount`、可选 `lastFailureCode` 和 `lastFailureMessage`，供 Agent 显示已尝试次数与上次失败原因；不返回规则快照、Token、地址、控件树或截图。
|
||||
- Android 仍只在服务端 `retryable=true` 且状态为 `failed` 时显示普通“重试采购”。确认文案必须说明任务号不变、使用最新规则重跑、可能产生待付款订单且系统不会支付。
|
||||
- 规则无效、设备离线/忙、能力不匹配、任务状态变化或同一 SYB 商品已有更新任务时，服务端明确拒绝且不得部分修改任务。
|
||||
- 来源任务必须属于当前 Device Token、在最近 30 天内、状态为 `failed`，且是分配给该设备的正式 SYB 采购任务；跨设备或超期按任务不存在处理。
|
||||
- 来源任务不得存在 `irreversibleAt`、`orderSubmitRequestId`、PDD 订单号或下单时间。已有任何不可逆证据时返回 `PURCHASE_RETRY_UNSAFE`，提示走“授权重新采购”，不得创建新任务。
|
||||
- `AgentRetry → BatchRetry → Create` 保留来源失败任务并创建不同 `purchase_task.id` 的新任务；新任务重新读取当前 SYB、虾皮/PDD 档案、当前采购规则、价格保护和设备能力，重新生成地址后缀，不继承来源任务的旧规格决策。
|
||||
- 新 SYB 任务按 #215 固定从 `spec_probe` 开始。相同 `requestId` 重放返回同一新任务且 `replayed=true`；不同 requestId 再次请求受同一 SYB 商品最新任务和设备并发门禁约束。
|
||||
- Android 只在服务端 `retryable=true` 且状态为 `failed` 时显示普通“重试采购”；确认文案和成功反馈必须说明原任务保留、新任务使用当前档案与规则、可能产生待付款订单且系统不会支付。
|
||||
- 规则无效、当前档案或价格不合格、设备离线/忙、能力不匹配、任务状态变化或同一 SYB 商品已有更新任务时，服务端明确拒绝且不得部分创建。
|
||||
- Admin 批量重试继续使用相同的新任务语义；替代商品“继续采购”仍在 AgentRetry 前额外验证替换分项与继续采购资格。
|
||||
|
||||
既有新建任务接口保留原语义：
|
||||
历史兼容的就地重置接口仍保留，但 Android 普通重试不再调用：
|
||||
|
||||
```http
|
||||
POST /api/agent/v1/purchase-tasks/{taskId}/retry
|
||||
POST /api/agent/v1/purchase-tasks/{taskId}/reset
|
||||
Authorization: Bearer <device-token>
|
||||
Content-Type: application/json
|
||||
|
||||
{"requestId":"<uuid>"}
|
||||
```
|
||||
|
||||
- `/retry` 的 `AgentRetry → BatchRetry → Create` 行为不变：保留来源失败任务并创建新任务，返回 `sourceTaskId`、`sourceTaskNo`、新 `taskId`、新 `taskNo` 和 `replayed`。
|
||||
- Android 普通“重试采购”不再调用 `/retry`；只有 #132 替代商品规格匹配完成后的“继续采购”继续调用它。Admin 批量重试行为也不变。
|
||||
- “继续采购”会重新解析替代商品、规格映射与价格并生成新地址后缀；这与普通失败任务保持快照的就地重跑不可互换。
|
||||
- `/reset` 只允许安全失败、无不可逆证据且不存在更新任务的原任务；它保留原业务快照并刷新当前规则。
|
||||
- 目标颜色存在但映射颜色为空，或目标尺码存在但映射尺码为空时，必须返回 `PURCHASE_SPEC_MAPPING_REQUIRED`，不得创建 `purchase` attempt 或下发正式采购 payload。
|
||||
- 两个入口都不执行支付。真机调用可能创建待付款订单，必须先取得人工授权。
|
||||
|
||||
## Agent 任务记录范围与同步（#99）
|
||||
@@ -849,22 +854,14 @@ file=<JPEG 二进制>
|
||||
|
||||
Agent 只比较整数 `versionCode`。设备有活动任务时禁止检查、下载和安装；下载到应用私有缓存并校验响应大小与 SHA-256，失败立即删除。安装使用 FileProvider 和 Android 系统安装确认页；未知来源权限必须由用户在系统设置授权，不静默安装。
|
||||
|
||||
## Admin 蝦皮规格自动匹配批次（#195）
|
||||
## 设备身份恢复（#201）
|
||||
|
||||
以下接口仅管理员可用，采购员与其他角色必须拒绝；两者不属于 Android Agent 接口，不改变任何 Agent 契约。
|
||||
```http
|
||||
POST /api/admin/v1/devices/{deviceId}/identity-reset
|
||||
POST /api/agent/v1/register
|
||||
X-GoAuto-Device-Recovery-Code: <one-time-code>
|
||||
```
|
||||
|
||||
### `POST /api/admin/v1/shopee-spec-auto-match/runs`
|
||||
仅管理员可以对未停用的既有设备发起身份重置。服务端立即使旧 Device Token 无效，并生成 10 分钟内仅能使用一次的恢复码；恢复码只在该管理员操作的响应中返回一次，服务端仅保存不可逆摘要，管理端设备列表、日志、任务接口和 Android 本地持久化均不得保存或返回原文。管理员将恢复码经受控人工渠道输入同一安装实例的 Agent 设置页。
|
||||
|
||||
请求：`{ "requestId": "UUID" }`。服务端以 `requestId` 幂等，异步受理默认最多 20 个商品的手动批次，并返回 HTTP 202、`data.run` 运行摘要。若已有活动批次，不再创建第二个批次，返回当前运行并标记 `alreadyRunning=true`；相同请求重放标记 `replayed=true`。
|
||||
|
||||
### `GET /api/admin/v1/shopee-spec-auto-match/runs/latest`
|
||||
|
||||
返回 `data.run`；从未执行时为 `null`。运行摘要包含 `id/requestId/trigger/status/batchLimit/scannedCount/eligibleCount/processedCount/confirmedCount/unmatchedCount/failedCount/startedAt/finishedAt` 和可选脱敏 `errorSummary`，不得返回 API Key、Provider 原始响应或商品原始 JSON。
|
||||
|
||||
`status` 当前为 `running`、`completed`、`completed_partial` 或 `failed`。页面只轮询最近摘要；查询本身不调用 AI。批次只更新蝦皮商品规格映射，不创建采购任务、订单或付款动作。
|
||||
|
||||
## SYB 异常规格 AI 解析字段（#198）
|
||||
|
||||
既有 SYB 商品列表与详情响应增加以下只读字段：`aiConfirmed`、可空 `aiConfidence`、可空 `aiReason`、可空 `aiConfirmedAt`。`aiInputFingerprint` 仅用于服务端并发和漂移校验，禁止通过 API 返回。`parseStatus` / `parseNote` 继续表示确定性解析器结果，`manuallyConfirmed` 继续只表示人工确认。
|
||||
|
||||
采购预检把仍命中关联蝦皮当前候选的 `aiConfirmed=true` 视为可信目标规格；候选消失、关联变化或来源重导入使其失效，并返回重新解析/人工修正原因。该能力不新增 Android 接口或 Agent 字段，不创建采购任务或订单。
|
||||
Agent 携带既有 Token（可已失效）及恢复码重新调用注册接口。服务端必须同时校验同一 `installId`、未停用状态、恢复码摘要、未过期和未使用；成功后使用原 `deviceId` 写入新 Token 摘要并返回一次新 Token，清除恢复码摘要和有效期。旧 Token 与恢复码都立即失效，已分配的 pending 采集或采购任务保持原 `deviceId`，不创建替代设备记录。缺少或错误恢复码仍为 `DEVICE_INSTALL_ID_CONFLICT`；过期码为 `DEVICE_RECOVERY_EXPIRED`；停用设备为 `DEVICE_DISABLED`。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Delivery-Issues
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Delivery-Issues.-
|
||||
wiki_revision: 0eed28dd5dc629ce66071833d5fefbdf24d567d3
|
||||
synchronized_at: 2026-08-24T02:35:58Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 当前 MVP 交付工单索引
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: OnePlus-Real-Device-Acceptance
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/OnePlus-Real-Device-Acceptance.-
|
||||
wiki_revision: 5b74a3b915cda6307cd59087bf9ce295f4c5e806
|
||||
synchronized_at: 2026-08-21T08:08:57Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 一加真机验收记录
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: PDD-Detail-Rule-Migration-Analysis
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/PDD-Detail-Rule-Migration-Analysis.-
|
||||
wiki_revision: 1fe9ed083c4fc565a50b4186571233d1dfab58a7
|
||||
synchronized_at: 2026-08-17T03:28:38Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# PDD 商品详情采集规则迁移分析
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: SYB-ERP-Interface-Contract
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/SYB-ERP-Interface-Contract.-
|
||||
wiki_revision: f596931468caf524cbd9d90b3c299b32a8cf8228
|
||||
synchronized_at: 2026-08-28T02:29:07Z
|
||||
wiki_revision: ad9adc22e69e48c9a8fd87d7121066eecca55fd6
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 12 顺云宝（SYB）ERP 接口契约
|
||||
@@ -393,19 +393,32 @@ POST /am/stock/detail/listByStock?hist=0
|
||||
|
||||
顺运宝给的是**商品级 ID + 规格原文**，没有規格 ID。
|
||||
|
||||
### 6.3 `productSpec` 的格式和蝦皮报表完全一致
|
||||
### 6.3 `productSpec` 的角色顺序不是固定的
|
||||
|
||||
```text
|
||||
蝦皮目录 `spec_raw` 黑色,M【建議40-50公斤】
|
||||
顺运宝 productSpec 白色,L【建議50-60公斤】
|
||||
黑色+白色【純棉兩件裝】 簡約親膚,L【建議52.5-60公斤】
|
||||
均碼,黑色
|
||||
```
|
||||
|
||||
`[必须]` 规格身份统一复用 `spec.SpecKey()`：只折叠空白，不猜颜色、尺码或建议。
|
||||
第三方目录脚本提交 `spec_raw` 和明确的解析结果；顺运宝匹配不到时交给人工确认。
|
||||
2026-09-04 的真实数据确认：`productSpec` 至少存在 `颜色,尺码` 与
|
||||
`尺码,颜色` 两种顺序，不能再固定把逗号前当颜色、逗号后当尺码。
|
||||
|
||||
`[必须]` 先按最后一个 ASCII 逗号拆成两段并剥离 `【...】` 备注。只有两侧
|
||||
恰好一侧带有明确尺码信号（如均码、字母尺码或明确尺码单位）时，才把该侧判为
|
||||
尺码、另一侧判为颜色。两侧都像尺码时标记存疑；不得使用模糊颜色词库、AI 或
|
||||
跨维度候选猜测角色。两侧都没有明确尺码信号时，暂按既有 `颜色,尺码` 契约兼容，
|
||||
并继续执行原有复杂分隔符和空值校验。
|
||||
|
||||
`[必须]` 修正规格角色时保留原始 `raw_json`，不得覆盖人工确认值。已错误写入
|
||||
虾皮档案的导入规格只能在确认无其他 SYB 明细引用且没有规格映射时移除；人工规格、
|
||||
映射及历史采购任务保持不变。
|
||||
|
||||
`[必须]` 规格身份继续复用 `spec.SpecKey()`：只折叠空白，不改写用于 PDD
|
||||
精确点击的原始候选标签。第三方目录脚本提交 `spec_raw` 和明确解析结果；角色或
|
||||
规格比对不明确时保持存疑，不得跨颜色/尺码猜测。
|
||||
|
||||
### 6.4 由此推导出的匹配路径
|
||||
|
||||
```text
|
||||
productId ──→ shopee_products.goods_id 商品级，直接相等
|
||||
productSpec ──→ SpecKey() ──→ 稳定规格身份键
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Deployment-and-Operations
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-and-Operations.-
|
||||
wiki_revision: 16d97e7596dc287786f702c71e25172b75cc4d56
|
||||
synchronized_at: 2026-09-02T15:05:56Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 部署与运维
|
||||
|
||||
+2
-2
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Home
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Home
|
||||
wiki_revision: d5a46210da9dffa27247d80b20ab31b40790e48a
|
||||
synchronized_at: 2026-08-31T16:06:14Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:06:45Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# GoAuto 文档中心
|
||||
|
||||
Vendored
+2
-2
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Deployment-Template
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-Template.-
|
||||
wiki_revision: 389f09d292b0aa408f26f1967e33eec82d37cedf
|
||||
synchronized_at: 2026-08-27T09:39:50Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 部署文档模板
|
||||
|
||||
Vendored
+2
-2
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Task-Archive-Template
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Task-Archive-Template.-
|
||||
wiki_revision: 53927b3b69fa26943f323f9be53153f80ed54530
|
||||
synchronized_at: 2026-08-24T08:23:07Z
|
||||
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
|
||||
synchronized_at: 2026-09-05T04:13:06Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
> 本模板只用于用户明确要求的专项历史快照或读取既有归档，不属于标准任务闭环。单次任务的唯一事实来源是 Gitea 工单；不要为了完成普通任务创建本页面，也不要自动导出到 `docs/task/`。
|
||||
|
||||
+240
-2
@@ -5,8 +5,11 @@ import os
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from argparse import Namespace
|
||||
from io import BytesIO
|
||||
from pathlib import Path
|
||||
from unittest.mock import Mock, patch
|
||||
from unittest.mock import MagicMock, Mock, patch
|
||||
from urllib.error import HTTPError
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
@@ -21,6 +24,7 @@ from harness import ( # noqa: E402
|
||||
existing_task_mirrors,
|
||||
export_task_archives,
|
||||
main as harness_main,
|
||||
run_sync,
|
||||
safe_title,
|
||||
task_target,
|
||||
)
|
||||
@@ -126,8 +130,215 @@ class MirrorTests(unittest.TestCase):
|
||||
sync_all(config, client)
|
||||
client.get_page.assert_not_called()
|
||||
|
||||
@patch("wiki_docs.dirty_mirror_paths", return_value=[])
|
||||
def test_incremental_sync_lists_once_and_skips_unchanged_body(self, _dirty) -> None:
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
target = root / "docs" / "README.md"
|
||||
target.parent.mkdir(parents=True)
|
||||
target.write_text(render_mirror(self.page), encoding="utf-8")
|
||||
config = Config(
|
||||
path=root / "wiki-docs.json",
|
||||
gitea_url="http://gitea.example",
|
||||
owner="o",
|
||||
repository="r",
|
||||
mappings=(Mapping("Home", "docs/README.md"),),
|
||||
)
|
||||
client = Mock()
|
||||
client.list_pages.return_value = [
|
||||
{
|
||||
"title": "Home",
|
||||
"sub_url": "Home",
|
||||
"last_commit": {"sha": self.page.revision},
|
||||
}
|
||||
]
|
||||
with patch("wiki_docs.ROOT", root):
|
||||
messages = sync_all(config, client)
|
||||
self.assertTrue(messages[0].startswith("无变化："))
|
||||
client.list_pages.assert_called_once_with()
|
||||
client.get_page_from_metadata.assert_not_called()
|
||||
|
||||
@patch("wiki_docs.dirty_mirror_paths", return_value=[])
|
||||
def test_incremental_sync_fetches_changed_page(self, _dirty) -> None:
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
target = root / "docs" / "README.md"
|
||||
target.parent.mkdir(parents=True)
|
||||
target.write_text(render_mirror(self.page), encoding="utf-8")
|
||||
changed = WikiPage(
|
||||
title="Home",
|
||||
sub_url="Home",
|
||||
text="# 新首页\n",
|
||||
revision="b" * 40,
|
||||
html_url=self.page.html_url,
|
||||
)
|
||||
metadata = {
|
||||
"title": "Home",
|
||||
"sub_url": "Home",
|
||||
"last_commit": {"sha": changed.revision},
|
||||
}
|
||||
config = Config(
|
||||
path=root / "wiki-docs.json",
|
||||
gitea_url="http://gitea.example",
|
||||
owner="o",
|
||||
repository="r",
|
||||
mappings=(Mapping("Home", "docs/README.md"),),
|
||||
)
|
||||
client = Mock()
|
||||
client.list_pages.return_value = [metadata]
|
||||
client.get_page_from_metadata.return_value = changed
|
||||
with patch("wiki_docs.ROOT", root):
|
||||
messages = sync_all(config, client)
|
||||
_metadata, body = parse_mirror(target.read_text(encoding="utf-8"))
|
||||
self.assertTrue(messages[0].startswith("已更新："))
|
||||
self.assertEqual(body, changed.text)
|
||||
client.get_page_from_metadata.assert_called_once_with(metadata, "Home")
|
||||
|
||||
@patch("wiki_docs.dirty_mirror_paths", return_value=[])
|
||||
def test_sync_does_not_write_partial_mirrors_when_later_read_fails(
|
||||
self, _dirty
|
||||
) -> None:
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
first_target = root / "docs" / "first.md"
|
||||
second_target = root / "docs" / "second.md"
|
||||
first_target.parent.mkdir(parents=True)
|
||||
first_original = render_mirror(self.page)
|
||||
first_target.write_text(first_original, encoding="utf-8")
|
||||
second_target.write_text(first_original, encoding="utf-8")
|
||||
config = Config(
|
||||
path=root / "wiki-docs.json",
|
||||
gitea_url="http://gitea.example",
|
||||
owner="o",
|
||||
repository="r",
|
||||
mappings=(
|
||||
Mapping("First", "docs/first.md"),
|
||||
Mapping("Second", "docs/second.md"),
|
||||
),
|
||||
)
|
||||
pages = [
|
||||
{
|
||||
"title": name,
|
||||
"sub_url": name,
|
||||
"last_commit": {"sha": revision},
|
||||
}
|
||||
for name, revision in (("First", "b" * 40), ("Second", "c" * 40))
|
||||
]
|
||||
changed = WikiPage(
|
||||
title="First",
|
||||
sub_url="First",
|
||||
text="# Changed\n",
|
||||
revision="b" * 40,
|
||||
html_url="http://gitea.example/o/r/wiki/First",
|
||||
)
|
||||
client = Mock()
|
||||
client.list_pages.return_value = pages
|
||||
client.get_page_from_metadata.side_effect = [
|
||||
changed,
|
||||
WikiDocsError("rate limited"),
|
||||
]
|
||||
with patch("wiki_docs.ROOT", root):
|
||||
with self.assertRaises(WikiDocsError):
|
||||
sync_all(config, client)
|
||||
self.assertEqual(first_target.read_text(encoding="utf-8"), first_original)
|
||||
|
||||
@patch("wiki_docs.dirty_mirror_paths", return_value=[])
|
||||
def test_sync_fetches_when_remote_revision_is_missing(self, _dirty) -> None:
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
target = root / "docs" / "README.md"
|
||||
target.parent.mkdir(parents=True)
|
||||
target.write_text(render_mirror(self.page), encoding="utf-8")
|
||||
metadata = {"title": "Home", "sub_url": "Home"}
|
||||
config = Config(
|
||||
path=root / "wiki-docs.json",
|
||||
gitea_url="http://gitea.example",
|
||||
owner="o",
|
||||
repository="r",
|
||||
mappings=(Mapping("Home", "docs/README.md"),),
|
||||
)
|
||||
client = Mock()
|
||||
client.list_pages.return_value = [metadata]
|
||||
client.get_page_from_metadata.return_value = self.page
|
||||
with patch("wiki_docs.ROOT", root):
|
||||
sync_all(config, client)
|
||||
client.get_page_from_metadata.assert_called_once_with(metadata, "Home")
|
||||
|
||||
def test_deep_check_fetches_unchanged_page_body(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
target = root / "docs" / "README.md"
|
||||
target.parent.mkdir(parents=True)
|
||||
target.write_text(render_mirror(self.page), encoding="utf-8")
|
||||
metadata = {
|
||||
"title": "Home",
|
||||
"sub_url": "Home",
|
||||
"last_commit": {"sha": self.page.revision},
|
||||
}
|
||||
config = Config(
|
||||
path=root / "wiki-docs.json",
|
||||
gitea_url="http://gitea.example",
|
||||
owner="o",
|
||||
repository="r",
|
||||
mappings=(Mapping("Home", "docs/README.md"),),
|
||||
)
|
||||
client = Mock()
|
||||
client.list_pages.return_value = [metadata]
|
||||
client.get_page_from_metadata.return_value = self.page
|
||||
with patch("wiki_docs.ROOT", root):
|
||||
sync_all(config, client, check=True, deep_check=True)
|
||||
client.list_pages.assert_called_once_with()
|
||||
client.get_page_from_metadata.assert_called_once_with(metadata, "Home")
|
||||
|
||||
@patch("harness.run_check", return_value=0)
|
||||
@patch("harness.sync_all", return_value=["已更新：docs/README.md"])
|
||||
@patch("harness.WikiClient")
|
||||
@patch("harness.load_config")
|
||||
def test_verify_reuses_one_deep_sync(
|
||||
self, load, client_class, sync, check
|
||||
) -> None:
|
||||
config = Mock()
|
||||
load.return_value = config
|
||||
result = run_sync(
|
||||
Namespace(verify=True, check=False, deep_check=False, config="config.json")
|
||||
)
|
||||
self.assertEqual(result, 0)
|
||||
sync.assert_called_once_with(
|
||||
config, client_class.return_value, check=False, deep_check=True
|
||||
)
|
||||
check.assert_called_once()
|
||||
|
||||
|
||||
class WikiClientTests(unittest.TestCase):
|
||||
@patch("wiki_docs.time.sleep")
|
||||
@patch("wiki_docs.urlopen")
|
||||
def test_get_retries_a_rate_limited_request(self, urlopen, sleep) -> None:
|
||||
config = Config(
|
||||
path=Path("wiki-docs.json"),
|
||||
gitea_url="http://gitea.example",
|
||||
owner="o",
|
||||
repository="r",
|
||||
mappings=(),
|
||||
)
|
||||
limited = HTTPError(
|
||||
"http://gitea.example/api/v1/repos/o/r/wiki/pages",
|
||||
429,
|
||||
"Too Many Requests",
|
||||
None,
|
||||
BytesIO(b"limited"),
|
||||
)
|
||||
success = MagicMock()
|
||||
success.__enter__.return_value.read.return_value = b"[]"
|
||||
urlopen.side_effect = [limited, success]
|
||||
|
||||
result = WikiClient(config, token="token")._request(
|
||||
"GET", "/repos/o/r/wiki/pages"
|
||||
)
|
||||
|
||||
self.assertEqual(result, [])
|
||||
self.assertEqual(urlopen.call_count, 2)
|
||||
sleep.assert_called_once_with(1.0)
|
||||
|
||||
def test_encoded_unicode_sub_url_is_not_double_encoded(self) -> None:
|
||||
config = Config(
|
||||
path=Path("wiki-docs.json"),
|
||||
@@ -323,7 +534,7 @@ class GovernancePolicyTests(unittest.TestCase):
|
||||
self.assertEqual(errors, [])
|
||||
|
||||
agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
|
||||
self.assertIn("Gitea 工单是单次任务", agents)
|
||||
self.assertIn("需要工单的任务以 Gitea 工单作为单次", agents)
|
||||
self.assertIn("标准流程不创建 Wiki 任务归档", agents)
|
||||
self.assertIn("Wiki 同步由长期事实变化触发，不由任务完成触发", agents)
|
||||
|
||||
@@ -340,6 +551,33 @@ class GovernancePolicyTests(unittest.TestCase):
|
||||
self.assertIn("### 线上原型审核与按需导出", workflow)
|
||||
self.assertIn("## Windows PowerShell 与 UTF-8", local_development)
|
||||
|
||||
def test_goauto_uses_lightweight_governance_and_explicit_authorization(self) -> None:
|
||||
agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
|
||||
profile = (ROOT / "docs" / "00-project-profile.md").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
workflow = (ROOT / "docs" / "01-workflow.md").read_text(encoding="utf-8")
|
||||
for text in (agents, profile, workflow):
|
||||
self.assertIn("轻量治理", text)
|
||||
for text in (agents, workflow):
|
||||
self.assertIn("明确授权后的执行", text)
|
||||
self.assertIn("不能单独构成人工授权", text)
|
||||
self.assertIn("不得仅因操作不可逆而重复询问或拒绝", text)
|
||||
self.assertIn("平台自身强制的审批", text)
|
||||
|
||||
def test_language_and_windows_command_policy_is_documented(self) -> None:
|
||||
agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
|
||||
workflow = (ROOT / "docs" / "01-workflow.md").read_text(encoding="utf-8")
|
||||
local_development = (
|
||||
ROOT / "docs" / "04-local-development-and-verification.md"
|
||||
).read_text(encoding="utf-8")
|
||||
for text in (agents, workflow):
|
||||
self.assertIn("默认使用中文", text)
|
||||
self.assertIn("日志和错误原文保持原样", text)
|
||||
self.assertIn("不得默认套用 Bash", agents)
|
||||
self.assertIn("### PowerShell 语法与外部命令", local_development)
|
||||
self.assertIn("rg -n -g '*.md'", local_development)
|
||||
|
||||
def test_deployment_template_is_required_and_mapped(self) -> None:
|
||||
path = "docs/templates/deployment.md"
|
||||
self.assertIn(path, harness.REQUIRED_FILES)
|
||||
|
||||
Reference in New Issue
Block a user