Document svc.sh comprehensively and layer its help system

Why:
svc.sh grew into a three-kind service manager with database operations,
but its only documentation was a flat --help wall of text; the user asked
for a complete usage document and a better help experience.

Evidence:
- docs/svc.md: 14-section manual (prerequisites, quick start, concepts
  and directory layout, per-command reference for service/global/db
  commands, deploy sources, database operations handbook, configuration
  layering, registry fields and event types, safety boundaries, exit
  codes, troubleshooting table, recipe index) — every claim cross-checked
  against the implementation from the previous two rounds.
- Help layering: no-args and -h print a one-screen overview; --help
  renders the header comment reorganized into 7 labeled sections; the new
  "help [topic]" command deep-dives eight topics (model, deploy,
  lifecycle, db, dbops, config, examples, safety); usage errors now show
  the short overview plus a pointer to --help / help / docs/svc.md.
  All topics verified to render; unknown topic exits 2.
- No runtime behavior changed: end-to-end db lifecycle regression
  (create → start → backup → status → stop → rm --purge) passes after the
  refactor.
- Makefile help and README's documentation section point to docs/svc.md.

Impact:
Documentation-only plus display-layer changes; command semantics,
exit codes and file formats are untouched. Maintenance note: behavior
changes must now update both --help and docs/svc.md.

Refs: .task/feature-svc-docs-help.md(任务卡=PR 描述)
This commit is contained in:
2026-09-30 14:29:39 +00:00
parent 96dfac6bc4
commit 2c7f55bfe8
5 changed files with 982 additions and 64 deletions
+1
View File
@@ -37,3 +37,4 @@ make dev # 开发模式说明(前后端分离热更新)
## 文档
设计方案:`modules/documents/docs/proposals/2026-09-29-system-skeleton-design-and-plan.md`(含 D1–D16 决策记录)。
本机服务管理(后端/前端/数据库部署、生命周期、备份克隆):`docs/svc.md`(`scripts/svc.sh`)。