OPC/cmautobuy
2
0
Fork 0
Code Issues 114 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 初始化核心 Wiki 镜像 (#313)

Browse Source
This commit is contained in:
chengma
2026-08-26 16:45:54 +08:00
parent cad1908256
commit d130e2675e
12 changed files with 1112 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/00-project-profile.md
+92
View File
@@ -0,0 +1,92 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Project-Profile
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Project-Profile.-
wiki_revision: a8497a098e753dc0f50e2bbee31ad04b848d69d1
synchronized_at: 2026-08-26T08:42:33Z
<!-- gitea-wiki-mirror:end -->
# 项目档案
## 基本信息
| 项目 | 值 |
|---|---|
| 项目名 | cmautobuy |
| Gitea 仓库 | `OPC/cmautobuy` |
| 仓库地址 | https://git.ilapage.cn/OPC/cmautobuy |
| 工作区 | `D:/chengma/cmautobuy` |
| 主要语言 | Go、Python、HTML/CSS/JavaScript |
| 维护对象 | Admin 管理端、Client Windows 桌面端 |
| Wiki 主源启用日期 | 2026-08-26 |
## DevHarness 来源与基线
- 来源目录：`D:/OPC/dev_harness`
- 采用的完整提交：`0b6ec7675dfc2d930a30527eddac83f4302d0879`
- 基线提交时间：2026-08-26 16:11:48 +08:00
- 本次升级日期：2026-08-26
- 升级范围：Wiki 主源、Gitea 工单主源、在线回读门禁、设计证据双门禁、自然语言快捷指令、依赖并行规则、可选任务快照和严格检查。
- 保留范围：本项目五条产品红线、Admin/Client 子项目规则、Client API 契约、真实启动和验证命令、历史 `docs/task`。
后续再升级时必须先记录新的完整上游提交、比较差异、建工单并增量迁移；不能用“最新版”代替可复现提交。
## 子项目与交付单元
| 交付单元 | 目录 | 技术栈 | 职责 |
|---|---|---|---|
| Admin | `admin/` | Go 1.23、Gin、html/template、MySQL 8.4 | 管理商品、顺运宝、任务、用户、客户端、AI 配置和档口入库码 |
| Client | `client/` | Python 3.10、PyQt5、uiautomator2、SQLite | 在 Windows 连接 Android，领取并执行 PDD 采集和真实下单（不支付）任务 |
| 共享契约 | `docs/client/04-admin-api-contract.md` 的 Wiki 镜像 | HTTP JSON | 登记、领取、提交结果、提交失败及运行时规格解析 |
两个子项目技术栈和线程模型完全不同。跨接口修改在同一个工单里同步两边契约与验证。
## 技术栈与运行环境
- Client 固定 PyQt5，不得改用其他 Qt 绑定。
- Admin 固定 Go 1.23.0、Gin v1.11.0、MySQL 8.4；生产运行时不使用 SQLite。
- Admin 页面使用服务端模板和少量原生 JavaScript，不引入 React/Vue/npm 构建链。
- Client 使用 `QObject + moveToThread` 执行耗时任务，QWidget 只在主线程访问。
- 生产 Admin 为 Linux 常驻服务，前置 nginx，数据位于 MySQL；详细信息见后续的 `Deployment-and-Operations` 页面。
## 阅读入口
1. [文档首页](Home)
2. [产品需求总览](Product-Requirements-Overview)
3. [架构与代码地图](Architecture-and-Code-Map)
4. [业务规则与术语](Business-Rules-and-Glossary)
5. 修改具体子项目前读取仓库中的对应 `AGENTS.md`
6. 按任务进入 Admin 或 Client 详细页面
## 常用命令
从仓库根目录：
```powershell
git status --short
python dev_scripts/harness.py check --strict
python dev_scripts/harness.py sync --verify
```
Admin 从 `admin/`：
```powershell
$env:GOTOOLCHAIN="go1.23.0"
go build ./...
go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN
```
Client 从 `client/`：
```powershell
C:/Python310/python.exe -m unittest discover -s test -v
```
## 环境、配置与凭据
- 真实 `admin/config.yaml`、AI API key、数据库密码、Cookie 和 Token 不进入 Git、Wiki、工单或日志。
- Admin 生产凭据来自权限受控的环境文件；Windows 本地可使用被 Git 忽略的 `admin/config.yaml`。
- Wiki 同步使用环境变量 `GITEA_URL`、`GITEA_TOKEN`；工具报错不得打印 Token。
- Client 软件更新公开引导默认密码 `chengma` 是唯一允许写入源码和文档的例外。
- 个人数据和无障碍 XML 原文仅保存在本机非 Git 目录，对外证据必须脱敏。
docs/01-workflow.md
+348
View File
@@ -0,0 +1,348 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Development-Workflow
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Development-Workflow.-
wiki_revision: 7154bfff323bc66a4f66725ffdbc823046ccabee
synchronized_at: 2026-08-26T08:42:36Z
<!-- gitea-wiki-mirror:end -->
# 开发工作流
## 事实来源边界
- Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
- Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。
- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
- 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。
## Gitea 交互与工单最小读取
- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
- 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。
## 新项目 Wiki 初始化门禁
本项目接入 DevHarness 后；从此仓库再创建新项目时，本地 `docs/` 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环：
1. 先创建 Gitea 远端仓库并启用 Wiki，再把 `wiki-docs.json` 指向该仓库。
2. 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
3. 查询线上页面列表；没有 `Home` 时先创建 `Home`，回读正文并记录 revision，然后再创建或更新其他核心映射页面。
4. 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地 `docs/` 文件替代这项证据。
5. 运行 `python dev_scripts/harness.py sync --verify`。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。
Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。
## 工单与设计证据双门禁
开始正式实现前依次判断“是否需要工单”和“需要什么设计证据”。原型确认不能代替方案、工单、安全检查或技术验证；工单存在也不能绕过原型确认。
### 先判断是否需要工单
只有纯界面显示文案同时满足以下全部条件时，才可以免工单、免原型：
- 只修改用户看到的组件显示名称、按钮文字、标题、提示语或其他文案；
- 不改变业务含义、操作流程、权限、状态、接口、数据和验收结果；
- 不涉及法律条款、安全提示、支付、金额、单位或其他高风险含义；
- 不修改国际化键、代码组件名、类名、变量、API 字段、数据库字段或其他程序标识符；
- 不造成明显布局、截断、换行、可访问性或支持平台问题；
- 有任何不确定时不使用豁免。
豁免修改只执行与受影响界面相称的最小检查，确认文字正确且没有明显布局或可访问性问题，然后停止。只要任一条件不满足，或涉及用户行为、样式布局、交互和导航，就建立单元任务工单。
### 再判断设计证据
| 修改类型 | 最低设计证据 | 正式编码门禁 |
|---|---|---|
| 纯显示文案且满足全部豁免条件 | 无原型 | 完成最小界面检查即可 |
| 现有界面的小范围样式或布局调整 | 标注截图或低保真线框图；没有设计不确定性时说明复用的现有规范 | 工单确认设计证据后编码 |
| 新组件但复用现有设计体系 | 组件状态、错误和边界说明；按需提供低保真图 | 工单确认状态和复用边界后编码 |
| 新页面、独立用户功能、重大交互或导航变化 | Quant-UX 或其他合适工具制作的可审阅原型 | 用户确认原型和文字需求后才能编写生产代码 |
| 后端、接口、数据处理或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后编码，不制作无意义的 UI 原型 |
| 恢复既有确认行为的 Bug | 原设计、已确认截图、复现步骤或现有验收证据 | 确认是恢复而不是改变行为后修复 |
采用最低成本、足以让用户确认的证据，不为了形式制作高保真原型。草稿原型可以用于需求讨论；草稿需要写入 Git/Wiki、多人协作或单独实施时，应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。
### 线上原型审核与按需导出
新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后，默认直接通过线上原型审核，不要求每次导出本地 HTML：
- 可编辑设计源保存在 Quant-UX 或原设计工具；工单和 Wiki 只保存链接、版本与确认记录，不复制为第二份可编辑事实来源。
- 线上链接必须能被确认人访问，并能通过版本、revision、复制版本或确认日期识别本次审核对象；无法访问或无法区分版本时停止审核，等待用户确认等效方案。
- 提交审核前检查主要页面、流程、状态和交互可访问，并删除令牌、真实账号、个人信息和生产数据。
- 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，更新线上原型并重新确认；不得用旧确认覆盖新版本。
- 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 仍只使用双门禁表规定的最低证据，不强制建立完整线上原型。
只有用户明确发出 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线交付时，才导出本地 HTML：
- 指定工单的快照放入 `prototypes/<工单号>/<版本>/index.html`；全部导出时也按工单和版本分目录，先在工单明确导出范围。
- 图片、样式、脚本和字体使用版本目录内的相对路径；需要网络资源才能显示时不得标记为可离线浏览。
- 已确认的本地快照不得原位覆盖；新版本使用新目录，已有快照继续作为历史审核证据。
- 导出后检查入口、主要交互和资源完整性；浏览器限制直接打开时，在工单记录最小本地静态服务命令和访问地址，不新增项目专用服务脚本。
- 导出指令只生成或更新请求范围内的快照并报告结果，不自动提交；用户未明确要求时不得顺带导出其他原型。
- 设计工具无法生成用户要求的可用 HTML 时，在工单记录限制并停止该导出或离线交付，等待用户确认等效方案；线上原型仍可访问且版本明确时，不因此阻塞线上审核。
### 记录和重新确认
需要设计证据的工单必须记录：
- 原型或设计的线上链接、对应事实来源，以及链接可访问性；
- 版本、revision、复制版本或确认日期，以及审核版本的识别方式；
- 状态：无、草稿、已确认或已废弃；
- 只有显式导出时才记录本地 HTML 路径、版本和资源检查结果；
- 确认人和确认时间；
- 本次确认覆盖的页面、组件、流程和边界；
- 不需要 UI 原型时采用的技术设计，或无需任何原型的原因。
页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新原型或文字需求并重新确认，再继续正式编码。只读技术检查可以在确认前进行；确需可行性代码验证时，必须由用户明确同意，隔离为不可进入生产的技术验证，不得悄悄扩展成正式实现。
## 一次任务怎样完成
### 1. 讨论
用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。
### 2. 建单
方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。
新产品或较大版本先建立 Epic，再建立 MVP：
```text
[Epic] 产品或长期目标
└── [MVP] 第一个可交付版本
├── #101 单元任务
├── #102 单元任务
└── #103 单元任务
```
每个单元任务都应目标单一，能够独立测试、提交和回退。
#### 依赖与并行
建立新工单不要求其他工单已经完成，也不按工单编号限制实施顺序。每个单元任务必须声明：
- 前置工单，没有时填写“无”；
- 是否允许与未完成的前置工单并行；
- 判断可以或不可以并行的原因。
开始修改前，Agent 检查工单声明的前置工单：
- 没有前置工单，或前置工单已经完成，可以进入“进行中”；
- 前置工单未完成且存在实际依赖时，不得开始实施，工单保持“待实施”；
- 与前置工单没有实施冲突、允许并行时，可以进入“进行中”，但必须在工单写明原因；
- 已经进入实施后出现计划外、当前无法解除的问题，才使用“阻塞”。
依赖不改变单元任务边界。依赖满足后，该任务仍须拥有独立的范围、提交、测试和回退方式。
### 3. 实施
Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。
重要进度及时写回工单：
- 已确认的根因；
- 方案或范围变化；
- 测试结果；
- 阻塞和未验证内容；
- Git 提交哈希；
- 相关 Wiki 页面及 revision。
工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和长期文档影响，保留可追溯时间线，不在 Wiki 重抄同一份任务结果。
只有长期事实发生变化时才执行核心文档闭环：
```text
修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像
```
没有长期文档影响时，在工单写明原因并跳过 Wiki 更新和核心镜像同步；默认任务流程不创建任务归档。长期文档仍不得先编辑本地镜像再反向覆盖 Wiki。
### 4. 待验收
实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。
### 5. 待验收和关闭
实现、必要测试和提交完成后，在工单追加一条最终证据评论并保持“待验收”。评论至少记录最终差异、测试结果、未验证内容、提交哈希，以及长期 Wiki 页面和 revision，或“无长期文档影响”及原因。
用户明确验收通过后：
1. 在工单追加验收时间和结论，不重复抄写已有测试与提交证据；
2. 关闭单元工单并勾选所属 MVP/Epic 子任务；
3. 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki；
4. 默认不创建或导出任务归档。
任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行：
```powershell
python dev_scripts/harness.py archive 123 "修复登录超时"
python dev_scripts/harness.py export # 增量导出已有归档
python dev_scripts/harness.py export --all # 全量导出已有归档
```
可选归档不得成为第二个日常维护入口；创建时以工单中的最终证据为来源，并记录工单链接。既有 Wiki 归档和 `docs/task/` 快照不自动删除、重命名或补齐。
## 文档同步规则
- 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。
- 可选任务归档不逐页登记映射；显式执行归档导出时，工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。
- 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。
- 镜像头必须记录页面名、页面地址、revision 和同步时间。
- 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
- 核心同步的 `--check` 只检查核心镜像，不要求线上任务归档全部存在于本地。
- 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。
- 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
- Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
- 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。
## 面向初级维护者的修改边界
| 风险 | 示例 | 处理方式 |
|---|---|---|
| 低 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下理解、修改和验证 |
| 中 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员检查差异并执行验证 |
| 高 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |
风险由影响范围决定，不按代码行数判断。
## 每个任务的文档影响
单元任务必须明确选择：
- 不影响长期文档，并说明原因；
- 更新项目档案或运行验证；
- 更新架构与代码地图；
- 更新业务规则与术语；
- 更新常见修改或故障排查；
- 新增或调整其他 Wiki 页面。
以下变化必须更新相关 Wiki：
- 启动、测试、部署或排错命令变化；
- 模块入口、目录职责或主要调用路径变化；
- 配置项、API、数据结构或状态变化；
- 业务规则、安全边界或权限变化；
- 日志位置、错误定位或常见处理方式变化。
部署命令的落点：有常驻服务的项目更新自己的 `Deployment-and-Operations` 页面（由[部署文档模板](Deployment-Template.-)复制建立）；没有常驻服务的项目在工单记录“无部署文档影响”及原因，不要创建空的部署页。
普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。
## 需求记录与流转
聊天用于分析和确认，不是正式需求的长期事实来源。创建单元任务工单时，Agent 应记录：
- 原始需求的来源和提出时间；
- 能表达用户目的、使用场景和限制的少量关键原话；
- 整理后的目标、非目标、确认方案、验收标准和文档影响；
- 实施期间影响范围、接口、数据、风险或验收的需求变化，以及变化原因和用户确认。
只摘录完成追踪所需的内容，不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据。包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。
需求按以下边界流转：
| 内容 | 事实来源 | 本地镜像 |
|---|---|---|
| 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 |
| 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 |
| 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` |
| 完成后的实现、验证、遗留问题和验收 | Gitea 单元任务工单正文与评论 | 无；用户明确要求时可创建专项 Wiki 快照 |
任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。
## 稳定文档与可选历史快照
- Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
- 工单正文和评论解释某次为什么修改、实际改了什么、如何验证以及怎样验收。
- 新人先读稳定主题页，只有追查历史原因时才读工单；可选 Wiki 快照和本地任务快照只是专项或历史兼容资料，不是默认事实来源。
- 任务产生的长期结论必须合并到对应主题页，不能只留在工单或可选快照。
## 效率与范围控制
本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。
### 严格控制范围
- 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
- 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
- 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
- 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。
### 渐进执行和修复
- 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
- 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
- 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
- 不在真实证据出现前堆叠与已知风险无关的预防性检查。
- 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。
### 复用已验证事实
- 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
- 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
- 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
- Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。
### 明确停止条件
- 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
- 未影响当前验收的相邻问题只提示或建单，不顺手处理。
## 自然语言快捷指令
快捷指令是对本工作流的自然语言别名，供 Claude Code、Codex 和维护者使用。它们只减少重复描述，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收。
| 指令 | 执行动作 | 停止位置 |
|---|---|---|
| `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 |
| `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 |
| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交并回写证据；仅有长期文档影响时更新 Wiki 和镜像 | 工单保持“待验收” |
| `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” |
| `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 |
| `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 |
| `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 |
| `导出原型 #N` | 人工触发导出指定工单已确认的原型版本；按工单和版本写入 `prototypes/` | 显示路径和检查结果；不扩展范围、不自动提交 |
| `导出全部原型` | 人工触发导出当前项目明确范围内的全部已确认原型 | 显示导出范围和结果；不自动提交 |
| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 |
| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 |
| `#N 验收通过` | 在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档 | 工单“已完成”并关闭 |
补充边界：
- 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。
- 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
- `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
- `导出原型 #N` 和 `导出全部原型` 必须由用户明确提出或项目专用规则明确要求；其他指令不隐式导出原型。
- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。
- Gitea 工单是单次任务唯一事实来源，不导出全文；`docs/task/` 只保存人工明确要求的专项或历史兼容快照。
## 什么时候重新确认方案
以下变化必须先更新工单，再由用户确认：
- 交付结果或用户操作发生变化；
- 增加或删除接口、数据库字段或迁移；
- 安全边界、权限或不可逆操作发生变化；
- 原方案不可行，需要更换主要技术路线；
- 任务范围明显扩大；
- Wiki 页面删除、重命名或事实源边界改变。
普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。
## 工单、Wiki 与 Git 分别写什么
| 信息 | Gitea 工单 | Gitea Wiki | Git / `docs` 镜像 |
|---|---:|---:|---:|
| 讨论过程和临时方案 | 是 | 否 | 否 |
| 实施进度和阻塞 | 是 | 否 | 否 |
| 长期有效的最终方案 | 链接 | 是 | 镜像 |
| 测试结果与未验证内容 | 是 | 否 | 否 |
| 提交哈希和验收结论 | 是 | 否 | 否 |
| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 |
| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |
docs/02-architecture-and-code-map.md
+69
View File
@@ -0,0 +1,69 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Architecture-and-Code-Map.-
wiki_revision: 85497cc74dcd6f45d81d2a2806c5425b625f9c2d
synchronized_at: 2026-08-26T08:42:40Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
## 项目定位
cmautobuy 把采购员在 Admin 上的商品、规格和任务管理，与 Client 在 Android PDD App 上的采集和真实下单（不支付）串成一个可追溯闭环。Admin 是调度器和业务数据主库，Client 是设备执行器。
## 代码地图
| 位置 | 作用 | 修改前先读 |
|---|---|---|
| `admin/main.go`、`admin/internal/app/` | Admin 启动和依赖装配 | `admin/AGENTS.md` |
| `admin/internal/handler/` | Web/API 请求解析与响应 | Admin 接口、界面文档 |
| `admin/internal/service/` | 导入、同步、匹配、任务等业务逻辑 | 对应需求和数据模型 |
| `admin/internal/repository/` | MySQL/迁移数据访问 | Admin 数据模型 |
| `admin/templates/`、`admin/static/` | 服务端页面和静态资源 | Admin UI 规范 |
| `client/src/ui_main.py`、`*_ui.py`、`*_ui_event.py` | Client 窗口、页面和事件装配 | `client/AGENTS.md` |
| `client/src/*gateway*.py` | Admin HTTP 边界 | Client API 契约 |
| `client/src/*repository*.py` | Client SQLite 和 Outbox | Client 数据模型 |
| `client/src/pdd_*adapter.py`、`select_color_size.py` | Android 页面识别、规格选择和采购执行 | Client 质量与安全 |
| `dev_scripts/` | Wiki/Harness 与发布辅助 | 开发工作流 |
| `docs/task/` | 2026-08-26 前历史归档及按需快照 | 默认只读 |
查代码符号时优先使用项目代码知识图谱；不足时再使用 `rg` 搜索字面量、配置和非代码文件。
## 两条主要执行路径
### 商品采集
```text
Admin 创建采集任务
→ Client 登记并领取
→ Android 打开 PDD 商品页并采集标题/店铺/颜色/尺码/价格
→ Client 先写 SQLite 与 Outbox
→ Client 提交 Admin
→ Admin 幂等落库并更新任务与关联商品
```
### 真实采购（不支付）
```text
Admin 创建采购任务并指定可见 Client
→ Client 只有在身份、设备、live 执行器就绪时领取
→ 复核商品、颜色、尺码、数量、总价上限
→ 不可逆前写 task_runs 标记
→ PDD 创建未付款订单
→ 只读核对订单编号和下单时间
→ 提交 Admin，等待人工审核和付款
```
规格无法确定时允许 Client 向 Admin 提交当前页面候选，Admin 用确定性规则或 AI 返回建议；Client 仍必须在页面上复核后才能继续。
## 不可破坏的边界
- 根 `AGENTS.md` 的五条红线不能被文档迁移或重构削弱。
- Admin 只调度，Client 只执行；Client 不在任务中途查询 Admin 状态。
- Client API 契约以 Client 侧文档为唯一事实来源。
- Handler 不写业务逻辑和 SQL；Repository 才能写业务 SQL。
- Qt 主线程不执行 HTTP、ADB、uiautomator2、休眠或大文件操作。
- 任务进入 `irreversible_action_at` 后只准核单，绝不重新下单。
- 金额用整数分，时间用带时区 ISO 8601，结果提交必须幂等。
- Wiki 是长期文档主源，本地 `docs/` 只是带 revision 的版本镜像。
docs/03-business-rules-and-glossary.md
+62
View File
@@ -0,0 +1,62 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Business-Rules-and-Glossary
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Business-Rules-and-Glossary.-
wiki_revision: 86e4b2ebb7c1d1623d6a839a5e61cccd00682bc6
synchronized_at: 2026-08-26T08:42:44Z
<!-- gitea-wiki-mirror:end -->
# 业务规则与术语
## 核心术语
| 术语 | 含义 |
|---|---|
| Admin | 采购员和管理员使用的 Web 管理端，也是任务调度器和业务主库 |
| Client | Windows 桌面执行端，连接一台 Android 设备操作 PDD App |
| 蝦皮商品 | 上游商品主数据，包含商品 ID、店铺、图片和规格 |
| PDD 商品 | 采购来源商品，采集后包含店铺、价格和可购买规格 |
| 顺运宝 / SYB | 货运单来源系统，提供订单商品、蝦皮信息和规格 |
| 采集任务 | 让 Client 获取 PDD 商品数据的任务，编号 `cjN` |
| 采购任务 | 让 Client 创建真实未付款 PDD 订单的任务，编号 `cgN` |
| Outbox | Client 先把结果写入本地，再可靠提交 Admin 的队列 |
| 幂等 | 同一个请求重复提交不会产生重复业务结果 |
| 不可逆阶段 | 已经执行可能创建订单的动作，`irreversible_action_at` 有值 |
| Wiki 镜像 | 从在线 Wiki 单向导出的本地 Markdown，含页面名和 revision |
详细业务词分别见 Admin 与 Client 术语页面。
## 工单状态
- 待确认：方案或边界还需用户确认。
- 待实施：方案已确认，尚未开始。
- 进行中：正在按工单实施。
- 阻塞：已有明确外部阻塞，并在工单记录原因和恢复条件。
- 待验收：实现、测试和提交已完成，等待用户验收。
- 已完成：用户明确验收通过后关闭。
## 稳定业务规则
1. Qt 绑定固定 PyQt5。
2. Admin 新建采购任务固定为真实下单（不支付）；不增加 Client 手工真实采购开关。
3. 不自动注册登录，不自动付款。
4. 除公开默认值 `chengma` 外，凭据不得进入 Git、Wiki、工单、数据库或日志。
5. 进入不可逆阶段后只准核对订单，绝不重新下单。
6. Admin 是调度器，Client 是执行器；任务领取后 Client 不查询 Admin 状态。
7. Admin 无条件接受曾被派发 Client 的结果，即使任务随后取消或重派。
8. PDD/目录导入使用 upsert，不先清空主表；原始规格文本保留。
9. 生产数据库为 MySQL 8.4；迁移版本只追加，已发布版本不得改写。
10. 金额使用整数分，时间在库中用 UTC、接口使用带时区 ISO 8601。
11. 第三方系统的只读同步和回写必须可审计、可重试并有幂等保护。
12. 原始无障碍 XML 可用于本地诊断，但不得提交或对外原样展示。
## 新项目需要补充什么
这部分保留为以后拆分新交付单元时的检查表：
- 新交付单元的目录、技术栈、启动命令和责任边界。
- 与 Admin/Client 的接口唯一事实来源。
- 新状态、金额单位、时间语义和幂等键。
- 是否触及采购、付款、登录、凭据或个人数据红线。
- 面向谁的长期文档和部署运维入口。
- 可复制的测试命令和明确的未验证部分。
docs/04-local-development-and-verification.md
+89
View File
@@ -0,0 +1,89 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Local-Development-and-Verification
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Local-Development-and-Verification.-
wiki_revision: 74462601132f6bd4d9dd1c60a597cedee9462e86
synchronized_at: 2026-08-26T08:42:48Z
<!-- gitea-wiki-mirror:end -->
# 本地开发与验证
## 环境要求
| 部分 | 固定环境 |
|---|---|
| Admin | Go 1.23.0、MySQL 8.4 |
| Client | Windows、Python 3.10、PyQt5 5.15.11、uiautomator2 3.2.5 |
| Wiki/Harness | Python 3.10，使用标准库 |
| Android | 已安装 PDD App；真实自动化只在明确授权的真机验证中运行 |
真实凭据只从被忽略的配置或安全环境读取，不复制到命令、文档和工单。
## 第一次运行
### Admin
从仓库根目录可运行 `run_admin.bat`。需要手动开发时：
```powershell
cd D:\chengma\cmautobuy\admin
go mod download
$env:GOTOOLCHAIN="go1.23.0"
go run .
```
预期日志显示数据目录和监听地址。连接线上 MySQL 会产生真实数据读取/写入，普通测试应使用名称以 `_test` 结尾的独立库。
### Client
```powershell
cd D:\chengma\cmautobuy\client
C:/Python310/python.exe -m pip install -r requirements.txt
C:/Python310/python.exe buyer_main.py
```
只打开窗口不会自动连接设备或下单；点击领取和采购相关命令会产生真实外部操作。
## 常用调试方式
- 先运行最小测试，再扩大到子项目完整测试。
- Admin handler 错误先看 HTTP 状态、稳定错误码和服务日志，再查 service/repository。
- Client 自动化错误优先使用脱敏 XML 固件和截图复现，避免反复真机下单。
- 修改 Wiki 后只从在线页面同步：
```powershell
python dev_scripts/harness.py sync --verify
```
- 查看工作区时使用 `git status --short`，只暂存当前工单文件。
## 完成修改前
Admin：
```powershell
cd D:\chengma\cmautobuy\admin
$env:GOTOOLCHAIN="go1.23.0"
go vet ./...
go build ./...
go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN
```
Client：
```powershell
cd D:\chengma\cmautobuy\client
C:/Python310/python.exe -m unittest discover -s test -v
```
工作流和 Wiki：
```powershell
cd D:\chengma\cmautobuy
python -m unittest discover -s tests -v
python dev_scripts/harness.py check --strict
python dev_scripts/harness.py sync --check
```
涉及真机、生产 MySQL、外部 ERP、部署或真实下单时，工单必须单独写明是否验证；没有执行就明确记录“未验证”，不能用单元测试代替。
docs/05-common-changes.md
+46
View File
@@ -0,0 +1,46 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Common-Changes
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Common-Changes.-
wiki_revision: 6ea470c4bc0b45de29973b0e03b2426a4a85a02a
synchronized_at: 2026-08-26T08:42:54Z
<!-- gitea-wiki-mirror:end -->
# 常见修改
## 风险分级
| 风险 | 示例 | 最小要求 |
|---|---|---|
| 低 | 错别字、注释、纯内部变量名 | 不改变行为时可小改直通 |
| 中 | 页面字段、筛选、普通接口行为 | 工单、对应子项目规则、单元测试 |
| 高 | 数据库迁移、Client API、线程、采购、下单、幂等、崩溃恢复 | 工单、设计证据、回退、专门验证；条件不全时停止 |
## 修改 Wiki 文案
1. 找到在线 Wiki 页面并确认当前 revision。
2. 修改在线页，写清提交说明。
3. 回读页面和新 revision。
4. 从仓库根目录运行 `python dev_scripts/harness.py sync --verify`。
5. 只提交对应镜像文件；不要直接编辑镜像正文。
长期事实没有变化时只更新工单，不修改 Wiki。
## 调整 Harness 检查
- 先在工单说明为什么规则变化，不把项目事实硬编码成 DevHarness 模板事实。
- 同步修改 `dev_scripts/harness.py`、`wiki-docs.json` 和对应 `tests/`。
- 映射只允许 `docs/` 下 Markdown，不能映射凭据、原始数据、日志和历史动态目录。
- 先运行工具单测，再运行严格检查和 Wiki 一致性校验。
## 看懂 Agent 的修改
交付时按这个顺序核对：
1. 工单目标、非目标和已确认设计证据。
2. `git diff --stat` 与实际改动文件是否一致。
3. 是否碰到根红线或跨子项目契约。
4. 测试命令的实际结果和“未验证部分”。
5. 提交是否只含当前工单文件。
6. Wiki 是否只在长期事实变化时更新，并带可回读 revision。
7. 用户验收前工单是否仍保持打开。
docs/06-troubleshooting.md
+40
View File
@@ -0,0 +1,40 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Troubleshooting
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Troubleshooting
wiki_revision: 84518342612d53e2e3919c2f961b4f7eb5910ece
synchronized_at: 2026-08-26T08:42:57Z
<!-- gitea-wiki-mirror:end -->
# 故障排查
## 排查顺序
1. 先保存完整错误时间、稳定错误码、任务号和操作步骤；凭据和个人数据脱敏。
2. 读取当前工单的状态、最新评论和首个未完成步骤，不重复已经验证的事实。
3. 确认错误属于 Admin、Client、Android 页面、MySQL、顺运宝、AI 服务还是 Wiki/Gitea。
4. 从最小只读检查开始：配置名称是否存在、进程是否运行、网络端口是否可达、数据状态是否符合前置条件。
5. 用代码知识图谱定位函数和调用链；错误文字、配置和脚本再用 `rg`。
6. 复现时优先独立测试库、脱敏固件和只读接口；不要用真实下单当普通诊断。
7. 找到根因后先更新工单，再按已确认范围修复并运行回归。
常见入口：
- Admin 启动/数据库错误：Admin 上手指南、质量安全、部署运维。
- Client 页面识别/规格选择：Client 架构、质量安全、脱敏 XML 固件。
- Client–Admin 404/422/幂等错误：Client API 契约。
- Wiki 镜像错误：检查在线页 revision、工作区脏文件和 `wiki-docs.json` 映射。
## 必须停止的情况
- 需要突破根 `AGENTS.md` 任一产品红线。
- 目标数据、环境或删除范围不明确。
- 工单、设计证据或用户确认缺失。
- 需要生产凭据但安全来源不可用。
- 采购任务已经进入不可逆阶段，却有人要求再次下单。
- 页面、规格、价格、数量、订单结果或候选不唯一。
- 数据库迁移自检不通过，或目标库可能不是测试库。
- Wiki 页面无法在线回读 revision，却准备把本地文件当成已同步。
- 工作区存在会被覆盖的无关修改。
停止时要把已确认事实、阻塞点、已尝试的安全检查和恢复条件写回工单。
docs/09-product-requirements-overview.md
+80
View File
@@ -0,0 +1,80 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Product-Requirements-Overview
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Product-Requirements-Overview.-
wiki_revision: c8b1e480eebca6b9f65f652a4469bb84f64143b9
synchronized_at: 2026-08-26T08:43:00Z
<!-- gitea-wiki-mirror:end -->
# 产品需求总览
## 本页用途
本页提供稳定产品目标、当前主线和需求入口，不复制单元工单正文。具体范围变化、实现记录、测试和验收仍以 Gitea 工单为准。
## 事实来源边界
- 产品主线和长期边界：本页及 Admin/Client 需求页面。
- 单次需求与状态：Gitea 工单。
- 产品红线和 Agent 行为：仓库 `AGENTS.md`。
- Client–Admin 接口：Client 侧契约。
- 已实现行为：代码、测试和与版本绑定的 Wiki 镜像。
## 当前需求索引
| 层级 | 工单 | 状态 |
|---|---|---|
| Epic | [#310 cmautobuy 接入最新版 DevHarness 工作流](https://git.ilapage.cn/OPC/cmautobuy/issues/310) | 进行中 |
| MVP | [#311 Wiki 主源与 DevHarness 新工作流切换](https://git.ilapage.cn/OPC/cmautobuy/issues/311) | 进行中 |
| 单元任务 | #312～#317 | 以各工单当前状态为准 |
产品业务主线：
1. 汇集蝦皮、PDD、顺运宝和第三方目录数据。
2. 建立蝦皮商品与 PDD 商品及颜色映射。
3. 由 Client 采集 PDD 当前可购买规格和价格。
4. 把顺运宝商品规格解析成采购规格，必要时使用 AI 辅助并保留人工复核。
5. 创建真实采购任务，在 PDD 生成未付款订单。
6. 回传订单信息，等待人工审核和付款。
7. 使用档口入库码匹配并安全回写顺运宝。
## 登记规则
- 新需求先判断是否改变行为；改变行为必须有 Gitea 单元工单。
- 工单记录原始来源、边界、设计证据、依赖、验证和文档影响。
- 长期事实确实变化才更新本页；短期进度只更新工单。
- 父工单只维护子任务索引和集成状态，不复制单元工单全文。
## 原型与设计资产
### 原型门禁
新页面、独立用户功能、重大交互或导航变化必须先有用户可审核的交互原型。小范围 UI 至少提供标注截图或低保真证据；非 UI 变更提供架构、API、数据、状态或流程设计。
### 线上原型与按需 HTML 快照
默认通过 Quant-UX 或其他设计工具的在线链接审核。只有用户明确要求 `导出原型 #N`、`导出全部原型`，或项目规则明确要求离线交付时，才导出到 `prototypes/<工单号>/<版本>/index.html`。已确认快照不得原位覆盖。
### 原型确认记录
确认记录写入对应工单，至少包含链接、可识别的版本/revision、确认人、时间和覆盖范围。设计变化影响已确认结果时，先更新工单和证据，再重新让用户确认。
## 状态规则
需求使用待确认、待实施、进行中、阻塞、待验收、已完成。用户没有明确验收通过前不得关闭工单；Epic 和 MVP 只在全部范围完成集成验收后关闭。
## 更新时机
- 产品目标、长期范围、主流程或安全边界变化。
- 新增或结束一个 Epic/MVP。
- 设计资产入口或事实来源规则变化。
- 不因单个工单的普通进度反复改写本页。
## 最小验收清单
- [ ] 需求可追溯到工单。
- [ ] 目标、非目标、依赖和验收标准明确。
- [ ] 所需设计证据已确认。
- [ ] 根红线和 Client 契约未削弱。
- [ ] 长期事实与 Wiki 页面一致。
- [ ] 未验证部分已明确记录。
docs/README.md
+60 -122
View File
@@ -1,137 +1,75 @@
# 项目文档索引
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Home
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Home
wiki_revision: 2b8bbc1cf2d91c7a2c5e2eb7dcb183e48cc8469c
synchronized_at: 2026-08-26T08:42:31Z
<!-- gitea-wiki-mirror:end -->
本目录保存项目级文档。长期稳定的基线文档按子项目放在 `docs/client` 和 `docs/admin`，
实施过程和完成记录放在 `docs/task`，两者不得混用。
# cmautobuy 文档首页
## 项目由两部分组成
cmautobuy 由两个交付单元组成：Admin 是 Go Web 管理端，Client 是 Windows + Android 自动化执行端。两个子项目技术栈不同，但通过 Client 侧 API 契约协作。
| 子项目 | 是什么 | 技术栈 | 规则文件 |
|---|---|---|---|
| **Client** | Windows 桌面客户端，控制安卓设备在拼多多采集和下单 | Python 3.10 + PyQt5 | [client/AGENTS.md](../client/AGENTS.md) |
| **Admin** | 本地 Web 管理端，管理蝦皮商品、PDD 商品、货运单、采集采购和客户端 | Go + Gin + HTML 模板 | [admin/AGENTS.md](../admin/AGENTS.md) |
## 第一次阅读
两者通过三个 HTTP 接口交互，契约以
[Client 侧的接口契约](client/04-admin-api-contract.md) 为准。
- 第一次接手项目：先读 [项目档案](Project-Profile) 和对应子项目上手指南。
- 修改 Admin：先读仓库 `admin/AGENTS.md`，再按任务进入 [Admin 上手指南](Admin-Getting-Started)。
- 修改 Client：先读仓库 `client/AGENTS.md`，再按任务进入 [Client 上手指南](Client-Getting-Started)。
- 修改两边接口：以 [Client–Admin API 契约](Client-Admin-API-Contract) 为唯一事实来源。
- 了解完整业务目标：读 [产品需求总览](Product-Requirements-Overview)。
> **两个子项目技术栈完全不同，规则不通用。** 别拿 Client 的经验套 Admin，反之亦然。
## 五分钟开始
## 新人从这里开始
从仓库根目录执行：
| 我要做 | 先读 |
```powershell
git status --short
python dev_scripts/harness.py check --strict
```
Admin 的常用验证从 `admin/` 执行：
```powershell
$env:GOTOOLCHAIN="go1.23.0"
go build ./...
go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN
```
Client 的普通离线验证从 `client/` 执行；不要把真实采购当冒烟测试：
```powershell
C:/Python310/python.exe -m unittest discover -s test -v
```
## 简单修改从哪里开始
| 要做的事 | 先读 |
|---|---|
| 上手 Client | [Client 上手指南](client/00-getting-started.md) + [Client 术语表](client/00-glossary.md) |
| 上手 Admin | [Admin 上手指南](admin/00-getting-started.md) + [Admin 术语表](admin/00-glossary.md) |
| 搞清楚整条业务链路 | [Admin 需求](admin/01-requirements.md) §3 |
| 找代码入口和调用边界 | [架构与代码地图](Architecture-and-Code-Map) |
| 查业务术语和红线 | [业务规则与术语](Business-Rules-and-Glossary) |
| 本地启动和验证 | [本地开发与验证](Local-Development-and-Verification) |
| 常见改动的最小路径 | [常见修改](Common-Changes) |
| 分析报错 | [故障排查](Troubleshooting) |
| 建工单、实施、验收 | [开发工作流](Development-Workflow) |
| 写面向采购员或运维的文档 | [交付文档指南](Delivery-Documentation-Guide) |
## 按任务找文档
## 详细文档
**不用通读全部文档**，按你要做的事挑：
Admin 与 Client 的详细长期文档按子项目分别维护。页面在核心导航完成后分批迁移；迁移完成前，仓库中原文件仍是可追溯基线，不能假装在线页已经存在。
### Client（桌面客户端）
## 事实来源
| 我要做的事 | 主要看 | 顺带看 |
|---|---|---|
| 第一次把项目跑起来 | [00 上手指南](client/00-getting-started.md) | — |
| 改界面、加页面、调表格 | [05 界面交互规范](client/05-ui-specification.md) | [02 架构](client/02-architecture.md) §5 线程 |
| 加字段、改表、写 SQL | [03 数据模型](client/03-data-model.md) | [02 架构](client/02-architecture.md) §7 数据所有权 |
| 对接 Admin、写 Gateway | [04 接口契约](client/04-admin-api-contract.md) | [07 联调手册](admin/07-设备登记联调手册.md) |
| 写自动化、控制手机 | [02 架构](client/02-architecture.md) §9 | [06 质量与安全](client/06-quality-security.md) §4 |
| 碰采购、下单相关代码 | [06 质量与安全](client/06-quality-security.md) §3 | [01 需求](client/01-requirements.md) §4.2 |
| 写测试 | [06 质量与安全](client/06-quality-security.md) §2 | — |
| 搞不清这功能到底要不要做 | [01 产品需求基线](client/01-requirements.md) | — |
| 打包成 exe、改文件路径 | [01 需求](client/01-requirements.md) §8.1 | [03 数据模型](client/03-data-model.md) §2 |
- 单次需求、变更、实现、测试、提交和验收：Gitea 工单。
- 长期稳定文档：Gitea Wiki。
- 代码和与版本绑定的 Wiki 镜像：Git 仓库。
- 产品红线和 Agent 执行规则：根 `AGENTS.md` 与子项目 `AGENTS.md`。
- Client–Admin 接口：Client 侧契约页面。
### Admin（Web 管理端）
本地 `docs/` 是 Wiki 的只读镜像；必须先改在线 Wiki，再运行：
| 我要做的事 | 主要看 | 顺带看 |
|---|---|---|
| 第一次把项目跑起来 | [00 上手指南](admin/00-getting-started.md) | — |
| 改页面、加表格列 | [05 界面规范](admin/05-ui-specification.md) | [02 架构](admin/02-architecture.md) §4 模板 |
| 加字段、改表、写 SQL | [03 数据模型](admin/03-data-model.md) | [02 架构](admin/02-architecture.md) §2 分层 |
| 改 Excel 导入 | [03 数据模型](admin/03-data-model.md) §3.3 | [00 术语表](admin/00-glossary.md) §3 upsert |
| 改顺运宝同步 | [08 顺运宝接口](admin/08-顺运宝接口.md) | [03 数据模型](admin/03-data-model.md) |
| 对接第三方商品目录脚本 | [10 商品目录接入接口](admin/10-商品目录接入接口.md) | [03 数据模型](admin/03-data-model.md) |
| 把旧 Admin 数据迁移到 MySQL | [09 SQLite 单向迁移](admin/09-sqlite迁移到mysql.md) | [06 质量与安全](admin/06-quality-security.md) |
| 改给 Client 的接口 | [04 Client 接口实现](admin/04-client-api.md) | [Client 侧契约](client/04-admin-api-contract.md) |
| 和 Admin 联调、登记新设备 | [07 设备登记联调手册](admin/07-设备登记联调手册.md) | [Client 侧契约](client/04-admin-api-contract.md) §5 |
| 写测试 | [06 质量与安全](admin/06-quality-security.md) §2 | — |
| 搞不清这功能到底要不要做 | [01 产品需求基线](admin/01-requirements.md) | — |
```powershell
python dev_scripts/harness.py sync --verify
```
### 通用
| 我要做的事 | 看这里 |
|---|---|
| 建工单、写归档 | [模板](templates/task.md) + 根目录 [AGENTS.md](../AGENTS.md) |
无论做哪一样，都必须先看一遍对应子项目的 `AGENTS.md`（技术栈和红线）。
## Client 基线文档
| 文档 | 用途 |
|---|---|
| [00 上手指南](client/00-getting-started.md) | 装环境、连手机、跑起来、常见报错 |
| [00 术语表](client/00-glossary.md) | Outbox、幂等、不可逆阶段等 |
| [01 产品需求基线](client/01-requirements.md) | 目标、范围、任务类型、打包策略 |
| [02 系统架构](client/02-architecture.md) | 分层、线程模型、Worker 模板 |
| [03 数据模型](client/03-data-model.md) | SQLite 表、状态机、`pdd_data` 结构 |
| [04 Admin 接口契约](client/04-admin-api-contract.md) | **两个子项目的接口边界，改动需同步 Admin** |
| [05 界面交互规范](client/05-ui-specification.md) | PDD 任务页、设置页、表格交互 |
| [06 质量、安全与测试](client/06-quality-security.md) | 测试策略、采购安全、发布门禁 |
## Admin 基线文档
| 文档 | 用途 |
|---|---|
| [00 上手指南](admin/00-getting-started.md) | 装 Go、跑起来、常见报错 |
| [00 术语表](admin/00-glossary.md) | 货运单、upsert、SKU 映射等 |
| [01 产品需求基线](admin/01-requirements.md) | 业务链路、五个模块、状态定义 |
| [02 系统架构](admin/02-architecture.md) | 分层、目录、模板组织、前端约束 |
| [03 数据模型](admin/03-data-model.md) | SQLite 表、Excel 导入规则 |
| [04 Client 接口实现](admin/04-client-api.md) | 服务端怎么实现那三个接口 |
| [05 界面规范](admin/05-ui-specification.md) | 三段式布局、五个页面、弹窗 |
| [06 质量、安全与测试](admin/06-quality-security.md) | 测试、Web 安全、发布门禁 |
| [07 设备登记联调手册](admin/07-设备登记联调手册.md) | **给 Client 开发者**：怎么让新设备登记成功 |
| [08 顺运宝接口](admin/08-顺运宝接口.md) | 从抓包还原的外部 ERP 契约：登录、会话、货运单列表与明细 |
| [09 SQLite 单向迁移](admin/09-sqlite迁移到mysql.md) | 只读演练、一次性导入、逐表核对和失败处理 |
| [10 商品目录接入接口](admin/10-商品目录接入接口.md) | 第三方批量提交蝦皮、PDD 和商品关联的 JSON 契约 |
## 文档标注说明
基线文档中的条目按下面三档标注，没有标注的默认是 `[必须]`：
| 标注 | 含义 |
|---|---|
| `[必须]` | 不许改。要改先走工单，并经用户确认 |
| `[建议]` | 默认这么做；有更合适的做法可以换，但要在工单里说明原因 |
| `[待定]` | 还没定下来。文档会给一个临时默认值，先按临时值做，别停工 |
## 文档生命周期
- `docs/client` 和 `docs/admin` 只记录不随单个任务频繁变化的产品和技术基线。
- 日常需求、缺陷、进度、阻塞和方案变更以 Gitea 工单为事实来源。
- 单元任务完成后，按 `AGENTS.md` 归档到 `docs/task/<工单号>-<简短名称>.md`。
- 基线发生实质变化时，必须先更新对应 Gitea 工单并完成评审，再在同一任务中更新这里的相关文档。
- **接口契约改动必须两边同步**：`docs/client/04-*` 和 `docs/admin/04-*` 在同一个工单里一起改。
## 文档和代码对不上怎么办
现在的代码还没做到文档描述的目标状态，**对不上是正常的**。
Client 的已知差异列在 [02 架构](client/02-architecture.md) §3.1；
Admin 目前尚未开始编码。
按下面处理，不要一发现不一致就停工：
| 情况 | 怎么办 |
|---|---|
| 差异已经列在差异清单里 | 按代码现状继续做，不用停 |
| 差异不在清单里，但只影响写法、不影响业务结果 | 按文档做，并在工单里记一句 |
| 差异会影响业务结果（金额、数量、状态、下单与否、数据结构） | **停下来**，在工单里说明，等用户确认哪边是对的 |
判断不了算不算"影响业务结果"时，按最后一行处理。
## 文档状态
Client 和 Admin 文档均为 **基线草案**。
Admin 尚未开始编码；顺运宝同步方式、认证方式和部分字段仍需确认，
这些事项已在对应文档中标注为 `[待定]`，并给出了临时默认值。
历史 `docs/task` 在 2026-08-26 工作流切换前形成，冻结保留，不删除、不重命名、不批量重写。新任务默认不再创建第二份任务归档。
docs/delivery/README.md
+80
View File
@@ -0,0 +1,80 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Delivery-Documentation-Guide
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Delivery-Documentation-Guide.-
wiki_revision: 64c62e57f63639b33e96ae340bad601415d061b5
synchronized_at: 2026-08-26T08:43:07Z
<!-- gitea-wiki-mirror:end -->
# 交付文档指南
## 本页用途
本页规定项目开发完成后，怎样为客户、最终用户和其他岗位选择、编写、验证及维护交付文档。交付文档面向实际使用产品的人，不替代开发工作流、架构说明和任务归档。
最小原则：先确认交付对象，只创建对方完成工作确实需要的文档，不预建空白手册。
## 什么时候需要交付文档
出现以下任一情况时，应在单元任务工单中评估并更新交付文档：
- 新增或改变用户可见功能、操作步骤、界面、权限或限制；
- 改变安装、配置、部署、备份、恢复、监控或升级方法；
- 改变外部 API、数据格式、集成条件或兼容范围；
- 改变常见故障的识别、处理或支持方式；
- 发布新版本或交付客户验收。
纯内部重构只有在外部行为、操作方式、配置和支持边界均未改变时，才可选择“无交付文档影响”并说明原因。
## 受众与文档选择
| 交付对象 | 典型文档 | 需要回答的问题 |
|---|---|---|
| 最终用户 | 用户使用说明 | 怎样完成日常操作，失败后怎么办 |
| 管理员 | 管理员指南 | 怎样配置用户、权限和系统参数 |
| 运维人员 | 部署与运维指南 | 怎样安装、启停、监控、备份和恢复 |
| 客服或一线支持 | 支持与排错指南 | 怎样识别问题、收集信息和升级处理 |
| 集成人员 | 接口与集成指南 | 怎样认证、调用接口和处理兼容性 |
| 验收或项目负责人 | 发布、升级与验收说明 | 本次交付了什么，怎样验证和回退 |
一个项目只选择实际存在的交付对象。多个岗位需要相同内容时可共享一份文档，但必须明确各自可以执行的操作和权限边界。
## 内部文档与交付文档边界
交付文档可以包含用户完成工作所需的产品地址、公开接口、配置项、操作步骤、结果、限制和支持渠道。
面向客户或公开的文档不得包含：
- 内部工单链接、聊天记录、内部决策过程或任务归档；
- 内部网络地址、仓库路径、无必要的源码模块名和调试细节；
- 密码、令牌、Cookie、私钥、个人数据或生产数据；
- 未经确认的安全实现、漏洞细节或仅供内部使用的恢复手段；
- 未承诺的路线图、期限和功能。
交付前必须检查模板中的“可见范围”。同一主题同时存在内部版和客户版时，应分别维护并明确名称，不能依靠读者自行忽略内部内容。
## 编写和维护流程
1. 在项目初始化或需求确认时识别交付对象、可见范围和所需文档。
2. 使用[岗位文档模板](Audience-Document-Template.-)按需创建文档，不创建没有明确读者的空页面。
3. 单元任务在工单“交付文档影响”中选择无影响并说明原因，或列出需要更新的页面和受众。
4. 功能、配置或流程改变时，代码与对应交付文档在同一任务中更新。
5. 由熟悉该岗位但未参与实现的人按文档执行关键步骤；不能验证的环境和步骤必须明确标注。
6. 发布或交付前确认适用版本、最后验证日期、负责人、已知限制和支持渠道。
7. 长期维护仍遵循 Wiki-first：先修改 Wiki、读取确认，再导出本地 `docs/` 镜像。
具体项目创建的岗位文档应增加到 `wiki-docs.json` 的显式映射中。本模板自身的指南和模板镜像位于 `docs/delivery/`。
## 最小验收清单
- [ ] 文档有明确受众、适用版本、可见范围和负责人。
- [ ] 前置条件、操作步骤和预期结果完整且可以对应。
- [ ] 常见失败、恢复方法、安全提示和已知限制已说明。
- [ ] 关键步骤由目标岗位视角验证，或明确记录未验证项。
- [ ] 外部版本不含内部链接、敏感数据和无关实现细节。
- [ ] 本次功能变化涉及的交付文档已更新并与版本一致。
- [ ] Wiki 已读取确认，本地镜像检查一致。
## 不在本页解决的内容
开发任务怎样建单、实施和归档见[开发工作流](Development-Workflow.-)；代码结构和维护入口见[架构与代码地图](Architecture-and-Code-Map.-)。本页不规定市场宣传、合同、法务或商务承诺。
docs/delivery/audience-document-template.md
+96
View File
@@ -0,0 +1,96 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Audience-Document-Template
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Audience-Document-Template.-
wiki_revision: 7f3a383c111237ddd91463276f31a0d5cc9b6c87
synchronized_at: 2026-08-26T08:43:11Z
<!-- gitea-wiki-mirror:end -->
# 岗位文档模板
> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。
## 文档信息
| 字段 | 内容 |
|---|---|
| 文档名称 | |
| 适用对象 | 最终用户 / 管理员 / 运维 / 客服 / 集成人员 / 验收人员 / 其他 |
| 适用版本 | |
| 最后验证日期 | YYYY-MM-DD |
| 负责人 | |
| 可见范围 | 内部 / 指定客户 / 公开 |
| 相关产品或模块 | |
## 目的与适用范围
说明读者完成什么工作，以及本文包含和不包含什么。用岗位语言描述结果，不复制内部需求分析。
## 前置条件
- 所需权限：
- 所需环境或设备：
- 已完成的准备：
- 需要提前获得的信息：
不得在这里填写真实密码、令牌、个人数据或生产数据。
## 操作步骤
### 任务一：<明确的操作目标>
1. <执行动作>
2. <执行动作>
3. <执行动作>
**预期结果**：<读者可以观察到的成功结果>
**失败时**：<先检查什么；何时停止并联系支持>
每个独立任务重复以上结构。命令和界面名称应与适用版本一致；危险或不可逆操作必须在执行前给出醒目警告、影响和回退条件。
## 常见错误与恢复
| 现象或错误信息 | 可能原因 | 处理步骤 | 何时升级 |
|---|---|---|---|
| | | | |
只记录经过确认的原因和恢复方法。不要让外部读者执行内部调试、绕过权限或可能扩大损失的操作。
## 安全与权限
- 本岗位允许执行的操作：
- 明确禁止或需要审批的操作：
- 敏感信息处理规则：
- 数据、日志和截图脱敏要求：
- 删除、发布、迁移或其他高风险操作的确认要求：
## 已知限制
- 支持的环境和版本：
- 当前不支持的场景：
- 兼容性限制：
- 未验证的环境或步骤：
## 支持与升级处理
- 支持渠道：
- 服务时间或响应约定：
- 联系支持前需要收集的信息：
- 不得提交的信息：
- 需要升级到下一岗位或负责人的条件：
## 版本记录
| 日期 | 适用版本 | 变更内容 | 验证人 |
|---|---|---|---|
| | | | |
## 交付前检查
- [ ] 目标岗位能够理解术语和步骤。
- [ ] 前置条件、步骤与预期结果一一对应。
- [ ] 关键流程已按目标岗位视角验证。
- [ ] 常见错误、恢复方法和升级条件清楚。
- [ ] 没有内部工单、内部地址、敏感数据或无关源码细节。
- [ ] 适用版本、最后验证日期、负责人和可见范围已填写。
docs/templates/task-archive.md
Vendored
+50
View File
@@ -0,0 +1,50 @@
<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Task-Archive-Template
wiki_url: https://git.ilapage.cn/OPC/cmautobuy/wiki/Task-Archive-Template.-
wiki_revision: 00deee1e1aa73826d1541cfa1e9b1c0d1e69ee6a
synchronized_at: 2026-08-26T08:43:14Z
<!-- gitea-wiki-mirror:end -->
# <工单号> <标题>
- 类型：需求 / 缺陷 / 重构
- 所属 Epic：#
- 所属 MVP / 版本：#
- 状态：待验收 / 已完成
- 日期：YYYY-MM-DD
- Gitea 工单：<链接>
- Wiki 页面：<页面名>
- Wiki revision：见本地镜像头
## 背景与目标
<!-- 原来有什么问题，这次达到什么结果。 -->
## 最终方案
<!-- 说明实际实现。与建单方案不同之处必须写清原因。 -->
## 修改文件
- `<文件>`：<改动说明>
## 验收结果
| 验收标准 | 结果 |
|---|---|
| | 通过 / 未通过 |
## 测试
- 执行命令：`<命令>`
- 结果：
- **未验证部分**：<!-- 必填；没有就写“无”。 -->
## 遗留问题
<!-- 没有就删除本节。 -->
## 相关提交
- `<提交哈希>` <提交说明>