# 星痕 · 智能课程工坊

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

## 技术组成

- 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 云服务器运行：

```bash
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`：手动初始化数据库