7.5 KiB

Raw Permalink Blame History

给 Trae 的开发交接说明

你(Trae)接手"采购主链RPA一期 · 状态中心"的后续开发。本文是你的入口,先读这份,再读下面点名的文件。写代码前把"硬规则"和"你不做什么"看完,别越界。

一、你要干什么(一句话)

做状态中心:一个 Python(FastAPI)+ MySQL 的后台 + 配套网页。它负责"每一单跑到哪步、出错派给谁、存状态和证据、画步骤树状图给业务看"。它自己不去点任何外部系统页面——点页面是艺赛旗 RPA 的活,通过 HTTP 回调跟你交互。

二、先读这几个文件(按顺序)

资料/采购主链RPA一期需求文档_三方会审版.md —— 业务规则(节点N01~N10、字段、异常)。
资料/采购主链RPA一期设计文档.md —— 技术设计(表结构、状态机、接口契约、对码引擎)。
资料/采购主链RPA一期实施与验收规范.md —— 每个节点的操作步骤 + 验收标准(代码+业务两栏),你做完对着这里勾。
state_center/README.md —— 已有代码怎么起、怎么验。

三、技术栈(已定,别改)

后台:Python 3 + FastAPI
库:MySQL 8(状态中心自己的库,建库脚本 sql/schema.sql 已给)
对码货品主数据:在 Oracle,只读直连查,不要复制成本地表
OCR:本地 Python 服务(PaddleOCR),仅线下手工单用
前端:Vue 或 React(待办页 + 步骤树状图 + 整单查询)
RPA 下层:艺赛旗 iS-RPA(不是你做,你只跟它的 HTTP 回调对接)

四、已经写好的(别重写,在这上面接着做)

state_center/ 里已有可跑的第1步骨架:

文件	已实现	状态
`sql/schema.sql`	8张表建库脚本	完成
`app/config.py`	MySQL/Oracle 连接、Oracle表名列名占位	完成
`app/db.py`	MySQL 访问(pymysql)	完成
`app/match_engine.py`	对码引擎:两级命中+规格标准化+Oracle取数函数	完成,单测6/6过
`app/main.py`	建单 + start/complete/fail 三回调(含幂等/乱序拒绝)+ 合同审批等待 + 整单查询	骨架完成
`tests/test_match_engine.py`	对码单测	通过

状态机流转已通(13 节点 = 11 主 + 2 条件 显式转移表、业务编号回写、回调幂等、乱序拒绝 409、合同审批等待态、M5质管缺失→FAILED_MANUAL、M5不自动保存),用假回调能把一个 job 从头走到尾。

节点数口径:主链 11 步每单都走;OCR_EXTRACT(仅线下单)、SOURCE_ADD(仅缺货源)是条件节点,不满足自动跳过。代码 NODE_ORDER 列全 13 个,TRANSITIONS 定转移,NODE_EXECUTOR 标执行方(STATE_CENTER/RPA/HUMAN)。

五、你的任务清单(按顺序做,每步对着验收规范勾)

任务1:把骨架在真 MySQL 上跑通

建库、起服务,按 README 的 curl 把一个 job 用假回调走完主链(线上单会自动跳过 OCR_EXTRACT/SOURCE_ADD 条件节点)。
验收:GET /api/jobs/{id} 能看到完整节点轨迹和状态。

任务2:对码接口 + Oracle 真连

拿到 Oracle 连接串/表名列名后,填 config.py,pip install oracledb。
骨架已写好(main.py),你主要是接真数据、补前置:
- POST /api/match/reload-goods:开工从 Oracle 全量拉货品主数据装进内存引擎(依赖 ORACLE_* 配置)。
- POST /api/jobs/{id}/match/run:对该 job 的 order_item 跑对码 → 落 product_match;MULTI/NONE 建 user_task 转 WAITING_USER,全命中推进下一节点。前置:order_item 要先落库(建单/ORDER_FETCH 后把明细写进来),否则 run 会 400。
- POST /api/match/{matchId}/confirm:人工确认一条,回写 product_match + 沉淀 mapping_config 累积别名(下次自动 ALIAS 命中),全部解决后自动推进。
已补齐的关键边界:
- 对码重跑幂等:product_match(job_id,order_item_id) 当前态唯一,match/run upsert 结果并重建 OPEN 待办。
- 货源判定:goods_id 明确后,按历史 supplier_name + goods_id 判断是否已有货源;缺货源会写 product_match.source_add_needed/job.needs_source_add 并创建 SOURCE_ADD 聚合待办。
- alias 沉淀:同一 config_key 先失效旧 active,再插新 active;装载时按固定顺序取当前结果。
你要补的:① 订单明细落 order_item 的入口;② GET /api/jobs/{id}/match/unmatched(列未命中给前端);③ H5 待办提交入口(把 SOURCE_ADD 完成动作接到 nodes/SOURCE_ADD/complete)。
只写 mapping_config 累积别名,绝不回写 Oracle 主数据(主数据只读)。
验收:喂真实订单,命中率有数字,未命中进待办,确认后能自动往下走。

任务3:待办 + 人工提交

GET /api/tasks/my?roleCode=&status=open、POST /api/tasks/{id}/submit。
动作:SELECT_CANDIDATE(对码选候选)/CONFIRM_AND_CONTINUE/RETRY_CURRENT_NODE/TRANSFER_MANUAL/TERMINATE_JOB。
幂等:task_id + submit_token 防重复提交。

任务4:前端网页

步骤树状图(样式见实施规范第三部分)、待办页、整单查询页。
验收:业务打开能看到每单跑到哪、卡在哪、去处理按钮跳待办。

任务5:证据 + 事件流 + 企业微信

证据落盘(job_artifact),事件流已有基础(job_event)。
企业微信推待办、H5 身份换 JWT。

任务6:调度与重试

定时触发建单(跑前一天订单)、系统类错误自动重试1-2次、CONTRACT_APPROVE_WAIT 轮询(别死等)、超时升级。

六、硬规则(红线,违反就是错的)

对码表在 Oracle,只读,绝不复制成本地表、绝不回写 Oracle。累积别名写自己的 mapping_config。
M5 质管资料缺失(errorCode=M5_QC_MISSING)→ 不重试、不等质管,直接 FAILED_MANUAL 转人工。已在 main.py 实现,别改成重试。
M5 一期不自动保存/签订(auto_save_enabled 默认0),做成开关,阶段二才放开。别默认自动。
关键送审在返利中心(REBATE_SUBMIT),不是合同系统。不送审 M5 带不出协议,是硬阻断。
签约日期 = 订单日期(不是今天),合同建单时按订单日期填。
医药城同供应商同日合同合并成一个PDF再上传(传第二份会覆盖),小药药不上传。
返利细单备注必填订单号、特定补偿必填0。
对码未命中/返利重复编码 = 单条挂起,整批继续;不是停整批。
所有写接口必须鉴权;RPA 回调校验 X-Agent-Token + 幂等键,禁止无认证暴露。
节点失败不覆盖历史,attempt_no+1 新建 job_node 行。

七、你不做什么(边界)

不写点外部系统页面的代码(登录/导Excel/建合同/M5录入)——那是艺赛旗,你只收它的 HTTP 回调。
不做招财平台(一期不纳入)。
不做加单/拆单全自动重做(先记录父订单号,转人工)。
不做返利重复编码全自动重建(规则未定,先转人工)。
遇到文档里标 【待确认】 的(订单状态过滤、OCR部署方式等),别自己拍板,先留 TODO 问项目负责人。

八、回调契约(艺赛旗会这样调你,已实现)

POST /api/jobs/{jobId}/nodes/{nodeCode}/start    header: X-Agent-Token
POST /api/jobs/{jobId}/nodes/{nodeCode}/complete  带 businessRefs/summary
POST /api/jobs/{jobId}/nodes/{nodeCode}/fail      带 errorCode/retryable/routeRole

字段细节看 设计文档 第六部分和 main.py 里的 Pydantic 模型。

九、验收总纲

每做完一个节点/接口,打开 实施与验收规范 第四部分,对着该节点的代码验收(你自检)和业务验收(交业务勾)两栏逐条过。全绿才算完。

7.5 KiB Raw Permalink Blame History