niuniu/ShiErFeng
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: niuniu/ShiErFeng:ecb254cb546f078eb1172a24d5e3ca46780f9d0c
Branches Tags
niuniu/ShiErFeng:master niuniu/ShiErFeng:feature/web-redesign
..
compare: niuniu/ShiErFeng:master
Branches Tags
niuniu/ShiErFeng:feature/web-redesign niuniu/ShiErFeng:master
10 Commits
ecb254cb54 .. master
Author SHA1 Message Date
焦龙言 80a71b48ce 添加前后端筛选导出excel按钮权限 2026-10-10 11:39:58 +08:00
yely 3330592fbe fix(layout): 修复侧边栏嵌套子菜单折叠指示箭头错位问题 2026-10-09 21:26:22 +08:00
yely a8af1f542b 为基础资料维护页面增加导入导出 2026-10-09 21:13:43 +08:00
yely a62803ccf0 停止跟踪 Python 构建产物并忽略本地环境 2026-10-09 21:13:43 +08:00
焦龙言 ae662a4941 修正公司名称 2026-10-09 13:28:02 +08:00
焦龙言 d00c725320 更新dockercompose模版文件默认绑定地址为0.0.0.0 2026-10-09 09:38:55 +08:00
焦龙言 3dc2a308eb 开启测试模式加密传输 2026-10-09 08:52:25 +08:00
焦龙言 f3393d78fb 停止跟踪本地工具和日志并完善生产迁移交付 2026-10-08 17:40:30 +08:00
焦龙言 56e646bcc1 更新登录页及优化相关功能 2026-10-08 14:13:05 +08:00
焦龙言 9a14b692e3 更新登录页及优化相关功能 2026-10-08 13:57:35 +08:00
373 changed files with 14663 additions and 522226 deletions
Expand all files Collapse all files
.env.docker.example
+1 -1
View File
@@ -1,7 +1,7 @@
# 复制为根目录 .env 后再修改；根目录 .env 已加入 Git 忽略。
# 对外绑定地址和端口（默认仅绑定本机；局域网访问时将 COMPOSE_BIND_IP 改为 0.0.0.0）
COMPOSE_BIND_IP=127.0.0.1
COMPOSE_BIND_IP=0.0.0.0
FRONTEND_HOST_PORT=8080
BACKEND_HOST_PORT=9099
MYSQL_HOST_PORT=13307
.gitignore
+24
View File
@@ -1 +1,25 @@
/.env
# 本机工具、工作记录和运行日志：保留本地文件，不进入版本库。
/.idea/
/.pnpm-store/
/.superpowers/
/docs/
/logs/
/shierfeng-fastapi-backend/logs/
# Python 运行及检查缓存。
__pycache__/
*.py[cod]
.pytest_cache/
.ruff_cache/
# 本地依赖；前端和 APP 构建产物继续由各自 .gitignore 管理。
node_modules/
/.venv/
/venv/
/shierfeng/
# Python 安装与构建产物，源码以 cli/ 为准。
*.egg-info/
/shierfeng-fastapi-backend/build/
.idea/.gitignore
Generated
-10
View File
@@ -1,10 +0,0 @@
# Default ignored files
/shelf/
/workspace.xml
# Ignored default folder with query files
/queries/
# Datasource local storage ignored files
/dataSources/
/dataSources.local.xml
# Editor-based HTTP Client requests
/httpRequests/
.idea/ShiErFeng.iml
Generated
-10
View File
@@ -1,10 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<module type="PYTHON_MODULE" version="4">
<component name="NewModuleRootManager">
<content url="file://$MODULE_DIR$">
<excludeFolder url="file://$MODULE_DIR$/venv" />
</content>
<orderEntry type="jdk" jdkName="Python 3.10 (ShiErFeng)" jdkType="Python SDK" />
<orderEntry type="sourceFolder" forTests="false" />
</component>
</module>
.idea/git_toolbox_prj.xml
Generated
-15
View File
@@ -1,15 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="GitToolBoxProjectSettings">
<option name="commitMessageIssueKeyValidationOverride">
<BoolValueOverride>
<option name="enabled" value="true" />
</BoolValueOverride>
</option>
<option name="commitMessageValidationEnabledOverride">
<BoolValueOverride>
<option name="enabled" value="true" />
</BoolValueOverride>
</option>
</component>
</project>
.idea/inspectionProfiles/Project_Default.xml
Generated
-25
View File
@@ -1,25 +0,0 @@
<component name="InspectionProjectProfileManager">
<profile version="1.0">
<option name="myName" value="Project Default" />
<inspection_tool class="PyPep8NamingInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true">
<option name="ignoredErrors">
<list>
<option value="N806" />
<option value="N803" />
<option value="N802" />
<option value="N801" />
</list>
</option>
</inspection_tool>
<inspection_tool class="PyUnresolvedReferencesInspection" enabled="true" level="WARNING" enabled_by_default="true">
<option name="ignoredIdentifiers">
<list>
<option value="list.to_numpy" />
<option value="str.__or__" />
<option value="str.like" />
<option value="nacos.client" />
</list>
</option>
</inspection_tool>
</profile>
</component>
.idea/inspectionProfiles/profiles_settings.xml
Generated
-6
View File
@@ -1,6 +0,0 @@
<component name="InspectionProjectProfileManager">
<settings>
<option name="USE_PROJECT_PROFILE" value="false" />
<version value="1.0" />
</settings>
</component>
.idea/misc.xml
Generated
-7
View File
@@ -1,7 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="Black">
<option name="sdkName" value="Python 3.11 (TavernProgram)" />
</component>
<component name="ProjectRootManager" version="2" project-jdk-name="Python 3.10 (ShiErFeng)" project-jdk-type="Python SDK" />
</project>
.idea/modules.xml
Generated
-8
View File
@@ -1,8 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="ProjectModuleManager">
<modules>
<module fileurl="file://$PROJECT_DIR$/.idea/ShiErFeng.iml" filepath="$PROJECT_DIR$/.idea/ShiErFeng.iml" />
</modules>
</component>
</project>
.idea/vcs.xml
Generated
-6
View File
@@ -1,6 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="VcsDirectoryMappings">
<mapping directory="" vcs="Git" />
</component>
</project>
.pnpm-store/v11/index.db
BIN
View File
Binary file not shown.
.pnpm-store/v11/projects/56837299f9596cf3ced974c322f66809
-1
View File
@@ -1 +0,0 @@
../../../shierfeng-fastapi-app
.superpowers/sdd/2026-09-22-test-data-batch-cleanup/task-5-report.md
-152
View File
@@ -1,152 +0,0 @@
# Task 5 交接报告
## Status
INCOMPLETE。当前尝试未完成 Task 5，未提交 commit。
## 已修改文件
本次 Task 5 尝试涉及 brief 白名单中的 18 个文件：
- `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/dao/operation_dao.py`
- `shierfeng-fastapi-backend/module_business/dao/inventory_dao.py`
- `shierfeng-fastapi-backend/module_business/service/inbound_service.py`
- `shierfeng-fastapi-backend/module_business/service/filling_service.py`
- `shierfeng-fastapi-backend/module_business/service/shipment_service.py`
- `shierfeng-fastapi-backend/module_business/service/usage_service.py`
- `shierfeng-fastapi-backend/module_business/service/return_service.py`
- `shierfeng-fastapi-backend/tests/module_business/test_inbound_service.py`
- `shierfeng-fastapi-backend/tests/module_business/test_filling_service.py`
- `shierfeng-fastapi-backend/tests/module_business/test_shipment_service.py`
- `shierfeng-fastapi-backend/tests/module_business/test_usage_service.py`
- `shierfeng-fastapi-backend/tests/module_business/test_return_service.py`
- `shierfeng-fastapi-backend/tests/module_business/test_inventory_dao.py`
## RED 证据
初始聚焦命令运行五类业务 service 与 inventory DAO 测试，共 282 个测试，结果为 `38 failures`。该 RED 结果用于确认显式 scope 契约、批次锁首语句、派生记录继承和 DAO scope 隔离的缺口。
## 阶段性结果
随后按单文件继续迁移测试调用和断言，当前结果为：
- `test_inbound_service`：55 tests，`24 failures / 9 errors`
- `test_return_service`：46 tests，`16 failures / 9 errors`
- `test_inventory_dao`：42 tests，`16 failures / 17 errors`
失败根因主要是既有测试中的旧 service/DAO 调用、旧参数顺序和旧 `assert_awaited_*` 断言尚未完成显式 scope 迁移；同时仍存在真实的跨 scope 校验、测试写入批次锁顺序、既有库存 ownership 保持和相关回滚行为需要继续实现与验证。生产接口当前保持 scope 必填，没有增加默认 formal scope。
## 未完成项
- 尚未使六个目标测试文件逐组 GREEN。
- 尚未完成五条业务链路的完整跨 scope、批次锁首语句、派生 `test_batch_id` 和既有库存 ownership 验证。
- 尚未运行 brief 要求的完整 282+ 回归测试。
- 尚未运行最终 Ruff format/check 和 diff check。
- 尚未执行精确白名单 `git commit --only`，当前没有可提交 SHA。
## 交接结论
这是 INCOMPLETE 交接，不代表 Task 5 完成。后续应从测试调用/断言迁移继续，修复每个单文件的真实 scope 与锁顺序失败，完成全套验证后再生成正式提交和最终报告。
## Task 5 最终结果（2026-09-23）
### Status
DONE。18 个白名单文件的 Task 5 实现、测试 scope 迁移和格式修复已完成；未提交 commit。生产代码保留显式 scope 必填，没有添加 formal 默认值；测试/生产数据中 `test_batch_id=NULL` 仍表示正式数据。
### 本轮完成
- 完成 `test_return_service.py` 的旧 DAO 调用、内部 helper 调用和 mock 断言迁移，补齐显式 `TestBatchScope`。
- 完成 `test_inventory_dao.py` 的 DAO 签名期望、列表参数顺序、幂等查询、详情/锁查询和写入调用迁移。
- 对 5 个控制器和 6 个业务测试文件执行白名单范围内的 Ruff 导入/格式修复；未修改白名单之外的源码、测试、日志或 pycache。
- 复核生产实现：DAO 根查询及明细查询应用 `batch_scope_condition`；测试写入口首条数据库语句锁定 active batch；派生订单、明细和事件显式继承 `test_batch_id`；已有库存未被改写 ownership；入库/发货旧 DELETE 在访问 DAO 前固定抛出批次清理提示；授权、状态机、幂等、锁顺序和回滚回归通过。
### 验证命令与真实结果
1. `PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_inbound_service`：`Ran 55 tests ... OK`。
2. `PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_filling_service`：`Ran 42 tests ... OK`。
3. `PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_shipment_service`：`Ran 46 tests ... OK`。
4. `PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_usage_service`：`Ran 51 tests ... OK`。
5. `PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_return_service`：`Ran 46 tests ... OK`。
6. `PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_inventory_dao`：`Ran 42 tests ... OK`。
7. 六文件合并命令：`PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_inbound_service tests.module_business.test_filling_service tests.module_business.test_shipment_service tests.module_business.test_usage_service tests.module_business.test_return_service tests.module_business.test_inventory_dao -v`：`Ran 282 tests ... OK`。
8. 白名单 `ruff format --check`：`18 files already formatted`，exit 0。
9. 白名单 `ruff check`：`All checks passed!`，exit 0。
10. 目录级 `ruff check module_business/controller module_business/dao module_business/service tests/module_business`：`All checks passed!`，exit 0。
11. 白名单范围 `git diff --check -- <18 files>`：无输出，exit 0。
12. 全仓 `git diff --check`：exit 2；首个实际根因为用户已有 `shierfeng-fastapi-backend/logs/2026/09/20/info.log` 的 trailing whitespace，未修改日志。
### Concerns
- 目录级 `ruff format --check module_business/controller module_business/dao module_business/service tests/module_business` 仍 exit 1，精确列出 4 个非白名单文件：`module_business/dao/test_batch_dao.py`、`module_business/service/test_batch_service.py`、`tests/module_business/test_sql_contract.py`、`tests/module_business/test_test_batch_service.py`。受本任务 18 文件白名单约束，未修改。
- 全仓 `git diff --check` 仍被用户已有日志 trailing whitespace 阻断；Task 5 白名单范围检查已通过。
## 停止长任务交接（2026-09-23）
本次停止请求已立即停止后续工作；当前没有仍在运行的测试或命令，没有回滚工作区改动，也未提交 commit。
本次停止请求本身未启动新命令，因此没有新增命令输出。停止前最近一次真实验证结果保持不变：六个单文件测试分别为 `55/55`、`42/42`、`46/46`、`51/51`、`46/46`、`42/42`，合并回归为 `Ran 282 tests ... OK`；白名单 Ruff format/check 和白名单 `git diff --check` 均 exit 0。
剩余阻塞/concerns：
- 目录级 Ruff format 仍因 4 个非白名单文件未格式化而 exit 1：`module_business/dao/test_batch_dao.py`、`module_business/service/test_batch_service.py`、`tests/module_business/test_sql_contract.py`、`tests/module_business/test_test_batch_service.py`。
- 全仓 `git diff --check` 仍因用户已有 `shierfeng-fastapi-backend/logs/2026/09/20/info.log` trailing whitespace 而 exit 2；未修改该日志。
## Task 5 Fix Round 1（2026-09-23）
### Status
DONE_WITH_CONCERNS。review 指出的生产缺陷已修复，并创建了退回申请 `IntegrityError` 入口回归和事件历史指针 scope SQL 回归；未执行真实数据库写入或迁移。
### 修复内容
- `ReturnService.request_return_services` 现在向 `_recover_request_integrity_error` 传入 `test_scope`；入口回归通过真实恢复分支验证同一 TEST batch 的幂等赢家稳定返回。
- 六个 `IntegrityError` recovery helper 在任何授权或业务查询前调用 `lock_active_batch`；退回申请的 site 重授权 helper 不再在 site 行锁后锁 batch。退回申请、确认及使用在预读 rollback 后开始的新事务也先重锁 batch。
- `InventoryDao.add_event` 现在强制接收 `scope`，历史 `last_event_id` 查询加入 `batch_scope_condition(BizPalletEvent.test_batch_id, scope)`；五个服务的全部事件写入调用均传递当前 scope。
- 入库和发货 DELETE OpenAPI summary/description 更新为固定拒绝消息：`不支持单条物理删除，请通过测试数据批次清理`。
- 业务测试中的事件 DAO 替身更新为四参 API。
### TDD 与验证命令（真实输出摘要）
1. RED：`cd shierfeng-fastapi-backend && PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_return_service.ReturnRequestTransactionRedTest.test_request_integrity_error_recovers_same_test_batch_idempotently -v`：exit 1，`TypeError: ReturnService._recover_request_integrity_error() missing 1 required positional argument: 'test_scope'`。
2. RED：`cd shierfeng-fastapi-backend && PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_inventory_dao.TestDaoPublicContract.test_inventory_dao_critical_parameter_names_are_stable tests.module_business.test_inventory_dao.TestInventoryDao.test_add_event_reads_exact_previous_pointer_and_updates_inventory -v`：exit 1，`add_event` 缺少 `scope` 参数，调用报 `takes 4 positional arguments but 5 were given`。
3. GREEN：上述退回入口单测：`Ran 1 test in 0.023s`，`OK`。
4. GREEN：`TestDaoPublicContract.test_inventory_dao_critical_parameter_names_are_stable` 及三个 `add_event` DAO 单测：`Ran 4 tests in 0.021s`，`OK`。
5. 单文件：`PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_inbound_service -v`：`Ran 55 tests ... OK`。
6. 单文件：`PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_filling_service -v`：`Ran 42 tests ... OK`。
7. 单文件：`PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_shipment_service -v`：`Ran 46 tests ... OK`。
8. 单文件：`PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_usage_service -v`：`Ran 51 tests ... OK`。
9. 单文件：`PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_return_service -v`：`Ran 47 tests ... OK`。
10. 单文件：`PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_inventory_dao -v`：`Ran 42 tests ... OK`。
11. 合并：`PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest tests.module_business.test_inbound_service tests.module_business.test_filling_service tests.module_business.test_shipment_service tests.module_business.test_usage_service tests.module_business.test_return_service tests.module_business.test_inventory_dao -v`：`Ran 283 tests in 1.761s`，`OK`。计数为 283 是本轮新增退回恢复回归的结果。
12. `PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m ruff format --check <18 个白名单文件>`：`18 files already formatted`，exit 0。
13. `PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m ruff check <18 个白名单文件>`：`All checks passed!`，exit 0。
14. `git diff --check -- <18 个白名单文件及本报告>`：无输出，exit 0（在追加本段前执行；追加后会在提交前重新执行）。
### Concerns
- 本轮新增的 TEST scope 入口成功回归目前集中于退回申请；入库、装填、发货和使用的既有业务成功回归仍以 `TestBatchScope.formal()` 为主。生产路径、DAO SQL scope 条件和六文件回归均已验证，但尚未为这四条链路分别补齐 TEST batch 成功、跨批次拒绝、CLOSED 拒绝、派生字段和 rollback 的专门用例。
- 目录级 Ruff format 和全仓 `git diff --check` 的既有非白名单阻塞仍按上文保留，未修改用户文件。
## Task 5 接管后补充（2026-09-23）
### 本轮修复
- 为正式模式 `SimpleNamespace` 仓库替身补齐 `test_batch_id=None`，保留服务层对已加载对象的强制 scope 校验。
- 入库、装填、发货扫码路径对仓库/现场、托盘、库存和活动装填记录增加显式 `assert_record_in_scope` 防御校验；不放宽 DAO 过滤。
- 装填与发货各增加 TEST scope 跨批次写入回滚回归；装填与发货扫码各增加跨批次对象拒绝回归。
### 最新验证
1. 红测：装填与发货跨批次扫码用例在新增服务校验前分别以 `ServiceException not raised` 失败；两条写入用例同时确认回滚路径可用。
2. 绿测：四条新增回归：`Ran 4 tests ... OK`。
3. 六文件合并：`PYTHONDONTWRITEBYTECODE=1 OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 /Users/jiaolongyan/miniconda3/envs/ShiErFeng/bin/python -u -m unittest tests.module_business.test_inbound_service tests.module_business.test_filling_service tests.module_business.test_shipment_service tests.module_business.test_usage_service tests.module_business.test_return_service tests.module_business.test_inventory_dao -v`：`Ran 290 tests ... OK`。
4. 18 文件 `ruff format --check`：`18 files already formatted`；`ruff check`：`All checks passed!`。
5. 18 文件范围 `git diff --check`：无输出，exit 0。
当前 Task 5 代码已具备提交条件；本报告仍只保留为本地审查材料，不应纳入业务提交。
LICENSE
+10 -17
View File
@@ -1,21 +1,14 @@
MIT License
# ShiErFeng 专有版权声明
Copyright (c) 2024 insistence
Copyright (c) 2024-2026 Sylvan International Biotechnology Co., Ltd.
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
除 [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md) 或具体文件另有说明的
第三方代码外，本仓库中的源代码、业务逻辑、界面设计、文档及其他原创内容
均为施尔丰国际生物科技有限公司的专有内容。
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
未经版权持有人书面许可，不得复制、修改、分发、再许可或将上述原创内容
用于其他项目或商业用途。
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
本文件不改变第三方代码所适用的原始许可证。RuoYi 来源代码的版权声明和
MIT License 请参阅 [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md)。
README.md
+10 -2
View File
@@ -45,9 +45,17 @@
* 只读报表：托盘库存、装填记录、发货出库、产线消耗、退回仓库、托盘追溯。
* Android PDA 可通过基于 uni-app 的 H5 页面使用，并支持 HID 扫码枪扫码后回车提交。
本轮交付包含 PDA H5 页面，但暂不打包 APK 或其他原生安装包，也未调用设备摄像头。上线前请阅读[托盘流转业务部署说明](./docs/pallet-workflow-deployment.md)。
本轮交付包含 PDA H5 页面，但暂不打包 APK 或其他原生安装包，也未调用设备摄像头。上线前请阅读[托盘流转业务部署说明](./shierfeng-fastapi-backend/sql/pallet-workflow-deployment.md)。
测试数据批次的创建、授权、历史数据纳入和清理流程请阅读[测试数据批次操作说明](./docs/test-data-batch-operations.md)。
测试数据批次的创建、授权、历史数据纳入和清理流程请阅读[测试数据批次操作说明](./shierfeng-fastapi-backend/sql/test-data-batch-operations.md)。
数据库初始化与升级入口请阅读 [SQL 使用说明](./shierfeng-fastapi-backend/sql/README.md)。新空库直接使用已包含隧道、物料日期、收货和 FIFO 结构的初始化 SQL；已有生产库不得运行全量初始化，请按[生产 Compose 增量迁移说明](./shierfeng-fastapi-backend/sql/production-compose-material-flow-migration-20261008.md)核对适用条件后执行。
### Git 跟踪范围
根目录 `.idea/`、`.pnpm-store/`、`.superpowers/`、`docs/`、`logs/` 及后端 `logs/` 仅保留本地，不再提交；Python 缓存及本地依赖同样忽略。必要的业务部署与数据库迁移说明随后端 `sql/` 目录维护。代码、迁移 SQL、测试和必要部署配置仍正常跟踪。
其他已有克隆首次拉取本次清理提交前，应先备份这些目录中需要保留的文件：Git 可能删除此前被跟踪的副本。此次清理不重写历史，旧提交中的文件仍然存在。
## 在线体验
THIRD-PARTY-NOTICES.md
+32
View File
@@ -0,0 +1,32 @@
# 第三方软件声明
本文件用于说明本项目中涉及的第三方来源代码及其适用许可证。本项目自身的业务代码、界面设计、文档和品牌内容仍以仓库根目录 [LICENSE](./LICENSE) 中的专有版权声明为准。
## RuoYi-Vue3-FastAPI
本项目 Web 前端部分参考并包含来源于 [RuoYi-Vue3-FastAPI](https://github.com/insistence/RuoYi-Vue3-FastAPI) 的代码及其衍生部分。
来源项目保留以下版权声明和 MIT 许可证文本：
```text
The MIT License (MIT)
Copyright (c) 2018 RuoYi
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```
docs/pallet-workflow-deployment.md
-86
View File
@@ -1,86 +0,0 @@
# 托盘流转业务部署说明
## 适用范围与当前状态
本文适用于 MySQL 增量补丁：
`shierfeng-fastapi-backend/sql/patches/20260724_pallet_workflow_mysql.sql`
2026-07-27 已在本地主工作区 `.env.dev` 指向的 MySQL 8.0.36 执行该补丁，且完成下述本地核对。其他环境尚未执行，Redis 缓存也未清理；本记录不能替代其他环境的上线审批、备份及恢复演练。
## 上线前门禁
执行补丁前必须完成以下准备：
1. 对目标 MySQL 实例进行完整备份，至少覆盖库结构、业务数据、菜单和角色关联数据，并验证备份可读。
2. 在隔离环境完成恢复演练，确认恢复步骤、耗时和责任人，不能只以“备份命令成功”代替可恢复性验证。
3. 由 DBA 人工审查补丁、目标库现状、已有同名表结构、固定菜单 ID 和回退方案。
4. 申请维护窗口，在补丁执行和缓存清理完成前保持后端停止，不接入业务流量。
任一门禁未满足时，不得执行补丁。
## MySQL 补丁执行与核对
MySQL DDL 会隐式提交，因此必须将补丁的 DDL、DML 分节执行，并在每一节后逐项核对结果。执行失败时不能假设整个补丁已自动回滚，应立即停止后续步骤，由 DBA 根据实际已提交状态决定人工修复或从已验证备份恢复。
### 1. DDL 节
1. 先执行补丁中的 DDL 节，逐表核对表结构、索引、外键和约束。
2. `CREATE TABLE IF NOT EXISTS` 只会跳过已经存在的同名表，不会修复已存在但结构发生漂移的表。发现同名表时，必须先人工比对实际结构；存在差异时停止执行并制定独立修复方案。
3. DDL 节核对通过前，不得继续执行 DML 节。
### 2. DML 节
1. DML 节包含固定 64 行菜单 seed。执行后必须核对结果恰为 64 行，并确认稳定字段与补丁定义一致。
2. 任一固定 ID 与未知既有数据冲突时，必须停止并由 DBA、业务负责人共同人工处理；不得覆盖、改写或复用未知 ID，也不得绕过冲突继续执行。
3. DML 节核对失败时，不得清理缓存或启动后端。
### 3. 2026-07-27 本地执行记录
1. 执行前备份：`/private/tmp/shierfeng-fastapi-before-pallet-workflow-20260727-1925.sql`，文件权限 `600`，大小 69,180 字节，SHA-256 为 `a217a7b071c7e3ecda0d4c94dd1010711b6061025148689156405b70a02f6c7e`。已校验文件非空、可读且包含核心系统表；未执行恢复演练。
2. DDL 分节执行成功：新增 18 张 `biz_*` InnoDB 表，业务域幂等键的复合唯一索引列顺序已核对。
3. DML 分节使用标准 `mysql` 批处理执行，未使用 `--force` 或 continue-on-error 模式。64 条新业务菜单已写入，旧 AI/外链菜单、AI 字典及旧角色映射已核对为 0。
4. 新菜单没有自动授予普通角色；后续应通过现有角色菜单机制按实际职责分配。
## 历史 AI/Agno 遗留表
曾运行过历史 AI/Agno 版本的数据库可能残留以下 11 张表：
* `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`
本补丁不会删除或修改这些表。未经另行确认，不得处理这些历史表。后续如需清理，应单独盘点表结构、数据量和外部依赖，完成备份与恢复验证，确认无消费者后，再通过独立变更审批和维护窗口人工执行。
## Redis 缓存清理
只有 MySQL 补丁全部执行成功且核对通过后，才能在目标 Redis 实例定向清理以下缓存：
* `api_cache:login:user:routers:*`
* `api_cache:login:user:info:*`
* `sys_dict:ai_provider_type`
对前两类模式应使用 `SCAN` 定位后逐项删除，只处理明确匹配的键；禁止使用 `FLUSHALL`。本轮未执行任何 Redis 缓存清理，不能把上述清单视为已清理证明。
## 启动与运行态验收
正式环境只有在 MySQL 补丁成功、逐节核对通过并完成上述定向缓存清理后，才可启动后端并开展运行态验收。至少应核对 `/getRouters` 返回的托盘业务菜单、真实角色权限，以及真实用户与仓库/客户现场映射下的业务访问范围，再验证响应式 Web 页面和 Android PDA HID 扫码回车流程。
本地环境已使用独立查询参数验证管理员 `/getRouters`：包含 3 个新业务目录和 17 个业务页面，不包含 AI 管理或“施尔丰仓库”。该结果不等于已完成 Redis 清理，也不代表普通角色已完成授权验收。
## 本轮未验证项
以下事项需要在后续真实环境中验证，本轮没有完成：
* 备份恢复演练。
* 真实角色与仓库/客户现场映射的端到端（E2E）流程。
* MySQL 行锁、并发和事务回滚行为。
* Redis 缓存清理。
docs/superpowers/pda-acceptance-training-runbook.md
-106
View File
@@ -1,106 +0,0 @@
# PDA 托盘业务验收与培训手册
## 1. 文档目的
本手册用于服务器、数据库和 PDA 设备准备完成后的现场验收与客户培训。它不替代部署、数据库迁移或 APK 打包，也不把本地构建结果视为真机验收结果。
当前代码交付物是 uni-app PDA 页面、接口封装、HID 扫码组件和可验证 H5 构建；APK 按当前范围暂不生成。
## 2. 验收前置条件
- 后端服务已部署并可从 PDA 访问，已确定 `VITE_APP_BASE_API` 对应地址。
- 数据库已执行与目标数据库类型匹配的初始化 SQL/业务补丁，并完成备份。
- Redis、JWT、传输加密和验证码配置已按目标环境确认。
- 已准备管理员、仓库操作员、客户现场操作员三类账号，并分别配置仓库/现场数据范围。
- 已准备至少两个空托盘、一个已装填托盘、一个可部分使用托盘和一个可退回托盘；每个托盘二维码唯一且可扫描。
- PDA 与扫码头处于 HID 键盘输入模式，扫码结束符配置为回车；网络稳定性和离线恢复策略已确认。
- 验收记录表包含：用例编号、账号、托盘码、时间、预期结果、实际结果、截图/日志、问题编号和签字人。
## 3. 角色验收
| 角色 | 应能操作 | 不应能操作 |
| --- | --- | --- |
| 管理员 | 在授权范围内查看基础资料、业务单、报表和追溯 | 不应绕过后端权限与数据范围 |
| 仓库操作员 | 入库、装填、发货、退回收货 | 不应操作未授权仓库或客户现场 |
| 客户现场操作员 | 扫码查看托盘、绑定产线、录入使用、发起退回 | 不应确认仓库收货或访问未授权现场 |
登录页默认填充用户名 `admin`；密码必须由操作员现场手工输入，不记录在测试单、日志或源码中。
## 4. 核心业务验收用例
### 4.1 基础资料与二维码
1. Web 后台新增菌种、客户、现场、产线、仓库和托盘。
2. 为托盘设置容量，生成并查看固定二维码。
3. 重复托盘编号或二维码应被拒绝；停用托盘不能进入业务流程。
4. 为仓库和现场分配用户，使用受限账号确认数据范围。
### 4.2 入库
1. 仓库用户选择授权仓库，扫描 `UNSTOCKED` 托盘。
2. 重复扫描同一托盘应被前端提示并不会重复加入。
3. 创建入库草稿，移除一条明细后保存并重新进入详情。
4. 确认入库，检查库存状态变为仓库空托盘，并检查托盘事件。
5. 在响应丢失后使用同一操作重试，确认不会重复入库。
### 4.3 装填
1. 扫描仓库空托盘，确认页面显示仓库、容量和当前余量。
2. 选择菌种，录入批次、规格和正整数包数。
3. 使用 0、负数、超容量和未授权仓库数据验证后端拒绝。
4. 提交成功后检查状态、菌种、批次、初始包数和装填事件。
### 4.4 发货
1. 选择授权来源仓库和目标客户现场，连续扫描可发货托盘。
2. 检查页面展示的菌种、批次和剩余包数为服务端数据。
3. 创建草稿并确认，检查来源库存扣减、现场位置和发货事件。
4. 用同一幂等键重试确认，确认不会重复扣减库存。
### 4.5 客户现场使用
1. 现场用户扫描已发货托盘，确认菌种、批次和剩余包数可读。
2. 首次使用选择当前现场产线，录入正整数使用包数。
3. 使用小于余量的包数，确认状态为部分使用且剩余包数正确。
4. 使用剩余全部包数，确认状态为现场空托盘且剩余包数为 0。
5. 尝试切换已绑定的其他产线、超出余量或使用 0 包，确认请求被拒绝。
### 4.6 退回
1. 现场用户选择目标仓库并扫描可退回托盘，提交退回申请。
2. 检查托盘状态进入退回中，不能再次发货或重复申请。
3. 仓库用户查看退回详情，扫描整集合托盘并确认收货。
4. 漏扫、错扫、重复扫和余量快照变化均应阻止确认。
5. 确认成功后检查仓库库存、托盘状态和退回事件。
## 5. 报表、权限与异常验收
- 查看托盘库存、装填、发货、产线消耗、退回和托盘追溯六类报表。
- 用受限账号验证未授权菜单不显示，直接调用接口返回 403。
- 检查关键写操作包含操作人、时间、业务单和托盘事件。
- 在扫码请求期间连续回车，确认输入锁生效且不会并发提交。
- 断网后重试，确认使用原幂等键；网络恢复后不会重复扣减库存。
- 使用非法状态、库存不足、错误仓库/现场和旧详情快照，确认错误可见且状态不被部分写入。
## 6. 培训顺序
1. 讲解托盘二维码、状态和“服务端结果为准”原则。
2. 仓库操作员练习入库、装填、发货和退回收货。
3. 客户现场操作员练习扫码、产线选择、部分/全部使用和退回申请。
4. 管理员练习基础资料、用户数据范围、报表和托盘追溯。
5. 演练重复扫码、断网重试、无权限和库存不足，不使用真实业务数据做首次演示。
6. 培训结束后由各角色完成一条完整闭环：入库 → 装填 → 发货 → 使用 → 退回。
## 7. 当前不包含事项
- 本阶段不打包、签名、安装或发布 APK。
- 本阶段不调用摄像头扫码，不新增原生扫码 SDK；扫码方式为 HID 扫码头加手工输入兜底。
- 本手册不执行生产部署、数据库迁移、密码重置或客户培训；这些动作需在目标环境中按前置条件执行并留存记录。
## 8. 代码证据
- 设计与需求覆盖矩阵：`docs/superpowers/specs/2026-09-20-pda-business-workflow-design.md`
- PDA 页面与接口：`shierfeng-fastapi-app/src/pages/business`、`shierfeng-fastapi-app/src/api/business`
- Web 基础资料、业务和报表：`shierfeng-fastapi-frontend/src/views`
- 后端业务与状态机：`shierfeng-fastapi-backend/module_business`
- 数据库结构：`shierfeng-fastapi-backend/sql`
docs/superpowers/plans/2026-07-24-pallet-workflow-system.md
-1843
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/plans/2026-07-27-promote-business-menus.md
-774
View File
@@ -1,774 +0,0 @@
# 业务菜单一级展示 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:** 将“基础资料维护”“业务管理”“报表查询”提升为独立一级菜单，并让六个目标一级目录按 121、122、123、1、2、3 的顺序展示。
**Architecture:** Web 菜单继续由后端 /getRouters 根据 sys_menu 动态生成，不增加前端拍平或重排代码。新建库通过 MySQL/PostgreSQL 初始化 SQL 得到目标层级，已有 MySQL 库通过独立、幂等、fail-closed 的 20260727 增量补丁迁移；已执行的 20260724 历史补丁保持不变。
**Tech Stack:** MySQL 8、PostgreSQL、Python 3.10 unittest、Ruff、Vue 3、Vite 6、Node 20。
---
## 文件结构与保护边界
- 修改 shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py：区分初始化器目标状态与 20260724 补丁历史状态，并新增 20260727 补丁契约。
- 修改 shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql：新建 MySQL 数据库的六个一级菜单层级与排序。
- 修改 shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql：新建 PostgreSQL 数据库的六个一级菜单层级与排序。
- 创建 shierfeng-fastapi-backend/sql/patches/20260727_promote_business_menus_mysql.sql：迁移现有 MySQL 数据库。
- 不修改 shierfeng-fastapi-backend/sql/patches/20260724_pallet_workflow_mysql.sql。
- 不修改 Web 前端源码、APP、API、权限标识、角色菜单关联、业务子菜单或数据库表结构。
- 当前工作区已有 APP、后端/前端环境文件和已暂存 .idea/git_toolbox_prj.xml；每次暂存和提交都必须按路径执行，禁止 git add -A。
## Task 1：用契约固定初始化器的目标层级，并保留历史补丁语义
**Files:**
- Modify: 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
- Preserve: shierfeng-fastapi-backend/sql/patches/20260724_pallet_workflow_mysql.sql
- [ ] **Step 1：先修改契约测试，表达目标状态和历史状态**
在测试文件顶部保留旧补丁路径，并新增新补丁路径：
PATCH_PATH = SQL_ROOT / 'patches/20260724_pallet_workflow_mysql.sql'
MENU_PROMOTION_PATCH_PATH = SQL_ROOT / 'patches/20260727_promote_business_menus_mysql.sql'
把 BUSINESS_MENU_SPECS 的前三行改为初始化器目标值，其余 61 行原样保留：
BUSINESS_MENU_SPECS = """
121|0|基础资料维护|businessMaster||1||<NULL>
122|0|业务管理|businessOperation||2||<NULL>
123|0|报表查询|businessReport||3||<NULL>
502|121|菌种资料|strain||1|master:strain:list|master/strain/index
在 EXPECTED_BUSINESS_MENU_FIELDS 和 BUSINESS_MENU_IDS 定义之后加入：
LEGACY_PATCH_BUSINESS_MENU_FIELDS = {
**EXPECTED_BUSINESS_MENU_FIELDS,
121: (1, '基础资料维护', 'businessMaster', '', 10, '', None),
122: (1, '业务管理', 'businessOperation', '', 11, '', None),
123: (1, '报表查询', 'businessReport', '', 12, '', None),
}
EXPECTED_TOP_LEVEL_MENU_POSITIONS = {
121: ('基础资料维护', 0, 1),
122: ('业务管理', 0, 2),
123: ('报表查询', 0, 3),
1: ('系统管理', 0, 4),
2: ('系统监控', 0, 5),
3: ('系统工具', 0, 6),
}
MENU_PROMOTION_IDS = set(EXPECTED_TOP_LEVEL_MENU_POSITIONS)
不要把 1、2、3 加入 BUSINESS_MENU_IDS；该集合还被“新业务菜单不默认授权角色”的现有测试使用。
把菜单提取和字段断言改为以下实现：
def _menu_rows(sql: str, menu_ids: set[int]) -> dict[int, list]:
rows = _insert_rows(sql, 'sys_menu')
selected = [
row
for row in rows
if row and str(row[0]).isdigit() and int(row[0]) in menu_ids
]
counts = {
menu_id: sum(int(row[0]) == menu_id for row in selected)
for menu_id in menu_ids
}
if any(count != 1 for count in counts.values()):
raise AssertionError(f'menu row counts differ: {counts}')
return {int(row[0]): row for row in selected}
def _business_menu_rows(sql: str) -> dict[int, list]:
return _menu_rows(sql, BUSINESS_MENU_IDS)
def _assert_business_menu_fields(
test_case: unittest.TestCase,
sql: str,
expected_fields: dict[int, tuple] = EXPECTED_BUSINESS_MENU_FIELDS,
) -> None:
rows = _business_menu_rows(sql)
invalid_widths = {
menu_id: len(row)
for menu_id, row in rows.items()
if len(row) != SYS_MENU_VALUE_COUNT
}
test_case.assertEqual({}, invalid_widths)
actual = {
menu_id: (
int(row[2]),
row[1],
row[4],
row[7],
int(row[3]),
row[13],
row[5],
)
for menu_id, row in rows.items()
}
test_case.assertEqual(expected_fields, actual)
在 test_initializers_define_fixed_business_menus_and_permissions 中把三个根目录断言改成：
self.assertEqual(
('基础资料维护', '0', '1', 'businessMaster', 'M', ''),
tuple(rows[121][index] for index in (1, 2, 3, 4, 10, 13)),
)
self.assertEqual(
('业务管理', '0', '2', 'businessOperation', 'M', ''),
tuple(rows[122][index] for index in (1, 2, 3, 4, 10, 13)),
)
self.assertEqual(
('报表查询', '0', '3', 'businessReport', 'M', ''),
tuple(rows[123][index] for index in (1, 2, 3, 4, 10, 13)),
)
紧接该测试新增六个一级目录的顺序契约：
def test_initializers_define_expected_top_level_menu_order(self) -> None:
for filename in INITIALIZERS:
with self.subTest(filename=filename):
sql = (SQL_ROOT / filename).read_text(encoding='utf-8')
rows = _menu_rows(sql, MENU_PROMOTION_IDS)
actual = {
menu_id: (row[1], int(row[2]), int(row[3]))
for menu_id, row in rows.items()
}
self.assertEqual(EXPECTED_TOP_LEVEL_MENU_POSITIONS, actual)
在 test_patch_is_documented_idempotent_and_contains_full_contract 中，将旧补丁字段断言改成：
_assert_business_menu_fields(
self,
raw,
LEGACY_PATCH_BUSINESS_MENU_FIELDS,
)
同一测试中，旧补丁与当前 MySQL 初始化器的比较只比较不含 parent_id、order_num 的稳定字段：
compared_indexes = (0, 1, *range(4, 15))
self.assertEqual(
{
menu_id: tuple(row[index] for index in compared_indexes)
for menu_id, row in mysql_rows.items()
},
{
menu_id: tuple(row[index] for index in compared_indexes)
for menu_id, row in patch_rows.items()
},
)
- [ ] **Step 2：运行初始化器契约，确认 RED**
工作目录：shierfeng-fastapi-backend
PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest \
tests.module_business.test_sql_contract.SqlContractTest.test_initializers_define_fixed_business_menus_and_permissions \
tests.module_business.test_sql_contract.SqlContractTest.test_initializers_define_expected_top_level_menu_order \
-v
预期：FAIL。MySQL/PostgreSQL 初始化器仍将 121/122/123 放在 parent_id=1、order_num=10/11/12，1/2/3 仍使用 order_num=1/2/3。
- [ ] **Step 3：对两份初始化 SQL 做六行最小修改**
MySQL 的六行目标内容：
insert into sys_menu values('1', '系统管理', '0', '4', 'system', null, '', '', 1, 0, 'M', '0', '0', '', 'system', 'admin', sysdate(), '', null, '系统管理目录');
insert into sys_menu values('2', '系统监控', '0', '5', 'monitor', null, '', '', 1, 0, 'M', '0', '0', '', 'monitor', 'admin', sysdate(), '', null, '系统监控目录');
insert into sys_menu values('3', '系统工具', '0', '6', 'tool', null, '', '', 1, 0, 'M', '0', '0', '', 'tool', 'admin', sysdate(), '', null, '系统工具目录');
insert into sys_menu values('121', '基础资料维护', '0', '1', 'businessMaster', null, '', '', 1, 0, 'M', '0', '0', '', '#', 'admin', sysdate(), '', null, '基础资料维护目录');
insert into sys_menu values('122', '业务管理', '0', '2', 'businessOperation', null, '', '', 1, 0, 'M', '0', '0', '', '#', 'admin', sysdate(), '', null, '业务管理目录');
insert into sys_menu values('123', '报表查询', '0', '3', 'businessReport', null, '', '', 1, 0, 'M', '0', '0', '', '#', 'admin', sysdate(), '', null, '报表查询目录');
把 MySQL 注释“托盘业务目录”同步改为“托盘业务一级目录”。
PostgreSQL 的六行目标内容：
insert into sys_menu values(1, '系统管理', 0, '4', 'system', null, '', '', 1, 0, 'M', '0', '0', '', 'system', 'admin', current_timestamp, '', null, '系统管理目录');
insert into sys_menu values(2, '系统监控', 0, '5', 'monitor', null, '', '', 1, 0, 'M', '0', '0', '', 'monitor', 'admin', current_timestamp, '', null, '系统监控目录');
insert into sys_menu values(3, '系统工具', 0, '6', 'tool', null, '', '', 1, 0, 'M', '0', '0', '', 'tool', 'admin', current_timestamp, '', null, '系统工具目录');
(121, '基础资料维护', 0, '1', 'businessMaster', null, '', '', 1, 0, 'M', '0', '0', '', '#', 'admin', current_timestamp, '', null, ''),
(122, '业务管理', 0, '2', 'businessOperation', null, '', '', 1, 0, 'M', '0', '0', '', '#', 'admin', current_timestamp, '', null, ''),
(123, '报表查询', 0, '3', 'businessReport', null, '', '', 1, 0, 'M', '0', '0', '', '#', 'admin', current_timestamp, '', null, ''),
把 PostgreSQL 注释“初始化-托盘业务菜单和权限”同步改为“初始化-托盘业务一级菜单和权限”。
- [ ] **Step 4：运行 GREEN 和历史补丁兼容回归**
工作目录：shierfeng-fastapi-backend
PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest \
tests.module_business.test_sql_contract.SqlContractTest.test_initializers_define_fixed_business_menus_and_permissions \
tests.module_business.test_sql_contract.SqlContractTest.test_initializers_define_expected_top_level_menu_order \
tests.module_business.test_sql_contract.SqlContractTest.test_mysql_and_postgresql_business_menu_fields_are_identical \
tests.module_business.test_sql_contract.SqlContractTest.test_patch_is_documented_idempotent_and_contains_full_contract \
-v
预期：4 项均通过；旧 20260724 补丁仍按历史层级通过契约，不发生文件改动。
- [ ] **Step 5：提交初始化器和对应契约**
从仓库根目录执行：
git add -- \
shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py \
shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql \
shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql
git commit --only -m '调整：提升业务菜单为一级目录' -- \
shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py \
shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql \
shierfeng-fastapi-backend/sql/shierfeng-fastapi-pg.sql
提交后确认 .idea/git_toolbox_prj.xml 仍单独处于暂存区。
## Task 2：新增幂等、fail-closed 的 MySQL 前向补丁
**Files:**
- Modify: shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py
- Create: shierfeng-fastapi-backend/sql/patches/20260727_promote_business_menus_mysql.sql
- [ ] **Step 1：先写新补丁的失败契约**
在 SqlContractTest 中新增：
def test_menu_promotion_patch_is_fail_closed_atomic_and_exact(self) -> None:
self.assertTrue(
MENU_PROMOTION_PATCH_PATH.is_file(),
f'missing patch: {MENU_PROMOTION_PATCH_PATH}',
)
raw = MENU_PROMOTION_PATCH_PATH.read_text(encoding='utf-8')
self.assertIn('备份', raw)
self.assertIn('未自动执行', raw)
self.assertIn('可幂等重跑', raw)
self.assertIn('禁止使用 mysql --force', raw)
statements = _sql_statements(raw)
normalized = [_normalized_sql_statement(statement) for statement in statements]
expected_table = 'promote_business_menus_expected'
guard_table = 'promote_business_menus_guard'
expected_insert_indexes = [
index
for index, statement in enumerate(normalized)
if statement.startswith(f'insert into {expected_table} ')
]
self.assertEqual(1, len(expected_insert_indexes))
expected_rows = _insert_rows(
statements[expected_insert_indexes[0]],
expected_table,
)
self.assertEqual(6, len(expected_rows))
actual_expected_rows = {
int(row[0]): tuple(row[1:])
for row in expected_rows
}
self.assertEqual(
{
1: ('系统管理', 'system', None, '', '', '1', '0', 'M', '0', '0', '', 'system', '0', '1', '0', '4'),
2: ('系统监控', 'monitor', None, '', '', '1', '0', 'M', '0', '0', '', 'monitor', '0', '2', '0', '5'),
3: ('系统工具', 'tool', None, '', '', '1', '0', 'M', '0', '0', '', 'tool', '0', '3', '0', '6'),
121: ('基础资料维护', 'businessMaster', None, '', '', '1', '0', 'M', '0', '0', '', '#', '1', '10', '0', '1'),
122: ('业务管理', 'businessOperation', None, '', '', '1', '0', 'M', '0', '0', '', '#', '1', '11', '0', '2'),
123: ('报表查询', 'businessReport', None, '', '', '1', '0', 'M', '0', '0', '', '#', '1', '12', '0', '3'),
},
actual_expected_rows,
)
starts = [
index
for index, statement in enumerate(normalized)
if statement == 'start transaction'
]
commits = [
index
for index, statement in enumerate(normalized)
if statement == 'commit'
]
self.assertEqual(1, len(starts))
self.assertEqual(1, len(commits))
start_transaction = starts[0]
commit = commits[0]
row_locks = [
index
for index, statement in enumerate(normalized)
if re.fullmatch(
r'select menu_id from sys_menu '
r'where menu_id in \(1, 2, 3, 121, 122, 123\) '
r'order by menu_id for update',
statement,
)
]
self.assertEqual(1, len(row_locks))
guard_indexes = [
index
for index, statement in enumerate(normalized)
if statement.startswith(f'insert into {guard_table} ')
]
self.assertEqual(2, len(guard_indexes))
precondition_guard = normalized[guard_indexes[0]]
postcondition_guard = normalized[guard_indexes[1]]
self.assertIn('as precondition_guard_rows', precondition_guard)
self.assertIn('as postcondition_guard_rows', postcondition_guard)
self.assertEqual(
2,
precondition_guard.count(
"'promote-business-menus-precondition-conflict'"
),
)
self.assertEqual(
2,
postcondition_guard.count(
"'promote-business-menus-postcondition-conflict'"
),
)
identity_columns = (
('menu_name', 'menu_name'),
('path', 'path'),
('component', 'component'),
('query', 'query_value'),
('route_name', 'route_name'),
('is_frame', 'is_frame'),
('is_cache', 'is_cache'),
('menu_type', 'menu_type'),
('visible', 'visible'),
('status', 'status'),
('perms', 'perms'),
('icon', 'icon'),
)
for actual_column, expected_column in identity_columns:
comparison = (
f'actual.{actual_column} <=> expected.{expected_column}'
)
self.assertIn(comparison, precondition_guard)
self.assertIn(comparison, postcondition_guard)
compact_precondition = re.sub(r'\s+', '', precondition_guard)
self.assertIn('count(actual.menu_id)=6', compact_precondition)
self.assertIn(
'sum((actual.parent_id<=>expected.old_parent_id)'
'and(actual.order_num<=>expected.old_order_num))=6',
compact_precondition,
)
self.assertIn(
'sum((actual.parent_id<=>expected.new_parent_id)'
'and(actual.order_num<=>expected.new_order_num))=6',
compact_precondition,
)
compact_postcondition = re.sub(r'\s+', '', postcondition_guard)
self.assertIn('count(actual.menu_id)=6', compact_postcondition)
self.assertIn(
'sum((actual.parent_id<=>expected.new_parent_id)'
'and(actual.order_num<=>expected.new_order_num))=6',
compact_postcondition,
)
expected_update = (
'update sys_menu set parent_id = case '
'when menu_id in (121, 122, 123) then 0 '
'else parent_id end, order_num = case menu_id '
'when 121 then 1 when 122 then 2 when 123 then 3 '
'when 1 then 4 when 2 then 5 when 3 then 6 '
'else order_num end '
'where menu_id in (1, 2, 3, 121, 122, 123)'
)
update_indexes = [
index
for index, statement in enumerate(normalized)
if statement == expected_update
]
self.assertEqual(1, len(update_indexes))
update_index = update_indexes[0]
permanent_mutations = [
statement
for statement in normalized
if re.match(
r'(?:insert\s+into|replace\s+into|update|delete\s+from)\s+sys_',
statement,
)
]
self.assertEqual([expected_update], permanent_mutations)
self.assertEqual(
(
start_transaction,
row_locks[0],
guard_indexes[0],
update_index,
guard_indexes[1],
commit,
),
tuple(
sorted(
(
start_transaction,
row_locks[0],
guard_indexes[0],
update_index,
guard_indexes[1],
commit,
)
)
),
)
expected_verification = (
'select menu_id, menu_name, parent_id, order_num, path, component, '
'menu_type, visible, status, perms from sys_menu '
'where menu_id in (1, 2, 3, 121, 122, 123) '
'order by order_num, menu_id'
)
self.assertEqual(expected_verification, normalized[-1])
- [ ] **Step 2：运行新补丁契约，确认 RED**
工作目录：shierfeng-fastapi-backend
PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest \
tests.module_business.test_sql_contract.SqlContractTest.test_menu_promotion_patch_is_fail_closed_atomic_and_exact \
-v
预期：FAIL，错误指出缺少 20260727_promote_business_menus_mysql.sql。
- [ ] **Step 3：创建最小 MySQL 前向补丁**
创建 shierfeng-fastapi-backend/sql/patches/20260727_promote_business_menus_mysql.sql，内容如下：
-- 将托盘业务目录 121/122/123 提升为一级菜单，并将系统菜单 1/2/3 后移。
-- 本补丁只更新 sys_menu.parent_id 和 sys_menu.order_num。
-- 本文件未自动执行；执行前必须备份目标数据库。
--
-- 必须在独立连接中使用标准 mysql batch 执行，并确保客户端遇错立即退出。
-- 禁止使用 mysql --force；guard 的 Duplicate entry 是故意设计的 fail-closed 错误，
-- 不能忽略错误继续执行到 commit。
--
-- 允许的写前状态只有两种：
-- 1. 20260724 旧状态；
-- 2. 本补丁目标状态，因此可幂等重跑。
-- 缺行、固定 ID 身份冲突或新旧状态混杂都会在永久更新前中止。
drop temporary table if exists promote_business_menus_expected;
create temporary table promote_business_menus_expected (
menu_id bigint not null,
menu_name varchar(50) not null,
path varchar(200),
component varchar(255),
query_value varchar(255),
route_name varchar(50),
is_frame int,
is_cache int,
menu_type char(1),
visible char(1),
status char(1),
perms varchar(100),
icon varchar(100),
old_parent_id bigint not null,
old_order_num int not null,
new_parent_id bigint not null,
new_order_num int not null,
primary key (menu_id)
) engine=innodb;
insert into promote_business_menus_expected (
menu_id, menu_name, path, component, query_value, route_name,
is_frame, is_cache, menu_type, visible, status, perms, icon,
old_parent_id, old_order_num, new_parent_id, new_order_num
) values
(1, '系统管理', 'system', null, '', '', 1, 0, 'M', '0', '0', '', 'system', 0, 1, 0, 4),
(2, '系统监控', 'monitor', null, '', '', 1, 0, 'M', '0', '0', '', 'monitor', 0, 2, 0, 5),
(3, '系统工具', 'tool', null, '', '', 1, 0, 'M', '0', '0', '', 'tool', 0, 3, 0, 6),
(121, '基础资料维护', 'businessMaster', null, '', '', 1, 0, 'M', '0', '0', '', '#', 1, 10, 0, 1),
(122, '业务管理', 'businessOperation', null, '', '', 1, 0, 'M', '0', '0', '', '#', 1, 11, 0, 2),
(123, '报表查询', 'businessReport', null, '', '', 1, 0, 'M', '0', '0', '', '#', 1, 12, 0, 3);
drop temporary table if exists promote_business_menus_guard;
create temporary table promote_business_menus_guard (
guard_token varchar(64) not null,
primary key (guard_token)
) engine=innodb;
start transaction;
-- 锁定目标行，防止身份校验与更新之间被并发修改。
select menu_id
from sys_menu
where menu_id in (1, 2, 3, 121, 122, 123)
order by menu_id
for update;
-- 写前身份和整体状态校验。失败时重复 token 触发主键冲突并终止 batch。
insert into promote_business_menus_guard (guard_token)
select guard_token
from (
select 'promote-business-menus-precondition-conflict' as guard_token
union all
select if(
count(actual.menu_id) = 6
and sum(
(actual.menu_name <=> expected.menu_name)
and (actual.path <=> expected.path)
and (actual.component <=> expected.component)
and (actual.query <=> expected.query_value)
and (actual.route_name <=> expected.route_name)
and (actual.is_frame <=> expected.is_frame)
and (actual.is_cache <=> expected.is_cache)
and (actual.menu_type <=> expected.menu_type)
and (actual.visible <=> expected.visible)
and (actual.status <=> expected.status)
and (actual.perms <=> expected.perms)
and (actual.icon <=> expected.icon)
) = 6
and (
sum(
(actual.parent_id <=> expected.old_parent_id)
and (actual.order_num <=> expected.old_order_num)
) = 6
or sum(
(actual.parent_id <=> expected.new_parent_id)
and (actual.order_num <=> expected.new_order_num)
) = 6
),
'promote-business-menus-precondition-verified',
'promote-business-menus-precondition-conflict'
) as guard_token
from promote_business_menus_expected as expected
left join sys_menu as actual
on actual.menu_id = expected.menu_id
) as precondition_guard_rows;
-- 永久变更只涉及 parent_id 和 order_num。
update sys_menu
set parent_id = case
when menu_id in (121, 122, 123) then 0
else parent_id
end,
order_num = case menu_id
when 121 then 1
when 122 then 2
when 123 then 3
when 1 then 4
when 2 then 5
when 3 then 6
else order_num
end
where menu_id in (1, 2, 3, 121, 122, 123);
-- 提交前再次校验目标状态，捕获未覆盖行或触发器造成的意外变化。
insert into promote_business_menus_guard (guard_token)
select guard_token
from (
select 'promote-business-menus-postcondition-conflict' as guard_token
union all
select if(
count(actual.menu_id) = 6
and sum(
(actual.menu_name <=> expected.menu_name)
and (actual.path <=> expected.path)
and (actual.component <=> expected.component)
and (actual.query <=> expected.query_value)
and (actual.route_name <=> expected.route_name)
and (actual.is_frame <=> expected.is_frame)
and (actual.is_cache <=> expected.is_cache)
and (actual.menu_type <=> expected.menu_type)
and (actual.visible <=> expected.visible)
and (actual.status <=> expected.status)
and (actual.perms <=> expected.perms)
and (actual.icon <=> expected.icon)
) = 6
and sum(
(actual.parent_id <=> expected.new_parent_id)
and (actual.order_num <=> expected.new_order_num)
) = 6,
'promote-business-menus-postcondition-verified',
'promote-business-menus-postcondition-conflict'
) as guard_token
from promote_business_menus_expected as expected
left join sys_menu as actual
on actual.menu_id = expected.menu_id
) as postcondition_guard_rows;
commit;
drop temporary table promote_business_menus_guard;
drop temporary table promote_business_menus_expected;
-- 固定 ID 事后核对：顺序应为 121、122、123、1、2、3。
select menu_id, menu_name, parent_id, order_num, path, component,
menu_type, visible, status, perms
from sys_menu
where menu_id in (1, 2, 3, 121, 122, 123)
order by order_num, menu_id;
- [ ] **Step 4：运行新补丁契约与完整 SQL 契约**
工作目录：shierfeng-fastapi-backend
PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest \
tests.module_business.test_sql_contract.SqlContractTest.test_menu_promotion_patch_is_fail_closed_atomic_and_exact \
-v
PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest \
tests.module_business.test_sql_contract \
-v
conda run -n ShiErFeng python -m ruff format --check \
tests/module_business/test_sql_contract.py
conda run -n ShiErFeng python -m ruff check \
tests/module_business/test_sql_contract.py
预期：新补丁定向契约通过，完整 SQL 契约全部通过，Ruff format/check 均为成功退出。
- [ ] **Step 5：提交新补丁和对应契约**
从仓库根目录执行：
git add -- \
shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py \
shierfeng-fastapi-backend/sql/patches/20260727_promote_business_menus_mysql.sql
git commit --only -m '迁移：新增业务菜单层级补丁' -- \
shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py \
shierfeng-fastapi-backend/sql/patches/20260727_promote_business_menus_mysql.sql
提交后再次确认 .idea/git_toolbox_prj.xml 仍单独处于暂存区，APP 和环境文件指纹未变化。
## Task 3：完成代码级回归验证
**Files:**
- Verify only: shierfeng-fastapi-backend
- Verify only: shierfeng-fastapi-frontend
- [ ] **Step 1：运行后端业务测试和 SQL 契约**
工作目录：shierfeng-fastapi-backend
PYTHONDONTWRITEBYTECODE=1 conda run -n ShiErFeng python -m unittest discover \
-s tests/module_business -p 'test_*.py' -v
预期：全部业务测试通过，不生成新的 Python 字节码。
- [ ] **Step 2：运行后端格式和静态检查**
工作目录：shierfeng-fastapi-backend
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
预期：两条命令均成功退出，无格式或 lint 错误。
- [ ] **Step 3：运行 Web 契约与生产构建**
工作目录：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
预期：Node 业务契约全部通过，Vite 生产构建成功。构建会读取用户已有的前端环境文件，但本任务不得修改或提交这些文件。
- [ ] **Step 4：检查 diff、提交边界和受保护改动**
从仓库根目录执行：
git diff --check
git status --short --branch
git diff --cached --name-status
预期：git diff --check 无输出；本任务代码已按路径提交；.idea/git_toolbox_prj.xml 仍保持用户原有暂存状态；APP、环境文件、缓存、日志和构建产物未被纳入提交。
## Task 4：经再次确认后迁移本地 MySQL 并验收菜单
**Files:**
- Read configuration: shierfeng-fastapi-backend/.env.dev
- Execute: shierfeng-fastapi-backend/sql/patches/20260727_promote_business_menus_mysql.sql
- Backup output pattern: /private/tmp/shierfeng-fastapi-before-promote-business-menus-YYYYMMDD-HHMMSS.sql
- [ ] **Step 1：停止并取得数据库写入确认**
向用户列出：目标数据库来自 .env.dev、将创建新的全库备份、将执行的补丁文件、只更新 sys_menu 六行的 parent_id/order_num、禁止 mysql --force。没有本次明确确认时不得执行后续步骤。
- [ ] **Step 2：确认后创建新的数据库备份并执行补丁**
工作目录：shierfeng-fastapi-backend。以下命令不打印密码，且 set -e 保证备份或补丁遇错立即退出：
set -euo pipefail
task_db_type=$(sed -nE "s/^[[:space:]]*DB_TYPE[[:space:]]*=[[:space:]]*'([^']*)'.*/\1/p" .env.dev)
task_db_host=$(sed -nE "s/^[[:space:]]*DB_HOST[[:space:]]*=[[:space:]]*'([^']*)'.*/\1/p" .env.dev)
task_db_port=$(sed -nE "s/^[[:space:]]*DB_PORT[[:space:]]*=[[:space:]]*([0-9]+).*/\1/p" .env.dev)
task_db_user=$(sed -nE "s/^[[:space:]]*DB_USERNAME[[:space:]]*=[[:space:]]*'([^']*)'.*/\1/p" .env.dev)
task_db_password=$(sed -nE "s/^[[:space:]]*DB_PASSWORD[[:space:]]*=[[:space:]]*'([^']*)'.*/\1/p" .env.dev)
task_db_name=$(sed -nE "s/^[[:space:]]*DB_DATABASE[[:space:]]*=[[:space:]]*'([^']*)'.*/\1/p" .env.dev)
test "$task_db_type" = 'mysql'
test -n "$task_db_host"
test -n "$task_db_port"
test -n "$task_db_user"
test -n "$task_db_password"
test -n "$task_db_name"
task_backup_path="/private/tmp/shierfeng-fastapi-before-promote-business-menus-$(date +%Y%m%d-%H%M%S).sql"
MYSQL_PWD="$task_db_password" mysqldump \
--host="$task_db_host" \
--port="$task_db_port" \
--user="$task_db_user" \
--single-transaction \
--routines \
--triggers \
--events \
--no-tablespaces \
"$task_db_name" > "$task_backup_path"
test -s "$task_backup_path"
shasum -a 256 "$task_backup_path"
MYSQL_PWD="$task_db_password" mysql \
--host="$task_db_host" \
--port="$task_db_port" \
--user="$task_db_user" \
--database="$task_db_name" \
< sql/patches/20260727_promote_business_menus_mysql.sql
unset task_db_password
预期：生成新的非空备份并输出其 SHA-256；mysql 使用独立连接、未带 --force；补丁最后输出六个目标菜单，parent_id 均为 0，order_num 依次为 1、2、3、4、5、6。
- [ ] **Step 3：只读核对数据库菜单和不变量**
继续使用 .env.dev 解析出的连接参数，在新的 mysql 连接执行：
select menu_id, menu_name, parent_id, order_num, path, component,
menu_type, visible, status, perms
from sys_menu
where menu_id in (1, 2, 3, 121, 122, 123)
order by order_num, menu_id;
select parent_id, count(*) as child_count
from sys_menu
where parent_id in (121, 122, 123)
group by parent_id
order by parent_id;
select count(*) as business_permission_count
from sys_menu
where perms regexp '^(master|business|report):';
预期：六个根目录顺序为 121、122、123、1、2、3；121/122/123 的直属子菜单数为 6、5、6；业务权限菜单总数为 61。
- [ ] **Step 4：重新登录并核对 /getRouters 与 Web 侧边栏**
保持现有前后端启动方式不变，退出 Web 登录后重新登录，使现有登录缓存刷新。确认 /getRouters 返回的根节点依次包含“基础资料维护”“业务管理”“报表查询”“系统管理”“系统监控”“系统工具”，三个业务目录不再出现在“系统管理”的 children 中；侧边栏顺序与返回结果一致。不得执行 Redis FLUSHALL，也不修改 APP。
## 最终验收
- 新建 MySQL/PostgreSQL 数据库直接得到目标一级菜单层级。
- 已有 MySQL 数据库只能从完整旧状态或完整目标状态执行 20260727 补丁；缺行、ID 复用、身份漂移和新旧状态混杂均在永久更新前失败。
- 永久 DML 只更新六个 sys_menu 行的 parent_id/order_num，并在提交前复核目标状态。
- 20260724 历史补丁、子菜单、API、权限标识、角色关联、Web 动态路由机制与 APP 均保持不变。
- 后端业务测试、SQL 契约、Ruff、Web 业务契约和生产构建均通过。
docs/superpowers/plans/2026-09-20-pda-business-workflow-implementation.md
-721
View File
@@ -1,721 +0,0 @@
# PDA 托盘业务操作功能 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:** 在不改变 FastAPI 业务契约的前提下，为 `shierfeng-fastapi-app` 增加可在 H5/开发环境验证的托盘入库、装填、发货、现场使用和退回操作。
**Architecture:** PDA 复用现有 `request`、JWT、传输加密和后端业务接口；API 封装按业务模块拆分，扫码输入和幂等键生成作为无业务状态的共享工具。五个页面各自维护表单、扫码会话、请求代数和服务端刷新状态，后端继续作为权限、库存、状态机、产线绑定和退回集合校验的唯一权威。
**Tech Stack:** uni-app Vue 3、Pinia、Tailwind CSS、现有 `src/utils/request.js`、Node 20 `node:test`、pnpm；不增加依赖。
**Spec:** `docs/superpowers/specs/2026-09-20-pda-business-workflow-design.md`
## Global Constraints
- 不打包、签名、安装或发布 APK；只运行 PDA 的 H5/开发构建。
- 不调用摄像头扫码，不新增原生扫码 SDK；扫码输入必须兼容 HID 键盘逐字符输入后回车提交，并保留手工输入。
- 不修改现有 FastAPI 业务接口的请求/响应契约，不在 PDA 前端计算最终库存或托盘状态。
- 基础资料维护和六类报表继续使用 Web 后台，不复制到 PDA。
- 不把管理员密码、Token、Cookie 或其他凭据写入源码、测试固定文本或日志；登录表单不得预填密码。
- 不修改 `.env.dev`、`.env.prod`、前端环境文件、用户已有 APP 改动、后端日志和无关缓存。
- 不安装、升级或删除依赖；使用仓库已有 `node_modules`、Node 20 和 pnpm 配置。
- 所有业务写请求必须使用后端要求的 camelCase 字段和幂等键；网络失败后直接重试复用原键，改变业务输入后才生成新键。
- 页面入口只按当前用户权限显示；页面内按钮权限与后端 401/403 校验同时保留，前端隐藏不能替代后端权限。
- 每个提交只包含本任务明确列出的文件；暂存和提交使用显式路径，禁止 `git add -A`、`git clean`、重置或覆盖用户已有改动。
- 每个任务完成后使用中文提交说明，并用 `git commit --only` 保护工作区中既有暂存内容。
---
## 文件结构与责任边界
### 新建文件
- `shierfeng-fastapi-app/src/api/business/inbound.js`：首次入库列表、选项、扫码、详情、草稿增改删和确认请求。
- `shierfeng-fastapi-app/src/api/business/filling.js`：装填列表、菌种选项、扫码、详情和装填提交请求。
- `shierfeng-fastapi-app/src/api/business/shipment.js`：发货列表、仓库/现场选项、扫码、详情、草稿增改删和确认请求。
- `shierfeng-fastapi-app/src/api/business/usage.js`：使用列表、产线选项、扫码、详情和使用提交请求。
- `shierfeng-fastapi-app/src/api/business/return.js`：退回列表、仓库选项、扫码、申请、详情和确认请求。
- `shierfeng-fastapi-app/src/utils/palletScan.js`：扫码值规范化、短时重复判断和 Web Crypto UUID v4 幂等键生成；不保存业务状态。
- `shierfeng-fastapi-app/src/components/business/PalletScanInput.vue`：HID/手工输入、回车提交、空值校验、短时重复提示和输入焦点管理。
- `shierfeng-fastapi-app/src/pages/business/inbound/index.vue`：入库草稿编辑、扫码、删除和确认。
- `shierfeng-fastapi-app/src/pages/business/filling/index.vue`：单托盘装填。
- `shierfeng-fastapi-app/src/pages/business/shipment/index.vue`：发货草稿编辑、扫码、删除和确认。
- `shierfeng-fastapi-app/src/pages/business/usage/index.vue`：现场使用、产线选择和服务端结果展示。
- `shierfeng-fastapi-app/src/pages/business/return/index.vue`：退回申请和仓库确认两个独立操作区。
- `shierfeng-fastapi-app/tests/business-contract.test.mjs`：Node 20 静态 API/页面/字段/安全契约与扫码工具测试。
### 修改文件
- `shierfeng-fastapi-app/package.json`：增加不依赖新包的 `test:business` 脚本。
- `shierfeng-fastapi-app/src/pages.json`：注册五个业务页面路由。
- `shierfeng-fastapi-app/src/pages/login.vue`：移除旧默认密码预填值，保留现有认证流程。
- `shierfeng-fastapi-app/src/pages/work/index.vue`：增加按权限过滤的五类 PDA 业务入口。
### 明确不修改
- `shierfeng-fastapi-backend/module_business/**`：后端接口已存在，本计划只消费其当前契约。
- `shierfeng-fastapi-frontend/**`：Web 端作为接口和交互参考，不复制改动。
- `shierfeng-fastapi-app/src/utils/request.js`、传输加密、Pinia 用户会话和环境配置：除非测试证明共享层存在直接阻塞，否则保持现状。
## 已核实的后端接口与字段
| 模块 | 查询/选项/扫码 | 写请求 | 必须保持的写入字段 |
| --- | --- | --- | --- |
| 入库 | `GET /business/inbound/list`、`/warehouse-options`、`/scan/{qrToken}?warehouseId=`、`/{inboundId}` | `POST /business/inbound`、`PUT /business/inbound`、`DELETE /business/inbound/{ids}`、`PUT /business/inbound/{id}/confirm` | 草稿：`warehouseId,palletIds`；确认：`idempotencyKey` |
| 装填 | `GET /business/filling/list`、`/strain-options`、`/scan/{qrToken}`、`/{fillingId}` | `POST /business/filling` | `qrToken,warehouseId,strainId,batchNo,packageSpec,initialPackages,idempotencyKey` |
| 发货 | `GET /business/shipment/list`、`/warehouse-options`、`/site-options`、`/scan/{qrToken}?sourceWarehouseId=&targetSiteId=`、`/{shipmentId}` | `POST /business/shipment`、`PUT /business/shipment`、`DELETE /business/shipment/{ids}`、`PUT /business/shipment/{id}/confirm` | 草稿：`sourceWarehouseId,targetSiteId,palletIds`；确认：`idempotencyKey` |
| 使用 | `GET /business/usage/list`、`/line-options?siteId=`、`/scan/{qrToken}`、`/{usageId}` | `POST /business/usage` | `qrToken,lineId,usedPackages,idempotencyKey` |
| 退回 | `GET /business/return/list`、`/warehouse-options`、`/scan/{qrToken}?mode=&returnId=`、`/{returnId}` | `POST /business/return/request`、`PUT /business/return/{id}/confirm` | 申请：`sourceSiteId,targetWarehouseId,palletIds,idempotencyKey`；确认：`scannedPalletIds,idempotencyKey` |
后端扫码响应统一使用 `data.palletId/palletCode/flowState/warehouseId/siteId/currentLineId/strainId/strainCode/strainName/batchNo/packageSpec/capacityPackages/remainingPackages/allowedActions`；列表响应使用 `rows` 和 `total`；详情使用 `data`。装填和使用写请求没有单独确认接口，成功后以列表、扫码结果或使用响应为准。
## Task 1: 用测试锁定 API 封装、扫码工具和幂等键
**Files:**
- Create: `shierfeng-fastapi-app/tests/business-contract.test.mjs`
- Create: `shierfeng-fastapi-app/src/api/business/inbound.js`
- Create: `shierfeng-fastapi-app/src/api/business/filling.js`
- Create: `shierfeng-fastapi-app/src/api/business/shipment.js`
- Create: `shierfeng-fastapi-app/src/api/business/usage.js`
- Create: `shierfeng-fastapi-app/src/api/business/return.js`
- Create: `shierfeng-fastapi-app/src/utils/palletScan.js`
- Modify: `shierfeng-fastapi-app/package.json`
**Interfaces:**
- Produces API exports `listInbound`, `getInboundWarehouseOptions`, `scanInboundPallet`, `getInbound`, `addInbound`, `updateInbound`, `delInbound`, `confirmInbound`；其他四个模块使用已核实接口表中的同义导出名。
- Produces `normalizeScanValue(value)`, `isDuplicateScan(value,lastValue,scannedAt,lastScannedAt,duplicateWindowMs)` 和 `createIdempotencyKey(cryptoProvider)`。
- All API wrappers import `request` from `@/utils/request` and return its promise without改写响应结构。
各模块的完整导出名固定如下，页面不得自行拼接 URL：
- `inbound.js`：`listInbound(query)`、`getInboundWarehouseOptions()`、`scanInboundPallet(qrToken,query)`、`getInbound(inboundId)`、`addInbound(data)`、`updateInbound(data)`、`delInbound(inboundIds)`、`confirmInbound(inboundId,data)`。
- `filling.js`：`listFilling(query)`、`getFillingStrainOptions()`、`scanFillingPallet(qrToken)`、`getFilling(fillingId)`、`addFilling(data)`。
- `shipment.js`：`listShipment(query)`、`getShipmentWarehouseOptions()`、`getShipmentSiteOptions()`、`scanShipmentPallet(qrToken,query)`、`getShipment(shipmentId)`、`addShipment(data)`、`updateShipment(data)`、`delShipment(shipmentIds)`、`confirmShipment(shipmentId,data)`。
- `usage.js`：`listUsage(query)`、`getUsageLineOptions(siteId)`、`scanUsagePallet(qrToken)`、`getUsage(usageId)`、`addUsage(data)`。
- `return.js`：`listReturn(query)`、`getReturnWarehouseOptions()`、`scanReturnPallet(qrToken,query)`、`requestReturn(data)`、`getReturn(returnId)`、`confirmReturn(returnId,data)`。
- [ ] **Step 1: 先写 API 与工具的失败测试**
在测试文件中用 `readFile` 读取五个 API 文件，用正则逐个断言 URL、HTTP 方法和关键参数名称；同时为工具写可执行单元测试：
```js
test('扫码值只去除首尾空白并拒绝空值', async () => {
const { normalizeScanValue } = await import('../src/utils/palletScan.js')
assert.equal(normalizeScanValue(' QR-001\n'), 'QR-001')
assert.throws(() => normalizeScanValue(' \n\t '), /二维码不能为空/)
})
test('幂等键使用 randomUUID 或安全随机字节，不使用时间和伪随机数', async () => {
const { createIdempotencyKey } = await import('../src/utils/palletScan.js')
const expected = '12345678-1234-4123-8123-123456789abc'
assert.equal(createIdempotencyKey({ randomUUID: () => expected }), expected)
assert.equal(
createIdempotencyKey({
getRandomValues(bytes) {
bytes.fill(0)
return bytes
}
}),
'00000000-0000-4000-8000-000000000000'
)
})
test('同一值只在重复时间窗口内被识别', async () => {
const { isDuplicateScan } = await import('../src/utils/palletScan.js')
assert.equal(isDuplicateScan('QR-001', 'QR-001', 1200, 1000, 500), true)
assert.equal(isDuplicateScan('QR-001', 'QR-002', 1200, 1000, 500), false)
assert.equal(isDuplicateScan('QR-001', 'QR-001', 1801, 1000, 500), false)
})
```
API 契约测试至少覆盖以下请求：入库和发货的列表、选项、扫码、详情、草稿增改删、确认；装填和使用的列表、选项、扫码、详情、提交；退回的列表、选项、扫码、申请、详情、确认。测试还要断言确认/写请求的函数名和 `data`/`params` 位置，防止把 query 字段误放入 body。
- [ ] **Step 2: 运行失败测试确认缺口**
工作目录：`shierfeng-fastapi-app`
```bash
node --test tests/business-contract.test.mjs
```
预期：因五个 API 模块、扫码工具和测试脚本尚未存在而失败；此时不修改后端或依赖。
- [ ] **Step 3: 实现最小 API 封装和测试脚本**
`package.json` 只增加以下脚本，不增加依赖：
```json
"test:business": "node --test tests/business-contract.test.mjs"
```
每个 API 文件只做路径和参数映射。例如入库模块必须保持如下接口形状：
```js
import request from '@/utils/request'
export function listInbound(query) {
return request({ url: '/business/inbound/list', method: 'get', params: query })
}
export function scanInboundPallet(qrToken, query) {
return request({ url: '/business/inbound/scan/' + qrToken, method: 'get', params: query })
}
export function addInbound(data) {
return request({ url: '/business/inbound', method: 'post', data })
}
export function confirmInbound(inboundId, data) {
return request({
url: '/business/inbound/' + inboundId + '/confirm',
method: 'put',
data,
headers: { repeatSubmit: false }
})
}
```
其他函数按接口表逐一实现，不增加前端字段别名。`createIdempotencyKey` 优先使用 `crypto.randomUUID()`，否则用 `crypto.getRandomValues(new Uint8Array(16))` 按 UUID v4 设置版本和变体位；缺少安全随机源时抛出明确错误，不使用 `Date.now()`、`Math.random()` 或账号信息。
- [ ] **Step 4: 运行测试确认 API 与工具契约通过**
```bash
pnpm test:business
```
预期：本任务新增的 API 路径、HTTP 方法、参数位置、扫码规范化、重复窗口和 UUID 测试通过；页面相关测试在后续任务加入。
- [ ] **Step 5: 只提交本任务文件**
```bash
git add -- \
shierfeng-fastapi-app/package.json \
shierfeng-fastapi-app/tests/business-contract.test.mjs \
shierfeng-fastapi-app/src/api/business/inbound.js \
shierfeng-fastapi-app/src/api/business/filling.js \
shierfeng-fastapi-app/src/api/business/shipment.js \
shierfeng-fastapi-app/src/api/business/usage.js \
shierfeng-fastapi-app/src/api/business/return.js \
shierfeng-fastapi-app/src/utils/palletScan.js
git commit --only -m '新增：PDA 业务 API 与扫码幂等工具' -- \
shierfeng-fastapi-app/package.json \
shierfeng-fastapi-app/tests/business-contract.test.mjs \
shierfeng-fastapi-app/src/api/business/inbound.js \
shierfeng-fastapi-app/src/api/business/filling.js \
shierfeng-fastapi-app/src/api/business/shipment.js \
shierfeng-fastapi-app/src/api/business/usage.js \
shierfeng-fastapi-app/src/api/business/return.js \
shierfeng-fastapi-app/src/utils/palletScan.js
```
## Task 2: 先测试再实现 HID 扫码输入组件
**Files:**
- Create: `shierfeng-fastapi-app/src/components/business/PalletScanInput.vue`
- Modify: `shierfeng-fastapi-app/tests/business-contract.test.mjs`
**Interfaces:**
- Consumes `normalizeScanValue` and `isDuplicateScan` from `@/utils/palletScan`.
- Props: `disabled:Boolean=false`、`loading:Boolean=false`、`duplicateWindowMs:Number=500`。
- Emits: `scan(normalizedValue)`、`invalid(message)`、`duplicate(normalizedValue)`。
- Exposes no business state; parent controls request lock through `loading` and owns accepted pallet rows.
- [ ] **Step 1: 写组件静态契约测试并确认 RED**
在 `business-contract.test.mjs` 读取组件源码，断言存在 `@confirm="handleSubmit"`、`normalizeScanValue`、`isDuplicateScan`、三个 emit 名称、`:disabled="disabled || loading"` 或等价锁定逻辑，并断言没有 `uni.scanCode`、摄像头 API 或状态机字段判断。执行 `pnpm test:business`，预期组件测试失败。
- [ ] **Step 2: 实现组件输入状态机**
组件使用 uni-app 原生 `<input>`，同时绑定 `@confirm`（HID 回车和手工确认）与一个可点击的“提交扫描”按钮；输入框在 `disabled` 或 `loading` 时只读/禁用。提交逻辑必须保持以下顺序：
```js
function handleSubmit() {
if (props.disabled || props.loading) return
let value
try {
value = normalizeScanValue(scanValue.value)
} catch (error) {
errorMessage.value = error.message
emit('invalid', error.message)
focusInput(true)
return
}
const scannedAt = Date.now()
if (isDuplicateScan(value, lastScanValue, scannedAt, lastScanAt, props.duplicateWindowMs)) {
scanValue.value = ''
emit('duplicate', value)
focusInput()
return
}
lastScanValue = value
lastScanAt = scannedAt
scanValue.value = ''
emit('scan', value)
focusInput()
}
```
`Date.now()`只用于比较短时重复输入，不得用于生成业务幂等键。组件自动聚焦、扫描完成后清空输入并重新聚焦；页面切换、请求进行中和权限不足时由父页面传入 `disabled/loading`。
- [ ] **Step 3: 运行组件契约和工具测试确认 GREEN**
```bash
pnpm test:business
```
预期：组件的 HID 回车、手工提交、空值、重复值和请求锁静态契约通过。
- [ ] **Step 4: 提交组件**
```bash
git add -- shierfeng-fastapi-app/src/components/business/PalletScanInput.vue shierfeng-fastapi-app/tests/business-contract.test.mjs
git commit --only -m '新增：PDA HID 扫码输入组件' -- \
shierfeng-fastapi-app/src/components/business/PalletScanInput.vue \
shierfeng-fastapi-app/tests/business-contract.test.mjs
```
## Task 3: 注册路由、移除密码预填并增加权限入口
**Files:**
- Modify: `shierfeng-fastapi-app/src/pages.json`
- Modify: `shierfeng-fastapi-app/src/pages/login.vue`
- Modify: `shierfeng-fastapi-app/src/pages/work/index.vue`
- Modify: `shierfeng-fastapi-app/tests/business-contract.test.mjs`
**Interfaces:**
- Produces routes `pages/business/inbound/index`、`pages/business/filling/index`、`pages/business/shipment/index`、`pages/business/usage/index`、`pages/business/return/index`。
- Uses existing `$auth.hasPermiOr`/`$auth.hasPermiAnd` and `$tab.navigateTo`; does not change Pinia or permission storage.
- [ ] **Step 1: 写路由、权限和凭据安全测试并确认 RED**
测试必须断言五个页面路径和标题存在，工作台包含五类业务权限字符串，且 `src/pages/login.vue` 不再包含旧默认密码或其他密码字面量。测试也要断言入口跳转路径与页面路径一致。
- [ ] **Step 2: 注册五个页面并实现入口过滤**
在 `pages.json` 按工作台之后加入五个页面，使用中文标题“仓库入库”“托盘装填”“发货出库”“现场使用”“退回仓库”。工作台增加“现场业务”区块，入口权限使用以下 OR 集合：
```js
const businessEntries = [
{ path: '/pages/business/inbound/index', permissions: ['business:inbound:list', 'business:inbound:query', 'business:inbound:add', 'business:inbound:edit', 'business:inbound:remove', 'business:inbound:confirm'] },
{ path: '/pages/business/filling/index', permissions: ['business:filling:list', 'business:filling:query', 'business:filling:add'] },
{ path: '/pages/business/shipment/index', permissions: ['business:shipment:list', 'business:shipment:query', 'business:shipment:add', 'business:shipment:edit', 'business:shipment:remove', 'business:shipment:confirm'] },
{ path: '/pages/business/usage/index', permissions: ['business:usage:list', 'business:usage:query', 'business:usage:add'] },
{ path: '/pages/business/return/index', permissions: ['business:return:list', 'business:return:query', 'business:return:request', 'business:return:confirm'] }
]
```
模板只渲染 `proxy.$auth.hasPermiOr(entry.permissions)` 为真的入口；点击前再次检查权限并调用 `$tab.navigateTo(entry.path)`。页面没有任何授权时不显示业务区块。保留现有非本任务系统入口，不扩展其他模块。
- [ ] **Step 3: 清除登录页密码默认值**
将 `loginForm` 的 `username` 和 `password` 初始值改为空字符串，验证码和登录 API 流程保持不变；开发联调账号只在人工输入时使用，不写入源码、测试或日志。
- [ ] **Step 4: 运行测试确认 GREEN**
```bash
pnpm test:business
```
预期：五个路由、权限入口、登录安全静态契约通过。
- [ ] **Step 5: 提交页面壳层改动**
```bash
git add -- \
shierfeng-fastapi-app/src/pages.json \
shierfeng-fastapi-app/src/pages/login.vue \
shierfeng-fastapi-app/src/pages/work/index.vue \
shierfeng-fastapi-app/tests/business-contract.test.mjs
git commit --only -m '新增：PDA 业务页面路由与权限入口' -- \
shierfeng-fastapi-app/src/pages.json \
shierfeng-fastapi-app/src/pages/login.vue \
shierfeng-fastapi-app/src/pages/work/index.vue \
shierfeng-fastapi-app/tests/business-contract.test.mjs
```
## Task 4: 实现首次入库 PDA 页面
**Files:**
- Create: `shierfeng-fastapi-app/src/pages/business/inbound/index.vue`
- Modify: `shierfeng-fastapi-app/tests/business-contract.test.mjs`
**Interfaces:**
- Consumes all exports from `src/api/business/inbound.js`, `PalletScanInput`, `createIdempotencyKey` and `$auth`.
- Produces page methods `handleInboundScan`, `submitInboundDraft`, `saveInboundUpdate`, `confirmInboundDraft`, `removeScannedPallet`, `resetInboundOperation`。
- Page state stores only scanned display rows, draft form values, request/loading/error state and confirm idempotency key; it never stores a client-calculated inventory state。
- [ ] **Step 1: 写入库页面契约测试并确认 RED**
测试读取页面源码并断言：
1. 使用 `PalletScanInput`，扫描调用 `scanInboundPallet(qrToken, { warehouseId })`。
2. 只接受 `flowState === 'UNSTOCKED'`，按 `palletId` 去重。
3. 草稿 payload 只含 `{ warehouseId, palletIds }`，编辑 payload 只含 `{ inboundId, warehouseId, palletIds }`。
4. 确认调用 `confirmInbound(inboundId, { idempotencyKey })`，失败分支不清空当前键。
5. 编辑/删除/确认按钮分别包含 `business:inbound:edit/remove/confirm`，入口操作需要同时具备 `query` 与对应写权限。
- [ ] **Step 2: 实现仓库选项、草稿扫码和编辑状态**
页面加载授权仓库选项和第一页列表；新增时选择仓库后允许连续扫描。每次扫码携带当前仓库 ID，接受服务端返回的 `palletId/palletCode/flowState`，重复托盘只提示不追加。切换仓库清空当前扫描集合并使旧扫码响应失效。
编辑时先调用 `getInbound(inboundId)`，只有详情仍为 `DRAFT` 才填充仓库和明细；详情未返回前禁止扫码、保存和删除。列表刷新/页面 `onShow` 以服务端 `rows` 为准，不从本地草稿推导状态。
- [ ] **Step 3: 实现草稿写入和确认重试**
```js
function submitInboundDraft() {
return addInbound({
warehouseId: form.value.warehouseId,
palletIds: scannedPallets.value.map((item) => item.palletId)
})
}
function confirmInboundDraft(row) {
const idempotencyKey = ensureConfirmIdempotencyKey(row.inboundId)
confirmLoading.value = true
confirmInbound(row.inboundId, { idempotencyKey })
.then(() => {
clearConfirmIdempotency()
loadInboundList()
})
.catch(() => {
confirmError.value = '入库确认失败；再次确认将复用本次幂等键'
})
.finally(() => {
confirmLoading.value = false
})
}
```
后端新增草稿响应不保证返回单据 ID，因此保存后只关闭编辑区并重新读取列表，由用户从服务端返回的 `DRAFT` 行选择确认，不按时间或本地数组猜测刚创建的单据。确认成功后清除键；网络超时、401 以外的可重试失败保留键，401 交由现有 `request` 会话处理。
- [ ] **Step 4: 运行入库契约和构建前静态检查**
```bash
pnpm test:business
```
预期：入库页面的字段、状态、权限、幂等键和服务端刷新契约通过。
- [ ] **Step 5: 提交入库页面**
```bash
git add -- shierfeng-fastapi-app/src/pages/business/inbound/index.vue shierfeng-fastapi-app/tests/business-contract.test.mjs
git commit --only -m '新增：PDA 首次入库操作页' -- \
shierfeng-fastapi-app/src/pages/business/inbound/index.vue \
shierfeng-fastapi-app/tests/business-contract.test.mjs
```
## Task 5: 实现整托发货 PDA 页面
**Files:**
- Create: `shierfeng-fastapi-app/src/pages/business/shipment/index.vue`
- Modify: `shierfeng-fastapi-app/tests/business-contract.test.mjs`
**Interfaces:**
- Consumes `src/api/business/shipment.js`、`PalletScanInput` 和 `createIdempotencyKey`。
- Produces `handleShipmentScan`, `submitShipmentDraft`, `saveShipmentUpdate`, `confirmShipmentDraft`, `removeScannedPallet`。
- Scanned rows expose `palletCode`, `strainName/strainCode`, `batchNo`, `remainingPackages` as read-only display values。
- [ ] **Step 1: 写发货页面失败契约**
断言页面加载仓库和现场选项，扫描调用 `scanShipmentPallet(qrToken, { sourceWarehouseId, targetSiteId })`，只接受 `flowState === 'FILLED_IN_WAREHOUSE' && remainingPackages > 0`，草稿/确认字段与接口表一致，并保留确认失败时的幂等键。
- [ ] **Step 2: 实现来源仓库、目标现场和集合扫码**
来源仓库或目标现场改变时清空托盘集合并使旧请求失效。扫描期间锁定输入和提交按钮；同一 `palletId` 不重复追加。列表、详情和选项失败显示页面内可重试错误，不吞掉后端业务消息。
- [ ] **Step 3: 实现草稿和确认**
```js
function submitShipmentDraft() {
return addShipment({
sourceWarehouseId: form.value.sourceWarehouseId,
targetSiteId: form.value.targetSiteId,
palletIds: scannedPallets.value.map((item) => item.palletId)
})
}
function confirmShipmentDraft(row) {
const idempotencyKey = ensureConfirmIdempotencyKey(row.shipmentId)
return confirmShipment(row.shipmentId, { idempotencyKey })
}
```
保存后重新读取列表；确认前要求 `DRAFT`，成功后重新加载列表和页面状态。错误重试只复用同一确认键，改变单据或托盘集合时清除并重新生成键；不在前端扣减 `remainingPackages`。
- [ ] **Step 4: 运行测试并提交**
```bash
pnpm test:business
git add -- shierfeng-fastapi-app/src/pages/business/shipment/index.vue shierfeng-fastapi-app/tests/business-contract.test.mjs
git commit --only -m '新增：PDA 整托发货操作页' -- \
shierfeng-fastapi-app/src/pages/business/shipment/index.vue \
shierfeng-fastapi-app/tests/business-contract.test.mjs
```
预期：测试通过后才执行提交；提交只包含发货页面和契约测试增量。
## Task 6: 实现单托盘装填 PDA 页面
**Files:**
- Create: `shierfeng-fastapi-app/src/pages/business/filling/index.vue`
- Modify: `shierfeng-fastapi-app/tests/business-contract.test.mjs`
**Interfaces:**
- Consumes `listFilling`、`getFillingStrainOptions`、`scanFillingPallet`、`addFilling` 和 `PalletScanInput`。
- Produces form fields `qrToken`, `warehouseId`, `strainId`, `batchNo`, `packageSpec`, `initialPackages` and one operation-scoped `idempotencyKey`。
- [ ] **Step 1: 写装填页面失败契约**
断言页面只接受 `flowState === 'EMPTY_IN_WAREHOUSE'`，扫码成功后展示仓库和容量，提交 payload 包含且只包含后端 `FillingCreateModel` 字段，包数校验为严格正整数，成功/失败状态不伪造库存。
- [ ] **Step 2: 实现扫码和表单**
扫码后保存服务端返回的 `qrToken`、`warehouseId`、`palletCode`、`capacityPackages`，加载菌种选项。菌种、批次、规格和包数在请求期间锁定；包数的前端校验只做正整数和非空检查，容量和托盘状态由后端最终判定。
- [ ] **Step 3: 实现幂等提交和成功刷新**
```js
function submitFilling() {
const idempotencyKey = ensureFillingIdempotencyKey()
return addFilling({
qrToken: form.value.qrToken,
warehouseId: form.value.warehouseId,
strainId: form.value.strainId,
batchNo: form.value.batchNo.trim(),
packageSpec: form.value.packageSpec.trim(),
initialPackages: form.value.initialPackages,
idempotencyKey
})
}
```
提交成功后清空表单并刷新装填列表，再以扫码查询或列表结果显示服务端状态；刷新失败不能覆盖已经成功的写入提示。提交失败保留键；修改托盘、菌种、批次、规格或包数后清除键，下一次输入生成新键。
- [ ] **Step 4: 运行测试并提交**
```bash
pnpm test:business
git add -- shierfeng-fastapi-app/src/pages/business/filling/index.vue shierfeng-fastapi-app/tests/business-contract.test.mjs
git commit --only -m '新增：PDA 托盘装填操作页' -- \
shierfeng-fastapi-app/src/pages/business/filling/index.vue \
shierfeng-fastapi-app/tests/business-contract.test.mjs
```
## Task 7: 实现客户现场使用 PDA 页面
**Files:**
- Create: `shierfeng-fastapi-app/src/pages/business/usage/index.vue`
- Modify: `shierfeng-fastapi-app/tests/business-contract.test.mjs`
**Interfaces:**
- Consumes `listUsage`、`getUsageLineOptions(siteId)`、`scanUsagePallet`、`addUsage` 和 `PalletScanInput`。
- Produces `handleUsageScan`, `loadLineOptions`, `submitUsage`, `resetUsageOperation`。
- Uses `UsageSuccessResponseModel` fields `usageId`, `remainingPackages`, `flowState` for result display only。
- [ ] **Step 1: 写现场使用失败契约**
断言页面只接受 `AT_SITE_UNUSED` 或 `AT_SITE_PARTIAL` 且 `remainingPackages > 0`；没有 `currentLineId` 时按扫码响应的 `siteId` 获取产线，有绑定时锁定该产线；提交使用 `qrToken,lineId,usedPackages,idempotencyKey`，不在本地推算新状态。
- [ ] **Step 2: 实现扫码、产线锁定和正整数校验**
每次新扫码先使旧产线请求失效、清空旧结果和幂等键。扫码成功后保存托盘、菌种、批次、余量和现场信息；首次使用显示可选产线，已有 `currentLineId` 时只能使用该产线。使用包数必须是严格正整数，超过当前展示余量时给出提示，但即使通过前端检查也仍由服务端校验。
- [ ] **Step 3: 实现使用提交和结果刷新**
```js
function submitUsage() {
const idempotencyKey = ensureUsageIdempotencyKey()
return addUsage({
qrToken: form.value.qrToken,
lineId: form.value.lineId,
usedPackages: form.value.usedPackages,
idempotencyKey
}).then((response) => {
usageResult.value = response.data
clearUsageIdempotencyKey()
return loadUsageList()
})
}
```
网络失败时保留键并显示“再次提交将复用本次幂等键”；成功只采用 `response.data.remainingPackages` 和 `response.data.flowState`，然后清理表单或允许重新扫码。列表和扫码响应晚于新会话时必须被请求代数丢弃。
- [ ] **Step 4: 运行测试并提交**
```bash
pnpm test:business
git add -- shierfeng-fastapi-app/src/pages/business/usage/index.vue shierfeng-fastapi-app/tests/business-contract.test.mjs
git commit --only -m '新增：PDA 客户现场使用操作页' -- \
shierfeng-fastapi-app/src/pages/business/usage/index.vue \
shierfeng-fastapi-app/tests/business-contract.test.mjs
```
## Task 8: 实现托盘退回申请与仓库确认
**Files:**
- Create: `shierfeng-fastapi-app/src/pages/business/return/index.vue`
- Modify: `shierfeng-fastapi-app/tests/business-contract.test.mjs`
**Interfaces:**
- Consumes all exports from `src/api/business/return.js` and two independent `PalletScanInput` instances。
- Request side state: `sourceSiteId`, `targetWarehouseId`, `requestScannedPallets`, `requestIdempotencyKey`。
- Confirm side state: `returnId`, `expectedPalletIds`, `confirmScannedPallets`, `confirmIdempotencyKey`。
- Produces `handleRequestScan`, `submitReturnRequest`, `loadReturnDetail`, `handleConfirmScan`, `submitReturnConfirm`, `sameIdSet`。
- [ ] **Step 1: 写退回两阶段失败契约**
断言测试覆盖：
1. 申请扫码使用 `{ mode: 'request' }`，首个托盘确定 `sourceSiteId`，后续托盘必须属于同一现场。
2. 申请 payload 为 `sourceSiteId,targetWarehouseId,palletIds,idempotencyKey`，申请键和确认键互不复用。
3. 确认先读取详情，状态必须为 `REQUESTED`，扫描使用 `{ mode: 'confirm', returnId }`，扫码集合必须与详情托盘 ID 集合完全相同。
4. 确认写请求前再次 `getReturn(returnId)`，比较最新状态和 ID 集合后才调用 `confirmReturn`。
5. 请求或确认扫码/提交的旧响应不能覆盖新选择；失败不清除对应幂等键。
- [ ] **Step 2: 实现申请区**
加载可访问目标仓库和退回列表。申请扫码成功后保存 `palletId,palletCode,siteId,remainingPackages`，同一托盘不重复，目标仓库或会话变化时清空集合和申请键。`requestReturn` 成功后清除申请键、清空申请区并刷新列表；不根据响应消息猜测新 `returnId`，确认入口从服务端返回的 `REQUESTED` 列表选择单据。
- [ ] **Step 3: 实现确认区的详情快照与整集合扫码**
选择退回单后调用 `getReturn`，保存详情中的 `items[].palletId` 作为预期集合。确认扫码必须命中预期集合且不能重复；切换退回单使确认扫码代数、详情代数和确认键同时失效。实现集合比较时使用去重后的 `Set`，长度和成员都必须一致：
```js
function sameIdSet(left, right) {
if (left.length !== right.length) return false
const leftSet = new Set(left)
const rightSet = new Set(right)
return leftSet.size === left.length &&
rightSet.size === right.length &&
right.every((id) => leftSet.has(id))
}
```
- [ ] **Step 4: 实现确认前复核和幂等提交**
```js
async function submitReturnConfirm() {
const returnId = confirmForm.value.returnId
const scannedPalletIds = confirmScannedPallets.value.map((item) => item.palletId)
if (!returnId || !sameIdSet(expectedPalletIds.value, scannedPalletIds)) {
confirmError.value = '必须逐个扫描并完整匹配退回单全部托盘'
return
}
const latest = (await getReturn(returnId)).data
if (latest.status !== 'REQUESTED' ||
!sameIdSet(latest.items.map((item) => item.palletId), scannedPalletIds)) {
confirmError.value = '退回单状态或托盘明细已变化，请重新选择并扫码'
return
}
const idempotencyKey = ensureConfirmIdempotencyKey(returnId)
await confirmReturn(returnId, { scannedPalletIds, idempotencyKey })
}
```
确认成功后清除确认键、刷新退回列表和详情；网络失败保留键。申请确认两个阶段的输入锁、错误状态和重试键必须分开，不能用一个全局 `loading` 或一个幂等键混用。
- [ ] **Step 5: 运行测试并提交**
```bash
pnpm test:business
git add -- shierfeng-fastapi-app/src/pages/business/return/index.vue shierfeng-fastapi-app/tests/business-contract.test.mjs
git commit --only -m '新增：PDA 托盘退回两阶段操作页' -- \
shierfeng-fastapi-app/src/pages/business/return/index.vue \
shierfeng-fastapi-app/tests/business-contract.test.mjs
```
## Task 9: 完成全量契约验证、H5 构建和交付检查
**Files:**
- Modify: `shierfeng-fastapi-app/tests/business-contract.test.mjs`（仅在发现测试覆盖缺口时补充）
- Preserve: 所有后端、Web、环境、日志、缓存和用户已有 APP 文件
**Interfaces:**
- Consumes all five PDA pages, five API modules, shared scanner and existing backend contract。
- Produces a verified H5/development build；does not produce an APK。
- [ ] **Step 1: 完成静态契约覆盖清单**
测试必须逐项覆盖：
- 五个 API 文件的路径、方法、参数位置和导出函数。
- 五个页面的路由存在、页面调用对应 API、camelCase payload 字段正确。
- 五类状态条件：`UNSTOCKED`、`EMPTY_IN_WAREHOUSE`、`FILLED_IN_WAREHOUSE`、`AT_SITE_UNUSED/AT_SITE_PARTIAL`、退回 `REQUESTED`。
- HID 回车、空值、重复扫码、扫描请求锁和手工输入。
- 入库/发货确认、装填、使用、退回申请/确认的幂等键生成、保留和成功清理时机。
- 页面权限标识和登录页无密码预填。
- 不存在摄像头扫码调用、APK 构建脚本调用、管理员密码或 Token 字面量。
- [ ] **Step 2: 运行 PDA 契约测试**
工作目录：`shierfeng-fastapi-app`
```bash
pnpm test:business
```
预期：所有 Node 20 测试通过且零失败。
- [ ] **Step 3: 运行 H5 构建，不运行 APK 构建**
```bash
pnpm run build:h5
```
预期：uni-app H5 构建成功。禁止运行 `pnpm run build:app`、`pnpm run dev:app`、APK 签名、安装或发布命令；构建产物不加入提交。
- [ ] **Step 4: 运行已有后端业务回归**
工作目录：`shierfeng-fastapi-backend`，使用当前已配置 Python 环境，不安装依赖：
```bash
PYTHONDONTWRITEBYTECODE=1 python -m pytest tests/module_business -q
ruff format --check module_business tests/module_business
ruff check module_business tests/module_business
```
预期：已有后端业务测试、格式检查和静态检查通过；若本地 Python 环境无法执行，记录实际错误，不伪造通过结果。
- [ ] **Step 5: 做最终 diff 与敏感信息检查**
仓库根目录执行：
```bash
git diff --check HEAD~9..HEAD
rg -n --fixed-strings '旧默认密码' shierfeng-fastapi-app/src shierfeng-fastapi-app/tests
rg -n 'Bearer[[:space:]]+[A-Za-z0-9._-]+' shierfeng-fastapi-app/src shierfeng-fastapi-app/tests
git status --short
```
敏感信息检查应无命中；`git status` 中只允许出现本计划任务的 PDA 文件和用户原有改动，不能出现由构建生成且准备提交的 APK、环境文件、日志或缓存。若提交数量因任务合并而不同，将 `HEAD~9..HEAD` 改为本次 PDA 首个提交到当前 `HEAD` 的实际范围，不扩大检查目标。
- [ ] **Step 6: 按人工验收清单交付**
在受控本地环境手工验证：管理员和受限普通用户登录；未授权入口不显示且直接接口返回 403；HID 扫码回车、重复扫码、空值和网络重试；库存余量、托盘状态、产线绑定、退回冻结与事件追溯均来自服务端；页面刷新和断网重试不重复扣减库存。管理员密码只在人工输入，不记录到终端输出、源码或日志。
## 计划自检
- 设计文档的范围、五类流程、认证安全、扫码输入、状态/幂等、验证、部署边界分别由 Tasks 1–9 覆盖。
- 所有跨任务接口在“已核实的后端接口与字段”和各任务的 `Interfaces` 中定义，页面调用名称与 API 导出名称保持一致。
- 没有新增依赖、后端契约改动、摄像头 SDK、APK 构建或凭据写入步骤。
- 实现前先写失败契约，随后运行最小测试，再执行 H5 和后端回归；每个任务都以显式路径提交。
docs/superpowers/plans/2026-09-22-test-data-batch-cleanup.md
-2180
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/plans/2026-09-27-mysql-compose-bootstrap.md
-77
View File
@@ -1,77 +0,0 @@
# MySQL Initialization and Docker Compose 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:** Keep the MySQL fresh-install script aligned with the current business model and provide a safe, persistent Compose deployment for the frontend, backend, MySQL, and Redis.
**Architecture:** The existing MySQL initializer remains the single bootstrap source for a new empty database and is mounted into MySQL's first-start initialization directory. Existing database volumes are never migrated automatically; operators continue to use the reviewed MySQL patches separately. Compose keeps MySQL and Redis on an internal network, persists their data in named volumes, and reads credentials from an ignored local `.env` file created from a checked-in example.
**Tech Stack:** MySQL 8.0, Redis 7, existing FastAPI and Vue/Nginx Dockerfiles, Docker Compose v2, Python `unittest` schema contracts.
**Spec:** User request; schema/seed contract in `shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py`; operational migration guidance in `docs/test-data-batch-operations.md` and `docs/pallet-workflow-deployment.md`.
## Global Constraints
- MySQL remains the only database engine; do not add PostgreSQL configuration or SQL files.
- Do not execute SQL, apply patches, start containers, or remove/replace any database volume as part of this change.
- The full initializer contains `DROP TABLE`; mount it only as a first-start script for a fresh MySQL data directory.
- Keep existing seed records and schema unchanged when the current contract tests confirm they are synchronized.
- Do not place real credentials in Compose or the checked-in example environment file.
- Preserve unrelated staged, unstaged, and untracked work already in the repository.
---
### Task 1: Mark the MySQL initializer's safe-use boundary
**Files:**
- Modify: `shierfeng-fastapi-backend/sql/shierfeng-fastapi.sql`
- Test: `shierfeng-fastapi-backend/tests/module_business/test_sql_contract.py`
**Interfaces:**
- Consumes: current SQLAlchemy ORM table metadata and the existing MySQL SQL contract tests.
- Produces: the same schema and seed statements, with a clear warning that this destructive bootstrap is only for an empty/new database.
- [x] Add a Chinese header warning that the script drops/recreates tables and is for a fresh empty database only; direct existing-database users to reviewed files under `sql/patches/`.
- [x] Run the existing SQL contract suite and confirm all table, field, constraint, menu, and test-batch contracts still pass.
- [x] Review the diff to confirm no seed rows or DDL changed beyond the warning.
### Task 2: Add a persistent full-stack Docker Compose deployment
**Files:**
- Create: `docker-compose.yml`
- Create: `.env.docker.example`
- Modify: `.gitignore`
**Interfaces:**
- Consumes: `Dockerfile.my`, the frontend `Dockerfile`, `nginx.dockermy.conf`, `.env.dockermy`, and the MySQL initializer.
- Produces: Compose services `shierfeng-mysql`, `shierfeng-redis`, `shierfeng-backend-my`, and `shierfeng-frontend`; named volumes `mysql-data` and `redis-data`; required secrets supplied by root `.env`.
- [x] Define MySQL 8.0 with the fresh-install SQL mounted read-only at `/docker-entrypoint-initdb.d/01-schema-and-seed.sql`, an app-scoped database user, a health check, and a named data volume.
- [x] Define Redis 7 with append-only persistence, a health check, and a named data volume; do not publish Redis to the host.
- [x] Build the backend and frontend from the existing Dockerfiles. Configure backend DB/Redis service hosts and credentials through Compose environment overrides; make backend wait for healthy dependencies.
- [x] Route browser API requests through the existing Nginx config. Publish the frontend on configurable host port 8080 by default and MySQL only on loopback port 13307 by default.
- [x] Create `.env.docker.example` with placeholders for MySQL root password, app DB username/password, and JWT secret; add only root `/.env` to `.gitignore`.
- [x] Run `docker compose config --quiet` with test-only environment values and confirm configuration resolves without starting services.
### Task 3: Document first-run and existing-database workflows
**Files:**
- Modify: `README.md`
**Interfaces:**
- Consumes: root Compose file and `.env.docker.example`.
- Produces: concise setup commands and explicit distinction between fresh database initialization and existing-database patches.
- [x] Replace the root deployment instructions that point to the test-only Compose file with instructions to copy `.env.docker.example` to `.env`, set strong local credentials, validate with `docker compose config`, and start with `docker compose up -d --build`.
- [x] Document the default frontend/MySQL addresses and state that MySQL initialization scripts run only when its data directory is empty; existing databases must use reviewed patches after backup.
- [x] Do not include `docker compose down -v` or any other volume-deletion command in the documentation.
- [x] Re-run the SQL contract suite and Compose config validation; do not run `docker compose up`.
## Verification Commands
```bash
PYTHONDONTWRITEBYTECODE=1 /Users/jiaolongyan/miniconda3/envs/ShiErFeng/bin/python -m unittest tests.module_business.test_sql_contract -v
MYSQL_ROOT_PASSWORD=compose-validation DB_USERNAME=compose_validation DB_PASSWORD=compose-validation JWT_SECRET_KEY=compose-validation docker compose config --quiet
```
Do not run the SQL initializer, migration patches, or `docker compose up` during implementation verification.
docs/superpowers/specs/2026-07-24-pallet-workflow-system-design.md
-440
View File
@@ -1,440 +0,0 @@
# 智链云枢托盘业务系统设计
## 1. 背景与目标
当前项目是基于 Vue 3、Element Plus、Pinia、Vite、FastAPI 和异步 SQLAlchemy 的通用管理后台。Web 菜单由后端 `/getRouters` 根据 `sys_menu`、`sys_role_menu` 动态生成，按钮权限由前端 `v-hasPermi` 控制，真实接口权限由后端 `UserInterfaceAuthDependency` 校验。
本次以用户提供的流程图为最终业务依据，完成以下目标：
- 完整移除“AI管理”专属功能。
- 删除“施尔丰仓库”外链菜单。
- 在“系统管理”下新增托盘基础资料、五类业务操作和六类报表。
- 保证菜单、页面、API、按钮权限、后端权限与数据范围一致。
- 建立可审计、可并发控制的托盘库存和追溯模型。
## 2. 已确认的范围
### 2.1 本次包含
- Web 前端页面、动态菜单、按钮权限、API 请求和类型约定。
- FastAPI 后端 Controller、Service、DAO、DO、VO、状态机和权限校验。
- MySQL、PostgreSQL 初始化脚本同步。
- 一份仅供审查、不自动执行的 MySQL 增量补丁。
- 直接相关的测试、README、CHANGELOG 和依赖声明。
- 适配 Android PDA 浏览器的 Web 操作页面。
### 2.2 本次明确排除
- 不修改 `shierfeng-fastapi-app` 下任何文件，也不兼容其现有接口逻辑。
- 不连接、不写入、不迁移本地 MySQL。
- 不生成或执行 PostgreSQL 增量补丁。
- 不删除现有数据库中的 AI 业务表、模型配置、聊天配置或 Agno 运行数据。
- 不新增在途、签收、拒收、冲销、库存调整、导入、导出或摄像头扫码功能。
- 不预置新的业务角色，不给现有普通角色自动分配新增权限。
- 不删除用户、角色、菜单、部门、岗位、字典、参数、通知、日志、监控或系统工具等通用功能。
## 3. 总体架构
### 3.1 后端
新增独立的 `module_business`，继续采用现有分层：
```text
module_business/
├── controller/
├── service/
├── dao/
├── entity/
│ ├── do/
│ └── vo/
└── domain/
```
模块内部职责划分：
- `master`：菌种、客户、客户现场、产线、仓库、托盘及用户授权。
- `operation`：首次入库、工厂装填、发货、现场使用、退回。
- `report`：六类只读报表和托盘追溯。
- `domain`：托盘状态枚举、状态迁移规则和跨业务公共校验。
Controller 只负责协议、参数、认证和权限依赖；Service 负责事务、状态机、数据范围和幂等；DAO 负责持久化查询；前端不得直接指定最终库存或最终状态。
### 3.2 Web
新增以下目录，沿用现有页面与请求风格：
```text
src/api/master/
src/api/business/
src/api/report/
src/views/master/
src/views/business/
src/views/report/
src/components/PalletScanInput/
```
PDA 页面属于 Web 页面，使用响应式布局。扫码设备按 HID 键盘输入处理：输入框自动聚焦，扫码头输入二维码后回车提交；不调用摄像头，不引入前端扫码依赖。
### 3.3 库存一致性
托盘是业务聚合根。每次状态变更必须在一个数据库事务内同时完成：
1. 校验接口权限和仓库/客户现场数据范围。
2. 锁定托盘当前库存行。
3. 校验当前状态、位置、数量和幂等键。
4. 写入或确认业务单据。
5. 更新托盘当前库存快照。
6. 追加不可变托盘事件。
任何一步失败都整体回滚，多托盘单据不允许部分成功。
## 4. 主数据模型
### 4.1 `biz_strain`
- 菌种是基础品种/SKU，不代表生产批次。
- `strain_code` 非空且唯一。
- 生产批次、包装规格和本次装填包数保存在装填记录中。
- 已被业务引用后只能停用，不能删除。
### 4.2 `biz_warehouse`
- 保存仓库编码、名称、地址和启停状态。
- `warehouse_code` 非空且唯一。
- 通过 `biz_user_warehouse` 与现有 `sys_user` 多对多关联。
### 4.3 客户、现场与产线
- `biz_customer`：客户主数据，客户编码唯一。
- `biz_customer_site`：归属于客户，现场编码在同一客户下唯一。
- `biz_production_line`：仅表示客户现场使用/消耗产线，产线编码在同一现场下唯一。
- `biz_user_site`：现有用户与客户现场的多对多关联。
- 本次不建立工厂内部装填产线。
### 4.4 `biz_pallet`
- 保存托盘编号、容量包数、资产启停状态和固定二维码标识。
- `pallet_code`、`qr_token` 非空且唯一，创建后不可修改。
- 托盘创建时同时建立 `biz_pallet_inventory`，初始流转状态为 `UNSTOCKED`。
- 二维码只编码不可推测的随机 `qr_token`，不包含菌种、批次、数量、客户或权限信息。
- 使用后端 `qrcode` 和现有 Pillow 生成可打印二维码；二维码损坏时补打原标识，不允许换码。
## 5. 业务与库存模型
### 5.1 单据与事实表
| 表 | 用途和核心约束 |
|---|---|
| `biz_inbound_order` | 首次入库单，状态仅为 `DRAFT`、`CONFIRMED`，单号唯一。 |
| `biz_inbound_item` | 入库单托盘明细，同一单据内托盘唯一。 |
| `biz_filling_record` | 单托盘即时装填；保存菌种、批次、包装规格、初始整数包数、仓库和操作人。 |
| `biz_shipment_order` | 发货单，状态仅为 `DRAFT`、`CONFIRMED`，单号唯一。 |
| `biz_shipment_item` | 多托盘整托发货明细；包数由确认时的当前余量快照生成，不允许手填拆分。 |
| `biz_usage_record` | 每次现场使用事实；保存产线、本次使用包数、使用后余量和幂等键。 |
| `biz_return_order` | 两阶段退回单，状态为 `REQUESTED`、`CONFIRMED`。 |
| `biz_return_item` | 退回托盘及发起时余量快照；同一退回单内托盘唯一。 |
| `biz_pallet_inventory` | 每托盘唯一一行当前状态、位置、余量、当前装填记录、当前绑定产线和版本号。 |
| `biz_pallet_event` | 只追加追溯流水；记录来源单据、前后状态、位置、数量、操作人、时间和幂等键。 |
### 5.2 数量约束
- 库存最小单位为“包”，所有包数均为整数。
- 装填量和使用量必须大于零。
- 剩余量必须满足 `0 <= remaining_packages <= pallet.capacity_packages`。
- 一个托盘的同一装填周期只能包含一个菌种和一个生产批次，禁止混装。
- 当前装填记录在余量归零后关闭；下一次装填形成新的独立记录，不覆盖历史。
### 5.3 位置约束
`biz_pallet_inventory` 在任意时刻只能表达一个有效位置：
- 位于仓库时只能有 `warehouse_id`。
- 位于客户现场时只能有 `site_id`。
- `UNSTOCKED` 时两者都为空。
- `current_line_id` 只能在客户现场第一次使用后设置，并在仓库确认退回时清空。
## 6. 托盘状态机
```text
UNSTOCKED
└─ 首次入库确认 → EMPTY_IN_WAREHOUSE
└─ 单托盘装填 → FILLED_IN_WAREHOUSE
└─ 发货确认 → AT_SITE_UNUSED
├─ 部分使用 → AT_SITE_PARTIAL
├─ 全部用完 → AT_SITE_EMPTY
└─ 发起退回 → RETURNING
AT_SITE_PARTIAL
├─ 继续部分使用 → AT_SITE_PARTIAL
├─ 全部用完 → AT_SITE_EMPTY
└─ 发起退回 → RETURNING
AT_SITE_EMPTY
└─ 发起退回 → RETURNING
RETURNING
└─ 仓库确认收货：
├─ remaining_packages > 0 → FILLED_IN_WAREHOUSE
└─ remaining_packages = 0 → EMPTY_IN_WAREHOUSE
```
补充规则：
- 发货确认后直接归属目标客户现场，不增加在途或签收状态。
- 客户现场第一次使用时选择产线，本次驻场周期内不可变更。
- 客户发起退回后冻结使用和再次发货，直到仓库确认。
- 仓库确认退回后解除产线绑定。
- 带料退回保留原菌种、批次和余量，可再次整托发货；再次到达现场后重新绑定产线。
- 空托盘必须退回仓库后才能再次装填。
## 7. 五类业务流程
### 7.1 仓库入库
- 只处理已建档空托盘的首次入库。
- 创建草稿，选择目标仓库，连续扫描 `UNSTOCKED` 托盘。
- 草稿可编辑或删除；确认后锁定全部托盘并整单转为 `EMPTY_IN_WAREHOUSE`。
- 流程图中连续出现的第二个“创建入库单”按重复节点处理。
### 7.2 工厂装填
- 扫描 `EMPTY_IN_WAREHOUSE` 托盘。
- 校验当前用户拥有该仓库数据权限。
- 选择菌种，填写生产批次、包装规格和正整数包数。
- 一次操作只处理一个托盘并即时确认。
- 成功后创建装填记录，状态转为 `FILLED_IN_WAREHOUSE`。
### 7.3 发货出库
- 创建草稿，选择来源仓库和目标客户现场。
- 一张发货单允许多个托盘，只允许整托发货。
- 当前用户必须同时拥有来源仓库和目标客户现场数据权限。
- 确认时按托盘 ID 排序加锁；全部成功后转为 `AT_SITE_UNUSED`。
- 不增加在途、签收或拒收流程。
### 7.4 客户现场使用
- 用户必须具备 `business:usage:add` 且关联当前客户现场。
- 扫码后后端返回托盘、菌种、批次、当前余量和允许操作。
- 第一次使用选择该现场下的产线，并锁定至本次退回完成。
- 使用包数必须为正整数且不得超过当前余量。
- 使用后余量大于零时转为 `AT_SITE_PARTIAL`，等于零时转为 `AT_SITE_EMPTY`。
- 使用请求必须携带幂等键，PDA 重复提交不得重复扣减。
### 7.5 退回仓库
- 客户现场用户扫描一个或多个同现场托盘，选择目标仓库并发起退回。
- 发起后保存余量快照，托盘转为 `RETURNING`，禁止继续使用。
- 仓库人员实际收货扫码确认，必须拥有目标仓库数据权限。
- 确认时重新校验状态和余量快照，整单成功或整单回滚。
- 有余料时转为 `FILLED_IN_WAREHOUSE`，无余料时转为 `EMPTY_IN_WAREHOUSE`。
## 8. 菜单、页面、API 与权限
### 8.1 菜单结构
```text
系统管理
├─ 基础资料维护
│ ├─ 菌种资料
│ ├─ 客户资料
│ ├─ 客户现场
│ ├─ 产线资料
│ ├─ 仓库资料
│ └─ 托盘资料
├─ 业务管理
│ ├─ 仓库入库
│ ├─ 工厂装填
│ ├─ 发货出库
│ ├─ 客户现场使用
│ └─ 退回仓库
└─ 报表查询
├─ 托盘库存
├─ 装填记录
├─ 发货出库
├─ 产线消耗
├─ 退回仓库
└─ 托盘追溯
```
三个目录节点不设置权限字符串。页面菜单使用 `*:list`，按钮节点使用具体操作权限。
### 8.2 权限映射
| 页面 | 资源前缀 | 动作 |
|---|---|---|
| 菌种资料 | `master:strain` | `list/query/add/edit/remove` |
| 客户资料 | `master:customer` | `list/query/add/edit/remove` |
| 客户现场 | `master:site` | `list/query/add/edit/remove/assign` |
| 产线资料 | `master:line` | `list/query/add/edit/remove` |
| 仓库资料 | `master:warehouse` | `list/query/add/edit/remove/assign` |
| 托盘资料 | `master:pallet` | `list/query/add/edit/remove/print` |
| 仓库入库 | `business:inbound` | `list/query/add/edit/remove/confirm` |
| 工厂装填 | `business:filling` | `list/query/add` |
| 发货出库 | `business:shipment` | `list/query/add/edit/remove/confirm` |
| 客户现场使用 | `business:usage` | `list/query/add` |
| 退回仓库 | `business:return` | `list/query/request/confirm` |
| 托盘库存 | `report:palletinventory` | `list` |
| 装填记录 | `report:filling` | `list` |
| 发货出库 | `report:shipment` | `list` |
| 产线消耗 | `report:consumption` | `list` |
| 退回仓库 | `report:return` | `list` |
| 托盘追溯 | `report:pallettrace` | `list` |
每个权限字符串必须同时出现在：
1. `sys_menu.perms`。
2. Web 的 `v-hasPermi` 或页面权限判断。
3. 后端 `UserInterfaceAuthDependency`。
4. 对应权限测试。
未授权用户绕过 Web 直接调用接口时返回现有规范的 403。拥有功能权限但没有目标仓库或客户现场关联时，同样拒绝访问。
### 8.3 API 前缀
- 主数据：`/master/strain`、`/master/customer`、`/master/site`、`/master/line`、`/master/warehouse`、`/master/pallet`。
- 业务：`/business/inbound`、`/business/filling`、`/business/shipment`、`/business/usage`、`/business/return`。
- 报表：`/report/pallet-inventory`、`/report/filling`、`/report/shipment`、`/report/consumption`、`/report/return`、`/report/pallet-trace`。
各业务 Controller 提供自己的扫码查询接口，避免现场操作员被迫获得托盘主数据管理权限。所有写接口由后端重新查询当前状态，不信任前端提交的库存、位置或状态。
### 8.4 角色
- 不新增固定业务角色。
- 不写入新增菜单对应的普通角色种子。
- 超级管理员沿用现有特例获得全部菜单和数据。
- 其他用户通过现有角色管理分配菜单和按钮，并通过仓库/客户现场页面分配数据范围。
- 角色授权必须包含“系统管理 → 分组目录 → 页面 → 按钮”的完整祖先链。
## 9. Web 页面行为
### 9.1 基础资料
- 沿用现有搜索、分页、表格和弹窗表单风格。
- 仓库和客户现场页面提供“分配用户”。
- 托盘页面提供二维码生成、查看、打印和补打。
- 被引用数据只允许停用；未引用数据才显示删除操作。
### 9.2 PDA Web
- 页面使用大尺寸输入区和操作按钮，适配 Android PDA 浏览器。
- 扫码输入框在成功、失败和页面恢复后重新聚焦。
- 回车触发扫码查询，重复扫码给出明确提示。
- 使用 `crypto.randomUUID()` 生成请求幂等键，不新增前端 UUID 依赖。
- 前端展示后端返回的状态和允许动作，不自行推算业务状态。
### 9.3 报表
六个独立页面只提供查询、筛选和分页：
- 托盘库存：当前状态、位置、菌种、批次、初始包数和剩余包数。
- 装填记录：装填时间、仓库、托盘、菌种、批次、规格和包数。
- 发货出库：发货单、客户现场、托盘和发货时余量。
- 产线消耗：客户、现场、产线、托盘、菌种、批次和使用包数。
- 退回仓库：退回申请、目标仓库、托盘、余量和确认时间。
- 托盘追溯：按事件时间展示托盘完整状态、位置和数量变化。
筛选条件从日期、仓库、客户、现场、产线、菌种、批次、托盘编号和状态中按页面需要选取。本次不提供 Excel 导出。
## 10. AI 管理与外链菜单清理
### 10.1 删除范围
- 删除后端 `module_ai` 全部源码。
- 删除 `utils/ai_util.py` 和仅被 AI 使用的 `utils/crypto_util.py`。
- 删除 Web `src/api/ai`、`src/views/ai` 和三个 AI 图标。
- 删除 13 个 `/ai/*` 接口及 `ai:model:*`、`ai:chat:*` 权限。
- 删除 AI 专属缓存命名空间、限流常量和 LiteLLM 日志配置。
- 从后端 requirements 删除 Agno 和模型提供商 SDK。
- 从前端 `package.json` 删除仅供 AI 使用的 Markdown、Monaco、UUID 等依赖，并删除 Monaco Vite 配置。
- README 删除当前 AI 功能说明；CHANGELOG 保留历史新增记录并增加移除记录。
### 10.2 保留范围
- 认证、JWT、接口权限、数据范围、自动路由扫描、缓存、日志、限流和通用上传。
- `utils/transport_crypto_util.py`。
- `@vueuse/core`、Pillow、PyJWT、cryptography 等共享依赖。
- 通用 API Key 日志脱敏测试。
- 导航栏独立“源码地址”和“文档地址”入口。
### 10.3 数据库残留策略
- 两套初始化脚本删除 AI 菜单、角色关联、AI 字典和 AI 表 DDL，确保新环境不再创建 AI 功能。
- MySQL 增量补丁删除 AI 菜单元数据、AI 字典元数据和“施尔丰仓库”菜单，但不执行。
- 增量补丁不得包含 `DROP TABLE ai_models`、`DROP TABLE ai_chat_config` 或任何 Agno 表删除语句。
- 现有 AI 表、行数、敏感配置和备份需求在最终交付中单独列出，后续获得明确确认后再清理。
## 11. SQL 交付策略
### 11.1 初始化脚本
MySQL 和 PostgreSQL 初始化脚本保持语义一致：
- 删除 AI 和外链菜单种子。
- 删除 AI 字典及 AI 表定义。
- 新增业务表、唯一约束、检查约束和索引。
- 新增三个目录、十一个业务/主数据页面、六个报表页面及按钮权限。
- 不重新编号现有无关菜单、字典或序列。
- 不给普通角色增加 `sys_role_menu` 记录。
### 11.2 MySQL 增量补丁
- 文件名使用日期和业务含义，作为一次性、可审查补丁。
- DDL 使用明确表名；菜单删除使用已审计的明确 ID，禁止通配删除。
- DDL 与菜单 DML 分节书写，明确 MySQL DDL 隐式提交边界。
- 包含业务表创建、菜单与权限插入、AI 元数据和菜单 ID 99 清理。
- 不连接、不执行本地 MySQL。
- 补丁应用后的 Redis 菜单、用户信息和 AI 字典缓存清理作为部署步骤记录，不在本次自动执行。
## 12. 错误、并发与审计
- 认证失败、功能越权和数据范围越权沿用项目现有异常与 403 处理。
- 非法数量、资源不存在、托盘状态冲突或单据状态冲突必须返回失败，不得伪成功。
- 所有确认、使用和退回请求使用唯一幂等键。
- 状态变更使用数据库行锁；多托盘按托盘 ID 排序加锁以降低死锁概率。
- `biz_pallet_inventory.version` 用于并发版本校验。
- `biz_pallet_event` 只追加、不修改、不删除；`sys_oper_log` 只作为补充审计，不能替代业务追溯。
- 已确认单据不可编辑或删除，本次不实现冲销或补偿事件入口。
## 13. 验证与验收
### 13.1 后端
- 运行 `ruff` 和相关 `pytest`。
- 验证应用可以导入，OpenAPI 中不存在 `/ai/*`。
- 覆盖状态机合法/非法迁移、整数数量边界、超用、幂等、数据范围和 403。
- 覆盖入库、装填、发货、使用、退回的事务回滚行为。
- 验证二维码生成接口输出有效图形。
### 13.2 Web
- 运行项目可用的 lint/check 命令和生产构建。
- 检查所有按钮权限和请求 URL 与后端一致。
- 检查 PDA 扫码输入、自动聚焦、重复提交和错误展示。
- 确认 `shierfeng-fastapi-app` 没有本次任务产生的改动。
### 13.3 静态和 SQL
- 使用 `rg` 检查 AI 页面、接口、权限、依赖和配置残留。
- 对比 MySQL、PostgreSQL 初始化脚本中的业务表和权限集合。
- 检查 MySQL 增量补丁不包含 AI 业务表删除。
- 检查菜单组件路径均对应真实 Web 页面。
### 13.4 本轮无法完成的运行态验收
由于用户选择只生成而不执行 MySQL 补丁，本轮不能真实验证：
- 业务表在 MySQL 中的实际建表结果。
- 运行态 `/getRouters` 是否返回新增菜单并移除旧菜单。
- 不同真实角色和仓库/现场授权数据下的完整端到端流程。
- 补丁执行后的 Redis 缓存失效行为。
这些项目必须在用户后续审查并应用补丁后执行，交付时不得表述为已通过。
## 14. 实施顺序
1. 保护现有未提交改动并建立验证基线。
2. 删除 AI 专属代码、配置、依赖和外链菜单种子。
3. 实现主数据、用户授权、二维码和状态机基础。
4. 实现首次入库、装填、发货、现场使用和两阶段退回。
5. 实现六类只读报表和托盘追溯。
6. 同步两套初始化脚本并生成不执行的 MySQL 增量补丁。
7. 执行后端、Web、权限、静态和 SQL 验证。
8. 交付修改清单、验证证据、AI 数据库残留和补丁应用后验收项。
docs/superpowers/specs/2026-07-27-promote-business-menus-design.md
-66
View File
@@ -1,66 +0,0 @@
# 业务菜单提升为一级菜单设计
## 目标
将“基础资料维护”、“业务管理”、“报表查询”从“系统管理”下提升为独立一级菜单，使业务入口与系统管理入口在侧边栏中并列展示。
## 目标层级与顺序
一级菜单按以下顺序展示：
1. 基础资料维护（`menu_id=121`）
2. 业务管理（`menu_id=122`）
3. 报表查询（`menu_id=123`）
4. 系统管理（`menu_id=1`）
5. 系统监控（`menu_id=2`）
6. 系统工具（`menu_id=3`）
对应的持久化字段为：
| 菜单 ID | 菜单名称 | `parent_id` | `order_num` |
|---|---|---:|---:|
| 121 | 基础资料维护 | 0 | 1 |
| 122 | 业务管理 | 0 | 2 |
| 123 | 报表查询 | 0 | 3 |
| 1 | 系统管理 | 0 | 4 |
| 2 | 系统监控 | 0 | 5 |
| 3 | 系统工具 | 0 | 6 |
## 架构与改动边界
项目的 Web 路由和侧边栏由后端 `/getRouters` 根据 `sys_menu` 动态生成，因此应修改菜单数据，不在前端增加拍平或重排逻辑。
本次仅调整六个目录菜单的层级和排序：
- 保持业务子菜单、组件路径、API 和权限标识不变。
- 保持角色菜单关联不变。
- 不修改 APP 端。
- 不新增依赖，不改动现有动态路由机制。
## SQL 与迁移设计
1. 同步修改 MySQL 和 PostgreSQL 初始化 SQL，使新建数据库直接得到目标层级。
2. 保留已执行的 `20260724_pallet_workflow_mysql.sql` 历史补丁，不改写已落库迁移的语义。
3. 新增一个 MySQL 增量补丁，同时支持“调整前”和“已调整”两种合法状态，保证可幂等重跑。
4. 增量补丁在第一条永久 DML 前校验六个固定 ID 的菜单身份和允许的层级状态。任一 ID 缺失、被复用或稳定字段异常时，在写入前中止。
5. 六条更新置于显式事务中，只修改 `parent_id` 和 `order_num`；执行器不得使用 `--force` 或 continue-on-error 模式。
6. 补丁末尾输出六个目录的实际层级和排序，用于人工核对。
## 缓存与运行态
数据库更新后，不使用 Redis `FLUSHALL`。本地验证通过重新登录触发现有登录缓存失效逻辑，并使用独立查询参数核对 `/getRouters` 的新层级。
## 测试与验收
- 先增加失败契约，要求 MySQL/PostgreSQL 初始化 SQL 定义上述六个一级菜单顺序。
- 增加增量补丁契约，覆盖写前校验、幂等性、显式事务、精确更新范围和事后查询。
- 运行后端 SQL 契约、业务测试、Ruff 检查、前端业务契约和生产构建。
- 数据库执行前重新创建备份，并只有在用户再次明确确认后才执行增量补丁。
- 数据库验收必须确认六个目录均为 `parent_id=0`，排序为 `1..6`，业务子菜单数量、页面组件和权限标识不变。
## 不在本次范围内
- 业务页面的功能、样式或交互调整。
- 普通角色的新授权或仓库/现场数据映射。
- 历史 AI 数据库表或其他数据清理。
- Redis 全库清理。
docs/superpowers/specs/2026-09-20-pda-business-workflow-design.md
-179
View File
@@ -1,179 +0,0 @@
# PDA 托盘业务操作功能补全设计
## 1. 背景与目标
当前仓库已经具备 Web 后台、FastAPI 业务接口、托盘库存状态机、数据库结构、权限模型和六类报表。`shierfeng-fastapi-app` 目前只有通用登录、首页、工作台和个人中心，没有托盘业务操作页面与对应 API 封装。
本次在不改变既有后端业务契约的前提下，补齐 uni-app PDA 操作端的现场业务功能。PDA 暂不生成 APK，先完成页面、接口对接、扫码交互、权限控制和可验证的开发运行版本。
## 2. 范围确认
### 2.1 本次包含
- 复用现有 `/login`、`/getInfo`、`/logout` 认证流程。
- 在 `shierfeng-fastapi-app` 增加五类现场操作：
- 仓库入库
- 工厂装填
- 发货出库
- 客户现场使用
- 退回仓库
- 增加 PDA 端 API 模块、扫码输入组件、业务页面、权限显示和错误/重试处理。
- 复用后端已有状态机、幂等键、数据范围、库存事务和托盘追溯，不在 PDA 前端自行计算最终库存或状态。
- 适配 PDA 扫码头的 HID 键盘输入和回车提交，并保留手工输入作为故障兜底。
- 增加 PDA 端静态契约测试和 H5/开发构建验证；不生成 APK。
- 继续使用 Web 后台维护菌种、客户、现场、产线、仓库、托盘和六类报表。
### 2.2 本次不包含
- 不打包、签名、安装或发布 APK。
- 不调用摄像头扫码，不新增原生扫码 SDK；当前以 HID 扫码枪输入为主。
- 不把基础资料维护和六类报表复制到 PDA。
- 不修改现有 FastAPI 业务接口的请求/响应契约，除非实现阶段发现有明确且可验证的 PDA 阻塞缺口。
- 不修改 `shierfeng-fastapi-frontend` 的既有 Web 业务页面，除非共享契约缺陷直接阻塞 PDA。
- 不修改 `.env.dev`、`.env.prod`、前端环境文件、用户已有 APP 改动或无关缓存。
- 不执行生产部署、服务器配置、Redis 清理、数据库迁移或培训；这些属于后续运行交付，需要单独的环境授权和验收。
- 不把管理员密码写入源码、设计文档、日志或测试固定文本。
## 3. 用户角色与权限边界
PDA 页面只展示当前用户拥有的权限，后端接口权限和仓库/现场数据范围仍是最终权威：
| 角色能力 | PDA 操作 |
|---|---|
| 仓库操作员 | 查看可访问仓库、创建/确认入库、扫描装填、创建/确认发货、确认退回 |
| 客户现场操作员 | 扫描托盘、首次选择产线、录入使用包数、发起退回 |
| 业务管理员/超级管理员 | 依据既有权限可执行全部授权操作 |
不新增固定角色，不自动给普通用户授权。仓库与客户现场的数据范围继续由现有用户-仓库、用户-现场关系决定。
## 4. 页面与 API 设计
### 4.1 PDA 页面
新增页面建议采用以下路径，沿用当前 uni-app 页面路由和 Tailwind 样式：
```text
src/pages/business/inbound/index.vue
src/pages/business/filling/index.vue
src/pages/business/shipment/index.vue
src/pages/business/usage/index.vue
src/pages/business/return/index.vue
```
工作台只增加实际权限允许的业务入口，不保留“建设中”假入口。页面加载失败、权限不足和接口异常必须给出可操作提示。
### 4.2 PDA API 封装
复用后台已有接口路径，在 `src/api/business/` 增加：
```text
inbound.js
filling.js
shipment.js
usage.js
return.js
```
每个模块覆盖对应的列表、详情、选项、扫码、创建/编辑/删除、确认或提交接口；请求字段使用后端既有 camelCase 契约，不在前端另建同义字段。
### 4.3 共享扫码组件
新增 PDA 专用扫码输入组件，职责仅限于输入采集和规范化：
- 自动聚焦可用输入框。
- 兼容 HID 扫码枪逐字符输入后回车提交。
- 去除首尾空白，拒绝空值。
- 防止同一托盘在短时间内重复追加。
- 扫码请求期间锁定相关输入，避免并发提交。
- 支持“重新扫描”和手工输入兜底。
- 不在组件内决定托盘状态、库存数量或权限结果。
## 5. 五类业务流程
### 5.1 入库
选择后端返回的可用仓库，创建草稿并连续扫描 `UNSTOCKED` 托盘；允许移除草稿明细，确认时复用业务幂等键。提交成功后以服务端结果刷新页面，不由 PDA 推算库存。
### 5.2 装填
扫描托盘并展示后端返回的仓库、状态和当前余量；选择菌种，填写批次、规格和正整数包数；提交后清理表单并重新获取托盘状态。非法状态、超容量、无仓库权限由后端拒绝并原样转为用户可读提示。
### 5.3 发货
选择来源仓库和目标客户现场，连续扫描多个可发货托盘；展示菌种、批次和剩余包数只读信息；确认前复核托盘集合，服务端负责整单锁定、库存扣减和事件追加。
### 5.4 客户现场使用
扫描托盘后展示菌种、批次、当前余量和允许操作；首次使用要求选择当前现场产线，后续使用沿用后端锁定产线；使用包数必须为正整数且不超过服务端返回余量。成功后只采用服务端返回的新余量和状态。
### 5.5 退回仓库
客户现场扫描待退回托盘，选择目标仓库并发起退回；仓库用户扫描并确认收货。申请和确认分别持有独立幂等键，页面分别保存两阶段状态，确认后以服务端返回的库存状态刷新。
## 6. 认证、密码与安全
- PDA 继续使用当前 JWT、传输加密和 `/getInfo` 权限信息。
- 前端不硬编码管理员密码；给定账号只用于经授权的本地联调验证。
- 当前登录页中的旧默认密码预填值需要改为不暴露密码的空表单或开发环境专用行为，不能把真实密码写入仓库。
- 管理员密码变更属于账号凭据写操作，须先只读核对当前认证存储，再单独确认、备份并执行，日志不得输出密码、Token 或 Cookie。
- PDA 页面隐藏不能替代后端权限校验；所有业务请求继续经过后端接口权限和数据范围检查。
## 7. 状态、幂等与错误处理
- PDA 只提交业务输入和幂等键，不提交目标库存、目标状态或版本号。
- 网络超时、响应丢失或用户重试时复用同一个业务幂等键；同键不同请求内容显示冲突，不自动生成新业务操作。
- 扫码重复、按钮重复点击和页面切换期间的旧响应由前端请求序列号/锁控制。
- 401 继续走现有会话过期处理；403、业务状态冲突、库存不足和数据范围错误必须显示后端消息并允许安全重试。
- 页面恢复或重新进入时，以详情/列表接口作为唯一权威，不能相信本地缓存的库存和状态。
## 8. 验证与交付
### 8.1 代码验证
- 为 PDA API 路径、字段映射、权限入口、扫码规范化、幂等键复用和五类页面交互增加 Node 20 契约测试。
- 使用现有后端业务测试和 Ruff 验证共享接口没有回归。
- 运行 uni-app 的 H5/开发构建或等价编译检查；不执行 `build:app`，不生成 APK。
- 对当前工作区做精确 diff 检查，保留用户已有 APP、环境、日志和缓存改动。
### 8.2 人工验收清单
1. 使用管理员和受限普通用户分别登录。
2. 验证未授权菜单不显示、直接接口请求返回 403。
3. 使用 HID 扫码枪验证五类业务的扫码、回车、重复扫码和错误重试。
4. 验证库存、剩余包数、产线绑定、退回冻结和事件追溯均以后端结果为准。
5. 验证页面刷新/断网重试不重复扣减库存。
真实服务器部署、APK 安装、客户培训和跨设备实测在本次代码补全后仍需单独安排，不能用本地构建结果替代。
## 9. 当前基线与风险
- Web/FastAPI 核心业务已存在并有业务测试；本次重点是 uni-app PDA 缺失能力。
- 当前 PDA 工程已包含通用登录、首页、工作台、个人中心，以及入库、装填、发货、现场使用、退回五类业务页面和对应 API 模块。
- 后端接口、Web 管理页面和数据库 SQL 已存在；PDA 的实际设备联调、服务器访问地址、数据库迁移和真实角色授权仍需运行环境配合。
- APK 暂不打包，因此本次交付物是源码、接口封装、页面和可验证开发版本，不包含安装包。
## 10. 需求覆盖矩阵（代码审计结果）
下表区分“代码已实现”和“真实环境已交付”，避免把静态测试或本地构建误认为部署、安装或培训完成。
| 序号 | 需求 | 当前结论 | 主要证据 |
| ---: | --- | --- | --- |
| 1 | 业务流程、功能边界、角色、交付内容和不包含事项 | 已确认 | 本设计第 1～3、8～9 节 |
| 2 | 托盘、菌种、产线、仓库、装填、发货、使用、退回字段 | 已梳理 | `module_business/entity`、SQL 脚本 |
| 3 | 后台、接口、数据库结构和基础运行环境 | 代码已完成；实际环境未部署 | `module_business`、`sql/`、前后端工程 |
| 4 | 菌种、产线、仓库、用户等基础资料维护 | 已实现 | Web `views/master`、系统用户/角色模块 |
| 5 | 托盘唯一标识、固定二维码、状态和档案 | 已实现 | `biz_pallet` 唯一约束、状态机、托盘管理页 |
| 6 | 入库登记、入库单、库存更新 | 已实现 | `inbound_controller.py`、`inbound_service.py` |
| 7 | 扫码装填菌种、批次、规格、包数并更新状态 | 已实现 | `filling_service.py`、Web/PDA 装填页 |
| 8 | 发货单、托盘扫码/选择、明细和库存扣减 | 已实现 | `shipment_service.py`、Web/PDA 发货页 |
| 9 | PDA 登录、扫码识别和读取菌种/余量 | 已实现；未打包 APK | `shierfeng-fastapi-app/src/pages/business`、PDA API |
| 10 | 客户扫码、产线绑定、使用包数、操作人和时间 | 已实现 | `usage_service.py`、使用记录模型和页面 |
| 11 | 全部/部分使用、剩余包数、退回和状态流转 | 已实现 | `pallet_state_machine.py`、使用/退回服务 |
| 12 | 六类库存、装填、发货、消耗、退回、追溯报表 | 已实现 | `report_controller.py`、Web 六类报表页 |
| 13 | 权限、操作记录、流转追溯和异常留痕 | 已实现 | 权限依赖、`Log`、`biz_pallet_event`、追溯报表 |
| 14 | Android 页面、接口、PDA 适配和 APK | 页面/API/HID 已实现；APK 按要求暂缓 | PDA H5 构建与扫码组件 |
| 15 | 后台、接口、PDA、库存、退回整体联调 | 代码级验证完成；真实设备联调未完成 | 契约测试通过；缺少真实设备/服务地址 |
| 16 | 服务器、数据库、后台/接口服务和访问地址部署 | 未完成 | 缺少目标服务器和部署授权 |
| 17 | App 安装、扫码验收和客户培训 | 未完成 | 缺少 PDA 设备及培训安排 |
登录页默认只填充用户名 `admin`；密码保持空白并由操作员手工输入，不将真实密码写入源码、测试或日志。
docs/superpowers/specs/2026-09-22-test-data-batch-cleanup-design.md
-298
View File
@@ -1,298 +0,0 @@
# 测试数据批次隔离与级联清理设计
## 1. 背景
当前菌种、客户、客户现场、产线、仓库和托盘等主数据在被业务单据引用后不允许删除。该约束能保护正式业务的外键完整性、库存状态、报表口径和托盘追溯链，但也导致开发、联调和验收期间产生的测试数据无法安全清理。
本设计引入“测试数据批次”，将正式数据与测试数据从创建、查询、业务操作到报表统计全程隔离。超级管理员可在预览完整影响范围后整批清理测试数据；正式数据在任何情况下都不能通过该能力物理删除。
## 2. 目标与非目标
### 2.1 目标
- 以测试批次为边界隔离正式数据和测试数据。
- 支持授权的普通用户在指定测试批次内完成入库、装填、发货、使用和退回流程。
- 支持超级管理员将升级前已有的旧测试数据完整纳入测试批次。
- 支持关闭批次后预览影响范围，并在单个数据库事务中整批清理。
- 保留批次元数据和操作审计，但不保留已清理的测试业务明细。
- 防止前端绕过、权限误配、并发请求或部分失败导致正式数据被删或测试链路残缺。
### 2.2 非目标
- 不允许按单条主数据或单据强制级联删除。
- 不允许将正在进行的批次直接清理。
- 不用测试清理代替正式业务的停用、作废、冲销或审计流程。
- 不根据名称、编码、创建人或时间自动猜测旧数据是否为测试数据。
- 不在本次实施中直接运行生产数据库迁移或清理。
## 3. 角色与权限边界
| 能力 | 超级管理员 | 已授权测试用户 | 其他用户 |
| --- | --- | --- | --- |
| 查看测试批次管理 | 允许 | 不允许 | 不允许 |
| 创建、关闭、重新开启批次 | 允许 | 不允许 | 不允许 |
| 授权批次测试用户 | 允许 | 不允许 | 不允许 |
| 创建批次内测试主数据 | 允许 | 不允许 | 不允许 |
| 进入已授权批次执行业务 | 允许 | 允许 | 不允许 |
| 将旧数据纳入批次 | 允许 | 不允许 | 不允许 |
| 预览并整批清理 | 允许 | 不允许 | 不允许 |
| 物理删除正式数据 | 不允许 | 不允许 | 不允许 |
超级管理员以后端 `current_user.user.admin` 为最终判断，不仅依赖前端角色或菜单权限。测试批次接口可同时使用独立权限字符控制菜单展示，但权限字符被误分配给普通角色时，后端仍必须返回 403。
## 4. 数据模型
### 4.1 测试批次
新增 `biz_test_batch`，至少包含：
- `batch_id`：主键。
- `batch_code`：系统生成的唯一编码。
- `batch_name`：用于界面识别与二次确认。
- `status`：`ACTIVE`、`CLOSED`、`PURGED`。
- `create_by`、`create_time`、`update_by`、`update_time`。
- `closed_by`、`closed_at`、`purged_by`、`purged_at`。
- `purge_summary`：保留按数据类型汇总的清理数量，不保留敏感业务内容。
- `remark`：批次用途说明。
新增 `biz_test_batch_user`，保存批次与参与测试用户的关联。该关联只是批次的外层访问权；现有用户-仓库、用户-现场数据范围仍然生效。
### 4.2 业务数据标记
以下表新增可空 `test_batch_id` 和索引，并外键引用 `biz_test_batch.batch_id`：
- 主数据：`biz_strain`、`biz_customer`、`biz_customer_site`、`biz_production_line`、`biz_warehouse`、`biz_pallet`。
- 入库：`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`。
`test_batch_id IS NULL` 表示正式数据；非空表示所属测试批次。该字段不允许普通业务请求直接写入，由后端从已验证的当前模式或关联记录中派生。
`biz_user_warehouse` 和 `biz_user_site` 不重复保存 `test_batch_id`，其数据归属由所关联的仓库或现场派生。批次清理时，必须先删除指向该批次仓库和现场的用户关联。
### 4.3 一致性约束
- 正式数据只能引用正式数据。
- 测试数据只能引用同一批次的测试数据。
- 不同测试批次之间不能互相引用。
- 批次标记一旦创建不能通过通用编辑接口修改。
- 只有“纳入测试批次”专用流程可将旧的无标记数据一次性改为测试数据。
- 关联对象的批次一致性由服务层在写入前校验，数据库外键作为存在性和删除顺序的最后保护。
- 现有编码、单号和二维码唯一约束继续全局生效；测试数据使用独立编码，清理后可重新使用。
## 5. 数据模式与查询隔离
### 5.1 模式选择
Web 管理端和 PDA 操作端都需支持：
- 正式模式：不传测试批次上下文，后端只允许 `test_batch_id IS NULL` 的数据。
- 测试模式：携带当前 `batch_id`。已授权用户只能进入 `ACTIVE` 批次；超级管理员可在批次管理页以只读方式检查 `CLOSED` 批次。任何写入都要求批次为 `ACTIVE`。
前端可通过统一请求头传递当前批次，但该值只是请求上下文，不是信任根。后端必须每次验证用户授权、批次状态和数据归属。
### 5.2 隔离范围
批次条件必须应用于：
- 六类基础资料的列表、详情和选项。编码、单号和二维码的唯一性校验仍按全局数据执行，与现有数据库唯一约束保持一致。
- 入库、装填、发货、使用和退回的列表、详情、扫码、创建、修改和确认。
- 仓库、现场、产线、菌种和托盘等业务选项接口。
- 托盘库存、装填、发货、消耗、退回和追溯六类报表。
- 首页仓储运营指标、待处理数量、趋势图和状态分布。
任何缺失批次条件的查询都可能造成测试数据污染正式报表，实施时必须对所有业务 DAO 做完整盘点。
## 6. 批次生命周期
```text
ACTIVE --关闭--> CLOSED --重新开启--> ACTIVE
|
+--预览并确认清理--> PURGED
```
- `ACTIVE`：允许超级管理员创建测试主数据，允许已授权用户执行业务。
- `CLOSED`：所有测试数据只读；可查看、预览清理范围、重新开启或清理。
- `PURGED`：批次业务数据已删除；仅保留批次元数据和审计汇总，不能重新开启。
关闭、重新开启和清理都需锁定批次记录。每个测试写操作在业务数据加锁前必须重新校验批次仍为 `ACTIVE`，保证“关闭成功后无新写入”。
## 7. 新测试数据创建与业务继承
1. 超级管理员创建批次，分配参与测试的用户。
2. 超级管理员切换到该批次，创建菌种、客户、现场、产线、仓库和托盘。
3. 后端根据当前批次自动写入 `test_batch_id`，忽略或拒绝请求体中伪造的批次字段。
4. 已授权用户进入该批次，使用批次内的仓库、现场、产线、菌种和托盘执行业务。
5. 入库单、装填记录、发货单、使用记录、退回单、库存和事件由后端自动继承同一 `test_batch_id`。
6. 任一关联数据的批次不一致时，整个业务操作失败并回滚。
## 8. 旧数据纳入测试批次
### 8.1 入口
超级管理员在正式模式的基础资料和业务管理页选择旧数据后，可执行“纳入测试批次”。报表页不提供该操作，因为报表行不是独立业务实体；需从其来源主数据或单据发起。
### 8.2 关联闭包
后端必须沿实际外键与业务关联双向计算连通闭包，直到没有新关联记录。闭包至少覆盖：
- 菌种与装填记录。
- 客户、现场与产线层级。
- 仓库、入库、装填、发货和退回。
- 托盘、单据明细、库存、使用记录和追溯事件。
- 与装填周期相关的发货、使用和退回记录。
由于旧数据没有可靠的测试标记，系统无法自动识别闭包中哪些数据被用户视为“正式”。预览必须按表展示数量和关键编号；如果闭包包含需保留的正式数据，管理员必须取消，系统不允许只标记半条关联链。
### 8.3 确认与写入
- 目标批次必须为 `ACTIVE`。
- 闭包中所有数据必须尚未归属任何测试批次。
- 管理员需输入目标批次名称二次确认。
- 服务端使用不透明预览校验标识；确认时重新计算闭包，范围变化则拒绝旧确认。
- 事务内锁定批次和闭包中的根记录，然后一次性写入所有 `test_batch_id`。
- 任何一步失败都回滚，不得出现部分数据已纳入、部分数据仍为正式的状态。
## 9. 整批清理
### 9.1 前置条件
- 操作人必须是超级管理员。
- 批次必须为 `CLOSED`。
- 清理预览需展示每类主数据、单据、明细、库存和事件的数量。
- 管理员必须输入完整批次名称并通过最终确认。
- 确认请求必须携带服务端生成的一次性预览标识。
### 9.2 事务与删除顺序
清理服务在单个数据库事务内锁定批次，重新计算影响范围并校验预览标识。删除顺序必须由实际外键图生成并以回归测试固化，原则为：
1. 先删除 `biz_pallet_inventory`，解除其对托盘事件和活动装填记录的外键引用。
2. 删除 `biz_usage_record`、`biz_return_item`、`biz_shipment_item` 和 `biz_inbound_item`。
3. 删除 `biz_return_order`、`biz_shipment_order` 和 `biz_inbound_order`。
4. 删除 `biz_pallet_event`，再删除 `biz_filling_record`。
5. 删除指向测试仓库、现场的 `biz_user_warehouse` 和 `biz_user_site` 关联。
6. 先删除产线，再删除现场和客户；随后删除仓库、菌种和托盘等其他主数据。
7. 删除批次用户授权，更新批次为 `PURGED`，写入清理汇总。
实施时以 SQLAlchemy 模型和 MySQL/PostgreSQL 外键的实际编译结果为准，不依赖上述文字顺序代替自动化测试。
不对业务外键配置 `ON DELETE CASCADE`。如果任何外键、并发状态或数据库错误导致删除失败，整个事务回滚，批次保持 `CLOSED`。
### 9.3 幂等与审计
- 同一批次的并发清理只有一个可以执行，其他请求等待后读取最新状态。
- 对 `PURGED` 批次重复请求返回稳定的“已清理”结果，不重复执行删除。
- 批次记录保留清理人、清理时间和分类数量。
- 系统操作日志保留，作为审计证据；日志不记录密码、Token、Cookie 或大量业务明细。
## 10. 界面与交互
### 10.1 测试数据批次管理
在“系统管理”下新增“测试数据批次”页面，仅超级管理员可见。页面支持：
- 查看批次编码、名称、状态、创建人、参与用户和时间。
- 创建批次、编辑备注、授权或移除测试用户。
- 关闭或重新开启未清理批次。
- 查看数据汇总、清理预览和最终清理确认。
- 查看已清理批次的审计汇总。
### 10.2 模式提示
- Web 顶部和 PDA 工作台提供“正式数据 / 已授权测试批次”切换。
- 测试模式始终展示高可见的批次名称和“测试数据”标识，不得只在隐蔽的下拉框中表示。
- 切换模式后刷新当前列表、选项、首页指标和报表，并清空未提交的跨模式表单状态。
- 批次被关闭、授权被移除或会话失效时，普通测试用户退回正式模式并得到明确提示；超级管理员仍可从批次管理页查看关闭批次的只读汇总和清理预览。
### 10.3 现有删除入口
- 基础资料、业务管理和报表页不再提供物理删除入口。
- 正式主数据通过停用保留历史引用；正式业务单据按现有业务状态处理，不使用测试批次能力物理删除。
- 旧的删除 API 保留路由兼容，但统一拒绝物理删除并提示“请通过测试数据批次清理”。
- “纳入测试批次”只在正式模式下向超级管理员展示。
## 11. 后端组件与接口边界
建议新增独立的批次控制器、服务、DAO 和 VO，不将级联清理逻辑分散到六个主数据服务中。职责划分如下：
- 批次管理：创建、列表、详情、用户授权、关闭和重新开启。
- 批次上下文：解析请求模式，校验用户与批次，为查询和写入提供受信任的 `batch_id | None`。
- 批次一致性校验：根据业务输入校验所有关联数据处于同一模式和批次。
- 旧数据纳入：计算关联闭包、生成预览、校验确认并原子写入批次标记。
- 整批清理：统计影响数据、生成预览、校验确认并原子删除。
预览与执行必须分为不同接口。执行接口不接受前端传入的“要删哪些表或 ID”，只接受批次 ID、批次名称确认和一次性预览标识；实际范围始终由后端重算。
## 12. 错误处理
需向用户明确区分以下失败：
- 非超级管理员访问管理或清理接口。
- 用户未被授权访问所选测试批次。
- 批次已关闭、已清理或在操作期间状态发生变化。
- 请求将正式数据与测试数据或不同批次数据混用。
- 旧数据关联闭包包含已属于其他批次的数据。
- 预览后数据范围发生变化，一次性校验标识失效。
- 批次名称确认不匹配。
- 外键、并发或数据库错误触发整体回滚。
前端不将未知错误表示为成功，也不在失败后乐观移除列表记录。所有成功状态均以服务端提交后重新查询的结果为准。
## 13. 数据库迁移与发布
- 同步更新 MySQL 和 PostgreSQL 全量建库脚本。
- 为已有环境提供 MySQL 和 PostgreSQL 增量补丁。
- 先创建批次与授权表，再以可空字段方式增加 `test_batch_id`、索引和外键。
- 既有记录的 `test_batch_id` 保持 `NULL`，迁移不自动更新业务数据。
- 发布前必须完成数据库备份和恢复演练；应用迁移和首次旧数据纳入属于独立高风险操作，需单独确认后执行。
- 先发布后端与前端代码，确认正式模式查询不回归，再创建新测试批次或纳入旧数据。
## 14. 测试与验证
### 14.1 后端
- 批次生命周期和不合法状态转换。
- 超级管理员硬校验，包括普通用户持有误分配权限字符的情况。
- 批次用户授权与现有仓库/现场数据范围的叠加效果。
- 正式、同批次和跨批次关联校验。
- 创建主数据和五类业务时的批次自动继承。
- 主数据、业务列表、选项、扫码、首页和六类报表的模式隔离。
- 旧数据闭包的完整性、循环去重、跨批次拒绝和事务回滚。
- 关闭批次后所有写入被拒绝，重新开启后恢复。
- 清理预览计数、预览过期、确认文本、外键删除顺序、失败回滚和重复清理幂等性。
- MySQL 和 PostgreSQL 的 SQL 编译与迁移契约。
### 14.2 Web 与 PDA
- 超级管理员、已授权测试用户和未授权用户的菜单与按钮可见性。
- 正式/测试模式切换、批次标识、请求上下文和授权失效回退。
- 旧数据纳入预览、批次名称二次确认和预览过期提示。
- 批次关闭后的只读界面和清理确认。
- 现有物理删除按钮移除，直接调用旧删除 API 时的稳定拒绝提示。
- Web 生产构建、PDA H5 构建、最相关契约测试和后端业务单元测试。
## 15. 验收标准
1. 正式模式的页面、选项、首页和报表不展示任何测试数据。
2. 测试模式只展示当前批次数据，不显示正式数据或其他批次数据。
3. 授权的普通用户可完成测试业务链，但无法管理、纳入、关闭或清理批次。
4. 正式与测试数据、不同测试批次之间不能混用。
5. 超级管理员可预览并完整纳入旧测试数据，范围变化时旧确认失效。
6. `ACTIVE` 批次不能清理；`CLOSED` 批次不能新增或修改业务数据。
7. 整批清理成功后，所有相关主数据、单据、明细、库存和追溯记录消失，报表不再返回该批次数据。
8. 清理任一步失败时不删除任何数据，批次仍为 `CLOSED`。
9. 超级管理员也无法通过批次清理或旧删除 API 物理删除正式数据。
10. 已清理批次保留操作人、时间和分类数量，且日志不包含凭据或敏感信息。
## 16. 已知风险与控制
- **旧数据闭包可能过大**：旧测试数据如果复用了正式仓库、现场或托盘，关联闭包可能扩展到大量正式数据。系统必须展示完整预览并允许取消，不提供忽略关联的强制选项。
- **大批量事务时间较长**：在目标数据库上通过压力测试确定在线清理上限，并将上限写入部署配置和运维文档。在线接口必须阻止超过上限的批次，且不得通过分段提交规避原子性；超大批次由 DBA 在备份后使用受审计脚本处理。数值上限依赖目标环境，本设计不在缺少实测数据时猜测固定值。
- **请求上下文被伪造**：后端每次验证授权、批次状态和数据归属，不相信前端显示或请求头本身。
- **漏加查询条件导致统计污染**：使用统一批次上下文和 DAO 查询辅助方法，并用契约测试盘点全部业务查询。
- **仅前端隐藏不能提供安全性**：批次管理、纳入和清理均在后端强制超级管理员检查。
- **迁移与实际数据存在差异**：应用前在目标数据库执行只读外键和表结构盘点，与代码模型和迁移脚本三方对照，不假设生产结构与仓库 SQL 完全一致。
logs/2026/09/26/error.log
View File
logs/2026/09/26/info.log
View File
logs/2026/09/27/error.log
View File
logs/2026/09/27/info.log
View File
shierfeng-fastapi-app/README.md
+1 -1
View File
@@ -33,7 +33,7 @@ VITE_APP_BASE_API=http://<服务器地址>:9099 pnpm run build:h5
不要把包含真实凭据的环境文件或地址配置提交到仓库。
PDA 测试模式、批次授权和失效回退规则请阅读[测试数据批次操作说明](../docs/test-data-batch-operations.md)。PDA 只允许选择后端返回的 ACTIVE 授权批次，退出登录会清除本地批次上下文。
PDA 测试模式、批次授权和失效回退规则请阅读[测试数据批次操作说明](../shierfeng-fastapi-backend/sql/test-data-batch-operations.md)。PDA 只允许选择后端返回的 ACTIVE 授权批次，退出登录会清除本地批次上下文。
### vscode
shierfeng-fastapi-app/package.json
+1 -1
View File
@@ -3,7 +3,7 @@
"version": "1.9.0",
"packageManager": "pnpm@10.28.1",
"scripts": {
"test:business": "node --test tests/business-contract.test.mjs",
"test:business": "node --test tests/*.test.mjs",
"dev": "uni -p mp-weixin",
"build": "npm run build:mp-weixin",
"dev:app": "uni -p app",
shierfeng-fastapi-app/src/api/business/filling.js
+1 -1
View File
@@ -17,7 +17,7 @@ export function getFillingStrainOptions() {
export function scanFillingPallet(qrToken) {
return request({
url: "/business/filling/scan/" + qrToken,
url: "/business/filling/scan/" + encodeURIComponent(qrToken),
method: "get",
});
}
shierfeng-fastapi-app/src/api/business/inbound.js
+1 -1
View File
@@ -17,7 +17,7 @@ export function getInboundWarehouseOptions() {
export function scanInboundPallet(qrToken, query) {
return request({
url: "/business/inbound/scan/" + qrToken,
url: "/business/inbound/scan/" + encodeURIComponent(qrToken),
method: "get",
params: query,
});
shierfeng-fastapi-app/src/api/business/return.js
+1 -1
View File
@@ -17,7 +17,7 @@ export function getReturnWarehouseOptions() {
export function scanReturnPallet(qrToken, query) {
return request({
url: "/business/return/scan/" + qrToken,
url: "/business/return/scan/" + encodeURIComponent(qrToken),
method: "get",
params: query,
});
shierfeng-fastapi-app/src/api/business/shipment.js
+1 -1
View File
@@ -24,7 +24,7 @@ export function getShipmentSiteOptions() {
export function scanShipmentPallet(qrToken, query) {
return request({
url: "/business/shipment/scan/" + qrToken,
url: "/business/shipment/scan/" + encodeURIComponent(qrToken),
method: "get",
params: query,
});
shierfeng-fastapi-app/src/api/business/shipmentReceipt.js
+22
View File
@@ -0,0 +1,22 @@
import request from '@/utils/request'
// 收货仅依赖目标现场范围，使用独立端点，不能复用出库查询。
export function listShipmentReceipts(query) {
return request({ url: '/business/shipment-receipt/list', method: 'get', params: query })
}
export function getShipmentReceipt(shipmentId) {
return request({ url: '/business/shipment-receipt/' + shipmentId, method: 'get' })
}
export function scanShipmentReceipt(shipmentId, identifier) {
return request({
url: '/business/shipment-receipt/' + shipmentId + '/scan/' + encodeURIComponent(identifier),
method: 'get'
})
}
export function confirmShipmentReceipt(shipmentId, data) {
return request({ url: '/business/shipment-receipt/' + shipmentId + '/confirm', method: 'put', data })
}
shierfeng-fastapi-app/src/api/business/usage.js
+25 -1
View File
@@ -16,13 +16,37 @@ export function getUsageLineOptions(siteId) {
});
}
export function getUsageTunnelOptions(siteId) {
return request({
url: "/business/usage/tunnel-options",
method: "get",
params: { siteId },
});
}
export function enterUsageTunnel(data) {
return request({
url: "/business/usage/enter-tunnel",
method: "post",
data,
});
}
export function scanUsagePallet(qrToken) {
return request({
url: "/business/usage/scan/" + qrToken,
url: "/business/usage/scan/" + encodeURIComponent(qrToken),
method: "get",
});
}
export function getUsageFifoRecommendation(qrToken, tunnelId) {
return request({
url: "/business/usage-fifo/recommendation",
method: "get",
params: { qrToken, ...(tunnelId != null ? { tunnelId } : {}) },
});
}
export function getUsage(usageId) {
return request({
url: "/business/usage/" + usageId,
shierfeng-fastapi-app/src/components/business/PalletScanInput.vue
+1 -1
View File
@@ -9,7 +9,7 @@
maxlength="128"
:focus="focusRequested"
:disabled="disabled || loading"
placeholder="请扫描或输入托盘二维码后按回车"
placeholder="扫描二维码或输入托盘号后按回车"
@confirm="handleSubmit"
@input="clearError"
/>
shierfeng-fastapi-app/src/components/business/ShipmentReceiptPanel.vue
+302
View File
@@ -0,0 +1,302 @@
<template>
<view v-if="canReceive" class="space-y-4">
<view class="rounded-2xl bg-white p-4 shadow-sm">
<text class="mb-3 block font-bold text-gray-800">收货单</text>
<picker :range="receiptStateOptions" range-key="label" :value="receiptStateIndex" @change="changeReceiptState">
<view class="mb-3 rounded-xl bg-gray-50 px-3 py-3 text-sm text-gray-700">{{ receiptStateOptions[receiptStateIndex].label }}</view>
</picker>
<input v-model="queryParams.shipmentNo" class="mb-3 rounded-xl bg-gray-50 px-3 py-3 text-sm" maxlength="64" placeholder="输入原发货单号" confirm-type="search" @confirm="handleQuery" />
<button size="mini" class="rounded-lg bg-blue-50 text-blue-600" :disabled="loading" @click="handleQuery">查询收货</button>
<text v-if="listError" class="mt-3 block text-xs text-red-500">{{ listError }}</text>
<text v-if="loading" class="mt-3 block text-xs text-gray-400">加载中...</text>
<text v-else-if="!receiptList.length" class="mt-3 block text-xs text-gray-400">暂无收货单</text>
<view v-for="row in receiptList" :key="row.shipmentId" class="mt-3 rounded-xl border border-gray-100 p-3">
<view class="flex items-center justify-between gap-2">
<text class="text-sm font-medium text-gray-700">{{ row.shipmentNo }}</text>
<text class="text-xs text-orange-600">{{ receiptStateLabel(row.receiptState) }}</text>
</view>
<text class="mt-2 block text-xs text-gray-500">仓库 #{{ row.sourceWarehouseId }} → 现场 #{{ row.targetSiteId }}</text>
<text v-if="row.receiptState === 'RECEIVED'" class="mt-1 block text-xs text-gray-500">收货时间：{{ row.receivedAt || '未登记' }}</text>
<button size="mini" class="mt-3 rounded-lg bg-orange-50 text-orange-600" @click="openReceipt(row)">{{ row.receiptState === 'PENDING' ? '核对收货' : '查看明细' }}</button>
</view>
<view class="mt-3 flex items-center justify-between gap-2">
<button size="mini" :disabled="loading || queryParams.pageNum <= 1" @click="changePage(-1)">上一页</button>
<text class="text-xs text-gray-500">第 {{ queryParams.pageNum }} 页 · 共 {{ total }} 单</text>
<button size="mini" :disabled="loading || queryParams.pageNum * queryParams.pageSize >= total" @click="changePage(1)">下一页</button>
</view>
</view>
<view v-if="activeShipmentId !== null" class="rounded-2xl bg-white p-4 shadow-sm">
<view class="mb-3 flex items-center justify-between">
<text class="font-bold text-gray-800">收货核对</text>
<button size="mini" class="text-xs text-gray-500" @click="closeReceipt">关闭</button>
</view>
<text v-if="detailLoading" class="block text-xs text-gray-400">加载原单明细...</text>
<text v-if="detailError" class="mb-3 block text-xs text-red-500">{{ detailError }}</text>
<button v-if="detailError" size="mini" :disabled="detailLoading || confirmLoading" @click="retryDetail">重新读取详情</button>
<template v-if="receiptDetail">
<text class="block text-sm font-medium text-gray-700">{{ receiptDetail.shipmentNo }} · {{ receiptStateLabel(receiptDetail.receiptState) }}</text>
<text class="mt-1 block text-xs text-gray-500">目标现场 #{{ receiptDetail.targetSiteId }}</text>
<text v-if="receiptDetail.receiptState === 'RECEIVED'" class="mt-1 block text-xs text-gray-500">收货时间：{{ receiptDetail.receivedAt || '未登记' }}</text>
<text v-if="receiptDetail.receiptState === 'LEGACY'" class="mt-3 block text-xs text-gray-500">历史未登记收货：仅供查询原单明细，不补造收货时间。</text>
<view v-if="receiptDetail.receiptState === 'PENDING'" class="mt-3">
<PalletScanInput :key="activeShipmentId" :disabled="!canScan" :loading="scanLoading" @scan="handleReceiptScan" @invalid="message => scanError = message" @duplicate="scanError = '扫码过快，请勿重复扫描'" />
<text class="mt-2 block text-xs text-gray-500">逐托核对原标签，已核对 {{ scannedPalletIds.length }} / {{ receiptItems.length }} 托，全部核对后才可确认。</text>
</view>
<text v-if="scanError" class="mt-3 block text-xs text-red-500">{{ scanError }}</text>
<text v-if="!receiptItems.length" class="mt-3 block text-xs text-red-500">原单无托盘明细，无法确认收货</text>
<view v-for="item in receiptItems" :key="item.palletId" class="mt-3 rounded-xl bg-gray-50 p-3">
<view class="flex items-center justify-between gap-2">
<text class="text-sm font-medium text-gray-700">{{ item.palletCode }}</text>
<text v-if="receiptDetail.receiptState === 'PENDING'" class="text-xs text-orange-600">{{ scannedPalletIds.includes(item.palletId) ? '已核对' : '待扫描' }}</text>
</view>
<text class="mt-2 block text-xs text-gray-600">品种：{{ item.strainName || '未登记' }} · 原发货 {{ item.packageQty }} 包</text>
<text class="mt-1 block text-xs text-gray-500">批号：{{ item.batchNo || '未登记' }}</text>
<text class="mt-1 block text-xs text-gray-500">生产日期：{{ item.productionDate || '未登记' }}</text>
<text class="mt-1 block text-xs text-gray-500">失效日期：{{ item.expiryDate || '未登记' }}</text>
<button v-if="receiptDetail.receiptState === 'PENDING' && scannedPalletIds.includes(item.palletId)" size="mini" class="mt-2 text-xs text-red-500" :disabled="!canScan || scanLoading" @click="removeScannedPallet(item.palletId)">撤销核对</button>
</view>
<text v-if="confirmError" class="mt-3 block text-xs text-red-500">{{ confirmError }}</text>
<button v-if="receiptDetail.receiptState === 'PENDING'" class="mt-4 rounded-xl bg-orange-500 py-3 text-sm text-white disabled:bg-gray-300" :disabled="!canConfirmReceipt" :loading="confirmLoading" @click="confirmReceipt">确认收货</button>
</template>
</view>
</view>
</template>
<script setup>
import { computed, getCurrentInstance, onBeforeUnmount, onMounted, reactive, ref } from 'vue'
import { onHide, onShow, onUnload } from '@dcloudio/uni-app'
import PalletScanInput from '@/components/business/PalletScanInput.vue'
import { listShipmentReceipts, getShipmentReceipt, scanShipmentReceipt, confirmShipmentReceipt } from '@/api/business/shipmentReceipt'
import { createIdempotencyKey } from '@/utils/palletScan'
const { proxy } = getCurrentInstance()
const emit = defineEmits(['received'])
const canReceive = computed(() => proxy.$auth.hasPermi('business:shipment:receive'))
const queryParams = reactive({ pageNum: 1, pageSize: 10, receiptState: 'PENDING', shipmentNo: undefined })
const receiptList = ref([])
const total = ref(0)
const loading = ref(false)
const listError = ref('')
const activeShipmentId = ref(null)
const receiptDetail = ref(null)
const detailLoading = ref(false)
const detailError = ref('')
const scannedPalletIds = ref([])
const scanLoading = ref(false)
const scanError = ref('')
const confirmLoading = ref(false)
const confirmError = ref('')
const receiptAccepted = ref(false)
let session = 0
let listGeneration = 0
let suspended = false
let idempotencyKey = ''
const receiptItems = computed(() => receiptDetail.value?.items || [])
const canScan = computed(() => canReceive.value && activeShipmentId.value !== null &&
receiptDetail.value?.status === 'CONFIRMED' && receiptDetail.value?.receiptState === 'PENDING' &&
!detailLoading.value && !detailError.value && !confirmLoading.value && !receiptAccepted.value)
const canConfirmReceipt = computed(() => canScan.value && !scanLoading.value &&
receiptItems.value.length > 0 && receiptItems.value.length === scannedPalletIds.value.length &&
receiptItems.value.every(item => scannedPalletIds.value.includes(item.palletId)))
function receiptStateLabel(state) {
return { PENDING: '待收货', RECEIVED: '已收货', LEGACY: '历史未登记收货' }[state] || '未登记收货'
}
function errorMessage(error, fallback) {
return error?.response?.data?.msg || error?.message || fallback
}
function isCurrent(currentSession) {
return currentSession === session && !suspended && canReceive.value
}
async function loadReceipts() {
if (!canReceive.value || suspended) return
const generation = ++listGeneration
loading.value = true
listError.value = ''
try {
const response = await listShipmentReceipts({ ...queryParams })
if (generation !== listGeneration || suspended || !canReceive.value) return
receiptList.value = Array.isArray(response.rows) ? response.rows : []
total.value = response.total || 0
} catch (error) {
if (generation !== listGeneration || suspended || !canReceive.value) return
receiptList.value = []
total.value = 0
listError.value = errorMessage(error, '收货列表加载失败，请重试')
} finally {
if (generation === listGeneration) loading.value = false
}
}
function handleQuery() {
queryParams.pageNum = 1
return loadReceipts()
}
function closeReceipt() {
// 会话版本同时隔离详情、扫码、确认响应，旧请求不能写入新单据。
session += 1
activeShipmentId.value = null
receiptDetail.value = null
scannedPalletIds.value = []
detailLoading.value = false
scanLoading.value = false
confirmLoading.value = false
receiptAccepted.value = false
detailError.value = ''
scanError.value = ''
confirmError.value = ''
idempotencyKey = ''
}
async function loadReceiptDetail(shipmentId, currentSession) {
detailLoading.value = true
detailError.value = ''
try {
const response = await getShipmentReceipt(shipmentId)
if (!isCurrent(currentSession)) return
if (!response.data || String(response.data.shipmentId) !== String(shipmentId)) {
throw new Error('收货详情与当前单据不一致，请重新打开')
}
receiptDetail.value = response.data
} catch (error) {
if (!isCurrent(currentSession)) return
detailError.value = errorMessage(error, '收货详情加载失败，请重试')
} finally {
if (isCurrent(currentSession)) detailLoading.value = false
}
}
async function openReceipt(row) {
if (!canReceive.value || suspended || row.shipmentId == null) return
closeReceipt()
activeShipmentId.value = row.shipmentId
await loadReceiptDetail(row.shipmentId, session)
}
function retryDetail() {
if (activeShipmentId.value === null || detailLoading.value || confirmLoading.value) return
return loadReceiptDetail(activeShipmentId.value, session)
}
async function handleReceiptScan(identifier) {
if (!canScan.value || scanLoading.value) return
const value = String(identifier ?? '').trim()
if (!value) {
scanError.value = '请扫描二维码或输入托盘号'
return
}
const currentSession = session
scanLoading.value = true
scanError.value = ''
try {
const response = await scanShipmentReceipt(activeShipmentId.value, value)
if (!isCurrent(currentSession)) return
const scanned = response.data
const original = receiptItems.value.find(item => String(item.palletId) === String(scanned?.palletId))
if (!original || String(original.activeFillingId) !== String(scanned?.activeFillingId)) {
scanError.value = '该托盘或装填记录不属于当前发货单'
return
}
if (scannedPalletIds.value.includes(original.palletId)) {
scanError.value = '该托盘已核对，请勿重复扫描'
return
}
// 仅登记实际扫码通过的 ID；品种、批号、日期与包数始终展示原单快照。
scannedPalletIds.value.push(original.palletId)
idempotencyKey = ''
confirmError.value = ''
} catch (error) {
if (isCurrent(currentSession)) scanError.value = errorMessage(error, '托盘核对失败，请重试')
} finally {
if (isCurrent(currentSession)) scanLoading.value = false
}
}
function removeScannedPallet(palletId) {
if (!canScan.value || scanLoading.value) return
if (!scannedPalletIds.value.includes(palletId)) return
scannedPalletIds.value = scannedPalletIds.value.filter(id => id !== palletId)
idempotencyKey = ''
confirmError.value = ''
}
async function confirmReceipt() {
if (!canReceive.value || confirmLoading.value || receiptAccepted.value) return
if (!canConfirmReceipt.value) {
confirmError.value = '请逐托扫码核对全部明细后再确认收货'
return
}
const currentSession = session
const shipmentId = activeShipmentId.value
confirmLoading.value = true
confirmError.value = ''
try {
// 失败保留同一键；增删核对集合时作废，下一次提交生成新键。
if (!idempotencyKey) idempotencyKey = createIdempotencyKey()
const response = await confirmShipmentReceipt(shipmentId, {
scannedPalletIds: [...scannedPalletIds.value], idempotencyKey
})
if (!isCurrent(currentSession)) return
receiptAccepted.value = true
proxy.$modal.msgSuccess(response.msg || '收货成功')
emit('received')
// 不推算余量，也不伪造已收状态/时间。刷新失败仍锁定本次已接受的确认。
await Promise.all([loadReceiptDetail(shipmentId, currentSession), loadReceipts()])
} catch (error) {
if (isCurrent(currentSession)) {
confirmError.value = errorMessage(error, '收货确认失败') + '；未修改核对集合时重试使用同一幂等键'
}
} finally {
if (isCurrent(currentSession)) confirmLoading.value = false
}
}
function suspendPanel() {
suspended = true
listGeneration += 1
loading.value = false
closeReceipt()
}
function resumePanel() {
if (!suspended) return
suspended = false
loadReceipts()
}
onMounted(loadReceipts)
onBeforeUnmount(suspendPanel)
const receiptStateOptions = [
{ label: '待收货', value: 'PENDING' },
{ label: '已收货', value: 'RECEIVED' },
{ label: '历史未登记收货', value: 'LEGACY' },
{ label: '全部', value: undefined }
]
const receiptStateIndex = computed(() => receiptStateOptions.findIndex(item => item.value === queryParams.receiptState))
function changeReceiptState(event) {
const option = receiptStateOptions[Number(event.detail.value)]
if (!option) return
queryParams.receiptState = option.value
handleQuery()
}
function changePage(offset) {
const page = queryParams.pageNum + offset
if (loading.value || page < 1 || (page > 1 && (page - 1) * queryParams.pageSize >= total.value)) return
queryParams.pageNum = page
loadReceipts()
}
onShow(resumePanel)
onHide(suspendPanel)
onUnload(suspendPanel)
</script>
shierfeng-fastapi-app/src/config/businessMenu.js
+1
View File
@@ -22,6 +22,7 @@ export const businessMenuEntries = [
icon: "i-mdi-truck-delivery",
iconClass: "bg-orange-50 text-orange-600",
permission: "business:shipment:list",
permissions: ["business:shipment:list", "business:shipment:receive"],
},
{
path: "/pages/business/usage/index",
shierfeng-fastapi-app/src/pages/business/filling/index.vue
+35 -8
View File
@@ -80,6 +80,18 @@
@input="markPayloadChanged"
/>
</view>
<view>
<text class="mb-2 block text-xs text-gray-500">生产日期</text>
<picker mode="date" :value="form.productionDate" :disabled="operationPending || !scannedPallet" @change="handleMaterialDateChange('productionDate', $event)">
<view class="rounded-xl bg-gray-50 px-3 py-3 text-sm text-gray-700">{{ form.productionDate || '选择来源生产日期' }}</view>
</picker>
</view>
<view>
<text class="mb-2 block text-xs text-gray-500">有效期至</text>
<picker mode="date" :value="form.expiryDate" :start="form.productionDate" :disabled="operationPending || !scannedPallet" @change="handleMaterialDateChange('expiryDate', $event)">
<view class="rounded-xl bg-gray-50 px-3 py-3 text-sm text-gray-700">{{ form.expiryDate || '选择有效期截止日期' }}</view>
</picker>
</view>
<view>
<text class="mb-2 block text-xs text-gray-500">包装规格</text>
<input
@@ -97,9 +109,8 @@
v-model="form.initialPackages"
class="rounded-xl bg-gray-50 px-3 py-3 text-sm text-gray-700"
type="number"
placeholder="请输入正整数"
:disabled="operationPending || !scannedPallet"
@input="markPayloadChanged"
placeholder="固定 100 包"
disabled
/>
<text v-if="scannedPallet" class="mt-1 block text-xs text-gray-400">
托盘容量 {{ scannedPallet.capacityPackages }} 包，最终容量由服务端校验
@@ -177,8 +188,10 @@ const form = reactive({
warehouseId: null,
strainId: null,
batchNo: "",
productionDate: "",
expiryDate: "",
packageSpec: "",
initialPackages: "",
initialPackages: 100,
});
let listGeneration = 0;
let scanGeneration = 0;
@@ -251,8 +264,10 @@ function resetOperation() {
form.warehouseId = null;
form.strainId = null;
form.batchNo = "";
form.productionDate = "";
form.expiryDate = "";
form.packageSpec = "";
form.initialPackages = "";
form.initialPackages = 100;
scanError.value = "";
formError.value = "";
scanLoading.value = false;
@@ -280,7 +295,7 @@ function handleFillingScan(qrToken) {
flowState: pallet.flowState,
capacityPackages: pallet.capacityPackages,
};
form.qrToken = qrToken;
form.qrToken = pallet.qrToken || qrToken;
form.warehouseId = pallet.warehouseId;
loadStrainOptions();
})
@@ -313,6 +328,12 @@ function markPayloadChanged() {
if (!submitLoading.value) idempotencyKey.value = "";
}
function handleMaterialDateChange(field, event) {
if (operationPending.value) return;
form[field] = event.detail.value;
markPayloadChanged();
}
function ensureIdempotencyKey() {
if (!idempotencyKey.value) idempotencyKey.value = createIdempotencyKey();
return idempotencyKey.value;
@@ -329,8 +350,12 @@ function submitFilling() {
formError.value = "请完整填写菌种、批次和包装规格";
return;
}
if (!Number.isInteger(initialPackages) || initialPackages <= 0) {
formError.value = "初始包数必须为正整数";
if (!form.productionDate || !form.expiryDate || form.expiryDate < form.productionDate) {
formError.value = "请填写生产日期和有效期，且有效期不能早于生产日期";
return;
}
if (initialPackages !== 100) {
formError.value = "新装填固定为 100 包";
return;
}
submitLoading.value = true;
@@ -340,6 +365,8 @@ function submitFilling() {
warehouseId: form.warehouseId,
strainId: form.strainId,
batchNo: form.batchNo.trim(),
productionDate: form.productionDate,
expiryDate: form.expiryDate,
packageSpec: form.packageSpec.trim(),
initialPackages,
idempotencyKey: ensureIdempotencyKey(),
shierfeng-fastapi-app/src/pages/business/shipment/index.vue
+24 -10
View File
@@ -4,13 +4,13 @@
<view class="space-y-4 p-4 pb-24">
<view class="flex items-center justify-between">
<view>
<text class="block text-xl font-bold text-gray-800">发货出库</text>
<text class="block text-xl font-bold text-gray-800">{{ activeTab === 'receipt' ? '收货核对' : '发货出库' }}</text>
<text class="mt-1 block text-xs text-gray-500">
选择来源仓库和目标现场，扫码创建整托发货单
{{ activeTab === 'receipt' ? '扫描原托盘标签，逐托核对目标现场收货' : '选择来源仓库和目标现场，扫码创建整托发货单' }}
</text>
</view>
<button
v-if="canDraft"
v-if="canDraft && activeTab === 'shipment'"
class="rounded-lg bg-orange-500 px-3 py-2 text-xs text-white active:opacity-80"
size="mini"
:disabled="operationPending"
@@ -20,12 +20,17 @@
</button>
</view>
<TestBatchBanner />
<view v-if="!canPage" class="rounded-2xl bg-white p-6 text-center shadow-sm">
<text class="text-sm text-gray-500">当前账号没有发货操作权限</text>
<view v-if="canReceive" class="flex gap-3">
<button v-if="canShipment" size="mini" :class="activeTab === 'shipment' ? 'bg-orange-500 text-white' : 'bg-white text-gray-600'" @click="activeTab = 'shipment'">发货出库</button>
<button size="mini" :disabled="operationPending || editorVisible" :class="activeTab === 'receipt' ? 'bg-orange-500 text-white' : 'bg-white text-gray-600'" @click="activeTab = 'receipt'">收货核对</button>
</view>
<template v-else>
<view v-if="!canPage" class="rounded-2xl bg-white p-6 text-center shadow-sm">
<text class="text-sm text-gray-500">当前账号没有发货或收货权限</text>
</view>
<ShipmentReceiptPanel v-else-if="canReceive && activeTab === 'receipt'" @received="loadShipmentList" />
<template v-else-if="canShipment && activeTab === 'shipment'">
<view v-if="editorVisible" class="rounded-2xl bg-white p-4 shadow-sm">
<view class="mb-4 flex items-center justify-between">
<text class="font-bold text-gray-800">
@@ -155,8 +160,8 @@
>
<view class="flex items-center justify-between">
<text class="font-medium text-gray-700">{{ row.shipmentNo || `#${row.shipmentId}` }}</text>
<text :class="row.status === 'DRAFT' ? 'text-orange-500' : 'text-green-500'" class="text-xs">
{{ row.status === "DRAFT" ? "草稿" : "已确认" }}
<text :class="row.status === 'DRAFT' || row.receiptState === 'PENDING' ? 'text-orange-500' : row.receiptState === 'LEGACY' ? 'text-gray-500' : 'text-green-500'" class="text-xs">
{{ shipmentStatusLabel(row) }}
</text>
</view>
<text class="mt-1 block text-xs text-gray-500">
@@ -195,6 +200,7 @@ import { computed, getCurrentInstance, reactive, ref } from "vue";
import { onShow } from "@dcloudio/uni-app";
import PalletScanInput from "@/components/business/PalletScanInput.vue";
import TestBatchBanner from "@/components/business/TestBatchBanner.vue";
import ShipmentReceiptPanel from "@/components/business/ShipmentReceiptPanel.vue";
import {
addShipment,
confirmShipment,
@@ -229,7 +235,7 @@ const confirmState = reactive({ shipmentId: null, key: "" });
let listGeneration = 0;
let scanGeneration = 0;
const canPage = computed(() =>
const canShipment = computed(() =>
proxy.$auth.hasPermiOr([
"business:shipment:list",
"business:shipment:query",
@@ -238,6 +244,9 @@ const canPage = computed(() =>
"business:shipment:confirm",
]),
);
const canReceive = computed(() => proxy.$auth.hasPermi("business:shipment:receive"));
const canPage = computed(() => canShipment.value || canReceive.value);
const activeTab = ref(canShipment.value ? "shipment" : "receipt");
const canList = computed(() => proxy.$auth.hasPermi("business:shipment:list"));
const canDraft = computed(() =>
proxy.$auth.hasPermiAnd(["business:shipment:query", "business:shipment:add"]),
@@ -274,6 +283,11 @@ function errorMessage(error, fallback) {
return error?.response?.data?.msg || error?.message || fallback;
}
function shipmentStatusLabel(row) {
if (row.status === "DRAFT") return "草稿";
return { PENDING: "待收货", RECEIVED: "已收货", LEGACY: "历史未登记收货" }[row.receiptState] || "已确认";
}
function warehouseName(id) {
return warehouseOptions.value.find((item) => item.id === id)?.name || `仓库 #${id || "-"}`;
}
shierfeng-fastapi-app/src/pages/business/usage/index.vue
+506 -66
View File
@@ -5,7 +5,7 @@
<view>
<text class="block text-xl font-bold text-gray-800">客户现场使用</text>
<text class="mt-1 block text-xs text-gray-500">
扫描现场托盘，首次使用绑定产线并记录本次消耗包数
扫描现场托盘，确认入隧后记录实际使用包数，产线可选
</text>
</view>
<TestBatchBanner />
@@ -15,6 +15,25 @@
</view>
<template v-else>
<view v-if="pendingOperations.length || recoveryError || recoveryMessage" class="rounded-2xl bg-amber-50 p-4 shadow-sm">
<text class="block font-bold text-gray-800">提交结果核对</text>
<text v-if="pendingOperations.length" class="mt-2 block text-xs text-gray-600">
以下操作结果尚未确认。恢复重试会核对原操作，请先确认结果再录入下一次使用。
</text>
<view v-for="item in pendingOperations" :key="item.payload.idempotencyKey" class="mt-3">
<text class="block text-sm text-gray-700">
{{ item.palletCode }} · {{ item.tunnelName }} · {{ item.action === "usage" ? `使用 ${item.payload.usedPackages} 包` : "托盘入隧" }}
</text>
<button size="mini" class="mt-2 text-blue-600" :disabled="!canOperate || operationPending" @click="retryPendingOperation(item)">
恢复重试 / 核对
</button>
<button size="mini" class="mt-2 text-gray-600" :disabled="operationPending" @click="releasePendingOperation(item)">
已人工核对，解除待确认
</button>
</view>
<text v-if="recoveryError" class="mt-2 block text-xs text-red-500">{{ recoveryError }}</text>
<text v-if="recoveryMessage" class="mt-2 block text-xs text-gray-700">{{ recoveryMessage }}</text>
</view>
<view class="rounded-2xl bg-white p-4 shadow-sm">
<view class="mb-3 flex items-center justify-between">
<text class="font-bold text-gray-800">扫描待使用托盘</text>
@@ -44,31 +63,81 @@
<text class="mt-1 block text-xs text-gray-500">
{{ scannedPallet.strainName || scannedPallet.strainCode || "未提供菌种" }} · 批次 {{ scannedPallet.batchNo || "—" }}
</text>
<text class="mt-1 block text-xs text-gray-500">
生产日期：{{ scannedPallet.productionDate || "未登记" }} · 有效期至：{{ scannedPallet.expiryDate || "未登记" }}
</text>
<text class="mt-1 block text-xs text-gray-500">
当前剩余：{{ scannedPallet.remainingPackages }} 包 · 现场 #{{ scannedPallet.siteId }}
</text>
</view>
<view v-if="scannedPallet" class="mt-3 rounded-xl bg-blue-50 p-3">
<view class="flex items-center justify-between">
<text class="text-sm text-gray-700">先到先用建议</text>
<button size="mini" class="text-xs text-blue-600" :disabled="fifoLoading || operationPending" @click="loadFifoRecommendation">
刷新建议
</button>
</view>
<text class="mt-2 block text-xs text-gray-600">{{ fifoLoading ? "建议加载中，提交时由服务端复核" : fifoMessage }}</text>
</view>
</view>
<view class="rounded-2xl bg-white p-4 shadow-sm">
<text class="mb-3 block font-bold text-gray-800">托盘入隧</text>
<view v-if="tunnelLocked" class="rounded-xl bg-gray-100 px-3 py-3 text-sm text-gray-600">
{{ selectedTunnelName }}（已入隧，不可切换）
</view>
<picker
v-else
:range="tunnelPickerOptions"
range-key="label"
:value="tunnelIndex"
:disabled="!canOperate || operationPending || optionLoading || !scannedPallet"
@change="handleTunnelChange"
>
<view class="rounded-xl bg-gray-50 px-3 py-3 text-sm text-gray-700">
{{ selectedTunnelName || "请选择使用隧道" }}
</view>
</picker>
<text v-if="scannedPallet && !tunnelLocked" class="mt-2 block text-xs text-gray-500">
先确认入隧，再提交使用包数。
</text>
<view class="mt-3">
<text class="mb-2 block text-xs text-gray-500">跳过先到托盘原因（{{ fifoRequiresSkipReason ? "必填" : "可选" }}）</text>
<textarea v-model="form.fifoSkipReason" class="w-full rounded-xl bg-gray-50 px-3 py-3 text-sm text-gray-700"
:maxlength="500" placeholder="跳过先到托盘时请填写原因，最多500字"
:disabled="operationPending || !scannedPallet" @input="markPayloadChanged" />
<text class="mt-1 block text-xs text-gray-400">最多500字；提交时由服务端复核先到先用要求。</text>
</view>
<button
v-if="!tunnelLocked"
class="mt-4 w-full rounded-xl bg-purple-500 py-3 text-sm text-white active:opacity-80 disabled:bg-gray-300"
:disabled="!canOperate || operationPending || scanLoading || optionLoading || !scannedPallet || !form.tunnelId"
@click="enterTunnel"
>
{{ entryLoading ? "入隧中" : "确认入隧" }}
</button>
</view>
<view class="rounded-2xl bg-white p-4 shadow-sm">
<text class="mb-3 block font-bold text-gray-800">使用信息</text>
<view class="mb-3">
<text class="mb-2 block text-xs text-gray-500">使用产线</text>
<text class="mb-2 block text-xs text-gray-500">使用产线（可选）</text>
<view v-if="lineLocked" class="rounded-xl bg-gray-100 px-3 py-3 text-sm text-gray-600">
{{ selectedLineName }}（已由托盘绑定）
</view>
<picker
v-else
:range="lineOptions"
:range="linePickerOptions"
range-key="name"
:value="lineIndex"
:disabled="operationPending || optionLoading || !scannedPallet"
:disabled="operationPending || lineOptionLoading || !scannedPallet"
@change="handleLineChange"
>
<view class="rounded-xl bg-gray-50 px-3 py-3 text-sm text-gray-700">
{{ selectedLineName || "请选择现场产线" }}
{{ selectedLineName || "不选择产线" }}
</view>
</picker>
<text v-if="lineOptionError" class="mt-2 block text-xs text-amber-600">{{ lineOptionError }}</text>
</view>
<view>
<text class="mb-2 block text-xs text-gray-500">本次使用包数</text>
@@ -93,7 +162,7 @@
</view>
<button
class="mt-4 w-full rounded-xl bg-purple-500 py-3 text-sm text-white active:opacity-80 disabled:bg-gray-300"
:disabled="!canOperate || operationPending || scanLoading || optionLoading || !scannedPallet || !!usageResult"
:disabled="!canOperate || operationPending || scanLoading || optionLoading || !scannedPallet || !tunnelLocked || !form.tunnelId || !!usageResult"
@click="submitUsage"
>
{{ submitLoading ? "提交中" : "确认使用" }}
@@ -120,11 +189,15 @@
>
<text class="block font-medium text-gray-700">{{ row.usageNo || `#${row.usageId}` }}</text>
<text class="mt-1 block text-xs text-gray-500">
托盘 #{{ row.palletId }} · 产线 #{{ row.lineId }} · 使用 {{ row.usedPackages }} 包
托盘 #{{ row.palletId }} · {{ row.tunnelName || row.tunnelCode || (row.tunnelId ? `隧道 #${row.tunnelId}` : "未登记隧道") }} · 使用 {{ row.usedPackages }} 包
</text>
<text v-if="row.lineId" class="mt-1 block text-xs text-gray-500">
产线 #{{ row.lineId }}
</text>
<text class="mt-1 block text-xs text-gray-400">
剩余 {{ row.remainingPackagesAfter }} 包 · {{ row.occurredAt || "—" }}
</text>
<text class="mt-1 block text-xs text-gray-500">跳过先到托盘原因：{{ row.fifoSkipReason || "—" }}</text>
</view>
</view>
</template>
@@ -135,35 +208,54 @@
<script setup>
import { computed, getCurrentInstance, reactive, ref } from "vue";
import { onShow } from "@dcloudio/uni-app";
import { onHide, onShow, onUnload } from "@dcloudio/uni-app";
import PalletScanInput from "@/components/business/PalletScanInput.vue";
import TestBatchBanner from "@/components/business/TestBatchBanner.vue";
import {
addUsage,
enterUsageTunnel,
getUsageFifoRecommendation,
getUsageLineOptions,
getUsageTunnelOptions,
listUsage,
scanUsagePallet,
} from "@/api/business/usage";
import { createIdempotencyKey } from "@/utils/palletScan";
import config from "@/config";
import constant from "@/utils/constant";
import storage from "@/utils/storage";
const { proxy } = getCurrentInstance();
const usageList = ref([]);
const lineOptions = ref([]);
const tunnelOptions = ref([]);
const scannedPallet = ref(null);
const usageResult = ref(null);
const lineLocked = ref(false);
const tunnelLocked = ref(false);
const loading = ref(false);
const optionLoading = ref(false);
const lineOptionLoading = ref(false);
const lineOptionError = ref("");
const fifoLoading = ref(false);
const fifoMessage = ref("");
const fifoRequiresSkipReason = ref(false);
const scanLoading = ref(false);
const submitLoading = ref(false);
const entryLoading = ref(false);
const listError = ref("");
const operationError = ref("");
const submitError = ref("");
const idempotencyKey = ref("");
const form = reactive({ qrToken: "", lineId: null, usedPackages: "" });
const pendingOperations = ref([]);
const recoveryStorageKey = ref("");
const recoveryLoading = ref(false);
const recoveryError = ref("");
const recoveryMessage = ref("");
const form = reactive({ qrToken: "", tunnelId: null, lineId: null, usedPackages: "", fifoSkipReason: "" });
let listGeneration = 0;
let scanGeneration = 0;
let optionGeneration = 0;
let fifoGeneration = 0;
let operationSession = 0;
const canPage = computed(() =>
@@ -177,19 +269,225 @@ const canList = computed(() => proxy.$auth.hasPermi("business:usage:list"));
const canOperate = computed(() =>
proxy.$auth.hasPermiAnd(["business:usage:query", "business:usage:add"]),
);
const operationPending = computed(() => submitLoading.value);
const operationPending = computed(() => submitLoading.value || entryLoading.value || recoveryLoading.value);
const linePickerOptions = computed(() => [
{ id: null, name: "不选择产线" },
...lineOptions.value,
]);
const lineIndex = computed(() => {
const index = lineOptions.value.findIndex((item) => item.id === form.lineId);
const index = linePickerOptions.value.findIndex((item) => item.id === form.lineId);
return index >= 0 ? index : 0;
});
const selectedLineName = computed(
() => lineOptions.value.find((item) => item.id === form.lineId)?.name || "",
);
const tunnelPickerOptions = computed(() => tunnelOptions.value.map((item) => ({
...item,
label: formatTunnelName(item),
})));
const tunnelIndex = computed(() => {
const index = tunnelOptions.value.findIndex((item) => item.id === form.tunnelId);
return index >= 0 ? index : 0;
});
const selectedTunnelName = computed(() => {
const option = tunnelOptions.value.find((item) => item.id === form.tunnelId);
if (option) return formatTunnelName(option);
if (!form.tunnelId) return "";
return formatTunnelName({
id: form.tunnelId,
name: scannedPallet.value?.tunnelName,
code: scannedPallet.value?.tunnelCode,
});
});
function formatTunnelName(option) {
return [option.name, option.code].filter(Boolean).join(" · ") || `隧道 #${option.id}`;
}
function errorMessage(error, fallback) {
return error?.response?.data?.msg || error?.message || fallback;
}
function currentRecoveryStorageKey() {
const userId = storage.get(constant.id);
if (!userId) throw new Error("账号信息未就绪，无法保存操作恢复记录");
return `business-usage-pending-v1:${JSON.stringify([config.baseUrl, userId, storage.get(constant.testBatchId) || "formal"])}`;
}
function loadPendingOperations() {
try {
const key = currentRecoveryStorageKey();
const records = uni.getStorageSync(key) || [];
if (!Array.isArray(records) || records.some((item) =>
!["entry", "usage"].includes(item?.action) || !item.payload?.qrToken || !item.payload?.idempotencyKey
)) throw new Error("本机操作恢复记录异常，请先联系管理员核对");
recoveryStorageKey.value = key;
pendingOperations.value = records;
recoveryError.value = "";
return true;
} catch (error) {
pendingOperations.value = [];
recoveryError.value = errorMessage(error, "本机操作恢复记录读取失败，请先核对");
return false;
}
}
function savePendingOperations(records) {
// 先持久化，再发送命令；页面隐藏、销毁或响应丢失都不能丢掉重试身份。
uni.setStorageSync(recoveryStorageKey.value, records);
pendingOperations.value = records;
}
function pendingForPallet() {
return pendingOperations.value.find((item) => item.palletId === scannedPallet.value?.palletId || item.payload.qrToken === form.qrToken);
}
function operationSignature(action, payload) {
return JSON.stringify([action, payload.qrToken, payload.tunnelId, payload.lineId ?? null, payload.usedPackages ?? null, payload.fifoSkipReason || ""]);
}
function prepareOperation(action, payload) {
if (!loadPendingOperations()) throw new Error(recoveryError.value);
const pending = pendingForPallet();
if (pending) {
if (operationSignature(pending.action, pending.payload) !== operationSignature(action, payload)) {
throw new Error("该托盘有结果未确认的操作，请先恢复重试并核对原操作");
}
return pending;
}
const operation = {
action,
palletId: scannedPallet.value.palletId,
palletCode: scannedPallet.value.palletCode,
tunnelName: selectedTunnelName.value,
payload: { ...payload, idempotencyKey: createIdempotencyKey() },
};
savePendingOperations([...pendingOperations.value, operation]);
return operation;
}
function completeOperation(operation, response) {
const result = response?.data;
// 先核实完整业务结果，再解除原凭据；空响应和不完整响应仍属于结果未知。
const confirmed = result && (operation.action === "usage"
? Number.isInteger(result.usageId) && result.usageId > 0 &&
Number.isInteger(result.remainingPackages) && result.remainingPackages >= 0 &&
typeof result.flowState === "string" && result.flowState.trim()
: result.palletId === operation.palletId && result.tunnelId === operation.payload.tunnelId &&
typeof result.traceNo === "string" && result.traceNo.trim());
if (!confirmed) throw new Error("服务端确认结果不完整，原操作凭据已保留");
if (!loadPendingOperations()) throw new Error(recoveryError.value);
savePendingOperations(pendingOperations.value.filter((item) => item.payload.idempotencyKey !== operation.payload.idempotencyKey));
return result;
}
function isCurrentOperation(session, scopeKey) {
try {
return session === operationSession && scopeKey === recoveryStorageKey.value && scopeKey === currentRecoveryStorageKey();
} catch {
return false;
}
}
function validatedFifoSkipReason() {
const reason = form.fifoSkipReason.trim();
if (Array.from(reason).length > 500) throw new Error("跳过先到托盘原因最多500字");
if (fifoRequiresSkipReason.value && !reason) throw new Error("请填写跳过先到托盘原因");
return reason;
}
function handleFifoRejection(error, operation) {
// 与 request 的 getResponseBody 一致：兼容 uni 响应外层及直接业务 body。
const response = error?.response;
const body = response?.data && typeof response.data === "object" ? response.data : response;
if (!operation || body?.code !== 500 || body.data !== "FIFO_SKIP_REASON_REQUIRED") return false;
try {
if (!loadPendingOperations()) return true;
const current = pendingOperations.value.find(item => item.payload.idempotencyKey === operation.payload.idempotencyKey);
if (!current || JSON.stringify(current) !== JSON.stringify(operation)) {
recoveryError.value = "本机待确认记录已变化，请重新核对后操作";
return true;
}
// 仅此明确业务错误保证事务回滚，可解除对应原凭据并允许修改原因。
savePendingOperations(pendingOperations.value.filter(item => item.payload.idempotencyKey !== operation.payload.idempotencyKey));
} catch (storageError) {
recoveryError.value = `${errorMessage(storageError, "本机待确认记录清理失败")}；原凭据已保留，请恢复重试`;
return true;
}
if (scannedPallet.value?.palletId === operation.palletId && form.qrToken === operation.payload.qrToken) {
fifoRequiresSkipReason.value = true;
loadFifoRecommendation();
} else {
recoveryLoading.value = false;
handleUsageScan(operation.payload.qrToken, operation);
}
operationError.value = "请补充跳过先到托盘原因后重新提交，本次操作未生效";
submitError.value = operationError.value;
recoveryMessage.value = operationError.value;
return true;
}
async function releasePendingOperation(item) {
if (operationPending.value) return;
const session = operationSession;
const scopeKey = recoveryStorageKey.value;
if (!loadPendingOperations() || recoveryStorageKey.value !== scopeKey) return;
const operation = pendingOperations.value.find((record) => record.payload.idempotencyKey === item.payload.idempotencyKey);
if (!operation) return;
recoveryLoading.value = true;
try {
const confirmed = await new Promise((resolve, reject) => {
uni.showModal({
title: "解除本机待确认记录",
content: `请先核对使用记录和当前库存，确认 ${operation.palletCode} 的原操作结果。此操作仅移除对应本机待确认记录，不撤销或确认服务端业务。若原操作已成功，再次提交可能重复扣减库存。确认已人工核对并解除？`,
cancelText: "取消",
confirmText: "确认解除",
success: (result) => resolve(Boolean(result.confirm)),
fail: reject,
});
});
// 弹窗期间可能换账号、批次或离页；不能把旧确认应用到新的范围。
if (!confirmed || !isCurrentOperation(session, scopeKey) || currentRecoveryStorageKey() !== scopeKey) return;
if (!loadPendingOperations()) return;
savePendingOperations(pendingOperations.value.filter((record) => record.payload.idempotencyKey !== operation.payload.idempotencyKey));
if (scannedPallet.value?.palletId === operation.palletId || form.qrToken === operation.payload.qrToken) {
resetUsageOperation();
}
recoveryMessage.value = `${operation.palletCode} 仅已解除本机待确认记录，不代表原操作成功。请依据人工核对结果重新扫码后继续。`;
} catch (error) {
if (!isCurrentOperation(session, scopeKey)) return;
recoveryError.value = errorMessage(error, "解除本机待确认失败，原记录仍保留");
} finally {
if (isCurrentOperation(session, scopeKey)) recoveryLoading.value = false;
}
}
async function retryPendingOperation(item) {
if (!canOperate.value || operationPending.value || !loadPendingOperations()) return;
const operation = pendingOperations.value.find((record) => record.payload.idempotencyKey === item.payload.idempotencyKey);
if (!operation) return;
resetUsageOperation();
const session = operationSession;
const scopeKey = recoveryStorageKey.value;
recoveryLoading.value = true;
recoveryMessage.value = "";
try {
const response = await (operation.action === "usage" ? addUsage : enterUsageTunnel)({ ...operation.payload });
if (!isCurrentOperation(session, scopeKey)) return;
const result = completeOperation(operation, response);
recoveryMessage.value = operation.action === "usage"
? `${operation.palletCode} 原使用已确认，剩余 ${result.remainingPackages} 包。请重新扫码后继续。`
: `${operation.palletCode} 原入隧已确认。请重新扫码后继续。`;
loadUsageList();
} catch (error) {
if (!isCurrentOperation(session, scopeKey)) return;
if (handleFifoRejection(error, operation)) return;
recoveryError.value = `${errorMessage(error, "原操作核对失败")}；原操作已保留，请重试或联系管理员核对`;
} finally {
if (isCurrentOperation(session, scopeKey)) recoveryLoading.value = false;
}
}
function loadUsageList() {
if (!canList.value) return;
const generation = ++listGeneration;
@@ -214,56 +512,104 @@ function resetUsageOperation() {
operationSession += 1;
scanGeneration += 1;
optionGeneration += 1;
fifoGeneration += 1;
scannedPallet.value = null;
usageResult.value = null;
lineOptions.value = [];
tunnelOptions.value = [];
lineLocked.value = false;
idempotencyKey.value = "";
tunnelLocked.value = false;
form.qrToken = "";
form.tunnelId = null;
form.lineId = null;
form.usedPackages = "";
form.fifoSkipReason = "";
operationError.value = "";
submitError.value = "";
scanLoading.value = false;
optionLoading.value = false;
lineOptionLoading.value = false;
lineOptionError.value = "";
fifoLoading.value = false;
fifoMessage.value = "";
fifoRequiresSkipReason.value = false;
submitLoading.value = false;
entryLoading.value = false;
recoveryLoading.value = false;
}
function loadLineOptions(siteId, session, scanRequestGeneration) {
function loadUsageOptions(pallet, session, scanRequestGeneration) {
const generation = ++optionGeneration;
const isCurrent = () => generation === optionGeneration &&
session === operationSession && scanRequestGeneration === scanGeneration;
optionLoading.value = true;
getUsageLineOptions(siteId)
.then((response) => {
if (
generation !== optionGeneration ||
session !== operationSession ||
scanRequestGeneration !== scanGeneration
) {
return;
lineOptionLoading.value = true;
const lineRequest = pallet.currentLineId == null
? getUsageLineOptions(pallet.siteId)
: Promise.resolve({ data: lineOptions.value });
getUsageTunnelOptions(pallet.siteId)
.then((tunnels) => {
if (!isCurrent()) return;
tunnelOptions.value = Array.isArray(tunnels.data) ? tunnels.data : [];
if (!tunnelLocked.value && !tunnelOptions.value.length) {
operationError.value = "该现场暂无可用隧道";
}
lineOptions.value = Array.isArray(response.data) ? response.data : [];
if (!lineOptions.value.length) operationError.value = "该现场暂无可用产线";
})
.catch((error) => {
if (generation !== optionGeneration || session !== operationSession) return;
lineOptions.value = [];
operationError.value = errorMessage(error, "产线选项加载失败，请稍后重新扫码");
if (!isCurrent()) return;
operationError.value = errorMessage(error, "隧道选项加载失败，请稍后重新扫码");
})
.finally(() => {
if (generation === optionGeneration && session === operationSession) {
optionLoading.value = false;
}
if (isCurrent()) optionLoading.value = false;
});
lineRequest
.then((lines) => {
if (isCurrent()) lineOptions.value = Array.isArray(lines.data) ? lines.data : [];
})
.catch((error) => {
if (!isCurrent()) return;
lineOptions.value = [];
lineOptionError.value = `${errorMessage(error, "产线选项加载失败")}；可不选产线继续操作`;
})
.finally(() => {
if (isCurrent()) lineOptionLoading.value = false;
});
}
function handleUsageScan(qrToken) {
async function loadFifoRecommendation() {
if (!scannedPallet.value || !form.qrToken) return;
const generation = ++fifoGeneration;
const session = operationSession;
const scopeKey = recoveryStorageKey.value;
const { qrToken, tunnelId } = form;
const isCurrent = () => generation === fifoGeneration && isCurrentOperation(session, scopeKey) &&
qrToken === form.qrToken && tunnelId === form.tunnelId;
fifoLoading.value = true;
fifoMessage.value = "";
try {
const response = await getUsageFifoRecommendation(qrToken, tunnelId);
if (!isCurrent()) return;
fifoMessage.value = response.data?.message || "当前暂无先到先用建议";
fifoRequiresSkipReason.value = response.data?.requiresSkipReason === true;
} catch {
if (!isCurrent()) return;
fifoMessage.value = "先到先用建议暂不可用，请人工核对；提交时由服务端复核，跳过先到托盘可能需要填写原因";
} finally {
if (isCurrent()) fifoLoading.value = false;
}
}
function handleUsageScan(qrToken, rejectedOperation = null) {
if (operationPending.value || scanLoading.value || optionLoading.value) return;
resetUsageOperation();
if (!loadPendingOperations()) return;
const session = operationSession;
const scopeKey = recoveryStorageKey.value;
const generation = ++scanGeneration;
scanLoading.value = true;
scanUsagePallet(qrToken)
.then((response) => {
if (generation !== scanGeneration || session !== operationSession) return;
if (generation !== scanGeneration || !isCurrentOperation(session, scopeKey)) return;
const pallet = response.data;
if (
!["AT_SITE_UNUSED", "AT_SITE_PARTIAL"].includes(pallet?.flowState) ||
@@ -277,13 +623,26 @@ function handleUsageScan(qrToken) {
palletCode: pallet.palletCode || `#${pallet.palletId}`,
siteId: pallet.siteId,
currentLineId: pallet.currentLineId,
tunnelId: pallet.tunnelId,
tunnelName: pallet.tunnelName,
tunnelCode: pallet.tunnelCode,
strainCode: pallet.strainCode,
strainName: pallet.strainName,
batchNo: pallet.batchNo,
productionDate: pallet.productionDate,
expiryDate: pallet.expiryDate,
remainingPackages: pallet.remainingPackages,
flowState: pallet.flowState,
};
form.qrToken = qrToken;
form.qrToken = pallet.qrToken || qrToken;
form.tunnelId = pallet.tunnelId ?? null;
tunnelLocked.value = pallet.tunnelId != null;
if (rejectedOperation) {
form.tunnelId = pallet.tunnelId ?? rejectedOperation.payload.tunnelId;
form.usedPackages = rejectedOperation.payload.usedPackages ?? "";
form.fifoSkipReason = rejectedOperation.payload.fifoSkipReason || "";
fifoRequiresSkipReason.value = true;
}
if (pallet.currentLineId != null) {
lineLocked.value = true;
form.lineId = pallet.currentLineId;
@@ -292,17 +651,18 @@ function handleUsageScan(qrToken) {
];
} else {
lineLocked.value = false;
form.lineId = null;
loadLineOptions(pallet.siteId, session, generation);
form.lineId = rejectedOperation?.payload.lineId ?? null;
}
loadUsageOptions(pallet, session, generation);
loadFifoRecommendation();
})
.catch((error) => {
if (generation === scanGeneration && session === operationSession) {
if (generation === scanGeneration && isCurrentOperation(session, scopeKey)) {
operationError.value = errorMessage(error, "托盘扫码校验失败，请检查后重试");
}
})
.finally(() => {
if (generation === scanGeneration && session === operationSession) {
if (generation === scanGeneration && isCurrentOperation(session, scopeKey)) {
scanLoading.value = false;
}
});
@@ -318,63 +678,143 @@ function handleScanDuplicate() {
}
function handleLineChange(event) {
if (lineLocked.value) return;
const option = lineOptions.value[Number(event.detail.value)];
form.lineId = option?.id || null;
if (lineLocked.value || operationPending.value) return;
const option = linePickerOptions.value[Number(event.detail.value)];
form.lineId = option?.id ?? null;
markPayloadChanged();
}
function handleTunnelChange(event) {
if (tunnelLocked.value || operationPending.value) return;
const option = tunnelOptions.value[Number(event.detail.value)];
if (form.tunnelId === (option?.id ?? null)) return;
form.tunnelId = option?.id ?? null;
markPayloadChanged();
fifoRequiresSkipReason.value = false;
loadFifoRecommendation();
}
function markPayloadChanged() {
if (!submitLoading.value) idempotencyKey.value = "";
if (operationPending.value) return;
submitError.value = "";
}
function ensureIdempotencyKey() {
if (!idempotencyKey.value) idempotencyKey.value = createIdempotencyKey();
return idempotencyKey.value;
async function enterTunnel() {
if (!canOperate.value || operationPending.value || scanLoading.value || optionLoading.value || tunnelLocked.value) return;
if (!scannedPallet.value || !form.qrToken || !form.tunnelId) {
operationError.value = "请先扫描托盘并选择隧道";
return;
}
let fifoSkipReason;
try {
fifoSkipReason = validatedFifoSkipReason();
} catch (error) {
operationError.value = error.message;
return;
}
const session = operationSession;
entryLoading.value = true;
operationError.value = "";
let scopeKey = recoveryStorageKey.value;
let operation;
try {
operation = prepareOperation("entry", {
qrToken: form.qrToken,
tunnelId: form.tunnelId,
...(fifoSkipReason ? { fifoSkipReason } : {}),
});
scopeKey = recoveryStorageKey.value;
const response = await enterUsageTunnel({ ...operation.payload });
if (!isCurrentOperation(session, scopeKey)) return;
const result = completeOperation(operation, response);
form.tunnelId = result.tunnelId;
scannedPallet.value.tunnelId = result.tunnelId;
tunnelLocked.value = true;
submitError.value = "";
proxy.$modal.msgSuccess(response.msg || "托盘入隧成功");
loadFifoRecommendation();
} catch (error) {
if (!isCurrentOperation(session, scopeKey)) return;
if (handleFifoRejection(error, operation)) return;
operationError.value = `${errorMessage(error, "托盘入隧失败")}；结果未确认时请恢复重试核对原操作`;
} finally {
if (isCurrentOperation(session, scopeKey)) entryLoading.value = false;
}
}
function submitUsage() {
if (!canOperate.value || operationPending.value || scanLoading.value || optionLoading.value) return;
async function submitUsage() {
if (!canOperate.value || operationPending.value || scanLoading.value || optionLoading.value || usageResult.value) return;
const usedPackages = Number(form.usedPackages);
if (!scannedPallet.value || !form.qrToken) {
submitError.value = "请先扫描待使用托盘";
return;
}
if (!form.lineId) {
submitError.value = "请选择使用产线";
if (!tunnelLocked.value || !form.tunnelId) {
submitError.value = "请先选择隧道并确认入隧";
return;
}
if (!Number.isInteger(usedPackages) || usedPackages <= 0) {
submitError.value = "使用包数必须为正整数";
return;
}
if (usedPackages > scannedPallet.value.remainingPackages) {
let fifoSkipReason;
try {
fifoSkipReason = validatedFifoSkipReason();
} catch (error) {
submitError.value = error.message;
return;
}
if (!loadPendingOperations()) {
submitError.value = recoveryError.value;
return;
}
// 服务端可能已扣减；已有原命令的重试由服务端幂等结果确认，不能用新余量拒绝。
if (usedPackages > scannedPallet.value.remainingPackages && !pendingForPallet()) {
submitError.value = "使用包数不能超过当前剩余包数";
return;
}
const session = operationSession;
submitLoading.value = true;
submitError.value = "";
addUsage({
qrToken: form.qrToken,
lineId: form.lineId,
usedPackages,
idempotencyKey: ensureIdempotencyKey(),
})
.then((response) => {
usageResult.value = response.data;
idempotencyKey.value = "";
proxy.$modal.msgSuccess(response.msg || "现场使用记录成功");
loadUsageList();
})
.catch((error) => {
submitError.value = `${errorMessage(error, "现场使用提交失败")}；直接重试将复用本次幂等键，修改输入后会生成新键`;
})
.finally(() => {
submitLoading.value = false;
const scopeKey = recoveryStorageKey.value;
let operation;
try {
operation = prepareOperation("usage", {
qrToken: form.qrToken,
tunnelId: form.tunnelId,
lineId: form.lineId,
usedPackages,
...(fifoSkipReason ? { fifoSkipReason } : {}),
});
const response = await addUsage({ ...operation.payload });
if (!isCurrentOperation(session, scopeKey)) return;
usageResult.value = completeOperation(operation, response);
proxy.$modal.msgSuccess(response.msg || "现场使用记录成功");
loadUsageList();
} catch (error) {
if (!isCurrentOperation(session, scopeKey)) return;
if (handleFifoRejection(error, operation)) return;
submitError.value = `${errorMessage(error, "现场使用提交失败")}；结果未确认时请恢复重试核对原操作`;
} finally {
if (isCurrentOperation(session, scopeKey)) submitLoading.value = false;
}
}
function leaveUsagePage() {
// uni-app 页面可能缓存；离开时使所有旧请求失效，不能回写下一次操作。
resetUsageOperation();
listGeneration += 1;
loading.value = false;
usageList.value = [];
listError.value = "";
recoveryMessage.value = "";
}
onHide(leaveUsagePage);
onUnload(leaveUsagePage);
onShow(() => {
loadPendingOperations();
loadUsageList();
});
loadPendingOperations();
</script>
shierfeng-fastapi-app/src/pages/index.vue
+1
View File
@@ -290,6 +290,7 @@ const INVENTORY_STATE_META = {
UNSTOCKED: { name: "未入库", tone: "slate" },
EMPTY_IN_WAREHOUSE: { name: "仓库空托盘", tone: "teal" },
FILLED_IN_WAREHOUSE: { name: "仓库有料", tone: "blue" },
IN_TRANSIT: { name: "在途待收货", tone: "blue" },
AT_SITE_UNUSED: { name: "现场未使用", tone: "purple" },
AT_SITE_PARTIAL: { name: "现场部分使用", tone: "orange" },
AT_SITE_EMPTY: { name: "现场空托盘", tone: "red" },
shierfeng-fastapi-app/src/pages/work/index.vue
+8 -2
View File
@@ -72,11 +72,17 @@ import { businessMenuEntries } from "@/config/businessMenu";
const { proxy } = getCurrentInstance();
const visibleBusinessEntries = computed(() =>
businessMenuEntries.filter((entry) => proxy.$auth.hasPermi(entry.permission)),
businessMenuEntries.filter(canOpenBusinessEntry),
);
function canOpenBusinessEntry(entry) {
return entry.permissions
? proxy.$auth.hasPermiOr(entry.permissions)
: proxy.$auth.hasPermi(entry.permission);
}
function handleBusinessEntry(entry) {
if (!proxy.$auth.hasPermi(entry.permission)) {
if (!canOpenBusinessEntry(entry)) {
proxy.$modal.msgError("当前账号没有该业务菜单权限");
return;
}
shierfeng-fastapi-app/src/utils/request.js
+6
View File
@@ -101,6 +101,7 @@ const request = async (config) => {
}
const body = getResponseBody(res);
const status = res.statusCode ?? res.status;
const code = body.code || 200;
const msg = errorCode[code] || body.msg || errorCode["default"];
if (code === 401) {
@@ -126,6 +127,11 @@ const request = async (config) => {
const error = new Error(msg);
error.response = res;
reject(error);
} else if (status != null && (status < 200 || status >= 300)) {
// uni.request 的 success 仅表示收到 HTTP 响应，不能据此确认业务成功。
const error = new Error(body.msg || `Request failed with status code ${status}`);
error.response = res;
reject(error);
} else {
resolve(body);
}
shierfeng-fastapi-app/tests/business-contract.test.mjs
+9 -7
View File
@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { test } from "node:test";
import JSON5 from "json5";
const appRoot = fileURLToPath(new URL("..", import.meta.url));
@@ -33,7 +34,7 @@ const apiContracts = {
"src/api/business/inbound.js": [
["listInbound", "'/business/inbound/list'", "get"],
["getInboundWarehouseOptions", "'/business/inbound/warehouse-options'", "get"],
["scanInboundPallet", "'/business/inbound/scan/' + qrToken", "get"],
["scanInboundPallet", "'/business/inbound/scan/' + encodeURIComponent(qrToken)", "get"],
["getInbound", "'/business/inbound/' + inboundId", "get"],
["addInbound", "'/business/inbound'", "post"],
["updateInbound", "'/business/inbound'", "put"],
@@ -42,7 +43,7 @@ const apiContracts = {
"src/api/business/filling.js": [
["listFilling", "'/business/filling/list'", "get"],
["getFillingStrainOptions", "'/business/filling/strain-options'", "get"],
["scanFillingPallet", "'/business/filling/scan/' + qrToken", "get"],
["scanFillingPallet", "'/business/filling/scan/' + encodeURIComponent(qrToken)", "get"],
["getFilling", "'/business/filling/' + fillingId", "get"],
["addFilling", "'/business/filling'", "post"],
],
@@ -50,7 +51,7 @@ const apiContracts = {
["listShipment", "'/business/shipment/list'", "get"],
["getShipmentWarehouseOptions", "'/business/shipment/warehouse-options'", "get"],
["getShipmentSiteOptions", "'/business/shipment/site-options'", "get"],
["scanShipmentPallet", "'/business/shipment/scan/' + qrToken", "get"],
["scanShipmentPallet", "'/business/shipment/scan/' + encodeURIComponent(qrToken)", "get"],
["getShipment", "'/business/shipment/' + shipmentId", "get"],
["addShipment", "'/business/shipment'", "post"],
["updateShipment", "'/business/shipment'", "put"],
@@ -59,14 +60,14 @@ const apiContracts = {
"src/api/business/usage.js": [
["listUsage", "'/business/usage/list'", "get"],
["getUsageLineOptions", "'/business/usage/line-options'", "get"],
["scanUsagePallet", "'/business/usage/scan/' + qrToken", "get"],
["scanUsagePallet", "'/business/usage/scan/' + encodeURIComponent(qrToken)", "get"],
["getUsage", "'/business/usage/' + usageId", "get"],
["addUsage", "'/business/usage'", "post"],
],
"src/api/business/return.js": [
["listReturn", "'/business/return/list'", "get"],
["getReturnWarehouseOptions", "'/business/return/warehouse-options'", "get"],
["scanReturnPallet", "'/business/return/scan/' + qrToken", "get"],
["scanReturnPallet", "'/business/return/scan/' + encodeURIComponent(qrToken)", "get"],
["requestReturn", "'/business/return/request'", "post"],
["getReturn", "'/business/return/' + returnId", "get"],
["confirmReturn", "'/business/return/' + returnId + '/confirm'", "put"],
@@ -145,7 +146,8 @@ test("PalletScanInput 使用 HID 回车提交并由 loading 锁定输入", async
});
test("PDA 路由和工作台入口覆盖五类现场业务", async () => {
const pages = JSON.parse(
// uni-app 的 pages.json 允许开发模式注释，与构建端保持相同解析语义。
const pages = JSON5.parse(
await readFile(path.join(appRoot, "src/pages.json"), "utf8"),
);
const pagePaths = new Set(pages.pages.map((page) => page.path));
@@ -242,7 +244,7 @@ test("运营驾驶舱 API 对接现有扫码异常接口", async () => {
test("APP 页面标题与后端业务菜单名称一致", async () => {
const [pages, fillingSource] = await Promise.all([
JSON.parse(await readFile(path.join(appRoot, "src/pages.json"), "utf8")),
JSON5.parse(await readFile(path.join(appRoot, "src/pages.json"), "utf8")),
readFile(path.join(appRoot, "src/pages/business/filling/index.vue"), "utf8"),
]);
const fillingPage = pages.pages.find((page) => page.path === "pages/business/filling/index");
shierfeng-fastapi-app/tests/usage-behavior.test.mjs
+1109
View File
File diff suppressed because it is too large Load Diff
shierfeng-fastapi-backend/.env.dev
+8 -2
View File
@@ -140,9 +140,15 @@ LOG_WORKER_ID = 'auto'
# -------- 传输层加解密配置 --------
# 是否启用传输层加解密
TRANSPORT_CRYPTO_ENABLED = false
#TRANSPORT_CRYPTO_ENABLED = false
## 传输层加解密模式：off=关闭，optional=明文/密文兼容，required=命中接口强制加密
#TRANSPORT_CRYPTO_MODE = 'off'
TRANSPORT_CRYPTO_ENABLED = true
# 传输层加解密模式：off=关闭，optional=明文/密文兼容，required=命中接口强制加密
TRANSPORT_CRYPTO_MODE = 'off'
TRANSPORT_CRYPTO_MODE = 'optional'
# 传输层加解密算法标识
TRANSPORT_CRYPTO_ALGORITHM = 'RSA_OAEP_AES_256_GCM'
# 当前启用的密钥版本标识
shierfeng-fastapi-backend/build/lib/cli/__init__.py
View File
shierfeng-fastapi-backend/build/lib/cli/bootstrap.py
-56
View File
@@ -1,56 +0,0 @@
import os
from cli.runtime import RUNTIME_ENVIRONMENT, RuntimeEnvironmentService
class AppBootstrapService:
"""
应用引导服务。
该服务负责解析应用原始入口路径、构建启动命令，并以 `exec`
方式将当前 CLI 进程切换为 FastAPI 应用入口进程。
"""
def __init__(self, *, runtime_environment: RuntimeEnvironmentService | None = None) -> None:
"""
初始化应用引导服务。
:param runtime_environment: 运行时环境服务
:return: None
"""
self.runtime_environment = runtime_environment or RUNTIME_ENVIRONMENT
def get_app_entry_path(self) -> str:
"""
获取应用启动入口路径。
:return: 应用启动入口绝对路径
"""
return os.path.join(self.runtime_environment.get_backend_dir(), 'app.py')
def build_app_run_command(self, env: str) -> list[str]:
"""
构建应用启动命令。
:param env: 运行环境
:return: 应用启动命令参数列表
"""
return [
self.runtime_environment.get_python_executable(),
self.get_app_entry_path(),
'--env',
env,
]
def exec_app_run_command(self, env: str) -> None:
"""
以应用原始入口进程启动当前 FastAPI 应用。
:param env: 运行环境
:return: None
"""
command = self.build_app_run_command(env)
os.execvp(command[0], command)
APP_BOOTSTRAP = AppBootstrapService()
shierfeng-fastapi-backend/build/lib/cli/completion/__init__.py
View File
shierfeng-fastapi-backend/build/lib/cli/completion/commands.py
-155
View File
@@ -1,155 +0,0 @@
from dataclasses import dataclass, field
from pathlib import Path
import typer
from cli.completion.controller import CompletionCommandController
from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY, CompletionProviderGateway
from cli.context import OutputOption
@dataclass(frozen=True)
class CompletionCommandRegistration:
"""
completion 子命令注册描述。
:param name: 子命令名称
:param help_text: 子命令帮助文本
"""
name: str
help_text: str
@dataclass
class CompletionSubcommandRegistrar:
"""
completion 子命令注册器。
该对象负责将 `show/install/doctor` 子命令挂载到 completion 应用，
将 Typer 命令声明细节从构建器主体中拆出。
:param completion_provider_gateway: completion 提供器对外网关
"""
completion_provider_gateway: CompletionProviderGateway = field(default_factory=lambda: COMPLETION_PROVIDER_GATEWAY)
@staticmethod
def build_registrations() -> tuple[CompletionCommandRegistration, ...]:
"""
返回 completion 子命令注册描述列表。
:return: 子命令注册描述元组
"""
return (
CompletionCommandRegistration(name='show', help_text='输出指定 shell 的 completion 脚本'),
CompletionCommandRegistration(name='install', help_text='安装指定 shell 的 completion 脚本'),
CompletionCommandRegistration(name='doctor', help_text='检查当前 completion 配置状态'),
)
def register(self, app: typer.Typer, *, controller: CompletionCommandController) -> None:
"""
向 completion 应用注册全部子命令。
:param app: completion 子应用
:param controller: completion 命令控制器
:return: None
"""
registrations = {registration.name: registration for registration in self.build_registrations()}
@app.command(registrations['show'].name, help=registrations['show'].help_text)
def show(
shell: str = typer.Argument(
...,
help='shell 名称，如 bash、zsh、fish',
autocompletion=self.completion_provider_gateway.complete_shell_names,
),
) -> None:
"""
输出指定 shell 的 completion 脚本。
:param shell: shell 名称
:return: None
"""
controller.show(shell)
@app.command(registrations['install'].name, help=registrations['install'].help_text)
def install(
shell: str | None = typer.Option(
None,
'--shell',
help='shell 名称，默认自动识别当前 shell',
autocompletion=self.completion_provider_gateway.complete_shell_names,
),
output: OutputOption = 'text',
target_file: Path | None = typer.Option(None, '--target-file', help='completion 脚本目标文件路径'),
activate: bool = typer.Option(False, '--activate', help='将激活命令写入 shell rc 文件'),
rc_file: Path | None = typer.Option(None, '--rc-file', help='自定义 shell rc 文件路径'),
force: bool = typer.Option(False, '--force', help='覆盖已存在且内容不同的目标文件'),
) -> None:
"""
安装指定 shell 的 completion 脚本。
:param shell: shell 名称，默认自动识别当前 shell
:param output: 输出格式
:param target_file: completion 脚本目标文件路径
:param activate: 是否写入 shell rc 文件激活命令
:param rc_file: 自定义 shell rc 文件路径
:param force: 是否强制覆盖已存在文件
:return: None
"""
controller.install(
output,
shell=shell,
target_file=target_file,
activate=activate,
rc_file=rc_file,
force=force,
)
@app.command(registrations['doctor'].name, help=registrations['doctor'].help_text)
def doctor(
output: OutputOption = 'text',
) -> None:
"""
检查当前 completion 配置状态。
:param output: 输出格式
:return: None
"""
controller.doctor(output)
@dataclass
class CompletionCommandBuilder:
"""
completion 子应用构建器。
该构建器负责装配 `completion` 子应用，并将控制器实例和子命令注册
细节收口到类式对象协作中。
:param completion_subcommand_registrar: completion 子命令注册器
"""
completion_subcommand_registrar: CompletionSubcommandRegistrar = field(
default_factory=CompletionSubcommandRegistrar
)
def build(self, root_cli: typer.Typer) -> typer.Typer:
"""
构建 completion 命令组。
:param root_cli: 根 Typer 应用
:return: completion 子应用
"""
app = typer.Typer(
help='shell completion 相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
completion_command_controller = CompletionCommandController(root_cli)
self.completion_subcommand_registrar.register(app, controller=completion_command_controller)
return app
COMPLETION_COMMAND_BUILDER = CompletionCommandBuilder()
shierfeng-fastapi-backend/build/lib/cli/completion/controller.py
-116
View File
@@ -1,116 +0,0 @@
from pathlib import Path
import typer
from cli.completion.doctor import COMPLETION_DOCTOR, CompletionDoctorService
from cli.completion.installers import COMPLETION_INSTALLER, CompletionInstallerService
from cli.completion.presenter import CompletionCommandPresenter
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
class CompletionCommandController:
"""
completion 命令控制器。
该控制器负责组织 `completion` 命令组的上下文准备、payload 生成、
文本渲染与脚本输出收口。
:param root_cli: 根 Typer 应用
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: completion 命令文本渲染器
:param installer_service: completion 安装与脚本生成服务
:param doctor_service: completion 诊断服务
"""
def __init__(
self,
root_cli: typer.Typer,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: CompletionCommandPresenter | None = None,
installer_service: CompletionInstallerService | None = None,
doctor_service: CompletionDoctorService | None = None,
) -> None:
"""
初始化 completion 命令控制器。
:param root_cli: 根 Typer 应用
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: completion 命令文本渲染器
:param installer_service: completion 安装与脚本生成服务
:param doctor_service: completion 诊断服务
:return: None
"""
self.root_cli = root_cli
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or CompletionCommandPresenter()
self.installer_service = installer_service or COMPLETION_INSTALLER
self.doctor_service = doctor_service or COMPLETION_DOCTOR
def show(self, shell: str) -> None:
"""
输出指定 shell 的 completion 脚本。
:param shell: shell 名称
:return: None
"""
typer.echo(self.installer_service.render_completion_script(self.root_cli, shell), nl=False)
def install(
self,
output: str,
*,
shell: str | None,
target_file: Path | None,
activate: bool,
rc_file: Path | None,
force: bool,
) -> None:
"""
安装指定 shell 的 completion 脚本。
:param output: 输出格式
:param shell: shell 名称
:param target_file: completion 脚本目标文件路径
:param activate: 是否写入 shell rc 文件激活命令
:param rc_file: 自定义 shell rc 文件路径
:param force: 是否强制覆盖已存在文件
:return: None
"""
ctx = self.context_factory.build_readonly('dev', output)
payload = self.installer_service.install_completion_script(
self.root_cli,
shell,
target_file=target_file,
activate=activate,
rc_file=rc_file,
force=force,
)
self.execution_service.complete_payload_result(
ctx,
payload,
text_builder=self.presenter.build_completion_install_text,
)
def doctor(self, output: str) -> None:
"""
检查当前 completion 配置状态。
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly('dev', output)
payload = self.doctor_service.build_completion_doctor_payload()
self.execution_service.complete_payload_result(
ctx,
payload,
text_builder=self.presenter.build_completion_doctor_text,
)
shierfeng-fastapi-backend/build/lib/cli/completion/doctor.py
-95
View File
@@ -1,95 +0,0 @@
from pathlib import Path
from typing import Any
from cli.completion.installers import (
CLICK_COMPLETE_ENV_VAR,
COMPLETION_INSTALLER,
CompletionInstallerService,
)
from cli.metadata import (
COMPLETION_SHELL_SPEC_REGISTRY,
ENVIRONMENT_OPTION_SERVICE,
CompletionShellSpecRegistry,
EnvironmentOptionService,
)
class CompletionDoctorService:
"""
completion 诊断服务。
该服务负责汇总活跃 shell、目标脚本路径、rc 文件状态、推荐安装命令
与环境候选列表，生成 `completion doctor` 所需的结构化结果。
:param installer_service: completion 安装服务
:param shell_spec_registry: shell 元数据注册表
:param environment_option_service: 环境选项服务
"""
def __init__(
self,
*,
installer_service: CompletionInstallerService | None = None,
shell_spec_registry: CompletionShellSpecRegistry | None = None,
environment_option_service: EnvironmentOptionService | None = None,
) -> None:
"""
初始化 completion 诊断服务。
:param installer_service: completion 安装服务
:param shell_spec_registry: shell 元数据注册表
:param environment_option_service: 环境选项服务
:return: None
"""
self.installer_service = installer_service or COMPLETION_INSTALLER
self.shell_spec_registry = shell_spec_registry or COMPLETION_SHELL_SPEC_REGISTRY
self.environment_option_service = environment_option_service or ENVIRONMENT_OPTION_SERVICE
def build_completion_doctor_payload(self) -> dict[str, Any]:
"""
构建 completion 诊断结果。
:return: 诊断结果字典
"""
active_shell = self.installer_service.detect_active_shell()
shells: dict[str, dict[str, Any]] = {}
for shell_name, shell_spec in self.shell_spec_registry.specs.items():
target_file = self.installer_service.resolve_completion_target(shell_name)
rc_file = self.installer_service.resolve_completion_rc_file(shell_name)
source_command = None
if shell_spec.supported and shell_spec.generator in {'click', 'custom'}:
source_command = self.installer_service.build_source_command(target_file, shell_name)
recommended_install_command = f'shierfeng completion install --shell={shell_name}'
if shell_spec.supported and not shell_spec.auto_discovery:
recommended_install_command = f'{recommended_install_command} --activate'
shells[shell_name] = {
'supported': shell_spec.supported,
'detected': shell_name == active_shell,
'description': shell_spec.description,
'targetFile': str(target_file),
'targetFileExists': target_file.exists(),
'rcFile': str(rc_file) if rc_file is not None else None,
'rcFileExists': rc_file.exists() if rc_file is not None else None,
'autoDiscovery': shell_spec.auto_discovery,
'sourceCommand': source_command,
'recommendedInstallCommand': recommended_install_command,
}
recommended_shell = active_shell if self.shell_spec_registry.get_spec(active_shell) is not None else None
recommended_install_command = None
if recommended_shell is not None:
recommended_install_command = shells[recommended_shell]['recommendedInstallCommand']
return {
'ok': True,
'message': 'completion 诊断信息已生成',
'activeShell': active_shell or None,
'projectDir': str(Path.cwd().resolve()),
'envChoices': self.environment_option_service.discover_env_names(),
'completeEnvVar': CLICK_COMPLETE_ENV_VAR,
'recommendedInstallCommand': recommended_install_command,
'shells': shells,
}
COMPLETION_DOCTOR = CompletionDoctorService()
shierfeng-fastapi-backend/build/lib/cli/completion/installers.py
-465
View File
@@ -1,465 +0,0 @@
import io
import os
from contextlib import redirect_stderr
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import click
import typer
import typer.main
from click.shell_completion import BashComplete, FishComplete, ZshComplete
from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY, CompletionProviderGateway
from cli.completion.shells import PowerShellComplete, ensure_custom_completion_classes_registered
from cli.exit_codes import ARGUMENT_ERROR, RUNTIME_ERROR
from cli.metadata import COMPLETION_SHELL_SPEC_REGISTRY, CompletionShellSpec, CompletionShellSpecRegistry
CLICK_COMPLETE_ENV_VAR = '_SHIERFENG_COMPLETE'
class CompletionInstallerShellSupport:
"""
completion shell 差异支持对象。
该对象负责封装不同 shell 在脚本兼容处理和 source 命令构建上的差异，
供安装服务通过轻量 strategy 协作对象统一复用。
"""
@staticmethod
def keep_script_text(script_text: str) -> str:
"""
保持脚本文本原样返回。
:param script_text: 原始脚本文本
:return: 原样脚本文本
"""
return script_text
@staticmethod
def make_bash_completion_script_compatible(script_text: str) -> str:
"""
对 Click 生成的 Bash completion 脚本做旧版本兼容处理。
兼容目标主要包括 macOS 默认 Bash 3.2：
- `complete -o nosort` 在旧 Bash 上会在 `source` 阶段直接报错
- `compopt` 在旧 Bash 上可能不存在
:param script_text: Click 原始 Bash completion 脚本文本
:return: 兼容处理后的脚本文本
"""
compatible_lines: list[str] = []
for line in script_text.splitlines():
stripped_line = line.strip()
if stripped_line == 'compopt -o dirnames':
indent = line[: len(line) - len(line.lstrip(' '))]
compatible_lines.extend(
[
f'{indent}if command -v compopt >/dev/null 2>&1; then',
f'{indent} compopt -o dirnames',
f'{indent}fi',
]
)
continue
if stripped_line == 'compopt -o default':
indent = line[: len(line) - len(line.lstrip(' '))]
compatible_lines.extend(
[
f'{indent}if command -v compopt >/dev/null 2>&1; then',
f'{indent} compopt -o default',
f'{indent}fi',
]
)
continue
if stripped_line.startswith('complete -o nosort -F '):
compatibility_line = stripped_line.replace('complete -o nosort -F ', '', 1)
function_name, command_name = compatibility_line.split(' ', 1)
compatible_lines.extend(
[
f'if complete -o nosort -F {function_name} {command_name} 2>/dev/null; then',
' :',
'else',
f' complete -F {function_name} {command_name}',
'fi',
]
)
continue
compatible_lines.append(line)
return '\n'.join(compatible_lines) + '\n'
@staticmethod
def build_posix_source_command(target_file: Path) -> str:
"""
构建 POSIX shell 使用的 source 命令。
:param target_file: completion 脚本文件路径
:return: source 命令
"""
return f'source {target_file}'
@staticmethod
def build_fish_source_command(target_file: Path) -> str:
"""
构建 Fish shell 使用的 source 命令。
:param target_file: completion 脚本文件路径
:return: source 命令
"""
return f'status --is-interactive; and source {target_file}'
@staticmethod
def build_powershell_source_command(target_file: Path) -> str:
"""
构建 PowerShell 使用的 source 命令。
:param target_file: completion 脚本文件路径
:return: source 命令
"""
return f'. "{target_file}"'
@dataclass(frozen=True)
class CompletionShellRuntimePolicy:
"""
completion shell 运行时策略定义。
:param name: shell 名称
:param click_completion_class: Click completion 生成器类型
:param script_transformer: 脚本文本后处理函数
:param source_command_builder: 激活命令构建函数
"""
name: str
click_completion_class: type[Any]
script_transformer: Any
source_command_builder: Any
@dataclass(frozen=True)
class CompletionShellRuntimePolicyRegistry:
"""
completion shell 运行时策略注册表。
:param policies: 按 shell 名称索引的运行时策略映射
"""
policies: dict[str, CompletionShellRuntimePolicy]
def get(self, shell_name: str) -> CompletionShellRuntimePolicy | None:
"""
获取指定 shell 的运行时策略。
:param shell_name: shell 名称
:return: 运行时策略，不存在时返回 None
"""
return self.policies.get(shell_name)
DEFAULT_COMPLETION_SHELL_RUNTIME_POLICIES = CompletionShellRuntimePolicyRegistry(
policies={
'bash': CompletionShellRuntimePolicy(
name='bash',
click_completion_class=BashComplete,
script_transformer=CompletionInstallerShellSupport.make_bash_completion_script_compatible,
source_command_builder=CompletionInstallerShellSupport.build_posix_source_command,
),
'zsh': CompletionShellRuntimePolicy(
name='zsh',
click_completion_class=ZshComplete,
script_transformer=CompletionInstallerShellSupport.keep_script_text,
source_command_builder=CompletionInstallerShellSupport.build_posix_source_command,
),
'fish': CompletionShellRuntimePolicy(
name='fish',
click_completion_class=FishComplete,
script_transformer=CompletionInstallerShellSupport.keep_script_text,
source_command_builder=CompletionInstallerShellSupport.build_fish_source_command,
),
'powershell': CompletionShellRuntimePolicy(
name='powershell',
click_completion_class=PowerShellComplete,
script_transformer=CompletionInstallerShellSupport.keep_script_text,
source_command_builder=CompletionInstallerShellSupport.build_powershell_source_command,
),
}
)
class CompletionInstallerService:
"""
completion 安装与脚本生成服务。
该服务负责 shell 元数据解析、脚本生成、目标路径解析、激活命令构建、
rc 文件写入以及安装结果收口。
:param completion_provider_gateway: completion 提供器对外网关
:param shell_spec_registry: shell 元数据注册表
:param shell_runtime_policy_registry: shell 运行时策略注册表
"""
def __init__(
self,
*,
completion_provider_gateway: CompletionProviderGateway | None = None,
shell_spec_registry: CompletionShellSpecRegistry | None = None,
shell_runtime_policy_registry: CompletionShellRuntimePolicyRegistry | None = None,
) -> None:
"""
初始化 completion 安装服务。
:param completion_provider_gateway: completion 提供器对外网关
:param shell_spec_registry: shell 元数据注册表
:param shell_runtime_policy_registry: shell 运行时策略注册表
:return: None
"""
self.completion_provider_gateway = completion_provider_gateway or COMPLETION_PROVIDER_GATEWAY
self.shell_spec_registry = shell_spec_registry or COMPLETION_SHELL_SPEC_REGISTRY
self.shell_runtime_policy_registry = shell_runtime_policy_registry or DEFAULT_COMPLETION_SHELL_RUNTIME_POLICIES
ensure_custom_completion_classes_registered()
def resolve_completion_shell_spec(self, shell: str) -> CompletionShellSpec:
"""
获取指定 shell 的 completion 元数据。
:param shell: shell 名称
:return: shell 元数据
:raises typer.BadParameter: shell 不存在时抛出异常
"""
normalized_shell = shell.strip().lower()
shell_spec = self.shell_spec_registry.get_spec(normalized_shell)
if shell_spec is None:
supported_shells = ', '.join(self.completion_provider_gateway.list_completion_shells())
raise typer.BadParameter(f'不支持的 shell：{shell}，可选值为 {supported_shells}')
return shell_spec
def resolve_shell_runtime_policy(self, shell: str) -> CompletionShellRuntimePolicy:
"""
获取指定 shell 的运行时策略。
:param shell: shell 名称
:return: shell 运行时策略
:raises typer.BadParameter: 当前 shell 未实现运行时策略时抛出异常
"""
shell_spec = self.resolve_completion_shell_spec(shell)
runtime_policy = self.shell_runtime_policy_registry.get(shell_spec.name)
if runtime_policy is None:
raise typer.BadParameter(f'{shell_spec.name} completion 当前版本未实现')
return runtime_policy
@staticmethod
def build_completion_click_command(root_cli: typer.Typer) -> click.Command:
"""
将 Typer 根应用转换为 Click 命令对象，供 shell completion 生成使用。
:param root_cli: Typer 根应用
:return: Click 命令对象
"""
return typer.main.get_command(root_cli)
def render_completion_script(self, root_cli: typer.Typer, shell: str) -> str:
"""
生成指定 shell 的 completion 脚本文本。
:param root_cli: Typer 根应用
:param shell: shell 名称
:return: completion 脚本文本
:raises typer.BadParameter: 当前 shell 未实现脚本生成时抛出异常
"""
shell_spec = self.resolve_completion_shell_spec(shell)
if not shell_spec.supported or shell_spec.generator not in {'click', 'custom'}:
raise typer.BadParameter(f'{shell_spec.name} completion 当前版本未实现')
runtime_policy = self.resolve_shell_runtime_policy(shell_spec.name)
click_command = self.build_completion_click_command(root_cli)
stderr_buffer = io.StringIO()
with redirect_stderr(stderr_buffer):
script_text = runtime_policy.click_completion_class(
click_command,
{},
'shierfeng',
CLICK_COMPLETE_ENV_VAR,
).source()
return runtime_policy.script_transformer(script_text)
def resolve_completion_target(self, shell: str, target_file: Path | None = None) -> Path:
"""
解析 completion 脚本目标文件路径。
:param shell: shell 名称
:param target_file: 用户显式指定的目标文件
:return: 目标文件绝对路径
"""
if target_file is not None:
return target_file.expanduser().resolve()
shell_spec = self.resolve_completion_shell_spec(shell)
return (Path.home() / shell_spec.default_target).expanduser().resolve()
def resolve_completion_rc_file(self, shell: str, rc_file: Path | None = None) -> Path | None:
"""
解析 completion 激活所使用的 rc 文件路径。
:param shell: shell 名称
:param rc_file: 用户显式指定的 rc 文件
:return: rc 文件绝对路径，若当前 shell 无 rc 文件则返回 None
"""
if rc_file is not None:
return rc_file.expanduser().resolve()
shell_spec = self.resolve_completion_shell_spec(shell)
if shell_spec.default_rc_file is None:
return None
return (Path.home() / shell_spec.default_rc_file).expanduser().resolve()
def build_source_command(self, target_file: Path, shell: str) -> str:
"""
构建当前 shell 对应的激活命令。
:param target_file: completion 脚本文件路径
:param shell: shell 名称
:return: 激活命令文本
"""
runtime_policy = self.resolve_shell_runtime_policy(shell)
return runtime_policy.source_command_builder(target_file)
@staticmethod
def detect_active_shell() -> str:
"""
检测当前进程环境下的活跃 shell 名称。
:return: shell 名称，未知时返回空字符串
"""
shell_path = os.environ.get('SHELL', '').strip()
if not shell_path:
return ''
return Path(shell_path).name.lower()
def resolve_install_shell(self, shell: str | None) -> str:
"""
解析安装命令实际使用的 shell。
:param shell: 用户显式指定的 shell，允许为空
:return: 实际使用的 shell 名称
:raises typer.BadParameter: 无法推断或不支持时抛出异常
"""
if shell and shell.strip():
return self.resolve_completion_shell_spec(shell).name
active_shell = self.detect_active_shell()
if not active_shell:
raise typer.BadParameter('未检测到当前 shell，请显式传入 --shell')
shell_spec = self.shell_spec_registry.get_spec(active_shell)
if shell_spec is None:
supported_shells = ', '.join(self.completion_provider_gateway.list_completion_shells())
raise typer.BadParameter(
f'当前 shell `{active_shell}` 不在支持列表中，请显式传入 --shell，可选值为 {supported_shells}'
)
return shell_spec.name
@staticmethod
def append_activation_line(rc_file: Path, source_command: str) -> bool:
"""
将激活命令追加到 rc 文件，若已存在则不重复写入。
:param rc_file: rc 文件路径
:param source_command: 激活命令文本
:return: 本次是否发生写入
"""
existing_text = ''
if rc_file.exists():
existing_text = rc_file.read_text(encoding='utf-8')
if source_command in existing_text:
return False
rc_file.parent.mkdir(parents=True, exist_ok=True)
with rc_file.open('a', encoding='utf-8') as file_object:
if existing_text and not existing_text.endswith('\n'):
file_object.write('\n')
file_object.write(f'{source_command}\n')
return True
def install_completion_script(
self,
root_cli: typer.Typer,
shell: str | None,
*,
target_file: Path | None = None,
activate: bool = False,
rc_file: Path | None = None,
force: bool = False,
) -> dict[str, Any]:
"""
安装指定 shell 的 completion 脚本文件。
:param root_cli: Typer 根应用
:param shell: shell 名称
:param target_file: completion 脚本目标文件
:param activate: 是否写入 rc 文件激活命令
:param rc_file: 自定义 rc 文件路径
:param force: 目标文件已存在时是否强制覆盖
:return: 安装结果字典
"""
resolved_shell = self.resolve_install_shell(shell)
shell_spec = self.resolve_completion_shell_spec(resolved_shell)
if not shell_spec.supported:
return {
'ok': False,
'message': f'{shell_spec.name} completion 当前版本未实现',
'shell': shell_spec.name,
'exit_code': ARGUMENT_ERROR,
}
resolved_target_file = self.resolve_completion_target(shell_spec.name, target_file)
script_text = self.render_completion_script(root_cli, shell_spec.name)
existing_text = resolved_target_file.read_text(encoding='utf-8') if resolved_target_file.exists() else None
if existing_text is not None and existing_text != script_text and not force:
return {
'ok': False,
'message': '目标文件已存在且内容不同，请传入 --force 覆盖',
'shell': shell_spec.name,
'targetFile': str(resolved_target_file),
'exit_code': RUNTIME_ERROR,
}
resolved_target_file.parent.mkdir(parents=True, exist_ok=True)
resolved_target_file.write_text(script_text, encoding='utf-8')
source_command = self.build_source_command(resolved_target_file, shell_spec.name)
activated = shell_spec.auto_discovery
rc_file_path = self.resolve_completion_rc_file(shell_spec.name, rc_file)
rc_file_updated = False
activation_required = not shell_spec.auto_discovery
detected_shell = self.detect_active_shell() or None
if activate and rc_file_path is not None:
rc_file_updated = self.append_activation_line(rc_file_path, source_command)
activated = True
next_step = '当前 shell 会自动发现 completion 脚本，无需额外 source 命令'
if activation_required and not activate:
next_step = f'请执行 `{source_command}`，或重新运行并传入 --activate'
elif activation_required and activate:
next_step = '请重启当前 shell，或手动执行 rc 文件中的 source 命令使其立即生效'
return {
'ok': True,
'message': 'completion 脚本已安装',
'shell': shell_spec.name,
'detectedShell': detected_shell,
'targetFile': str(resolved_target_file),
'activated': activated,
'activateRequested': activate,
'rcFile': str(rc_file_path) if rc_file_path is not None else None,
'rcFileUpdated': rc_file_updated,
'sourceCommand': source_command,
'autoDiscovery': shell_spec.auto_discovery,
'activationRequired': activation_required,
'nextStep': next_step,
'completeEnvVar': CLICK_COMPLETE_ENV_VAR,
}
COMPLETION_INSTALLER = CompletionInstallerService()
shierfeng-fastapi-backend/build/lib/cli/completion/presenter.py
-83
View File
@@ -1,83 +0,0 @@
from typing import Any
class CompletionCommandPresenter:
"""
completion 命令文本渲染器。
该渲染器负责将 `completion` 命令组产生的结构化 payload 转换为稳定的文本摘要，
同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
"""
def build_completion_doctor_text(self, payload: dict[str, Any]) -> str:
"""
将 completion 诊断结果渲染为文本摘要。
:param payload: completion 诊断结果字典
:return: 文本摘要
"""
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'message: {payload.get("message", "-")}',
f'active_shell: {payload.get("activeShell") or "-"}',
f'project_dir: {payload.get("projectDir", "-")}',
f'complete_env_var: {payload.get("completeEnvVar", "-")}',
]
if payload.get('recommendedInstallCommand'):
lines.append(f'recommended_install_command: {payload.get("recommendedInstallCommand")}')
env_choices = payload.get('envChoices')
if isinstance(env_choices, list) and env_choices:
lines.append('env_choices:')
lines.extend(f' - {env_name}' for env_name in env_choices)
shells = payload.get('shells')
if isinstance(shells, dict) and shells:
lines.append('shells:')
for shell_name, shell_payload in shells.items():
if not isinstance(shell_payload, dict):
continue
lines.extend(
[
f' {shell_name}:',
f' supported: {str(shell_payload.get("supported", False)).lower()}',
f' detected: {str(shell_payload.get("detected", False)).lower()}',
f' target_file: {shell_payload.get("targetFile", "-")}',
f' target_file_exists: {str(shell_payload.get("targetFileExists", False)).lower()}',
f' rc_file: {shell_payload.get("rcFile", "-") or "-"}',
f' rc_file_exists: {str(shell_payload.get("rcFileExists", False)).lower()}',
f' auto_discovery: {str(shell_payload.get("autoDiscovery", False)).lower()}',
f' source_command: {shell_payload.get("sourceCommand", "-")}',
f' recommended_install_command: {shell_payload.get("recommendedInstallCommand", "-")}',
]
)
return '\n'.join(lines)
@staticmethod
def build_completion_install_text(payload: dict[str, Any]) -> str:
"""
将 completion 安装结果渲染为文本摘要。
:param payload: completion 安装结果字典
:return: 文本摘要
"""
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'message: {payload.get("message", "-")}',
f'shell: {payload.get("shell", "-")}',
]
field_label_mapping = {
'detectedShell': 'detected_shell',
'targetFile': 'target_file',
'activated': 'activated',
'activateRequested': 'activate_requested',
'rcFile': 'rc_file',
'rcFileUpdated': 'rc_file_updated',
'sourceCommand': 'source_command',
'autoDiscovery': 'auto_discovery',
'activationRequired': 'activation_required',
'nextStep': 'next_step',
'completeEnvVar': 'complete_env_var',
}
for field_name, field_label in field_label_mapping.items():
if field_name in payload:
lines.append(f'{field_label}: {payload.get(field_name)}')
return '\n'.join(lines)
shierfeng-fastapi-backend/build/lib/cli/completion/providers.py
-1022
View File
File diff suppressed because it is too large Load Diff
shierfeng-fastapi-backend/build/lib/cli/completion/shells.py
-113
View File
@@ -1,113 +0,0 @@
import os
from click.shell_completion import (
CompletionItem,
ShellComplete,
add_completion_class,
get_completion_class,
split_arg_string,
)
_SOURCE_POWERSHELL = """\
$%(complete_func)s = {
param($wordToComplete, $commandAst, $cursorPosition)
$previousCompWords = $env:COMP_WORDS
$previousCompCword = $env:COMP_CWORD
$previousCompleteInstruction = $env:%(complete_var)s
$commandLine = $commandAst.ToString()
if ($cursorPosition -lt $commandLine.Length) {
$commandLine = $commandLine.Substring(0, $cursorPosition)
}
$env:COMP_WORDS = $commandLine
$env:COMP_CWORD = $wordToComplete
$env:%(complete_var)s = "powershell_complete"
try {
%(prog_name)s | ForEach-Object {
$line = $_.ToString()
if ([string]::IsNullOrWhiteSpace($line)) {
return
}
$parts = $line -split "`t", 3
$completionValue = if ($parts.Length -ge 2) { $parts[1] } else { "" }
$completionHelp = if ($parts.Length -ge 3 -and $parts[2]) { $parts[2] } else { $completionValue }
[System.Management.Automation.CompletionResult]::new(
$completionValue,
$completionValue,
[System.Management.Automation.CompletionResultType]::ParameterValue,
$completionHelp
)
}
} finally {
if ($null -ne $previousCompWords) {
$env:COMP_WORDS = $previousCompWords
} else {
Remove-Item Env:\\COMP_WORDS -ErrorAction SilentlyContinue
}
if ($null -ne $previousCompCword) {
$env:COMP_CWORD = $previousCompCword
} else {
Remove-Item Env:\\COMP_CWORD -ErrorAction SilentlyContinue
}
if ($null -ne $previousCompleteInstruction) {
$env:%(complete_var)s = $previousCompleteInstruction
} else {
Remove-Item Env:\\%(complete_var)s -ErrorAction SilentlyContinue
}
}
}
Register-ArgumentCompleter -Native -CommandName %(prog_name)s -ScriptBlock $%(complete_func)s
"""
class PowerShellComplete(ShellComplete):
"""
PowerShell shell completion 支持。
基于 PowerShell `Register-ArgumentCompleter -Native` 协议，将当前
命令行和光标位置传回 Click completion 分发器，再把返回的候选项转换为
`CompletionResult` 对象。
"""
name = 'powershell'
source_template = _SOURCE_POWERSHELL
def get_completion_args(self) -> tuple[list[str], str]:
"""
从 PowerShell 注入的环境变量中恢复 CLI 上下文。
:return: 已解析的完整参数与当前不完整输入
"""
cwords = split_arg_string(os.environ.get('COMP_WORDS', ''))
incomplete = os.environ.get('COMP_CWORD', '')
if incomplete:
incomplete_parts = split_arg_string(incomplete)
incomplete = incomplete_parts[0] if incomplete_parts else incomplete
args = cwords[1:]
if incomplete and args and args[-1] == incomplete:
args.pop()
return args, incomplete
def format_completion(self, item: CompletionItem) -> str:
"""
将候选项格式化为 PowerShell 脚本可解析的文本行。
:param item: Click completion 候选项
:return: 格式化后的文本
"""
help_text = item.help or item.value
return f'{item.type}\t{item.value}\t{help_text}'
def ensure_custom_completion_classes_registered() -> None:
"""
确保自定义 shell completion 类已注册到 Click。
:return: None
"""
if get_completion_class(PowerShellComplete.name) is None:
add_completion_class(PowerShellComplete)
shierfeng-fastapi-backend/build/lib/cli/context.py
-74
View File
@@ -1,74 +0,0 @@
from dataclasses import dataclass
from typing import Annotated, Literal
import typer
from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY
@dataclass
class CliContext:
"""
CLI 运行上下文。
env: 当前命令使用的环境名称
output: 结果输出格式
operator: 操作者标识，后续用于审计
allow_prod: 是否显式允许生产环境执行危险命令
yes: 是否跳过二次确认
dry_run: 是否执行演练模式
"""
env: str = 'dev'
output: Literal['text', 'json'] = 'text'
operator: str | None = None
allow_prod: bool = False
yes: bool = False
dry_run: bool = False
class CliContextBuilder:
"""
CLI 上下文构建器。
该对象负责将命令层显式参数收口为统一的 `CliContext` 数据对象，
供上下文工厂与测试场景复用。
"""
@staticmethod
def build(
env: str,
output: Literal['text', 'json'],
allow_prod: bool,
yes: bool,
dry_run: bool,
) -> CliContext:
"""
构建命令执行上下文。
:param env: 当前命令环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过二次确认
:param dry_run: 是否执行演练模式
:return: 构建完成的 CLI 上下文
"""
return CliContext(
env=env,
output=output,
allow_prod=allow_prod,
yes=yes,
dry_run=dry_run,
)
CLI_CONTEXT_BUILDER = CliContextBuilder()
EnvOption = Annotated[
str,
typer.Option('--env', help='运行环境名称', autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_env_values),
]
OutputOption = Annotated[Literal['text', 'json'], typer.Option('--output', help='输出格式，支持 text 或 json')]
AllowProdOption = Annotated[bool, typer.Option('--allow-prod', help='允许在生产环境中执行危险命令')]
YesOption = Annotated[bool, typer.Option('--yes', help='跳过危险命令确认')]
DryRunOption = Annotated[bool, typer.Option('--dry-run', help='仅执行预演，不落地实际变更')]
shierfeng-fastapi-backend/build/lib/cli/core/__init__.py
-51
View File
@@ -1,51 +0,0 @@
from dataclasses import dataclass, field
from cli.core.app_builder import CliApplicationBuilder, ProjectRuntimeLocator
from cli.core.completion_dispatcher import CompletionDispatcher
from cli.core.context_factory import CliContextFactory, CliRuntimeState
from cli.core.execution import CliExecutionService
from cli.output import OutputRenderer
@dataclass
class CoreServiceContainer:
"""
CLI 核心服务容器。
该容器负责统一装配输出渲染器、运行期状态、上下文工厂与执行服务，
作为控制器、向导和 TUI 等编排层的默认依赖入口。
:param output_renderer: 输出渲染器
:param runtime_state: CLI 运行期状态对象
"""
output_renderer: OutputRenderer = field(default_factory=OutputRenderer)
runtime_state: CliRuntimeState = field(default_factory=CliRuntimeState)
context_factory: CliContextFactory = field(init=False)
execution_service: CliExecutionService = field(init=False)
def __post_init__(self) -> None:
"""
初始化核心服务依赖图。
:return: None
"""
self.context_factory = CliContextFactory(
runtime_state=self.runtime_state,
output_renderer=self.output_renderer,
)
self.execution_service = CliExecutionService(output_renderer=self.output_renderer)
DEFAULT_CORE_SERVICES = CoreServiceContainer()
__all__ = [
'DEFAULT_CORE_SERVICES',
'CliApplicationBuilder',
'CliContextFactory',
'CliExecutionService',
'CliRuntimeState',
'CompletionDispatcher',
'CoreServiceContainer',
'ProjectRuntimeLocator',
]
shierfeng-fastapi-backend/build/lib/cli/core/app_builder.py
-363
View File
@@ -1,363 +0,0 @@
import importlib
import sys
from collections.abc import Callable
from dataclasses import dataclass, field
from pathlib import Path
from typing import Annotated, Literal
import typer
from cli.output import OutputRenderer
from cli.runtime.base import RUNTIME_ENVIRONMENT
@dataclass(frozen=True)
class ProjectRuntimeLocator:
"""
CLI 项目运行时定位器。
该对象负责判断当前目录是否为后端项目根目录、注入 `sys.path`，
并为配置导入阶段提取最小化的 `argv` 参数。
"""
def is_backend_project_dir(self, project_dir: Path) -> bool:
"""
判断给定目录是否为后端项目根目录。
:param project_dir: 待检查目录
:return: 是否为后端项目根目录
"""
return RUNTIME_ENVIRONMENT.is_backend_project_dir(project_dir)
def ensure_backend_dir_on_sys_path(self) -> Path:
"""
将当前后端项目根目录加入 `sys.path` 首位。
:return: 当前后端项目根目录
:raises typer.Exit: 当前目录不是后端项目根目录时退出命令
"""
project_dir = Path.cwd().resolve()
if not self.is_backend_project_dir(project_dir):
typer.echo('`shierfeng` 命令需在 `shierfeng-fastapi-backend` 目录下执行', err=True)
raise typer.Exit(code=2)
project_dir_str = str(project_dir)
if sys.path and sys.path[0] == project_dir_str:
return project_dir
sys.path.insert(0, project_dir_str)
return project_dir
def extract_import_argv(self, argv: list[str] | None = None) -> list[str]:
"""
提取供配置模块导入阶段使用的最小参数集。
:param argv: 原始命令行参数列表
:return: 仅保留程序名和 `--env` 的参数列表
"""
current_argv = argv or sys.argv
program_name = current_argv[0] if current_argv else 'shierfeng'
import_argv = [program_name]
env_value = ''
current_args = current_argv[1:]
for index, argument in enumerate(current_args):
if argument.startswith('--env='):
env_value = argument.split('=', 1)[1].strip()
break
if argument == '--env' and index + 1 < len(current_args):
env_value = current_args[index + 1].strip()
break
if env_value:
import_argv.extend(['--env', env_value])
return import_argv
@dataclass(frozen=True)
class CliCommandGroupRegistry:
"""
CLI 命令组注册表。
该注册表集中维护根 CLI 需要挂载的业务命令组模块路径，
避免命令组声明散落在应用构建器主体中。
:param command_modules: 命令组到模块路径的映射
"""
command_modules: dict[str, str]
@dataclass(frozen=True)
class CliExtensionRegistration:
"""
CLI 扩展入口注册描述。
:param module_path: 扩展模块导入路径
:param attach: 已加载模块挂载到根 CLI 的函数
"""
module_path: str
attach: Callable[[typer.Typer, object], None]
@dataclass(frozen=True)
class CliExtensionRegistry:
"""
CLI 扩展入口注册表。
该注册表集中维护 completion、wizard、TUI 等扩展入口的模块路径与
挂载方式，避免这些规则继续散落在注册器主体中。
:param registrations: 扩展注册描述列表
"""
registrations: tuple[CliExtensionRegistration, ...]
@dataclass(frozen=True)
class CliCommandGroupRegistrar:
"""
CLI 命令组注册器。
该对象负责根据命令组注册表向根 Typer 应用挂载业务命令组。
:param command_group_registry: CLI 命令组注册表
"""
command_group_registry: CliCommandGroupRegistry
module_loader: 'CliModuleLoader' = field(default_factory=lambda: DEFAULT_CLI_MODULE_LOADER)
def register(self, cli: typer.Typer) -> None:
"""
向根应用注册业务命令组。
:param cli: 根 Typer 应用
:return: None
"""
for command_name, module_path in self.command_group_registry.command_modules.items():
command_module = self.module_loader.load(module_path)
cli.add_typer(command_module.app, name=command_name)
class CliExtensionMountSupport:
"""
CLI 扩展入口挂载支持对象。
该对象负责封装不同扩展模块挂载到根 CLI 的差异，避免扩展注册器本体
继续堆积 `if/else` 或硬编码模块处理逻辑。
"""
@staticmethod
def attach_completion(cli: typer.Typer, module: object) -> None:
"""
挂载 completion 扩展入口。
:param cli: 根 Typer 应用
:param module: 已加载模块
:return: None
"""
cli.add_typer(module.COMPLETION_COMMAND_BUILDER.build(cli), name='completion')
@staticmethod
def attach_wizard(cli: typer.Typer, module: object) -> None:
"""
挂载 wizard 扩展入口。
:param cli: 根 Typer 应用
:param module: 已加载模块
:return: None
"""
cli.add_typer(module.WIZARD_COMMAND_BUILDER.build(), name='wizard')
@staticmethod
def attach_tui(cli: typer.Typer, module: object) -> None:
"""
挂载 TUI 扩展入口。
:param cli: 根 Typer 应用
:param module: 已加载模块
:return: None
"""
module.TUI_COMMAND_REGISTRATION.register(cli)
@dataclass(frozen=True)
class CliExtensionRegistrar:
"""
CLI 扩展入口注册器。
该对象负责向根 Typer 应用挂载 completion、wizard 与 TUI
等扩展入口。
"""
extension_registry: CliExtensionRegistry
module_loader: 'CliModuleLoader' = field(default_factory=lambda: DEFAULT_CLI_MODULE_LOADER)
def register(self, cli: typer.Typer) -> None:
"""
向根应用注册扩展入口。
:param cli: 根 Typer 应用
:return: None
"""
for registration in self.extension_registry.registrations:
extension_module = self.module_loader.load(registration.module_path)
registration.attach(cli, extension_module)
@dataclass(frozen=True)
class CliRootOptionInitializer:
"""
CLI 根级选项初始化器。
该对象负责将根级 `--color`、`--icon` 选项映射到共享输出渲染器，
避免根回调继续内联输出配置逻辑。
:param output_renderer: 根命令共享的输出渲染器
"""
output_renderer: OutputRenderer
def initialize(self, *, color: str, icon: str) -> None:
"""
初始化根级输出选项。
:param color: 文本输出颜色模式
:param icon: 文本输出图标模式
:return: None
"""
self.output_renderer.set_color_mode(color)
self.output_renderer.set_icon_mode(icon)
@dataclass(frozen=True)
class CliRootCallbackRegistrar:
"""
CLI 根回调注册器。
该对象负责把根级 `--color`、`--icon` 选项回调挂载到 Typer 根应用，
让 `CliApplicationBuilder` 更专注于整体装配流程。
:param root_option_initializer: 根级选项初始化器
"""
root_option_initializer: CliRootOptionInitializer
def register(self, cli: typer.Typer) -> None:
"""
向根应用注册回调。
:param cli: 根 Typer 应用
:return: None
"""
@cli.callback()
def root_callback(
color: Annotated[
Literal['auto', 'always', 'never'],
typer.Option('--color', help='文本输出颜色模式'),
] = 'always',
icon: Annotated[
Literal['emoji', 'ascii', 'none'],
typer.Option('--icon', help='文本输出图标模式'),
] = 'emoji',
) -> None:
"""
初始化 CLI 根级运行参数。
:param color: 文本输出颜色模式
:param icon: 文本输出图标模式
:return: None
"""
self.root_option_initializer.initialize(color=color, icon=icon)
@dataclass(frozen=True)
class CliModuleLoader:
"""
CLI 模块加载服务。
该对象负责集中执行命令组与扩展入口所需的延迟导入，
让注册器本身更专注于挂载动作。
"""
@staticmethod
def load(module_path: str) -> object:
"""
按模块路径加载模块对象。
:param module_path: 模块导入路径
:return: 已加载模块
"""
return importlib.import_module(module_path)
@dataclass
class CliApplicationBuilder:
"""
CLI 根应用构建器。
:param output_renderer: 根命令共享的输出渲染器
:param command_group_registrar: CLI 命令组注册器
:param extension_registrar: CLI 扩展入口注册器
"""
output_renderer: OutputRenderer
command_group_registrar: CliCommandGroupRegistrar = field(
default_factory=lambda: CliCommandGroupRegistrar(DEFAULT_COMMAND_GROUP_REGISTRY)
)
extension_registrar: CliExtensionRegistrar = field(
default_factory=lambda: CliExtensionRegistrar(DEFAULT_CLI_EXTENSION_REGISTRY)
)
root_option_initializer: CliRootOptionInitializer = field(init=False)
root_callback_registrar: CliRootCallbackRegistrar = field(init=False)
def __post_init__(self) -> None:
"""
初始化根应用构建器依赖。
:return: None
"""
self.root_option_initializer = CliRootOptionInitializer(self.output_renderer)
self.root_callback_registrar = CliRootCallbackRegistrar(self.root_option_initializer)
def build(self) -> typer.Typer:
"""
构建 Typer 根应用并注册全部命令组。
:return: Typer 根应用
"""
cli = typer.Typer(
name='shierfeng',
help='ShiErFeng FastAPI 后端统一命令入口',
no_args_is_help=True,
add_completion=False,
context_settings={'help_option_names': ['-h', '--help']},
)
self.root_callback_registrar.register(cli)
self.command_group_registrar.register(cli)
self.extension_registrar.register(cli)
return cli
DEFAULT_COMMAND_GROUP_REGISTRY = CliCommandGroupRegistry(
command_modules={
'app': 'cli.groups.app',
'db': 'cli.groups.db',
'ops': 'cli.groups.ops',
'cache': 'cli.groups.cache',
'job': 'cli.groups.job',
'config': 'cli.groups.config',
'crypto': 'cli.groups.crypto',
'gen': 'cli.groups.gen',
'dev': 'cli.groups.dev',
}
)
DEFAULT_CLI_EXTENSION_REGISTRY = CliExtensionRegistry(
registrations=(
CliExtensionRegistration('cli.completion.commands', CliExtensionMountSupport.attach_completion),
CliExtensionRegistration('cli.wizard.commands', CliExtensionMountSupport.attach_wizard),
CliExtensionRegistration('cli.tui', CliExtensionMountSupport.attach_tui),
)
)
DEFAULT_CLI_MODULE_LOADER = CliModuleLoader()
shierfeng-fastapi-backend/build/lib/cli/core/completion_dispatcher.py
-121
View File
@@ -1,121 +0,0 @@
import os
from dataclasses import dataclass, field
import typer
from click.shell_completion import shell_complete as click_shell_complete
from typer.completion import shell_complete as typer_shell_complete
from cli.completion.shells import ensure_custom_completion_classes_registered
@dataclass(frozen=True)
class CompletionInstructionSupport:
"""
completion 指令解析支持对象。
该对象负责管理 completion 环境变量名、受支持 shell 列表，以及
Click / Typer 两种指令格式的判定逻辑。
:param complete_env_var: completion 环境变量名
:param supported_shells: 支持的 shell 名称列表
"""
complete_env_var: str = '_SHIERFENG_COMPLETE'
supported_shells: tuple[str, ...] = ('bash', 'zsh', 'fish', 'powershell')
def is_click_style_instruction(self, instruction: str) -> bool:
"""
判断 completion 指令是否为 Click 原生格式。
Click 原生格式为 `<shell>_<instruction>`，例如 `bash_complete`。
:param instruction: completion 指令文本
:return: 是否为 Click 风格指令
"""
return any(instruction.startswith(f'{shell}_') for shell in self.supported_shells)
def is_typer_style_instruction(self, instruction: str) -> bool:
"""
判断 completion 指令是否为 Typer 兼容格式。
Typer 兼容格式为 `<instruction>_<shell>`，例如 `complete_bash`。
:param instruction: completion 指令文本
:return: 是否为 Typer 风格指令
"""
return any(instruction.endswith(f'_{shell}') for shell in self.supported_shells)
@dataclass(frozen=True)
class CompletionInstructionReader:
"""
completion 指令读取器。
该对象负责从当前进程环境中读取并规范化 completion 指令。
:param support: completion 指令解析支持对象
"""
support: CompletionInstructionSupport
def read_instruction(self) -> str:
"""
读取当前进程中的 completion 指令文本。
:return: 规范化后的 completion 指令文本
"""
return os.environ.get(self.support.complete_env_var, '').strip()
@dataclass(frozen=True)
class CompletionDispatcher:
"""
shell completion 请求分发器。
该对象负责识别 Click 与 Typer 两种 completion 指令格式，
并在命中时直接执行补全流程后退出当前进程。
:param support: completion 指令解析支持对象
:param instruction_reader: completion 指令读取器
"""
support: CompletionInstructionSupport = field(default_factory=CompletionInstructionSupport)
instruction_reader: CompletionInstructionReader = field(init=False)
def __post_init__(self) -> None:
"""
初始化 completion 指令读取器。
:return: None
"""
object.__setattr__(self, 'instruction_reader', CompletionInstructionReader(self.support))
def dispatch(self, cli: typer.Typer) -> None:
"""
处理 shell completion 请求并在命中时直接退出。
这里同时兼容 Click 与 Typer 两种 completion 指令格式，避免
生成脚本格式和运行时解析格式不一致时出现 `Shell complete not supported.`。
:param cli: Typer 根应用
:return: None
"""
ensure_custom_completion_classes_registered()
instruction = self.instruction_reader.read_instruction()
if not instruction:
return
click_command = typer.main.get_command(cli)
if self.support.is_click_style_instruction(instruction):
raise SystemExit(
click_shell_complete(click_command, {}, 'shierfeng', self.support.complete_env_var, instruction)
)
if self.support.is_typer_style_instruction(instruction):
raise SystemExit(
typer_shell_complete(click_command, {}, 'shierfeng', self.support.complete_env_var, instruction)
)
raise SystemExit(1)
DEFAULT_COMPLETION_INSTRUCTION_SUPPORT = CompletionInstructionSupport()
shierfeng-fastapi-backend/build/lib/cli/core/context_factory.py
-239
View File
@@ -1,239 +0,0 @@
import logging
from dataclasses import dataclass, field
from importlib import import_module
from typing import Any
from cli.context import CLI_CONTEXT_BUILDER, CliContext, CliContextBuilder
from cli.guards import (
DEFAULT_DANGEROUS_COMMAND_GUARD,
DEFAULT_DANGEROUS_COMMAND_RULE_REGISTRY,
DangerousCommandGuardService,
DangerousCommandRuleRegistry,
)
from cli.output import OutputRenderer
@dataclass
class CliRuntimeState:
"""
CLI 运行期状态。
:param logs_suppressed: 当前进程日志是否已切换为静默模式
"""
logs_suppressed: bool = False
sqlalchemy_logs_suppressed: bool = False
def get_logger(self) -> Any:
"""
获取 CLI 使用的日志对象。
:return: 日志对象
"""
return import_module('utils.log_util').logger
def suppress_logs(self) -> None:
"""
关闭 CLI 进程中的终端日志输出。
:return: None
"""
if self.logs_suppressed:
return
self.get_logger().remove()
self.logs_suppressed = True
def suppress_sqlalchemy_logs(self) -> None:
"""
关闭 CLI 进程中的 SQLAlchemy 终端 SQL 日志输出。
该逻辑同时处理两类来源：
1. 将 `config.env.DataBaseConfig.db_echo` 强制关闭，避免后续新建 Engine 时
继续打开 SQLAlchemy echo。
2. 将已知 SQLAlchemy logger 级别提升到 WARNING，避免已有 logger 配置把
`INFO sqlalchemy.engine.Engine ...` 继续打到标准输出。
:return: None
"""
if self.sqlalchemy_logs_suppressed:
return
env_module = import_module('config.env')
database_config = getattr(env_module, 'DataBaseConfig', None)
if database_config is not None and hasattr(database_config, 'db_echo'):
database_config.db_echo = False
for logger_name in (
'sqlalchemy',
'sqlalchemy.engine',
'sqlalchemy.engine.Engine',
'sqlalchemy.pool',
):
logging.getLogger(logger_name).setLevel(logging.WARNING)
self.sqlalchemy_logs_suppressed = True
@dataclass
class CliLogPolicy:
"""
CLI 日志策略服务。
该对象负责在上下文构建前应用统一的日志输出策略，
将“是否静默日志”这一策略从上下文工厂主体中拆出。
:param runtime_state: CLI 运行期状态对象
"""
runtime_state: CliRuntimeState
def prepare_regular_command(self) -> None:
"""
为普通 CLI 命令应用默认日志策略。
:return: None
"""
self.runtime_state.suppress_logs()
self.runtime_state.suppress_sqlalchemy_logs()
@dataclass
class DangerousCommandContextSupport:
"""
危险命令上下文支持服务。
该对象负责危险命令规则查询、保护执行与拒绝结果收口，
让上下文工厂本体只保留装配职责。
:param dangerous_command_rule_registry: 危险命令规则注册表
:param dangerous_command_guard_service: 危险命令保护执行服务
:param output_renderer: 输出渲染器
"""
dangerous_command_rule_registry: DangerousCommandRuleRegistry
dangerous_command_guard_service: DangerousCommandGuardService
output_renderer: OutputRenderer
def guard_context(self, ctx: CliContext, *, command_name: str) -> CliContext:
"""
对危险命令上下文执行统一保护。
:param ctx: 已构建的 CLI 上下文
:param command_name: 命令唯一标识
:return: 通过保护后的 CLI 上下文
"""
rule = self.dangerous_command_rule_registry.require_rule(command_name)
guard_result = self.dangerous_command_guard_service.guard(ctx, rule=rule)
if guard_result is not None:
self.output_renderer.complete_command(guard_result, ctx)
return ctx
@dataclass
class CliContextFactory:
"""
统一构建 CLI 命令上下文。
:param runtime_state: CLI 运行期状态对象
:param output_renderer: 输出渲染器
:param cli_context_builder: CLI 上下文构建器
:param dangerous_command_rule_registry: 危险命令规则注册表
:param dangerous_command_guard_service: 危险命令保护执行服务
"""
runtime_state: CliRuntimeState = field(default_factory=CliRuntimeState)
output_renderer: OutputRenderer = field(default_factory=OutputRenderer)
cli_context_builder: CliContextBuilder = field(default_factory=lambda: CLI_CONTEXT_BUILDER)
dangerous_command_rule_registry: DangerousCommandRuleRegistry = field(
default_factory=lambda: DEFAULT_DANGEROUS_COMMAND_RULE_REGISTRY
)
dangerous_command_guard_service: DangerousCommandGuardService = field(
default_factory=lambda: DEFAULT_DANGEROUS_COMMAND_GUARD
)
_log_policy: CliLogPolicy | None = field(default=None, init=False, repr=False)
_dangerous_command_support: DangerousCommandContextSupport | None = field(
default=None,
init=False,
repr=False,
)
def get_log_policy(self) -> CliLogPolicy:
"""
获取当前上下文工厂使用的日志策略服务。
:return: CLI 日志策略服务
"""
if self._log_policy is None:
self._log_policy = CliLogPolicy(runtime_state=self.runtime_state)
return self._log_policy
def get_dangerous_command_support(self) -> DangerousCommandContextSupport:
"""
获取当前上下文工厂使用的危险命令上下文支持服务。
:return: 危险命令上下文支持服务
"""
if self._dangerous_command_support is None:
self._dangerous_command_support = DangerousCommandContextSupport(
dangerous_command_rule_registry=self.dangerous_command_rule_registry,
dangerous_command_guard_service=self.dangerous_command_guard_service,
output_renderer=self.output_renderer,
)
return self._dangerous_command_support
def build_regular(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
) -> CliContext:
"""
构建普通命令上下文。
:param env: 运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:return: CLI 上下文
"""
self.get_log_policy().prepare_regular_command()
return self.cli_context_builder.build(env, output, allow_prod, yes, dry_run)
def build_readonly(
self,
env: str,
output: str,
) -> CliContext:
"""
构建只读命令上下文。
:param env: 运行环境
:param output: 输出格式
:return: CLI 上下文
"""
return self.build_regular(env, output, False, False, False)
def build_dangerous(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
command_name: str,
) -> CliContext:
"""
构建危险命令上下文并执行统一保护。
:param env: 运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param command_name: 命令唯一标识
:return: CLI 上下文
"""
ctx = self.build_regular(env, output, allow_prod, yes, dry_run)
return self.get_dangerous_command_support().guard_context(ctx, command_name=command_name)
shierfeng-fastapi-backend/build/lib/cli/core/execution.py
-137
View File
@@ -1,137 +0,0 @@
import asyncio
from collections.abc import Callable
from dataclasses import dataclass, field
from typing import Any
from cli.context import CliContext
from cli.exit_codes import RUNTIME_ERROR
from cli.output import CommandResult, OutputRenderer
@dataclass
class CliExecutionService:
"""
CLI 执行与结果收口服务。
:param output_renderer: 输出渲染器
"""
output_renderer: OutputRenderer = field(default_factory=OutputRenderer)
def run_async(self, coroutine: Any) -> Any:
"""
执行异步协程并返回结果。
:param coroutine: 待执行协程
:return: 协程执行结果
"""
return asyncio.run(coroutine)
def complete_payload(
self,
ctx: CliContext,
payload: dict[str, Any],
*,
default_exit_code: int = 0,
) -> None:
"""
输出标准字典负载并结束命令。
:param ctx: CLI 上下文
:param payload: 标准结果字典
:param default_exit_code: 默认退出码
:return: None
"""
self.output_renderer.complete_command(self.build_result(payload, default_exit_code=default_exit_code), ctx)
def complete_result(
self,
ctx: CliContext,
result: CommandResult,
) -> None:
"""
输出命令结果对象并结束命令。
:param ctx: CLI 上下文
:param result: 命令执行结果对象
:return: None
"""
self.output_renderer.complete_command(result, ctx)
def complete_payload_with_text(
self,
ctx: CliContext,
payload: dict[str, Any],
*,
text_builder: Callable[[dict[str, Any]], Any],
default_exit_code: int = 0,
text_condition: Callable[[dict[str, Any]], bool] | None = None,
) -> None:
"""
按输出格式收口标准负载，必要时先转换为文本结果。
:param ctx: CLI 上下文
:param payload: 标准结果字典
:param text_builder: 文本结果构建函数
:param default_exit_code: 默认退出码
:param text_condition: 文本模式下是否应用构建函数的判定函数
:return: None
"""
if ctx.output != 'text':
self.complete_payload(ctx, payload, default_exit_code=default_exit_code)
return
result = self.build_result(payload, default_exit_code=default_exit_code)
should_build_text = True
if callable(text_condition) and isinstance(result.data, dict):
should_build_text = bool(text_condition(result.data))
if should_build_text and isinstance(result.data, dict):
result.data = text_builder(result.data)
self.complete_result(ctx, result)
def complete_payload_result(
self,
ctx: CliContext,
payload: dict[str, Any],
*,
text_builder: Callable[[dict[str, Any]], Any] | None = None,
default_exit_code: int = 0,
text_condition: Callable[[dict[str, Any]], bool] | None = None,
) -> None:
"""
统一收口标准负载，按输出格式决定是否渲染为文本结果。
:param ctx: CLI 上下文
:param payload: 标准结果字典
:param text_builder: 文本结果构建函数
:param default_exit_code: 默认退出码
:param text_condition: 文本模式下是否应用构建函数的判定函数
:return: None
"""
if text_builder is None:
self.complete_payload(ctx, payload, default_exit_code=default_exit_code)
return
self.complete_payload_with_text(
ctx,
payload,
text_builder=text_builder,
default_exit_code=default_exit_code,
text_condition=text_condition,
)
@staticmethod
def build_result(payload: dict[str, Any], *, default_exit_code: int = 0) -> CommandResult:
"""
将标准字典负载转换为命令结果对象。
:param payload: 标准结果字典
:param default_exit_code: 默认退出码；当 payload 未显式提供 exit_code 且
该值仍为 0 时，失败结果会统一回退到 `RUNTIME_ERROR`
:return: 命令结果对象
"""
result_payload = dict(payload)
exit_code = result_payload.pop('exit_code', None)
if exit_code is None:
is_ok = bool(result_payload.get('ok', True))
exit_code = default_exit_code if is_ok or default_exit_code != 0 else RUNTIME_ERROR
return CommandResult(data=result_payload, exit_code=exit_code)
shierfeng-fastapi-backend/build/lib/cli/exit_codes.py
-8
View File
@@ -1,8 +0,0 @@
SUCCESS = 0
ARGUMENT_ERROR = 2
DEPENDENCY_ERROR = 10
DATABASE_ERROR = 20
REDIS_ERROR = 21
SCHEDULER_ERROR = 22
GUARD_REJECTED = 30
RUNTIME_ERROR = 50
shierfeng-fastapi-backend/build/lib/cli/groups/__init__.py
View File
shierfeng-fastapi-backend/build/lib/cli/groups/app/__init__.py
-3
View File
@@ -1,3 +0,0 @@
from .command import app
__all__ = ['app']
shierfeng-fastapi-backend/build/lib/cli/groups/app/command.py
-102
View File
@@ -1,102 +0,0 @@
from typing import Annotated, Literal
import typer
from cli.context import EnvOption, OutputOption
from .controller import AppCommandController
app = typer.Typer(
help='应用相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
_APP_COMMAND_CONTROLLER = AppCommandController()
@app.command('run', help='启动当前 FastAPI 应用')
def run_app(
env: EnvOption = 'dev',
) -> None:
"""
启动当前 FastAPI 应用。
:param env: 当前命令运行环境
:return: None
"""
_APP_COMMAND_CONTROLLER.run_app(env)
@app.command('doctor', help='执行应用启动前检查')
def doctor(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
执行应用启动前检查。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_APP_COMMAND_CONTROLLER.doctor(env, output)
@app.command('config', help='查看当前应用配置快照')
def app_config(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
输出当前应用配置快照。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_APP_COMMAND_CONTROLLER.show_config(env, output)
@app.command('env', help='查看当前 CLI 解析到的应用环境信息')
def app_env(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
输出当前 CLI 解析到的应用环境信息。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_APP_COMMAND_CONTROLLER.show_env(env, output)
@app.command('routes', help='查看当前应用注册路由清单')
def routes(
env: EnvOption = 'dev',
output: OutputOption = 'text',
path_prefix: Annotated[str, typer.Option('--path-prefix', help='按路由前缀过滤')] = '',
method: Annotated[str, typer.Option('--method', help='按请求方法过滤，如 GET、POST')] = '',
group_by: Annotated[Literal['none', 'tag'], typer.Option('--group-by', help='路由分组方式')] = 'none',
include_hidden: Annotated[bool, typer.Option('--include-hidden', help='包含未出现在 OpenAPI 中的路由')] = False,
) -> None:
"""
输出当前应用注册路由清单。
:param env: 当前命令运行环境
:param output: 输出格式
:param path_prefix: 路由前缀过滤条件
:param method: 请求方法过滤条件
:param group_by: 路由分组方式
:param include_hidden: 是否包含隐藏路由
:return: None
"""
_APP_COMMAND_CONTROLLER.show_routes(
env,
output,
path_prefix=path_prefix,
method=method,
group_by=group_by,
include_hidden=include_hidden,
)
shierfeng-fastapi-backend/build/lib/cli/groups/app/controller.py
-236
View File
@@ -1,236 +0,0 @@
from collections import defaultdict
from typing import Any
from fastapi.routing import APIRoute
from cli.bootstrap import APP_BOOTSTRAP, AppBootstrapService
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
from cli.exit_codes import DEPENDENCY_ERROR, SUCCESS
from cli.runtime.app import APP_RUNTIME, AppRuntimeService
from cli.runtime.crypto import CRYPTO_RUNTIME, CryptoRuntimeService
from cli.runtime.db import DATABASE_RUNTIME, DatabaseRuntimeService
from cli.runtime.ops import OPERATIONS_RUNTIME, OperationsRuntimeService
from .presenter import AppCommandPresenter
class AppCommandController:
"""
应用命令控制器。
该控制器负责组织 `app` 命令组的上下文准备、runtime 调用、
payload 构建，以及基于输出格式选择 presenter 或直接返回 JSON。
"""
def __init__(
self,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: AppCommandPresenter | None = None,
runtime_service: AppRuntimeService | None = None,
database_runtime: DatabaseRuntimeService | None = None,
operations_runtime: OperationsRuntimeService | None = None,
crypto_runtime: CryptoRuntimeService | None = None,
bootstrap_service: AppBootstrapService | None = None,
) -> None:
"""
初始化应用命令控制器。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 应用命令文本渲染器
:param runtime_service: 应用运行时服务
:param database_runtime: 数据库运行时服务
:param operations_runtime: 运维运行时服务
:param crypto_runtime: 传输加密运行时服务
:param bootstrap_service: 应用引导服务
:return: None
"""
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or AppCommandPresenter()
self.runtime_service = runtime_service or APP_RUNTIME
self.database_runtime = database_runtime or DATABASE_RUNTIME
self.operations_runtime = operations_runtime or OPERATIONS_RUNTIME
self.crypto_runtime = crypto_runtime or CRYPTO_RUNTIME
self.bootstrap_service = bootstrap_service or APP_BOOTSTRAP
def run_app(self, env: str) -> None:
"""
启动当前 FastAPI 应用。
:param env: 当前命令运行环境
:return: None
"""
self.bootstrap_service.exec_app_run_command(env)
def doctor(self, env: str, output: str) -> None:
"""
执行应用启动前检查。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
db_status = self.execution_service.run_async(self.database_runtime.ping_database())
redis_status = self.execution_service.run_async(self.operations_runtime.ping_redis())
crypto_status = self.crypto_runtime.validate_crypto_config()
payload = {
'env': ctx.env,
'database': db_status,
'redis': redis_status,
'crypto': crypto_status,
}
payload['ok'] = all(item.get('ok', False) for item in (db_status, redis_status, crypto_status))
exit_code = SUCCESS if payload['ok'] else DEPENDENCY_ERROR
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_doctor_text,
default_exit_code=exit_code,
)
def show_config(self, env: str, output: str) -> None:
"""
输出当前应用配置快照。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
self.execution_service.complete_payload_result(
ctx,
{'ok': True, 'env': ctx.env, 'config': self.runtime_service.get_app_config_snapshot()},
text_builder=self.presenter.build_app_config_text,
default_exit_code=SUCCESS,
)
def show_env(self, env: str, output: str) -> None:
"""
输出当前 CLI 解析到的应用环境信息。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
self.execution_service.complete_payload_result(
ctx,
{'ok': True, 'env': ctx.env, 'runtime': self.runtime_service.get_app_env_snapshot()},
text_builder=self.presenter.build_app_env_text,
default_exit_code=SUCCESS,
)
def show_routes(
self,
env: str,
output: str,
*,
path_prefix: str,
method: str,
group_by: str,
include_hidden: bool,
) -> None:
"""
输出当前应用注册路由清单。
:param env: 当前命令运行环境
:param output: 输出格式
:param path_prefix: 路由前缀过滤条件
:param method: 请求方法过滤条件
:param group_by: 路由分组方式
:param include_hidden: 是否包含隐藏路由
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
routes_payload = self._serialize_routes(
self.runtime_service.build_app_instance(),
path_prefix=path_prefix,
method=method,
include_hidden=include_hidden,
)
grouped_routes = self._group_routes_by_tag(routes_payload) if group_by == 'tag' else None
payload = {
'ok': True,
'env': ctx.env,
'count': len(routes_payload),
'filters': {
'pathPrefix': path_prefix,
'method': method.upper().strip(),
'groupBy': group_by,
'includeHidden': include_hidden,
},
'routes': routes_payload,
'groupedRoutes': grouped_routes,
}
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_routes_text,
default_exit_code=SUCCESS,
text_condition=lambda data: data.get('ok', False),
)
@staticmethod
def _serialize_routes(
app_instance: Any,
*,
path_prefix: str = '',
method: str = '',
include_hidden: bool = False,
) -> list[dict[str, Any]]:
"""
序列化 FastAPI 路由信息。
:param app_instance: FastAPI 应用实例
:param path_prefix: 路径前缀过滤条件
:param method: 请求方法过滤条件
:param include_hidden: 是否包含未出现在 OpenAPI 中的路由
:return: 序列化后的路由列表
"""
normalized_method = method.upper().strip()
routes = []
for route in app_instance.routes:
if not isinstance(route, APIRoute):
continue
if not include_hidden and not route.include_in_schema:
continue
if path_prefix and not route.path.startswith(path_prefix):
continue
route_methods = sorted(item for item in route.methods if item not in {'HEAD', 'OPTIONS'})
if normalized_method and normalized_method not in route_methods:
continue
routes.append(
{
'path': route.path,
'methods': route_methods,
'name': route.name,
'summary': route.summary or '',
'operationId': route.operation_id or '',
'tags': route.tags or [],
'includeInSchema': route.include_in_schema,
}
)
return sorted(routes, key=lambda item: (item['path'], ','.join(item['methods'])))
@staticmethod
def _group_routes_by_tag(routes_payload: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
"""
按标签对路由信息分组。
:param routes_payload: 原始路由列表
:return: 按标签分组后的路由映射
"""
grouped_routes: dict[str, list[dict[str, Any]]] = defaultdict(list)
for route in routes_payload:
tags = route.get('tags') or ['__untagged__']
for tag in tags:
grouped_routes[tag].append(route)
return dict(sorted(grouped_routes.items(), key=lambda item: item[0]))
shierfeng-fastapi-backend/build/lib/cli/groups/app/presenter.py
-210
View File
@@ -1,210 +0,0 @@
from typing import Any
from cli.utils import SHELL_TEXT_FORMATTER
class AppCommandPresenter:
"""
应用命令文本渲染器。
该渲染器负责将 `app` 命令组产生的结构化 payload 转换为稳定的文本摘要，
同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
"""
def build_routes_text(self, payload: dict[str, Any]) -> str:
"""
将路由列表结果渲染为文本摘要。
:param payload: 路由列表结果字典
:return: 文本摘要
"""
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'count: {payload.get("count", 0)}',
]
filters = payload.get('filters')
if isinstance(filters, dict):
lines.extend(self._build_route_filter_lines(filters))
grouped_routes = payload.get('groupedRoutes')
if filters and filters.get('groupBy') == 'tag' and isinstance(grouped_routes, dict):
lines.extend(self._build_grouped_routes_text(grouped_routes))
return '\n'.join(lines)
routes = payload.get('routes')
if not isinstance(routes, list) or not routes:
lines.append('routes: none')
return '\n'.join(lines)
lines.append('routes:')
for route in routes:
if isinstance(route, dict):
lines.extend([f' {line}' for line in self._build_route_item_lines(route)])
return '\n'.join(lines)
def build_app_config_text(self, payload: dict[str, Any]) -> str:
"""
将应用配置快照渲染为文本摘要。
:param payload: 应用配置结果字典
:return: 文本摘要
"""
config = payload.get('config')
if not isinstance(config, dict):
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
'config: none',
]
)
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
'application:',
f' name: {config.get("name", "-")}',
f' host: {config.get("host", "-")}:{config.get("port", "-")}',
f' root_path: {config.get("rootPath", "-") or "/"}',
f' reload: {str(config.get("reload", False)).lower()}',
f' workers: {config.get("workers", "-")}',
f' disable_swagger: {str(config.get("disableSwagger", False)).lower()}',
f' disable_redoc: {str(config.get("disableRedoc", False)).lower()}',
'database:',
f' type: {config.get("dbType", "-")}',
f' host: {config.get("dbHost", "-")}:{config.get("dbPort", "-")}',
f' name: {config.get("dbDatabase", "-")}',
'redis:',
f' host: {config.get("redisHost", "-")}:{config.get("redisPort", "-")}',
'logging:',
f' level: {config.get("logLevel", "-")}',
'transport_crypto:',
f' enabled: {str(config.get("transportCryptoEnabled", False)).lower()}',
f' mode: {config.get("transportCryptoMode", "-")}',
]
return '\n'.join(lines)
def build_app_env_text(self, payload: dict[str, Any]) -> str:
"""
将应用环境解析结果渲染为文本摘要。
:param payload: 应用环境结果字典
:return: 文本摘要
"""
runtime = payload.get('runtime')
if not isinstance(runtime, dict):
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
'runtime: none',
]
)
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
'runtime:',
f' cli_env: {runtime.get("cliEnv", "-")}',
f' config_env: {runtime.get("configEnv", "-")}',
f' app_env: {runtime.get("appEnv", "-")}',
f' env_file: {runtime.get("envFile", "-")}',
f' env_file_exists: {str(runtime.get("envFileExists", False)).lower()}',
f' backend_dir: {runtime.get("backendDir", "-")}',
f' python_executable: {runtime.get("pythonExecutable", "-")}',
]
)
def build_doctor_text(self, payload: dict[str, Any]) -> str:
"""
将应用启动前检查结果渲染为文本摘要。
:param payload: 启动前检查结果字典
:return: 文本摘要
"""
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
'checks:',
self._build_check_status_line('database', payload.get('database')),
self._build_check_status_line('redis', payload.get('redis')),
self._build_check_status_line('crypto', payload.get('crypto')),
]
)
@staticmethod
def _build_route_filter_lines(filters: dict[str, object]) -> list[str]:
"""
构建路由过滤条件文本行。
:param filters: 过滤条件字典
:return: 过滤条件文本行列表
"""
active_filters = []
for key, value in filters.items():
if value in (None, '', False, 'none'):
continue
active_filters.append(f'{SHELL_TEXT_FORMATTER.to_snake_case(key)}={value}')
if not active_filters:
return ['filters: none']
return ['filters:', *[f' - {item}' for item in active_filters]]
@staticmethod
def _build_route_item_lines(route_item: dict[str, Any]) -> list[str]:
"""
构建单条路由记录的文本行。
:param route_item: 单条路由记录
:return: 文本行列表
"""
methods = ','.join(route_item.get('methods', [])) or '-'
path = SHELL_TEXT_FORMATTER.truncate_text(route_item.get('path', ''), 72)
tags = ','.join(route_item.get('tags', [])) or '-'
summary = SHELL_TEXT_FORMATTER.truncate_text(route_item.get('summary', ''), 60)
name = SHELL_TEXT_FORMATTER.truncate_text(route_item.get('name', ''), 40)
return [
f'- [{methods}] {path}',
f' name: {name or "-"} | tags: {tags}',
f' summary: {summary or "-"}',
]
def _build_grouped_routes_text(self, grouped_routes: dict[str, Any]) -> list[str]:
"""
将按标签分组后的路由结果渲染为文本行。
:param grouped_routes: 按标签分组后的路由映射
:return: 文本行列表
"""
if not grouped_routes:
return ['groups: none']
lines = [f'groups: {len(grouped_routes)}']
for tag, routes in grouped_routes.items():
route_items = routes if isinstance(routes, list) else []
lines.append(f' {tag}: {len(route_items)}')
for route in route_items:
if isinstance(route, dict):
lines.extend([f' {line}' for line in self._build_route_item_lines(route)])
return lines
@staticmethod
def _build_check_status_line(name: str, status_payload: dict[str, Any] | None) -> str:
"""
构建单项检查结果摘要行。
:param name: 检查项名称
:param status_payload: 检查结果字典
:return: 摘要行文本
"""
if not isinstance(status_payload, dict):
return f' {name}: unknown'
ok = str(status_payload.get('ok', False)).lower()
message = status_payload.get('message', '-') or '-'
error = status_payload.get('error')
if error:
return f' {name}: {ok} | {message} | error: {SHELL_TEXT_FORMATTER.truncate_text(error, 120)}'
return f' {name}: {ok} | {message}'
shierfeng-fastapi-backend/build/lib/cli/groups/cache/__init__.py
Vendored
-3
View File
@@ -1,3 +0,0 @@
from .command import app
__all__ = ['app']
shierfeng-fastapi-backend/build/lib/cli/groups/cache/command.py
Vendored
-163
View File
@@ -1,163 +0,0 @@
import typer
from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY
from cli.context import AllowProdOption, DryRunOption, EnvOption, OutputOption, YesOption
from .controller import CacheCommandController
app = typer.Typer(
help='缓存相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
_CACHE_COMMAND_CONTROLLER = CacheCommandController()
@app.command('stats', help='查看缓存统计信息')
def stats(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
查看缓存统计信息。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_CACHE_COMMAND_CONTROLLER.stats(env, output)
@app.command('keys', help='查看指定缓存名称下的键名列表')
def keys(
cache_name: str = typer.Argument(
...,
help='缓存名称',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_cache_names,
),
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
查看指定缓存名称下的键名列表。
:param cache_name: 缓存名称
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_CACHE_COMMAND_CONTROLLER.keys(cache_name, env, output)
@app.command('get', help='查看指定缓存内容')
def get(
cache_name: str = typer.Argument(
...,
help='缓存名称',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_cache_names,
),
cache_key: str = typer.Argument(
...,
help='缓存键名',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_cache_keys,
),
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
查看指定缓存内容。
:param cache_name: 缓存名称
:param cache_key: 缓存键名
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_CACHE_COMMAND_CONTROLLER.get(cache_name, cache_key, env, output)
@app.command('clear', help='执行缓存清理')
def clear(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
cache_name: str = typer.Option(
'',
'--cache-name',
help='按缓存名称前缀清理',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_cache_names,
),
cache_key: str = typer.Option('', '--cache-key', help='按缓存键名模糊清理'),
clear_all: bool = typer.Option(False, '--all', help='清理全部缓存并重建系统基础缓存'),
) -> None:
"""
清理缓存。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param cache_name: 缓存名称前缀
:param cache_key: 缓存键名
:param clear_all: 是否清理全部缓存
:return: None
"""
_CACHE_COMMAND_CONTROLLER.clear(
env,
output,
allow_prod,
yes,
dry_run,
cache_name=cache_name,
cache_key=cache_key,
clear_all=clear_all,
)
@app.command('ttl', help='查看指定缓存键的剩余过期时间')
def ttl(
cache_name: str = typer.Argument(
...,
help='缓存名称',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_cache_names,
),
cache_key: str = typer.Argument(
...,
help='缓存键名',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_cache_keys,
),
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
查看指定缓存键的剩余过期时间。
:param cache_name: 缓存名称
:param cache_key: 缓存键名
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_CACHE_COMMAND_CONTROLLER.ttl(cache_name, cache_key, env, output)
@app.command('warmup', help='执行系统缓存预热')
def warmup(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
) -> None:
"""
执行系统缓存预热。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
_CACHE_COMMAND_CONTROLLER.warmup(env, output, allow_prod, yes)
shierfeng-fastapi-backend/build/lib/cli/groups/cache/controller.py
Vendored
-183
View File
@@ -1,183 +0,0 @@
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
from cli.runtime.cache import CACHE_RUNTIME, CacheRuntimeService
from .presenter import CacheCommandPresenter
class CacheCommandController:
"""
缓存命令控制器。
该控制器负责组织 `cache` 命令组的上下文准备、runtime 调用、
payload 注入，以及基于输出格式选择 presenter 或直接返回 JSON。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 缓存命令文本渲染器
"""
def __init__(
self,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: CacheCommandPresenter | None = None,
runtime_service: CacheRuntimeService | None = None,
) -> None:
"""
初始化缓存命令控制器。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 缓存命令文本渲染器
:param runtime_service: 缓存运行时服务
:return: None
"""
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or CacheCommandPresenter()
self.runtime_service = runtime_service or CACHE_RUNTIME
def stats(self, env: str, output: str) -> None:
"""
查看缓存统计信息。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.runtime_service.get_cache_stats())
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_cache_stats_text,
text_condition=lambda result_data: bool(result_data.get('ok', False)),
)
def keys(self, cache_name: str, env: str, output: str) -> None:
"""
查看指定缓存名称下的键名列表。
:param cache_name: 缓存名称
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.runtime_service.list_cache_keys(cache_name))
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_cache_keys_text,
text_condition=lambda result_data: bool(result_data.get('ok', False)),
)
def get(self, cache_name: str, cache_key: str, env: str, output: str) -> None:
"""
查看指定缓存内容。
:param cache_name: 缓存名称
:param cache_key: 缓存键名
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.runtime_service.get_cache_value(cache_name, cache_key))
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_cache_value_text,
text_condition=lambda result_data: bool(result_data.get('ok', False)),
)
def clear(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
cache_name: str,
cache_key: str,
clear_all: bool,
) -> None:
"""
清理缓存。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param cache_name: 缓存名称前缀
:param cache_key: 缓存键名
:param clear_all: 是否清理全部缓存
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='cache clear',
)
self.execution_service.complete_payload(
ctx,
self.execution_service.run_async(
self.runtime_service.clear_cache(
cache_name=cache_name,
cache_key=cache_key,
clear_all=clear_all,
dry_run=dry_run,
)
),
)
def ttl(self, cache_name: str, cache_key: str, env: str, output: str) -> None:
"""
查看指定缓存键的剩余过期时间。
:param cache_name: 缓存名称
:param cache_key: 缓存键名
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.runtime_service.get_cache_ttl(cache_name, cache_key))
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_cache_ttl_text,
text_condition=lambda result_data: 'error' not in result_data,
)
def warmup(self, env: str, output: str, allow_prod: bool, yes: bool) -> None:
"""
执行系统缓存预热。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
False,
command_name='cache warmup',
)
self.execution_service.complete_payload(
ctx, self.execution_service.run_async(self.runtime_service.warmup_cache())
)
shierfeng-fastapi-backend/build/lib/cli/groups/cache/presenter.py
Vendored
-150
View File
@@ -1,150 +0,0 @@
from cli.utils import SHELL_TEXT_FORMATTER
class CacheCommandPresenter:
"""
缓存命令文本渲染器。
该渲染器负责将 `cache` 命令组产生的结构化 payload 转换为稳定的文本摘要，
同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
"""
def build_cache_stats_text(self, payload: dict[str, object]) -> str:
"""
将缓存统计结果渲染为文本摘要。
:param payload: 缓存统计结果
:return: 文本摘要
"""
info = payload.get('info')
command_stats = payload.get('commandStats')
cache_names = payload.get('cacheNames')
redis_version = '-'
connected_clients = '-'
used_memory = '-'
uptime_seconds = '-'
keyspace_hits = '-'
keyspace_misses = '-'
if isinstance(info, dict):
redis_version = info.get('redis_version', '-')
connected_clients = info.get('connected_clients', '-')
used_memory = info.get('used_memory_human', info.get('used_memory', '-'))
uptime_seconds = info.get('uptime_in_seconds', '-')
keyspace_hits = info.get('keyspace_hits', '-')
keyspace_misses = info.get('keyspace_misses', '-')
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'db_size: {payload.get("dbSize", 0)}',
'redis:',
f' version: {redis_version}',
f' connected_clients: {connected_clients}',
f' used_memory: {used_memory}',
f' uptime_seconds: {uptime_seconds}',
f' keyspace_hits: {keyspace_hits}',
f' keyspace_misses: {keyspace_misses}',
]
if isinstance(command_stats, list) and command_stats:
lines.append('command_stats_top10:')
lines.extend(
f' - {item.get("name", "-")}: {item.get("value", 0)}'
for item in command_stats[:10]
if isinstance(item, dict)
)
else:
lines.append('command_stats_top10: none')
if isinstance(cache_names, list) and cache_names:
lines.append(f'cache_names: {len(cache_names)}')
lines.append('cache_name_samples:')
lines.extend(
f' - {item.get("cacheName", "-")}: {self._build_cache_name_remark(item.get("remark", ""))}'
for item in cache_names[:10]
if isinstance(item, dict)
)
else:
lines.append('cache_names: 0')
return '\n'.join(lines)
def build_cache_keys_text(self, payload: dict[str, object]) -> str:
"""
将缓存键列表结果渲染为文本摘要。
:param payload: 缓存键列表结果
:return: 文本摘要
"""
keys = payload.get('keys')
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'cache_name: {payload.get("cacheName", "")}',
f'count: {payload.get("count", 0)}',
]
if not isinstance(keys, list) or not keys:
lines.append('keys: none')
return '\n'.join(lines)
lines.append('keys:')
lines.extend(f' - {key}' for key in keys)
return '\n'.join(lines)
def build_cache_value_text(self, payload: dict[str, object]) -> str:
"""
将缓存值读取结果渲染为文本摘要。
:param payload: 缓存值读取结果字典
:return: 文本摘要
"""
cache_value = '' if payload.get('cacheValue') is None else str(payload.get('cacheValue'))
cache_value_lines = cache_value.splitlines() if cache_value else []
if not cache_value_lines:
rendered_value_lines = [' -']
elif len(cache_value_lines) == 1:
rendered_value_lines = [f' {SHELL_TEXT_FORMATTER.truncate_text(cache_value_lines[0], 200)}']
else:
rendered_value_lines = [' |', *[f' {line}' for line in cache_value_lines]]
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'cache_name: {payload.get("cacheName", "")}',
f'cache_key: {payload.get("cacheKey", "")}',
f'full_cache_key: {payload.get("fullCacheKey", "")}',
'cache_value:',
*rendered_value_lines,
]
)
@staticmethod
def build_cache_ttl_text(payload: dict[str, object]) -> str:
"""
将缓存 TTL 结果渲染为文本摘要。
:param payload: 缓存 TTL 结果字典
:return: 文本摘要
"""
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'cache_name: {payload.get("cacheName", "")}',
f'cache_key: {payload.get("cacheKey", "")}',
f'full_cache_key: {payload.get("fullCacheKey", "")}',
f'message: {payload.get("message", "-")}',
f'ttl_seconds: {payload.get("ttlSeconds", "-")}',
f'persistent: {str(payload.get("persistent", False)).lower()}',
f'expires: {str(payload.get("expires", False)).lower()}',
]
)
@staticmethod
def _build_cache_name_remark(remark: object) -> str:
"""
规范化缓存名称备注文本。
:param remark: 原始备注
:return: 规范化后的备注
"""
text = '' if remark is None else str(remark).strip()
return text or '-'
shierfeng-fastapi-backend/build/lib/cli/groups/config/__init__.py
-3
View File
@@ -1,3 +0,0 @@
from .command import app
__all__ = ['app']
shierfeng-fastapi-backend/build/lib/cli/groups/config/command.py
-173
View File
@@ -1,173 +0,0 @@
from typing import Annotated, Literal
import typer
from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY
from cli.context import AllowProdOption, DryRunOption, EnvOption, OutputOption, YesOption
from .controller import ConfigCommandController
app = typer.Typer(
help='参数配置相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
_CONFIG_COMMAND_CONTROLLER = ConfigCommandController()
@app.command('list', help='查看参数配置列表')
def list_command(
env: EnvOption = 'dev',
output: OutputOption = 'text',
config_name: Annotated[str, typer.Option('--config-name', help='按参数名称过滤')] = '',
config_key: Annotated[
str,
typer.Option(
'--config-key',
help='按参数键名过滤',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_config_keys,
),
] = '',
config_type: Annotated[Literal['Y', 'N'] | None, typer.Option('--config-type', help='按系统内置标记过滤')] = None,
begin_date: Annotated[str, typer.Option('--begin-date', help='按创建时间开始日期过滤，格式 YYYY-MM-DD')] = '',
end_date: Annotated[str, typer.Option('--end-date', help='按创建时间结束日期过滤，格式 YYYY-MM-DD')] = '',
paged: Annotated[bool, typer.Option('--paged/--no-paged', help='是否启用分页结果')] = False,
page_num: Annotated[int, typer.Option('--page-num', min=1, help='分页页码')] = 1,
page_size: Annotated[int, typer.Option('--page-size', min=1, help='分页每页数量')] = 20,
) -> None:
"""
查看参数配置列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param config_name: 参数名称过滤条件
:param config_key: 参数键名过滤条件
:param config_type: 参数类型过滤条件
:param begin_date: 查询开始日期
:param end_date: 查询结束日期
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
_CONFIG_COMMAND_CONTROLLER.list_configs(
env,
output,
config_name=config_name,
config_key=config_key,
config_type=config_type,
begin_date=begin_date,
end_date=end_date,
paged=paged,
page_num=page_num,
page_size=page_size,
)
@app.command('get', help='查看单个参数配置详情')
def get_command(
config_key: Annotated[
str,
typer.Argument(
help='需要查询的参数键名',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_config_keys,
),
],
env: EnvOption = 'dev',
output: OutputOption = 'text',
source: Annotated[Literal['db', 'cache', 'both'], typer.Option('--source', help='读取来源')] = 'both',
) -> None:
"""
查看单个参数配置详情。
:param config_key: 需要查询的参数键名
:param env: 当前命令运行环境
:param output: 输出格式
:param source: 配置读取来源
:return: None
"""
_CONFIG_COMMAND_CONTROLLER.get_config(config_key, env, output, source=source)
@app.command('set', help='新增或更新单个参数配置')
def set_command(
config_key: Annotated[
str,
typer.Argument(
help='需要写入的参数键名',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_config_keys,
),
],
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
value: Annotated[str, typer.Option('--value', help='参数键值')] = ...,
name: Annotated[str | None, typer.Option('--name', help='参数名称，新增时必填')] = None,
config_type: Annotated[Literal['Y', 'N'] | None, typer.Option('--config-type', help='系统内置标记')] = None,
remark: Annotated[str | None, typer.Option('--remark', help='参数备注')] = None,
) -> None:
"""
新增或更新单个参数配置。
:param config_key: 需要写入的参数键名
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param value: 参数键值
:param name: 参数名称
:param config_type: 参数类型
:param remark: 参数备注
:return: None
"""
_CONFIG_COMMAND_CONTROLLER.set_config(
config_key,
env,
output,
allow_prod,
yes,
dry_run,
value=value,
name=name,
config_type=config_type,
remark=remark,
)
@app.command('sync-cache', help='刷新参数配置缓存')
def sync_cache(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
) -> None:
"""
刷新参数配置缓存。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
_CONFIG_COMMAND_CONTROLLER.sync_cache(env, output, allow_prod, yes)
@app.command('doctor', help='诊断参数配置数据库与缓存是否一致')
def doctor(
env: EnvOption = 'dev',
output: OutputOption = 'text',
sample_limit: Annotated[int, typer.Option('--sample-limit', min=1, help='问题示例键名输出上限')] = 10,
) -> None:
"""
诊断参数配置数据库与缓存是否一致。
:param env: 当前命令运行环境
:param output: 输出格式
:param sample_limit: 问题示例键名输出上限
:return: None
"""
_CONFIG_COMMAND_CONTROLLER.doctor(env, output, sample_limit=sample_limit)
shierfeng-fastapi-backend/build/lib/cli/groups/config/controller.py
-225
View File
@@ -1,225 +0,0 @@
from typing import Literal
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
from cli.runtime.config import CONFIG_RUNTIME, ConfigRuntimeService
from .presenter import ConfigCommandPresenter
class ConfigCommandController:
"""
参数配置命令控制器。
该控制器负责组织 `config` 命令组的上下文准备、runtime 调用、
payload 注入，以及基于输出格式选择 presenter 或直接返回 JSON。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 参数配置命令文本渲染器
"""
def __init__(
self,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: ConfigCommandPresenter | None = None,
runtime_service: ConfigRuntimeService | None = None,
) -> None:
"""
初始化参数配置命令控制器。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 参数配置命令文本渲染器
:param runtime_service: 参数配置运行时服务
:return: None
"""
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or ConfigCommandPresenter()
self.runtime_service = runtime_service or CONFIG_RUNTIME
def list_configs(
self,
env: str,
output: str,
*,
config_name: str,
config_key: str,
config_type: Literal['Y', 'N'] | None,
begin_date: str,
end_date: str,
paged: bool,
page_num: int,
page_size: int,
) -> None:
"""
查看参数配置列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param config_name: 参数名称过滤条件
:param config_key: 参数键名过滤条件
:param config_type: 参数类型过滤条件
:param begin_date: 查询开始日期
:param end_date: 查询结束日期
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(
self.runtime_service.list_configs(
config_name=config_name,
config_key=config_key,
config_type=config_type,
begin_date=begin_date,
end_date=end_date,
paged=paged,
page_num=page_num,
page_size=page_size,
)
)
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_config_list_text,
text_condition=lambda data: data.get('ok', False),
)
def get_config(
self,
config_key: str,
env: str,
output: str,
*,
source: Literal['db', 'cache', 'both'],
) -> None:
"""
查看单个参数配置详情。
:param config_key: 需要查询的参数键名
:param env: 当前命令运行环境
:param output: 输出格式
:param source: 配置读取来源
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.runtime_service.get_config(config_key, source=source))
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_config_get_text,
text_condition=lambda data: data.get('ok', False),
)
def set_config(
self,
config_key: str,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
value: str,
name: str | None,
config_type: Literal['Y', 'N'] | None,
remark: str | None,
) -> None:
"""
新增或更新单个参数配置。
:param config_key: 需要写入的参数键名
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param value: 参数键值
:param name: 参数名称
:param config_type: 参数类型
:param remark: 参数备注
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='config set',
)
payload = self.execution_service.run_async(
self.runtime_service.set_config(
config_key,
value,
config_name=name,
config_type=config_type,
remark=remark,
dry_run=dry_run,
)
)
payload['env'] = ctx.env
self.execution_service.complete_payload(ctx, payload)
def sync_cache(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
) -> None:
"""
刷新参数配置缓存。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
False,
command_name='config sync-cache',
)
payload = self.execution_service.run_async(self.runtime_service.sync_config_cache())
payload['env'] = ctx.env
self.execution_service.complete_payload(ctx, payload)
def doctor(
self,
env: str,
output: str,
*,
sample_limit: int,
) -> None:
"""
诊断参数配置数据库与缓存是否一致。
:param env: 当前命令运行环境
:param output: 输出格式
:param sample_limit: 问题示例键名输出上限
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.runtime_service.diagnose_config(sample_limit=sample_limit))
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_config_doctor_text,
text_condition=lambda data: 'error' not in data,
)
shierfeng-fastapi-backend/build/lib/cli/groups/config/presenter.py
-180
View File
@@ -1,180 +0,0 @@
from cli.utils import SHELL_TEXT_FORMATTER
class ConfigCommandPresenter:
"""
参数配置命令文本渲染器。
该渲染器负责将 `config` 命令组产生的结构化 payload 转换为稳定的文本摘要，
同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
"""
def build_config_list_text(self, payload: dict[str, object]) -> str:
"""
将参数配置列表结果渲染为文本摘要。
:param payload: 参数配置列表结果字典
:return: 文本摘要
"""
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
]
filters = payload.get('filters')
if isinstance(filters, dict):
lines.extend(self._build_config_filter_lines(filters))
page_payload = payload.get('page')
if isinstance(page_payload, dict):
rows = page_payload.get('rows')
lines.append(
'page: '
f'{page_payload.get("pageNum", "-")}/{page_payload.get("pages", "-")} '
f'(page_size={page_payload.get("pageSize", "-")}, total={page_payload.get("total", "-")})'
)
lines.append(f'count: {len(rows) if isinstance(rows, list) else 0}')
if not isinstance(rows, list) or not rows:
lines.append('configs: none')
return '\n'.join(lines)
lines.append('configs:')
for row in rows:
if isinstance(row, dict):
lines.extend([f' {item}' for item in self._build_config_item_lines(row)])
return '\n'.join(lines)
items = payload.get('items')
lines.append(f'count: {payload.get("count", 0)}')
if not isinstance(items, list) or not items:
lines.append('configs: none')
return '\n'.join(lines)
lines.append('configs:')
for item in items:
if isinstance(item, dict):
lines.extend([f' {line}' for line in self._build_config_item_lines(item)])
return '\n'.join(lines)
def build_config_get_text(self, payload: dict[str, object]) -> str:
"""
将单个参数配置详情结果渲染为文本摘要。
:param payload: 参数配置详情结果字典
:return: 文本摘要
"""
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'key: {payload.get("key", "")}',
f'source: {payload.get("source", "")}',
]
if payload.get('source') == 'both':
lines.append(f'in_sync: {str(payload.get("inSync", False)).lower()}')
if payload.get('source') in {'db', 'both'}:
lines.extend(self._build_config_detail_section('database', payload.get('database')))
if payload.get('source') in {'cache', 'both'}:
lines.extend(self._build_config_detail_section('cache', payload.get('cache')))
return '\n'.join(lines)
def build_config_doctor_text(self, payload: dict[str, object]) -> str:
"""
将参数配置诊断结果渲染为文本摘要。
:param payload: 参数配置诊断结果字典
:return: 文本摘要
"""
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'message: {payload.get("message", "-")}',
f'database_count: {payload.get("databaseCount", 0)}',
f'cache_count: {payload.get("cacheCount", 0)}',
f'missing_in_cache_count: {payload.get("missingInCacheCount", 0)}',
f'orphan_in_cache_count: {payload.get("orphanInCacheCount", 0)}',
f'mismatch_count: {payload.get("mismatchCount", 0)}',
f'sample_limit: {payload.get("sampleLimit", 0)}',
]
lines.extend(self._build_config_doctor_items('missing_in_cache', payload.get('missingInCache')))
lines.extend(self._build_config_doctor_items('orphan_in_cache', payload.get('orphanInCache')))
lines.extend(self._build_config_doctor_items('mismatch_keys', payload.get('mismatchKeys')))
return '\n'.join(lines)
@staticmethod
def _build_config_filter_lines(filters: dict[str, object]) -> list[str]:
"""
构建参数配置过滤条件文本行。
:param filters: 过滤条件字典
:return: 过滤条件文本行列表
"""
active_filters = []
for key, value in filters.items():
if value in (None, '', False):
continue
active_filters.append(f'{SHELL_TEXT_FORMATTER.to_snake_case(key)}={value}')
if not active_filters:
return ['filters: none']
return ['filters:', *[f' - {item}' for item in active_filters]]
@staticmethod
def _build_config_item_lines(config_item: dict[str, object]) -> list[str]:
"""
构建单条参数配置记录的文本行。
:param config_item: 单条参数配置记录
:return: 文本行列表
"""
config_id = config_item.get('configId', '-')
config_key = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configKey', ''), 50)
config_name = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configName', ''), 24)
config_type = config_item.get('configType', '-')
config_value = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configValue', ''), 80)
remark = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('remark', ''), 60)
return [
f'- [{config_id}] {config_key} | 名称: {config_name} | 内置: {config_type}',
f' value: {config_value or "-"}',
f' remark: {remark or "-"}',
]
@staticmethod
def _build_config_detail_section(title: str, config_item: dict[str, object] | None) -> list[str]:
"""
构建单个配置来源的详情文本段落。
:param title: 段落标题
:param config_item: 配置详情字典
:return: 文本行列表
"""
if not isinstance(config_item, dict):
return [f'{title}: none']
config_key = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configKey', ''), 60)
config_name = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configName', ''), 30)
config_value = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('configValue', ''), 120)
config_type = config_item.get('configType', '-')
remark = SHELL_TEXT_FORMATTER.truncate_text(config_item.get('remark', ''), 80)
config_id = config_item.get('configId', '-')
return [
f'{title}:',
f' id: {config_id}',
f' key: {config_key or "-"}',
f' name: {config_name or "-"}',
f' value: {config_value or "-"}',
f' type: {config_type}',
f' remark: {remark or "-"}',
]
@staticmethod
def _build_config_doctor_items(title: str, items: list[object] | object) -> list[str]:
"""
构建配置诊断问题示例段落。
:param title: 段落标题
:param items: 问题键名列表
:return: 文本行列表
"""
if not isinstance(items, list) or not items:
return [f'{title}: none']
return [f'{title}:', *[f' - {item}' for item in items]]
shierfeng-fastapi-backend/build/lib/cli/groups/crypto/__init__.py
-3
View File
@@ -1,3 +0,0 @@
from .command import app
__all__ = ['app']
shierfeng-fastapi-backend/build/lib/cli/groups/crypto/command.py
-94
View File
@@ -1,94 +0,0 @@
import typer
from cli.context import AllowProdOption, DryRunOption, EnvOption, OutputOption, YesOption
from .controller import CryptoCommandController
app = typer.Typer(
help='传输加密相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
_CRYPTO_COMMAND_CONTROLLER = CryptoCommandController()
@app.command('validate', help='校验传输加密配置')
def validate(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
校验传输加密配置。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_CRYPTO_COMMAND_CONTROLLER.validate(env, output)
@app.command('keygen', help='生成新的传输加密密钥对')
def keygen(
env: EnvOption = 'dev',
output: OutputOption = 'text',
kid: str = typer.Option('default', '--kid', help='生成的密钥版本标识'),
key_size: int = typer.Option(2048, '--key-size', help='RSA 密钥长度'),
) -> None:
"""
生成新的传输加密密钥对。
:param env: 当前命令运行环境
:param output: 输出格式
:param kid: 生成的密钥版本标识
:param key_size: RSA 密钥长度
:return: None
"""
_CRYPTO_COMMAND_CONTROLLER.keygen(env, output, kid=kid, key_size=key_size)
@app.command('rotate', help='生成传输加密密钥轮换辅助结果')
def rotate(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
next_kid: str = typer.Option('rotated', '--next-kid', help='轮换后的新密钥版本标识'),
key_size: int = typer.Option(2048, '--key-size', help='新密钥的 RSA 长度'),
) -> None:
"""
生成传输加密密钥轮换辅助结果。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param next_kid: 轮换后的新密钥版本标识
:param key_size: 新密钥的 RSA 长度
:return: None
"""
_CRYPTO_COMMAND_CONTROLLER.rotate(
env,
output,
allow_prod,
yes,
dry_run,
next_kid=next_kid,
key_size=key_size,
)
@app.command('export-public', help='查看当前运行环境的公钥信息')
def export_public(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
导出当前运行环境的公钥信息。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_CRYPTO_COMMAND_CONTROLLER.export_public(env, output)
shierfeng-fastapi-backend/build/lib/cli/groups/crypto/controller.py
-125
View File
@@ -1,125 +0,0 @@
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
from cli.runtime.crypto import CRYPTO_RUNTIME, CryptoRuntimeService
from .presenter import CryptoCommandPresenter
class CryptoCommandController:
"""
传输加密命令控制器。
该控制器负责组织 `crypto` 命令组的上下文准备、runtime 调用、
payload 注入，以及基于输出格式选择 presenter 或直接返回 JSON。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 传输加密命令文本渲染器
"""
def __init__(
self,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: CryptoCommandPresenter | None = None,
runtime_service: CryptoRuntimeService | None = None,
) -> None:
"""
初始化传输加密命令控制器。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 传输加密命令文本渲染器
:param runtime_service: 传输加密运行时服务
:return: None
"""
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or CryptoCommandPresenter()
self.runtime_service = runtime_service or CRYPTO_RUNTIME
def validate(self, env: str, output: str) -> None:
"""
校验传输加密配置。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
self.execution_service.complete_payload(ctx, self.runtime_service.validate_crypto_config())
def keygen(self, env: str, output: str, *, kid: str, key_size: int) -> None:
"""
生成新的传输加密密钥对。
:param env: 当前命令运行环境
:param output: 输出格式
:param kid: 生成的密钥版本标识
:param key_size: RSA 密钥长度
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.runtime_service.generate_crypto_key_pair(kid, key_size)
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_crypto_keygen_text,
text_condition=lambda data: data.get('ok', False),
)
def rotate(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
next_kid: str,
key_size: int,
) -> None:
"""
生成传输加密密钥轮换辅助结果。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param next_kid: 轮换后的新密钥版本标识
:param key_size: 新密钥的 RSA 长度
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='crypto rotate',
)
self.execution_service.complete_payload(ctx, self.runtime_service.build_rotation_payload(next_kid, key_size))
def export_public(self, env: str, output: str) -> None:
"""
导出当前运行环境的公钥信息。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.runtime_service.export_public_key()
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_export_public_text,
text_condition=lambda data: data.get('ok', False),
)
shierfeng-fastapi-backend/build/lib/cli/groups/crypto/presenter.py
-79
View File
@@ -1,79 +0,0 @@
class CryptoCommandPresenter:
"""
传输加密命令文本渲染器。
该渲染器负责将 `crypto` 命令组产生的结构化 payload 转换为稳定的文本摘要，
同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
"""
def build_crypto_keygen_text(self, payload: dict[str, object]) -> str:
"""
将密钥生成结果渲染为文本摘要。
:param payload: 密钥生成结果字典
:return: 文本摘要
"""
env_patch = payload.get('envPatch')
env_patch_keys = sorted(env_patch.keys()) if isinstance(env_patch, dict) else []
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'kid: {payload.get("kid", "-")}',
f'key_size: {payload.get("keySize", "-")}',
]
lines.extend(self._build_multiline_block('public_key', payload.get('publicKey')))
lines.extend(self._build_multiline_block('private_key', payload.get('privateKey')))
if env_patch_keys:
lines.append('env_patch_keys:')
lines.extend(f' - {key}' for key in env_patch_keys)
else:
lines.append('env_patch_keys: none')
return '\n'.join(lines)
def build_export_public_text(self, payload: dict[str, object]) -> str:
"""
将公钥导出结果渲染为文本摘要。
:param payload: 公钥导出结果字典
:return: 文本摘要
"""
public_key_payload = payload.get('publicKey')
if not isinstance(public_key_payload, dict):
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
'public_key: none',
]
)
supported_kids = public_key_payload.get('supportedKids')
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'kid: {public_key_payload.get("kid", "-")}',
f'alg: {public_key_payload.get("alg", "-")}',
f'envelope_version: {public_key_payload.get("envelopeVersion", "-")}',
f'expire_at: {public_key_payload.get("expireAt", "-")}',
]
if isinstance(supported_kids, list) and supported_kids:
lines.append('supported_kids:')
lines.extend(f' - {kid}' for kid in supported_kids)
else:
lines.append('supported_kids: none')
lines.extend(self._build_multiline_block('public_key_pem', public_key_payload.get('publicKey')))
return '\n'.join(lines)
@staticmethod
def _build_multiline_block(title: str, value: object) -> list[str]:
"""
将多行文本构建为带标题的块级文本。
:param title: 块标题
:param value: 原始文本值
:return: 文本行列表
"""
text = '' if value is None else str(value).strip()
if not text:
return [f'{title}: -']
return [f'{title}:', ' |', *[f' {line}' for line in text.splitlines()]]
shierfeng-fastapi-backend/build/lib/cli/groups/db/__init__.py
-3
View File
@@ -1,3 +0,0 @@
from .command import app
__all__ = ['app']
shierfeng-fastapi-backend/build/lib/cli/groups/db/command.py
-191
View File
@@ -1,191 +0,0 @@
from typing import Annotated
import typer
from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY
from cli.context import AllowProdOption, DryRunOption, EnvOption, OutputOption, YesOption
from .controller import DbCommandController
app = typer.Typer(
help='数据库相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
_DB_COMMAND_CONTROLLER = DbCommandController()
@app.command('check', help='检查数据库连接状态')
def check(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
检查数据库连接状态。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_DB_COMMAND_CONTROLLER.check(env, output)
@app.command('current', help='查看当前数据库迁移版本')
def current(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
查看数据库当前迁移版本。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_DB_COMMAND_CONTROLLER.current(env, output)
@app.command('upgrade', help='执行数据库升级')
def upgrade(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
revision: Annotated[
str,
typer.Option(
'--revision',
help='目标迁移版本',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_alembic_revisions,
),
] = 'head',
) -> None:
"""
执行数据库升级。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param revision: 目标迁移版本
:return: None
"""
_DB_COMMAND_CONTROLLER.upgrade(env, output, allow_prod, yes, dry_run, revision=revision)
@app.command('init', help='初始化数据库到最新迁移版本')
def init(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
) -> None:
"""
初始化数据库到最新迁移版本。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:return: None
"""
_DB_COMMAND_CONTROLLER.init(env, output, allow_prod, yes, dry_run)
@app.command('downgrade', help='执行数据库回退')
def downgrade(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
revision: Annotated[
str,
typer.Option(
'--revision',
help='目标回退版本',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_alembic_revisions,
),
] = '-1',
) -> None:
"""
执行数据库回退。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param revision: 目标回退版本
:return: None
"""
_DB_COMMAND_CONTROLLER.downgrade(env, output, allow_prod, yes, dry_run, revision=revision)
@app.command('revision', help='创建新的数据库迁移版本文件')
def revision(
message: Annotated[str, typer.Option('--message', '-m', help='迁移说明')],
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
autogenerate: bool = typer.Option(False, '--autogenerate/--no-autogenerate', help='是否自动生成迁移内容'),
) -> None:
"""
创建新的数据库迁移版本文件。
:param message: 迁移说明
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param autogenerate: 是否自动生成迁移内容
:return: None
"""
_DB_COMMAND_CONTROLLER.revision(
message,
env,
output,
allow_prod,
yes,
dry_run,
autogenerate=autogenerate,
)
@app.command('heads', help='查看当前代码仓库中的 Alembic heads')
def heads(
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
查看当前代码仓库中的 Alembic heads。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_DB_COMMAND_CONTROLLER.heads(env, output)
@app.command('history', help='查看当前代码仓库中的 Alembic 历史版本')
def history(
env: EnvOption = 'dev',
output: OutputOption = 'text',
limit: Annotated[int, typer.Option('--limit', min=1, help='输出的最大历史记录数量')] = 20,
) -> None:
"""
查看当前代码仓库中的 Alembic 历史版本。
:param env: 当前命令运行环境
:param output: 输出格式
:param limit: 输出的最大历史记录数量
:return: None
"""
_DB_COMMAND_CONTROLLER.history(env, output, limit=limit)
shierfeng-fastapi-backend/build/lib/cli/groups/db/controller.py
-237
View File
@@ -1,237 +0,0 @@
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
from cli.runtime.db import DATABASE_RUNTIME, DatabaseRuntimeService
from .presenter import DbCommandPresenter
class DbCommandController:
"""
数据库命令控制器。
该控制器负责组织 `db` 命令组的上下文准备、runtime 调用、
payload 注入，以及基于输出格式选择 presenter 或直接返回 JSON。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 数据库命令文本渲染器
"""
def __init__(
self,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: DbCommandPresenter | None = None,
runtime_service: DatabaseRuntimeService | None = None,
) -> None:
"""
初始化数据库命令控制器。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 数据库命令文本渲染器
:param runtime_service: 数据库运行时服务
:return: None
"""
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or DbCommandPresenter()
self.runtime_service = runtime_service or DATABASE_RUNTIME
def check(self, env: str, output: str) -> None:
"""
检查数据库连接状态。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
self.execution_service.complete_payload(
ctx, self.execution_service.run_async(self.runtime_service.ping_database())
)
def current(self, env: str, output: str) -> None:
"""
查看数据库当前迁移版本。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.runtime_service.get_current_revision()
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_current_revision_text,
text_condition=lambda result_data: bool(result_data.get('ok', False)),
)
def upgrade(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
revision: str,
) -> None:
"""
执行数据库升级。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param revision: 目标迁移版本
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='db upgrade',
)
self.execution_service.complete_payload(ctx, self.runtime_service.upgrade_database(revision, dry_run=dry_run))
def init(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
) -> None:
"""
初始化数据库到最新迁移版本。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='db init',
)
self.execution_service.complete_payload(ctx, self.runtime_service.init_database(dry_run=dry_run))
def downgrade(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
revision: str,
) -> None:
"""
执行数据库回退。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param revision: 目标回退版本
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='db downgrade',
)
self.execution_service.complete_payload(ctx, self.runtime_service.downgrade_database(revision, dry_run=dry_run))
def revision(
self,
message: str,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
autogenerate: bool,
) -> None:
"""
创建新的数据库迁移版本文件。
:param message: 迁移说明
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param autogenerate: 是否自动生成迁移内容
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='db revision',
)
self.execution_service.complete_payload(
ctx,
self.runtime_service.create_revision(message, autogenerate=autogenerate, dry_run=dry_run),
)
def heads(self, env: str, output: str) -> None:
"""
查看当前代码仓库中的 Alembic heads。
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.runtime_service.get_alembic_heads()
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_alembic_revisions_text,
text_condition=lambda result_data: 'error' not in result_data,
)
def history(self, env: str, output: str, *, limit: int) -> None:
"""
查看当前代码仓库中的 Alembic 历史版本。
:param env: 当前命令运行环境
:param output: 输出格式
:param limit: 输出的最大历史记录数量
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.runtime_service.get_alembic_history(limit=limit)
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_alembic_revisions_text,
text_condition=lambda result_data: 'error' not in result_data,
)
shierfeng-fastapi-backend/build/lib/cli/groups/db/presenter.py
-71
View File
@@ -1,71 +0,0 @@
class DbCommandPresenter:
"""
数据库命令文本渲染器。
该渲染器负责将 `db` 命令组产生的结构化 payload 转换为稳定的文本摘要，
同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
"""
@staticmethod
def build_current_revision_text(payload: dict[str, object]) -> str:
"""
将数据库当前迁移版本结果渲染为文本摘要。
:param payload: 当前迁移版本结果字典
:return: 文本摘要
"""
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'current_revision: {payload.get("currentRevision", "-")}',
]
)
def build_alembic_revisions_text(self, payload: dict[str, object]) -> str:
"""
将 Alembic 修订版本结果渲染为文本摘要。
:param payload: 修订版本结果字典
:return: 文本摘要
"""
items = payload.get('items')
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'message: {payload.get("message", "-")}',
f'count: {payload.get("count", 0)}',
]
if 'totalCount' in payload:
lines.append(f'total_count: {payload.get("totalCount", 0)}')
if 'limit' in payload:
lines.append(f'limit: {payload.get("limit", 0)}')
if not isinstance(items, list) or not items:
lines.append('items: none')
return '\n'.join(lines)
lines.append('items:')
for item in items:
if isinstance(item, dict):
lines.extend([f' {line}' for line in self._build_alembic_revision_item_lines(item)])
return '\n'.join(lines)
@staticmethod
def _build_alembic_revision_item_lines(revision_item: dict[str, object]) -> list[str]:
"""
构建单个 Alembic 修订版本的文本行。
:param revision_item: 修订版本结果字典
:return: 文本行列表
"""
down_revisions = revision_item.get('downRevisions')
branch_labels = revision_item.get('branchLabels')
depends_on = revision_item.get('dependsOn')
return [
f'- revision: {revision_item.get("revision", "-")}',
f' down_revisions: {",".join(down_revisions) if isinstance(down_revisions, list) and down_revisions else "-"}',
f' branch_labels: {",".join(branch_labels) if isinstance(branch_labels, list) and branch_labels else "-"}',
f' depends_on: {",".join(depends_on) if isinstance(depends_on, list) and depends_on else "-"}',
f' doc: {revision_item.get("doc", "") or "-"}',
f' path: {revision_item.get("path", "-")}',
]
shierfeng-fastapi-backend/build/lib/cli/groups/dev/__init__.py
-3
View File
@@ -1,3 +0,0 @@
from .command import app
__all__ = ['app']
shierfeng-fastapi-backend/build/lib/cli/groups/dev/command.py
-74
View File
@@ -1,74 +0,0 @@
from typing import Annotated
import typer
from cli.context import EnvOption, OutputOption
from .controller import DevCommandController
app = typer.Typer(
help='开发相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
_DEV_COMMAND_CONTROLLER = DevCommandController()
@app.command('lint', help='执行 Ruff 格式化与静态检查')
def lint(
targets: Annotated[list[str] | None, typer.Argument(help='待检查路径，可传多个')] = None,
env: EnvOption = 'dev',
output: OutputOption = 'text',
check_only: bool = typer.Option(False, '--check-only', help='仅检查，不写回格式化结果'),
fix: bool = typer.Option(False, '--fix', help='执行 ruff check --fix'),
unsafe_fixes: bool = typer.Option(False, '--unsafe-fixes', help='允许 Ruff 不安全修复'),
) -> None:
"""
执行 Ruff 格式化与静态检查。
:param targets: 待检查路径列表
:param env: 当前命令运行环境
:param output: 输出格式
:param check_only: 是否仅检查不写回
:param fix: 是否自动修复可修复问题
:param unsafe_fixes: 是否允许不安全修复
:return: None
"""
_DEV_COMMAND_CONTROLLER.lint(
targets,
env,
output,
check_only=check_only,
fix=fix,
unsafe_fixes=unsafe_fixes,
)
@app.command('test', help='执行项目测试')
def test(
targets: Annotated[list[str] | None, typer.Argument(help='待执行的测试路径，可传多个')] = None,
env: EnvOption = 'dev',
output: OutputOption = 'text',
keyword: str = typer.Option('', '--keyword', '-k', help='pytest -k 过滤表达式'),
maxfail: int = typer.Option(0, '--maxfail', min=0, help='最大失败数，0 表示不限制'),
quiet: bool = typer.Option(False, '--quiet', '-q', help='启用简洁输出'),
) -> None:
"""
执行项目测试。
:param targets: 测试目标路径列表
:param env: 当前命令运行环境
:param output: 输出格式
:param keyword: pytest 关键字过滤表达式
:param maxfail: 最大失败数
:param quiet: 是否启用简洁输出
:return: None
"""
_DEV_COMMAND_CONTROLLER.test(
targets,
env,
output,
keyword=keyword,
maxfail=maxfail,
quiet=quiet,
)
shierfeng-fastapi-backend/build/lib/cli/groups/dev/controller.py
-103
View File
@@ -1,103 +0,0 @@
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
from cli.runtime.dev import DEVELOPMENT_RUNTIME, DevelopmentRuntimeService
from .presenter import DevCommandPresenter
class DevCommandController:
"""
开发命令控制器。
该控制器负责组织 `dev` 命令组的上下文准备、runtime 调用、
payload 注入，以及基于输出格式选择 presenter 或直接返回 JSON。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 开发命令文本渲染器
"""
def __init__(
self,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: DevCommandPresenter | None = None,
runtime_service: DevelopmentRuntimeService | None = None,
) -> None:
"""
初始化开发命令控制器。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 开发命令文本渲染器
:param runtime_service: 开发运行时服务
:return: None
"""
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or DevCommandPresenter()
self.runtime_service = runtime_service or DEVELOPMENT_RUNTIME
def lint(
self,
targets: list[str] | None,
env: str,
output: str,
*,
check_only: bool,
fix: bool,
unsafe_fixes: bool,
) -> None:
"""
执行 Ruff 格式化与静态检查。
:param targets: 待检查路径列表
:param env: 当前命令运行环境
:param output: 输出格式
:param check_only: 是否仅检查不写回
:param fix: 是否自动修复可修复问题
:param unsafe_fixes: 是否允许不安全修复
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.runtime_service.run_lint(targets, check_only=check_only, fix=fix, unsafe_fixes=unsafe_fixes)
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_dev_lint_text,
)
def test(
self,
targets: list[str] | None,
env: str,
output: str,
*,
keyword: str,
maxfail: int,
quiet: bool,
) -> None:
"""
执行项目测试。
:param targets: 测试目标路径列表
:param env: 当前命令运行环境
:param output: 输出格式
:param keyword: pytest 关键字过滤表达式
:param maxfail: 最大失败数
:param quiet: 是否启用简洁输出
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.runtime_service.run_tests(targets, keyword=keyword, maxfail=maxfail, quiet=quiet)
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_dev_test_text,
)
shierfeng-fastapi-backend/build/lib/cli/groups/dev/presenter.py
-96
View File
@@ -1,96 +0,0 @@
class DevCommandPresenter:
"""
开发命令文本渲染器。
该渲染器负责将 `dev` 命令组产生的结构化 payload 转换为稳定的文本摘要，
同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
"""
def build_dev_lint_text(self, payload: dict[str, object]) -> str:
"""
将 lint 执行结果渲染为文本摘要。
:param payload: lint 执行结果字典
:return: 文本摘要
"""
targets = payload.get('targets')
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'check_only: {str(payload.get("checkOnly", False)).lower()}',
f'fix: {str(payload.get("fix", False)).lower()}',
f'unsafe_fixes: {str(payload.get("unsafeFixes", False)).lower()}',
]
if isinstance(targets, list) and targets:
lines.append('targets:')
lines.extend(f' - {target}' for target in targets)
else:
lines.append('targets: none')
lines.extend(self._build_command_result_section('format', payload.get('format')))
lines.extend(self._build_command_result_section('check', payload.get('check')))
return '\n'.join(lines)
def build_dev_test_text(self, payload: dict[str, object]) -> str:
"""
将测试执行结果渲染为文本摘要。
:param payload: 测试执行结果字典
:return: 文本摘要
"""
targets = payload.get('targets')
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'keyword: {payload.get("keyword", "") or "-"}',
f'maxfail: {payload.get("maxfail", 0)}',
f'quiet: {str(payload.get("quiet", False)).lower()}',
]
if isinstance(targets, list) and targets:
lines.append('targets:')
lines.extend(f' - {target}' for target in targets)
else:
lines.append('targets: none')
lines.extend(self._build_command_result_section('test', payload.get('test')))
return '\n'.join(lines)
@staticmethod
def _build_command_result_section(title: str, payload: dict[str, object] | None) -> list[str]:
"""
构建单个子命令执行结果段落。
:param title: 段落标题
:param payload: 子命令执行结果
:return: 文本行列表
"""
if not isinstance(payload, dict):
return [f'{title}: none']
lines = [
f'{title}:',
f' ok: {str(payload.get("ok", False)).lower()}',
f' return_code: {payload.get("returnCode", "-")}',
f' command: {DevCommandPresenter._format_command_text(payload.get("command"))}',
]
stdout = payload.get('stdout')
stderr = payload.get('stderr')
if stdout:
lines.append(' stdout:')
lines.append(' |')
lines.extend(f' {line}' for line in str(stdout).splitlines())
if stderr:
lines.append(' stderr:')
lines.append(' |')
lines.extend(f' {line}' for line in str(stderr).splitlines())
return lines
@staticmethod
def _format_command_text(command: object) -> str:
"""
将命令参数列表格式化为可读文本。
:param command: 命令参数列表
:return: 格式化后的命令文本
"""
if not isinstance(command, list):
return '-'
return ' '.join(str(item) for item in command) or '-'
shierfeng-fastapi-backend/build/lib/cli/groups/gen/__init__.py
-3
View File
@@ -1,3 +0,0 @@
from .command import app
__all__ = ['app']
shierfeng-fastapi-backend/build/lib/cli/groups/gen/command.py
-273
View File
@@ -1,273 +0,0 @@
from typing import Annotated, Literal
import typer
from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY
from cli.context import AllowProdOption, DryRunOption, EnvOption, OutputOption, YesOption
from .controller import GenCommandController
app = typer.Typer(
help='代码生成相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
_GEN_COMMAND_CONTROLLER = GenCommandController()
@app.command('import-table', help='导入数据库表到代码生成业务表')
def import_table(
table_names: Annotated[
list[str],
typer.Argument(
help='待导入的数据库表名，可传多个',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_gen_db_table_names,
),
],
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
) -> None:
"""
导入数据库表到代码生成业务表。
:param table_names: 待导入表名列表
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:return: None
"""
_GEN_COMMAND_CONTROLLER.import_table(
table_names,
env,
output,
allow_prod,
yes,
dry_run,
)
@app.command('list', help='查看代码生成业务表列表')
def list_command(
env: EnvOption = 'dev',
output: OutputOption = 'text',
table_name: str = typer.Option(
'',
'--table-name',
help='按表名称过滤',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_gen_table_names,
),
table_comment: str = typer.Option('', '--table-comment', help='按表描述过滤'),
paged: bool = typer.Option(False, '--paged/--no-paged', help='是否启用分页结果'),
page_num: int = typer.Option(1, '--page-num', min=1, help='分页页码'),
page_size: int = typer.Option(20, '--page-size', min=1, help='分页每页数量'),
) -> None:
"""
查看代码生成业务表列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param table_name: 表名称过滤条件
:param table_comment: 表描述过滤条件
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
_GEN_COMMAND_CONTROLLER.list_tables(
env,
output,
table_name=table_name,
table_comment=table_comment,
paged=paged,
page_num=page_num,
page_size=page_size,
)
@app.command('db-list', help='查看数据库中可导入的物理表列表')
def db_list(
env: EnvOption = 'dev',
output: OutputOption = 'text',
table_name: str = typer.Option(
'',
'--table-name',
help='按表名称过滤',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_gen_db_table_names,
),
table_comment: str = typer.Option('', '--table-comment', help='按表描述过滤'),
paged: bool = typer.Option(False, '--paged/--no-paged', help='是否启用分页结果'),
page_num: int = typer.Option(1, '--page-num', min=1, help='分页页码'),
page_size: int = typer.Option(20, '--page-size', min=1, help='分页每页数量'),
) -> None:
"""
查看数据库中可导入的物理表列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param table_name: 表名称过滤条件
:param table_comment: 表描述过滤条件
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
_GEN_COMMAND_CONTROLLER.list_db_tables(
env,
output,
table_name=table_name,
table_comment=table_comment,
paged=paged,
page_num=page_num,
page_size=page_size,
)
@app.command('detail', help='查看单个代码生成业务表详情')
def detail(
table_id: Annotated[int, typer.Argument(help='业务表 ID')],
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
查看单个代码生成业务表详情。
:param table_id: 业务表 ID
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_GEN_COMMAND_CONTROLLER.show_detail(table_id, env, output)
@app.command('create-table', help='根据建表 SQL 创建表结构并导入代码生成业务表')
def create_table(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
sql: str = typer.Option('', '--sql', help='直接传入建表 SQL 文本'),
sql_file: str = typer.Option(
'',
'--sql-file',
help='从文件读取建表 SQL',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_sql_files,
),
) -> None:
"""
根据建表 SQL 创建表结构并导入代码生成业务表。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param sql: 直接传入的 SQL 文本
:param sql_file: SQL 文件路径
:return: None
"""
_GEN_COMMAND_CONTROLLER.create_table(
env,
output,
allow_prod,
yes,
dry_run,
sql=sql,
sql_file=sql_file,
)
@app.command('preview', help='查看指定业务表的代码生成结果预览')
def preview(
table_id: Annotated[int, typer.Argument(help='业务表 ID')],
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
预览指定业务表的代码生成结果。
:param table_id: 业务表 ID
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_GEN_COMMAND_CONTROLLER.preview(table_id, env, output)
@app.command('export', help='导出代码生成结果')
def export(
table_names: Annotated[
list[str],
typer.Argument(
help='待导出的业务表名，可传多个',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_gen_table_names,
),
],
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
dry_run: DryRunOption = False,
mode: Annotated[Literal['zip', 'local'], typer.Option('--mode', help='导出模式')] = 'zip',
output_file: str = typer.Option(
'',
'--output-file',
help='zip 导出目标文件路径',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_output_paths,
),
) -> None:
"""
导出代码生成结果。
:param table_names: 业务表名称列表
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param mode: 导出模式
:param output_file: zip 导出目标文件路径
:return: None
"""
_GEN_COMMAND_CONTROLLER.export(
table_names,
env,
output,
allow_prod,
yes,
dry_run,
mode=mode,
output_file=output_file,
)
@app.command('sync-db', help='同步指定业务表的数据库表结构')
def sync_db(
table_name: Annotated[
str,
typer.Argument(
help='业务表名称',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_gen_table_names,
),
],
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
) -> None:
"""
同步指定业务表的数据库表结构。
:param table_name: 业务表名称
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
_GEN_COMMAND_CONTROLLER.sync_db(table_name, env, output, allow_prod, yes)
shierfeng-fastapi-backend/build/lib/cli/groups/gen/controller.py
-304
View File
@@ -1,304 +0,0 @@
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
from cli.runtime.gen import GEN_RUNTIME, GenRuntimeService
from .presenter import GenCommandPresenter
class GenCommandController:
"""
代码生成命令控制器。
该控制器负责组织 `gen` 命令组的上下文准备、runtime 调用、
payload 注入，以及基于输出格式选择 presenter 或直接返回 JSON。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 代码生成命令文本渲染器
"""
def __init__(
self,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: GenCommandPresenter | None = None,
runtime_service: GenRuntimeService | None = None,
) -> None:
"""
初始化代码生成命令控制器。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 代码生成命令文本渲染器
:param runtime_service: 代码生成运行时服务
:return: None
"""
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or GenCommandPresenter()
self.runtime_service = runtime_service or GEN_RUNTIME
def import_table(
self,
table_names: list[str],
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
) -> None:
"""
导入数据库表到代码生成业务表。
:param table_names: 待导入表名列表
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='gen import-table',
)
payload = self.execution_service.run_async(self.runtime_service.import_tables(table_names, dry_run=dry_run))
payload['env'] = ctx.env
self.execution_service.complete_payload(ctx, payload)
def list_tables(
self,
env: str,
output: str,
*,
table_name: str,
table_comment: str,
paged: bool,
page_num: int,
page_size: int,
) -> None:
"""
查看代码生成业务表列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param table_name: 表名称过滤条件
:param table_comment: 表描述过滤条件
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(
self.runtime_service.list_gen_tables(
table_name=table_name,
table_comment=table_comment,
paged=paged,
page_num=page_num,
page_size=page_size,
)
)
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=lambda data: self.presenter.build_gen_table_list_text(data, db_mode=False),
text_condition=lambda data: data.get('ok', False),
)
def list_db_tables(
self,
env: str,
output: str,
*,
table_name: str,
table_comment: str,
paged: bool,
page_num: int,
page_size: int,
) -> None:
"""
查看数据库中可导入的物理表列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param table_name: 表名称过滤条件
:param table_comment: 表描述过滤条件
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(
self.runtime_service.list_gen_db_tables(
table_name=table_name,
table_comment=table_comment,
paged=paged,
page_num=page_num,
page_size=page_size,
)
)
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=lambda data: self.presenter.build_gen_table_list_text(data, db_mode=True),
text_condition=lambda data: data.get('ok', False),
)
def show_detail(self, table_id: int, env: str, output: str) -> None:
"""
查看单个代码生成业务表详情。
:param table_id: 业务表 ID
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.runtime_service.get_gen_table_detail(table_id))
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_gen_detail_text,
text_condition=lambda data: 'error' not in data,
)
def create_table(
self,
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
sql: str,
sql_file: str,
) -> None:
"""
根据建表 SQL 创建表结构并导入代码生成业务表。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param sql: 直接传入的 SQL 文本
:param sql_file: SQL 文件路径
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='gen create-table',
)
payload = self.execution_service.run_async(self.runtime_service.create_tables(sql, sql_file, dry_run=dry_run))
payload['env'] = ctx.env
self.execution_service.complete_payload(ctx, payload)
def preview(self, table_id: int, env: str, output: str) -> None:
"""
预览指定业务表的代码生成结果。
:param table_id: 业务表 ID
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.runtime_service.preview_code(table_id))
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_gen_preview_text,
text_condition=lambda data: data.get('ok', False),
)
def export(
self,
table_names: list[str],
env: str,
output: str,
allow_prod: bool,
yes: bool,
dry_run: bool,
*,
mode: str,
output_file: str,
) -> None:
"""
导出代码生成结果。
:param table_names: 业务表名称列表
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:param dry_run: 是否演练执行
:param mode: 导出模式
:param output_file: zip 导出目标文件路径
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
dry_run,
command_name='gen export',
)
payload = self.execution_service.run_async(
self.runtime_service.export_code(table_names, mode=mode, output_file=output_file, dry_run=dry_run)
)
payload['env'] = ctx.env
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_gen_export_text,
text_condition=lambda data: data.get('ok', False),
)
def sync_db(
self,
table_name: str,
env: str,
output: str,
allow_prod: bool,
yes: bool,
) -> None:
"""
同步指定业务表的数据库表结构。
:param table_name: 业务表名称
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
ctx = self.context_factory.build_dangerous(
env,
output,
allow_prod,
yes,
False,
command_name='gen sync-db',
)
payload = self.execution_service.run_async(self.runtime_service.sync_gen_table_from_db(table_name))
payload['env'] = ctx.env
self.execution_service.complete_payload(ctx, payload)
shierfeng-fastapi-backend/build/lib/cli/groups/gen/presenter.py
-231
View File
@@ -1,231 +0,0 @@
from cli.utils import SHELL_TEXT_FORMATTER
class GenCommandPresenter:
"""
代码生成命令文本渲染器。
该渲染器负责将 `gen` 命令组产生的结构化 payload 转换为稳定的文本摘要，
同时保持 JSON 输出仍由控制器直接返回，不在此处做契约变形。
"""
def build_gen_preview_text(self, payload: dict[str, object]) -> str:
"""
将代码预览结果渲染为文本摘要。
:param payload: 代码预览结果字典
:return: 文本摘要
"""
preview_payload = payload.get('preview')
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'table_id: {payload.get("tableId", "-")}',
f'template_count: {payload.get("templateCount", 0)}',
]
if not isinstance(preview_payload, dict) or not preview_payload:
lines.append('templates: none')
return '\n'.join(lines)
lines.append('templates:')
for template_name, template_content in preview_payload.items():
lines.extend([f' {line}' for line in self._build_text_block(str(template_name), template_content)])
return '\n'.join(lines)
def build_gen_export_text(self, payload: dict[str, object]) -> str:
"""
将代码导出结果渲染为文本摘要。
:param payload: 代码导出结果字典
:return: 文本摘要
"""
table_names = payload.get('tableNames')
results = payload.get('results')
lines = [
f'ok: {str(payload.get("ok", False)).lower()}',
f'env: {payload.get("env", "")}',
f'mode: {payload.get("mode", "-")}',
f'dry_run: {str(payload.get("dryRun", False)).lower()}',
f'message: {payload.get("message", "-")}',
]
if isinstance(table_names, list) and table_names:
lines.append('table_names:')
lines.extend(f' - {table_name}' for table_name in table_names)
else:
lines.append('table_names: none')
if payload.get('outputFile'):
lines.append(f'output_file: {payload.get("outputFile")}')
if payload.get('genPath'):
lines.append(f'gen_path: {payload.get("genPath")}')
if payload.get('size') is not None:
lines.append(f'size: {payload.get("size")}')
if isinstance(results, list) and results:
lines.append('results:')
lines.extend(
f' - {item.get("tableName", "-")}: {str(item.get("ok", False)).lower()} | {item.get("message", "-")}'
for item in results
if isinstance(item, dict)
)
return '\n'.join(lines)
def build_gen_table_list_text(self, payload: dict[str, object], *, db_mode: bool = False) -> str:
"""
将代码生成表列表或数据库表列表渲染为文本摘要。
:param payload: 列表结果字典
:param db_mode: 是否为数据库物理表列表模式
:return: 文本摘要
"""
lines = [f'ok: {str(payload.get("ok", False)).lower()}']
filters = payload.get('filters')
if isinstance(filters, dict):
lines.extend(self._build_gen_filter_lines(filters))
page_payload = payload.get('page')
if isinstance(page_payload, dict):
rows = page_payload.get('rows', [])
lines.append(
'page: '
f'{page_payload.get("pageNum", "-")}/{page_payload.get("pages", "-")} '
f'(page_size={page_payload.get("pageSize", "-")}, total={page_payload.get("total", "-")})'
)
lines.append(f'count: {len(rows) if isinstance(rows, list) else 0}')
if not isinstance(rows, list) or not rows:
lines.append('items: none')
return '\n'.join(lines)
lines.append('items:')
for row in rows:
if isinstance(row, dict):
item_lines = (
self._build_gen_db_table_item_lines(row) if db_mode else self._build_gen_table_item_lines(row)
)
lines.extend([f' {item}' for item in item_lines])
return '\n'.join(lines)
items = payload.get('items')
lines.append(f'count: {payload.get("count", 0)}')
if not isinstance(items, list) or not items:
lines.append('items: none')
return '\n'.join(lines)
lines.append('items:')
for item in items:
if isinstance(item, dict):
item_lines = (
self._build_gen_db_table_item_lines(item) if db_mode else self._build_gen_table_item_lines(item)
)
lines.extend([f' {line}' for line in item_lines])
return '\n'.join(lines)
def build_gen_detail_text(self, payload: dict[str, object]) -> str:
"""
将代码生成业务表详情渲染为文本摘要。
:param payload: 详情结果字典
:return: 文本摘要
"""
detail = payload.get('detail')
if not isinstance(detail, dict):
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'table_id: {payload.get("tableId", "-")}',
'detail: none',
]
)
info = detail.get('info')
if not isinstance(info, dict):
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'table_id: {payload.get("tableId", "-")}',
'info: none',
]
)
return '\n'.join(
[
f'ok: {str(payload.get("ok", False)).lower()}',
f'table_id: {payload.get("tableId", "-")}',
f'table_name: {payload.get("tableName", "-")}',
f'column_count: {payload.get("columnCount", 0)}',
f'table_count: {payload.get("tableCount", 0)}',
f'table_comment: {SHELL_TEXT_FORMATTER.truncate_text(info.get("tableComment", ""), 80) or "-"}',
f'class_name: {info.get("className", "-")}',
f'tpl_category: {info.get("tplCategory", "-")}',
f'tpl_web_type: {info.get("tplWebType", "-")}',
f'package_name: {SHELL_TEXT_FORMATTER.truncate_text(info.get("packageName", ""), 80) or "-"}',
f'module_name: {info.get("moduleName", "-")}',
f'business_name: {info.get("businessName", "-")}',
f'function_name: {info.get("functionName", "-")}',
f'function_author: {info.get("functionAuthor", "-")}',
f'gen_type: {info.get("genType", "-")}',
f'gen_path: {SHELL_TEXT_FORMATTER.truncate_text(info.get("genPath", ""), 120) or "-"}',
f'remark: {SHELL_TEXT_FORMATTER.truncate_text(info.get("remark", ""), 160) or "-"}',
]
)
@staticmethod
def _build_text_block(title: str, value: object) -> list[str]:
"""
将多行文本构建为带标题的块级文本。
:param title: 块标题
:param value: 原始文本值
:return: 文本行列表
"""
text = '' if value is None else str(value)
if not text.strip():
return [f'{title}: -']
return [f'{title}:', ' |', *[f' {line}' for line in text.splitlines()]]
@staticmethod
def _build_gen_filter_lines(filters: dict[str, object]) -> list[str]:
"""
构建代码生成表过滤条件文本行。
:param filters: 过滤条件字典
:return: 过滤条件文本行列表
"""
active_filters = []
for key, value in filters.items():
if value in (None, '', False):
continue
active_filters.append(f'{SHELL_TEXT_FORMATTER.to_snake_case(key)}={value}')
if not active_filters:
return ['filters: none']
return ['filters:', *[f' - {item}' for item in active_filters]]
@staticmethod
def _build_gen_table_item_lines(table_item: dict[str, object]) -> list[str]:
"""
构建单条代码生成表记录的文本行。
:param table_item: 代码生成表记录
:return: 文本行列表
"""
return [
f'- [{table_item.get("tableId", "-")}] {SHELL_TEXT_FORMATTER.truncate_text(table_item.get("tableName", ""), 40) or "-"}',
f' comment: {SHELL_TEXT_FORMATTER.truncate_text(table_item.get("tableComment", ""), 60) or "-"}',
f' class_name: {table_item.get("className", "-")}',
f' tpl_category: {table_item.get("tplCategory", "-")} | module_name: {table_item.get("moduleName", "-")}',
f' business_name: {table_item.get("businessName", "-")} | function_name: {table_item.get("functionName", "-")}',
]
@staticmethod
def _build_gen_db_table_item_lines(table_item: dict[str, object]) -> list[str]:
"""
构建单条数据库物理表记录的文本行。
:param table_item: 数据库物理表记录
:return: 文本行列表
"""
return [
f'- {SHELL_TEXT_FORMATTER.truncate_text(table_item.get("tableName", ""), 48) or "-"}',
f' comment: {SHELL_TEXT_FORMATTER.truncate_text(table_item.get("tableComment", ""), 80) or "-"}',
f' create_time: {table_item.get("createTime", "-")}',
f' update_time: {table_item.get("updateTime", "-")}',
]
shierfeng-fastapi-backend/build/lib/cli/groups/job/__init__.py
-3
View File
@@ -1,3 +0,0 @@
from .command import app
__all__ = ['app']
shierfeng-fastapi-backend/build/lib/cli/groups/job/command.py
-216
View File
@@ -1,216 +0,0 @@
import typer
from cli.completion.providers import COMPLETION_PROVIDER_GATEWAY
from cli.context import AllowProdOption, EnvOption, OutputOption, YesOption
from .controller import JobCommandController
app = typer.Typer(
help='定时任务相关命令',
no_args_is_help=True,
context_settings={'help_option_names': ['-h', '--help']},
)
_JOB_COMMAND_CONTROLLER = JobCommandController()
@app.command('list', help='查看定时任务列表')
def list_command(
env: EnvOption = 'dev',
output: OutputOption = 'text',
job_name: str = typer.Option(
'',
'--job-name',
help='按任务名称过滤',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_job_names,
),
job_group: str = typer.Option('', '--job-group', help='按任务组过滤'),
status: str | None = typer.Option(None, '--status', help='按任务状态过滤，0正常 1暂停'),
paged: bool = typer.Option(False, '--paged/--no-paged', help='是否启用分页结果'),
page_num: int = typer.Option(1, '--page-num', min=1, help='分页页码'),
page_size: int = typer.Option(20, '--page-size', min=1, help='分页每页数量'),
) -> None:
"""
查看定时任务列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param job_name: 任务名称过滤条件
:param job_group: 任务组过滤条件
:param status: 状态过滤条件
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
_JOB_COMMAND_CONTROLLER.list(
env,
output,
job_name=job_name,
job_group=job_group,
status=status,
paged=paged,
page_num=page_num,
page_size=page_size,
)
@app.command('run-once', help='执行一次定时任务')
def run_once(
job_id: int = typer.Argument(
...,
help='任务ID',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_job_ids,
),
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
) -> None:
"""
执行一次定时任务。
:param job_id: 任务ID
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
_JOB_COMMAND_CONTROLLER.run_once(job_id, env, output, allow_prod, yes)
@app.command('detail', help='查看单个定时任务详情')
def detail(
job_id: int = typer.Argument(
...,
help='任务ID',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_job_ids,
),
env: EnvOption = 'dev',
output: OutputOption = 'text',
) -> None:
"""
查看单个定时任务详情。
:param job_id: 任务ID
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
_JOB_COMMAND_CONTROLLER.detail(job_id, env, output)
@app.command('logs', help='查看定时任务执行日志列表')
def logs(
env: EnvOption = 'dev',
output: OutputOption = 'text',
job_name: str = typer.Option(
'',
'--job-name',
help='按任务名称过滤',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_job_names,
),
job_group: str = typer.Option('', '--job-group', help='按任务组过滤'),
status: str | None = typer.Option(None, '--status', help='按执行状态过滤，0成功 1失败'),
begin_date: str = typer.Option('', '--begin-date', help='按创建时间开始日期过滤，格式 YYYY-MM-DD'),
end_date: str = typer.Option('', '--end-date', help='按创建时间结束日期过滤，格式 YYYY-MM-DD'),
paged: bool = typer.Option(False, '--paged/--no-paged', help='是否启用分页结果'),
page_num: int = typer.Option(1, '--page-num', min=1, help='分页页码'),
page_size: int = typer.Option(20, '--page-size', min=1, help='分页每页数量'),
) -> None:
"""
查看定时任务执行日志列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param job_name: 任务名称过滤条件
:param job_group: 任务组过滤条件
:param status: 执行状态过滤条件
:param begin_date: 查询开始日期
:param end_date: 查询结束日期
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
_JOB_COMMAND_CONTROLLER.logs(
env,
output,
job_name=job_name,
job_group=job_group,
status=status,
begin_date=begin_date,
end_date=end_date,
paged=paged,
page_num=page_num,
page_size=page_size,
)
@app.command('pause', help='暂停定时任务')
def pause(
job_id: int = typer.Argument(
...,
help='任务ID',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_job_ids,
),
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
) -> None:
"""
暂停定时任务。
:param job_id: 任务ID
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
_JOB_COMMAND_CONTROLLER.pause(job_id, env, output, allow_prod, yes)
@app.command('resume', help='恢复定时任务')
def resume(
job_id: int = typer.Argument(
...,
help='任务ID',
autocompletion=COMPLETION_PROVIDER_GATEWAY.complete_job_ids,
),
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
) -> None:
"""
恢复定时任务。
:param job_id: 任务ID
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
_JOB_COMMAND_CONTROLLER.resume(job_id, env, output, allow_prod, yes)
@app.command('sync', help='同步调度任务配置')
def sync(
env: EnvOption = 'dev',
output: OutputOption = 'text',
allow_prod: AllowProdOption = False,
yes: YesOption = False,
) -> None:
"""
同步调度任务配置。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
_JOB_COMMAND_CONTROLLER.sync(env, output, allow_prod, yes)
shierfeng-fastapi-backend/build/lib/cli/groups/job/controller.py
-221
View File
@@ -1,221 +0,0 @@
from cli.core import (
DEFAULT_CORE_SERVICES,
CliContextFactory,
CliExecutionService,
)
from cli.runtime.job import JOB_RUNTIME, JobRuntimeService
from cli.runtime.ops import OPERATIONS_RUNTIME, OperationsRuntimeService
from .presenter import JobCommandPresenter
class JobCommandController:
"""
定时任务命令控制器。
该控制器负责组织 `job` 命令组的上下文准备、runtime 调用、
payload 注入，以及基于输出格式选择 presenter 或直接返回 JSON。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 定时任务命令文本渲染器
"""
def __init__(
self,
*,
context_factory: CliContextFactory | None = None,
execution_service: CliExecutionService | None = None,
presenter: JobCommandPresenter | None = None,
operations_runtime: OperationsRuntimeService | None = None,
job_runtime: JobRuntimeService | None = None,
) -> None:
"""
初始化定时任务命令控制器。
:param context_factory: CLI 上下文工厂
:param execution_service: CLI 执行服务
:param presenter: 定时任务命令文本渲染器
:param operations_runtime: 运维运行时服务
:param job_runtime: 定时任务运行时服务
:return: None
"""
self.context_factory = context_factory or DEFAULT_CORE_SERVICES.context_factory
self.execution_service = execution_service or DEFAULT_CORE_SERVICES.execution_service
self.presenter = presenter or JobCommandPresenter()
self.operations_runtime = operations_runtime or OPERATIONS_RUNTIME
self.job_runtime = job_runtime or JOB_RUNTIME
def list(
self,
env: str,
output: str,
*,
job_name: str,
job_group: str,
status: str | None,
paged: bool,
page_num: int,
page_size: int,
) -> None:
"""
查看定时任务列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param job_name: 任务名称过滤条件
:param job_group: 任务组过滤条件
:param status: 状态过滤条件
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(
self.job_runtime.list_jobs(
job_name=job_name,
job_group=job_group,
status=status,
paged=paged,
page_num=page_num,
page_size=page_size,
)
)
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_job_list_text,
text_condition=lambda result_data: bool(result_data.get('ok', False)),
)
def run_once(self, job_id: int, env: str, output: str, allow_prod: bool, yes: bool) -> None:
"""
执行一次定时任务。
:param job_id: 任务ID
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
ctx = self.context_factory.build_dangerous(env, output, allow_prod, yes, False, command_name='job run-once')
self.execution_service.complete_payload(
ctx, self.execution_service.run_async(self.job_runtime.run_job_once(job_id))
)
def detail(self, job_id: int, env: str, output: str) -> None:
"""
查看单个定时任务详情。
:param job_id: 任务ID
:param env: 当前命令运行环境
:param output: 输出格式
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(self.job_runtime.get_job_detail(job_id))
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_job_detail_text,
text_condition=lambda result_data: 'error' not in result_data,
)
def logs(
self,
env: str,
output: str,
*,
job_name: str,
job_group: str,
status: str | None,
begin_date: str,
end_date: str,
paged: bool,
page_num: int,
page_size: int,
) -> None:
"""
查看定时任务执行日志列表。
:param env: 当前命令运行环境
:param output: 输出格式
:param job_name: 任务名称过滤条件
:param job_group: 任务组过滤条件
:param status: 执行状态过滤条件
:param begin_date: 查询开始日期
:param end_date: 查询结束日期
:param paged: 是否启用分页
:param page_num: 页码
:param page_size: 每页数量
:return: None
"""
ctx = self.context_factory.build_readonly(env, output)
payload = self.execution_service.run_async(
self.job_runtime.list_job_logs(
job_name=job_name,
job_group=job_group,
status=status,
begin_date=begin_date,
end_date=end_date,
paged=paged,
page_num=page_num,
page_size=page_size,
)
)
self.execution_service.complete_payload_with_text(
ctx,
payload,
text_builder=self.presenter.build_job_logs_text,
text_condition=lambda result_data: bool(result_data.get('ok', False)),
)
def pause(self, job_id: int, env: str, output: str, allow_prod: bool, yes: bool) -> None:
"""
暂停定时任务。
:param job_id: 任务ID
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
ctx = self.context_factory.build_dangerous(env, output, allow_prod, yes, False, command_name='job pause')
self.execution_service.complete_payload(
ctx, self.execution_service.run_async(self.job_runtime.pause_job(job_id))
)
def resume(self, job_id: int, env: str, output: str, allow_prod: bool, yes: bool) -> None:
"""
恢复定时任务。
:param job_id: 任务ID
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
ctx = self.context_factory.build_dangerous(env, output, allow_prod, yes, False, command_name='job resume')
self.execution_service.complete_payload(
ctx, self.execution_service.run_async(self.job_runtime.resume_job(job_id))
)
def sync(self, env: str, output: str, allow_prod: bool, yes: bool) -> None:
"""
同步调度任务配置。
:param env: 当前命令运行环境
:param output: 输出格式
:param allow_prod: 是否允许生产环境危险命令
:param yes: 是否跳过确认
:return: None
"""
ctx = self.context_factory.build_dangerous(env, output, allow_prod, yes, False, command_name='job sync')
self.execution_service.complete_payload(
ctx,
self.execution_service.run_async(self.operations_runtime.sync_jobs()),
)

Some files were not shown because too many files have changed in this diff Show More