diff --git a/README.md b/README.md index 7c5309dc..5885c94a 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,47 @@ ## 当前状态 -更新时间：2026-07-01 +更新时间：2026-07-02 + +## 接管快照 + +截至 2026-07-02，当前 `main` 已同步到 Gitea，最新前端交付提交为 `f54421f test: align Taro visual guardrails with legacy UI`，其前一个核心实现提交为 `aa71251 fix: align Taro H5 with legacy question bank UI`。另一台工作机接管时，优先从 Gitea 拉取 `main`，不要从服务器的构建产物反向覆盖源码。 + +本轮已完成的关键变化： + +- 学生 H5 已按旧题库主视觉重做：浅灰网格背景、旧蓝色主色、PC 侧边栏、移动端底部导航、蓝色学习 banner、白色数据卡、彩色功能模块和紧凑列表。 +- 租户后台和平台后台已按旧后台工作台风格收敛：白/灰高密度界面、侧边栏/移动导航、深色激活态、紧凑表格/表单/行布局。 +- 受保护页面已补路由守卫：Auth/角色校验期间不渲染业务内容；静态 H5 可以加载入口壳，但不应在未鉴权时暴露可用业务数据。 +- 三端 H5 首屏入口按构建目标区分：`student`、`tenant-admin`、`platform-admin`。 +- 视觉守卫已从通用圆角/渐变规则调整为旧题库 UI 规则，防止后续改回营销页式大卡片风格。 + +本地已通过的验证命令： + +```bash +npm --workspace @tiku-saas/taro run check +node scripts/taro-route-contract-test.js +npm run guard:taro:visual +node scripts/taro-visual-guardrails-test.js +npm run build:taro:h5:student +npm run build:taro:h5:tenant +npm run build:taro:h5:platform +npm run smoke:taro:h5 +npm run smoke:taro:h5:interaction +node scripts/taro-h5-release-guardrails-test.js +``` + +云服务器当前接管点： + +- 服务器仓库：`/opt/tiku-saas/repo` +- H5 发布目录：`/srv/tiku-saas/www/student`、`/srv/tiku-saas/www/tenant-admin`、`/srv/tiku-saas/www/platform-admin` +- 发布脚本：`/opt/tiku-saas/bin/deploy.sh` +- 线上 Supabase、自研 API、Nginx、runtime-config 已能基本联通；`https://api.tjszsb.com/api/tenant/resolve?host=app.tjszsb.com` 已返回 `master` 租户。 +- Gitea SSH 端口是 `2222`，服务器 `deploy` 用户拉取应使用 `ssh://git@git.gongxue100.com:2222/chenhaogxjy/tiku-supabase.git` 或在 SSH config 中显式配置 `Port 2222`。 +- 2026-07-02 服务器手动执行 `sudo -u deploy npm run build:taro:h5:student` 时出现 Taro 构建长时间无输出、CPU 持续接近满载、`dist/h5-student` 未更新的情况。接管后建议先中止残留构建进程，清理目标目录，再用 `CI=1 NODE_OPTIONS="--max-old-space-size=4096"` 重新构建三端，详见 `scripts/deploy/README.md` 的“服务器接管和故障恢复”。 ## 最新交付快照 -截至 2026-07-01，当前 `main` 已推送到 Gitea，可进入云服务器部署和生产测试阶段。这里的“生产测试”指在真实云服务器、真实域名、真实对象存储和真实 provider 配置下做灰度/演练验证；正式对 C 端或合作商放量前，仍必须通过本文的生产上线证据门禁。 +截至 2026-07-02，当前 `main` 已推送到 Gitea，可进入云服务器部署和生产测试阶段。这里的“生产测试”指在真实云服务器、真实域名、真实对象存储和真实 provider 配置下做灰度/演练验证；正式对 C 端或合作商放量前，仍必须通过本文的生产上线证据门禁。 - 后端核心业务已经覆盖旧题库主链路：刷题、背单词、知识手册、分数线、错题本、收藏夹、资料下载、题目视频、会员/订单/优惠券/激活码、个人中心、站内通知、勋章、租户后台、平台 SaaS 管理、公共题库授权/采纳/同步、CRM/销售/代理/分佣、财务对账和 worker 任务。 - 多租户安全底座已经具备商用联调条件：平台/租户/学生三类身份边界、Supabase Auth JWT、迁移期 `tk_` session、RLS 测试、租户角色模板、成员权限、班级/教师/学生范围、字段脱敏、审计日志、私有资源短签名、导入/导出 job 审计均已落地。 diff --git a/docs/refactor/frontend-handoff-index.md b/docs/refactor/frontend-handoff-index.md index 3e166136..c0f7dca6 100644 --- a/docs/refactor/frontend-handoff-index.md +++ b/docs/refactor/frontend-handoff-index.md @@ -1,9 +1,44 @@ # 前端交接索引 -更新时间：2026-06-30 +更新时间：2026-07-02 这份文件是给 Taro/H5/小程序前端同事的入口。当前仓库的前端重构建议从 `apps/taro` 新建工程开始，不再把旧 React/Vite 前端搬回根目录继续开发。 +## 2026-07-02 接管重点 + +当前 `main` 已包含旧题库视觉对齐版本，最新提交是 `f54421f test: align Taro visual guardrails with legacy UI`。另一台工作机接管后，先确认本地代码至少包含该提交： + +```bash +git log -2 --oneline +``` + +本轮前端变化的边界： + +- 学生端不是营销 landing page，而是旧题库式学习应用：首页直接呈现学习状态、题库入口、模块入口和最近学习，不再用大 hero、大圆角卡片或紫蓝渐变。 +- 租户后台和平台后台不是官网风格，而是旧后台式工作台：信息密度更高、控件更紧凑、侧边栏清晰、移动端保留可用导航。 +- 登录/权限校验期间，受保护页面只显示校验态或跳转，不渲染真实业务列表、表格和操作按钮。 +- 视觉守卫已经按旧题库风格改写，后续如果确实要新增渐变、超大圆角或特殊装饰，必须先更新 `docs/refactor/taro-visual-language.md` 并让守卫有明确例外。 + +接管后建议先跑这一组最小验证： + +```bash +npm --workspace @tiku-saas/taro run check +node scripts/taro-route-contract-test.js +npm run guard:taro:visual +node scripts/taro-visual-guardrails-test.js +npm run build:taro:h5:student +npm run build:taro:h5:tenant +npm run build:taro:h5:platform +npm run smoke:taro:h5 +``` + +准备上线或改动关键交互时，再补： + +```bash +npm run smoke:taro:h5:interaction +node scripts/taro-h5-release-guardrails-test.js +``` + ## 必读顺序 1. `docs/refactor/project-structure.md` diff --git a/scripts/deploy/README.md b/scripts/deploy/README.md index 6d5130d0..225e9b73 100644 --- a/scripts/deploy/README.md +++ b/scripts/deploy/README.md @@ -145,6 +145,86 @@ NPM_FETCH_TIMEOUT=300000 Taro H5 构建存在 webpack asset size warning，这是前端包体优化事项，不影响当前部署继续进行。后续可做拆包、按需加载和 KaTeX 字体裁剪。 +## 服务器接管和故障恢复 + +2026-07-02 最新接管状态： + +- Gitea `main` 已包含旧题库视觉对齐版本，最新提交应至少是 `f54421f`。 +- 服务器仓库仍在 `/opt/tiku-saas/repo`，归属用户应为 `deploy:deploy`。 +- 生产 API 已能启动，`https://api.tjszsb.com/api/tenant/resolve?host=app.tjszsb.com` 已返回 `master` 租户。 +- Supabase self-hosted 运行在 `/opt/tiku-saas/supabase-project`，Kong 通过 Nginx 暴露到 `https://supabase.tjszsb.com`。 +- 线上 H5 公开配置文件在 `/srv/tiku-saas/www/*/runtime-config.json`，密钥只允许放 `supabasePublishableKey` 这类公开 key。 + +接管服务器时先做只读检查： + +```bash +cd /opt/tiku-saas/repo +sudo -u deploy git status --short +sudo -u deploy git log -3 --oneline +sudo -u deploy git remote -v +systemctl status tiku-api --no-pager -l +systemctl status tiku-worker --no-pager -l +docker compose -f /opt/tiku-saas/supabase-project/docker-compose.yml ps +``` + +Gitea SSH 使用 `2222` 端口，推荐服务器 `deploy` 用户的 remote 使用完整 SSH URL： + +```bash +sudo -u deploy git -C /opt/tiku-saas/repo remote set-url origin ssh://git@git.gongxue100.com:2222/chenhaogxjy/tiku-supabase.git +sudo -u deploy ssh -o BatchMode=yes -T -p 2222 git@git.gongxue100.com +sudo -u deploy git -C /opt/tiku-saas/repo pull origin main +``` + +也可以写 `/home/deploy/.ssh/config`，但必须包含 `Port 2222`： + +```sshconfig +Host git.gongxue100.com + HostName git.gongxue100.com + User git + Port 2222 + IdentityFile /home/deploy/.ssh/tiku_saas_deploy + IdentitiesOnly yes +``` + +如果 Taro 构建长时间没有输出，先判断它是真在编译还是已经卡死。构建中的 Taro/webpack 可能会有一段时间安静，但如果 `dist` 目录大小和最近修改时间 30 秒以上都不变，就按卡住处理： + +```bash +ps -eo pid,ppid,user,stat,etime,%cpu,%mem,cmd | grep -E 'npm|node|taro|webpack' | grep -v grep +du -sh /opt/tiku-saas/repo/apps/taro/dist/h5-student +sleep 30 +du -sh /opt/tiku-saas/repo/apps/taro/dist/h5-student +find /opt/tiku-saas/repo/apps/taro/dist/h5-student -type f -mmin -5 | head -20 +``` + +确认卡住后，先在原终端 `Ctrl+C`。如果仍有残留 Taro 构建进程，再只结束这条构建链路，不要杀生产 API、Supabase 或其它 Node 服务： + +```bash +ps -eo pid,ppid,user,stat,etime,%cpu,%mem,cmd | grep -E 'npm run build:taro|taro build --type h5|webpack' | grep -v grep +kill +sleep 3 +kill -9 +``` + +然后清理单端产物并带 CI/内存参数重跑。先单独跑学生端，成功后再跑另外两端： + +```bash +cd /opt/tiku-saas/repo +rm -rf apps/taro/dist/h5-student +sudo -u deploy env CI=1 NODE_OPTIONS="--max-old-space-size=4096" npm run build:taro:h5:student + +rm -rf apps/taro/dist/h5-tenant-admin apps/taro/dist/h5-platform-admin +sudo -u deploy env CI=1 NODE_OPTIONS="--max-old-space-size=4096" npm run build:taro:h5:tenant +sudo -u deploy env CI=1 NODE_OPTIONS="--max-old-space-size=4096" npm run build:taro:h5:platform +``` + +三端构建成功后再发布： + +```bash +sudo -u deploy /opt/tiku-saas/bin/deploy.sh +``` + +如果只是想接管代码开发，不要从服务器 `apps/taro/dist` 或 `/srv/tiku-saas/www` 拷贝产物；它们只是发布结果，源码以 Gitea `main` 为准。 + ## 首次安装 1. 安装基础组件：Docker、Docker Compose、Node.js 20+、Nginx、Certbot、Git、rsync、flock。