xinghen.work

星痕 · 智能课程工坊

系统支持个人与组织工作区。用户可加入多个组织，课程归属于一个工作区；个人与组织分别拥有积分账户和流水。组织成员可查看本组织课程列表与进度，组织管理员可在独立页面管理成员、课程与组织账单。

技术组成

• React + Vite + TypeScript
• Fastify Server
• PostgreSQL
• PPT 文件保存在服务器本地持久目录，PostgreSQL 保存课程和文件元数据

本地启动

1. 复制环境配置：cp .env.example .env
2. 启动 PostgreSQL：docker compose up -d postgres
3. 安装依赖：npm install
4. 启动前后端：npm run dev
5. 打开 http://localhost:5173

Server 启动时会自动创建所需的数据表。

组织功能

• 平台管理员在 /admin/organizations 创建组织、设置组织管理员和调整组织积分。
• 平台管理员可停用并恢复组织。停用期间停止新成员加入和新建组织课程，历史课程、成员与账单保留。
• 组织管理员在 /organizations/<组织网址标识>/manage 审批加入申请、创建老师账号、生成免审批注册链接、管理组织课程并查看完整账单。
• 普通成员在工作台切换个人或组织工作区；组织页面只显示课程列表、进度和人员名单。成员只能查看自己课程产生的组织积分消耗。
• 组织管理员现场创建老师时只需手机号和姓名；初始密码为 888888，首次登录可直接进入工作区，之后可在账户安全中自行修改密码。
• 上传素材与交付文件通过鉴权接口读取，原 /uploads/ 公开文件路径不再提供文件。
• 已有课程默认保留在个人工作区，已有个人积分保留并转换为个人流水。旧的用户“单位”资料不再参与组织关系。

广告落地页

• 独立入口：landing.html + src/landing/，自带独立样式，与主站路由、全局样式和登录态完全隔离。
• 生产访问：/lp（服务端显式路由，返回 dist/landing.html）；本地开发访问 http://localhost:5173/landing.html。
• 页面提交的线索写入 lead_requests 表，管理员在 /admin/leads 跟进，状态包括：待联系 / 已联系 / 已成交 / 无效，可添加跟进备注。
• 投放时可在链接后带来源参数，例如 /lp?from=wechat-mp 或标准 utm_source / utm_campaign，会随线索一起入库，便于对比渠道效果。
• 修改落地页请只改 src/landing/ 与 landing.css，不要引入主站的 styles.css 或 api.ts。

公网部署

推荐在带持久磁盘的 Linux 云服务器运行：

docker compose up -d --build

应用默认监听 3001 端口。生产环境应使用 Caddy 或 Nginx 配置域名、HTTPS 和反向代理，并修改 docker-compose.yml 中的 PostgreSQL 密码。

postgres_data 和 uploads_data 都是持久卷。部署时必须备份这两个卷；若使用无状态或 Serverless 平台，本地上传文件可能在重启时丢失，应先迁移至对象存储。

常用命令

• npm run dev：开发模式
• npm run build：生产构建
• npm run check：TypeScript 检查
• npm start：启动生产 Server
• npm run db:migrate：手动初始化数据库