chengmaandClaude Opus 5
f0d7da37cf
原来的采购任务页是骨架：var rows []gin.H 从不查库，页面永远为空； TODO 写的还是只查 task_type = 'purchase'。所以 #18 建出来的采集任务 在界面上哪儿都看不到——用户点完「创建采集任务」只能盯着 collect_status 猜。 模块名定为「采集采购」（用户指定），直接点出这页装的是哪两类任务， 比泛称「任务」更能让人一眼知道点进去看什么。路由 /tasks 不变， 改路由会让已有书签和文档链接全失效，没有收益。 列不按类型并列——两种任务字段完全不同，并列会让采集任务行一半是空列。 改成固定列 + 一列「目标」把业务信息概括成一句话： 采集 PDD 737116531267 采购 SO-001 · M/黑色 · 2件 · ≤¥42.00 拼接逻辑在 service 层，模板只负责显示。 统计和列表共用同一个筛选条件拼装函数。分开写的话总有一天会忘了 给统计也加条件，数字和表格对不上，操作员会以为页面坏了。 无主任务的客户端列显示「—」。#17 之后采集任务默认无主，这列会大量为空。 详情弹窗只读，采购专有字段（数量、价格上限、目标规格）在采集任务里 整段不出现，不显示空行。复用 #18 的弹窗机制，app.js 无需改动。 顺带清掉 PDD 页加进来之后一直没跟上的模块计数：多处「四个模块/四个页面」 改成五个。其中 06-quality-security.md 那两处是验证清单， 照着做的人只会测四个页面，PDD 页永远不在回归范围里。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
132 lines
7.4 KiB
Markdown
132 lines
7.4 KiB
Markdown
# 项目文档索引
|
||
|
||
本目录保存项目级文档。长期稳定的基线文档按子项目放在 `docs/client` 和 `docs/admin`，
|
||
实施过程和完成记录放在 `docs/task`，两者不得混用。
|
||
|
||
## 项目由两部分组成
|
||
|
||
| 子项目 | 是什么 | 技术栈 | 规则文件 |
|
||
|---|---|---|---|
|
||
| **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) 为准。
|
||
|
||
> **两个子项目技术栈完全不同，规则不通用。** 别拿 Client 的经验套 Admin，反之亦然。
|
||
|
||
## 新人从这里开始
|
||
|
||
| 我要做 | 先读 |
|
||
|---|---|
|
||
| 上手 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 |
|
||
|
||
## 按任务找文档
|
||
|
||
**不用通读全部文档**，按你要做的事挑：
|
||
|
||
### 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 |
|
||
|
||
### Admin（Web 管理端）
|
||
|
||
| 我要做的事 | 主要看 | 顺带看 |
|
||
|---|---|---|
|
||
| 第一次把项目跑起来 | [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 |
|
||
| 改给 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) | — |
|
||
|
||
### 通用
|
||
|
||
| 我要做的事 | 看这里 |
|
||
|---|---|
|
||
| 建工单、写归档 | [模板](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 开发者**：怎么让新设备登记成功 |
|
||
|
||
## 文档标注说明
|
||
|
||
基线文档中的条目按下面三档标注，没有标注的默认是 `[必须]`：
|
||
|
||
| 标注 | 含义 |
|
||
|---|---|
|
||
| `[必须]` | 不许改。要改先走工单，并经用户确认 |
|
||
| `[建议]` | 默认这么做；有更合适的做法可以换，但要在工单里说明原因 |
|
||
| `[待定]` | 还没定下来。文档会给一个临时默认值，先按临时值做，别停工 |
|
||
|
||
## 文档生命周期
|
||
|
||
- `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 尚未开始编码；顺运宝同步方式、认证方式和部分字段仍需确认，
|
||
这些事项已在对应文档中标注为 `[待定]`，并给出了临时默认值。
|