AutoRpa/docs/superpowers/specs/2026-10-02-repo-layout-design.md

# 仓库布局：四接口一服务 + 四个英文作业包

| 文档属性 | 内容 |
| --- | --- |
| 日期 | 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`。未跟踪残留（`.explore/`、`.magic/`、`output/结果` 下 html/png、本地 `.venv` / `.env`）不会跟着走，目录会留下。把需要的本地文件普通 `mv` 进 `rpa_selection/`，探测垃圾直接删，然后去掉空的 `选品流程/`。不要 `git add` `.explore` / `.magic` / 截图 |
| `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/`。不要新建第二套文档根。`资料/` 拆开并入后删除空目录。

已跟踪的用 `git mv`；未跟踪的用普通 `mv`，改完再 `git add`。不要对未跟踪文件跑 `git mv`。

仓库根 `README.md` 当前未跟踪。本轮按第 5.3 节写好后 `git add README.md`。

`选品流程/output/结果/.gitkeep` 已跟踪，随父目录 `git mv` 进入 `rpa_selection/output/结果/.gitkeep`。目录名保持 `结果`。

### 6.1 现行（`docs/` 根下）

已跟踪（`git mv`）：

| 来源 | 去向 |
| --- | --- |
| `资料/RPA订单中心接口开发口径_20260930.md` | `docs/` 同名 |
| `资料/采购平台选品条件优先项_20260902.txt` | `docs/` 同名 |

未跟踪（`mv` + `git add`）：

| 来源 | 去向 |
| --- | --- |
| `资料/README.md` | `docs/README.md`（重写路径，去掉「路径先不动」） |
| `资料/RPA订单中心接口口径讨论纪要_20260929.md` | `docs/` 同名 |
| `资料/ddl/` | `docs/ddl/` |
| `资料/API鉴权.doc` | `docs/` |
| `资料/下一会话任务_建表.md` | `docs/` |
| `资料/合同系统录入流程.md` | `docs/` |
| `资料/合同返利系统字段映射_20260911.xlsx` | `docs/` |
| `资料/【项目方案】福建洁达采购合同RPA自动化录入需求_v20260924.docx` | `docs/` |

口径正文里的 `` `资料/...` `` 改成 `` `docs/...` ``；`` `选品流程/` `` 改成 `` `rpa_selection/` ``。`合同系统录入流程.md` 里指向 `rpa_yisaiqi` 的句子保留。

### 6.2 归档（`docs/archive/`）

一期 13 节点主链，以及未列入现行表的旧设计说明。

已跟踪（`git mv` 进 `docs/archive/`）：

- `PLAN.md`
- `一期开发任务清单_表结构_API草案.md`
- `一期需求简版说明_业务版.md`
- `界面截图证据记录.md`
- `采购业务RPA思路20260625.docx`
- `采购主链RPA一期实施与验收规范.md`
- `采购主链RPA一期开发规划.md`
- `采购主链RPA一期设计文档.md`
- `采购主链RPA一期需求文档_三方会审版.md`
- `采购主链RPA一期需求文档_会议整理版.md`

未跟踪（`mv` + `git add` 进 `docs/archive/`）：

- `福建洁达采购合同自动化设计说明.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`

`选品流程` 出现在两处，按前缀替换，不要当成一整段覆盖：

1. 顶部 `.vscode` 例外：`!选品流程/.vscode/` → `!rpa_selection/.vscode/`（两行）
2. 底部凭据与产物：`选品流程/secrets.json` 等四行，前缀改 `rpa_selection/`

其余规则不动。根 README 的代码入口表仍保留 `rpa_yisaiqi` 一行，标明过渡；「五包」指 oms + 四个作业，不是把艺赛旗从入口拿掉。

---

## 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`；按 5.1 处理未跟踪残留，改该包 `pyproject.toml` 与 README
2. 建三个占位包并 `git add`
3. 按第 6 节：已跟踪文件 `git mv`，未跟踪文件 `mv` 后 `git add`；重写 `docs/README.md`
4. 写根 `README.md` 并 `git add`（该文件当前未跟踪）；改 `rpa_oms/README.md`、`rpa_yisaiqi/README.md`、`.gitignore`、搬过来的现行口径
5. 跑第 8 节两条 pytest
6. 确认根上没有 `选品流程/`、`资料/`