13 · 本地运行与部署清单¶
适用项目：泽湖成长平台（长沙市一中大泽湖学校） 更新：2026-08-16 · 子代理 B（Codex） 范围：本地一键启动、验证命令、CI 覆盖项、常见问题与发布前检查
1. 环境要求¶
| 依赖 | 版本/说明 |
|---|---|
| Node.js | 24+（node --version） |
| Python | 3.x，仅用于 Web 管理后台静态服务（可选） |
| PowerShell | Windows 自带，start.bat 用它做端口探测 |
| 微信开发者工具 | 运行 miniapp-wechat 时需要 |
| 钉钉开发者工具 | 运行 miniapp-dingtalk 时后续需要 |
本仓库 server 为零第三方依赖，不需要 npm install。
2. 目录说明¶
server/ 统一 Node API（Mock，端口 3000）
miniapp-wechat/ 微信小程序端
miniapp-dingtalk/ 钉钉端（薄 UI）
web-admin/ Web 管理后台（静态页面，端口 8080）
docs/ 架构 / API / 阶段计划 / 本清单
start.bat 一键启动入口
.github/workflows/ci.yml CI 检查
3. 本地启动¶
3.1 一键启动（Windows）¶
- 双击项目根目录的
start.bat，或在终端执行：
start.bat
启动内容：
- API server：
node src/index.js，监听http://127.0.0.1:3000 - Web 管理后台：
python -m http.server 8080 --bind 127.0.0.1，监听http://127.0.0.1:8080
幂等性：脚本会先检查 3000 / 8080 端口是否已有进程监听：
- 已在监听 → 打印「[跳过]」，不会二次绑定端口报
EADDRINUSE - 未监听 → 才启动对应窗口
3.2 手动启动¶
:: 终端 1：API
cd server
node src/index.js
:: 终端 2：Web 后台（任选其一）
cd web-admin
python -m http.server 8080 --bind 127.0.0.1
3.3 健康检查地址¶
| 用途 | 地址 | 预期 |
|---|---|---|
| API 存活探测 | http://127.0.0.1:3000/api |
返回 404（无根路由），有 HTTP 响应即表示服务已监听 |
| API 真实登录 | POST http://127.0.0.1:3000/api/auth/login |
返回 200，含 token |
| Web 后台 | http://127.0.0.1:8080/ |
返回目录页 200 |
命令行探测示例：
curl.exe -s -o nul http://127.0.0.1:3000/api
echo %errorlevel%
errorlevel=0 表示连接成功（HTTP 404 也返回 0）。
4. 验证命令¶
在 server 目录执行：
| 命令 | 作用 | 通过标志 |
|---|---|---|
node scripts/check.js |
全量 JS 语法 + Prisma schema 存在 + 30 评价点 | CHECK_RESULT: all passed |
node scripts/smoke.js |
8 个已注册端点冒烟 + CORS/404 自检 | SMOKE_RESULT: 全部 passed |
node tools/etl-migrate.js |
从雷小锋快照生成 prisma/migrated-seed.json |
输出班级/学生/记录统计 |
node tools/etl-verify.js |
校验 ETL 产物引用、五维、分数、排名连续 | ETL_VERIFY: ok |
node --check <file> |
单个 JS 文件语法检查 | 无输出即通过 |
全量 JS 语法检查：
find src scripts prisma tools -name '*.js' -print0 | xargs -0 -n1 node --check
Prisma schema 校验：
npx --yes prisma@6 validate --schema server/prisma/schema.prisma
prisma/migrated-seed.json是 ETL 生成物，已被.gitignore排除；etl-verify.js前必须先运行etl-migrate.js。
5. CI 覆盖项¶
工作流：.github/workflows/ci.yml（push 忽略 docs/**，pull_request 全量）。
| CI 步骤 | 检查内容 |
|---|---|
| Prisma schema validate | 固定 prisma@6 校验 schema |
| Node syntax check | src/scripts/prisma/tools 下全部 .js 逐一 node --check |
| Run check.js | 语法 + schema + 30 评价点 |
| Run smoke.js | 8 端点冒烟 + CORS/404 自检 |
| Run ETL migrate + verify | 生成 migrated-seed.json 后跑 etl-verify.js |
本地可复现 CI 全部命令：
npx --yes prisma@6 validate --schema server/prisma/schema.prisma
cd server
find src scripts prisma tools -name '*.js' -print0 | xargs -0 -n1 node --check
node scripts/check.js
node scripts/smoke.js
node tools/etl-migrate.js
node tools/etl-verify.js
6. 常见问题¶
6.1 端口被占用（EADDRINUSE）¶
start.bat已做幂等检查，重复运行不会二次绑定。- 手动排查：
Get-NetTCPConnection -LocalPort 3000,8080 -State Listen
- 清理：结束占用进程后重跑，或改用其他端口（server 支持
PORT环境变量）。
6.2 /api 返回 404¶
这是预期行为：服务没有根路由，但能返回 404 说明监听正常。真正可用的 200 接口是 POST /api/auth/login 等。
6.3 提示未找到 Python¶
start.bat 会跳过 Web 后台；API 不受影响。可直接双击 web-admin/index.html，或安装 Python 后重跑。
6.4 etl-verify.js 报找不到 migrated-seed.json¶
该文件是生成物且未提交到 Git。先执行：
cd server
node tools/etl-migrate.js
node tools/etl-verify.js
6.5 Prisma 7 兼容性¶
当前 schema 使用标准 url = env("DATABASE_URL") 写法，CI 固定 prisma@6。若后续升级 Prisma 7，需同时迁移 prisma.config.ts 与 adapter，不要在未定版本前单独升级。
6.6 中文乱码¶
start.bat 已用 chcp 65001，并保持 UTF-8 编码。若手工重存文件，避免转成 ANSI/GBK 或带 BOM。
7. 发布前检查清单¶
- [ ]
node scripts/check.js输出CHECK_RESULT: all passed - [ ]
node scripts/smoke.js输出SMOKE_RESULT: 全部 passed - [ ]
node tools/etl-migrate.js+node tools/etl-verify.js输出ETL_VERIFY: ok - [ ] CI 工作流全绿
- [ ] 小程序端
miniapp-wechat/utils/api.js指向正确的 API 地址 - [ ] 未提交
prisma/migrated-seed.json、.env等生成物/敏感文件 - [ ] 云端/生产部署前完成数据库、鉴权、权限矩阵、教育部备案材料（见 PRD 二期）