diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md new file mode 100644 index 0000000..5e3745f --- /dev/null +++ b/docs/00-project-profile.md @@ -0,0 +1,92 @@ + +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 + + +# 项目档案 + +## 基本信息 + +| 项目 | 值 | +|---|---| +| 项目名 | 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 目录，对外证据必须脱敏。 diff --git a/docs/01-workflow.md b/docs/01-workflow.md new file mode 100644 index 0000000..dc62f93 --- /dev/null +++ b/docs/01-workflow.md @@ -0,0 +1,348 @@ + +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 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。 +- 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` 镜像 | +|---|---:|---:|---:| +| 讨论过程和临时方案 | 是 | 否 | 否 | +| 实施进度和阻塞 | 是 | 否 | 否 | +| 长期有效的最终方案 | 链接 | 是 | 镜像 | +| 测试结果与未验证内容 | 是 | 否 | 否 | +| 提交哈希和验收结论 | 是 | 否 | 否 | +| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 | +| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 | diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md new file mode 100644 index 0000000..9edfa89 --- /dev/null +++ b/docs/02-architecture-and-code-map.md @@ -0,0 +1,69 @@ + +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 + + +# 架构与代码地图 + +## 项目定位 + +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 的版本镜像。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md new file mode 100644 index 0000000..bf1f58e --- /dev/null +++ b/docs/03-business-rules-and-glossary.md @@ -0,0 +1,62 @@ + +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 + + +# 业务规则与术语 + +## 核心术语 + +| 术语 | 含义 | +|---|---| +| 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 的接口唯一事实来源。 +- 新状态、金额单位、时间语义和幂等键。 +- 是否触及采购、付款、登录、凭据或个人数据红线。 +- 面向谁的长期文档和部署运维入口。 +- 可复制的测试命令和明确的未验证部分。 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md new file mode 100644 index 0000000..738ee28 --- /dev/null +++ b/docs/04-local-development-and-verification.md @@ -0,0 +1,89 @@ + +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 + + +# 本地开发与验证 + +## 环境要求 + +| 部分 | 固定环境 | +|---|---| +| 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、部署或真实下单时，工单必须单独写明是否验证；没有执行就明确记录“未验证”，不能用单元测试代替。 diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md new file mode 100644 index 0000000..b909533 --- /dev/null +++ b/docs/05-common-changes.md @@ -0,0 +1,46 @@ + +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 + + +# 常见修改 + +## 风险分级 + +| 风险 | 示例 | 最小要求 | +|---|---|---| +| 低 | 错别字、注释、纯内部变量名 | 不改变行为时可小改直通 | +| 中 | 页面字段、筛选、普通接口行为 | 工单、对应子项目规则、单元测试 | +| 高 | 数据库迁移、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. 用户验收前工单是否仍保持打开。 diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md new file mode 100644 index 0000000..d4c340f --- /dev/null +++ b/docs/06-troubleshooting.md @@ -0,0 +1,40 @@ + +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 + + +# 故障排查 + +## 排查顺序 + +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，却准备把本地文件当成已同步。 +- 工作区存在会被覆盖的无关修改。 + +停止时要把已确认事实、阻塞点、已尝试的安全检查和恢复条件写回工单。 diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md new file mode 100644 index 0000000..9158eba --- /dev/null +++ b/docs/09-product-requirements-overview.md @@ -0,0 +1,80 @@ + +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 工单为准。 + +## 事实来源边界 + +- 产品主线和长期边界：本页及 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 页面一致。 +- [ ] 未验证部分已明确记录。 diff --git a/docs/README.md b/docs/README.md index 5cff028..bcdda44 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,137 +1,75 @@ -# 项目文档索引 + +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 + -本目录保存项目级文档。长期稳定的基线文档按子项目放在 `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 工作流切换前形成，冻结保留，不删除、不重命名、不批量重写。新任务默认不再创建第二份任务归档。 diff --git a/docs/delivery/README.md b/docs/delivery/README.md new file mode 100644 index 0000000..10feedc --- /dev/null +++ b/docs/delivery/README.md @@ -0,0 +1,80 @@ + +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 + + +# 交付文档指南 + +## 本页用途 + +本页规定项目开发完成后，怎样为客户、最终用户和其他岗位选择、编写、验证及维护交付文档。交付文档面向实际使用产品的人，不替代开发工作流、架构说明和任务归档。 + +最小原则：先确认交付对象，只创建对方完成工作确实需要的文档，不预建空白手册。 + +## 什么时候需要交付文档 + +出现以下任一情况时，应在单元任务工单中评估并更新交付文档： + +- 新增或改变用户可见功能、操作步骤、界面、权限或限制； +- 改变安装、配置、部署、备份、恢复、监控或升级方法； +- 改变外部 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.-)。本页不规定市场宣传、合同、法务或商务承诺。 diff --git a/docs/delivery/audience-document-template.md b/docs/delivery/audience-document-template.md new file mode 100644 index 0000000..e506e6a --- /dev/null +++ b/docs/delivery/audience-document-template.md @@ -0,0 +1,96 @@ + +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 + + +# 岗位文档模板 + +> 使用说明：复制本模板创建具体岗位文档，删除说明性文字并填写真实内容。没有明确受众时不要创建文档；不得保留“待填写”后直接交付。 + +## 文档信息 + +| 字段 | 内容 | +|---|---| +| 文档名称 | | +| 适用对象 | 最终用户 / 管理员 / 运维 / 客服 / 集成人员 / 验收人员 / 其他 | +| 适用版本 | | +| 最后验证日期 | YYYY-MM-DD | +| 负责人 | | +| 可见范围 | 内部 / 指定客户 / 公开 | +| 相关产品或模块 | | + +## 目的与适用范围 + +说明读者完成什么工作，以及本文包含和不包含什么。用岗位语言描述结果，不复制内部需求分析。 + +## 前置条件 + +- 所需权限： +- 所需环境或设备： +- 已完成的准备： +- 需要提前获得的信息： + +不得在这里填写真实密码、令牌、个人数据或生产数据。 + +## 操作步骤 + +### 任务一：<明确的操作目标> + +1. <执行动作> +2. <执行动作> +3. <执行动作> + +**预期结果**：<读者可以观察到的成功结果> + +**失败时**：<先检查什么；何时停止并联系支持> + +每个独立任务重复以上结构。命令和界面名称应与适用版本一致；危险或不可逆操作必须在执行前给出醒目警告、影响和回退条件。 + +## 常见错误与恢复 + +| 现象或错误信息 | 可能原因 | 处理步骤 | 何时升级 | +|---|---|---|---| +| | | | | + +只记录经过确认的原因和恢复方法。不要让外部读者执行内部调试、绕过权限或可能扩大损失的操作。 + +## 安全与权限 + +- 本岗位允许执行的操作： +- 明确禁止或需要审批的操作： +- 敏感信息处理规则： +- 数据、日志和截图脱敏要求： +- 删除、发布、迁移或其他高风险操作的确认要求： + +## 已知限制 + +- 支持的环境和版本： +- 当前不支持的场景： +- 兼容性限制： +- 未验证的环境或步骤： + +## 支持与升级处理 + +- 支持渠道： +- 服务时间或响应约定： +- 联系支持前需要收集的信息： +- 不得提交的信息： +- 需要升级到下一岗位或负责人的条件： + +## 版本记录 + +| 日期 | 适用版本 | 变更内容 | 验证人 | +|---|---|---|---| +| | | | | + +## 交付前检查 + +- [ ] 目标岗位能够理解术语和步骤。 +- [ ] 前置条件、步骤与预期结果一一对应。 +- [ ] 关键流程已按目标岗位视角验证。 +- [ ] 常见错误、恢复方法和升级条件清楚。 +- [ ] 没有内部工单、内部地址、敏感数据或无关源码细节。 +- [ ] 适用版本、最后验证日期、负责人和可见范围已填写。 diff --git a/docs/templates/task-archive.md b/docs/templates/task-archive.md new file mode 100644 index 0000000..ebab910 --- /dev/null +++ b/docs/templates/task-archive.md @@ -0,0 +1,50 @@ + +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 + + +# <工单号> <标题> + +- 类型：需求 / 缺陷 / 重构 +- 所属 Epic：# +- 所属 MVP / 版本：# +- 状态：待验收 / 已完成 +- 日期：YYYY-MM-DD +- Gitea 工单：<链接> +- Wiki 页面：<页面名> +- Wiki revision：见本地镜像头 + +## 背景与目标 + + + +## 最终方案 + + + +## 修改文件 + +- `<文件>`：<改动说明> + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| | 通过 / 未通过 | + +## 测试 + +- 执行命令：`<命令>` +- 结果： +- **未验证部分**： + +## 遗留问题 + + + +## 相关提交 + +- `<提交哈希>` <提交说明>