CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

团队文档流水线项目，模拟一个四人小团队（PM、设计师、开发、测试）协作完成博客系统的全过程。核心产出是一个 Node.js + Express + Nunjucks + MySQL + TailwindCSS 博客系统，含前台展示与后台管理。

流水线阶段（严格按序执行）

每个阶段 先读 00_skill_lib/ 下对应 Skill，再只改该阶段目录。

口令与阶段详细说明见 .claude/CLAUDE_ROLES.md。目录结构定义见根目录 team.md。

技术架构

项目包含两个子应用，共享同一个 MySQL 数据库：

后端 + 前台 SSR (03_development/src/)

• 框架: Express + Nunjucks 模板引擎
• 数据库: MySQL (mysql2 连接池，supportBigNumbers + bigNumberStrings 已启用)
• 认证: JWT (jsonwebtoken + bcryptjs)
• 样式: TailwindCSS 3
• API 文档: Swagger (swagger-jsdoc + swagger-ui-express)，访问 /api-docs
• 入口: app.js，端口默认 3300

后台 SPA (03_development/admin-spa/)

• 框架: React 19 + React Router 6
• UI 库: Ant Design 5
• 构建: Vite 8，开发端口 5173
• HTTP: Axios，开发时通过 Vite proxy 将 /api 代理到后端 3300
• 表单: @rjsf/antd v6（JSON Schema 驱动动态表单）

模块化 CMS 架构

系统采用四层模块化架构组装页面：

module_types (模块类型: header/nav/section/footer)
  └── module_templates (模板: 每种类型可有多个模板变体)
       └── module_instances (实例: 绑定模板 + 具体配置数据)
            └── page_module_configs (页面配置: 实例挂载到页面 + 排序)

• 模板文件: src/templates/{type}/{slug}.njk + .css + .schema.json
• 加载策略: templateLoader.js 本地文件优先，数据库兜底
• 同步机制: templateSync.js 将本地模板同步到数据库

ID 生成

所有业务表使用 Snowflake（雪花算法） 生成 BIGINT 主键（src/utils/snowflake.js）。INSERT 前必须调用 generateId() 显式传入 ID。mysql2 以字符串返回 BIGINT 值，前端当作不透明字符串使用。

SSR 渲染流程

middleware/systemModules.js 拦截前台请求 → 查询页面绑定的模块 → 用 Nunjucks 渲染每个模块的模板 + 配置数据 → 注入到布局的 headerHtml/navHtml/sectionHtml/footerHtml 变量。

常用命令

# === 后端 (在 03_development/src/ 目录下) ===
npm install              # 安装依赖
npm run init-db          # 初始化数据库（DROP + 重建 + 种子数据）
npm run build:css        # 构建 TailwindCSS
npm run dev              # 开发模式（nodemon 热重载）
npm start                # 生产模式

# === 数据库迁移 (在 03_development/src/ 目录下) ===
npm run migrate:status   # 查看迁移状态
npm run migrate:up       # 应用所有待执行迁移
npm run migrate:down     # 回退最后一个迁移
npm run migrate:reset    # 回退所有迁移

# === 后台 SPA (在 03_development/admin-spa/ 目录下) ===
npm run dev              # Vite 开发服务器 (localhost:5173)
npm run build            # 生产构建
npm run lint             # ESLint 检查

# === 一键启动 ===
chmod +x 03_development/run.sh && ./03_development/run.sh

# === 静态站点构建 (在 03_development/src/ 目录下) ===
npm run build            # 输出到 src/dist/

数据库迁移系统

迁移文件在 src/scripts/migrations/，回退脚本在 migrations/down/。迁移注册在 scripts/migrate.js 的 MIGRATIONS 数组中。migration_history 表追踪已执行的迁移。

添加新迁移：

1. 创建 migrations/vX.X.X_name.sql（up）
2. 创建 migrations/down/vX.X.X_name.sql（down）
3. 在 migrate.js 的 MIGRATIONS 数组末尾追加记录
4. 在 init-db.js 的 migrationRecords 数组中同步追加

注意：init-db.js 是全量重建（DROP DATABASE），它会自动执行所有迁移并记录历史。migrate.js 用于增量迁移管理。

已知兼容性问题

• @rjsf/antd v6 + React 19: 内置按钮组件（MoveUpButton 等）不兼容 React 19。ModuleInstances.jsx 已通过自定义 rjsfButtonTemplates 覆盖修复，新增使用 RJSFForm 的页面需同样传入 templates={{ ButtonTemplates: rjsfButtonTemplates }}。

约定

• 用户可见的字符串和团队职责使用中文
• 团队成员通过短 ID 引用：min（开发）、qiqi（设计）、chen（PM）、xiu（测试）
• 各阶段角色只能写入自己的产出目录，不可修改其他阶段已完成的产出
• 变更接口须同步 02_design/data_model.md 或单独说明差异与原因
• 配置通过 .env 环境变量管理，禁止提交密钥；参考 src/.env.example
• 需求来源文件：根目录 demand.md
• 不确定的问题，需要澄清问题
• 不要反复发起询问，除非是需要确认的问题
• 上下文已经处理过的问题再出现需要记录到你的执行要求中，避免再重复错误