cisd/docs/plans/2026-03-10-tms-deployment-doc-plan.md

TMS Deployment Document Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Create a production-oriented TMS deployment manual that documents runtime files, directories, scripts, config, upload/fileId flow, and on-host verification for /home/tms deployments.

Architecture: Keep README.md as the short entry point and move the full operational content into a dedicated deployment manual under docs/deployment/. Reuse existing runtime scripts and config examples instead of duplicating logic, and align every section with the current init/fileId implementation.

Tech Stack: Markdown documentation, existing shell scripts, Spring Boot config examples

---

Task 1: Create deployment manual skeleton

Files:

• Create: /Users/waner/Work/CISD/文档/tms-framework/docs/deployment/tms-deployment.md
• Modify: /Users/waner/Work/CISD/文档/tms-framework/README.md

Step 1: Draft the document outline

Add section headers for:

• environment
• directory layout
• deployment artifacts
• config
• scripts
• file upload/fileId flow
• startup operations
• precheck
• troubleshooting

Step 2: Review against current repo assets

Verify each section maps to existing files:

• scripts/tms.sh
• scripts/standard-init/*.sh
• config/application.yml.example
• init/file upload config

Step 3: Write the initial manual content

Populate the outline with precise paths and commands using /home/tms.

Step 4: Link README to the new manual

Keep README concise and add a “see full deployment guide” link.

Task 2: Document deployment artifacts and directories

Files:

• Modify: /Users/waner/Work/CISD/文档/tms-framework/docs/deployment/tms-deployment.md

Step 1: Add directory tree

Document:

• /home/tms/tms-framework.jar
• /home/tms/config/application.yml
• /home/tms/scripts/tms.sh
• /home/tms/bin/*.sh
• /home/tms/uploads
• /home/tms/logs
• /home/tms/run
• /home/tms/tmp

Step 2: Add artifact source mapping

State where each deployed file comes from in the repo.

Step 3: Add deployment commands

Include copy/chmod commands required on CentOS.

Task 3: Document config and init dependencies

Files:

• Modify: /Users/waner/Work/CISD/文档/tms-framework/docs/deployment/tms-deployment.md
• Reference: /Users/waner/Work/CISD/文档/tms-framework/config/application.yml.example
• Reference: /Users/waner/Work/CISD/文档/tms-framework/src/main/resources/application.yml

Step 1: Document mandatory config items

Explain required runtime settings:

• security token
• upload directory
• init executor mode
• standard script commands
• staging/log directories

Step 2: Document standard-init scripts

Describe purpose and prerequisites of:

• apply_standard_db.sh
• start_standard_apps.sh
• start_standard_nginx.sh
• check_standard_runtime.sh

Step 3: Document credential handling

Clarify which credentials stay in pre-provisioned env vars instead of application.yml.

Task 4: Document file upload and fileId flow

Files:

• Modify: /Users/waner/Work/CISD/文档/tms-framework/docs/deployment/tms-deployment.md

Step 1: Describe upload-first workflow

State that init APIs do not accept multipart files and only accept fileId.

Step 2: Map init fields to uploaded files

Document:

• receiverLicenseFileId
• tlqLicenseFileId
• cfmqConfigFileId
• cfgZipFileId

Step 3: Explain storage layout

Describe /home/tms/uploads/<fileId>/<originalFilename> and how the init executor resolves files.

Task 5: Add operations and troubleshooting sections

Files:

• Modify: /Users/waner/Work/CISD/文档/tms-framework/docs/deployment/tms-deployment.md

Step 1: Add start/stop/status commands

Document tms.sh usage and log locations.

Step 2: Add precheck guidance

Reference scripts/cisd_init_precheck.sh and describe expected pass/fail output.

Step 3: Add troubleshooting cases

Document diagnosis steps for:

• standardDbApplyCommand is blank
• cpconfig not found
• uploaded file not found by fileId
• RabbitMQ command/path errors
• WEB/NGINX publish/start issues

Task 6: Final review

Files:

• Verify only

Step 1: Read the final manual top to bottom

Check for mismatches against current code/scripts/config.

Step 2: Review focused diff

Run: git diff -- README.md docs/deployment/tms-deployment.md Expected: only deployment documentation changes.