From e4875c58e523a0e4622bcb181d5f14a729dc390f Mon Sep 17 00:00:00 2001 From: Yuuuu <1569752928@qq.com> Date: Fri, 2 Oct 2026 17:42:43 +0800 Subject: [PATCH] docs: lock repo layout for oms + four English job packages --- .../specs/2026-10-02-repo-layout-design.md | 256 ++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-02-repo-layout-design.md diff --git a/docs/superpowers/specs/2026-10-02-repo-layout-design.md b/docs/superpowers/specs/2026-10-02-repo-layout-design.md new file mode 100644 index 0000000..bff87ae --- /dev/null +++ b/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-" +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. 确认根上没有 `选品流程/`、`资料/`