257 lines
11 KiB
Markdown
257 lines
11 KiB
Markdown
# 仓库布局：四接口一服务 + 四个英文作业包
|
||
|
||
| 文档属性 | 内容 |
|
||
| --- | --- |
|
||
| 日期 | 2026-10-02 |
|
||
| 状态 | 已锁定，本轮实施依据 |
|
||
| 范围 | 根目录命名与分家：`选品流程/` 整包迁到 `rpa_selection/`；占位 `rpa_cart/`、`rpa_contract/`、`rpa_rebate/`；`资料/` 并入 `docs/`。路径与文档引用。 |
|
||
| 替代 | 根 `README.md` 代码入口表；`资料/README.md`（并入后成为 `docs/README.md`） |
|
||
| 不变 | 四张表、四个口的作业语义、接口 1 行为、选品规则与拆量、`rpa_yisaiqi` 页面步骤 |
|
||
|
||
四个 HTTP 口不是四个服务。四条作业不是一个包。代码目录名全英文。
|
||
|
||
---
|
||
|
||
## 1. 要做成什么
|
||
|
||
根目录变成：
|
||
|
||
```
|
||
AutoRpa/
|
||
README.md
|
||
rpa_oms/ # 四个 HTTP 口，一个 FastAPI
|
||
rpa_selection/ # 选品班（现 选品流程/ 整包搬来）
|
||
rpa_cart/ # 加购 + 支付回传（占位）
|
||
rpa_contract/ # 合同班（占位）
|
||
rpa_rebate/ # 返利班（占位）
|
||
docs/ # 现行口径 + 归档（现 资料/ 并入）
|
||
rpa_yisaiqi/ # 过渡：合同班能跑之后整包删除
|
||
```
|
||
|
||
完成标准：
|
||
|
||
1. 仓库根上不再有 `选品流程/`、`资料/`。
|
||
2. `cd rpa_selection && uv run pytest -v` 与搬前同等通过。
|
||
3. `cd rpa_oms && uv run pytest -v` 通过。
|
||
4. 根 README、`docs/README.md`、`.gitignore`、现行口径里的路径指向新目录。
|
||
5. `rpa_cart/`、`rpa_contract/`、`rpa_rebate/` 各有 README 和空 `pyproject.toml`，能看出职责，没有可运行作业代码。
|
||
|
||
---
|
||
|
||
## 2. 不做什么
|
||
|
||
- 不加购、不支付回传、不录合同、不录返利
|
||
- 不实现接口 2 / 3 / 4，不在 `rpa_oms` 里建空路由模块
|
||
- 不改选品规则、班次判定、表结构、接口 1 报文
|
||
- 不整理、不改名、不删除 `rpa_yisaiqi/`（本轮只改指向它的现行文档路径，若文档从 `资料/` 搬走）
|
||
- 不把作业改成 `app/` 包；作业保持扁平脚本（`main.py` + `job.py`）
|
||
- 不把四个作业收进 `rpa_jobs/`
|
||
- 不改 `docs/superpowers/` 里历史 spec / plan 的死链（视为归档）
|
||
- 不提交 `state_center/` 等本轮无关的已删文件（那些删除不在本 spec 范围）
|
||
|
||
---
|
||
|
||
## 3. 已锁定决策
|
||
|
||
| 项 | 决定 |
|
||
| --- | --- |
|
||
| 四个口 | 继续住在 `rpa_oms/`。入站 1、3 在 `app/inbound/`，出站 2、4 做到时再加 `app/outbound/`。本轮只把这张地图写进 `rpa_oms/README.md` |
|
||
| 四个作业 | 根上并列：`rpa_selection`、`rpa_cart`、`rpa_contract`、`rpa_rebate` |
|
||
| `rpa_cart` | 加购（接口 2 `operateType=1`）和支付回传（`operateType=2`）同一个包。两个班次，共享表 2 |
|
||
| 选品 | `git mv 选品流程 rpa_selection`。业务代码、扁平 import、`pythonpath = ["."]` 不动 |
|
||
| 占位包 | 只有 `README.md` + `pyproject.toml`。无 `main.py`、无 `tests/` |
|
||
| 中文 | **代码目录**全英文。文档文件名可以中文。`docs/` 是目录名，里面的 `.md` 文件名不改 |
|
||
| `rpa_yisaiqi` | 过渡资产。合同页面步骤仍以它为准。等 `rpa_contract` 能跑再整包删 |
|
||
| `docs/superpowers/` | 原地不动，归档 |
|
||
|
||
---
|
||
|
||
## 4. `rpa_oms`：四个口的地图
|
||
|
||
本轮不改 Python 文件（README 除外）。运行时仍只开放接口 1。
|
||
|
||
| 口 | 方向 | 底表 | 代码落点（做到再写） |
|
||
| --- | --- | --- | --- |
|
||
| 1 | 订单中心 → 本方 | `rpa_sales_goods_mapping_data` | 已有 `app/inbound/sales_goods.py`，`POST /api/oms/v1/sales-goods` |
|
||
| 2 | 本方 → 订单中心 | `rpa_cart_settlement_goods_data` | 未来 `app/outbound/`，由 `rpa_cart` 班次调用，本服务也可提供 push 客户端 |
|
||
| 3 | 订单中心 → 本方 | `rpa_purchase_contract_data` | 未来 `app/inbound/`，复用接口 1 信封/鉴权 |
|
||
| 4 | 本方 → 订单中心 | `rpa_contract_agreement_result` | 未来 `app/outbound/`，由合同/返利班次调用 |
|
||
|
||
`rpa_oms/README.md` 用上表替换「本期只开放接口 1」的单一叙述，并写明：HTTP 收件不同步跑作业。
|
||
|
||
---
|
||
|
||
## 5. 四个作业包
|
||
|
||
作业语义仍以 `docs/RPA订单中心接口开发口径_20260930.md`（搬后路径）为准。包只是落点。
|
||
|
||
### 5.1 `rpa_selection/`（整包搬）
|
||
|
||
来源：`选品流程/`。
|
||
|
||
| 动作 | 细节 |
|
||
| --- | --- |
|
||
| 移动 | `git mv 选品流程 rpa_selection` |
|
||
| `pyproject.toml` | `name = "rpa-selection"`；description 改成带新目录名。依赖、`requires-python`、pytest 配置不动 |
|
||
| `README.md` | 所有 `cd 选品流程`、`` `选品流程/` `` 改成 `rpa_selection`；口径路径改 `docs/...` |
|
||
| 代码 | 不改 import、不改 `PROJECT_ROOT = Path(__file__).resolve().parent` |
|
||
| `output/结果` | 不改名（gitignored 产物）。`.gitignore` 路径跟着父目录改 |
|
||
|
||
搬完后包内仍是扁平脚本：`main.py`、`job.py`、`persist.py`、`repo.py`、`rules.py`、`pipeline.py`、`search_*.py`、`auth_login.py`、`tests/`。
|
||
|
||
### 5.2 占位包共同形态
|
||
|
||
`rpa_cart/`、`rpa_contract/`、`rpa_rebate/` 各两个文件，模板一致。
|
||
|
||
`pyproject.toml`：
|
||
|
||
```toml
|
||
[project]
|
||
name = "rpa-<slot>"
|
||
version = "0.1.0"
|
||
description = "<一句话职责>"
|
||
requires-python = ">=3.12"
|
||
dependencies = []
|
||
|
||
[tool.uv]
|
||
package = false
|
||
|
||
[[tool.uv.index]]
|
||
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
|
||
default = true
|
||
```
|
||
|
||
三个 `name` / `description`：
|
||
|
||
| 目录 | name | description |
|
||
| --- | --- | --- |
|
||
| `rpa_cart` | `rpa-cart` | 洁达加购与支付回传。表 2 → 接口 2。本包尚未实现。 |
|
||
| `rpa_contract` | `rpa-contract` | 洁达合同班。表 3 合单录入 → 表 4。本包尚未实现。 |
|
||
| `rpa_rebate` | `rpa-rebate` | 洁达返利班。按合同号查号、录协议 → 表 4。本包尚未实现。 |
|
||
|
||
每个 README 必须写清：
|
||
|
||
1. 读哪张表、写哪张表、对应哪个口
|
||
2. 班次（选品随接口 1；加购在选品之后另班；支付另班对准 12:30 / 17:30；合同/返利一天两班，返利建议合同班之后）
|
||
3. 本期不做（占位）
|
||
4. 合同包额外一句：页面步骤目前仍在 `rpa_yisaiqi/`，本包能跑之后再删艺赛旗
|
||
|
||
`rpa_cart` README 须写明两个入口将来都在本包：`operateType=1` 加购、`operateType=2` 支付回传。不要暗示会拆成第五个包。
|
||
|
||
### 5.3 作业与表的对照（写入根 README）
|
||
|
||
| 包 | 读 | 写 | 口 |
|
||
| --- | --- | --- | --- |
|
||
| `rpa_selection` | 表 1 `deal_flag=0` | 表 2 `operate_type=1`，表 1 处理标志 | 不直接调口；口 2 由 `rpa_cart` 推 |
|
||
| `rpa_cart` | 表 2 | 表 2 `push_status`；支付行 | 口 2 |
|
||
| `rpa_contract` | 表 3 `process_status=0` | 表 4 `actionCode=1` | 口 3 收件在 oms；口 4 回写 |
|
||
| `rpa_rebate` | 表 3 / 表 4 待查号与待录协议 | 表 4 `contractStatus=2`、`actionCode=2` | 口 4 |
|
||
|
||
---
|
||
|
||
## 6. `资料/` → `docs/`
|
||
|
||
`docs/` 已有 `superpowers/`。不要新建第二套文档根。`资料/` 拆开并入后删除空目录。
|
||
|
||
### 6.1 现行（`docs/` 根下）
|
||
|
||
| 来源 | 去向 |
|
||
| --- | --- |
|
||
| `资料/README.md` | `docs/README.md`（重写路径，去掉「路径先不动」） |
|
||
| `资料/RPA订单中心接口开发口径_20260930.md` | `docs/` 同名 |
|
||
| `资料/RPA订单中心接口口径讨论纪要_20260929.md` | `docs/` 同名 |
|
||
| `资料/ddl/` | `docs/ddl/` |
|
||
| `资料/API鉴权.doc` | `docs/` |
|
||
| `资料/下一会话任务_建表.md` | `docs/` |
|
||
| `资料/合同系统录入流程.md` | `docs/` |
|
||
| `资料/合同返利系统字段映射_20260911.xlsx` | `docs/` |
|
||
| `资料/采购平台选品条件优先项_20260902.txt` | `docs/` |
|
||
| `资料/【项目方案】福建洁达采购合同RPA自动化录入需求_v20260924.docx` | `docs/` |
|
||
|
||
口径正文里的 `` `资料/...` `` 改成 `` `docs/...` ``；`` `选品流程/` `` 改成 `` `rpa_selection/` ``。`合同系统录入流程.md` 里指向 `rpa_yisaiqi` 的句子保留。
|
||
|
||
### 6.2 归档（`docs/archive/`）
|
||
|
||
一期 13 节点主链，以及未列入现行表的旧设计说明：
|
||
|
||
- `PLAN.md`
|
||
- `一期开发任务清单_表结构_API草案.md`
|
||
- `一期需求简版说明_业务版.md`
|
||
- `界面截图证据记录.md`
|
||
- `福建洁达采购合同自动化设计说明.md`
|
||
- `采购业务RPA思路20260625.docx`
|
||
- `采购主链RPA一期实施与验收规范.md`
|
||
- `采购主链RPA一期开发规划.md`
|
||
- `采购主链RPA一期设计文档.md`
|
||
- `采购主链RPA一期需求文档_三方会审版.md`
|
||
- `采购主链RPA一期需求文档_会议整理版.md`
|
||
|
||
这些文件内部的 `资料/` 链接不改。`docs/README.md` 的历史节指向 `docs/archive/`，并保留原警告：那套模型是「一单合同走状态机」，不要用来解释接口 1 收件箱。
|
||
|
||
### 6.3 必须改路径的现行文件
|
||
|
||
只改还在用的入口，不扫历史 spec。
|
||
|
||
| 文件 | 改什么 |
|
||
| --- | --- |
|
||
| `README.md`（仓库根） | 代码入口表换成五包；文档入口改 `docs/` |
|
||
| `docs/README.md` | 见 6.1 |
|
||
| `rpa_oms/README.md` | 四个口地图；文档链接 `docs/` |
|
||
| `rpa_selection/README.md` | 目录名与口径路径 |
|
||
| `rpa_yisaiqi/README.md` | `` `资料/合同系统录入流程.md` `` → `` `docs/合同系统录入流程.md` `` |
|
||
| `.gitignore` | `选品流程/` → `rpa_selection/`（`.vscode` 例外规则、secrets、`data/.auth`、`output/结果`） |
|
||
| `docs/RPA订单中心接口开发口径_20260930.md` | `选品流程/`、`资料/` 路径 |
|
||
| `docs/RPA订单中心接口口径讨论纪要_20260929.md` | `资料/` 路径 |
|
||
| `docs/ddl/列对照.md` | `资料/ddl/` → `docs/ddl/` |
|
||
| `docs/下一会话任务_建表.md` | `资料/` 路径 |
|
||
| `docs/合同系统录入流程.md` | 若正文有 `资料/` 自引用则改 |
|
||
|
||
`docs/superpowers/specs/2026-10-02-selection-split-allocation-design.md` 里的 `选品流程/`、`资料/` 是当时实施记录，不改。
|
||
|
||
---
|
||
|
||
## 7. `.gitignore`
|
||
|
||
现有选品相关行整段替换为：
|
||
|
||
```
|
||
!rpa_selection/.vscode/
|
||
!rpa_selection/.vscode/**
|
||
rpa_selection/secrets.json
|
||
rpa_selection/data/.auth/
|
||
rpa_selection/output/结果/*.xlsx
|
||
rpa_selection/output/结果/*.txt
|
||
```
|
||
|
||
其余规则不动。
|
||
|
||
---
|
||
|
||
## 8. 错误与回归
|
||
|
||
这是搬家，没有新的运行时错误分支。失败模式只有路径漏改：
|
||
|
||
- 测试或文档还写 `选品流程`、`资料/`（现行入口）
|
||
- `cd 选品流程` 还出现在现行 README
|
||
- 占位包被误写成可运行作业（出现 `main.py` 却无实现）
|
||
|
||
回归：
|
||
|
||
```bash
|
||
cd rpa_oms && uv run pytest -v
|
||
cd rpa_selection && uv run pytest -v
|
||
```
|
||
|
||
选品单测不得改断言、不得为搬家放宽。若有测试读仓库根路径或写死 `选品流程`，改为相对包根（`Path(__file__).resolve().parents[1]` 已是包根的保持不动）。
|
||
|
||
---
|
||
|
||
## 9. 实施顺序
|
||
|
||
1. `git mv 选品流程 rpa_selection`，改该包 `pyproject.toml` 与 README
|
||
2. 建三个占位包
|
||
3. 把 `资料/` 按第 6 节拆进 `docs/` 与 `docs/archive/`，重写 `docs/README.md`
|
||
4. 改根 README、`rpa_oms/README.md`、`rpa_yisaiqi/README.md`、`.gitignore`、搬过来的现行口径
|
||
5. 跑第 8 节两条 pytest
|
||
6. 确认根上没有 `选品流程/`、`资料/`
|