Develop and deploy web app — 开发和部署 web app

开发和部署Web应用程序

在当前工作空间中构建一个简单的全栈Web应用程序，作为一个独立的进程在本地运行，并提供一个其他人可以从外部机器打开的URL。

操作规则

在工作空间下创建生成的Web项目，路径为workspaces/web-apps/{sessionId}/{token}，其中{token}是一个8个字符的随机标识符，仅包含大写字母和数字。如果sessionId在运行时上下文中可用，则直接使用它。如果它不能从环境或用户请求中发现，则在创建项目之前询问用户。除非用户显式覆盖输出规则，否则不要在存储库根目录下创建应用程序。将{token}视为文件夹名称和URL段。每个Web应用程序在其自己的隔离Node.js进程中运行。不要依赖一个共享的Node.js主机进程来服务多个应用程序文件夹。更喜欢两包布局：client/用于React应用程序，server/用于Express API。更喜欢在所有地方使用TypeScript。更喜欢使用Vite进行React前端开发。更喜欢使用better-sqlite3进行SQLite访问，除非工作空间已经使用另一个SQLite库。更喜欢一个最终的HTTP服务。在生产模式下，让Express在同一个服务器进程中提供构建的前端和/api端点。如果用户没有指定产品理念，则默认为一个简单的待办事项或笔记应用程序，具有一个SQLite支持的实体和一个完整的快乐路径。扩展现有的应用程序，而不是替换工作的用户代码。遵循references/ui-style.md中的UI指南设计前端。从Huashu Design的Web示例中捕获视觉原则，而不复制其原始资产或品牌内容。使应用程序在子路径/{sessionId}/{token}/下工作，而不仅仅是在/下。为每个应用程序分配一个专用的端口，在33333-39999的范围内。从33333开始，直到找到一个空闲端口。将最终的外部URL视为http://host:{port}/{sessionId}/{token}/。维护机器可读和人类可读的记录，因此可以查询当前会话和应用程序，而无需手动扫描源文件。更喜欢在scripts/中捆绑的Node脚本用于应用程序初始化、端口分配、注册表维护、启动、关闭和文档同步，而不是重新实现这些流程。保持部署自动化局部和显式。不要添加脚本来获取远程代码、管理秘密、修改无关系统状态或尝试特权升级。支持通过注册表驱动的恢复脚本来恢复重启，但不要默默地安装OS启动钩子或计划任务。

工作流

在更改任何内容之前检查工作空间。解析输出目录为workspaces/web-apps/{sessionId}/{token}，如果需要则创建它。使用scripts/init-app.js初始化应用程序文件夹和基本应用程序文档。决定是否扩展现有的应用程序或创建一个新的应用程序。在目标目录中创建一个最小但完整的应用程序：React前端具有小但可用的UI，Express后端使用TypeScript，SQLite数据库具有模式初始化，至少一个CRUD流程，健康端点。添加根级脚本，使应用程序易于安装、运行、构建、启动和在重新分配的端口上重新运行。使用scripts/scaffold-app.js创建实际项目文件。使用scripts/sync-docs.js同步应用程序文档。更喜欢使用scripts/deploy-app.js进行有序部署，它安装依赖项、构建应用程序、启动它、同步文档并更新注册表，而不会出现竞争条件。如果单独运行部署步骤，则以以下顺序运行：install-app.js -> build-app.js -> start-app.js -> sync-docs.js -> update-registry.js。使用status-app.js和restart-app.js进行生命周期检查和受控重启。使用restore-apps.js进行重新启动后恢复，并使用bootstrap-host.js打印主机级启动机制应运行的命令。返回URL以及本地命令和任何重要注意事项。

实现默认值

使用references/stack.md中的结构和包指导。使用references/scaffold.md中的具体脚手架命令从头开始构建新的应用程序。使用scripts/中的部署脚本。使用references/scripts.md中的最小脚本合同。使用references/autoload.md中的自动加载兼容性规则。使用references/ui-style.md中的前端样式指导。默认本地端口：前端开发服务器：5173，后端开发服务器：3000或3001，生产应用程序服务器：33333-39999范围内的一个空闲端口。在开发中，使用Vite代理进行/api。在生产中，使用Express在基本路径下提供客户端/dist，并在/{sessionId}/{token}/api下保持API路由。将SQLite数据库存储在项目本地路径中，例如server/data/app.db。

平台URL规则

不要在创建文件后停止。任务在应用程序从生成的文件夹中实际可运行并产生最终URL或确认具体阻塞器之前尚未完成。更喜欢暴露生产构建，而不是Vite开发服务器，因此最终URL指向生产构建。