|
|
@@ -0,0 +1,89 @@
|
|
|
+# MCP Export Pending Outbound Orders Implementation Plan
|
|
|
+
|
|
|
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
+
|
|
|
+**Goal:** Expose the fmsoperate add-page “导出未排舱订单” workflow through MCP, including a permission-scoped filter-options tool that resolves user-facing names to valid values.
|
|
|
+
|
|
|
+**Architecture:** Python Gateway owns tool metadata, argument shape, and HTTP forwarding only. fmsoperate owns validation, tool registry checks, session-derived identity, permission-scoped option queries, and the existing synchronous export task. Both new tools use the established MCP response and access-log boundary.
|
|
|
+
|
|
|
+**Tech Stack:** Python 3 unittest, ThinkPHP 6/PHP 7.1+, MySQL ORM, Redis-backed MCP registry, existing export queue/OSS logic.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Task 1: Add Python tool contracts and red tests
|
|
|
+
|
|
|
+**Files:**
|
|
|
+- Create: `Y:/mcp/tools/export_pending_outbound_orders.py`
|
|
|
+- Create: `Y:/mcp/tools/list_pending_outbound_export_filter_options.py`
|
|
|
+- Create: `Y:/mcp/tests/test_export_pending_outbound_tools.py`
|
|
|
+- Modify: `Y:/mcp/app.py`
|
|
|
+- Modify: `Y:/mcp/public_gateway.py`
|
|
|
+
|
|
|
+- [ ] **Step 1: Write failing tests** for both tool metadata contracts, all add-page filter names, the three multi-select representations, `is_remove=0` preservation, product-type dependency forwarding, and local/public registration.
|
|
|
+- [ ] **Step 2: Run the focused tests** with `python -m unittest tests.test_export_pending_outbound_tools`; confirm failure because the new tool modules and registrations do not exist.
|
|
|
+- [ ] **Step 3: Implement minimal Python tools** with explicit schemas, whitelist-based argument forwarding, route paths, and bounded pagination.
|
|
|
+- [ ] **Step 4: Register both tools** in `GatewayApp` and `PublicGatewayApp`, preserving dynamic enabled-tool filtering.
|
|
|
+- [ ] **Step 5: Run focused tests** and commit the Python contract changes.
|
|
|
+
|
|
|
+### Task 2: Add fmsoperate tool routes, validation, and registry migrations
|
|
|
+
|
|
|
+**Files:**
|
|
|
+- Modify: `Y:/fmsoperate/route/mcp/mcp_route.php`
|
|
|
+- Modify: `Y:/fmsoperate/app/mcp/validate/McpToolValidate.php`
|
|
|
+- Modify: `Y:/fmsoperate/sql/mcp_add_exact_order_tools.sql`
|
|
|
+- Create: `Y:/fmsoperate/sql/mcp_add_pending_outbound_export_tools.sql`
|
|
|
+- Create: `Y:/settlement_tests/tests/Unit/FmsOperate/McpPendingOutboundExportRegisterTest.php`
|
|
|
+
|
|
|
+- [ ] **Step 1: Write failing tests** asserting both routes, validation scenes, and idempotent registry rows with the exact tool codes and route codes.
|
|
|
+- [ ] **Step 2: Run the focused PHP test** with `php Y:/settlement_tests/bin/phpunit.phar -c Y:/settlement_tests/phpunit.xml --filter McpPendingOutboundExportRegisterTest`; confirm the new routes/scenes are absent.
|
|
|
+- [ ] **Step 3: Add route closures** for `exportPendingOutboundOrders` and `listPendingOutboundExportFilterOptions`, both behind `checkMcpToken`.
|
|
|
+- [ ] **Step 4: Add strict validation scenes** for page-native parameters, array/scalar distinctions, `Y` property flags, date format, pagination, and reject identity/internal fields by scene allow-listing.
|
|
|
+- [ ] **Step 5: Add repeatable SQL registry entries** with risk level 1, POST, correct route codes, enabled status, and permission-oriented remarks.
|
|
|
+- [ ] **Step 6: Run the focused PHP test and PHP lint** on changed files.
|
|
|
+
|
|
|
+### Task 3: Implement permission-scoped pending-export filter options
|
|
|
+
|
|
|
+**Files:**
|
|
|
+- Create: `Y:/fmsoperate/app/mcp/logic/McpPendingOutboundExportFilterOptionsLogic.php`
|
|
|
+- Modify: `Y:/fmsoperate/app/mcp/controller/McpToolsController.php`
|
|
|
+- Create: `Y:/settlement_tests/tests/Unit/FmsOperate/McpPendingOutboundExportFilterOptionsLogicTest.php`
|
|
|
+- Create: `Y:/settlement_tests/tests/Unit/FmsOperate/McpPendingOutboundExportFilterOptionsDispatchTest.php`
|
|
|
+
|
|
|
+- [ ] **Step 1: Write failing Logic tests** for each filter type, A/B company isolation, platform-customer product restriction, `country_auth`, empty country authorization, product-type narrowing, keyword-after-authorization, and static option values.
|
|
|
+- [ ] **Step 2: Run focused Logic tests** and confirm expected failures before production implementation.
|
|
|
+- [ ] **Step 3: Implement the Logic** using session-derived identity only and the same page data sources: `OutboundTypeModel`, `ProductModel`, `OrderModel::getSortWarehouse`, `getTcAddCountryCode` plus account country auth, company-scoped importer rows, packing dictionary, operate statuses, and goods attributes.
|
|
|
+- [ ] **Step 4: Apply keyword and pagination only after the authorized result set is built**; never query unrestricted values before filtering.
|
|
|
+- [ ] **Step 5: Add the controller method through `executeNewQueryTool`** so dynamic registry checks, request IDs, response envelopes, and access logs match existing tools.
|
|
|
+- [ ] **Step 6: Run focused PHP tests and lint** for the new Logic/controller.
|
|
|
+
|
|
|
+### Task 4: Implement export dispatch with page-native parameters
|
|
|
+
|
|
|
+**Files:**
|
|
|
+- Create: `Y:/fmsoperate/app/mcp/logic/McpPendingOutboundExportLogic.php`
|
|
|
+- Modify: `Y:/fmsoperate/app/mcp/controller/McpToolsController.php`
|
|
|
+- Create: `Y:/settlement_tests/tests/Unit/FmsOperate/McpPendingOutboundExportLogicTest.php`
|
|
|
+- Create: `Y:/settlement_tests/tests/Unit/FmsOperate/McpPendingOutboundExportDispatchTest.php`
|
|
|
+
|
|
|
+- [ ] **Step 1: Write failing tests** for whitelist filtering, fixed `EXPORT_PEND_OUTBOUND_ORDER`, fixed `is_sync=1`, session-derived timezone/company/operator fields, URL normalization to `file_url`, missing URL failure, and permission/tool-disabled rejection.
|
|
|
+- [ ] **Step 2: Run focused tests** and confirm they fail before implementation.
|
|
|
+- [ ] **Step 3: Implement Logic** to accept only the add-page fields, preserve arrays/string formats exactly, invoke the existing async export controller/service path, and normalize the successful URL without duplicating SQL or Excel code.
|
|
|
+- [ ] **Step 4: Add the controller method through the shared MCP execution boundary** with the dedicated route code and validation scene.
|
|
|
+- [ ] **Step 5: Run focused PHP tests and lint**.
|
|
|
+
|
|
|
+### Task 5: Complete Python integration and regression coverage
|
|
|
+
|
|
|
+**Files:**
|
|
|
+- Modify: `Y:/mcp/tests/test_app_coverage.py`
|
|
|
+- Modify: `Y:/mcp/tests/test_mcp_protocol.py`
|
|
|
+- Modify: `Y:/mcp/tests/test_public_gateway.py`
|
|
|
+- Modify: `Y:/mcp/tests/test_public_gateway_unit.py`
|
|
|
+- Modify: `Y:/mcp/tests/test_public_server_integration.py`
|
|
|
+- Modify: `Y:/mcp/project-docs/requirements.md`
|
|
|
+- Modify: `Y:/mcp/project-docs/timeline.md`
|
|
|
+
|
|
|
+- [ ] **Step 1: Add integration assertions** that tools/list exposes both tools only when the backend registry enables them, tools/call forwards the exact route/tool headers, and business errors become `isError=true` without JSON-RPC termination.
|
|
|
+- [ ] **Step 2: Run all focused Python tests** with `python -m unittest discover -s tests -p 'test_*pending*outbound*.py'` and the touched integration modules.
|
|
|
+- [ ] **Step 3: Run the complete Python suite** with `python -m unittest discover -s tests -p 'test_*.py'`.
|
|
|
+- [ ] **Step 4: Run PHP MCP regression tests** including existing query/order-filter tests and all new pending-export tests.
|
|
|
+- [ ] **Step 5: Update project requirements/timeline** with the delivered tools, permission guarantees, and verification results.
|
|
|
+- [ ] **Step 6: Run `git diff --check` in both repositories and record final test evidence before completion.
|
jackson