diff --git a/docs/BACKLOG-archive.md b/docs/BACKLOG-archive.md index 26776727..309af231 100644 --- a/docs/BACKLOG-archive.md +++ b/docs/BACKLOG-archive.md @@ -3,8 +3,32 @@ > 从 [BACKLOG.md](./BACKLOG.md) 迁出的历史条目,**行文保留迁出时原样**(含当时措辞、链接与遗留注记)。 > 首次归档:2026-08-13(31 项)。之后每当 BACKLOG 有项完成,按其维护规则把整行移到本表顶部。 +## 2026-11-08 源码核对补记 + +以下迁出行的主题保留原历史措辞,状态列更新为本轮结论。迁出依据以 [本轮核对记录](migration/backlog-audit-2026-11-08.md) 为准;“实现已存在”不代表本次执行过部署或数据核验。 + +- **B-028**:源码已实现:现有 workflow 的 deploy-prod job 由 workflow_dispatch + deploy_prod 触发;本次未核验实际发布环境。 +- **B-039**:源码已实现:当前问卷页面消费后端结构并使用 submitPaperV2;早期固定槽方案已由 B-041 数组契约取代。 +- **B-040**:源码已实现:角色、音乐和 CP 成员来自后端候选;资源、别名、candidate ID 与筛选 metadata 已接入。 +- **B-041**:源码已实现:问卷数组、category/order、required、隐藏组及结构化答案提交/回填已消费;本次未验证题库或线上验收。 +- **B-050**:v1 与后补2/5/6 均已实现,不能再把 trend、DSL、数据库白名单列为未做;上届对比单独保留为 B-050-后补3。 +- **B-050-后补2**:append-only 净增量趋势已由主榜和 DSL 子集路径消费;原尾项 attempt 列也已在源码展示。 +- **B-057**:实现收口:管理列表/归属编辑、导入按名称查找/创建 work、前端 Task8/9 与 candidateId 已具备,CP metadata 收口为前端 edeaeea;历史榜单导入并入 B-050-后补3。 +- **B-061**:源码已有 API attempt 字段、DAO 取值和管理界面列,原“未展示”描述失实。 +- **B-063**:已补关键站点解析、URL 路由及限流测试,见 2026-10-20 CHANGELOG;不表示穷尽每个站点成功路径。 + | 编号 | 主题 | 严重度/状态 | 可并行做? | 源文档 | |---|---|---|---|---| +| **B-028** ⚡ | `.github/workflows/deploy-test.yml` 当前唯一的部署 workflow 没有 prod 路径——main 分支推送也只触发部署到 test 环境(镜像 tag 区分为 `prod` vs `test`,但部署目标都是 TEST_SERVER_HOST)。需要确认是否真的没有 prod 发布通道,或补一个 `deploy-prod.yml`。**注:2026-05-19 的 3 个 `fix(ci)` 提交只是修 deploy-test.yml 的 YAML/包发现 bug,未补 prod 通道,此项仍开放** | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | [cicd-pipeline §二](./operations/cicd-pipeline.md) | +| **B-039** | 问卷结构化系统(Block 3A):后端 4 结构表 + admin 整树导入 + structure 查询 + 结构化答题 + 完成校验升级;前端 questionnaireV2 改从后端拉(一次性切换) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期,旧方案由 B-041 取代 | — | 后端✅:模型0008/assembler/completion/domain/graphql submitPaperV2/门禁升级/整树导入+UI;前端[plan](archive/superpowers/plans/2026-06-08-questionnaire-frontend.md)待做 | +| **B-040** | 投票对象迁后端(Block 3B):角色/音乐 merged_into 去重合并(自动+admin手调) + /vote-objects/characters\|music\|{id} 分类查询;前端角色/音乐/CP 改从后端拉 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 后端✅:merged_into 0009/detect_merges/merge端点/compute归并/vote-objects端点/合并UI;前端[plan](archive/superpowers/plans/2026-06-08-vote-objects-frontend.md)待做 | +| **B-041** | 问卷管理增强:自由问卷列表(去年份,持续迭代) + 全层级 CRUD(问卷/题组/题/选项) + 自研嵌套编辑器;契约改问卷数组(migration 0010);取代 B-039 的 admin/契约部分 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 后端✅:模型重塑+0010/assembler数组/importer数组/completion required/结构端点去年份/扁平答案/13 CRUD端点/自研嵌套编辑器UI;前端[plan](archive/superpowers/plans/2026-06-08-questionnaire-admin-frontend.md)待做 | +| **B-050** ⚡ | **计票系统大重写** —— ✅ **v1 完成 (2026-07-18)**:计票已改读真实提交表 `raw_*`(取每 `vote_id` 最新、排除 `invalidated`);按角色/音乐 id 归票 + 白名单丢未知 id;CP 改无序 multiset(顺序/主动方不进 key)+ 主动率 + 组合票数 1 不计;名次口径对齐权威文档(票数→本命数→系统ID,同票数同名次虚位);`RankingEntity` schema 补 `id`/`favorite_percentage_of_all`。删死表 vote_data 已完成(2026-07-17)。**v1 后补子项:1/4/8 已在 `feat/result-graphql-compat` 分支完成(2026-07-19,见下),2/3/5/6 仍开放**。 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期;历史对比/数据剩余并入 B-050-后补3 | — | **[设计稿:纯 id 记票重写](./superpowers/specs/2026-07-18-result-recount-id-based-design.md)**(§九 v1 实现落地);`compute_dao.py`/`compute.py`/`compute_service.py`/`whitelist.py`;数据落点见 B-049 | +| **B-050-后补2** | trend 投票演进 | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | 同上设计稿 §9.4;CHANGELOG 2026-08-29 两条目 | +| **B-057** | voteable/work 重构收尾清单(2026-07-23 合入盘点发现):①✅**已完成**(2026-08-22,`feat/b060-b057`)——`GET /admin/voteables`(联 work 出 workId/workName/workType,q/分页)+ `POST /admin/voteables/{id}` 编辑 work 归属(清 vote-objects 缓存),5 测试;admin-ui 消费页面可后补;② admin import 的 work 按 name 匹配/自动建 work(Task 5,计划内 tech-debt);③ 上届 `final_ranking`(year=11) 导入未执行(会议结论要求"只导上届");④ 前端 Task 8/9(characterList/musicList 过滤逻辑、专辑名反查)+ **提交侧切 candidateId**(前置 B-050-后补6 已于 08-13 解除;**前端=我方负责**);⑤ 设计稿/plan 的 checkbox 与状态维护(与 zfq 沟通) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期;历史对比/数据剩余并入 B-050-后补3 | — | [work 统一设计稿](./superpowers/specs/2026-07-21-work-table-unified-design.md);[实施计划](archive/superpowers/plans/2026-07-21-work-table-unified.md);CHANGELOG 2026-07-23 条目 | +| **B-061** | admin 监控投票列表(`src/apps/admin/monitor/`)展示 `attempt` 列:B-050-后补2 Step 2 把 `raw_*`/`paper_answer` 改成 append-only 后,同一选民多次改票会在监控列表出现多条历史行,当前列表未展示批次号,管理员不易一眼分辨"哪几行属于同一次改票" | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | `src/apps/admin/monitor/`;CHANGELOG 2026-08-29 append-only 条目 | +| **B-063** | `apps/scraper` 模块**无任何测试**(`tests/` 下无 scraper 相关用例)——外部 HTTP 依赖需 mock。与 B-010(覆盖率门禁切 `fail_under=80`)同域:scraper 是当前最大的未覆盖面(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,已复核仍成立**) | ✅ 已有实现(2026-11-08 源码核对);原缺口描述已过期 | — | `src/apps/scraper/`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §十 | +| **B-062** | `AutocompleteDAO.search_cps()` 恒返回 `[]`(`src/apps/autocomplete/dao.py:78`)——CP 自动补全端点 `POST /autocomplete/search` 的 CP 分类**永远为空**。角色/音乐走 `candidate_character`/`candidate_music` 表 ILIKE 已实现,CP 无现成候选表,需从已提交的 `cp.cp_list` JSON 抽唯一 CP 名做模糊匹配(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,代码侧已复核仍成立**) | ✅ 已废弃(2026-11-08,本地未部署):旧建议链路及空 CP 方法随统一候选搜索移除;CP 成员使用 character 搜索,未新增 CP 组合推荐 | — | `src/apps/autocomplete/dao.py:77-78`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §六 | | **B-008** | ~~MongoDB → PostgreSQL 历史用户数据回填脚本~~ | ✅ 已废弃 (2026-09-06):上线即空库,不再从旧 Mongo 导入用户;`map_voter`/voters 同步项随身份模型归一化删除,见 CHANGELOG 2026-09-06 | — | [medium-priority-backlog-design](./superpowers/specs/2026-05-16-medium-priority-backlog-design.md) | | **B-011** | ~~SSO 落地后移除 `User.at_least_one_identifier` CHECK 约束(约束仍在 `src/db_model/user.py:49` + migration 0001)~~ | ✅ 已完成 (2026-09-06):CHECK 约束随 migration 0018(`user_identity`)一并删除 | — | [design §九 F7](./superpowers/specs/2026-04-27-user-auth-design.md) | | **B-064** | ~~迁移 0018 回填把「管理员封禁」当成「自助注销」,`WHERE removed = FALSE` 把封禁账号一并排除,其邮箱/手机被释放、解封后无身份可登录~~ | ✅ 已完成 (2026-09-12):**并非 GDPR 与封禁二选一** —— 旧 `remove_voter` 把 email/phone/password 全部置空而 `ban_user` 一个不动,两者可区分。回填范围改用 `_BACKFILL_SCOPE`(`removed = FALSE OR email IS NOT NULL OR phone_number IS NOT NULL`),封禁账号完整回填、自助注销账号一条不回填(含旧实现漏清的 qq/thbwiki)。真 PG 四形态验证通过 | — | [design §七](./superpowers/specs/2026-09-06-user-identity-model-design.md) | diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 6e379f5d..5e2fd991 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -1,120 +1,65 @@ -# 后续开发 BACKLOG(单一仪表盘) +# 后续开发 BACKLOG -> 创建日期:2026-04-27 -> 最后更新:2026-08-31(文档大扫除:新增 B-062/B-063——从已归档的 `REFACTOR_TODO.md` 迁入两条经代码复核仍成立的缺口;docs 树归档重整,详见 CHANGELOG 2026-08-31)。此前:2026-08-13 第二轮(大扫除:31 条已完成/废弃项迁至 [BACKLOG-archive.md](./BACKLOG-archive.md);B-028/B-054/B-042②/B-043尾项标 ⏸ 等外部——用户确认只能等;前端队列确认我方负责) +> 创建:2026-04-27。当前核对:2026-11-08。 +> 源码基准:后端 `44bd972`(包含 `origin/main=6d8afc1`),前端 `edeaeea`(包含 `origin/dev=ef028e0`);本次已 fetch 核对远端。 +> 只核验已提交源码及维护记录,没有查询线上数据库、Nacos、告警服务或部署状态,也没有运行浏览器验收。完整证据见 [核对记录](migration/backlog-audit-2026-11-08.md)。 -把散落在 5 份文档里的 follow-up 收拢到这里。**这是仪表盘,不是真理来源**——每项的上下文还在原文档里,本表只给一行摘要 + 跳转。 +本表记录尚需决策或处理的事项。历史文档、空 checkbox、与其他语言实现不同或缺少某项可选能力,都不能单独作为缺陷证据。已实现/废弃内容进入 [归档](BACKLOG-archive.md),不继续重复排期。 -如果新发现 follow-up,**两件事都要做**:(1)写进对应主题的源文档;(2)在本表加一行。 +## 已确认仍有源码差异或待决定的行为 ---- +| 编号 | 当前事实 | 剩余范围/边界 | 证据 | +|---|---|---|---| +| **B-037** | 提名校验响应、待审核提示及问卷门禁已接入前端;“前端待做”失实 | 原计划逐条 index 提示与现有合并原因/重复数量展示有差异,是否调整待产品判断;可选 approved 列表不自动变为需求 | [前端计划](archive/superpowers/plans/2026-06-08-security-frontend.md);`Touhou-Vote/packages/vote/src/vote-doujin/VoteDoujin.vue` | +| **B-050-后补3** | 主榜与 DSL 子集仍传空 historical,历史字段返回 -1/-1.0;旧 load_historical 已删除 | 若需要上届对比,需确认历史数据、ID 对应及接口接线。2026-08-22 旧 API 可用只是历史记录,本轮未核验数据/服务,不执行导入 | `src/apps/result/compute_service.py`、`advanced_search/service.py`、`src/api/graphql/result_compat.py` | +| **B-059** | Nacos 失败会记 warning,再尝试本地配置并可能回退默认值;并非无日志“静默”回退 | 是否改为 fail-fast 及适用运行模式仍需确认;历史事故不能自动授权增加恢复机制 | `src/common/nacos.py`、`src/common/config.py`;[Nacos 手册](operations/nacos-config-center.md) | +| **monitor 文案** | `_B050_NOTE` 仍说“需 B-050 落地后生效”,但计票已排除作废票 | 真实残留为提示文案;处置后仍需重算结果。本轮只核对文档,未修改业务响应 | `src/apps/admin/monitor/router.py`、`src/apps/result/compute_dao.py` | -## 状态总览(现存开放项;已完成/废弃项见 [BACKLOG-archive.md](./BACKLOG-archive.md)) +## 发布、运营及外部状态事项 -| 编号 | 主题 | 严重度 | 可并行做? | 源文档 | -|---|---|---|---|---| -| **B-010** | 测试覆盖率门禁切到 `fail_under=80` | 低 | 🟡 待模块稳定 1-2 sprint | [design §九 F6](./superpowers/specs/2026-04-27-user-auth-design.md) / spec §九 | -| **B-013** | 邮件/短信发送的"已发送"幂等性(避免阿里云调用成功但写日志失败造成的双发) | 低 | 🟡 低优先级,待发送链路稳定 | [design §九 F9](./superpowers/specs/2026-04-27-user-auth-design.md) | -| **B-019** | 错误响应 `{"detail":"..."}` 与 Rust 的 `{"error":"...","service":"..."}` 不一致 | 低 | 🟡 等前端反馈是否需要 | [open-issues §三 U-11](./superpowers/specs/2026-04-27-user-auth-open-issues.md) | -| **B-020** | mypy 在 CI 不是硬门禁;先清现存告警,再去掉 `\|\| true` | 低 | 🟢 可立即做 | [open-issues §三 U-12](./superpowers/specs/2026-04-27-user-auth-open-issues.md) | -| **B-026** | DB 治理纪律:PR 模板 model 改动提示 / CI `alembic check` / `db_model 改动必须有 migration` 检查 | 低 | 🟢 可立即做(**阻塞已解除**:B-025 已完成) | [schema-mgmt §三阶段 4](./architecture/database-schema-management.md) | -| **B-028** ⚡ | `.github/workflows/deploy-test.yml` 当前唯一的部署 workflow 没有 prod 路径——main 分支推送也只触发部署到 test 环境(镜像 tag 区分为 `prod` vs `test`,但部署目标都是 TEST_SERVER_HOST)。需要确认是否真的没有 prod 发布通道,或补一个 `deploy-prod.yml`。**注:2026-05-19 的 3 个 `fix(ci)` 提交只是修 deploy-test.yml 的 YAML/包发现 bug,未补 prod 通道,此项仍开放** | 高 | ⏸ **等上游拍板**(2026-08-13 用户确认:只能等) | [cicd-pipeline §二](./operations/cicd-pipeline.md) | -| **B-031** | `src/common/nacos.py` 的 `_parse_config_content` 自带 JS 风格 JSON 容错解析(正则提取),属于隐式技术债——上游 Nacos 配置应该写标准 JSON,让解析器走 `json.loads`。如果是为了兼容某个老 dataId,需文档化该 dataId 的写法约束 | 低 | 🟢 可立即做 | `src/common/nacos.py:29-97` | -| **B-037** | 安全块:二创提名校验(域名/发布时间/udid去重)+ 人工审核队列 + 提名时间窗 + 投票问卷门禁(弱校验) | 🟡 后端+管理端已完成 (2026-06-08);前端待做(**前端=我方负责,准备开做**,2026-08-13) | — | 后端✅[plan](./archive/superpowers/plans/2026-06-08-security-backend.md):配置/模型0007/纯校验/DAO/编排+门禁/GraphQL/管理端审核UI/公开查询;前端[plan](./superpowers/plans/2026-06-08-security-frontend.md)待实施 | -| **B-039** | 问卷结构化系统(Block 3A):后端 4 结构表 + admin 整树导入 + structure 查询 + 结构化答题 + 完成校验升级;前端 questionnaireV2 改从后端拉(一次性切换) | 🟡 后端已完成 (2026-06-08, 已合并 main 2026-07-14);前端待做(**前端=我方负责,准备开做**,2026-08-13) | — | 后端✅:模型0008/assembler/completion/domain/graphql submitPaperV2/门禁升级/整树导入+UI;前端[plan](./superpowers/plans/2026-06-08-questionnaire-frontend.md)待做 | -| **B-040** | 投票对象迁后端(Block 3B):角色/音乐 merged_into 去重合并(自动+admin手调) + /vote-objects/characters\|music\|{id} 分类查询;前端角色/音乐/CP 改从后端拉 | 🟡 后端已完成 (2026-06-08, 已合并 main 2026-07-14);前端待做(**前端=我方负责,准备开做**,2026-08-13) | — | 后端✅:merged_into 0009/detect_merges/merge端点/compute归并/vote-objects端点/合并UI;前端[plan](./superpowers/plans/2026-06-08-vote-objects-frontend.md)待做 | -| **B-041** | 问卷管理增强:自由问卷列表(去年份,持续迭代) + 全层级 CRUD(问卷/题组/题/选项) + 自研嵌套编辑器;契约改问卷数组(migration 0010);取代 B-039 的 admin/契约部分 | 🟡 后端+管理端已完成 (2026-06-09, 已合并 main 2026-07-14);投票前端待做(**前端=我方负责,准备开做**,2026-08-13) | — | 后端✅:模型重塑+0010/assembler数组/importer数组/completion required/结构端点去年份/扁平答案/13 CRUD端点/自研嵌套编辑器UI;前端[plan](./superpowers/plans/2026-06-08-questionnaire-admin-frontend.md)待做 | -| **B-043** | 注册防刷:发验证码前强制人机验证(阿里云验证码 2.0,service 层双入口收口,默认 fail-closed)+ 补齐发码端点 per-IP 限流与短信 per-号码守卫(当前发码端点**无任何后端限流**,2026-07-16 勘探发现) | 🟡 **人机验证已通真人验收** (2026-07-17):后端壳+Nacos(ENABLED=true,fail-closed)+前端 widget(Touhou-Vote `11a7630`,含 getInstance 触发时机修复)全链路打通,浏览器实测弹窗→过验→倒计时→收码正常;剩:①~~发码 per-IP 限流+短信 per-号码守卫~~✅已做(2026-07-17,service 层 per-IP 30/60s@captcha前 + 短信 per-号码 1/60s@captcha后,367 passed) ②海外网络加载实测 ③上线前切公家账户(手册§六,⏸ 等上游,2026-08-13) | — | [design](./superpowers/specs/2026-07-16-captcha-anti-abuse-design.md) / [接入手册](./operations/captcha-onboarding.md) | -| **B-048** | 拦脚本:让变更请求尽量来自真人浏览器。① 服务端 Origin/Referer 校验(对 GraphQL mutation + REST 提交/发码/登录要求带浏览器头,不带→403)② 端口收口(`:18000` 直连关闭,走 nginx) | 🟡 ①**已合并已部署,默认关** (2026-08-13 确认在 main:`REQUIRE_BROWSER_ORIGIN` 默认 false)——待 Nacos 置 true 灰度开启+真人回归;②**待办**(阻塞:前端 codegen 直连 :18000,收口前须先改走 nginx 代理) | 🟢 ①只差配置开关;②需先改前端 codegen | [design](./superpowers/specs/2026-07-17-block-scripts-design.md) | -| **B-047** | 反机器人特征 IP→ASN/数据中心归属:投票/注册 IP 富化出 ASN、标记机房/代理 IP(阿里云 ECS/AWS 等机房 IP 投票=高度可疑)。写入时或离线查;或用数据中心 IP 段名单。只取证不拦截 | ⏳ 待办(用户 2026-07-17 指定放待办) | 🟢 可独立做(依赖 B-044 可信 IP,已具备) | [反机器人特征清单见 submit-timing/anti-vote-farming 设计] | -| **B-049** | 管理端安全监控台:`require_admin` 统一闸门(secret 常量时间比较 + IP 白名单,fail-closed) + 监控 API(概览/IP·设备聚类/可疑打分/投票浏览器/账号钻取) + 处置动作(单条投票作废/恢复、账号人工复核,仅记录) | 🟡 **后端 Plan 1 已实现** (2026-07-17):migration `0014`(`raw_*.invalidated` + 索引 + `voter_review` 表) + `src/apps/admin/monitor/`(只读查询 + 处置端点,401 passed,flake8 clean)。**处置动作仅写标记/行,不接入排名计算**——排名效果推迟到 B-050。①✅ `main.py` 三个 ops 端点(`reload-config`/`discover*`)已纳入 `require_admin` 闸门(2026-07-17,勘察确认无内部/自动调用方,唯一调用方是带 secret 的 admin UI);②前端 Plan 2 **Phase 1+2 已实现** (2026-07-18):`admin-ui/` Vue3+Vite+TS 模块化(api client/composable/共享组件/view)。Phase 1=仪表盘+5 监控页+Users;Phase 2=**全部 6 个旧工具已迁**(候选项/数据同步/提名审核/问卷 4 层嵌套编辑器/审计日志/导出)。旧面板 `/admin-ui-legacy` 暂留兜底。**待:①视觉验收后删 legacy**(dir+挂载+nav 入口);②几个无 UI 端点补上(用户详情钻取/建合并/ranking preview) | 🟢 验收后清理 legacy;无 UI 端点可选补 | [design](./superpowers/specs/2026-07-17-admin-console-vue-security-monitoring-design.md) / [backend plan](./archive/superpowers/plans/2026-07-17-admin-console-security-monitoring-backend.md) | -| **B-050** ⚡ | **计票系统大重写** —— ✅ **v1 完成 (2026-07-18)**:计票已改读真实提交表 `raw_*`(取每 `vote_id` 最新、排除 `invalidated`);按角色/音乐 id 归票 + 白名单丢未知 id;CP 改无序 multiset(顺序/主动方不进 key)+ 主动率 + 组合票数 1 不计;名次口径对齐权威文档(票数→本命数→系统ID,同票数同名次虚位);`RankingEntity` schema 补 `id`/`favorite_percentage_of_all`。删死表 vote_data 已完成(2026-07-17)。**v1 后补子项:1/4/8 已在 `feat/result-graphql-compat` 分支完成(2026-07-19,见下),2/3/5/6 仍开放**。 | 🟡 中(核心闭环已修复,后补项非阻塞) | — | **[设计稿:纯 id 记票重写](./superpowers/specs/2026-07-18-result-recount-id-based-design.md)**(§九 v1 实现落地);`compute_dao.py`/`compute.py`/`compute_service.py`/`whitelist.py`;数据落点见 B-049 | -| **B-050-后补2** | trend 投票演进 | ✅ **已完成**(两步交付,2026-08-29):**Step 1**——`compute_paper_results` 已产出按提交行 `created_at` 分桶的近似 trend,`queryQuestionnaireTrend` 已接通(含 DSL 子集路径)。**Step 2**——`raw_*`/`paper_answer` 四表改造为 **append-only** 存储(迁移 0017,`paper_answer` 加 `attempt` 批次号 + 索引、删原 UNIQUE 约束;`SubmitDAO._upsert` 不再删旧插新),新纯函数 `src/apps/result/trend.py::net_delta_trends` 把角色/音乐/CP/问卷全类别 `trend`/`trend_first` 升级为真实净增量序列(改票产生负桶,不变量:每实体分桶净增量之和 == 最终票数),`compute_all` 与 DSL 子集重算路径均已接入。剩余小尾巴见 **B-061**(admin 监控列表展示 attempt 列) | — | 同上设计稿 §9.4;CHANGELOG 2026-08-29 两条目 | -| **B-050-后补3** | 上届对比:需历史 `final_ranking` 表有数据,且 `compute_dao.load_historical` 的 key 是 name、与 id-based 归票路径未对齐(现 `compute_service.py` 传空 `{}`)。**仍开放**——本轮契约层 `RankingEntry`/`CPRankingEntry` 的 8 个 `*_last_1`/`*_last_2` 历史字段已按 brief 要求固定填 -1 哨兵(见契约层 `_ranking_entry_from_dict` docstring 的"移除条件"),此项落地后需同步把契约层从硬编码 0 改成读 `rank[1]`/`rank[2]` 快照。**数据源已验证**(2026-08-22):老 Rust 生产 API `touhou.ai/vote-be/graphql` 的 `query*Ranking(voteYear:11)` 可直取上届完整榜(char totalVotes=13283 实测),字段与 `final_ranking` 表一一对应,无需找 dump;**导入动作等用户与协作方沟通后再执行** | 低 | ⏸ 等沟通(数据源就绪) | 同上设计稿 §9.4 | -| **B-053** | 通用"任意问卷题 × 投票结果"交叉分析 API + 前端(与 B-050-后补5 高级搜索同组,共用 `vote_id → {题code: [选项code]}` 索引,**该索引已在 2026-08-14 落地于 `src/apps/result/advanced_search/subset.py` 的 `build_facts`/`evaluate_subset`,可直接复用**):本轮只落地了"性别"这一个特例分段(经配置指定的固定题),通用查询(任选一道问卷题作为切分轴,交叉任意投票结果)与配套前端本轮未做——全题目预聚合会撑爆 Redis 榜单(244 角色 × 32 题 × 40 选项),应按需算 | 低 | 🟢 可独立做(与 B-050-后补5 同组) | 本设计稿 §五「C1.2」/§九「BACKLOG」;子集原语见 `src/apps/result/advanced_search/subset.py` | -| **B-054**(运营) | 录入真实问卷内容并回填 `question_def`/`option_def` 的 `code` 列:线上问卷结构是占位文案 + 非语义自增 id(问卷 id=1,2,3/组 id=1,2/题 id=1,2,3/选项 id=1,2),**在此之前性别票(B-050-后补1)与问卷结果(B-050-后补4)的统计管道虽已就绪,数字恒为 0**。前端 legacy `Touhou-Vote/packages/shared/data/questionnaire.ts` 含真实问卷内容 + 真实 7 位 id,是现成的导入源,不必手敲 | 高(阻塞两个契约层字段出真实数据) | ⏸ **等出题方**(2026-08-13 用户确认:只能等) | 本设计稿 §四「B」;`Touhou-Vote/packages/shared/data/questionnaire.ts` | -| **B-055**(前端,Touhou-Vote 仓库) | Task 7 验收时勘察 `packages/result/src` 发现的前端已知缺口(与本仓库后端无关,记录以便跨仓库跟踪):① `characterConnect.vue`/`MusicConnect.vue` 是"维护中"占位页(covote 契约本轮已修好,但无消费方);② `Doujin.vue` 总票数硬编码字面量 `1272`,无 GraphQL 查询;③ CP 部门只有 `Couple`/`CoupleDetail`/`CoupleSingleDetail`/`CoupleReason` 四页,缺角色/音乐都有的 compare/evolution 页;④ `router.ts` 里 `/test` → `Test.vue` 调试路由无条件注册在生产路由表 | 低(另一仓库,不阻塞本仓库任何工作) | — | `Touhou-Vote/packages/result/src/{pages/characterConnect.vue,pages/MusicConnect.vue,pages/Doujin.vue,router.ts}` | -| **B-056** | 迁移编号约定漂移:zfq_dev 的 voteable/work 重构引入 autogenerate 哈希名迁移 `12a5f2e6dbed_voteable_cross_year_stable_id`(约定应为 `00XX` 顺延)。测试库 `alembic_version` 已记录该 id,**改名需 stamp 修正、不建议轻动**——文档化现状即可;`0015` 已重接其后成单链(`0014→12a5f2e6dbed→0015`),**后续新迁移从 `0016` 顺延、down_revision 指 `0015`**。与 zfq 同步一下命名约定,避免下次再产生哈希名 | 低 | 🟢 纯约定沟通 | `alembic/versions/12a5f2e6dbed_*.py`;[[branch-ownership-zfq-dev]] 约定见 CLAUDE.md §9 | -| **B-057** | voteable/work 重构收尾清单(2026-07-23 合入盘点发现):①✅**已完成**(2026-08-22,`feat/b060-b057`)——`GET /admin/voteables`(联 work 出 workId/workName/workType,q/分页)+ `POST /admin/voteables/{id}` 编辑 work 归属(清 vote-objects 缓存),5 测试;admin-ui 消费页面可后补;② admin import 的 work 按 name 匹配/自动建 work(Task 5,计划内 tech-debt);③ 上届 `final_ranking`(year=11) 导入未执行(会议结论要求"只导上届");④ 前端 Task 8/9(characterList/musicList 过滤逻辑、专辑名反查)+ **提交侧切 candidateId**(前置 B-050-后补6 已于 08-13 解除;**前端=我方负责**);⑤ 设计稿/plan 的 checkbox 与状态维护(与 zfq 沟通) | 中 | 🟢 ①②③可独立;④前置已解除,入我方前端队列 | [work 统一设计稿](./superpowers/specs/2026-07-21-work-table-unified-design.md);[实施计划](./superpowers/plans/2026-07-21-work-table-unified.md);CHANGELOG 2026-07-23 条目 | -| **B-059** | 后端 Nacos 不可达时**静默回退**默认配置(localhost DB)再崩——08-13 事故中真实根因(Nacos auth 500)被掩埋在 asyncio 未回收异常里,排障绕了一圈。改法:`NACOS_ENABLED=true` 且拉取失败时 fail-fast 抛明确错误(带"检查 mynacos 容器"提示),不要带默认值起跑。与 B-017(热更新限制)同域 | 中(排障成本,已有 CI 前置检查兜一层) | 🟢 可立即做 | `src/common/nacos.py`/`config.py`;事故记录 `docs/operations/nacos-config-center.md` §八 | -| **B-061** | admin 监控投票列表(`src/apps/admin/monitor/`)展示 `attempt` 列:B-050-后补2 Step 2 把 `raw_*`/`paper_answer` 改成 append-only 后,同一选民多次改票会在监控列表出现多条历史行,当前列表未展示批次号,管理员不易一眼分辨"哪几行属于同一次改票" | 低 | 🟢 可独立做 | `src/apps/admin/monitor/`;CHANGELOG 2026-08-29 append-only 条目 | -| **B-058** | dependabot 9 个 npm 告警(3 高 6 中,2026-08-13 push 时发现):全部位于 `admin-ui/` 构建链(vite≤6.4.2 fs.deny 绕过/路径穿越、esbuild dev-server、nanoid、postcss)。**均为 dev/构建期依赖,不进运行时**(admin-ui 走 commit-dist);风险=开发者本机跑 `pnpm dev/build` 时。修法:`cd admin-ui && pnpm update vite esbuild postcss nanoid` + 重建 dist | 低(构建期,非线上面) | 🟢 可立即做 | https://github.com/PatchyVideo/thvote-be-re/security/dependabot | -| **B-046** | 反机器人特征:User-Agent(服务端取)+ 浏览器环境(tz/screen/lang,前端采)落 `raw_*.client_env`(单 JSON 列 migration 0013)。只取证不拦截 | 🟡 **后端已合并已部署** (0013 已在测试库,2026-08-13 盘点确认在 main);前端(Touhou-Vote `4b89a23`)状态需在前端仓核对。待:①前端侧确认已推+真人验证 ②Phase 2 聚类纳入 | — | [design](./superpowers/specs/2026-07-17-submit-timing-signal-design.md) | -| **B-045** | 反机器人时序特征:提交耗时 `fill_duration_ms`(客户端挂载→提交,新列 migration 0012)+ 服务端 `attempt` 改票计数(复用死列,首次=1/改票≥2)。只取证不拦截;"耗时短=可疑"只对首次生效,改票豁免(根治改票假阳性) | 🟡 **后端已合并已部署** (0012 已在测试库,2026-08-13 盘点确认在 main,07-24 tally 系列还补了首填耗时防洗白);前端(Touhou-Vote `f59585a`)状态需在前端仓核对。待:①前端侧确认已推+真人验证 ②Phase 2 管理端多信号聚类 | — | [design](./superpowers/specs/2026-07-17-submit-timing-signal-design.md) | -| **B-044** | 反刷票证据采集:设备 UUID 指纹(注册 + 每票)+ 可信客户端 IP(读 X-Real-IP、CIDR 信任、REST 覆盖)。只取证不拦截,供事后按 IP/设备聚类多账号 | 🟡 **Phase 0 已联调验证** (2026-07-17):后端(0011+deviceId落库+IP修复,355 passed,已部署)+前端(Touhou-Vote `4b9f4c5`,已部署:8082)+Nacos `TRUSTED_PROXY_IPS` 已配;真人投票实测:新票记真实公网 IP(对照旧票 nginx 内网 172.18.0.7)+设备指纹已落 raw_*。待:①Phase 1 FingerprintJS(+ HTTP 兜底改 crypto.getRandomValues) ②Phase 2 管理端聚类视图 ③~~投票记录 append-only 评估~~✅**已完成**(2026-08-29,B-050-后补2 Step 2:迁移 0017 落地 `raw_*`/`paper_answer` append-only 存储,见 CHANGELOG 同日条目) ④admin 端点暴露 register_device_id/投票指纹(现仅 CSV 出 user_ip) | — | [design](./superpowers/specs/2026-07-17-anti-vote-farming-design.md) | -| **B-042** | 测试环境配置硬化(2026-07-14 联调准备中实测发现):①✅ **已解决**(2026-07-17)——Nacos `thvote_be` 已配 `ADMIN_SECRET`(测试弱值 `abc123`,公开前换强值),`require_admin` fail-closed(secret+IP 白名单)已覆盖 `/api/v1/admin/*` 两路由 **+ `main.py` 三个 ops 端点**(`reload-config`/`discover*`),admin 不再裸奔;② scraper **Pixiv 凭据仍未配**(`Pixiv authentication failed`),二创提名刮削 Pixiv 源不可用,**上线前必须配**(配完需重启容器,B-017) | 低(仅剩 Pixiv 配置项,且 2026-08-13 用户示意**可能不再需要 Pixiv**) | ⏸ 等上游/待定(若确认不用 Pixiv 即可关闭本项) | Nacos 控制台见 `docs/operations/nacos-config-center.md` | -| **B-062** | `AutocompleteDAO.search_cps()` 恒返回 `[]`(`src/apps/autocomplete/dao.py:78`)——CP 自动补全端点 `POST /autocomplete/search` 的 CP 分类**永远为空**。角色/音乐走 `candidate_character`/`candidate_music` 表 ILIKE 已实现,CP 无现成候选表,需从已提交的 `cp.cp_list` JSON 抽唯一 CP 名做模糊匹配(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,代码侧已复核仍成立**) | 低(功能缺口,非阻塞) | 🟢 可立即做 | `src/apps/autocomplete/dao.py:77-78`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §六 | -| **B-063** | `apps/scraper` 模块**无任何测试**(`tests/` 下无 scraper 相关用例)——外部 HTTP 依赖需 mock。与 B-010(覆盖率门禁切 `fail_under=80`)同域:scraper 是当前最大的未覆盖面(**2026-08-31 文档整理时从 `REFACTOR_TODO.md` 迁入,已复核仍成立**) | 低 | 🟢 可立即做 | `src/apps/scraper/`;原始记录见 [archive/2026-05-30-refactor-todo](./archive/2026-05-30-refactor-todo.md) §十 | +以下不是“当前代码完全没实现”。历史部署/人工验证记录保留在原主题文档,本次不重复执行,也不把未核验推断成仍有故障。 ---- - -## ⏸ 等外部 / 上游(2026-08-13 用户确认:只能等,我方不排期) - -- **B-028** prod 部署通道——等上游拍板部署形态 -- **B-054** 真实问卷录入 + code 回填——等出题方定稿(性别票/问卷统计出真实数字的唯一阻塞) -- **B-042②** Pixiv 凭据——等上游;且**可能不再需要 Pixiv**,若确认不用即可关闭 -- **B-043 尾项** 切公家验证码账户——等上游(海外网络加载实测可自行随时做) - -## 🎨 前端队列(Touhou-Vote 仓,我方负责,2026-08-13 确认) - -按依赖顺序: - -1. **提交侧切 candidateId**(B-057④)——✅ **前端已上线并端到端验证** (2026-08-14):测试机前端已全打 `/v12-be/`、vote-objects 返回 candidateId,投 candidateId 13/22/21→compute vote_year=12→queryCharacterRanking 正确归票(雾雨魔理沙/明罗/Flower战车),B-050-后补6 真实验证通过。剩:与 zfq 收口分支(功能修复在 zfq_dev_fe,dev 落后) -2. **B-039** questionnaireV2 改拉后端结构(一次性切换) -3. **B-040** 角色/音乐/CP 投票对象改拉后端 `/vote-objects/*` -4. **B-041** 问卷前端消费数组契约 -5. **B-037** 安全块前端(提名校验交互) -6. 核对 **B-045**(`f59585a`)/**B-046**(`4b89a23`) 两个前端 commit 是否已推已部署 -7. **B-055** 已知缺口(connect 占位页、Doujin 硬编码 1272、`/test` 调试路由) - -## 🟢 后端可立即做(7 项) - -按建议优先级排序: - -| 编号 | 一句话 | 估时 | +| 编号 | 已有内容/历史记录 | 尚待核验或决定 | |---|---|---| -| **B-059** | Nacos 不可达时 fail-fast(08-13 事故教训,取代静默回退 localhost DB) | 半天 | -| **B-026** | DB 治理纪律:PR 模板 + CI `alembic check`(防 B-051 类漂移复发) | 半天 | -| **B-057①③** | `GET /admin/voteables` 补实现;上届 final_ranking(year=11) 导入 | 各半天 | -| **B-020** | mypy 接入 CI(现状:lint job 只 pip install 了 mypy 但从未运行),先清告警再当门禁 | 半天-1 天 | -| **B-058** | admin-ui 构建链 9 个 npm 告警:`pnpm update` + 重建 dist | 1 小时 | -| **B-031** | Nacos 配置约束为标准 JSON 后删除 `_parse_config_content` 容错分支 | 1 小时(视上游配置是否能改) | +| **B-042** | 历史测试环境配置硬化及 Pixiv 凭据事项 | 当前凭据与 Pixiv 是否仍需要均未核验;不得据旧快照补造配置或要求新功能 | +| **B-043** | 人机验证与发码限流已有实现和历史验收记录 | 公用账号切换、海外网络体验等运营事项本次未核验 | +| **B-044 / B-045 / B-046** | 历史 IP/设备、提交耗时、clientEnv 采集已有记录;提交态前端角色/音乐/CP/提名已传耗时和环境字段 | 当前部署与真实落库未核验;问卷 V2 的提交签名不含相同字段,不宣称所有提交入口一致。后续指纹/聚类是独立需求 | +| **B-048** | Origin 校验已有代码;历史记录默认关闭。前端 codegen 仍使用测试机端口地址 | 开关、端口和当前部署状态未核验;收口之前须核对实际调用,不直接修改配置或网络 | +| **B-054** | 问卷语义 code 与统计管道已有历史实现记录 | 当前题库内容、code 与统计值未查库;删除“线上仍是占位、统计恒为0”的现状断言。内容由出题方确认,不执行导入或重新计票 | +| **B-058** | 2026-08-13 的 admin-ui 依赖告警是历史快照 | 未重跑在线告警/依赖审计,旧“9个、3高6中”不能当当前结果,也不据此自动升级依赖 | -## 🟡 需要判断 / 等条件成熟 +## 按需优化、兼容及待确认需求 -- **B-010** 覆盖率门禁切 `fail_under=80`(依赖模块运行 1-2 sprint 稳定后再切) -- **B-013** 邮件/短信发送幂等性(低优先级,发送链路已稳定后做) -- **B-019** 错误响应 `{"detail"}` → 与 Rust `{"error","service"}` 统一(等前端反馈是否需要) -- **B-033** 删除 legacy-compat 路由层(移除条件:Rust gateway 下线 + 前端迁 `/api/v1` 新 shape;与 B-019 同属契约收敛,详见 `docs/migration/legacy-rest-compat.md`) -- **B-050-后补2/3 + B-053** 记票深水区(trend 需 append-only 存储改造;上届对比依赖 B-057③ 数据;交叉分析共用"子集重算"原语)——适合打包出一份设计稿再动手。**2026-08-14 结果统计三方审计确认**:这几项正是结果站前端已具备入口、后端仍是桩的缺口——`characterCompare` 有往届对比页、`QuestionnaireDetail` 拿问卷趋势,后端一实现即点亮;`/res-be` 通路已通、result 站可联调。详见 [result-stats-audit-2026-08-14](./migration/result-stats-audit-2026-08-14.md)。(后补5 高级搜索已于 2026-08-14 完成,见 [BACKLOG-archive.md](./BACKLOG-archive.md),不再属于此"仍是桩"分组。) -- **前端 result 可维护性债(Touhou-Vote 仓,B-055 归口)** 审计新发现:`voteYear:11`+`voteStart` 硬编码散落 20+ 处未走 `lib/voteYear.ts`;characterEvolution.vue 过期日期文案;`/test` 调试路由在生产路由表;Doujin 页总票数等全硬编码(每届手改代码)。见审计文档 §三E/§C -- **B-049 尾项** admin-ui legacy 面板视觉验收后删除;无 UI 端点可选补 -- **B-047** IP→ASN 机房归属取证(可独立,属反作弊 Phase 2) -- **B-056** 迁移命名约定与 zfq 沟通(顺带同步:下一个迁移编号 **0018**、down=0017) -- ~~**B-066** 全站权限扫描后的两处加固~~ ✅ **已完成**(2026-09-13,`fix/scraper-ratelimit-email-code-attempts`):`POST /scraper/scrape` per-IP 10/min;邮箱验证码错 5 次作废。扫描的其余结论收进 `docs/operations/production-readiness-checklist.md`(P-1 关文档/GraphiQL、P-2 admin IP 白名单为**上线硬性项**;S-1 SSO `state`/`sid` 在接 SSO 前必须修) -- ~~**B-065** REST 提交/回读接口的 vote_id 越权~~ ✅ **已完成**(2026-09-13,`fix/rest-readback-token-auth`):6 个 `get-*`/`voting-status` 改按 `vote_token` 回读;5 个提交端点把 `meta.vote_id` 强制绑定为 token 的 user_id。契约见 `docs/api/voteable-api-contract.md` §3.2–3.4,细节见 CHANGELOG 2026-09-13 -- ~~**B-060** 高级搜索 per-IP 限流细化 + 两条终审小尾巴~~ ✅ **已完成**(2026-08-22,`feat/b060-b057`):`ClientIPMiddleware`(ContextVar) + 双层预算(per-IP 10/min + 全局 30/min) + 扣费后置到真正执行重算处(小尾巴①注释失实随之消除)+ 等锁改跟随锁存活轮询(上限 60s,锁消失提前接手;真机实测重算 ~8s,原固定 5s 会让等锁者集体重复计算)+ 3 个新测试真实覆盖等锁分支(小尾巴②销账:sleep 让出事件循环即可在 fakeredis 下触发 waiter 路径) +这些条目不等同于产品故障;没有具体场景或明确要求时,不自动变为本分支必做事项。 -## 🟢 模块功能缺口(不在 B 编号体系内) - -- **autocomplete CP 搜索**:`src/apps/autocomplete/dao.py` 的 `search_cps()` 仍 `return []`(角色/音乐已实现);需从已提交 `cp.cp_list` JSON 提取唯一 CP 名 -- **`GET /server-time` 端点**:旧 gateway 有,Python 侧未移植(低优先级) -- **scraper 测试**:18 站点全部移植但无测试(外部 HTTP 依赖,需 mock) -- **monitor invalidate 过时文案**:`_B050_NOTE`(`src/apps/admin/monitor/router.py`)作废投票时返回"影响排名需 B-050 计票重写落地后生效"——2026-08-14 实测作废后 compute 排名确实变化(chars 3→0),B-050 v1 早落地,此文案已过时误导,应更新(一行改动) - ---- - -## 推荐的下一步 - -- **前端(我方)**:candidateId 切换打头——同时解锁 B-057④ 与计票全链路真实数据,是当前唯一不受外部阻塞的高价值主线。 -- **后端穿插**:`B-059 + B-026` 打包一个"配置/DB 韧性"小 PR(都是 08-13 事故与 B-051 的直接教训);暖手 `B-058`(1 小时)。 -- **等外部的四项**不排期,条件一到再捡。 - ---- - -## 维护规则 - -- **新发现 follow-up:** 写进对应主题的源文档;在本表加一行;编号顺延 B-028, B-029... -- **某项完成:** 先把"严重度"改为 ✅ 已完成 + 完成日期 + commit hash / PR #;再把整行**移入 [BACKLOG-archive.md](./BACKLOG-archive.md)**(原文保留),保持本表只有活项 -- **三个状态分组**(🟢🟡🔴)随完成情况调整:依赖项落地后,相关项可以从 🔴 升到 🟡 或 🟢 -- 本表过 50 项时考虑分类拆文件(按主题:security backlog / schema backlog / test backlog 等),但目前规模够小不必拆 +| 编号 | 当前判断 | 下一步条件 | +|---|---|---| +| **B-010** | `fail_under=80` 是旧质量门禁建议 | 按实际风险决定阈值,不因旧数字自动扩充测试或 CI | +| **B-013** | 发码幂等性是历史边角情况建议 | 先看重复提交的实际影响和频率,未经确认不增加队列/状态机制 | +| **B-019** | Python 与 Rust 的错误 shape 有差异 | 只有具体调用方不兼容才构成修复需求;不为形式一致重做契约 | +| **B-020** | CI 安装 mypy 但未执行;flake8 已是 88 字符硬门禁 | 删除“去掉 mypy/flake8 的 `\|\| true`”旧描述。是否加入类型检查门禁另行决定;本轮未评估 mypy 告警 | +| **B-026** | CI 已在真实 Postgres 应用迁移;未增加 PR model 差异/alembic check 机制 | 更细治理检查仍是建议,新增 CI 工作需按项目规模单独确认 | +| **B-031** | 现有 Nacos 解析器支持 JSON、JS 风格兼容及 Properties | 当前配置写法未核验,不能直接删兼容分支;是否统一格式先由配置维护方决定 | +| **B-033** | legacy token-status 仍由前端 `${API_PREFIX}/user-token-status` 使用 | 兼容层仍有调用方,不能因“legacy”字样直接删除;[兼容说明](migration/legacy-rest-compat.md)记录退出条件 | +| **B-047** | IP→ASN/机房归属是用户明确保留的后续取证方向 | 保持待办,实施前确认数据源、成本及使用场景 | +| **B-049 尾项** | 管理端主体已有实现;历史还留 legacy 面板清理、可选钻取/合并/preview UI | 先核对实际入口及使用情况,再决定清理或补界面,不把“无UI”自动当缺陷 | +| **B-053** | 任意问卷题的 DSL 过滤与回答索引已存在;专用任意轴多分组输出 API/前端尚未提供 | 专用交叉展示是否需要是产品决定,不能再写成“通用问卷筛选全无” | +| **B-055** | connect 占位页此前已审计为无需求;result `/test` 已移除,统一年份和 timeline 日期已接入。Doujin 仍是示例数据,CP compare/evolution 不在现有页面范围 | 不自动补 connect 或 CP 页面;Doujin 是否数据化由运营需要决定,保留现状记录而非阻塞缺陷 | +| **B-056** | 历史哈希迁移保留;本地迁移图为单 head `0022` | 不重命名已执行迁移,不使用旧文档中的“下一编号0016/0018”;新增迁移前重新核对本地链与云端状态 | + +## 本轮已退出开放队列 + +B-028、B-039、B-040、B-041、B-050 主项、B-050-后补2、B-057、B-061、B-063 已移入 [归档](BACKLOG-archive.md),原始描述及本轮判定同时保留。 + +- 候选 ID、后端候选/资源、问卷数组契约已接入,不再安排“从零迁移”。 +- CP 静态作品分类依赖已由前端 `edeaeea` 清理;拼音搜索与唯一 `/autocomplete/search` 入口见后端 `77f43cf`、`44bd972`。 +- B-062 旧 CP 空实现已经随旧建议链路废弃;本轮删除“模块功能缺口”中的重复记录,不将 CP 组合推荐认定为应补功能。 +- scraper 的“无测试”重复记录删除;趋势、DSL、数据库白名单及 attempt 列不再重复列为未实现。 +- B-060/B-065/B-066 的历史完成项已有归档记录,不在活跃清单再次展开。 + +## 后续维护 + +1. 新条目先写清复现/实际使用场景、源码证据及对应需求,区分缺陷、运营事项与可选建议。 +2. 状态变更同步对应主题文档的当前状态;历史正文和旧 checkbox 保留为过程记录,不能据其重新执行迁移、导入或部署。 +3. 结项保留编号与证据后移入归档;接口缺失或界面占位本身不构成需求授权。 +4. 本轮不修改产品代码、测试策略、工作流或真实数据;后续事项按具体需求单独推进。 diff --git a/docs/CHANGELOG-archive-2026Q3.md b/docs/CHANGELOG-archive-2026Q3.md new file mode 100644 index 00000000..5ef233a5 --- /dev/null +++ b/docs/CHANGELOG-archive-2026Q3.md @@ -0,0 +1,753 @@ +# CHANGELOG 归档:2026 年第三季度 + +> 2026-11-08 从主 CHANGELOG 按完整条目迁出,保留历史正文及日期,仅修正已归档文档的链接。这里不代表当前部署、数据或需求状态。 +> 最近变更见 [CHANGELOG](CHANGELOG.md),仍开放事项见 [BACKLOG](BACKLOG.md)。 + +## [2026-09-17] 公共读接口 Redis 缓存 + 管理台手动刷缓存 + +> `vote-objects`/问卷结构/自动补全/公开提名列表此前每次直查数据库;项目 Redis 一直存在 +> 却只用于限流/会话/计票锁。本次接入缓存(写入即失效 + TTL 兜底),并给管理台加刷缓存入口。 + +### Added +- **`src/common/cache.py`**:JSON/原始文本读写 + `invalidate_prefix`(**SCAN 游标**删除,替代 `KEYS`);全部 fail-open(Redis 故障不影响请求)。 +- **vote-objects 缓存**(`src/apps/vote_objects/router.py`):列表 `vote_objects:{year}:{category}`、详情 `vote_objects:detail:{category}:{id}`,TTL 600s;命中直接返回缓存字节,`GZipMiddleware` 仍压缩。 +- **问卷结构缓存**:`questionnaire:structure:{year}`,TTL 1800s。 +- **自动补全缓存**:`autocomplete:{year}:{limit}:{q}`,TTL 60s。 +- **公开提名列表缓存**:`nominations:approved:{page}:{size}`,TTL 60s。 +- **管理端刷缓存**(`src/apps/admin/router.py`):`GET /admin/cache/stats`(各 scope 键数)、`POST /admin/cache/flush`(scope 白名单 `all|vote_objects|questionnaire|autocomplete|nominations`,未知 → 422)。管理台 Dashboard 新增「缓存」卡片(计数 + 单项/一键刷新)。 + +### Changed +- 失效逻辑补齐:`_clear_vote_objects_cache` 改为 SCAN 并同时清 `autocomplete:`;候选导入/改/删/合并/拆分、提名 approve/reject、问卷 admin 全部 13 个写端点都接上对应前缀失效(此前候选变更根本不失效)。 + +### 兼容性 +- 无接口 shape 变化(vote-objects 响应不变,只是更快)。 +- 明确**不缓存**带 `vote_token`/用户身份的读接口与所有写端点。 +- `result:*` 仍是计票产物,由 `POST /admin/compute-results` 重建,不纳入手动刷缓存。 + +### Tests +- 新增 `tests/unit/test_cache.py`(往返/前缀失效/fail-open)。 +- `test_vote_objects.py` 增缓存写入断言;`test_admin_voteables.py` 增 stats/flush/scope 校验/鉴权。 +- 全量 `666 passed, 4 skipped`。 + +## [2026-09-16] 投票对象资源 URL 后端化(0019) + +> 角色立绘 / 曲目封面 / 试听 URL 原存在前端 `packages/shared/data/{character,music}.ts`, +> 由前端**按 `name`** 匹配挂到后端候选上,管理台无法配置、改名即失效。本次迁到后端 +> 与 voteable 1:1 绑定,公共接口下发,管理台可编辑,前端静态表与匹配逻辑整体删除。 + +### Added +- **迁移 `0019_voteable_resources`**(`alembic/versions/0019_voteable_resources.py`):`voteable_character.image_url`、`voteable_music.image_url`、`voteable_music.music_url`、`voteable_music.include`(JSON,默认 `[]`)。Postgres-only 幂等;`aliases` 列已存在仅回填。 +- **公共接口下发资源**(`src/apps/vote_objects/dao.py`):`GET /api/v1/vote-objects/{characters|music}` 与 `/{category}/{id}` 的 item 新增 `imageUrl`、`aliases`(音乐另加 `musicUrl`、`include`)。 +- **管理端资源配置**:`GET /admin/voteables` 补资源字段;新增 `PUT /admin/voteables/{id}/resources`(部分更新、空串清空、URL 仅 http(s) 且 ≤2048、写后清缓存)。复用路由级 `require_admin`。 +- **迁移工具**:`scripts/voteable_resources.json`(一次性数据工件,含来源 commit)+ `scripts/import_voteable_resources.py`(按 name 导入,默认 dry-run/只填空值,`--apply --yes` 写入,`--overwrite` 覆盖)。 +- 管理台新页「投票对象资源」(`admin-ui/src/views/VoteableResourcesView.vue` + `api/voteables.ts`),产物已重建提交到 `src/admin_ui/`。 +- 前端统一加载层 `packages/shared/api/voteObjects.ts`;结果页资源索引 `packages/result/src/lib/voteObjectResources.ts`。 + +### Changed +- 投票页 `voteObjectsDataSource` 不再按 name 匹配静态表,直接映射后端字段;sessionStorage 缓存加 5 分钟 TTL(后端资源可被管理台修改)。 +- class 定义抽到 `packages/shared/model/{character,music}.ts`。 + +### Removed +- 删除 `packages/shared/data/character.ts`、`music.ts`(Touhou-Vote 仓库)及按 name 取 URL 的老逻辑;连带清理死代码 `vote/common/lib/getNickName.ts`、`result/lib/getIDtoName.ts`、`result/pages/Test.vue`。 + +### Fixed(顺带) +- 修复 `admin-ui/src/views/WorksView.vue`:此前对不上现有 `useAsync`/`usePagination`/`DataTable` API,`vue-tsc` 直接失败,admin-ui 无法构建。 + +### Performance(同日后补:修复投票列表页变慢) +- **后端加 `GZipMiddleware`**(`src/main.py`):vote-objects JSON 实测角色 `100KB→23KB`、曲目 `255KB→32KB`(4~8×)。此前仅 vote 的 nginx 配了 gzip,result 的 `/res-be` 与 dev 代理都未压缩。 +- **前端投票页按类别懒加载**:`VoteCharacter.vue` 只调 `loadCharacterVoteObjects()`、`VoteMusic.vue` 只调 `loadMusicVoteObjects()`(原都调 `loadVoteObjects()` 一次拉两个列表)。角色列表页不再为曲目付 32KB + 一次 DB 查询。 +- **缓存改「先渲染、后台 revalidate」**:sessionStorage 命中即同步渲染并立即返回,TTL 只决定何时在后台刷新,不再阻塞页面。原来 5 分钟 TTL 会让已缓存的列表页重新等待网络(测试机 TTFB 0.3~1.3s),这是"变慢"的主因。 +- 量化:静态表删除使 JS 少 **371KB(min)/50KB(gzip)**;API 增 ~38KB(gzip)。首次加载净约 −12KB,命中缓存后不再有阻塞请求。 + +### 兼容性 +- 只增列/只增字段,旧前端与旧调用方不受影响;但**新前端强依赖新字段 → 必须后端先发布、再发布前端**。 +- 数据迁移为一次性人工步骤(测试库已执行:角色 image 164、aliases 175;曲目 image 605、music 612、include 231)。 +- 无 GraphQL schema 变更;`color`/`title` 不建列(源数据分别为全表常量和全空),前端用常量/空串。 + +## [2026-09-15] 修正音乐候选「我的女仆,我甜美的女仆」的错误数据 + +> 稀翁玉曲目 `My Maid, Sweet Maid` 在早期导入时被英文逗号拆坏,后端白名单快照和测试库里存成了 `name="My Maid"`、`name_jp=" Sweet Maid"`、旧 id `d60777dd`。前端 `packages/shared/data/music.ts` 早已改正(id `462e28a2`)。投票页按曲名把后端候选对到前端静态表取封面和试听音频,名字对不上,这首歌在投票页没有封面、也放不了。 + +### Fixed +- `src/apps/result/data/whitelist_music.json`:用 `scripts/extract_whitelist.mjs` 从前端重新提取,diff 只有这一条(id `d60777dd`→`462e28a2`,name/name_jp 改正),其余 611 条和 244 条角色不变。 +- 测试库 `voteable_music` id=417:`name` 改为 `我的女仆,我甜美的女仆`,`name_jp` 改为 `My Maid, Sweet Maid`(直接 SQL,带原值条件,`UPDATE 1`;admin 没有改 voteable 名称的接口)。改完用 `POST /api/v1/admin/compute-results?vote_year=12` 重跑了计票。 + +### 兼容性 +- 计票已改读 DB(`load_whitelist_db`),JSON 快照只是 `scripts/whitelist_to_import.py` 的导入数据源,id 变化不影响计票。`candidate_music` id=601、voteable id=417 不变,已有投票(按整数 candidateId 存)不受影响;`old_id` 全表为 NULL,未改。 +- 结果计算的 `historical` 目前固定为 `{}`,按名字查历史的路径没有数据,改名不断链。 +- 无接口 shape、schema、migration、配置变更。生产环境仍是老 Rust 服务,不涉及。 + +## [2026-09-13] B-066 全站权限扫描:scraper 限流 + 邮箱验证码错 5 次作废 + +> B-065 之后对登录/token 签发、admin、投票侧数据端点、中间件与配置做了一轮只读扫描(4 个并行审计 + 人工复核)。结论:没有第二个越权洞;本条目落地两处加固,其余结论收进新文档 `docs/operations/production-readiness-checklist.md`。 + +### Fixed +- **`POST /api/v1/scraper/scrape` 增加 per-IP 限流**(`src/apps/scraper/router.py`):10 次/60 秒,超出 `429 REQUEST_TOO_FREQUENT`。此前公开、无鉴权、无限流,任何人都能驱动服务器用自己的 Pixiv 凭据去刷第三方站点。出站目标本就被各站点正则锁死在固定域名,不是任意 SSRF。 +- **邮箱验证码错 5 次作废**(`src/common/verification/email_code.py`,新增 `MAX_WRONG_ATTEMPTS`、`email-verify-attempts-{email}` 计数键,TTL 与码同为 3600s):此前 6 位码有效 1 小时,唯一防线是登录接口 per-IP 5 次/分钟,多 IP 可撞。旧 Rust 也没有次数限制,属新增防线。发新码时计数清零;成功消费时一并删除。错误码保持 `INCORRECT_VERIFY_CODE`,客户端契约不变。短信码由阿里云 PNVS 校验,其自身有次数控制,不在本条范围。 + +### Added +- `docs/operations/production-readiness-checklist.md`:生产上线待办清单。硬性项:关 `/docs`/`/openapi.json`/GraphiQL(测试机实测公网 200)、`ADMIN_ALLOWED_IPS`+`TRUSTED_PROXY_IPS` 必配、`ADMIN_SECRET` 换强值、删测试登录旁路、CORS 收紧、前端截止时间改回。建议项含 SSO `state`/`sid` 未校验(当前路径不可达)等。 +- 测试:`tests/unit/test_email_code_service.py` +3 例(第 5 次错作废、第 4 次错后正确码仍可用、发新码清零);`tests/integration/test_scraper_rate_limit.py` +1 例(第 11 次 429)。 + +### 兼容性 +- 无接口 shape 变化、无 schema/migration/配置变更。scraper 限流阈值对正常填表用户(粘几个链接)不可感知。 +- 邮箱码连错 5 次后即使输对也报 `INCORRECT_VERIFY_CODE`,用户需重新发码(受 120s 发码守卫约束)。 + +## [2026-09-13] B-065 REST 提交/回读接口按 vote_token 绑定身份(安全修复) + +> 外部 review 指出 6 个 REST 回读接口零鉴权;复核后确认,且写入路径有同源问题。根因:Rust 里 `/v1/get-*`、`/v1/voting-status/` 是 `submit-handler` 的**内网**路由,gateway 从 token 解出 vote_id 再转发;Python 重写把它们原样挂到公网 `/api/v1`,测试机 nginx `/v12-be/` 兜底可直达。`vote_id` 即 user_id(uuid4),会出现在 vote_token 载荷、管理端与导出数据里,不算秘密。 + +### Fixed +- **回读接口不再接受裸 `vote_id`**(`src/apps/submit/router.py`):`POST /get-character/`、`/get-music/`、`/get-cp/`、`/get-paper/`、`/get-dojin/`、`/voting-status/` 改为从请求体 `vote_token` 解出 user_id 再查,只返回调用者自己的提交。缺 token → `401 VOTE_TOKEN_REQUIRED`,伪造/过期 → `401` + 校验错误码。与 GraphQL 桥接 `getSubmit*Vote` / `getVotingStatus` 和 legacy `/user-token-status` 语义对齐。 +- **提交接口的 `vote_id` 改为强制取 token 的 user_id**(新增 `_bind_submit_identity`):此前 5 个 `POST /character/` 等端点只校验 token,`meta.vote_id` 仍原样落库,任何持有效 token 的用户都能以他人 vote_id 写入或改票。现与 Rust gateway `generate_submit_metadata`、GraphQL 桥接 `_make_meta` 一致,客户端传值被覆盖。 +- `docs/api/voteable-api-contract.md` §3.3 原文写"需要 userToken 鉴权"但实现没有,文档与代码已同步;2026-05-13 提交完成度设计稿中"get-* 不需要鉴权"一句加勘正注。 + +### Added +- `tests/integration/test_submit.py` 新增 15 例:6 路由 × 无 token 401、6 路由 × 伪造 token 401、跨用户 token 读不到他人提交、客户端伪造 `meta.vote_id` 不生效。 + +### 兼容性 +- **REST 回读请求体变更**:`{"vote_id"}` → `{"vote_token"}`。仓内排查:前端 Touhou-Vote、admin-ui 均不调用这 6 个 REST 接口(前端回读走 GraphQL),唯一调用方是本仓集成测试,已随改。`QuerySubmitRequest.vote_id` 暂留为可选并忽略,让旧请求得到 `401` 而非 `422`;**移除条件**:确认无调用方再发 `vote_id`。 +- 提交接口请求体 shape 不变;行为变化仅"客户端 `meta.vote_id` 不再生效",正常客户端本就不该传(Rust 时代前端从不控制该字段)。 +- 无 schema / migration / 配置变更;GraphQL 契约不变。 + +## [2026-09-12] #29 归一化的登录链路复核:六处修复 + 迁移回填前置检查 + +> 对 #29(`user` + `user_identity` 归一化)做的独立复核。七条候选问题逐条在真环境验证:六条确认并修复,一条确认为潜伏(加护栏)。 + +### Fixed +- **验证码登录不再漏掉「提升为已验证」**(`identity_service.touch_login(proven=True)` / `bind()` 已绑分支)。`_new_identity` 只在创建时写 `verified=True`,`src/` 里**没有任何地方**事后赋值 `verified`;而迁移 0018 是从 legacy `email_verified`/`phone_verified` 回填的,可能为 `false`。这类账号能正常登录,但 `_maybe_sign_vote_token` 里的 `identity.verified` 永远为假 → **静默拿不到 vote_token、投不了票,且任何地方都不报错**。#29 之前的实现有 `if not user.email_verified: user.email_verified = True`,归一化时丢了。 +- **密码登录不再在校验口令前泄露封禁状态**(`service.login_with_email_password` 改用新增的 `IdentityService.find_owner`)。`resolve()` 对封禁账号抛 `USER_REMOVED`/403,且跑在 `verify_password` 之前,未认证调用方因此能区分「该邮箱属于封禁账号」与「查无此邮箱」。改为先验口令,口令正确才告知 `USER_REMOVED`。 +- **登录顺带的 SSO 合并不再顶掉已有绑定**(`_merge_sso_session`)。它调的 `bind()` 语义是**替换**,被顶掉的 openid 随之释放、可被他人认领,且该路径此前**完全没有审计记录**(`_rebind_contact` 是有的)。现在已有绑定且 subject 不同则跳过并告警,真正新增绑定时补写 `bind_sso` 审计。换绑仍走 `update_*` / `bind_sso` 显式入口。> 注:设计稿 §一 已载明该路径在生产链路上暂不可达(GraphQL 桥接不传 redis/sid),属防御性修复。 +- **`VOTE_ELIGIBLE_PROVIDERS` 写错不再让进程起不来**(`config.Settings`)。`nacos.py` 把配置原样塞进 `os.environ`(全是字符串),pydantic-settings 对 `list[str]` 默认按 JSON 解析,写成 `phone` 或 `email,phone`(旁边字符串型键就长这样)会在 **source 层**抛 `SettingsError`——比字段校验器更早,所以 `mode="before"` 的校验器拦不住。改用 `Annotated[list[str], NoDecode]` 关掉预解析 + 校验器宽容解析(JSON 数组/逗号分隔/单个名字),看着像 JSON 却解不出数组时记错误日志并回默认值。 +- **Argon2 rehash 显式落库**(`login_with_email_password`)。此前只靠 `touch_login` 顺手 `save()`,而它在 `user.identity(provider) is None` 时会提前 return——今天不可达,但让一次写入依赖无关方法的内部实现是隐患。 + +### Added +- `alembic/versions/0018_user_identity.py`:`_assert_no_backfill_collisions()`,在**建表之前**拒绝会撞 `uq_user_identity_provider_subject` 的回填。旧 partial unique index 建在原始列上且大小写敏感,`Foo@Example.com` 与 `foo@example.com` 可合法共存,回填的 `lower(trim(...))` 会让两者塌成同一 subject(`trim(phone_number)` 同理)。真 PG 16 复现:原实现跑到一半抛 `UniqueViolation` 整体回滚;现在开工前报错并点名冲突账号,`alembic_version` 不动、`user_identity` 不建、`user` 列不删。 +- 回归测试 `tests/integration/test_identity_login_regressions.py`(6 例)与 `tests/unit/test_vote_eligible_providers_config.py`(7 例)。前者含两个对照用例(口令正确时正常报封禁、空位时正常补绑),确保修复不是「把功能关掉」。 + +### 兼容性 +- **无破坏性**:无 schema / migration 版本变化(0018 仍是 0018)、无 GraphQL 契约变化、无需数据迁移或配置变更。 +- ⚠️ 0018 的**回填范围**有变(B-064)。现有环境不受影响:测试机的 0018 已在近乎空库上跑完,新环境是空 `user` 表上跑 0018(回填为空操作),且设计稿 §9 已定「上线即空库」、`COLLECTION_CONFIG` 里没有 user 映射 —— 不存在 legacy 用户导入通道。改动只在「拿 0018 之前的存量库重放迁移」时生效,那正是它要修的场景。 +- 行为变化仅三处,都是修正:① 回填出的未验证身份在验证码登录后变为已验证(此前永久投不了票);② 封禁账号 + 错误口令改报 `INCORRECT_PASSWORD`(此前报 `USER_REMOVED`);③ 登录路径不再改绑已有 SSO 身份。 +- `VOTE_ELIGIBLE_PROVIDERS` 现在多接受两种写法,原 JSON 数组写法不受影响。 + +### Fixed(续)— B-064:0018 回填不再把「管理员封禁」当成「自助注销」 +- 原回填用 `WHERE removed = FALSE` 一刀切,把 `ban_user` 封禁的账号也排除了。而 `IdentityService.resolve` 正是靠身份行对封禁 subject 抛 `USER_REMOVED` 来阻止对方拿同一邮箱/手机改头换面重新注册 —— 没有身份行,**封禁形同虚设,解封出来的账号又没有任何登录方式**。真 PG 已复现:封禁账号回填得 0 条 identity。 +- **这不是「GDPR 抹除」与「封禁可执行」的二选一**——复核时查实两者可区分(此前误判为不可区分):旧 `remove_voter` 在同一次提交里把 `email` / `phone_number` / `password_hash` **全部置空**,而 `ban_user`(`UserDAO.set_removed`)一个都不动;旧 CHECK `at_least_one_identifier` 又保证活跃账号必有 email 或 phone,封禁前是活跃的,故必有其一。 +- 回填范围改用 `_BACKFILL_SCOPE = (removed = FALSE OR email IS NOT NULL OR phone_number IS NOT NULL)`,前置检查复用同一条件(否则查不到新纳入的封禁账号之间的冲突)。两个目标同时成立:封禁账号身份行完整回填;自助注销账号一条都不回填 —— **包括旧 `remove_voter` 漏清的 `qq_openid` / `thbwiki_uid`**(设计稿 §一.2 记的缺陷),不借回填把用户要求抹除的标识搬进新表。 +- 真 PG 16 上四种形态逐一验证:活跃账号 3 条身份;封禁账号 3 条(封禁可执行、解封可登录);只有手机号的封禁账号 1 条(判别式靠 phone 兜住);自助注销账号 0 条(含其残留的 qq_openid)。并复验前置检查在新范围下能拦住「活跃账号 vs 封禁账号」的大小写冲突。 + +## [2026-09-11] 回退 `UserDAO.save()` 的 `session.merge()`,改为显式拒绝 detached 实例(B-024 / U-18) + +> 承接 #30。#30 把 `save()` 改走 `session.merge()` 以「防 detached 静默 no-op」,但该前提不成立、且引入三条静默数据损坏路径,故回退并改为硬约束。 + +### Fixed +- `UserDAO.save()` 不再 `session.merge()`(`src/apps/user/dao.py`)。`merge()` 会按传入的陈旧副本重建 `User.identities`,而该关系是 `delete-orphan` —— **DB 里有、副本里没有的绑定会被 DELETE**。同一次盲写还会把 `removed` 覆盖回 `False`(**解封已封禁账号**)、把已硬删的行重新 INSERT(**复活账号**)。三者均已用探针在 sqlite 上复现。 +- `save()` 改为显式 `_reject_detached()`:非本 session 托管的实例直接抛 `InvalidRequestError` 并给出补救指引。此前 `refresh()` 也会抛同名异常,但属偶然行为;现在是写明的契约。 +- 更正 #30 的立论:`save()` 对 detached 实例**从未**静默 no-op —— 合入前的实现在 `refresh()` 处就抛 `InvalidRequestError`,调用方立刻知情。 + +### Changed +- 回归测试 `tests/integration/test_user_dao_save.py` 重写为 4 例:托管实例正常落库、detached 实例被拒、**不得删掉别处新建的绑定**、**不得解封或复活**。后三例在 `merge()` 版下会红(已验证),不是永远绿的测试。 +- `tests/integration/conftest.py` 按 B-023 本意收口为单行 `import fakeredis.aioredis`(必须带子模块名),删除 #30 留下的注释掉的旧代码、裸 `except:`(会吞 `BaseException`,且兜底换成的是**同步** FakeRedis,交给 `await` 会在无关模块炸 `TypeError`)与未被引用的 `FakeRedis` 死变量。 +- BACKLOG 复位:#30 把已归档的 **B-022 / B-024** 重新加回开放表(陈旧 rebase 产物),**B-023** 一度同时列在开放表与归档中。现统一以归档为准,开放表不再残留这三项。 + +### 兼容性 +- **无破坏性**:无 schema / migration / 配置 / GraphQL 契约变化,无需数据迁移。 +- 行为面:现网 5 个 `save()` 调用方(`identity_service.py:115,123,128`、`service.py:277,300`)全部持有同一 session 的托管实例,走的是正常路径,**行为不变**。只有传 detached 实例才会拿到报错,而这在合入前同样是报错。 + +## [2026-09-06] 用户身份模型归一化:`user` + `user_identity`(migration 0018,破坏性,无兼容期) + +> 设计:[user-identity-model-design](./superpowers/specs/2026-09-06-user-identity-model-design.md)。系统尚未公开上线,用户库允许重建。 + +### Changed +- **`user` 表只留账号属性**(id / nickname / pfp / password_hash / removed / register_*);邮箱、手机、QQ openid、THBWiki uid 各成一行进入新表 **`user_identity`**(`provider` / `subject` / `verified` / `verified_at` / `created_at` / `created_ip` / `created_device_id` / `last_login_at`)。唯一约束 `(provider, subject)` 与 `(user_id, provider)`,`provider` 有 CHECK。每条身份自带绑定时间、绑定 IP 与设备指纹,供反刷聚类使用。 +- **登录 / 改绑 / SSO 绑定 / 注销收敛为一条路径**:`src/apps/user/identity_service.py`(`resolve` / `register` / `bind` / `unbind_all`),provider 规则集中在 `src/apps/user/identity.py`。加一个认证来源只需加枚举值 + 放宽 CHECK。 +- **投票 token 资格可配置**:新配置项 `VOTE_ELIGIBLE_PROVIDERS`(JSON 数组,默认 `["email","phone"]`,与旧 Rust 规则一致)。是否收紧为仅手机号,上线前另行决定。 +- `remove_voter` 改为删除全部身份行 + 清密码;账号行留作 tombstone。 +- 管理端 `/admin/users` 的 `email` / `phone` / `email_verified` / `phone_verified` 改由身份行推导,**响应形状不变**;搜索改为 join 身份表。 +- `VoterFE` / GraphQL `LoginResult` **形状不变**:`thbwiki` = 是否绑定 THBWiki 身份。 + +### Fixed +- 注销后 QQ / THBWiki 身份不再被永久占用(此前 `remove_voter` 不清 SSO 列,且查找不过滤 `removed`,他人再绑报 `SSO_ID_ALREADY_BOUND`)。 +- 登录时合并 Redis SSO 会话撞到他人的 openid:此前 `IntegrityError` → 500 且 sid 已被消费;现记 warning 跳过,不阻断登录。 +- 被管理端封禁的邮箱/手机再登录:此前撞 partial unique index → 500;现返回 `USER_REMOVED`(403),且该标识不能被新账号注册。 + +### Removed +- legacy bcrypt+salt 密码路径(`legacy_salt` 列、`verify_legacy_password` / `verify_any_password`、`bcrypt` 依赖)。 +- 旧 Mongo `voters` 集合同步(`map_voter`、`COLLECTION_CONFIG` 项、`scripts/bson_to_sql.py` / `scripts/import_mongo_dump.py` 的 voters 注册)。其余集合同步不变。 +- `UserDAO.get_by_email` / `get_by_phone` / `find_by_thbwiki_uid` / `find_by_qq_openid`;`User.at_least_one_identifier` CHECK 与四个 partial unique index。 + +### 测试 +- 新增 `tests/helpers/users.py::make_user/build_user`;`tests/integration/test_identity_binding.py`(注册元数据、改绑替换、409、注销重注册、封禁、大小写归一、资格配置);`test_identity_pg_constraints.py`(PG-only,非 PG 自动 skip);`test_sso_flows.py` 重写。全量 614 passed(sqlite)。 + +### 兼容性 / 迁移 +- **需要数据迁移**:`alembic upgrade head`(0018:建表 → 从旧列回填 → 删旧列)。回填近似:每身份 `created_*` 取账号 `register_*`;`removed=TRUE` 账号不回填身份。**无兼容期**;`downgrade` 反向回填可回滚。 +- **配置**:可选新增 Nacos key `VOTE_ELIGIBLE_PROVIDERS`;不配即默认。 +- **对外接口形状无变化**(REST `VoterFE`、GraphQL、admin 用户列表)。新增错误码 `USER_REMOVED`(403)。 +- 关闭 BACKLOG B-008(废弃)、B-011、B-022、B-024。 + +## [2026-08-31] 文档树大扫除:归档过程产物、重建索引、整理 CHANGELOG(docs,无代码变更) + +> 文档累积到 131 份约 1.75 MB,过程产物占七成;索引停更在 2026-06-08,07–08 月新增的约 25 份文档从未进索引; +> 多份设计稿的 `状态` 行已与事实不符。本次只动文档,**不涉及任何代码、接口、schema、配置或部署**。 + +### Changed +- **30 份过程产物迁入 `docs/archive/superpowers/`**:25 份已执行完/已废弃的 plans、4 份已废弃或属事后记录的 specs、1 份一次性 handoff。每份头部插入归档状态块(状态 + 证据 + 落地去向 + 「不代表当前实现」)。判定依据是 BACKLOG / BACKLOG-archive / CHANGELOG 三者交叉核对**加代码复核**——plans 里的 `- [ ]` checkbox 从未被维护(B-057⑤),不可作为完成度依据。 +- **36 份现役设计稿统一补 `状态` 块**(已实施 14 / 部分实施 15 / 已实施(部分被取代)6 / 待实施 1)。其中**修正 7 份与事实不符的旧状态行**,例如:`2026-08-14-advanced-search-dsl-design` 仍写「待实施」而功能当天即上线;`2026-07-21-work-table-unified-design` 仍称 `GET /admin/voteables` 未实现而该缺口已于 2026-08-22 由 B-057① 补齐;`2026-07-23-tally-db-truth-source-design` 仍写「待实施」而 Phase 1 已随 #26 于 2026-08-13 上线。 +- **本文件**:合并 9 组重复条目(均为「孤儿标题紧跟真正条目」的合并残留)、按日期倒序重排(修正 2026-08-22 错位于 08-14 之前)、2026-07-01 之前的 15 条切至 `CHANGELOG-archive-2026H1.md`。**正文逐行比对确认零丢失**,条目数 59 → 50。 +- **`docs/README.md` 全量重写**:补齐此前缺失的约 25 份文档,设计稿按主题分组(用户认证 / GraphQL 契约 / 计票结果 / 候选项 / 安全 / 管理端 / 前端侧),并新增「归档」与「维护规则」两节。 + +### Added +- `docs/archive/README.md` —— 归档索引与**归档规则**(什么该归档、归档时必须做什么、判定状态时不要凭印象)。 +- `docs/CHANGELOG-archive-2026H1.md` —— 2026 上半年变更记录归档。 +- `docs/requirements/` —— VoileLabs 官方需求文档(投票系统 / 投票结果页面,md + docx 原件)从 `docs/` 根迁入。 +- BACKLOG **B-062**:`AutocompleteDAO.search_cps()` 恒返回 `[]`(`src/apps/autocomplete/dao.py:78`),CP 自动补全永远为空。 +- BACKLOG **B-063**:`apps/scraper` 模块无任何测试。 + > 两条均从 `REFACTOR_TODO.md` 迁出,**迁出前经代码复核确认仍成立**。 + +### Removed +- `REFACTOR_TODO.md`(子项目根目录,违反 CLAUDE.md §2,且内容已过期——其中 `vote_data ✅` 所指模块已于 2026-07-17 作为死代码删除)→ 归档至 `docs/archive/2026-05-30-refactor-todo.md`。 +- `.github/PR_DRAFT_user_and_verify.md`(2026-05-30 的 PR 草稿,对应 PR 早已合入 main)。 + +### 兼容性 / 迁移 +- **无兼容性影响**;**不需要数据迁移或配置变更**。 +- 过期文档一律**归档而非删除**,全文保留可查。 + +## [2026-08-29] append-only 提交历史 + 真实净增量 trend(B-050-后补2 Step 2,Task 4-8) + +### Changed +- 提交存储改为 append-only:`SubmitDAO._upsert` 覆盖的全部 `raw_*` 表(`raw_character`/`raw_music`/`raw_cp`/`raw_paper`/`raw_dojin`)与结构化问卷表 `paper_answer` 改票不再删除/覆盖旧行,`_upsert` 与 `questionnaire/dao.py::replace_answers` 均改为追加(`paper_answer` 新增可空 `attempt` 批次号列 + 索引,一次提交的所有行归入同一 `attempt`;`raw_*` 天然按行追加,无需批次号)。读方经 `latest_batch`/等价逻辑只取最新批次,行为与迁移前一致。 +- `queryQuestionnaireTrend` 及角色/音乐/CP 三类榜单的 `trend`/`trendFirst` 全部升级为**真实净增量序列**:新纯函数 `src/apps/result/trend.py::net_delta_trends` 取代 Step 1 的"最新提交分桶"近似——改票产生的旧选择在原分桶记负值、新选择记正值,不变量为每个实体全部分桶净增量之和 == 该实体最终 `vote_count`。`compute_all`(预计算主路径)与 `advanced_search/service.py::_compute_filtered`(DSL 子集重算路径)均已接入。 +- 前端契约无变化:`Trends(trend, trend_first)` 字段本就按净增量语义消费(`QuestionnaireDetail.vue` 等组件直接绘制为增量柱状图),无需前端跟进发版。 + +### Added +- 迁移 `0017`:`paper_answer` 新增可空 `attempt` 列 + 索引,**删除** 原 `uq_paper_answer_voter_group` UNIQUE 约束(`vote_id, vote_year, questionnaire_id, group_id`),改由 append-only 语义承接(`down_revision=0016`)。 +- `ComputeDAO` 新增历史加载器:`load_char_history`/`load_music_history`/`load_cp_history`/`load_questionnaire_history`,按时间序读取 append-only 提交历史供净增量计算消费。 +- `src/apps/result/trend.py::net_delta_trends`:纯函数,输入按时间排序的提交历史(含改票批次),输出真实净增量分桶序列;配套不变量测试(每实体分桶净增量之和 == 最终票数)。 + +### 兼容性 +- **需跑 `alembic upgrade head`(落地到 0017)**:`paper_answer` 表结构变化,未升级迁移则新版应用代码写入会失败(`attempt` 列不存在)。 +- **需重跑一次 `compute_all`**(或等定时任务下一轮):Redis 里的旧近似 trend 快照需要用净增量口径重新计算才会生效;重跑前行为保持 Step 1 的近似值,不报错。 +- admin 监控投票列表会开始出现**历史行**(同一选民多次改票会看到多条 `paper_answer`/`raw_*` 记录,而非过去覆盖后的单行)——作废(软删)历史行不影响计票(只读最新批次),作废最新行的效果仍等价于该选民出局,管理员操作口径不变。 +- **历史断点**:迁移上线前发生的改票历史已被旧覆盖式存储永久抹掉,无法回填;真实净增量曲线从上线时刻起才开始积累,上线当天已存在的单行选民数据会被当作一次性净增量处理(近似值),属于数据侧自然退化,不需要额外兼容代码。 +- **已知限制**:同一选民短时间内**并发**重复提交理论上可能落在同一个 `attempt` 批次号(`prev + 1` 的读-算-写非原子),导致两次提交的行被误合并为一批——旧版本的 UNIQUE 约束曾意外挡住这种情况,现实并发窗口极窄、概率很低;问卷侧若观察到异常,可在读方按 `created_at` 取最大值兜底识别真正的最新批次。 + +## [2026-08-29] 问卷趋势接通近似版(B-050-后补2 Step 1,Task 3) + +### Added +- `queryQuestionnaireTrend` GraphQL 字段接通真实数据:`_query_questionnaire_trend_entries` 不再固定返回空 `Trends` 列表,改为逐题读取 `compute_paper_results` 产出的 `"trend"`(近似口径:按每条问卷回答行 `created_at` 分桶,与 legacy Rust 网关口径一致,非真实净增量——问卷题允许改答案,`paper_answer` 同一 `vote_id`+`group_id` 只留最新一行);`trendFirst` 恒为空列表(问卷题没有"本命"概念,是本字段永久形状,不是退化);某道题从未算过时该条目仍退化为 `Trends(trend=[], trend_first=[])`,不中断其余题目。 +- DSL `query` 子集路径(`advanced_search/service.py::_compute_filtered`)同样接通 trend:筛选后的子集重算复用同一 `compute_paper_results(..., vote_start=, total_hours=)` 调用,子集 trend 与全集同口径。 +- 两个调用点补齐 `vote_start`/`total_hours` 透传:`compute_service.py::compute_all`(预计算主路径)与 `advanced_search/service.py::_compute_filtered`(筛选子集路径)。 +- 测试:`tests/integration/test_result_compat_rest.py` 新增/改写 `queryQuestionnaireTrend` 集成测试——不同小时 `created_at` 的问卷回答验证 trend 精确分桶、`trendFirst` 恒空;DSL `query` 子集路径同样返回非空 trend(子集 counts ≤ 全集)。 + +### 兼容性 +- **无 GraphQL schema 变化**:字段签名/返回类型不变,只是内容从恒空变成真实近似值——消费方(`QuestionnaireDetail.vue`)本就按 `[Trends!]!` 消费,无需跟进。 +- **需重跑 compute 才有数据**:本轮改动只影响 `compute_paper_results` 调用参数,不改数据模型;线上现有 Redis 缓存需重跑一次 `compute_all`(或等定时任务下一轮)才会写入非空 `trend`,重跑前该字段行为不变(仍是恒空)。 +- 真实净增量(Step 2)仍需 append-only 提交历史存储落地,属于同一 BACKLOG 项(B-050-后补2)的后续步骤,本轮不含。 + +## [2026-08-22] B-060 高级搜索限频/单飞加固 + B-057① admin voteables 端点 + +### Added +- **B-057①**:`GET /api/v1/admin/voteables`(category/q/分页,联 work 表出 `workId`/`workName`/`workType`)+ `POST /api/v1/admin/voteables/{id}`(编辑 work 归属,null 清空;不存在的 work→409),挂 `require_admin`,变更后清 vote-objects 缓存。5 个集成测试。admin-ui 消费页面可后补(B-049 无 UI 端点清单)。 +- **B-060**:`ClientIPMiddleware`(`src/common/middleware/client_ip.py`)把 B-044 可信代理解析的 client IP 放 ContextVar,供深层服务读取。 + +### Changed +- **B-060 高级搜索 miss 限频升级为双层**:per-IP `ADV_MISS_LIMIT_PER_IP_PER_MINUTE=10` + 全局 30/min 兜底;**扣费点后置到真正执行重算处**——缓存命中、等锁后从缓存拿到结果的赛跑者不再扣预算(消除终审小尾巴"注释与行为不符")。 +- **等锁策略**:由固定 5s(25×200ms)改为**跟随锁存活轮询**(200ms 间隔,上限 60s,锁消失提前接手)。依据:真机实测单次重算 ~8s(4 万行问卷载票),固定 5s 会让并发等锁者在最贵场景集体转入重复计算。 +- 新增 3 个测试真实覆盖等锁分支(等锁缓存命中零扣费/锁消失提前接手含耗时断言/per-IP 隔离)——终审小尾巴"锁竞争分支覆盖为空"销账。 + +### 兼容性 +- 无契约变化;`ADVANCED_SEARCH_BUSY` 语义不变,只是触发口径更精确(真重算才计数)。无 DB 迁移。 + +## [2026-08-14] 高级搜索/筛选 DSL 实现落地(B-050-后补5,Task 1-6 全部完成) + +### Added +- 新子包 `src/apps/result/advanced_search/`(`dsl.py`/`subset.py`/`service.py`):lark 文法解析器(`chars`/`musics`/`chars_first`/`musics_first`/`q=