docs: lock repo layout for oms + four English job packages

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

@@ -0,0 +1,256 @@
+# 仓库布局：四接口一服务 + 四个英文作业包
+
+| 文档属性 | 内容 |
+| --- | --- |
+| 日期 | 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. 确认根上没有 `选品流程/`、`资料/`