核心定位
nodejs-project-arch 是一套面向 AI 辅助开发的 Node.js 工程架构规范，核心目标是通过严格的文件粒度控制和配置管理，最大化 AI 编码助手的有效工作轮次。
核心用法
文件拆分规则：单文件硬性上限 400 行（index.html 200 行，server.js 100 行），强制开发者按功能域拆分为模块化结构。后端采用 routes/（按领域路由）、services/（共享逻辑）、db.js（数据库层）三层架构；前端 HTML 仅保留骨架，JS/CSS 完全分离。
配置外置化：所有可调参数纳入 config.json，运行时加载并可通过 /api/config 端点暴露给前端。配套提供 routes/admin.js + admin.html 实现配置热重载、可视化编辑、备份回滚及基础运维监控。
项目类型适配：内置 6 类项目模板——H5 游戏（Canvas/Phaser）、数据工具（爬虫/调度）、内容平台、监控面板、API 服务、SDK 库，通过 references/ 目录引用对应细分规范。
显著优点
1. AI 效率倍增：将 3000 行文件（约 40K tokens/次读取）压缩至 200 行模块（约 2.7K tokens），上下文窗口利用率从 20% 降至 1.3%，理论有效交互轮次从 3-5 轮提升至 10-15 轮。
2. 运维友好：标准化 admin 面板降低配置变更成本，热重载避免重启服务。
3. 工程可维护性：强制模块化天然契合单一职责原则，降低技术债务累积速度。
局限性与风险
适用边界：主要针对 Express/Koa 类传统 Node.js 项目，对 Next.js/Nuxt 等全栈框架的文件结构约束可能冲突；未涉及 TypeScript、测试策略、CI/CD 等现代工程链。
安全风险：admin 路由仅依赖 x-admin-password 头部校验，无速率限制、无会话管理、无审计日志，生产环境极易遭受暴力破解和未授权配置篡改；config.json 明文存储且备份文件 .bak 残留敏感信息。
性能陷阱：fs.readFileSync 同步读取配置在高并发场景阻塞事件循环；配置全量暴露给前端可能泄露数据库连接串等敏感字段（虽有 delete safe.admin 过滤，但依赖人工维护白名单）。
适合人群
- 独立开发者/小团队快速搭建 MVP，追求 AI 编码效率最大化
- 遗留单体 Node.js 项目重构，需控制文件规模以接入 AI 辅助
- 教学场景演示模块化架构思想
生产环境建议
admin 面板必须叠加 JWT + RBAC、配置加密存储（如 AWS Secrets Manager）、接口限流、操作审计日志；敏感配置字段采用服务端注入而非前端暴露。