nl-pms-api/README.md

nl-pms-api

code-count（view 桌面端）的 云同步 + 文件存储 HTTP 服务。桌面端不再直连 MySQL： 登录一次拿到 JWT 后，同步、团队、文件上传共用同一 Bearer，无需二次登录。

技术栈：Go + gin + gorm。分层：router → controller → service → commonservice → model。 MySQL 库 code_count 的 DDL 以本仓库 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；同归属秒传去重。

配置

复制 config.example.yaml 为 config.yaml 后修改。必填：jwt_secret、mysql.dsn； base_url 建议填客户端可达地址（拼文件 URL）。

数据库迁移约定

• 仅 dev（env: dev）启动 AutoMigrate。
• 生产绝不迁移：缺表直接退出。部署前：

mysql -u root -p < init.sql

运行

go run . -config config.yaml     # config.yaml 里 env: dev
go build -o bin/nl-pms-api .
./bin/nl-pms-api -config /etc/nl-pms-api/config.yaml

与桌面端的关系

view 打包配置 build/sync.defaults.json 的 baseUrl 指向本服务。 登录后本地存 sync_access_token / sync_refresh_token；文件存储「服务器」模式只需填本服务 baseUrl，鉴权用登录 JWT。