docs: 建立 Admin 子项目的文档基线
仓库从单子项目变成两个:client(Python + PyQt5 桌面端)和 admin(Go + Gin + HTML 模板 Web 管理端)。两者技术栈完全不同, 规则各自独立,只通过三个 HTTP 接口交互。 新增 admin/AGENTS.md 和 docs/admin/ 共 9 份文档,结构与 docs/client/ 对齐。 关键设计决策(均已与用户确认) - 四模块:蝦皮数据 / 顺运宝数据 / 采购任务 / 客户端列表, 统一三段式布局(工具条 / 带勾选的表格 / 状态条) - 蝦皮数据拆成商品表 + SKU 表:报表本身就是两层结构, 且 PDD 链接是商品级的,放 SKU 级会重复维护 - pdd_data 存商品级,一个 PDD 商品采一次,所有订单共用 - SKU 映射独立成表且可复用,同一蝦皮 SKU 只需人工匹配一次 - PDD 链接人工填写,采集按钮就放在填链接的编辑弹窗里 - 任务分配给指定客户端;不加心跳,注册在领取时完成, 在线状态由 last_seen_at 派生 - SQLite 驱动固定 modernc.org/sqlite(纯 Go 免 cgo,go build 直接出 exe) - 不引入前端框架和 npm 构建,只允许原生 JS 或 htmx 基于样本文件 raw_data/蝦皮数据样本.xlsx 实测得出的约束 - 11287 行 = 5195 商品汇总行 + 6092 SKU 行,导入必须分开处理 - 商品規格ID 零重复,是天然主键 - 规格原文两种格式各占 53.4% / 46.6%,只解析【】会漏掉一半 - 平均每商品仅 1.17 个 SKU,报表不是全量目录, 因此必须支持手动新增,且货运单外键不能加硬约束 同步更新 - 根 AGENTS.md 开头的指针改为两个子项目对照表 - docs/README.md 重构为双子项目索引 - .gitignore 加 admin/data/、admin.exe、Excel 锁文件 说明:Gitea 尚未配置,本次无对应工单号。 raw_data/ 未提交,含台币销售额等商业数据,待用户决定。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -13,13 +13,17 @@
|
||||
|
||||
改动看起来再合理,只要碰到上面任意一条,先停下来告诉用户。
|
||||
|
||||
> **动 `client/` 下任何东西之前,先读 [client/AGENTS.md](client/AGENTS.md)。**
|
||||
> 那里有技术栈、代码分层、线程、采购安全和界面的硬性规则,本文件不重复。
|
||||
> **本项目的代码目前全部在 `client/` 下**,所以基本上只要是写代码,就必须先读它。
|
||||
> **动代码之前,先读对应子项目的 AGENTS.md**,那里有技术栈、分层和硬性规则,本文件不重复:
|
||||
>
|
||||
> 第一次接手本项目,还要先看:
|
||||
> [上手指南](docs/client/00-getting-started.md)(装环境、跑起来)和
|
||||
> [术语表](docs/client/00-glossary.md)(Outbox、幂等、不可逆阶段等)。
|
||||
> | 你要改的东西在 | 先读 | 技术栈 |
|
||||
> |---|---|---|
|
||||
> | `client/` 桌面客户端 | [client/AGENTS.md](client/AGENTS.md) | Python + PyQt5 |
|
||||
> | `admin/` 管理端 | [admin/AGENTS.md](admin/AGENTS.md) | Go + Gin + HTML 模板 |
|
||||
>
|
||||
> **两个子项目技术栈完全不同,规则不通用,不要拿一边的经验套另一边。**
|
||||
>
|
||||
> 第一次接手,先看对应的上手指南和术语表:
|
||||
> [Client](docs/client/00-getting-started.md) · [Admin](docs/admin/00-getting-started.md)
|
||||
|
||||
## 需求、缺陷与任务工作流
|
||||
|
||||
@@ -235,9 +239,23 @@ Gitea 使用约定(**首次使用前需由项目负责人补全**):
|
||||
- 报错分析应指出具体位置、直接原因、修复方法和验证方式,不只给出修改后的完整代码。
|
||||
- 不假设维护者熟悉 Qt 线程、SQLite 事务、Admin 幂等或 uiautomator2 控件树;涉及这些概念时给出一句话背景。
|
||||
|
||||
## Client 子项目
|
||||
## 子项目
|
||||
|
||||
- 处理 `client/` 下的需求、代码、测试或文档前,必须读取并遵循 [client/AGENTS.md](client/AGENTS.md)。
|
||||
- 从仓库根目录启动时也不能跳过该文件(本文件开头已重复提醒一次)。
|
||||
- Client 的详细需求和技术基线位于 [docs/client/](docs/client/);按当前任务只读取相关文档,清单见 [文档索引](docs/README.md)。
|
||||
- Client 专用技术栈、线程、自动化安全、界面和验证规则不在根文件重复维护。
|
||||
本仓库有两个子项目,**技术栈完全不同,规则各自独立**:
|
||||
|
||||
| 子项目 | 是什么 | 规则文件 | 基线文档 |
|
||||
|---|---|---|---|
|
||||
| `client/` | Windows 桌面客户端,控制安卓设备执行采集和采购 | [client/AGENTS.md](client/AGENTS.md) | [docs/client/](docs/client/) |
|
||||
| `admin/` | 本地 Web 管理端,管理商品、订单、任务和客户端 | [admin/AGENTS.md](admin/AGENTS.md) | [docs/admin/](docs/admin/) |
|
||||
|
||||
- 处理某个子项目下的需求、代码、测试或文档前,必须读取并遵循它的 `AGENTS.md`。
|
||||
- 从仓库根目录启动时也不能跳过(本文件开头已重复提醒一次)。
|
||||
- 按当前任务只读取相关文档,清单见 [文档索引](docs/README.md)。
|
||||
- 子项目专用的技术栈、分层、安全和验证规则不在根文件重复维护。
|
||||
|
||||
### 两者的接口边界
|
||||
|
||||
Admin 和 Client 通过三个 HTTP 接口交互,**契约以 Client 侧文档为准**:
|
||||
[docs/client/04-admin-api-contract.md](docs/client/04-admin-api-contract.md)。
|
||||
|
||||
改动接口时,两边的文档必须在同一个工单里同步更新,不允许只改一边。
|
||||
|
||||
Reference in New Issue
Block a user