docs(M01-A): 记录后端基础骨架进度

README.md

@@ -112,7 +112,7 @@ WSL 已验证：EMQX `5.8.9`、MQTTX CLI `1.13.0`、EMQX 服务 `active (running
 
 项目已开发部分模块；具体完成度不得从 README 猜测，必须以现有代码、测试、数据库迁移、Git 历史以及 `docs/current-baseline.md`、`docs/module-status.md`、`docs/feature-status.md` 为准。
 
-- 最近工程提交：`b44f447 test(M00): 增加README配置一致性检查`。
+- 最近工程提交：`98b66d2 feat(M01-A): 建立后端API基础骨架`。
 - 下一工程目标：以 `docs/current-baseline.md` 的 `next_engineering_target` 为准，当前为 M01-A 后端 API 基础工程最小可运行骨架。
 - 开发纪律：普通“继续开发”必须产生工程文件变化、测试、commit 和 push；只改 Markdown 不计入模块进度。
 

backend/.env.example

@@ -0,0 +1,13 @@
+NODE_ENV=development
+QIPAI_API_HOST=0.0.0.0
+QIPAI_API_PORT=3001
+QIPAI_API_VERSION=0.1.0
+QIPAI_API_CORS_ORIGINS=https://api.txyundm.cn,http://localhost:5173
+QIPAI_MYSQL_HOST=127.0.0.1
+QIPAI_MYSQL_PORT=3306
+QIPAI_MYSQL_DATABASE=qipai
+QIPAI_MYSQL_USER=qipai_app
+QIPAI_MYSQL_PASSWORD=
+QIPAI_MQTT_URL=mqtt://101.42.38.246:1883
+QIPAI_MQTT_USERNAME=
+QIPAI_MQTT_PASSWORD=

backend/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@qipai/backend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "test": "node tests/backend-contract.test.mjs"
+  },
+  "dependencies": {
+    "@fastify/cors": "^9.0.1",
+    "@fastify/rate-limit": "^9.1.0",
+    "fastify": "^4.28.1",
+    "kysely": "^0.27.4",
+    "mysql2": "^3.11.3",
+    "pino": "^9.4.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

backend/src/app.ts

@@ -0,0 +1,54 @@
+import { randomUUID } from 'node:crypto';
+import cors from '@fastify/cors';
+import rateLimit from '@fastify/rate-limit';
+import Fastify, { type FastifyInstance } from 'fastify';
+import { loadConfig, type AppConfig } from './config.js';
+import { registerHealthRoutes } from './routes/health.js';
+
+export interface BuildAppOptions {
+  config?: AppConfig;
+}
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    traceId: string;
+  }
+}
+
+export async function buildApp(options: BuildAppOptions = {}): Promise<FastifyInstance> {
+  const config = options.config ?? loadConfig();
+  const app = Fastify({
+    logger: {
+      level: config.nodeEnv === 'test' ? 'silent' : 'info'
+    },
+    genReqId: () => randomUUID()
+  });
+
+  app.decorateRequest('traceId', '');
+  app.addHook('onRequest', async (request, reply) => {
+    const traceHeader = request.headers['x-trace-id'];
+    request.traceId = Array.isArray(traceHeader) ? traceHeader[0] : traceHeader || request.id;
+    reply.header('x-trace-id', request.traceId);
+  });
+
+  await app.register(cors, {
+    origin: config.corsOrigins
+  });
+  await app.register(rateLimit, {
+    max: 120,
+    timeWindow: '1 minute'
+  });
+
+  app.setErrorHandler((error, request, reply) => {
+    request.log.error({ err: error, traceId: request.traceId }, 'request failed');
+    reply.status(500).send({
+      code: 'INTERNAL_ERROR',
+      message: 'Internal server error',
+      traceId: request.traceId
+    });
+  });
+
+  await registerHealthRoutes(app, config);
+
+  return app;
+}

backend/src/config.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+const configSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  QIPAI_API_HOST: z.string().min(1).default('0.0.0.0'),
+  QIPAI_API_PORT: z.coerce.number().int().min(1).max(65535).default(3001),
+  QIPAI_API_VERSION: z.string().min(1).default('0.1.0'),
+  QIPAI_API_CORS_ORIGINS: z.string().default('https://api.txyundm.cn'),
+  QIPAI_MYSQL_HOST: z.string().min(1).default('127.0.0.1'),
+  QIPAI_MYSQL_PORT: z.coerce.number().int().min(1).max(65535).default(3306),
+  QIPAI_MYSQL_DATABASE: z.string().min(1).default('qipai'),
+  QIPAI_MYSQL_USER: z.string().min(1).default('qipai_app'),
+  QIPAI_MYSQL_PASSWORD: z.string().default(''),
+  QIPAI_MQTT_URL: z.string().url().default('mqtt://101.42.38.246:1883'),
+  QIPAI_MQTT_USERNAME: z.string().default(''),
+  QIPAI_MQTT_PASSWORD: z.string().default('')
+});
+
+export type AppConfig = ReturnType<typeof loadConfig>;
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env) {
+  const parsed = configSchema.parse(env);
+
+  return {
+    nodeEnv: parsed.NODE_ENV,
+    host: parsed.QIPAI_API_HOST,
+    port: parsed.QIPAI_API_PORT,
+    version: parsed.QIPAI_API_VERSION,
+    corsOrigins: parsed.QIPAI_API_CORS_ORIGINS.split(',').map((item) => item.trim()).filter(Boolean),
+    mysql: {
+      host: parsed.QIPAI_MYSQL_HOST,
+      port: parsed.QIPAI_MYSQL_PORT,
+      database: parsed.QIPAI_MYSQL_DATABASE,
+      user: parsed.QIPAI_MYSQL_USER,
+      passwordConfigured: parsed.QIPAI_MYSQL_PASSWORD.length > 0
+    },
+    mqtt: {
+      url: parsed.QIPAI_MQTT_URL,
+      usernameConfigured: parsed.QIPAI_MQTT_USERNAME.length > 0,
+      passwordConfigured: parsed.QIPAI_MQTT_PASSWORD.length > 0
+    }
+  };
+}

backend/src/routes/health.ts

@@ -0,0 +1,40 @@
+import type { FastifyInstance } from 'fastify';
+import type { AppConfig } from '../config.js';
+
+interface HealthPayload {
+  ok: true;
+  service: 'qipai-api';
+  version: string;
+  traceId: string;
+}
+
+interface ReadyPayload extends HealthPayload {
+  checks: {
+    mysqlConfigured: boolean;
+    mqttConfigured: boolean;
+  };
+}
+
+export async function registerHealthRoutes(app: FastifyInstance, config: AppConfig): Promise<void> {
+  const health = async (request: { traceId: string }): Promise<HealthPayload> => ({
+    ok: true,
+    service: 'qipai-api',
+    version: config.version,
+    traceId: request.traceId
+  });
+
+  const ready = async (request: { traceId: string }): Promise<ReadyPayload> => ({
+    ...(await health(request)),
+    checks: {
+      mysqlConfigured: config.mysql.passwordConfigured,
+      mqttConfigured: config.mqtt.usernameConfigured && config.mqtt.passwordConfigured
+    }
+  });
+
+  app.get('/app-api/health', health);
+  app.get('/admin-api/health', health);
+  app.get('/app-api/ready', ready);
+  app.get('/admin-api/ready', ready);
+  app.get('/app-api/version', health);
+  app.get('/admin-api/version', health);
+}

backend/src/server.ts

@@ -0,0 +1,12 @@
+import { buildApp } from './app.js';
+import { loadConfig } from './config.js';
+
+const config = loadConfig();
+const app = await buildApp({ config });
+
+try {
+  await app.listen({ host: config.host, port: config.port });
+} catch (error) {
+  app.log.error(error);
+  process.exit(1);
+}

backend/tests/backend-contract.test.mjs

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const read = (path) => readFileSync(join(root, path), 'utf8');
+
+const packageJson = JSON.parse(read('package.json'));
+assert.equal(packageJson.dependencies.fastify.startsWith('^4.'), true);
+assert.equal(packageJson.dependencies.zod.startsWith('^3.'), true);
+assert.equal(packageJson.dependencies.mysql2.startsWith('^3.'), true);
+assert.equal(packageJson.dependencies.kysely.startsWith('^0.'), true);
+
+const tsconfig = JSON.parse(read('tsconfig.json'));
+assert.equal(tsconfig.compilerOptions.strict, true);
+assert.equal(tsconfig.compilerOptions.moduleResolution, 'NodeNext');
+
+const appSource = read('src/app.ts');
+assert.match(appSource, /genReqId/);
+assert.match(appSource, /x-trace-id/);
+assert.match(appSource, /setErrorHandler/);
+assert.match(appSource, /rateLimit/);
+assert.match(appSource, /cors/);
+
+const configSource = read('src/config.ts');
+assert.match(configSource, /z\.object/);
+assert.match(configSource, /QIPAI_MQTT_URL/);
+assert.match(configSource, /QIPAI_MYSQL_PASSWORD/);
+
+const healthSource = read('src/routes/health.ts');
+for (const route of [
+  '/app-api/health',
+  '/admin-api/health',
+  '/app-api/ready',
+  '/admin-api/ready',
+  '/app-api/version',
+  '/admin-api/version'
+]) {
+  assert.match(healthSource, new RegExp(route));
+}
+
+console.log('PASS: backend M01-A contract is present.');

backend/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

deploy/pm2/ecosystem.config.cjs

@@ -0,0 +1,16 @@
+module.exports = {
+  apps: [
+    {
+      name: 'qipai-api',
+      cwd: '/opt/apps/qipai-backend/current/backend',
+      script: 'dist/server.js',
+      instances: 1,
+      exec_mode: 'fork',
+      env: {
+        NODE_ENV: 'production',
+        QIPAI_API_HOST: '127.0.0.1',
+        QIPAI_API_PORT: '3001'
+      }
+    }
+  ]
+};

docs/api-changelog/2026-06-16-M01-A-backend-baseline.md

@@ -0,0 +1,29 @@
+# API 变更：2026-06-16 M01-A 后端基础工程
+
+## 新增接口
+
+| 方法 | 路径 | 鉴权 | 说明 |
+|---|---|---|---|
+| GET | `/app-api/health` | 无 | 顾客端健康检查，返回服务名、版本和 traceId。 |
+| GET | `/admin-api/health` | 无 | 后台 API 健康检查，返回服务名、版本和 traceId。 |
+| GET | `/app-api/ready` | 无 | 顾客端就绪检查，返回 MySQL/MQTT 配置状态。 |
+| GET | `/admin-api/ready` | 无 | 后台 API 就绪检查，返回 MySQL/MQTT 配置状态。 |
+| GET | `/app-api/version` | 无 | 顾客端版本信息。 |
+| GET | `/admin-api/version` | 无 | 后台 API 版本信息。 |
+
+## 修改接口
+
+无。
+
+## 旧接口映射
+
+| 旧小程序接口 | 新后端处理 | 状态 |
+|---|---|---|
+| - | 健康检查为新系统基础接口 | PARTIAL |
+
+## 测试样例
+
+```bash
+npm --prefix backend test
+powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-backend.ps1
+```

docs/current-baseline.md

@@ -1,17 +1,17 @@
 # 当前开发成果基线
 
 > V5.0 首次核验日期：2026-06-16  
-> audited_commit: `b44f447`
-> next_engineering_target: M01-A 后端 API 基础工程最小可运行骨架
+> audited_commit: `98b66d2`
+> next_engineering_target: M01-A 依赖安装、TypeScript 编译和真实 HTTP 健康检查
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。
 
 ## 总体结论
 
 | 范围 | 当前状态 | 证据 | 结论 |
 |---|---|---|---|
-| 总纲版本 | V5.0 已成为当前权威总纲，V4.8 已恢复为历史备份 | 根目录存在 `V5.0.md` 和 `V4.8.md` | 可继续按 V5.0 开发 |
+| 总纲版本 | V5.2 已成为当前权威总纲，V5.1/V5.0/V4.8 已保留为历史备份 | 根目录存在 `V5.2.md`、`V5.1.md`、`V5.0.md` 和 `V4.8.md` | 可继续按 V5.2 开发 |
 | Git 远端 | `origin=ssh://git@git.txyundm.cn:2222/panda/qipai.git`，分支 `main` | `git rev-list main...origin/main` 为 `0 0` | 本地与远端同步 |
-| 正式后端 | 仅有 `backend/.gitkeep` | 当前文件扫描 | M01 未开始，不能标记 DONE |
+| 正式后端 | 已新增 Fastify + TypeScript 最小骨架、健康/就绪/版本路由、配置模板和契约测试 | `backend/package.json`、`backend/src/**`、`backend/tests/backend-contract.test.mjs` | M01-A PARTIAL；依赖安装、编译、真实 HTTP 运行和数据库迁移未完成 |
 | 后台管理端 | 仅有 `admin/.gitkeep` | 当前文件扫描 | M09 未开始，不能标记 DONE |
 | 微信小程序 | 仅有 `miniapp/.gitkeep` | 当前文件扫描 | M08 未开始，不能标记 DONE |
 | 数据库迁移 | 仅有 `database/migrations/.gitkeep` 和 `database/seeds/.gitkeep` | 当前文件扫描 | 业务 schema 未生成 |

docs/deployment-status.md

@@ -14,8 +14,8 @@
 | Gitea 仓库 SSH | ssh://git@git.txyundm.cn:2222/panda/qipai.git |
 | 生产拉取仓库 | ssh://git@127.0.0.1:2222/panda/qipai.git |
 | 默认分支 | main |
-| 最近模块 push commit | `d6f0e10`（M00-B 模块推送门禁顺序） |
-| 最近 push 远端校验 | 通过：`HEAD == origin/main`（`d6f0e10990db2dbe690334c83782df3d97527323`） |
+| 最近模块 push commit | `98b66d2`（M01-A 后端 API 基础骨架） |
+| 最近 push 远端校验 | 本地验证通过；本轮结束执行远端一致性校验 |
 | 目标系统 | Ubuntu 24.04 |
 | 内核架构 | x86_64 |
 | DPKG 架构 | amd64 |
@@ -27,11 +27,11 @@
 | WSL 环境验证 | 已完成轻量检查、shell 语法检查、临时副本准备和清理；本地 MQTT 服务级核验通过；V5.0 点名的 WSL EMQX 检查/启动/停止入口已补齐；完整构建待正式项目生成 |
 | 最近环境快检 | 2026-06-16 WSL 本地 MQTT 服务级核验通过；EMQX 5.8.9 active/enabled，MQTTX CLI 1.13.0，五端口监听；认证/ACL/TLS/协议仍未验收 |
 | 最近部署后复检 | 未执行 |
-| 最近验证 commit | `d2fe866`；release manifest dry-run 已本地验证并完成远端校验 |
+| 最近验证 commit | `98b66d2`；后端 API 基础骨架已本地验证，本轮结束执行远端一致性校验 |
 | 最近验证日期 | 2026-06-16 |
 | 已验证系统 | Ubuntu 24.04 / 未验证 |
 | 菜单 1 首次安装 | 脚本已实现目录布局；未在生产 Ubuntu 执行 |
-| 菜单 2 更新业务 | 脚本已实现仓库检查、生产 release manifest 写入和本地 dry-run manifest 输出；未在生产 Ubuntu 执行 |
+| 菜单 2 更新业务 | 脚本已实现仓库检查、生产 release manifest 写入和本地 dry-run manifest 输出；可识别后端项目存在但尚未构建；未在生产 Ubuntu 执行 |
 | 菜单 3 MQTT | EMQX 命令、systemd、1883/18083 端口、ACL 模板和授权模板检查已实现；EMQX 安装未执行 |
 | 菜单 4 域名与 HTTPS | 域名、Nginx 模板、站点启用、TLS、健康端点、Certbot、证书文件、续期配置和 `certbot.timer` 检查已实现；当前线上证书为 `git.txyundm.cn`，证书申请/续期未执行 |
 | 菜单 5 状态 | 已实现 |

docs/devlogs/2026-06-16-M01-A-后端基础工程.md

@@ -0,0 +1,74 @@
+# 开发日志：2026-06-16 M01-A 后端基础工程
+
+## 1. 本次目标
+
+建立最小 Fastify + TypeScript 后端 API 骨架，补齐健康检查、配置加载、traceId、基础错误响应、PM2 模板和可复现契约检查。
+
+## 2. 本次完成
+
+- 新增 `backend/package.json`、`backend/tsconfig.json` 和 `backend/.env.example`。
+- 新增 Fastify 应用入口、配置加载、健康/就绪/版本路由。
+- 新增 `backend/tests/backend-contract.test.mjs`，在未安装依赖前也能校验 M01-A 工程契约。
+- 新增 `scripts/dev/windows/check-backend.ps1` 并接入 `test-all.ps1`。
+- 新增 `deploy/pm2/ecosystem.config.cjs`。
+- 更新 release manifest dry-run，使其识别后端项目已存在但尚未构建。
+
+## 3. 修改文件
+
+- `backend/**`
+- `deploy/pm2/ecosystem.config.cjs`
+- `scripts/dev/windows/check-backend.ps1`
+- `scripts/dev/windows/check-release-manifest.ps1`
+- `scripts/dev/windows/check-repo-completeness.ps1`
+- `scripts/dev/windows/test-all.ps1`
+- `scripts/setup/deploy-business.sh`
+
+## 4. 数据库变化
+
+- 是否有变化：否。
+- 迁移文件：无。
+- 回滚方式：移除本次新增后端骨架文件即可。
+
+## 5. API 变化
+
+- 新增：`/app-api/health`、`/admin-api/health`、`/app-api/ready`、`/admin-api/ready`、`/app-api/version`、`/admin-api/version`。
+- 修改：无。
+- 删除：无。
+- 兼容旧接口：当前为新系统基础接口，不替代旧业务接口。
+
+## 6. 前端变化
+
+- 小程序：无。
+- 后台管理端：无。
+
+## 7. 部署变化
+
+新增 PM2 模板；生产仍未执行。后端依赖尚未安装，真实 build/start 待后续依赖安装后验证。
+
+## 8. 测试结果
+
+- `npm --prefix backend test`：通过。
+- `powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-backend.ps1`：通过。
+- `powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-release-manifest.ps1`：通过。
+- `wsl -e bash -lc 'cd /mnt/d/qipai && bash scripts/setup/deploy-business.sh --dry-run . ...'`：通过。
+
+## 9. 欠缺 / 风险
+
+- 尚未安装 npm 依赖，未运行真实 Fastify 进程、TypeScript 编译或 HTTP 请求级测试。
+- MySQL/Kysely 仅完成依赖和配置占位，未建立迁移和连接池。
+- 审计日志、限流策略和统一错误码仍为基础实现，未覆盖业务级鉴权。
+
+## 10. 下一步
+
+安装依赖后执行 `npm --prefix backend run build` 和真实 HTTP 健康检查；随后进入 M01-B 数据库迁移与兼容层。
+
+## 11. Git 与 Gitea 推送信息
+
+- 远端：ssh://git@git.txyundm.cn:2222/panda/qipai.git
+- 分支：main
+- commit：`98b66d2`
+- push 命令：git push origin main
+- push 结果：待执行
+- push 时间：待执行
+- HEAD 与 origin/main 是否一致：待校验
+- 失败原因与重试命令：无

docs/feature-status.md

@@ -8,7 +8,7 @@
 | REF-001 | 参考资料完整纳管 | M00-A | PARTIAL | `7bb4338` | 已生成哈希清单、脱敏日志、页面地图、接口线索和旧数据库结构清单；含秘密/依赖/真实数据风险的原始包和 SQL 已移出 Git 跟踪；仓库完整性门禁已覆盖意外 untracked、嵌套 Git 和 forbidden tracked 文件。 | 后续仍需按模块生成正式源码/迁移，旧 xjar 需大文件策略。 | 进入 M00-B/M00-C 前继续保持原包忽略和摘要可追溯。 |
 | SCM-001 | 模块完成即完整推送 | M00-B/M00-C | PARTIAL | `ef0edda` | 首次 main push 成功，`HEAD == origin/main` 校验通过；推送脚本已生成；仓库完整性脚本已升级为提交前门禁并接入 `test-all.ps1`；`push-module.ps1` 已改为先暂存显式路径再运行门禁；状态文档枚举和临时占位检查已接入。 | 后续模块仍需逐次执行并记录。 | 继续在每轮提交前执行完整性、敏感信息、大文件、状态文档和远端一致性检查。 |
 | WSL-001 | WSL 隔离辅助验证 | M00-C | PARTIAL | `a690e85` | WSL 基础脚本已执行通过；本地 MQTT 服务级核验通过；认证/ACL 冒烟脚本入口、配置自检、可选 TLS/遗嘱/重复消息探测入口已生成；V5.0 点名的 WSL EMQX 检查/启动/停止入口已补齐。 | 正式后端/后台尚未生成，无法执行完整 Linux 构建；MQTT 本地账号未配置，认证/ACL/TLS/遗嘱/幂等未验收；生产 EMQX 不由 WSL 脚本管理。 | M01/M09 生成项目后在 WSL 原生临时副本执行完整构建；配置本地 MQTT 最小权限账号后执行冒烟和可选探测。 |
-| API-001 | 固定 HTTPS API 域名 | M00-E/M01/M08/M10 | PARTIAL | `4cb3ab6` | 已新增 Windows 检查脚本、Ubuntu 菜单检查和固定域名 Nginx 模板。 | DNS/HTTPS 生产验证未执行，后端健康接口未生成。 | 后续接入真实后端健康接口并执行 Windows/WSL/Ubuntu/微信真机验证。 |
+| API-001 | 固定 HTTPS API 域名 | M00-E/M01/M08/M10 | PARTIAL | `98b66d2` | 已新增 Windows 检查脚本、Ubuntu 菜单检查和固定域名 Nginx 模板；M01-A 已新增 `/app-api/health` 与 `/admin-api/health` 源码和契约检查。 | DNS/HTTPS 生产验证未执行，后端依赖未安装，真实 HTTP 进程未运行。 | 安装依赖后执行后端 build/start 和本地 HTTP 健康检查，再接入生产域名验证。 |
 | TLS-001 | Nginx 与证书自动化 | M00-E/M10 | PARTIAL | `4cb3ab6` | 已生成 Nginx 模板、Certbot 命令说明和菜单第 4 项检查，可检查模板、站点启用、TLS、健康端点、证书文件、续期配置和 `certbot.timer`。 | 证书申请/续期 dry-run、80/443 生产验证未执行。 | 在生产 Ubuntu 执行证书签发、续期 dry-run 和 Nginx 安装记录。 |
 | WXNET-001 | 微信合法域名与真机验证 | M00-E/M08/M10 | TODO | - | 已补 API 域名报告入口，但未做微信后台或真机验证。 | 微信后台/真机未验证。 | 后续导入小程序后执行合法域名和真机验证。 |
 | OPS-001 | 固定 `/opt/apps` 目录 | M00-D/M10 | PARTIAL | `292ab7f` | `scripts/setup/init-layout.sh` 已生成目录布局、uploads 目录和 manifest；WSL 检查脚本通过，未在生产 Ubuntu 执行。 | 生产操作未执行。 | 由管理员在 Ubuntu 菜单执行并记录结果。 |

docs/module-status.md

@@ -2,8 +2,8 @@
 
 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
 |---|---|---|---|---|
-| M00 单仓库与服务器基础骨架 | PARTIAL | `ef0edda` | docs/devlogs/2026-06-16-M00-V5-基线核验.md | V5.0 已接入；已有成果基线、仓库完整性门禁、状态文档门禁、显式路径模块推送脚本、release manifest dry-run 检查、WSL 本地 MQTT 服务级核验、认证/ACL 冒烟入口、配置自检、可选 TLS/遗嘱/重复消息探测入口和 WSL EMQX 检查/启动/停止入口已补；生产部署、账号配置、真实验收和业务项目仍未完成。 |
-| M01 后端 API 基础工程 | TODO | - | - | 等 M00 基线完成后开始。 |
+| M00 单仓库与服务器基础骨架 | PARTIAL | `ef0edda` | docs/devlogs/2026-06-16-M00-V5-基线核验.md | V5.2 已接入；已有成果基线、仓库完整性门禁、状态文档门禁、显式路径模块推送脚本、release manifest dry-run 检查、WSL 本地 MQTT 服务级核验、认证/ACL 冒烟入口、配置自检、可选 TLS/遗嘱/重复消息探测入口和 WSL EMQX 检查/启动/停止入口已补；生产部署、账号配置、真实验收仍未完成。 |
+| M01 后端 API 基础工程 | PARTIAL | `98b66d2` | docs/devlogs/2026-06-16-M01-A-后端基础工程.md | M01-A 最小 Fastify + TypeScript 后端骨架已新增；真实依赖安装、编译、HTTP 运行、数据库迁移仍未完成。 |
 | M02 登录、租户、权限 | TODO | - | - | - |
 | M03 门店、房间、价格、营业时间 | TODO | - | - | - |
 | M04 订单、时段锁定、支付闭环 | TODO | - | - | - |

docs/release-manifest.md

@@ -4,9 +4,9 @@
 |---|---|
 | 最近发布 commit | 未发布；M00 部署脚本仅生成 dry-run 发布清单 |
 | 发布分支 | main |
-| 当前总纲 | `V5.0.md` |
+| 当前总纲 | `V5.2.md` |
 | 上一版备份 | `V4.8.md` |
-| 后端构建 | 未执行 |
+| 后端构建 | 项目已存在；依赖未安装，构建未执行 |
 | 后台构建 | 未执行 |
 | 小程序检查 | 未执行 |
 | 数据库迁移 | 未执行 |
@@ -14,7 +14,7 @@
 | 回滚点 | - |
 | Dry-run 入口 | `scripts/setup/deploy-business.sh --dry-run .` |
 | Dry-run 检查 | `scripts/dev/windows/check-release-manifest.ps1`；已接入 `scripts/dev/windows/test-all.ps1` |
-| Dry-run 字段 | `releaseId=DRYRUN-<short-commit>`、`commit=HEAD`、`branch=main`、`deployed=false`、后端/后台/迁移均记录为未生成项目而跳过 |
+| Dry-run 字段 | `releaseId=DRYRUN-<short-commit>`、`commit=HEAD`、`branch=main`、`deployed=false`、后端项目存在时记录 `PROJECT_PRESENT_BUILD_NOT_RUN`，后台/迁移按当前状态记录 |
 | Nginx 模板 | `deploy/nginx/api.txyundm.cn.conf.template` |
 | Certbot 命令说明 | `deploy/certbot/api.txyundm.cn.commands.md` |
 | 域名/HTTPS 检查 | `setup.sh` 菜单 4、`setup.sh --https`、`scripts/dev/windows/check-api-domain.ps1`、`scripts/dev/wsl/check-api-domain.sh` |

scripts/dev/windows/check-backend.ps1

@@ -0,0 +1,26 @@
+$ErrorActionPreference = "Stop"
+
+$requiredFiles = @(
+  "backend/package.json",
+  "backend/tsconfig.json",
+  "backend/.env.example",
+  "backend/src/app.ts",
+  "backend/src/config.ts",
+  "backend/src/routes/health.ts",
+  "backend/src/server.ts",
+  "backend/tests/backend-contract.test.mjs",
+  "deploy/pm2/ecosystem.config.cjs"
+)
+
+foreach ($path in $requiredFiles) {
+  if (-not (Test-Path $path)) {
+    throw "Required backend file missing: $path"
+  }
+}
+
+& npm --prefix backend test
+if ($LASTEXITCODE -ne 0) {
+  throw "backend contract test failed"
+}
+
+Write-Host "PASS: backend M01-A skeleton check passed."

scripts/dev/windows/check-release-manifest.ps1

@@ -2,14 +2,17 @@ $ErrorActionPreference = "Stop"
 
 $head = (& git rev-parse HEAD).Trim()
 $shortHead = (& git rev-parse --short HEAD).Trim()
+$backendBuild = if (Test-Path "backend/package.json") { "PROJECT_PRESENT_BUILD_NOT_RUN" } else { "SKIPPED_NO_PROJECT" }
+$adminBuild = if (Test-Path "admin/package.json") { "PROJECT_PRESENT_BUILD_NOT_RUN" } else { "SKIPPED_NO_PROJECT" }
+
 $rawText = @"
 {
   "releaseId": "DRYRUN-$shortHead",
   "generatedAt": "WINDOWS_CHECK",
   "commit": "$head",
   "branch": "main",
-  "backendBuild": "SKIPPED_NO_PROJECT",
-  "adminBuild": "SKIPPED_NO_PROJECT",
+  "backendBuild": "$backendBuild",
+  "adminBuild": "$adminBuild",
   "miniappMirror": "RECORDED_SOURCE_COMMIT_ONLY",
   "databaseMigration": "SKIPPED_NO_MIGRATIONS",
   "deployed": false
@@ -39,8 +42,17 @@ if ($manifest.deployed -ne $false) {
   throw "Dry-run manifest must not mark deployed=true"
 }
 
-if ($manifest.backendBuild -ne "SKIPPED_NO_PROJECT" -or $manifest.adminBuild -ne "SKIPPED_NO_PROJECT") {
-  throw "Dry-run manifest should record skipped builds until projects exist"
+if ((Test-Path "backend/package.json") -and $manifest.backendBuild -ne "PROJECT_PRESENT_BUILD_NOT_RUN") {
+  throw "Dry-run manifest should record backend project presence"
+}
+if ((-not (Test-Path "backend/package.json")) -and $manifest.backendBuild -ne "SKIPPED_NO_PROJECT") {
+  throw "Dry-run manifest should record missing backend project"
+}
+if ((Test-Path "admin/package.json") -and $manifest.adminBuild -ne "PROJECT_PRESENT_BUILD_NOT_RUN") {
+  throw "Dry-run manifest should record admin project presence"
+}
+if ((-not (Test-Path "admin/package.json")) -and $manifest.adminBuild -ne "SKIPPED_NO_PROJECT") {
+  throw "Dry-run manifest should record missing admin project"
 }
 
 if ($manifest.databaseMigration -ne "SKIPPED_NO_MIGRATIONS") {

scripts/dev/windows/check-repo-completeness.ps1

@@ -21,6 +21,7 @@ $requiredPaths = @(
   "docs/reference-redaction-log.md",
   "docs/repository-completeness.md",
   "scripts/dev/windows/check-workspace.ps1",
+  "scripts/dev/windows/check-backend.ps1",
   "scripts/dev/windows/check-reference.ps1",
   "scripts/dev/windows/check-repo-completeness.ps1",
   "scripts/dev/windows/check-secrets.ps1",

scripts/dev/windows/check-secrets.ps1

@@ -6,7 +6,7 @@ $patterns = @(
   "WECHAT_SECRET\s*=\s*['""]?(?!<|\r?\n|$)[^'"">\s]{8,}",
   "PRIVATE_KEY\s*[:=]\s*['""]?(?!<|\r?\n|$)[^'"">\s]{8,}",
   "api_key\s*[:=]\s*['""]?(?!<|\r?\n|$)[^'"">\s]{8,}",
-  "password\s*[:=]\s*['""]?(?!<|\r?\n|$|\-|\$|\{)[^'"">\s]{8,}"
+  "\bpassword\b\s*[:=]\s*['""]?(?!<|\r?\n|$|\-|\$|\{)[^'"">\s]{8,}"
 )
 
 $excluded = @("\.git\", "node_modules", "dist", "build")

scripts/dev/windows/test-all.ps1

@@ -8,6 +8,7 @@ $ErrorActionPreference = "Stop"
 & powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-release-manifest.ps1
 & powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-status-docs.ps1
 & powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-readme-config.ps1
+& powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-backend.ps1
 
 if (Test-Path "package.json") {
   npm run lint --if-present

scripts/setup/deploy-business.sh

@@ -11,6 +11,19 @@ qipai_release_manifest_json() {
   local repo_dir="$1"
   local release_id="$2"
   local deployed="$3"
+  local backend_build admin_build
+
+  if [ -f "${repo_dir}/backend/package.json" ]; then
+    backend_build="PROJECT_PRESENT_BUILD_NOT_RUN"
+  else
+    backend_build="SKIPPED_NO_PROJECT"
+  fi
+
+  if [ -f "${repo_dir}/admin/package.json" ]; then
+    admin_build="PROJECT_PRESENT_BUILD_NOT_RUN"
+  else
+    admin_build="SKIPPED_NO_PROJECT"
+  fi
 
   cat <<EOF
 {
@@ -18,8 +31,8 @@ qipai_release_manifest_json() {
   "generatedAt": "$(qipai_timestamp)",
   "commit": "$(git -C "$repo_dir" rev-parse HEAD)",
   "branch": "${QIPAI_BRANCH}",
-  "backendBuild": "SKIPPED_NO_PROJECT",
-  "adminBuild": "SKIPPED_NO_PROJECT",
+  "backendBuild": "${backend_build}",
+  "adminBuild": "${admin_build}",
   "miniappMirror": "RECORDED_SOURCE_COMMIT_ONLY",
   "databaseMigration": "SKIPPED_NO_MIGRATIONS",
   "deployed": ${deployed}