2026-08-15 07:41:11 +08:00
|
|
|
|
# nl-pms-api
|
|
|
|
|
|
|
2026-08-15 17:04:47 +08:00
|
|
|
|
code-count（view 桌面端）的 **云同步 + 文件存储** HTTP 服务。桌面端不再直连 MySQL：
|
|
|
|
|
|
登录一次拿到 JWT 后，同步、团队、文件上传共用同一 Bearer，无需二次登录。
|
|
|
|
|
|
|
|
|
|
|
|
技术栈：Go + gin + gorm。分层：`router → controller → service → commonservice → model`。
|
|
|
|
|
|
MySQL 库 `code_count` 的 DDL 以本仓库 [`init.sql`](./init.sql) 为唯一来源。
|
|
|
|
|
|
|
|
|
|
|
|
## 鉴权
|
|
|
|
|
|
|
|
|
|
|
|
| 方式 | 说明 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| 公开 | `GET /healthz`；`POST /api/v1/auth/register\|login\|refresh` |
|
|
|
|
|
|
| JWT | 其余 `/api/v1/*`：`Authorization: Bearer <accessToken>` |
|
|
|
|
|
|
| 刷新 | `POST /api/v1/auth/refresh` 用 `refreshToken` 换新双令牌 |
|
|
|
|
|
|
|
|
|
|
|
|
配置项：`jwt_secret`（必填）、`access_ttl_hours`（默认 2）、`refresh_ttl_days`（默认 30）。
|
|
|
|
|
|
|
|
|
|
|
|
身份从 JWT claims 解析（`user_id` / `username`），**不再信任客户端自报 userId**。
|
|
|
|
|
|
|
|
|
|
|
|
## 主要接口
|
|
|
|
|
|
|
|
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| GET | `/healthz` | 健康检查 |
|
|
|
|
|
|
| POST | `/api/v1/auth/register` | 注册 `{username,password}` |
|
|
|
|
|
|
| POST | `/api/v1/auth/login` | 登录 → `{accessToken,refreshToken,userId,username}` |
|
|
|
|
|
|
| POST | `/api/v1/auth/refresh` | 刷新 `{refreshToken}` |
|
|
|
|
|
|
| POST | `/api/v1/auth/change-password` | 改密 `{oldPassword,newPassword}` |
|
|
|
|
|
|
| POST | `/api/v1/sync/push` | `{table,rows}` LWW 推送 |
|
|
|
|
|
|
| GET | `/api/v1/sync/pull` | `table` + `cursor` 增量拉取 |
|
|
|
|
|
|
| GET/PUT | `/api/v1/settings/:name` | 用户/全局设置 KV |
|
|
|
|
|
|
| GET | `/api/v1/settings?prefix=` | 按前缀批量（如 `fest_img:`） |
|
|
|
|
|
|
| GET | `/api/v1/settings/global/:name` | 读管理员全局设置 |
|
|
|
|
|
|
| GET/PUT | `/api/v1/profile` | 公开资料 |
|
|
|
|
|
|
| GET | `/api/v1/notices` | 团队通知 `after=` |
|
|
|
|
|
|
| * | `/api/v1/teams...` | 团队/任务/日报/摘要 |
|
|
|
|
|
|
| POST/GET/DELETE | `/api/v1/files` | 图片上传/列表/删除（JWT） |
|
|
|
|
|
|
| GET | `/files/*path` | 文件公开访问（随机路径） |
|
|
|
|
|
|
|
|
|
|
|
|
上传约束：默认单文件 ≤ 20MB；仅 jpeg/png/gif/webp；同归属秒传去重。
|
2026-08-15 07:41:11 +08:00
|
|
|
|
|
|
|
|
|
|
## 配置
|
|
|
|
|
|
|
2026-08-15 17:04:47 +08:00
|
|
|
|
复制 `config.example.yaml` 为 `config.yaml` 后修改。必填：`jwt_secret`、`mysql.dsn`；
|
|
|
|
|
|
`base_url` 建议填客户端可达地址（拼文件 URL）。
|
2026-08-15 07:41:11 +08:00
|
|
|
|
|
2026-08-15 17:04:47 +08:00
|
|
|
|
## 数据库迁移约定
|
2026-08-15 07:41:11 +08:00
|
|
|
|
|
2026-08-15 17:04:47 +08:00
|
|
|
|
- **仅 dev**（`env: dev`）启动 AutoMigrate。
|
|
|
|
|
|
- **生产绝不迁移**：缺表直接退出。部署前：
|
2026-08-15 07:41:11 +08:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
mysql -u root -p < init.sql
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 运行
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
go run . -config config.yaml # config.yaml 里 env: dev
|
2026-08-15 17:04:47 +08:00
|
|
|
|
go build -o bin/nl-pms-api .
|
2026-08-15 07:41:11 +08:00
|
|
|
|
./bin/nl-pms-api -config /etc/nl-pms-api/config.yaml
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-15 17:04:47 +08:00
|
|
|
|
## 与桌面端的关系
|
2026-08-15 07:41:11 +08:00
|
|
|
|
|
2026-08-15 17:04:47 +08:00
|
|
|
|
view 打包配置 `build/sync.defaults.json` 的 `baseUrl` 指向本服务。
|
|
|
|
|
|
登录后本地存 `sync_access_token` / `sync_refresh_token`；文件存储「服务器」模式只需填本服务 `baseUrl`，鉴权用登录 JWT。
|
