# 开发者文档变更记录

## 2026.11.07-r1（后端 1.11.7）

### 新增

- **运行时数据库后端章节**：首次对外说明平台自身存储层支持三种后端——SQLite 3.46.0（默认，库文件 `app/var/data/cfapi.db`，WAL，内嵌 DDL 自举）、MariaDB 11.8.6、PostgreSQL 18.6（端口 5433）。
- 写明配置形态（三个 URL 槽位常驻 + `DATABASE_URL`/`DATABASE_TYPE` 表示当前生效）、切换入口（后台 `/qq123008/` → 数据库管理，或 `scripts/db_port/cutover.sh sqlite|mysql|postgres`）与切换语义（停写 → 快照 → 搬运 → 行级摘要校验 mismatch=0 → 改配置 → 重启 → 健康检查，失败自动回滚）。
- 写明后端差异导致的静默失效：MySQL `int(11)` 在 PG 是 `int4`、`tinyint` 是 `int2`，解码类型必须按 `bigint↔i64 / integer↔i32 / smallint↔i16` 对齐，否则 MySQL 隐式放宽、PG 拒绝解码且错误常被业务吞掉。质量门已内置这项一致性审计。
- 列出 SQLite 侧的 MySQL 语法改写清单（`INSERT IGNORE` / `IF()` / `CONCAT` / `DATE_FORMAT` / `LIMIT a,b` / `ON DUPLICATE KEY UPDATE` / `COLLATE utf8mb4_*`），以及 PG upsert 自引用列必须带表名的限制。
- 明确插件仍然**禁止直连数据库**，后端类型对插件不可见，切换不需要插件改动。
- `ai-context.json` 增加 `database_backends` 结构化字段（`docs_version` 升到 2026.11.07-r1），供 AI 编码助手直接读取。

## 2026.11.06-r3（后端 1.10.113）

### 新增

- **公开契约拆分**：`/docs/devcenter/openapi.public.json` 只含公开与插件接口（105 路径 / 138 操作），全部 JSON 请求体都有 schema；内部运维接口不在其中。生成脚本 `scripts/gen_openapi_public.py` 带断言：出现无 schema 的 JSON 写操作即失败。
- **TypeScript SDK**：由公开契约生成（`@hey-api/openapi-ts` + fetch client），下载 `/docs/devcenter/downloads/cfapi-sdk-ts.zip`。
- **Postman 集合**：138 个请求，内置 `baseUrl` 与 `token` 变量，下载 `/docs/devcenter/downloads/cfapi-postman.json`。
- **内部接口补 schema**：106 个 `internal-admin-generic` 中，73 个从 Rust serde 结构体导出字段级 schema（标记 `x-schema-source: derived-from-struct`，未逐项运行时校验）；剩余 33 个为无类型 JSON 或非 JSON 请求体，仍明确标注不承诺兼容。

### 安全

- 移除 `upgrade.sh` / `deploy_merge.sh` / `rollback_db.sh` / 两个自测脚本里硬编码的数据库口令，统一由 `scripts/lib_db_cred.sh` 从运行时 `.env` 的 `DATABASE_URL` 读取。
- 执行数据库口令轮换：旧口令已失效（实测拒绝连接），新口令 32 位，服务健康且应用读库正常。
- 修正两个自测脚本把后台路径误当管理员密码的问题，改为读取 `ADMIN_INIT_USER` / `ADMIN_INIT_PASSWORD`。

## 2026.11.05-r2（后端 1.10.112）

### 补齐（按“新开发者从零到上线”的缺口逐项补）

- **补上第一步：账号从哪来**。明确外部开发者走 `POST /api/app/register`（用户名 3–32 位、密码 8–64 位含字母和数字），注册后强制 `external`，再 `POST /api/auth/login` 取 token；内部账号由管理员 `POST /api/admin/users` 创建，没有公开自助注册。写出注册 5 次/分钟、登录 10 次/分钟的 IP 限流。
- **修正错误码表**：`40300` 不再标注“无权限/限流”——限流实际是 `429/42900`；补 `40900` 冲突与 `50300` 暂不可用，并补 HTTP 状态码与业务码的对应列。
- **新增“分页与列表约定”**：`page`（默认 1）+ `page_size`（默认 20，服务端夹到 1–100），返回 `items/total/page/page_size`；空结果为 `[]`。
- **新增“幂等与重试”**：GET 与幂等 PUT 可重试；POST 创建类（投稿/上传/数据新增/扣费）超时后必须先查状态；只对 429/500/503 与网络错误退避。
- **契约补 4 条真实在用的路由**：`POST /api/market/submissions/{code}/withdraw`（页面“撤回待审”按钮在用，此前只在文档里、不在 OpenAPI 里）、`GET /api/plugins/mine`、`GET|POST /api/plugins/categories`、`POST /api/plugins/{code}/submit-review`。
- **新增 `ErrorResponse` 统一错误模型**，`401/403/400/409` 共享响应补上 schema，并新增 429/500/503 共享响应；40 个缺少 4xx 声明的操作补上 401/403。
- **补齐 8 个在用但未定义的 OpenAPI 标签**（插件、后台账号、角色权限、部门、业务用户、公共、认证、系统），Swagger 分组不再是无说明的裸标签。
- **关键请求补示例**：注册、登录、市场投稿、插件数据新增。
- **排版修正**：行内代码不再用 `word-break:break-all` 从中间劈开 API 路径（如 `/api/auth/login` 被拆成两行）；账号表首列不折行、次列给最小宽度，桌面与手机都不再挤成窄条。
- **窄屏宽表格加滑动提示**：表格超出卡片宽度时显示右侧渐隐和“可左右滑动”提示，滑到末尾提示消失；此前手机上表格看起来像被裁掉。切换标签页后会重新测量，避免在隐藏状态下误判为“不需要滑动”。

## 2026.11.05-r1（后端 1.10.108，包含 1.10.106 的文档与插件验签改造）

### 修正（会直接影响开发成败）

- 明确 `external` 外部开发者不能私有创建、上传或启用插件；市场投稿是唯一自助发布路径。
- 拆分两条上传链：
  - 私有安装：`POST /api/plugins/upload?code=...`，raw ZIP，需要 `plugin.manage`，默认 50 MB。
  - 市场投稿：`POST /api/market/upload?plugin_code=...`，`multipart/form-data`，字段 `file`，上限 500 MB，不要求 `plugin.manage`。
- 删除 `plugin.toml` 上传模型；统一以 `plugin.json` 为清单。
- 明确 local 静态入口固定为 `index.html`，`entry` 不改变页面入口。
- 明确代理仅适用于 `remote` + 非空 `base_url`；读需要 `plugin.view`，写需要 `plugin.manage`。
- 明确“市场可见”不等于“无需授权”；仅 `external` 身份不会自动获得权限码；API Key scope 只是前置闸门。
- 删除“市场批准后自动在沙箱运行”的错误说明：批准只更新市场状态与版本记录，不安装、不启用、不部署、不启动沙箱。
- 修正 `set-current` 语义：只切换市场当前版本指针，不替换已部署文件、不重启 remote 服务。
- 按源码修正沙箱默认值：超时 5000 ms、内存 256 MB、CPU 1000 ms、并发 8、网络 `deny`、文件系统 `readonly`、WASM `wasmi`、单次日志 64 KB。
- 删除无源码证据的 seccomp、capability 裁剪、全站 CSRF 等泛化安全声明。
- 删除不存在的 `cargo run --example plugin-test` 调试命令。

### 新增

- 插件专属代理验签密钥：
  - 市场批准后：`GET /api/market/submissions/{code}/signing-secret`（原提交者/超管）。
  - 私有插件：`GET /api/plugins/{code}/signing-secret`（需 `plugin.manage` + 归属）。
  - 代理新增 `X-Platform-Signature`、`X-Platform-Caller-Signature`、`X-Platform-Signature-Version`，按插件派生密钥签名；旧全局签名头保留兼容但不再作为外部验签依据。
  - 插件作用域令牌申领同样接受 `X-Platform-Signature` + 插件专属密钥；签名串为 `code + timestamp`，与代理的 `code + timestamp + tenant` 不同。
- 外部开发者市场发布完整命令链：登录 → multipart 上传 → 验证码 → 提交 → 查询/撤回 → 审核 → 安装 → 取验签密钥。
- 升级、版本历史、切换当前版本、下架的独立语义表。
- local / remote / 沙箱的真实安全边界与责任划分。
- 常见失败原因与上架前检查清单。
- AI 可读取资料：
  - `llms.txt`：入口与硬约束。
  - `llms-full.txt`：完整开发上下文与可复制模板。
  - `ai-context.json`：结构化事实、权限、工作流。
  - `schemas/plugin-manifest.schema.json`：清单 JSON Schema。

### 规范

- `/api/openapi.json` 升级为唯一权威合同。
- 补齐 `/api/market/upload`、`/api/plugins/templates`、`/api/plugins/callable`、`/api/plugins/{code}/export-template`。
- 修正 `PluginManifest.type` 枚举与字段，增加 `entry`、`dependencies`、`requirements`。
- Actix `{param:.*}` 路径统一写成标准 OpenAPI `{param}`，并去掉重复代理路径。
- 修复 11 处嵌套 `responses.200.200` 结构。
- 修复 13 处非标准 5 位响应码。
- 补充插件稳定面的请求体：token、用户、AI、KV、支付、推送、房间、沙箱、数据、市场提交。
- 增加 `x-required-permission` 权限语义。
- `openapi_extra.json` 废弃并清空接口定义。
- 文档与机器可读资源（`.html`/`.txt`/`.md`/`.json`）统一 no-store，避免 Nginx 或浏览器把旧契约缓存 7 天。

### 安全

- 标注内部文档公开副本问题，并将开发者中心改为经鉴权入口读取内部文档。
- 服务端统一拒绝 `/docs/**/internal.html` 公开副本；内部文档改走 `/internal-docs/{doc}` 且按数据库实时层级校验，不再只信任 JWT 中可能过期的 tier。
- 官方示例移除旧域名、前端高权限令牌与未验签的 remote 模板。
- local 示例改为无密钥静态页；remote 示例强制校验平台与调用者签名。
- 旧 CDN 图片库 / 字体库模板从推荐示例移除：其将高权限令牌存入浏览器 localStorage，且 README 与当前路由不一致。
- 公开静态目录移除铁律全集版、完整服务器说明书等敏感副本，只保留脱敏外部版；完整内部版仅经 `/internal-docs/{doc}` 提供。
- 铁律外部版/通用版/内部版由 v0.5.17 源重新生成；停用停留在 v0.5.10/v0.5.15 的旧产物。
- 开发者中心不再展示停留在 v1.10.68 的旧版平台使用说明书，公开 URL 改为迁移说明页，避免继续传播错误的插件类型与令牌用法。

## 修复前状态（2026-11-05 审计）

- 主 OpenAPI 版本停在 1.10.65，补充规范停在 1.10.61。
- 补充规范声称主规范“仅含基础 38 接口”，实际主规范已有 311 个路径。
- 主规范缺少市场投稿上传等端点，Swagger 只加载主规范。
- 官方 local 示例仍指向 `rust.aog.cc`，并要求把 `plugin.manage` 令牌粘贴到前端。
- 官方 remote 示例不校验 `X-Platform-Token`，与页面安全要求矛盾。
- 标注为“内部版”的文档存在匿名可读公开副本。