1844 lines
106 KiB
Markdown
1844 lines
106 KiB
Markdown
# 智链云枢托盘业务系统 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.
|
||
|
||
**Goal:** 移除 AI 管理和“施尔丰仓库”外链菜单，并在现有 Web/FastAPI 架构内实现具备真实权限、库存事务和完整追溯的托盘业务系统。
|
||
|
||
**Architecture:** 新增独立 module_business，继续使用 controller → service → dao → entity/do + entity/vo 分层。托盘以业务单据、当前库存快照和只追加事件流水组成聚合，所有状态变更由 Service 在单一事务中完成；Web 继续使用后端动态菜单和现有权限体系。
|
||
|
||
**Tech Stack:** Python 3.10+、FastAPI、Pydantic v2、异步 SQLAlchemy 2、MySQL/PostgreSQL 初始化 SQL、Vue 3、Element Plus、Pinia、Vite 6、后端 qrcode 8.2、Python unittest、Node 20 内置测试。
|
||
|
||
**Design:** ../specs/2026-07-24-pallet-workflow-system-design.md
|
||
|
||
---
|
||
|
||
## 执行安全边界
|
||
|
||
1. 当前工作区有用户未提交改动，尤其是 APP、环境文件、前端 package.json 和已暂存的 .idea/git_toolbox_prj.xml。每次提交都必须使用精确文件路径和 git commit --only，禁止提交或取消暂存用户文件；不得对任何可能包含 __pycache__ 的目录执行普通 git add。
|
||
2. 不修改 shierfeng-fastapi-app，不修改 .env.dev、.env.prod 或任何前端 .env 文件。
|
||
3. 不启动 app.py、server.py、uvicorn 或 shierfeng app run。启动生命周期会执行 Base.metadata.create_all()，可能写入本地 MySQL。
|
||
4. 不执行两套初始化 SQL 或 MySQL 增量补丁，不运行会连接业务数据库的 TestClient 生命周期或集成测试。
|
||
5. 如果实施开始时发现该项目后端进程正在运行，立即停止代码修改并请用户先关闭服务；不得主动终止未知进程。
|
||
6. Conda 环境没有 pytest，但有 ruff 0.15.0。新增测试统一使用 unittest.IsolatedAsyncioTestCase 和 unittest.mock。
|
||
7. 前端没有 lint、typecheck 或单元测试脚本。新增 Node 20 内置契约测试，不引入测试依赖；生产构建使用 Node v20.20.2 的绝对路径。
|
||
8. qrcode 8.2 的安装已获得用户确认；不安装、升级或卸载其他 Conda/npm 依赖。
|
||
9. package.json 已包含任务开始前的“智链云枢管理系统”修改。本任务必须保留该修改，但不得在没有额外确认时把它自动纳入提交；Task 1 的依赖删除和 Task 16 的 test:business 脚本允许留在工作区未提交。
|
||
10. 受保护改动当前基线 SHA-256 为：APP diff 6b7871be6b8cdede4c508adeb345e70084b01583403cfd0aab67e5b3beeb7e1c，环境文件 diff 5f1189e56551fc16485244e46c8e78cd32ce9ac9f0eaac91cfd0cf42b1ded57a，已暂存 .idea diff f21bea19dc68716136d77a3f1567659fd1af2f10f7b1fc6d246851dcfaa645c1。实施结束必须重新计算并完全一致。
|
||
11. 计划提交“文档：新增托盘业务实施计划”是后续实现历史的基线锚点；最终使用该提交到 HEAD 的完整路径历史检查 APP、.env、.idea、__pycache__ 和 .pyc，而不是只检查 HEAD~1。
|
||
|
||
## 文件结构
|
||
|
||
### 后端业务模块
|
||
|
||
~~~text
|
||
shierfeng-fastapi-backend/module_business/
|
||
├── domain/
|
||
│ ├── enums.py
|
||
│ └── pallet_state_machine.py
|
||
├── entity/
|
||
│ ├── do/
|
||
│ │ ├── master_do.py
|
||
│ │ └── operation_do.py
|
||
│ └── vo/
|
||
│ ├── master_vo.py
|
||
│ ├── operation_vo.py
|
||
│ └── report_vo.py
|
||
├── dao/
|
||
│ ├── access_dao.py
|
||
│ ├── master_dao.py
|
||
│ ├── inventory_dao.py
|
||
│ ├── operation_dao.py
|
||
│ └── report_dao.py
|
||
├── service/
|
||
│ ├── access_service.py
|
||
│ ├── master_service.py
|
||
│ ├── pallet_service.py
|
||
│ ├── inbound_service.py
|
||
│ ├── filling_service.py
|
||
│ ├── shipment_service.py
|
||
│ ├── usage_service.py
|
||
│ ├── return_service.py
|
||
│ └── report_service.py
|
||
└── controller/
|
||
├── strain_controller.py
|
||
├── customer_controller.py
|
||
├── site_controller.py
|
||
├── line_controller.py
|
||
├── warehouse_controller.py
|
||
├── pallet_controller.py
|
||
├── inbound_controller.py
|
||
├── filling_controller.py
|
||
├── shipment_controller.py
|
||
├── usage_controller.py
|
||
├── return_controller.py
|
||
└── report_controller.py
|
||
~~~
|
||
|
||
### 后端测试
|
||
|
||
~~~text
|
||
shierfeng-fastapi-backend/tests/module_business/
|
||
├── test_ai_removal_contract.py
|
||
├── test_state_machine.py
|
||
├── test_model_contract.py
|
||
├── test_vo_contract.py
|
||
├── test_access_service.py
|
||
├── test_master_service.py
|
||
├── test_pallet_service.py
|
||
├── test_inventory_dao.py
|
||
├── test_inbound_service.py
|
||
├── test_filling_service.py
|
||
├── test_shipment_service.py
|
||
├── test_usage_service.py
|
||
├── test_return_service.py
|
||
├── test_report_service.py
|
||
├── test_api_permission_contract.py
|
||
└── test_sql_contract.py
|
||
~~~
|
||
|
||
### Web
|
||
|
||
~~~text
|
||
shierfeng-fastapi-frontend/src/api/master/{strain,customer,site,line,warehouse,pallet}.js
|
||
shierfeng-fastapi-frontend/src/api/business/{inbound,filling,shipment,usage,return}.js
|
||
shierfeng-fastapi-frontend/src/api/report/{palletInventory,filling,shipment,consumption,return,palletTrace}.js
|
||
shierfeng-fastapi-frontend/src/views/master/{strain,customer,site,line,warehouse,pallet}/index.vue
|
||
shierfeng-fastapi-frontend/src/views/business/{inbound,filling,shipment,usage,return}/index.vue
|
||
shierfeng-fastapi-frontend/src/views/report/{palletInventory,filling,shipment,consumption,return,palletTrace}/index.vue
|
||
shierfeng-fastapi-frontend/src/components/PalletScanInput/index.vue
|
||
shierfeng-fastapi-frontend/src/components/BusinessUserAssignDialog/index.vue
|
||
shierfeng-fastapi-frontend/src/utils/palletScan.js
|
||
shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
### SQL
|
||
|
||
~~~text
|
||
shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql
|
||
shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql
|
||
shierfeng-fastapi-backend/sql/patches/20260724_pallet_workflow_mysql.sql
|
||
~~~
|
||
|
||
## 固定数据库与权限契约
|
||
|
||
业务表固定为 18 张：
|
||
|
||
~~~text
|
||
biz_strain
|
||
biz_warehouse
|
||
biz_customer
|
||
biz_customer_site
|
||
biz_production_line
|
||
biz_pallet
|
||
biz_user_warehouse
|
||
biz_user_site
|
||
biz_inbound_order
|
||
biz_inbound_item
|
||
biz_filling_record
|
||
biz_shipment_order
|
||
biz_shipment_item
|
||
biz_usage_record
|
||
biz_return_order
|
||
biz_return_item
|
||
biz_pallet_inventory
|
||
biz_pallet_event
|
||
~~~
|
||
|
||
菜单 ID 固定使用当前空闲区间，不复用已删除 AI/外链 ID：
|
||
|
||
- 121–123：基础资料维护、业务管理、报表查询。
|
||
- 502–518：6 个基础页面、5 个业务页面、6 个报表页面。
|
||
- 1065–1108：44 个按钮权限。
|
||
- 保留 sys_menu 的 auto_increment/restart 2000。
|
||
|
||
API 与权限固定使用设计稿中的 master:*、business:*、report:*，不改为 pallet:*。
|
||
|
||
### 18 张表的字段与约束
|
||
|
||
所有主数据和单据沿用项目审计列：create_by、create_time、update_by、update_time、remark。主数据 status/asset_status 使用 CHAR(1) 并 CHECK IN ('0', '1')，0=正常、1=停用；普通单据状态、退回状态、flow_state、event_type 使用 String(32)，分别按 DocumentStatus、ReturnStatus、PalletFlowState、PalletEventType 建 CHECK。以下字段名是 ORM、MySQL 和 PostgreSQL 的共同持久化契约；VO/报表如需展示名必须在本计划中显式声明映射，不能在实现时另起未记录的同义字段：
|
||
|
||
~~~text
|
||
BizStrain:
|
||
strain_id PK, strain_code UQ, strain_name, status + 审计字段
|
||
BizWarehouse:
|
||
warehouse_id PK, warehouse_code UQ, warehouse_name, address, status + 审计字段
|
||
BizCustomer:
|
||
customer_id PK, customer_code UQ, customer_name, status + 审计字段
|
||
BizCustomerSite:
|
||
site_id PK, customer_id FK, site_code, site_name, address, status,
|
||
UQ(customer_id, site_code) + 审计字段
|
||
BizProductionLine:
|
||
line_id PK, site_id FK, line_code, line_name, status,
|
||
UQ(site_id, line_code) + 审计字段
|
||
BizPallet:
|
||
pallet_id PK, pallet_code UQ, qr_token UQ, capacity_packages CHECK > 0,
|
||
asset_status + 审计字段
|
||
BizUserWarehouse:
|
||
user_id FK, warehouse_id FK, create_by, create_time,
|
||
PK(user_id, warehouse_id)
|
||
BizUserSite:
|
||
user_id FK, site_id FK, create_by, create_time,
|
||
PK(user_id, site_id)
|
||
|
||
BizInboundOrder:
|
||
inbound_id PK, inbound_no UQ, warehouse_id FK, status,
|
||
confirm_idempotency_key UQ NULL, confirm_request_hash NULL,
|
||
confirmed_by FK sys_user NULL, confirmed_at NULL + 审计字段
|
||
BizInboundItem:
|
||
inbound_item_id PK, inbound_id FK, pallet_id FK,
|
||
UQ(inbound_id, pallet_id), create_by, create_time
|
||
BizFillingRecord:
|
||
filling_id PK, filling_no UQ, pallet_id FK, warehouse_id FK, strain_id FK,
|
||
strain_code_snapshot, strain_name_snapshot, batch_no, package_spec,
|
||
initial_packages CHECK > 0, active_slot NULL, closed_at NULL,
|
||
idempotency_key UQ, request_hash, operator_id FK, operated_at,
|
||
UQ(pallet_id, active_slot) + 审计字段
|
||
BizShipmentOrder:
|
||
shipment_id PK, shipment_no UQ, source_warehouse_id FK, target_site_id FK,
|
||
status, confirm_idempotency_key UQ NULL, confirm_request_hash NULL,
|
||
confirmed_by FK sys_user NULL, confirmed_at NULL + 审计字段
|
||
BizShipmentItem:
|
||
shipment_item_id PK, shipment_id FK, pallet_id FK,
|
||
active_filling_id FK NULL, package_qty NULL CHECK(package_qty IS NULL OR package_qty > 0),
|
||
UQ(shipment_id, pallet_id), create_by, create_time
|
||
BizUsageRecord:
|
||
usage_id PK, usage_no UQ, pallet_id FK, active_filling_id FK,
|
||
site_id FK, line_id FK, used_packages CHECK > 0,
|
||
remaining_packages_after CHECK >= 0, idempotency_key UQ, request_hash,
|
||
operator_id FK, occurred_at
|
||
BizReturnOrder:
|
||
return_id PK, return_no UQ, source_site_id FK, target_warehouse_id FK,
|
||
status, request_idempotency_key UQ, request_hash,
|
||
confirm_idempotency_key UQ NULL, confirm_request_hash NULL,
|
||
requested_by FK sys_user, requested_at,
|
||
confirmed_by FK sys_user NULL, confirmed_at NULL + 审计字段
|
||
BizReturnItem:
|
||
return_item_id PK, return_id FK, pallet_id FK,
|
||
active_filling_id_snapshot FK NULL,
|
||
remaining_packages_snapshot CHECK >= 0,
|
||
UQ(return_id, pallet_id), create_by, create_time
|
||
BizPalletInventory:
|
||
pallet_id PK/FK, active_filling_id FK NULL,
|
||
warehouse_id FK NULL, site_id FK NULL, current_line_id FK NULL,
|
||
flow_state, remaining_packages CHECK >= 0,
|
||
last_event_id FK NULL, version CHECK >= 0, updated_at
|
||
BizPalletEvent:
|
||
event_id PK, pallet_id FK, event_seq, event_type, source_type, source_id,
|
||
before_state, after_state,
|
||
before_warehouse_id, before_site_id, before_line_id,
|
||
after_warehouse_id, after_site_id, after_line_id,
|
||
before_remaining_packages, after_remaining_packages,
|
||
operator_id FK, occurred_at, idempotency_key, request_hash,
|
||
UQ(pallet_id, event_seq), UQ(pallet_id, idempotency_key)
|
||
~~~
|
||
|
||
额外约束固定如下：
|
||
|
||
- active_slot 仅在装填周期活动时写 ACTIVE，周期关闭时置 NULL；数据库同时建立 CHECK(active_slot IS NULL OR active_slot = 'ACTIVE') 和 UQ(pallet_id, active_slot)，在 MySQL/PostgreSQL 下共同保证单托盘最多一条活动装填记录。
|
||
- BizPalletInventory.current_line_id 是当前驻场周期的产线锁权威字段；首次使用设置，退回确认清空。历史产线由 BizUsageRecord.line_id 和 BizPalletEvent 保存，不在 BizPallet 主数据上保存。
|
||
- 余量归零时同时关闭装填记录、清 active_slot、写 closed_at 并清 inventory.active_filling_id；带料退回保留活动装填记录和 active_filling_id，再次发货后可重新绑定产线。
|
||
- RETURNING 期间仍保留 source site 和 current_line_id，直到仓库确认；UNSTOCKED 两个位置均为空，仓库状态只能有 warehouse_id，现场状态只能有 site_id。
|
||
- remaining_packages 不得超过 BizPallet.capacity_packages；该跨表约束由 Service 在持锁后校验，数据库保留非负检查。
|
||
- request_hash 是对规范化请求业务字段计算的 SHA-256：对象键排序，pallet_ids/scanned_pallet_ids 去重后按数值排序，不包含时间、操作人或随机字段；同一幂等键同一 hash 返回原结果，同键不同 hash 返回失败。
|
||
- 幂等重试返回既有结果前仍必须重新执行当前用户的接口权限和 warehouse/site 数据范围校验，不能用幂等键绕过授权或探测其他用户单据。
|
||
- 每次成功的托盘状态或数量变更都必须在持锁事务内把 inventory.version 精确加 1，并同步 last_event_id；幂等重试不得再次增加 version 或追加事件。
|
||
|
||
### 菜单页面固定映射
|
||
|
||
目录 121、122、123 的 parent_id 均为系统管理 1，menu_type=M，perms 为空。页面 menu_type=C，映射固定如下；全部新目录/页面使用 visible=0、status=0、is_frame=1、is_cache=0，按钮的 path/component/route_name 为空：
|
||
|
||
| ID | parent | 菜单名 | path | component | API 前缀 | 页面权限 |
|
||
|---:|---:|---|---|---|---|---|
|
||
| 502 | 121 | 菌种资料 | strain | master/strain/index | /master/strain | master:strain:list |
|
||
| 503 | 121 | 客户资料 | customer | master/customer/index | /master/customer | master:customer:list |
|
||
| 504 | 121 | 客户现场 | site | master/site/index | /master/site | master:site:list |
|
||
| 505 | 121 | 产线资料 | line | master/line/index | /master/line | master:line:list |
|
||
| 506 | 121 | 仓库资料 | warehouse | master/warehouse/index | /master/warehouse | master:warehouse:list |
|
||
| 507 | 121 | 托盘资料 | pallet | master/pallet/index | /master/pallet | master:pallet:list |
|
||
| 508 | 122 | 仓库入库 | inbound | business/inbound/index | /business/inbound | business:inbound:list |
|
||
| 509 | 122 | 工厂装填 | filling | business/filling/index | /business/filling | business:filling:list |
|
||
| 510 | 122 | 发货出库 | shipment | business/shipment/index | /business/shipment | business:shipment:list |
|
||
| 511 | 122 | 客户现场使用 | usage | business/usage/index | /business/usage | business:usage:list |
|
||
| 512 | 122 | 退回仓库 | return | business/return/index | /business/return | business:return:list |
|
||
| 513 | 123 | 托盘库存 | palletInventory | report/palletInventory/index | /report/pallet-inventory | report:palletinventory:list |
|
||
| 514 | 123 | 装填记录 | reportFilling | report/filling/index | /report/filling | report:filling:list |
|
||
| 515 | 123 | 发货出库 | reportShipment | report/shipment/index | /report/shipment | report:shipment:list |
|
||
| 516 | 123 | 产线消耗 | consumption | report/consumption/index | /report/consumption | report:consumption:list |
|
||
| 517 | 123 | 退回仓库 | reportReturn | report/return/index | /report/return | report:return:list |
|
||
| 518 | 123 | 托盘追溯 | palletTrace | report/palletTrace/index | /report/pallet-trace | report:pallettrace:list |
|
||
|
||
17 个页面的 route_name 固定为空字符串，运行时名称由唯一 path 生成；reportFilling、reportShipment、reportReturn 必须保持当前唯一 path，不能改成业务页面已使用的 filling、shipment、return。三个目录的 path 分别固定为 businessMaster、businessOperation、businessReport，order_num 分别为 10、11、12。页面 502–507、508–512、513–518 在各自目录内的 order_num 均从 1 连续递增。
|
||
|
||
### 按钮 ID 固定映射
|
||
|
||
以下 44 行 menu_type=F，order_num 是同一页面内的顺序；六个报表没有按钮权限：
|
||
|
||
~~~text
|
||
1065 parent=502 order=1 菌种查询 master:strain:query
|
||
1066 parent=502 order=2 菌种新增 master:strain:add
|
||
1067 parent=502 order=3 菌种修改 master:strain:edit
|
||
1068 parent=502 order=4 菌种删除 master:strain:remove
|
||
1069 parent=503 order=1 客户查询 master:customer:query
|
||
1070 parent=503 order=2 客户新增 master:customer:add
|
||
1071 parent=503 order=3 客户修改 master:customer:edit
|
||
1072 parent=503 order=4 客户删除 master:customer:remove
|
||
1073 parent=504 order=1 现场查询 master:site:query
|
||
1074 parent=504 order=2 现场新增 master:site:add
|
||
1075 parent=504 order=3 现场修改 master:site:edit
|
||
1076 parent=504 order=4 现场删除 master:site:remove
|
||
1077 parent=504 order=5 分配用户 master:site:assign
|
||
1078 parent=505 order=1 产线查询 master:line:query
|
||
1079 parent=505 order=2 产线新增 master:line:add
|
||
1080 parent=505 order=3 产线修改 master:line:edit
|
||
1081 parent=505 order=4 产线删除 master:line:remove
|
||
1082 parent=506 order=1 仓库查询 master:warehouse:query
|
||
1083 parent=506 order=2 仓库新增 master:warehouse:add
|
||
1084 parent=506 order=3 仓库修改 master:warehouse:edit
|
||
1085 parent=506 order=4 仓库删除 master:warehouse:remove
|
||
1086 parent=506 order=5 分配用户 master:warehouse:assign
|
||
1087 parent=507 order=1 托盘查询 master:pallet:query
|
||
1088 parent=507 order=2 托盘新增 master:pallet:add
|
||
1089 parent=507 order=3 托盘修改 master:pallet:edit
|
||
1090 parent=507 order=4 托盘删除 master:pallet:remove
|
||
1091 parent=507 order=5 托盘打印 master:pallet:print
|
||
1092 parent=508 order=1 入库查询 business:inbound:query
|
||
1093 parent=508 order=2 入库新增 business:inbound:add
|
||
1094 parent=508 order=3 入库修改 business:inbound:edit
|
||
1095 parent=508 order=4 入库删除 business:inbound:remove
|
||
1096 parent=508 order=5 入库确认 business:inbound:confirm
|
||
1097 parent=509 order=1 装填查询 business:filling:query
|
||
1098 parent=509 order=2 装填新增 business:filling:add
|
||
1099 parent=510 order=1 发货查询 business:shipment:query
|
||
1100 parent=510 order=2 发货新增 business:shipment:add
|
||
1101 parent=510 order=3 发货修改 business:shipment:edit
|
||
1102 parent=510 order=4 发货删除 business:shipment:remove
|
||
1103 parent=510 order=5 发货确认 business:shipment:confirm
|
||
1104 parent=511 order=1 使用查询 business:usage:query
|
||
1105 parent=511 order=2 使用新增 business:usage:add
|
||
1106 parent=512 order=1 退回查询 business:return:query
|
||
1107 parent=512 order=2 退回申请 business:return:request
|
||
1108 parent=512 order=3 退回确认 business:return:confirm
|
||
~~~
|
||
|
||
### HTTP、扫码和 Service 固定契约
|
||
|
||
六类 master 资源都提供 GET /list、GET /{resource_id}、POST 根路径、PUT 根路径、DELETE /{resource_ids}，依次使用 list/query/add/edit/remove 权限；参数名分别固定为 strain_id(s)、customer_id(s)、site_id(s)、line_id(s)、warehouse_id(s)、pallet_id(s)。额外接口为 GET/PUT /master/site/{site_id}/users、GET/PUT /master/warehouse/{warehouse_id}/users（assign）和 GET /master/pallet/{pallet_id}/qrcode（print）。
|
||
|
||
| 资源 | 固定接口 | 权限 |
|
||
|---|---|---|
|
||
| inbound | GET /business/inbound/list；GET /business/inbound/scan/{qr_token}；GET /business/inbound/{inbound_id}；POST /business/inbound；PUT /business/inbound；DELETE /business/inbound/{inbound_ids}；PUT /business/inbound/{inbound_id}/confirm | list；query；query；add；edit；remove；confirm |
|
||
| filling | GET /business/filling/list；GET /business/filling/scan/{qr_token}；GET /business/filling/{filling_id}；POST /business/filling | list；query；query；add |
|
||
| shipment | GET /business/shipment/list；GET /business/shipment/scan/{qr_token}；GET /business/shipment/{shipment_id}；POST /business/shipment；PUT /business/shipment；DELETE /business/shipment/{shipment_ids}；PUT /business/shipment/{shipment_id}/confirm | list；query；query；add；edit；remove；confirm |
|
||
| usage | GET /business/usage/list；GET /business/usage/scan/{qr_token}；GET /business/usage/{usage_id}；POST /business/usage | list；query；query；add |
|
||
| return | GET /business/return/list；GET /business/return/scan/{qr_token}；GET /business/return/{return_id}；POST /business/return/request；PUT /business/return/{return_id}/confirm | list；query；query；request；confirm |
|
||
|
||
五个 /scan/{qr_token} 必须在对应资源的动态详情路由之前声明，且复用本资源 query 权限，不新增 scan 权限。扫码上下文查询参数固定为：inbound 使用 warehouseId；shipment 使用 sourceWarehouseId 和 targetSiteId；return 使用 mode=request 或 mode=confirm，confirm 模式同时传 returnId；filling、usage 不需要额外上下文。后端必须重新校验这些 ID，不信任前端选择。
|
||
|
||
业务人员不应为了填写单据而获得 master:*:list，因此各业务 Controller 还提供以下只读选项接口，全部在对应资源的动态详情路由之前声明并复用本资源 query 权限：
|
||
|
||
~~~text
|
||
GET /business/inbound/warehouse-options
|
||
GET /business/filling/strain-options
|
||
GET /business/shipment/warehouse-options
|
||
GET /business/shipment/site-options
|
||
GET /business/usage/line-options?siteId={site_id}
|
||
GET /business/return/warehouse-options
|
||
~~~
|
||
|
||
inbound/shipment 的 warehouse 和 shipment site 选项仅返回当前用户关联且启用的数据；usage line 只返回用户已授权 site 下的启用产线；filling strain 返回启用 SKU。return warehouse 是客户发起退回所需的目标字典，只返回所有启用仓库的 id/code/name，不要求发起人拥有仓库数据权限；真正确认仍必须校验确认人对目标仓库的关联。六个报表只提供各自 GET /list；不存在导出或写接口。
|
||
|
||
核心 Service 签名固定为：
|
||
|
||
~~~text
|
||
confirm_inbound_services(AsyncSession, int, ConfirmCommandModel, CurrentUserModel) -> CrudResponseModel
|
||
fill_pallet_services(AsyncSession, FillingCreateModel, CurrentUserModel) -> CrudResponseModel
|
||
confirm_shipment_services(AsyncSession, int, ConfirmCommandModel, CurrentUserModel) -> CrudResponseModel
|
||
record_usage_services(AsyncSession, UsageCreateModel, CurrentUserModel) -> CrudResponseModel
|
||
request_return_services(AsyncSession, ReturnRequestModel, CurrentUserModel) -> CrudResponseModel
|
||
confirm_return_services(AsyncSession, int, ReturnConfirmModel, CurrentUserModel) -> CrudResponseModel
|
||
~~~
|
||
|
||
对应 page_object 类型依次为 ConfirmCommandModel、FillingCreateModel、ConfirmCommandModel、UsageCreateModel、ReturnRequestModel、ReturnConfirmModel；返回类型统一 CrudResponseModel，current_user 统一 CurrentUserModel。
|
||
|
||
---
|
||
|
||
### Task 1: 删除 AI 专属能力和外链菜单种子
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_ai_removal_contract.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/controller/ai_chat_controller.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/controller/ai_model_controller.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/dao/ai_chat_dao.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/dao/ai_model_dao.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/entity/do/ai_chat_do.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/entity/do/ai_model_do.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/entity/vo/ai_chat_vo.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/entity/vo/ai_model_vo.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/service/ai_chat_service.py
|
||
- Delete: shierfeng-fastapi-backend/module_ai/service/ai_model_service.py
|
||
- Delete: shierfeng-fastapi-backend/utils/ai_util.py
|
||
- Delete: shierfeng-fastapi-backend/utils/crypto_util.py
|
||
- Delete: shierfeng-fastapi-frontend/src/api/ai/chat.js
|
||
- Delete: shierfeng-fastapi-frontend/src/api/ai/model.js
|
||
- Delete: shierfeng-fastapi-frontend/src/views/ai/chat/components/AiMessage.vue
|
||
- Delete: shierfeng-fastapi-frontend/src/views/ai/chat/index.vue
|
||
- Delete: shierfeng-fastapi-frontend/src/views/ai/model/index.vue
|
||
- Delete: shierfeng-fastapi-frontend/src/assets/icons/svg/ai-chat.svg
|
||
- Delete: shierfeng-fastapi-frontend/src/assets/icons/svg/ai-manage.svg
|
||
- Delete: shierfeng-fastapi-frontend/src/assets/icons/svg/ai-model.svg
|
||
- Modify: shierfeng-fastapi-backend/common/constant.py
|
||
- Modify: shierfeng-fastapi-backend/common/annotation/rate_limit_annotation.py
|
||
- Modify: shierfeng-fastapi-backend/utils/log_util.py:593
|
||
- Modify: shierfeng-fastapi-backend/requirements.txt
|
||
- Modify: shierfeng-fastapi-backend/requirements-pg.txt
|
||
- Modify: shierfeng-fastapi-frontend/package.json
|
||
- Modify: shierfeng-fastapi-frontend/vite/plugins/index.js
|
||
- Modify: shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql
|
||
- Modify: shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql
|
||
- Modify: README.md
|
||
- Modify: CHANGELOG.md
|
||
|
||
- [ ] **Step 1: 写删除契约测试**
|
||
|
||
~~~python
|
||
import json
|
||
from pathlib import Path
|
||
import re
|
||
import unittest
|
||
|
||
|
||
class AiRemovalContractTest(unittest.TestCase):
|
||
root = Path(__file__).resolve().parents[3]
|
||
|
||
def test_ai_source_files_are_removed(self):
|
||
module_root = self.root / 'shierfeng-fastapi-backend/module_ai'
|
||
remaining = list(module_root.rglob('*.py')) if module_root.exists() else []
|
||
explicit_files = (
|
||
'shierfeng-fastapi-backend/utils/ai_util.py',
|
||
'shierfeng-fastapi-backend/utils/crypto_util.py',
|
||
'shierfeng-fastapi-frontend/src/api/ai/chat.js',
|
||
'shierfeng-fastapi-frontend/src/api/ai/model.js',
|
||
'shierfeng-fastapi-frontend/src/views/ai/chat/components/AiMessage.vue',
|
||
'shierfeng-fastapi-frontend/src/views/ai/chat/index.vue',
|
||
'shierfeng-fastapi-frontend/src/views/ai/model/index.vue',
|
||
'shierfeng-fastapi-frontend/src/assets/icons/svg/ai-chat.svg',
|
||
'shierfeng-fastapi-frontend/src/assets/icons/svg/ai-manage.svg',
|
||
'shierfeng-fastapi-frontend/src/assets/icons/svg/ai-model.svg',
|
||
)
|
||
remaining.extend(self.root / path for path in explicit_files if (self.root / path).is_file())
|
||
self.assertEqual([], [str(path.relative_to(self.root)) for path in remaining])
|
||
|
||
def test_ai_dependencies_are_removed(self):
|
||
backend_forbidden = {
|
||
'agno', 'anthropic', 'cerebras-cloud-sdk', 'cohere', 'google-genai',
|
||
'groq', 'litellm', 'llama-api-client', 'mistralai', 'ollama',
|
||
'openai', 'portkey-ai',
|
||
}
|
||
for name in ('requirements.txt', 'requirements-pg.txt'):
|
||
content = (self.root / 'shierfeng-fastapi-backend' / name).read_text(encoding='utf-8')
|
||
installed = {
|
||
re.split(r'[<>=!~;\[]', line, maxsplit=1)[0].strip().lower()
|
||
for line in content.splitlines()
|
||
if line.strip() and not line.lstrip().startswith('#')
|
||
}
|
||
self.assertTrue(backend_forbidden.isdisjoint(installed), backend_forbidden & installed)
|
||
|
||
package = json.loads(
|
||
(self.root / 'shierfeng-fastapi-frontend/package.json').read_text(encoding='utf-8')
|
||
)
|
||
installed = set(package.get('dependencies', {})) | set(package.get('devDependencies', {}))
|
||
frontend_forbidden = {
|
||
'katex', 'markstream-vue', 'mermaid', 'shiki', 'stream-markdown',
|
||
'stream-monaco', 'uuid', 'vite-plugin-monaco-editor-esm',
|
||
}
|
||
self.assertTrue(frontend_forbidden.isdisjoint(installed), frontend_forbidden & installed)
|
||
|
||
def test_initialization_sql_has_no_ai_or_external_menu(self):
|
||
for name in ('shierfeng-fastapi.sql', 'shierfeng-fastapi-pg.sql'):
|
||
content = (self.root / 'shierfeng-fastapi-backend/sql' / name).read_text(encoding='utf-8')
|
||
self.assertNotIn('ai_models', content)
|
||
self.assertNotIn('ai_chat_config', content)
|
||
self.assertNotIn('ai_provider_type', content)
|
||
self.assertNotIn('施尔丰仓库', content)
|
||
~~~
|
||
|
||
- [ ] **Step 2: 运行测试并确认当前失败**
|
||
|
||
Run from shierfeng-fastapi-backend:
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_ai_removal_contract -v
|
||
~~~
|
||
|
||
Expected: FAIL，列出仍存在的 AI 路径、依赖和初始化 SQL 内容。
|
||
|
||
- [ ] **Step 3: 删除专属文件并局部清理共享文件**
|
||
|
||
仅删除文件清单中的 20 个跟踪源码/资源文件，不递归删除 module_ai 目录，不清理、不暂存现有 __pycache__ 和 .pyc；目录因未跟踪缓存继续存在不视为失败。common/constant.py 仅删除 6 个 AI namespace、DATA_SCOPE_MUTATION 中 3 个 AI 成员、AI_MODEL_MUTATION 和 AI_CHAT_CONFIG_MUTATION；rate_limit_annotation.py 仅删除 USER_INTERACTIVE_HIGH_FREQ；log_util.py 仅删除 LiteLLM 特殊日志级别；保留 transport_crypto_util.py 和通用脱敏测试。
|
||
|
||
requirements 两份文件删除以下 12 项，并增加 qrcode==8.2：
|
||
|
||
~~~text
|
||
agno
|
||
anthropic
|
||
cerebras-cloud-sdk
|
||
cohere
|
||
google-genai
|
||
groq
|
||
litellm
|
||
llama-api-client
|
||
mistralai
|
||
ollama
|
||
openai
|
||
portkey-ai
|
||
~~~
|
||
|
||
package.json 仅删除 katex、markstream-vue、mermaid、shiki、stream-markdown、stream-monaco、uuid 和 vite-plugin-monaco-editor-esm，保留用户已有的“智链云枢管理系统”描述；vite/plugins/index.js 删除 Monaco 导入、worker 配置和插件注册。README 删除当前 AI 功能描述；CHANGELOG 在最新章节增加移除记录，但保留历史新增记录。
|
||
|
||
- [ ] **Step 4: 清理两套初始化 SQL**
|
||
|
||
删除菜单 4、118、119、1061–1064、角色 2 到菜单 4 的映射、ai_provider_type 字典和 ai_models/ai_chat_config DDL；删除菜单 99。保留其他菜单 ID、字典 ID、序列和 auto_increment，不删除 CHANGELOG 中历史新增记录。
|
||
|
||
- [ ] **Step 5: 安装已批准的二维码依赖**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m pip install qrcode==8.2
|
||
~~~
|
||
|
||
Expected: Successfully installed qrcode-8.2；不得安装或升级其他项目依赖。
|
||
|
||
- [ ] **Step 6: 运行删除契约、OpenAPI 和静态检查**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_ai_removal_contract -v
|
||
conda run -n ShiErFeng python -c "from server import create_app; app=create_app(); assert not any(path.startswith('/ai/') for path in app.openapi()['paths'])"
|
||
conda run -n ShiErFeng python -m ruff check common/constant.py common/annotation/rate_limit_annotation.py utils/log_util.py tests/module_business/test_ai_removal_contract.py
|
||
~~~
|
||
|
||
Expected: 全部通过；OpenAPI 不包含 /ai/*。静态残留检查不得把 CHANGELOG、设计文档和未来补丁中的清理语句误判为代码残留。
|
||
|
||
- [ ] **Step 7: 核对并提交不重叠文件**
|
||
|
||
~~~bash
|
||
git status --short --untracked-files=all
|
||
git diff --cached --name-status
|
||
git add -- shierfeng-fastapi-backend/tests/module_business/test_ai_removal_contract.py
|
||
git commit --only -m "重构：移除 AI 管理模块" -- README.md CHANGELOG.md shierfeng-fastapi-backend/module_ai shierfeng-fastapi-backend/utils/ai_util.py shierfeng-fastapi-backend/utils/crypto_util.py shierfeng-fastapi-backend/common/constant.py shierfeng-fastapi-backend/common/annotation/rate_limit_annotation.py shierfeng-fastapi-backend/utils/log_util.py shierfeng-fastapi-backend/requirements.txt shierfeng-fastapi-backend/requirements-pg.txt shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql shierfeng-fastapi-backend/tests/module_business/test_ai_removal_contract.py shierfeng-fastapi-frontend/src/api/ai shierfeng-fastapi-frontend/src/views/ai shierfeng-fastapi-frontend/src/assets/icons/svg/ai-chat.svg shierfeng-fastapi-frontend/src/assets/icons/svg/ai-manage.svg shierfeng-fastapi-frontend/src/assets/icons/svg/ai-model.svg shierfeng-fastapi-frontend/vite/plugins/index.js
|
||
~~~
|
||
|
||
不得执行 git add -A，不得对 module_ai 目录执行普通 git add。package.json 的依赖删除保留在工作区但不纳入该提交，因为同一文件含有任务开始前的用户品牌修改；现有 .idea 暂存状态必须原样保留。
|
||
|
||
### Task 2: 实现纯托盘状态机
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/domain/enums.py
|
||
- Create: shierfeng-fastapi-backend/module_business/domain/pallet_state_machine.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_state_machine.py
|
||
|
||
- [ ] **Step 1: 写状态迁移失败测试**
|
||
|
||
~~~python
|
||
import unittest
|
||
from module_business.domain.enums import PalletFlowState
|
||
from module_business.domain.pallet_state_machine import InvalidPalletTransition, PalletStateMachine
|
||
|
||
|
||
class PalletStateMachineTest(unittest.TestCase):
|
||
def test_confirmed_flow_is_allowed(self):
|
||
allowed = (
|
||
(PalletFlowState.UNSTOCKED, PalletFlowState.EMPTY_IN_WAREHOUSE),
|
||
(PalletFlowState.EMPTY_IN_WAREHOUSE, PalletFlowState.FILLED_IN_WAREHOUSE),
|
||
(PalletFlowState.FILLED_IN_WAREHOUSE, PalletFlowState.AT_SITE_UNUSED),
|
||
(PalletFlowState.AT_SITE_UNUSED, PalletFlowState.AT_SITE_PARTIAL),
|
||
(PalletFlowState.AT_SITE_UNUSED, PalletFlowState.AT_SITE_EMPTY),
|
||
(PalletFlowState.AT_SITE_UNUSED, PalletFlowState.RETURNING),
|
||
(PalletFlowState.AT_SITE_PARTIAL, PalletFlowState.AT_SITE_PARTIAL),
|
||
(PalletFlowState.AT_SITE_PARTIAL, PalletFlowState.AT_SITE_EMPTY),
|
||
(PalletFlowState.AT_SITE_PARTIAL, PalletFlowState.RETURNING),
|
||
(PalletFlowState.AT_SITE_EMPTY, PalletFlowState.RETURNING),
|
||
(PalletFlowState.RETURNING, PalletFlowState.FILLED_IN_WAREHOUSE),
|
||
(PalletFlowState.RETURNING, PalletFlowState.EMPTY_IN_WAREHOUSE),
|
||
)
|
||
for current, target in allowed:
|
||
PalletStateMachine.ensure_transition(current, target)
|
||
|
||
def test_refill_at_customer_site_is_rejected(self):
|
||
with self.assertRaises(InvalidPalletTransition):
|
||
PalletStateMachine.ensure_transition(
|
||
PalletFlowState.AT_SITE_EMPTY,
|
||
PalletFlowState.FILLED_IN_WAREHOUSE,
|
||
)
|
||
~~~
|
||
|
||
- [ ] **Step 2: 运行测试并确认导入失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_state_machine -v
|
||
~~~
|
||
|
||
Expected: FAIL with ModuleNotFoundError: module_business.domain。
|
||
|
||
- [ ] **Step 3: 实现枚举和迁移表**
|
||
|
||
~~~python
|
||
from enum import Enum
|
||
|
||
|
||
class PalletFlowState(str, Enum):
|
||
UNSTOCKED = 'UNSTOCKED'
|
||
EMPTY_IN_WAREHOUSE = 'EMPTY_IN_WAREHOUSE'
|
||
FILLED_IN_WAREHOUSE = 'FILLED_IN_WAREHOUSE'
|
||
AT_SITE_UNUSED = 'AT_SITE_UNUSED'
|
||
AT_SITE_PARTIAL = 'AT_SITE_PARTIAL'
|
||
AT_SITE_EMPTY = 'AT_SITE_EMPTY'
|
||
RETURNING = 'RETURNING'
|
||
|
||
|
||
class DocumentStatus(str, Enum):
|
||
DRAFT = 'DRAFT'
|
||
CONFIRMED = 'CONFIRMED'
|
||
|
||
|
||
class ReturnStatus(str, Enum):
|
||
REQUESTED = 'REQUESTED'
|
||
CONFIRMED = 'CONFIRMED'
|
||
|
||
|
||
class PalletEventType(str, Enum):
|
||
INBOUND_CONFIRMED = 'INBOUND_CONFIRMED'
|
||
FILLING_CONFIRMED = 'FILLING_CONFIRMED'
|
||
SHIPMENT_CONFIRMED = 'SHIPMENT_CONFIRMED'
|
||
USAGE_RECORDED = 'USAGE_RECORDED'
|
||
RETURN_REQUESTED = 'RETURN_REQUESTED'
|
||
RETURN_CONFIRMED = 'RETURN_CONFIRMED'
|
||
~~~
|
||
|
||
pallet_state_machine.py 定义与测试 allowed 元组完全相同的唯一迁移集合，允许未使用/部分使用/空托盘发起退回，并根据退回余量允许 RETURNING 回到 FILLED_IN_WAREHOUSE 或 EMPTY_IN_WAREHOUSE；不提供任意状态赋值入口。使用 str + Enum 兼容项目声明的 Python 3.10，不使用 Python 3.11 才提供的 StrEnum。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_state_machine -v
|
||
conda run -n ShiErFeng python -m ruff check module_business/domain tests/module_business/test_state_machine.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/domain/enums.py shierfeng-fastapi-backend/module_business/domain/pallet_state_machine.py shierfeng-fastapi-backend/tests/module_business/test_state_machine.py
|
||
git commit --only -m "功能：新增托盘状态机" -- shierfeng-fastapi-backend/module_business/domain/enums.py shierfeng-fastapi-backend/module_business/domain/pallet_state_machine.py shierfeng-fastapi-backend/tests/module_business/test_state_machine.py
|
||
~~~
|
||
|
||
### Task 3: 建立 18 张业务 ORM 模型
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/entity/do/master_do.py
|
||
- Create: shierfeng-fastapi-backend/module_business/entity/do/operation_do.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_model_contract.py
|
||
|
||
- [ ] **Step 1: 写元数据契约测试**
|
||
|
||
~~~python
|
||
import unittest
|
||
from config.database import Base
|
||
from module_business.entity.do import master_do, operation_do
|
||
|
||
|
||
class BusinessModelContractTest(unittest.TestCase):
|
||
def test_exact_business_tables_are_registered(self):
|
||
expected = {
|
||
'biz_strain', 'biz_warehouse', 'biz_customer', 'biz_customer_site',
|
||
'biz_production_line', 'biz_pallet', 'biz_user_warehouse', 'biz_user_site',
|
||
'biz_inbound_order', 'biz_inbound_item', 'biz_filling_record',
|
||
'biz_shipment_order', 'biz_shipment_item', 'biz_usage_record',
|
||
'biz_return_order', 'biz_return_item', 'biz_pallet_inventory',
|
||
'biz_pallet_event',
|
||
}
|
||
actual = {name for name in Base.metadata.tables if name.startswith('biz_')}
|
||
self.assertEqual(expected, actual)
|
||
|
||
def test_pallet_identifiers_are_unique(self):
|
||
table = Base.metadata.tables['biz_pallet']
|
||
unique_columns = {column.name for column in table.columns if column.unique}
|
||
self.assertEqual({'pallet_code', 'qr_token'}, unique_columns)
|
||
~~~
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_model_contract -v
|
||
~~~
|
||
|
||
Expected: FAIL，module_business.entity.do 不存在。
|
||
|
||
- [ ] **Step 3: 创建主数据模型**
|
||
|
||
master_do.py 创建 BizStrain、BizWarehouse、BizCustomer、BizCustomerSite、BizProductionLine、BizPallet、BizUserWarehouse、BizUserSite。字段和约束逐项实现“18 张表的字段与约束”章节，不增加第 19 张 biz_* 表。所有主数据使用 BigInteger 主键、UTF-8 字符串编码、CHAR(1) 状态和 0/1 CHECK、创建/更新时间；用户关联表使用 user_id + resource_id 联合主键和明确 ForeignKey。
|
||
|
||
关键列必须精确满足：
|
||
|
||
~~~text
|
||
BizStrain: strain_id, strain_code UQ, strain_name, status, remark
|
||
BizWarehouse: warehouse_id, warehouse_code UQ, warehouse_name, address, status, remark
|
||
BizCustomer: customer_id, customer_code UQ, customer_name, status, remark
|
||
BizCustomerSite: site_id, customer_id FK, site_code, site_name, address, status, UQ(customer_id, site_code)
|
||
BizProductionLine: line_id, site_id FK, line_code, line_name, status, UQ(site_id, line_code)
|
||
BizPallet: pallet_id, pallet_code UQ, qr_token UQ, capacity_packages CHECK > 0, asset_status, remark
|
||
BizUserWarehouse: user_id FK sys_user, warehouse_id FK biz_warehouse
|
||
BizUserSite: user_id FK sys_user, site_id FK biz_customer_site
|
||
~~~
|
||
|
||
- [ ] **Step 4: 创建业务模型**
|
||
|
||
operation_do.py 创建 10 张业务表，字段逐项实现“18 张表的字段与约束”章节。单据、退回、流转和事件状态统一使用 String(32) + 各自 CheckConstraint，不使用方言原生 Enum。包数字段使用 Integer，检查约束固定为初始量 > 0、使用量 > 0、余量 >= 0；BizReturnItem 必须包含 active_filling_id_snapshot 和 remaining_packages_snapshot，BizFillingRecord 必须保存 strain_code_snapshot、strain_name_snapshot、active_slot、closed_at 和 request_hash。
|
||
|
||
关键唯一约束：
|
||
|
||
~~~text
|
||
biz_inbound_order.inbound_no
|
||
biz_inbound_order.confirm_idempotency_key
|
||
biz_filling_record.filling_no
|
||
biz_filling_record.idempotency_key
|
||
(biz_filling_record.pallet_id, active_slot)
|
||
biz_shipment_order.shipment_no
|
||
biz_shipment_order.confirm_idempotency_key
|
||
biz_usage_record.usage_no
|
||
biz_usage_record.idempotency_key
|
||
biz_return_order.return_no
|
||
biz_return_order.request_idempotency_key
|
||
biz_return_order.confirm_idempotency_key
|
||
(biz_inbound_item.inbound_id, pallet_id)
|
||
(biz_shipment_item.shipment_id, pallet_id)
|
||
(biz_return_item.return_id, pallet_id)
|
||
biz_pallet_inventory.pallet_id
|
||
(biz_pallet_event.pallet_id, event_seq)
|
||
(biz_pallet_event.pallet_id, idempotency_key)
|
||
~~~
|
||
|
||
biz_pallet_inventory 必须包含 active_filling_id、warehouse_id、site_id、current_line_id、flow_state、remaining_packages、last_event_id、version、updated_at；仓库和现场位置不能同时非空。元数据测试还要断言 BizReturnItem 和 BizFillingRecord 的上述快照/活动字段存在，并断言精确 18 张 biz_* 表而非子集。
|
||
|
||
- [ ] **Step 5: 运行元数据测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_model_contract -v
|
||
conda run -n ShiErFeng python -m ruff check module_business/entity/do tests/module_business/test_model_contract.py
|
||
~~~
|
||
|
||
Expected: PASS；不连接数据库。
|
||
|
||
- [ ] **Step 6: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/entity/do/master_do.py shierfeng-fastapi-backend/module_business/entity/do/operation_do.py shierfeng-fastapi-backend/tests/module_business/test_model_contract.py
|
||
git commit --only -m "功能：新增托盘业务数据模型" -- shierfeng-fastapi-backend/module_business/entity/do/master_do.py shierfeng-fastapi-backend/module_business/entity/do/operation_do.py shierfeng-fastapi-backend/tests/module_business/test_model_contract.py
|
||
~~~
|
||
|
||
### Task 4: 固化 Pydantic 输入输出契约
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/entity/vo/master_vo.py
|
||
- Create: shierfeng-fastapi-backend/module_business/entity/vo/operation_vo.py
|
||
- Create: shierfeng-fastapi-backend/module_business/entity/vo/report_vo.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_vo_contract.py
|
||
|
||
- [ ] **Step 1: 写别名和数量边界测试**
|
||
|
||
~~~python
|
||
import unittest
|
||
from pydantic import ValidationError
|
||
from module_business.entity.vo.operation_vo import FillingCreateModel, UsageCreateModel
|
||
|
||
|
||
class BusinessVoContractTest(unittest.TestCase):
|
||
def test_filling_accepts_camel_case_and_positive_packages(self):
|
||
model = FillingCreateModel.model_validate({
|
||
'qrToken': 'qr-12345678',
|
||
'warehouseId': 1,
|
||
'strainId': 2,
|
||
'batchNo': 'B20260724',
|
||
'packageSpec': '20kg/包',
|
||
'initialPackages': 10,
|
||
'idempotencyKey': 'fill-key-1',
|
||
})
|
||
self.assertEqual(10, model.initial_packages)
|
||
|
||
def test_usage_rejects_zero_packages(self):
|
||
with self.assertRaises(ValidationError):
|
||
UsageCreateModel.model_validate({
|
||
'qrToken': 'qr-12345678',
|
||
'lineId': 3,
|
||
'usedPackages': 0,
|
||
'idempotencyKey': 'usage-key-1',
|
||
})
|
||
~~~
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_vo_contract -v
|
||
~~~
|
||
|
||
Expected: FAIL，VO 文件不存在。
|
||
|
||
- [ ] **Step 3: 实现 VO**
|
||
|
||
所有模型使用 ConfigDict(alias_generator=to_camel, from_attributes=True, populate_by_name=True)；所有写模型额外设置 extra='forbid'。分页模型固定 page_num/page_size；包数字段使用 Field(strict=True, gt=0) 拒绝小数和字符串，ID 使用 Field(gt=0)。pallet_ids、scanned_pallet_ids 和 UserAssignModel.user_ids 至少一项并通过 field_validator 拒绝重复元素。test_vo_contract.py 额外断言 usedPackages=1.5 和 usedPackages='1' 均触发 ValidationError。
|
||
|
||
master_vo.py 固定定义 StrainModel/StrainPageQueryModel/DeleteStrainModel、CustomerModel/CustomerPageQueryModel/DeleteCustomerModel、SiteModel/SitePageQueryModel/DeleteSiteModel、LineModel/LinePageQueryModel/DeleteLineModel、WarehouseModel/WarehousePageQueryModel/DeleteWarehouseModel、PalletModel/PalletCreateModel/PalletEditModel/PalletPageQueryModel/DeletePalletModel 和 UserAssignModel。PalletEditModel 不声明 pallet_code 或 qr_token，避免通过 exclude 逻辑静默忽略非法修改。
|
||
|
||
operation_vo.py 固定模型：
|
||
|
||
~~~text
|
||
InboundCreateModel(warehouse_id, pallet_ids)
|
||
InboundUpdateModel(inbound_id, warehouse_id, pallet_ids)
|
||
ConfirmCommandModel(idempotency_key)
|
||
FillingCreateModel(qr_token, warehouse_id, strain_id, batch_no, package_spec, initial_packages, idempotency_key)
|
||
ShipmentCreateModel(source_warehouse_id, target_site_id, pallet_ids)
|
||
ShipmentUpdateModel(shipment_id, source_warehouse_id, target_site_id, pallet_ids)
|
||
UsageCreateModel(qr_token, line_id, used_packages, idempotency_key)
|
||
ReturnRequestModel(source_site_id, target_warehouse_id, pallet_ids, idempotency_key)
|
||
ReturnConfirmModel(scanned_pallet_ids, idempotency_key)
|
||
~~~
|
||
|
||
operation_vo.py 还必须定义 InboundModel/InboundItemModel、FillingModel、ShipmentModel/ShipmentItemModel、UsageModel、ReturnModel/ReturnItemModel，以及 InboundPageQueryModel、FillingPageQueryModel、ShipmentPageQueryModel、UsagePageQueryModel、ReturnPageQueryModel、InboundScanQueryModel(warehouse_id)、ShipmentScanQueryModel(source_warehouse_id, target_site_id)、ReturnScanQueryModel(mode, return_id)、BusinessOptionModel 和 PalletScanResponseModel；mode 只允许 request/confirm，confirm 时 return_id 必填，request 时必须为空。扫码响应字段固定为 pallet_id、pallet_code、flow_state、warehouse_id、site_id、current_line_id、active_filling_id、strain_id、strain_code、strain_name、batch_no、package_spec、capacity_packages、remaining_packages、allowed_actions；后端按具体业务接口过滤 allowed_actions，不返回未授权动作。
|
||
|
||
report_vo.py 为六个报表定义独立查询和行模型：PalletInventoryReportQueryModel/PalletInventoryReportModel、FillingReportQueryModel/FillingReportModel、ShipmentReportQueryModel/ShipmentReportModel、ConsumptionReportQueryModel/ConsumptionReportModel、ReturnReportQueryModel/ReturnReportModel、PalletTraceReportQueryModel/PalletTraceReportModel。查询模型公共字段为 page_num、page_size、begin_time、end_time；页面所需过滤字段显式声明，不使用任意 dict。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_vo_contract -v
|
||
conda run -n ShiErFeng python -m ruff check module_business/entity/vo tests/module_business/test_vo_contract.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/entity/vo/master_vo.py shierfeng-fastapi-backend/module_business/entity/vo/operation_vo.py shierfeng-fastapi-backend/module_business/entity/vo/report_vo.py shierfeng-fastapi-backend/tests/module_business/test_vo_contract.py
|
||
git commit --only -m "功能：新增托盘业务接口模型" -- shierfeng-fastapi-backend/module_business/entity/vo/master_vo.py shierfeng-fastapi-backend/module_business/entity/vo/operation_vo.py shierfeng-fastapi-backend/module_business/entity/vo/report_vo.py shierfeng-fastapi-backend/tests/module_business/test_vo_contract.py
|
||
~~~
|
||
|
||
### Task 5: 实现仓库和客户现场数据范围
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/dao/access_dao.py
|
||
- Create: shierfeng-fastapi-backend/module_business/service/access_service.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_access_service.py
|
||
|
||
- [ ] **Step 1: 写管理员放行和普通用户拒绝测试**
|
||
|
||
~~~python
|
||
from types import SimpleNamespace
|
||
import unittest
|
||
from unittest.mock import AsyncMock, patch
|
||
from exceptions.exception import PermissionException
|
||
from module_business.service.access_service import AccessService
|
||
|
||
|
||
class AccessServiceTest(unittest.IsolatedAsyncioTestCase):
|
||
async def test_admin_bypasses_mapping(self):
|
||
user = SimpleNamespace(user=SimpleNamespace(user_id=1, admin=True))
|
||
await AccessService.assert_warehouse_access(AsyncMock(), user, 99)
|
||
|
||
@patch('module_business.service.access_service.AccessDao.user_has_site', new_callable=AsyncMock)
|
||
async def test_unmapped_site_is_forbidden(self, user_has_site):
|
||
user_has_site.return_value = False
|
||
user = SimpleNamespace(user=SimpleNamespace(user_id=8, admin=False))
|
||
with self.assertRaises(PermissionException):
|
||
await AccessService.assert_site_access(AsyncMock(), user, 7)
|
||
~~~
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_access_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，AccessService 不存在。
|
||
|
||
- [ ] **Step 3: 实现 DAO 和 Service**
|
||
|
||
~~~python
|
||
class AccessService:
|
||
@classmethod
|
||
async def assert_warehouse_access(cls, db, current_user, warehouse_id):
|
||
if current_user.user.admin:
|
||
return
|
||
if not await AccessDao.user_has_warehouse(db, current_user.user.user_id, warehouse_id):
|
||
raise PermissionException(data='', message='无权访问该仓库')
|
||
|
||
@classmethod
|
||
async def assert_site_access(cls, db, current_user, site_id):
|
||
if current_user.user.admin:
|
||
return
|
||
if not await AccessDao.user_has_site(db, current_user.user.user_id, site_id):
|
||
raise PermissionException(data='', message='无权访问该客户现场')
|
||
~~~
|
||
|
||
AccessDao 还必须提供 list_user_warehouse_ids、list_user_site_ids、replace_warehouse_users、replace_site_users；替换关联只 flush，不 commit，由上层 Service 统一事务。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_access_service -v
|
||
conda run -n ShiErFeng python -m ruff check module_business/dao/access_dao.py module_business/service/access_service.py tests/module_business/test_access_service.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/dao/access_dao.py shierfeng-fastapi-backend/module_business/service/access_service.py shierfeng-fastapi-backend/tests/module_business/test_access_service.py
|
||
git commit --only -m "功能：新增仓库与客户现场数据权限" -- shierfeng-fastapi-backend/module_business/dao/access_dao.py shierfeng-fastapi-backend/module_business/service/access_service.py shierfeng-fastapi-backend/tests/module_business/test_access_service.py
|
||
~~~
|
||
|
||
### Task 6: 实现五类非托盘基础资料 CRUD
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/dao/master_dao.py
|
||
- Create: shierfeng-fastapi-backend/module_business/service/master_service.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/strain_controller.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/customer_controller.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/site_controller.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/line_controller.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/warehouse_controller.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_master_service.py
|
||
|
||
- [ ] **Step 1: 写唯一性、层级和引用删除测试**
|
||
|
||
使用 IsolatedAsyncioTestCase 和 patch 固定以下断言：
|
||
|
||
~~~python
|
||
async def test_duplicate_strain_code_is_rejected(self):
|
||
with patch.object(MasterDao, 'find_strain_by_code', new=AsyncMock(return_value=object())):
|
||
with self.assertRaises(ServiceException):
|
||
await MasterService.add_strain(self.db, self.strain)
|
||
|
||
async def test_line_must_belong_to_enabled_site(self):
|
||
with patch.object(MasterDao, 'get_site', new=AsyncMock(return_value=None)):
|
||
with self.assertRaises(ServiceException):
|
||
await MasterService.add_line(self.db, self.line)
|
||
|
||
async def test_referenced_master_can_only_be_disabled(self):
|
||
with patch.object(MasterDao, 'count_references', new=AsyncMock(return_value=1)):
|
||
with self.assertRaises(ServiceWarning):
|
||
await MasterService.remove_strain(self.db, 1)
|
||
~~~
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_master_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，MasterDao/MasterService 不存在。
|
||
|
||
- [ ] **Step 3: 实现 DAO、Service 和 Controller**
|
||
|
||
MasterDao 为每类主数据提供 list/get/find_by_code/add/update/delete/count_references。MasterService 负责唯一性、父级启用状态、引用删除保护、commit/rollback；唯一键并发冲突捕获 IntegrityError，rollback 后转换为明确 ServiceException，不返回原始 500。五个 Controller 的固定前缀和权限；托盘在 Task 7 单独实现：
|
||
|
||
~~~text
|
||
/master/strain master:strain:list/query/add/edit/remove
|
||
/master/customer master:customer:list/query/add/edit/remove
|
||
/master/site master:site:list/query/add/edit/remove
|
||
/master/line master:line:list/query/add/edit/remove
|
||
/master/warehouse master:warehouse:list/query/add/edit/remove
|
||
~~~
|
||
|
||
每个 APIRouterPro 配置 PreAuthDependency；写接口配置 Log 和 CurrentUserDependency；分页返回 PageResponseModel；ServiceException/ServiceWarning 沿用现有全局处理。
|
||
|
||
- [ ] **Step 4: 运行单元测试、OpenAPI 路由检查和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_master_service -v
|
||
conda run -n ShiErFeng python -c "from server import create_app; paths=create_app().openapi()['paths']; assert '/master/strain/list' in paths and '/master/warehouse/list' in paths"
|
||
conda run -n ShiErFeng python -m ruff check module_business/dao/master_dao.py module_business/service/master_service.py module_business/controller tests/module_business/test_master_service.py
|
||
~~~
|
||
|
||
Expected: PASS；不启动 lifespan。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/dao/master_dao.py shierfeng-fastapi-backend/module_business/service/master_service.py shierfeng-fastapi-backend/module_business/controller/strain_controller.py shierfeng-fastapi-backend/module_business/controller/customer_controller.py shierfeng-fastapi-backend/module_business/controller/site_controller.py shierfeng-fastapi-backend/module_business/controller/line_controller.py shierfeng-fastapi-backend/module_business/controller/warehouse_controller.py shierfeng-fastapi-backend/tests/module_business/test_master_service.py
|
||
git commit --only -m "功能：新增业务基础资料接口" -- shierfeng-fastapi-backend/module_business/dao/master_dao.py shierfeng-fastapi-backend/module_business/service/master_service.py shierfeng-fastapi-backend/module_business/controller/strain_controller.py shierfeng-fastapi-backend/module_business/controller/customer_controller.py shierfeng-fastapi-backend/module_business/controller/site_controller.py shierfeng-fastapi-backend/module_business/controller/line_controller.py shierfeng-fastapi-backend/module_business/controller/warehouse_controller.py shierfeng-fastapi-backend/tests/module_business/test_master_service.py
|
||
~~~
|
||
|
||
### Task 7: 实现托盘、二维码和用户分配
|
||
|
||
**Files:**
|
||
- Modify: shierfeng-fastapi-backend/module_business/dao/master_dao.py
|
||
- Modify: shierfeng-fastapi-backend/module_business/entity/vo/master_vo.py
|
||
- Create: shierfeng-fastapi-backend/module_business/service/pallet_service.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/pallet_controller.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_pallet_service.py
|
||
- Modify: shierfeng-fastapi-backend/module_business/controller/warehouse_controller.py
|
||
- Modify: shierfeng-fastapi-backend/module_business/controller/site_controller.py
|
||
|
||
- [ ] **Step 1: 写二维码不可变和分配事务测试**
|
||
|
||
测试必须断言：创建托盘使用 secrets.token_urlsafe(32) 生成 token 并同时创建 UNSTOCKED 快照；编辑请求不能改变 pallet_code/qr_token；PNG 结果以八字节 PNG 签名开头；替换用户关联失败时 rollback。
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_pallet_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，PalletService 不存在。
|
||
|
||
- [ ] **Step 3: 实现托盘与二维码服务**
|
||
|
||
~~~python
|
||
@staticmethod
|
||
def render_qr_png(qr_token: str) -> bytes:
|
||
output = BytesIO()
|
||
image = qrcode.make(qr_token)
|
||
image.save(output, format='PNG')
|
||
return output.getvalue()
|
||
~~~
|
||
|
||
MasterDao 和 master_vo.py 补齐托盘 list/query/add/edit/remove 所需 DAO 与 VO。PalletService.add_pallet 在同一事务写 BizPallet 和 BizPalletInventory(UNSTOCKED, remaining_packages=0, version=0)，并把 pallet_code/qr_token 唯一冲突转换为 ServiceException。edit_pallet 明确排除 pallet_code、qr_token；remove_pallet 仅允许 UNSTOCKED 且无事件。Controller 完整提供 master:pallet:list/query/add/edit/remove，并提供 GET /master/pallet/{pallet_id}/qrcode，权限为 master:pallet:print，返回 image/png。
|
||
|
||
仓库和客户现场 Controller 分别增加 GET/PUT /master/warehouse/{warehouse_id}/users 和 GET/PUT /master/site/{site_id}/users，权限分别为 master:warehouse:assign、master:site:assign；读取用户选项复用 SysUser，但不要求调用方额外拥有 system:user:list。
|
||
|
||
- [ ] **Step 4: 运行测试、OpenAPI 和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_pallet_service -v
|
||
conda run -n ShiErFeng python -c "from server import create_app; assert '/master/pallet/{pallet_id}/qrcode' in create_app().openapi()['paths']"
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business/test_pallet_service.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/service/pallet_service.py shierfeng-fastapi-backend/module_business/controller/pallet_controller.py shierfeng-fastapi-backend/tests/module_business/test_pallet_service.py
|
||
git commit --only -m "功能：新增托盘二维码与用户分配" -- shierfeng-fastapi-backend/module_business/dao/master_dao.py shierfeng-fastapi-backend/module_business/entity/vo/master_vo.py shierfeng-fastapi-backend/module_business/service/pallet_service.py shierfeng-fastapi-backend/module_business/controller/pallet_controller.py shierfeng-fastapi-backend/module_business/controller/warehouse_controller.py shierfeng-fastapi-backend/module_business/controller/site_controller.py shierfeng-fastapi-backend/tests/module_business/test_pallet_service.py
|
||
~~~
|
||
|
||
### Task 8: 实现库存锁、幂等和事件基础设施
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/dao/inventory_dao.py
|
||
- Create: shierfeng-fastapi-backend/module_business/dao/operation_dao.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_inventory_dao.py
|
||
|
||
- [ ] **Step 1: 写锁顺序和事件不可变测试**
|
||
|
||
测试 patch AsyncSession.execute，断言 get_inventories_for_update([9, 2, 5]) 构造按 2、5、9 排序且带 FOR UPDATE 的 SELECT；InventoryDao 仅暴露 add_event，不存在 update_event/delete_event；同一 pallet_id + idempotency_key 返回既有事件。
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_inventory_dao -v
|
||
~~~
|
||
|
||
Expected: FAIL，InventoryDao 不存在。
|
||
|
||
- [ ] **Step 3: 实现 DAO 固定签名**
|
||
|
||
~~~text
|
||
InventoryDao.get_inventory_for_update(AsyncSession, int) -> BizPalletInventory | None
|
||
InventoryDao.get_inventories_for_update(AsyncSession, list[int]) -> list[BizPalletInventory]
|
||
InventoryDao.get_pallet_by_qr_token(AsyncSession, str) -> BizPallet | None
|
||
InventoryDao.get_pallets_by_ids(AsyncSession, list[int]) -> list[BizPallet]
|
||
InventoryDao.get_event_by_idempotency_key(AsyncSession, int, str) -> BizPalletEvent | None
|
||
InventoryDao.add_event(AsyncSession, BizPalletInventory, BizPalletEvent) -> BizPalletEvent
|
||
|
||
OperationDao.get_inbound_for_update(AsyncSession, int) -> BizInboundOrder | None
|
||
OperationDao.get_shipment_for_update(AsyncSession, int) -> BizShipmentOrder | None
|
||
OperationDao.get_return_for_update(AsyncSession, int) -> BizReturnOrder | None
|
||
OperationDao.get_active_filling_for_update(AsyncSession, int) -> BizFillingRecord | None
|
||
OperationDao.get_inbound_by_confirm_idempotency_key(AsyncSession, str, list[int] | None = None) -> BizInboundOrder | None
|
||
OperationDao.get_shipment_by_confirm_idempotency_key(AsyncSession, str) -> BizShipmentOrder | None
|
||
OperationDao.get_filling_by_idempotency_key(AsyncSession, str) -> BizFillingRecord | None
|
||
OperationDao.get_usage_by_idempotency_key(AsyncSession, str) -> BizUsageRecord | None
|
||
OperationDao.get_return_by_request_idempotency_key(AsyncSession, str) -> BizReturnOrder | None
|
||
OperationDao.get_return_by_confirm_idempotency_key(AsyncSession, str) -> BizReturnOrder | None
|
||
|
||
OperationDao.get_inbound_list / get_inbound_by_id
|
||
OperationDao.add_inbound / update_inbound / delete_inbound / replace_inbound_items
|
||
OperationDao.get_filling_list / get_filling_by_id / add_filling_record / update_filling_record
|
||
OperationDao.get_shipment_list / get_shipment_by_id
|
||
OperationDao.add_shipment / update_shipment / delete_shipment / replace_shipment_items
|
||
OperationDao.get_usage_list / get_usage_by_id / add_usage_record
|
||
OperationDao.get_return_list / get_return_by_id / add_return_order / update_return_order / add_return_items
|
||
~~~
|
||
|
||
列表方法接收相应 PageQueryModel 和 is_page，返回 PageModel 或列表；by_id 返回对应 ORM 或 None；add/update/delete/replace 方法接收明确 ORM/VO，且只 add/execute/flush，不 commit，Service 不得绕过 DAO 直接执行单据持久化。get_inventories_for_update 对输入先去重、升序排序，再构造带 FOR UPDATE 的 SELECT；add_event 在同一锁内分配 event_seq，flush 后同步 inventory.last_event_id。
|
||
|
||
唯一键并发冲突捕获 IntegrityError 后必须先 rollback，再按幂等键重读并比较摘要：filling、usage、return request 比较 request_hash；inbound confirm、shipment confirm、return confirm 比较 confirm_request_hash。同一键同一摘要返回原结果，同键不同摘要抛 ServiceException，不得静默复用。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_inventory_dao -v
|
||
conda run -n ShiErFeng python -m ruff check module_business/dao tests/module_business/test_inventory_dao.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/dao/inventory_dao.py shierfeng-fastapi-backend/module_business/dao/operation_dao.py shierfeng-fastapi-backend/tests/module_business/test_inventory_dao.py
|
||
git commit --only -m "功能：新增托盘库存事务基础" -- shierfeng-fastapi-backend/module_business/dao/inventory_dao.py shierfeng-fastapi-backend/module_business/dao/operation_dao.py shierfeng-fastapi-backend/tests/module_business/test_inventory_dao.py
|
||
~~~
|
||
|
||
### Task 9: 实现首次入库
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/service/inbound_service.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/inbound_controller.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_inbound_service.py
|
||
|
||
- [ ] **Step 1: 写整单确认与回滚测试**
|
||
|
||
覆盖：草稿可增删明细；确认要求仓库权限；仅 UNSTOCKED 可入库；重复托盘拒绝；任一托盘非法时不写单据/事件并 rollback；同一确认幂等键重试只返回既有结果。
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_inbound_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，InboundService 不存在。
|
||
|
||
- [ ] **Step 3: 实现 Service 和 Controller**
|
||
|
||
confirm_inbound_services(query_db, inbound_id, page_object, current_user) 的固定顺序：仓库权限 → 通过 get_inbound_by_confirm_idempotency_key 比较 confirm_request_hash → 按 pallet_id 加锁 → 全量状态校验 → 更新订单 CONFIRMED → 每托盘转 EMPTY_IN_WAREHOUSE → 写事件 → flush → 单次 commit。异常统一 rollback。
|
||
|
||
Controller 前缀 /business/inbound，权限为 list/query/add/edit/remove/confirm；增加 GET /warehouse-options 和 GET /scan/{qr_token}?warehouseId={warehouse_id}，均使用 business:inbound:query，只返回授权仓库选项以及 UNSTOCKED 且可加入所选仓库的托盘信息；确认接口 PUT /{inbound_id}/confirm，请求体只包含 idempotencyKey。
|
||
|
||
- [ ] **Step 4: 运行测试、路由检查和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_inbound_service -v
|
||
conda run -n ShiErFeng python -c "from server import create_app; assert '/business/inbound/{inbound_id}/confirm' in create_app().openapi()['paths']"
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business/test_inbound_service.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/service/inbound_service.py shierfeng-fastapi-backend/module_business/controller/inbound_controller.py shierfeng-fastapi-backend/tests/module_business/test_inbound_service.py
|
||
git commit --only -m "功能：实现空托盘首次入库" -- shierfeng-fastapi-backend/module_business/service/inbound_service.py shierfeng-fastapi-backend/module_business/controller/inbound_controller.py shierfeng-fastapi-backend/tests/module_business/test_inbound_service.py
|
||
~~~
|
||
|
||
### Task 10: 实现单托盘装填
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/service/filling_service.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/filling_controller.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_filling_service.py
|
||
|
||
- [ ] **Step 1: 写状态、容量和幂等测试**
|
||
|
||
覆盖：仅仓库空托盘允许装填；用户必须拥有仓库权限；包数为正整数且不超过托盘容量；同托盘不能存在 active filling；记录保存菌种编码/名称快照并写 active_slot=ACTIVE；同键同请求返回原结果，同键不同请求拒绝。
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_filling_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，FillingService 不存在。
|
||
|
||
- [ ] **Step 3: 实现装填事务**
|
||
|
||
锁定 inventory 后创建 BizFillingRecord，写入菌种、菌种编码/名称快照、批次、规格、initial_packages 和 active_slot=ACTIVE；设置 active_filling_id、remaining_packages、FILLED_IN_WAREHOUSE、version+1；写 FILLING_CONFIRMED 事件；单次 commit。
|
||
|
||
Controller 前缀 /business/filling，提供 /list、/strain-options、/scan/{qr_token}、/{filling_id} 和 POST 根路径；选项、扫码、详情使用 business:filling:query，写入使用 business:filling:add。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_filling_service -v
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business/test_filling_service.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/service/filling_service.py shierfeng-fastapi-backend/module_business/controller/filling_controller.py shierfeng-fastapi-backend/tests/module_business/test_filling_service.py
|
||
git commit --only -m "功能：实现单托盘装填" -- shierfeng-fastapi-backend/module_business/service/filling_service.py shierfeng-fastapi-backend/module_business/controller/filling_controller.py shierfeng-fastapi-backend/tests/module_business/test_filling_service.py
|
||
~~~
|
||
|
||
### Task 11: 实现多托盘整托发货
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/service/shipment_service.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/shipment_controller.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_shipment_service.py
|
||
|
||
- [ ] **Step 1: 写整托、双数据范围和原子性测试**
|
||
|
||
覆盖：来源仓库和目标现场权限缺一即拒绝；所有托盘必须在同一来源仓库并处于 FILLED_IN_WAREHOUSE；明细数量只能取当前全部余量；任一托盘不合法则整单 rollback；确认后直接 AT_SITE_UNUSED，无在途状态。
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_shipment_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，ShipmentService 不存在。
|
||
|
||
- [ ] **Step 3: 实现发货事务**
|
||
|
||
草稿保存托盘 ID，不接受客户端发货包数；shipment_item.active_filling_id/package_qty 在草稿中为空。confirm_shipment_services(query_db, shipment_id, page_object, current_user) 先通过 get_shipment_by_confirm_idempotency_key 比较 confirm_request_hash，再按 pallet_id 锁定并生成 shipment_item.active_filling_id/package_qty 快照，清空 warehouse_id，设置 site_id、current_line_id=None、AT_SITE_UNUSED、version+1，并逐托盘写 SHIPMENT_CONFIRMED 事件。
|
||
|
||
Controller 前缀 /business/shipment，权限为 list/query/add/edit/remove/confirm；增加 GET /warehouse-options、GET /site-options 和 GET /scan/{qr_token}?sourceWarehouseId={source_warehouse_id}&targetSiteId={target_site_id}，均使用 business:shipment:query；后端校验双数据范围且只返回可整托发货的 FILLED_IN_WAREHOUSE 托盘；确认接口 PUT /{shipment_id}/confirm。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_shipment_service -v
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business/test_shipment_service.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/service/shipment_service.py shierfeng-fastapi-backend/module_business/controller/shipment_controller.py shierfeng-fastapi-backend/tests/module_business/test_shipment_service.py
|
||
git commit --only -m "功能：实现多托盘发货出库" -- shierfeng-fastapi-backend/module_business/service/shipment_service.py shierfeng-fastapi-backend/module_business/controller/shipment_controller.py shierfeng-fastapi-backend/tests/module_business/test_shipment_service.py
|
||
~~~
|
||
|
||
### Task 12: 实现客户现场使用
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/service/usage_service.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/usage_controller.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_usage_service.py
|
||
|
||
- [ ] **Step 1: 写首次锁线、超用和重复提交测试**
|
||
|
||
覆盖：用户必须拥有托盘所在现场权限；产线必须属于该现场；第一次使用写 current_line_id；后续异线拒绝；used_packages 不得超过余量；余量归零转 AT_SITE_EMPTY，并清 active_filling_id/active_slot、写 closed_at；同一幂等键不重复扣减。
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_usage_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，UsageService 不存在。
|
||
|
||
- [ ] **Step 3: 实现使用事务**
|
||
|
||
record_usage_services 依次解析二维码、校验 site 权限、锁定 inventory、校验 active filling/current_line_id/数量、创建 usage_record、扣减余量、设置 AT_SITE_PARTIAL 或 AT_SITE_EMPTY、version+1、写 USAGE_RECORDED 事件并 commit。首次使用同时写 inventory.current_line_id；后续只能使用相同 line_id。余量归零时把活动装填记录 active_slot 置 NULL、写 closed_at 并清 inventory.active_filling_id，但 current_line_id 保留到退回确认以反映当前现场位置。
|
||
|
||
Controller 前缀 /business/usage，提供 /list、/line-options?siteId={site_id}、/scan/{qr_token}、/{usage_id}、POST；选项、扫码、详情使用 business:usage:query，写入使用 business:usage:add。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_usage_service -v
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business/test_usage_service.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/service/usage_service.py shierfeng-fastapi-backend/module_business/controller/usage_controller.py shierfeng-fastapi-backend/tests/module_business/test_usage_service.py
|
||
git commit --only -m "功能：实现客户现场使用记录" -- shierfeng-fastapi-backend/module_business/service/usage_service.py shierfeng-fastapi-backend/module_business/controller/usage_controller.py shierfeng-fastapi-backend/tests/module_business/test_usage_service.py
|
||
~~~
|
||
|
||
### Task 13: 实现两阶段退回
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/service/return_service.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/return_controller.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_return_service.py
|
||
|
||
- [ ] **Step 1: 写发起冻结、收货确认和残料再发测试**
|
||
|
||
覆盖：同一退回单托盘必须属于同一 site；发起人拥有 site 权限；发起后 RETURNING 且不能使用；确认人拥有目标 warehouse 权限；确认扫码集合与单据明细一致；remaining_packages_snapshot 或 active_filling_id_snapshot 任一被改变时拒绝；有余料回 FILLED_IN_WAREHOUSE 并保留活动装填，无余料回 EMPTY_IN_WAREHOUSE 且活动装填为空；两者均清 current_line_id。
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_return_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，ReturnService 不存在。
|
||
|
||
- [ ] **Step 3: 实现发起和确认事务**
|
||
|
||
request_return_services 创建 REQUESTED 单据，为每个托盘保存 active_filling_id_snapshot 和 remaining_packages_snapshot，使用 request_hash 做申请幂等，状态转 RETURNING，写 RETURN_REQUESTED 事件。confirm_return_services(query_db, return_id, page_object, current_user) 通过 get_return_by_confirm_idempotency_key 比较 confirm_request_hash 后，重新按 pallet_id 加锁，核对状态、两个快照和扫码集合，将位置转入仓库，按余量选择目标状态，清 site_id/current_line_id，写 RETURN_CONFIRMED 事件并确认单据。有余料时必须保留 active_filling_id 和 active_slot 以支持再次整托发货；无余料时两者必须为空。
|
||
|
||
Controller 前缀 /business/return，权限为 list/query/request/confirm；增加 GET /warehouse-options、GET /scan/{qr_token}?mode=request 和 GET /scan/{qr_token}?mode=confirm&returnId={return_id}，均使用 business:return:query，按当前操作人的 site/warehouse 数据范围返回可发起或可确认的托盘；写接口为 POST /request 和 PUT /{return_id}/confirm。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_return_service -v
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business/test_return_service.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/service/return_service.py shierfeng-fastapi-backend/module_business/controller/return_controller.py shierfeng-fastapi-backend/tests/module_business/test_return_service.py
|
||
git commit --only -m "功能：实现托盘两阶段退回" -- shierfeng-fastapi-backend/module_business/service/return_service.py shierfeng-fastapi-backend/module_business/controller/return_controller.py shierfeng-fastapi-backend/tests/module_business/test_return_service.py
|
||
~~~
|
||
|
||
### Task 14: 实现六类只读报表
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/module_business/dao/report_dao.py
|
||
- Create: shierfeng-fastapi-backend/module_business/service/report_service.py
|
||
- Create: shierfeng-fastapi-backend/module_business/controller/report_controller.py
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_report_service.py
|
||
|
||
- [ ] **Step 1: 写数据范围和查询来源测试**
|
||
|
||
测试六个方法均将管理员/普通用户可见 warehouse_ids/site_ids 传入 DAO；库存报表读取 inventory + active filling，装填报表读取 BizFillingRecord.strain_code_snapshot/strain_name_snapshot，追溯读取 pallet_event 的前后状态、位置和数量字段；不得从可变菌种主数据反推历史名称，不得从 sys_oper_log 构造业务报表；接口不包含导出方法。
|
||
|
||
- [ ] **Step 2: 运行测试并确认失败**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_report_service -v
|
||
~~~
|
||
|
||
Expected: FAIL，ReportService 不存在。
|
||
|
||
- [ ] **Step 3: 实现 DAO、Service 和 Controller**
|
||
|
||
固定只读接口：
|
||
|
||
~~~text
|
||
GET /report/pallet-inventory/list report:palletinventory:list
|
||
GET /report/filling/list report:filling:list
|
||
GET /report/shipment/list report:shipment:list
|
||
GET /report/consumption/list report:consumption:list
|
||
GET /report/return/list report:return:list
|
||
GET /report/pallet-trace/list report:pallettrace:list
|
||
~~~
|
||
|
||
全部使用 PageUtil.paginate；每个查询显式应用日期和对应业务过滤字段；普通用户查询条件与授权 warehouse/site 取交集；无可见范围返回空分页，不泄露总数。
|
||
|
||
ReportDao/ReportService 方法名逐项固定为 get_pallet_inventory_list/get_pallet_inventory_list_services、get_filling_report_list/get_filling_report_list_services、get_shipment_report_list/get_shipment_report_list_services、get_consumption_report_list/get_consumption_report_list_services、get_return_report_list/get_return_report_list_services、get_pallet_trace_list/get_pallet_trace_list_services；Controller 不通过一个 mode 参数复用单一路由。
|
||
|
||
- [ ] **Step 4: 运行测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_report_service -v
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business/test_report_service.py
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/module_business/dao/report_dao.py shierfeng-fastapi-backend/module_business/service/report_service.py shierfeng-fastapi-backend/module_business/controller/report_controller.py shierfeng-fastapi-backend/tests/module_business/test_report_service.py
|
||
git commit --only -m "功能：新增托盘业务报表接口" -- shierfeng-fastapi-backend/module_business/dao/report_dao.py shierfeng-fastapi-backend/module_business/service/report_service.py shierfeng-fastapi-backend/module_business/controller/report_controller.py shierfeng-fastapi-backend/tests/module_business/test_report_service.py
|
||
~~~
|
||
|
||
### Task 15: 固化后端 API 与权限契约
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_api_permission_contract.py
|
||
- Modify: shierfeng-fastapi-backend/module_business/controller/*.py
|
||
|
||
- [ ] **Step 1: 写完整 OpenAPI 路径和源码权限集合测试**
|
||
|
||
测试创建 app 但不进入 lifespan。预期路径集合覆盖 6 个 master、5 个 business、6 个 report 前缀；源码提取 UserInterfaceAuthDependency 字符串，必须等于设计稿权限集合；任何 /ai/ 路径均失败。
|
||
|
||
~~~python
|
||
def test_no_ai_and_required_business_paths(self):
|
||
from server import create_app
|
||
paths = set(create_app().openapi()['paths'])
|
||
self.assertFalse(any(path.startswith('/ai/') for path in paths))
|
||
for resource in ('inbound', 'filling', 'shipment', 'usage', 'return'):
|
||
self.assertIn(f'/business/{resource}/scan/{{qr_token}}', paths)
|
||
for path in (
|
||
'/business/inbound/warehouse-options',
|
||
'/business/filling/strain-options',
|
||
'/business/shipment/warehouse-options',
|
||
'/business/shipment/site-options',
|
||
'/business/usage/line-options',
|
||
'/business/return/warehouse-options',
|
||
):
|
||
self.assertIn(path, paths)
|
||
self.assertIn('/business/return/{return_id}/confirm', paths)
|
||
self.assertIn('/report/pallet-trace/list', paths)
|
||
~~~
|
||
|
||
- [ ] **Step 2: 运行测试并修正契约差异**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_api_permission_contract -v
|
||
~~~
|
||
|
||
Expected: 首次运行可能因遗漏路由/权限失败；仅修正 Controller 与已确认契约，不扩大功能。
|
||
|
||
- [ ] **Step 3: 运行所有后端业务单元测试和 Ruff**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest discover -s tests/module_business -p "test_*.py" -v
|
||
conda run -n ShiErFeng python -m ruff format --check module_business tests/module_business
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business
|
||
~~~
|
||
|
||
Expected: PASS；不连接数据库。
|
||
|
||
- [ ] **Step 4: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/tests/module_business/test_api_permission_contract.py
|
||
git commit --only -m "测试：固化业务接口权限契约" -- shierfeng-fastapi-backend/module_business/controller/strain_controller.py shierfeng-fastapi-backend/module_business/controller/customer_controller.py shierfeng-fastapi-backend/module_business/controller/site_controller.py shierfeng-fastapi-backend/module_business/controller/line_controller.py shierfeng-fastapi-backend/module_business/controller/warehouse_controller.py shierfeng-fastapi-backend/module_business/controller/pallet_controller.py shierfeng-fastapi-backend/module_business/controller/inbound_controller.py shierfeng-fastapi-backend/module_business/controller/filling_controller.py shierfeng-fastapi-backend/module_business/controller/shipment_controller.py shierfeng-fastapi-backend/module_business/controller/usage_controller.py shierfeng-fastapi-backend/module_business/controller/return_controller.py shierfeng-fastapi-backend/module_business/controller/report_controller.py shierfeng-fastapi-backend/tests/module_business/test_api_permission_contract.py
|
||
~~~
|
||
|
||
### Task 16: 新增 Web API、扫码工具和契约测试
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-frontend/src/api/master/*.js
|
||
- Create: shierfeng-fastapi-frontend/src/api/business/*.js
|
||
- Create: shierfeng-fastapi-frontend/src/api/report/*.js
|
||
- Create: shierfeng-fastapi-frontend/src/utils/palletScan.js
|
||
- Create: shierfeng-fastapi-frontend/src/components/PalletScanInput/index.vue
|
||
- Create: shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
- Modify: shierfeng-fastapi-frontend/package.json
|
||
|
||
- [ ] **Step 1: 写 Node 20 失败测试**
|
||
|
||
~~~javascript
|
||
import test from 'node:test'
|
||
import assert from 'node:assert/strict'
|
||
import fs from 'node:fs'
|
||
import { normalizeScanValue, isDuplicateScan } from '../src/utils/palletScan.js'
|
||
|
||
test('扫码值去除首尾空白并拒绝空值', () => {
|
||
assert.equal(normalizeScanValue(' qr-12345678\n'), 'qr-12345678')
|
||
assert.throws(() => normalizeScanValue(' '), /二维码不能为空/)
|
||
})
|
||
|
||
test('短时间重复扫码会被识别', () => {
|
||
assert.equal(isDuplicateScan('qr-a', 'qr-a', 1200, 1000, 500), true)
|
||
assert.equal(isDuplicateScan('qr-a', 'qr-b', 1200, 1000, 500), false)
|
||
})
|
||
|
||
test('业务 API 文件不出现未确认导出接口', () => {
|
||
const reportApi = fs.readFileSync(new URL('../src/api/report/palletInventory.js', import.meta.url), 'utf8')
|
||
assert.doesNotMatch(reportApi, /export/i)
|
||
})
|
||
~~~
|
||
|
||
同一脚本还要以“HTTP、扫码和 Service 固定契约”为硬编码 expectedRequests，逐个读取 17 个 API 文件并核对 request 的 url 和 method；必须显式覆盖五个 /business/*/scan/{qr_token}、六个业务选项 GET、三个确认 PUT、退回 POST /request、托盘二维码 GET 和六个报表 GET /list，不能只比较前后端彼此相等。
|
||
|
||
- [ ] **Step 2: 运行测试并确认模块不存在**
|
||
|
||
~~~bash
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
Expected: FAIL，palletScan.js 或 API 文件不存在。
|
||
|
||
- [ ] **Step 3: 实现工具、API 和扫码组件**
|
||
|
||
palletScan.js 导出 normalizeScanValue、isDuplicateScan、createIdempotencyKey；createIdempotencyKey 使用 globalThis.crypto.randomUUID()，不可回退到时间戳。
|
||
|
||
17 个 API 文件严格映射“HTTP、扫码和 Service 固定契约”。PalletScanInput 接收 disabled、loading、minLength、duplicateWindowMs；发出 scan、invalid、duplicate；Enter 时 trim、校验、抑制短时间重复码；提交完成后 nextTick 重新 focus。样式使用最小 48px 控件高度和移动端全宽，不调用摄像头/BarcodeDetector。
|
||
|
||
package.json 增加：
|
||
|
||
~~~json
|
||
"test:business": "node --test scripts/verify-business-contract.mjs"
|
||
~~~
|
||
|
||
保留 Task 1 已完成的 AI 依赖删除和用户品牌描述。
|
||
|
||
- [ ] **Step 4: 运行 Node 测试**
|
||
|
||
~~~bash
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-frontend/src/api/master/strain.js shierfeng-fastapi-frontend/src/api/master/customer.js shierfeng-fastapi-frontend/src/api/master/site.js shierfeng-fastapi-frontend/src/api/master/line.js shierfeng-fastapi-frontend/src/api/master/warehouse.js shierfeng-fastapi-frontend/src/api/master/pallet.js shierfeng-fastapi-frontend/src/api/business/inbound.js shierfeng-fastapi-frontend/src/api/business/filling.js shierfeng-fastapi-frontend/src/api/business/shipment.js shierfeng-fastapi-frontend/src/api/business/usage.js shierfeng-fastapi-frontend/src/api/business/return.js shierfeng-fastapi-frontend/src/api/report/palletInventory.js shierfeng-fastapi-frontend/src/api/report/filling.js shierfeng-fastapi-frontend/src/api/report/shipment.js shierfeng-fastapi-frontend/src/api/report/consumption.js shierfeng-fastapi-frontend/src/api/report/return.js shierfeng-fastapi-frontend/src/api/report/palletTrace.js shierfeng-fastapi-frontend/src/utils/palletScan.js shierfeng-fastapi-frontend/src/components/PalletScanInput/index.vue shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
git commit --only -m "功能：新增业务接口与扫码组件" -- shierfeng-fastapi-frontend/src/api/master/strain.js shierfeng-fastapi-frontend/src/api/master/customer.js shierfeng-fastapi-frontend/src/api/master/site.js shierfeng-fastapi-frontend/src/api/master/line.js shierfeng-fastapi-frontend/src/api/master/warehouse.js shierfeng-fastapi-frontend/src/api/master/pallet.js shierfeng-fastapi-frontend/src/api/business/inbound.js shierfeng-fastapi-frontend/src/api/business/filling.js shierfeng-fastapi-frontend/src/api/business/shipment.js shierfeng-fastapi-frontend/src/api/business/usage.js shierfeng-fastapi-frontend/src/api/business/return.js shierfeng-fastapi-frontend/src/api/report/palletInventory.js shierfeng-fastapi-frontend/src/api/report/filling.js shierfeng-fastapi-frontend/src/api/report/shipment.js shierfeng-fastapi-frontend/src/api/report/consumption.js shierfeng-fastapi-frontend/src/api/report/return.js shierfeng-fastapi-frontend/src/api/report/palletTrace.js shierfeng-fastapi-frontend/src/utils/palletScan.js shierfeng-fastapi-frontend/src/components/PalletScanInput/index.vue shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
package.json 的 test:business 脚本和 Task 1 依赖删除继续保留在工作区，不纳入该提交；只有用户另行确认允许同时提交任务开始前的品牌描述修改时，才提交 package.json 当前内容。
|
||
|
||
### Task 17: 实现六个基础资料页面
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-frontend/src/components/BusinessUserAssignDialog/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/master/strain/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/master/customer/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/master/site/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/master/line/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/master/warehouse/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/master/pallet/index.vue
|
||
- Modify: shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
|
||
- [ ] **Step 1: 扩展契约测试**
|
||
|
||
读取六个 Vue 文件并断言每个页面包含对应 list 权限、按钮 v-hasPermi、Pagination；仓库/现场包含 assign；托盘包含 master:pallet:print 且不允许编辑 palletCode/qrToken。
|
||
|
||
- [ ] **Step 2: 运行测试并确认页面缺失**
|
||
|
||
~~~bash
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
Expected: FAIL，页面文件不存在。
|
||
|
||
- [ ] **Step 3: 实现页面**
|
||
|
||
页面复用 system/post/index.vue 的搜索、分页、表格和弹窗结构，不提供导入导出。字段固定为设计稿主数据字段；删除按钮只在后端返回 canRemove=true 时显示，停用操作走 edit。BusinessUserAssignDialog 复用角色用户选择弹窗交互，但调用 warehouse/site 自身 users API。
|
||
|
||
托盘页面创建时只输入 palletCode、capacityPackages、remark；详情显示只读 qrToken；打印按钮请求 PNG Blob 并打开独立打印窗口，不在浏览器生成二维码。
|
||
|
||
- [ ] **Step 4: 运行契约测试和生产构建**
|
||
|
||
~~~bash
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node /Users/jiaolongyan/.nvm/versions/node/v20.20.2/lib/node_modules/npm/bin/npm-cli.js run build:prod
|
||
~~~
|
||
|
||
Expected: PASS；Vite build completed successfully。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-frontend/src/components/BusinessUserAssignDialog/index.vue shierfeng-fastapi-frontend/src/views/master/strain/index.vue shierfeng-fastapi-frontend/src/views/master/customer/index.vue shierfeng-fastapi-frontend/src/views/master/site/index.vue shierfeng-fastapi-frontend/src/views/master/line/index.vue shierfeng-fastapi-frontend/src/views/master/warehouse/index.vue shierfeng-fastapi-frontend/src/views/master/pallet/index.vue
|
||
git commit --only -m "功能：新增业务基础资料页面" -- shierfeng-fastapi-frontend/src/components/BusinessUserAssignDialog/index.vue shierfeng-fastapi-frontend/src/views/master/strain/index.vue shierfeng-fastapi-frontend/src/views/master/customer/index.vue shierfeng-fastapi-frontend/src/views/master/site/index.vue shierfeng-fastapi-frontend/src/views/master/line/index.vue shierfeng-fastapi-frontend/src/views/master/warehouse/index.vue shierfeng-fastapi-frontend/src/views/master/pallet/index.vue shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
### Task 18: 实现五个业务操作页面
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-frontend/src/views/business/inbound/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/business/filling/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/business/shipment/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/business/usage/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/business/return/index.vue
|
||
- Modify: shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
|
||
- [ ] **Step 1: 扩展业务页面契约测试**
|
||
|
||
断言五页分别包含已确认权限；入库/发货只有草稿显示编辑删除；确认按钮使用 confirm；使用页使用 PalletScanInput 和 business:usage:add；退回页分别使用 request/confirm；所有提交函数在 Promise 未完成时禁用扫码和按钮。幂等写操作在首次构造请求时生成 key，网络失败后的原请求重试复用同一个 key，只在成功、取消或业务输入改变后清空并重新生成。
|
||
|
||
- [ ] **Step 2: 运行测试并确认页面缺失**
|
||
|
||
~~~bash
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
Expected: FAIL。
|
||
|
||
- [ ] **Step 3: 实现入库、装填和发货页面**
|
||
|
||
入库：通过本业务 warehouse-options 选择授权仓库、连续扫码待入库托盘、明细去重、确认前二次确认。
|
||
|
||
装填：扫码后显示托盘/仓库，通过本业务 strain-options 选择菌种，输入 batchNo、packageSpec、正整数 initialPackages，首次提交时生成并保存幂等键；同一表单重试不得重新生成。
|
||
|
||
发货：通过本业务 warehouse-options/site-options 选择来源仓库和目标现场，连续扫描有料托盘；数量只读显示后端 remainingPackages；确认前二次确认。
|
||
|
||
- [ ] **Step 4: 实现使用和退回 PDA 页面**
|
||
|
||
使用：移动端大控件，扫码后展示菌种/批次/余量；首次通过本业务 line-options 选择现场产线，后续只读；输入正整数本次使用包数；成功后显示新余量和状态。入库确认、发货确认、使用、退回申请和退回确认采用与装填相同的幂等键生命周期。
|
||
|
||
退回：同页以权限区分“客户发起”和“仓库确认”操作区；发起时通过本业务 warehouse-options 选择目标仓库并扫描同现场托盘；确认时扫描退回单全部托盘，集合不一致时不提交。五个业务页面不得调用 master API 获取操作选项。
|
||
|
||
- [ ] **Step 5: 运行契约测试和生产构建**
|
||
|
||
~~~bash
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node /Users/jiaolongyan/.nvm/versions/node/v20.20.2/lib/node_modules/npm/bin/npm-cli.js run build:prod
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 6: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-frontend/src/views/business/inbound/index.vue shierfeng-fastapi-frontend/src/views/business/filling/index.vue shierfeng-fastapi-frontend/src/views/business/shipment/index.vue shierfeng-fastapi-frontend/src/views/business/usage/index.vue shierfeng-fastapi-frontend/src/views/business/return/index.vue
|
||
git commit --only -m "功能：新增托盘业务操作页面" -- shierfeng-fastapi-frontend/src/views/business/inbound/index.vue shierfeng-fastapi-frontend/src/views/business/filling/index.vue shierfeng-fastapi-frontend/src/views/business/shipment/index.vue shierfeng-fastapi-frontend/src/views/business/usage/index.vue shierfeng-fastapi-frontend/src/views/business/return/index.vue shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
### Task 19: 实现六个报表页面
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-frontend/src/views/report/palletInventory/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/report/filling/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/report/shipment/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/report/consumption/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/report/return/index.vue
|
||
- Create: shierfeng-fastapi-frontend/src/views/report/palletTrace/index.vue
|
||
- Modify: shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
|
||
- [ ] **Step 1: 扩展报表契约测试**
|
||
|
||
断言六页只有 list 权限，没有 add/edit/remove/export；每页包含分页和搜索重置；追溯页面按 occurredAt 展示 before/after 状态、位置和数量。
|
||
|
||
- [ ] **Step 2: 运行测试并确认页面缺失**
|
||
|
||
~~~bash
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
Expected: FAIL。
|
||
|
||
- [ ] **Step 3: 实现报表页面**
|
||
|
||
六页字段和过滤器严格按设计稿第 9.3 节实现。所有筛选提交时 pageNum 重置为 1；空数据展示 Element Plus empty；不添加导出按钮、不调用 proxy.download。
|
||
|
||
- [ ] **Step 4: 运行契约测试和生产构建**
|
||
|
||
~~~bash
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node /Users/jiaolongyan/.nvm/versions/node/v20.20.2/lib/node_modules/npm/bin/npm-cli.js run build:prod
|
||
~~~
|
||
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-frontend/src/views/report/palletInventory/index.vue shierfeng-fastapi-frontend/src/views/report/filling/index.vue shierfeng-fastapi-frontend/src/views/report/shipment/index.vue shierfeng-fastapi-frontend/src/views/report/consumption/index.vue shierfeng-fastapi-frontend/src/views/report/return/index.vue shierfeng-fastapi-frontend/src/views/report/palletTrace/index.vue
|
||
git commit --only -m "功能：新增托盘业务报表页面" -- shierfeng-fastapi-frontend/src/views/report/palletInventory/index.vue shierfeng-fastapi-frontend/src/views/report/filling/index.vue shierfeng-fastapi-frontend/src/views/report/shipment/index.vue shierfeng-fastapi-frontend/src/views/report/consumption/index.vue shierfeng-fastapi-frontend/src/views/report/return/index.vue shierfeng-fastapi-frontend/src/views/report/palletTrace/index.vue shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
### Task 20: 同步两套初始化 SQL 并生成 MySQL 补丁
|
||
|
||
**Files:**
|
||
- Create: shierfeng-fastapi-backend/sql/patches/20260724_pallet_workflow_mysql.sql
|
||
- Create: shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py
|
||
- Modify: shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql
|
||
- Modify: shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql
|
||
|
||
- [ ] **Step 1: 写 SQL 静态契约测试**
|
||
|
||
~~~python
|
||
from pathlib import Path
|
||
import re
|
||
import unittest
|
||
|
||
|
||
class SqlContractTest(unittest.TestCase):
|
||
root = Path(__file__).resolve().parents[3] / 'shierfeng-fastapi-backend/sql'
|
||
|
||
def test_initializers_have_exact_business_tables_and_permissions(self):
|
||
expected_tables = {
|
||
'biz_strain', 'biz_warehouse', 'biz_customer', 'biz_customer_site',
|
||
'biz_production_line', 'biz_pallet', 'biz_user_warehouse', 'biz_user_site',
|
||
'biz_inbound_order', 'biz_inbound_item', 'biz_filling_record',
|
||
'biz_shipment_order', 'biz_shipment_item', 'biz_usage_record',
|
||
'biz_return_order', 'biz_return_item', 'biz_pallet_inventory',
|
||
'biz_pallet_event',
|
||
}
|
||
for name in ('shierfeng-fastapi.sql', 'shierfeng-fastapi-pg.sql'):
|
||
sql = (self.root / name).read_text(encoding='utf-8').lower()
|
||
actual_tables = set(re.findall(
|
||
r'create\s+table\s+(?:if\s+not\s+exists\s+)?[`"]?(biz_[a-z0-9_]+)',
|
||
sql,
|
||
))
|
||
self.assertEqual(expected_tables, actual_tables)
|
||
for column in (
|
||
'strain_code_snapshot', 'strain_name_snapshot', 'active_slot',
|
||
'active_filling_id_snapshot', 'remaining_packages_snapshot',
|
||
'confirm_idempotency_key', 'request_idempotency_key', 'request_hash',
|
||
):
|
||
self.assertIn(column, sql)
|
||
for permission in ('master:pallet:print', 'business:return:confirm', 'report:pallettrace:list'):
|
||
self.assertIn(permission, sql)
|
||
|
||
def test_patch_never_mutates_ai_tables(self):
|
||
raw = (self.root / 'patches/20260724_pallet_workflow_mysql.sql').read_text(
|
||
encoding='utf-8'
|
||
).lower()
|
||
sql = re.sub(r'/\*.*?\*/', '', raw, flags=re.S)
|
||
sql = re.sub(r'(?m)^\s*(?:--|#).*$\n?', '', sql).replace('`', '')
|
||
ai_tables = ('ai_models', 'ai_chat_config', 'ai_sessions', 'ai_memories', 'ai_metrics',
|
||
'ai_eval_runs', 'ai_knowledge', 'ai_culture', 'ai_traces', 'ai_spans',
|
||
'ai_schema_versions')
|
||
for table in ai_tables:
|
||
qualified = rf'(?:[a-z0-9_]+\.)?{re.escape(table)}'
|
||
patterns = (
|
||
rf'\bdrop\s+(?:temporary\s+)?table\s+(?:if\s+exists\s+)?{qualified}\b',
|
||
rf'\btruncate\s+(?:table\s+)?{qualified}\b',
|
||
rf'\bdelete\s+from\s+{qualified}\b',
|
||
)
|
||
for pattern in patterns:
|
||
self.assertIsNone(re.search(pattern, sql), f'危险 AI 表操作: {table}')
|
||
~~~
|
||
|
||
- [ ] **Step 2: 运行测试并确认业务 SQL 缺失**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_sql_contract -v
|
||
~~~
|
||
|
||
Expected: FAIL，业务表或补丁不存在。
|
||
|
||
- [ ] **Step 3: 同步 18 张表 DDL**
|
||
|
||
以“18 张表的字段与约束”及 ORM 元数据为唯一契约，在 MySQL/PostgreSQL 初始化脚本分别写出等价 DDL。SQL 测试必须精确提取 18 张 biz_* 表，并检查快照、活动装填、幂等摘要、唯一约束、外键、检查约束和索引。不得新增 Alembic revision，不改 create_all 行为，不执行 SQL。
|
||
|
||
- [ ] **Step 4: 写入固定菜单和权限**
|
||
|
||
目录 ID：121 基础资料维护、122 业务管理、123 报表查询。
|
||
|
||
页面 502–518 必须逐项使用“菜单页面固定映射”表中的 menu_name、parent_id、path、component、API 语义和 perms；按钮 1065–1108 必须逐行使用“按钮 ID 固定映射”，不得在实现时重新排序。不写任何新 sys_role_menu。两套脚本保持 ID、parent_id、menu_name、path、route_name、order_num、perms 和 component 完全一致。
|
||
|
||
- [ ] **Step 5: 生成一份不执行的 MySQL 增量补丁**
|
||
|
||
补丁包含 18 张表 CREATE TABLE、菜单/权限 INSERT、明确 ID 的 AI 菜单/字典和菜单 99 DELETE。DDL 和 DML 分节，注明 MySQL DDL 隐式提交；禁止 DROP/TRUNCATE/DELETE 任何 AI 业务表。补丁末尾记录应用后需要清理 /getRouters、用户信息和 sys_dict:ai_provider_type 缓存，但不自动执行缓存命令。
|
||
|
||
- [ ] **Step 6: 运行 SQL 测试和差异检查**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_sql_contract -v
|
||
rg -n "master:|business:|report:" shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql
|
||
~~~
|
||
|
||
Expected: PASS；两份权限集合相同；补丁安全测试无 AI 表删除命中。
|
||
|
||
- [ ] **Step 7: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/sql/patches/20260724_pallet_workflow_mysql.sql shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py
|
||
git commit --only -m "功能：新增托盘业务数据库脚本" -- shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql shierfeng-fastapi-backend/sql/patches/20260724_pallet_workflow_mysql.sql shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py
|
||
~~~
|
||
|
||
### Task 21: 校验前后端权限、组件和 API 一致性
|
||
|
||
**Files:**
|
||
- Modify: shierfeng-fastapi-backend/tests/module_business/test_api_permission_contract.py
|
||
- Modify: shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py
|
||
- Modify: shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
|
||
- [ ] **Step 1: 增加四方权限集合比较**
|
||
|
||
Python 测试提取 SQL sys_menu.perms、后端 UserInterfaceAuthDependency 和 Vue v-hasPermi；Node 测试检查 17 个 component 路径存在。预期集合硬编码为本计划的 17 个页面 list 权限和 44 个按钮权限，共 61 个；禁止只比较“彼此相等”而同时漏项。菜单测试还逐项比较 121–123、502–518、1065–1108 的 parent_id、menu_name、path、route_name、order_num、perms 和 component。
|
||
|
||
- [ ] **Step 2: 运行契约测试并修复差异**
|
||
|
||
~~~bash
|
||
conda run -n ShiErFeng python -m unittest tests.module_business.test_api_permission_contract tests.module_business.test_sql_contract -v
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
Expected: PASS；SQL、后端、Web 和组件文件映射一致。
|
||
|
||
- [ ] **Step 3: 提交**
|
||
|
||
~~~bash
|
||
git add -- shierfeng-fastapi-backend/tests/module_business/test_api_permission_contract.py shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
git commit --only -m "测试：校验菜单接口权限一致性" -- shierfeng-fastapi-backend/tests/module_business/test_api_permission_contract.py shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py shierfeng-fastapi-frontend/scripts/verify-business-contract.mjs
|
||
~~~
|
||
|
||
### Task 22: 完成静态验证和交付文档
|
||
|
||
**Files:**
|
||
- Modify: README.md
|
||
- Modify: CHANGELOG.md
|
||
- Create: docs/pallet-workflow-deployment.md
|
||
|
||
- [ ] **Step 1: 更新文档**
|
||
|
||
README 说明新增基础资料、五类业务、六类报表和 PDA Web；CHANGELOG 增加本次功能与 AI 移除条目但保留历史记录；部署文档明确：
|
||
|
||
- 先备份数据库并审查补丁。
|
||
- 本轮未执行补丁。
|
||
- 现有 AI/Agno 表可能残留及其精确表名。
|
||
- 应用补丁后清理菜单/用户/字典缓存。
|
||
- 只有应用补丁后才允许启动后端做运行态验收。
|
||
|
||
- [ ] **Step 2: 运行全部无数据库验证**
|
||
|
||
~~~bash
|
||
cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/ShiErFeng/shierfeng-fastapi-backend
|
||
conda run -n ShiErFeng python -m unittest discover -s tests/module_business -p "test_*.py" -v
|
||
conda run -n ShiErFeng python -m ruff format --check module_business tests/module_business
|
||
conda run -n ShiErFeng python -m ruff check module_business tests/module_business
|
||
conda run -n ShiErFeng python -c "from server import create_app; app=create_app(); paths=app.openapi()['paths']; assert not any(path.startswith('/ai/') for path in paths)"
|
||
conda run -n ShiErFeng python -m pip check
|
||
cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/ShiErFeng/shierfeng-fastapi-frontend
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node --test scripts/verify-business-contract.mjs
|
||
/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin/node /Users/jiaolongyan/.nvm/versions/node/v20.20.2/lib/node_modules/npm/bin/npm-cli.js run build:prod
|
||
~~~
|
||
|
||
Expected: 所有命令通过。构建产物如 dist 由现有 .gitignore 管理，不加入提交。
|
||
|
||
- [ ] **Step 3: 检查 AI 源码、接口和依赖残留**
|
||
|
||
~~~bash
|
||
cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/ShiErFeng/shierfeng-fastapi-backend
|
||
conda run -n ShiErFeng python -c "from pathlib import Path; p=Path('module_ai'); files=[] if not p.exists() else [str(x) for x in p.rglob('*.py')]; assert not files, files"
|
||
rg -n --glob '!**/__pycache__/**' --glob '!build/**' --glob '!logs/**' 'module_ai|utils\.ai_util|utils\.crypto_util|AiUtil|AI_MODEL_|AI_CHAT_|USER_INTERACTIVE_HIGH_FREQ|LiteLLM|litellm' common config middlewares module_admin module_business sub_applications utils server.py
|
||
cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/ShiErFeng/shierfeng-fastapi-frontend
|
||
rg -n '@/api/ai|/ai/(chat|model)|ai:model|ai:chat|ai_provider_type|markstream-vue|stream-monaco|vite-plugin-monaco-editor-esm' src vite package.json
|
||
~~~
|
||
|
||
Expected: Python 断言通过；两个 rg 均无输出并以 1 退出。检查范围故意排除 tests、CHANGELOG、设计文档、计划文档和增量补丁中的预期清理文本；module_ai 下未跟踪 __pycache__ 可以继续存在。
|
||
|
||
- [ ] **Step 4: 检查 APP、环境和用户暂存改动保护**
|
||
|
||
~~~bash
|
||
cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/ShiErFeng
|
||
git status --short --untracked-files=all
|
||
PALLET_PLAN_COMMIT=$(git log -1 --format=%H --fixed-strings --grep='^文档：新增托盘业务实施计划$')
|
||
test -n "$PALLET_PLAN_COMMIT"
|
||
git diff --name-only "$PALLET_PLAN_COMMIT"..HEAD -- shierfeng-fastapi-app shierfeng-fastapi-backend/.env.dev shierfeng-fastapi-backend/.env.prod shierfeng-fastapi-frontend/.env.development shierfeng-fastapi-frontend/.env.docker shierfeng-fastapi-frontend/.env.production shierfeng-fastapi-frontend/.env.staging .idea/git_toolbox_prj.xml
|
||
git diff --name-only "$PALLET_PLAN_COMMIT"..HEAD | rg '(^|/)(__pycache__/|[^/]+\.pyc$)'
|
||
git diff --binary -- shierfeng-fastapi-app | shasum -a 256
|
||
git diff --binary -- shierfeng-fastapi-backend/.env.dev shierfeng-fastapi-backend/.env.prod shierfeng-fastapi-frontend/.env.development shierfeng-fastapi-frontend/.env.docker shierfeng-fastapi-frontend/.env.production shierfeng-fastapi-frontend/.env.staging | shasum -a 256
|
||
git diff --cached --binary -- .idea/git_toolbox_prj.xml | shasum -a 256
|
||
rg -n '"description": "智链云枢管理系统"' shierfeng-fastapi-frontend/package.json
|
||
~~~
|
||
|
||
Expected: 受保护路径历史检查和缓存文件历史检查均无输出；三个 SHA-256 依次仍为 6b7871be6b8cdede4c508adeb345e70084b01583403cfd0aab67e5b3beeb7e1c、5f1189e56551fc16485244e46c8e78cd32ce9ac9f0eaac91cfd0cf42b1ded57a、f21bea19dc68716136d77a3f1567659fd1af2f10f7b1fc6d246851dcfaa645c1；品牌描述命中。工作区原有 .idea/git_toolbox_prj.xml 继续保持暂存状态，package.json 保留用户品牌和本任务依赖/脚本改动但未自动提交。
|
||
|
||
- [ ] **Step 5: 记录未执行验收项**
|
||
|
||
最终交付必须明确标为未验证：
|
||
|
||
- MySQL 真实建表和约束。
|
||
- 运行态 /getRouters 菜单结果。
|
||
- 不同真实角色、仓库和现场映射下的端到端流程。
|
||
- MySQL 行锁、并发竞争和事务回滚。
|
||
- Redis 缓存清理。
|
||
|
||
- [ ] **Step 6: 提交**
|
||
|
||
~~~bash
|
||
git add -- docs/pallet-workflow-deployment.md
|
||
git commit --only -m "文档：补充托盘业务部署说明" -- README.md CHANGELOG.md docs/pallet-workflow-deployment.md
|
||
~~~
|
||
|
||
## 完成标准
|
||
|
||
- AI 专属代码、接口、页面、权限、依赖和新环境 DDL 已移除，共享能力未受影响。
|
||
- “施尔丰仓库”菜单种子及增量清理语句已完成，导航栏独立源码/文档入口仍保留。
|
||
- 18 张 ORM 表、状态机、数据范围、五类事务和六类报表均有无数据库单元测试。
|
||
- 17 个动态页面、44 个按钮权限、后端依赖和 API URL 四方一致。
|
||
- Web 生产构建与 Node 契约测试通过，APP 无本次改动。
|
||
- 两套初始化脚本语义一致，MySQL 补丁只生成不执行且不删除任何 AI 业务表。
|
||
- 最终说明准确列出无法在方案 A 下完成的运行态验收，不把未运行测试表述为通过。
|