报告发布 · 老师端（腾讯云 COS）

用途

把本地跑出来的 HTML 报告一键发布到腾讯云对象存储（COS），按日期归档、维护一个索引页（学员打开索引就能看到历史每天的报告），并直接给出可分享的访问链接。

配套技能：tdx-report-read（学员端，负责从 COS 读取报告）。

何时使用

• 报告生成完毕，需要上传到 COS 供他人查看。
• 需要每天发布一版，且历史版本不能被覆盖。
• 需要给学员/同事一个固定的入口页（索引），而不是每次发一个新链接。

前置条件

• Node.js 18+，已安装官方 SDK：npm install cos-nodejs-sdk-v5
  （若 SDK 装在别处，用 NODE_PATH 指向其 node_modules 目录）
• 腾讯云 API 密钥（SecretId / SecretKey）+ 存储桶名 + 地域。
• 建议用子账号密钥并只授予写入权限，详见 references/cos_setup.md。

环境变量

> 密钥只在创建时可见一次，务必妥善保存；不用时建议在控制台「禁用」。

用法

# 1) 环境自检（SDK / 凭证 / 桶是否通）
node scripts/verify_setup.js

# 2) 发布当前目录下的 HTML 报告（按今天归档 + 更新索引页）
#    注意：存储桶非「公有读」时必须加 --public，否则学员端匿名读取会 AccessDenied。
node scripts/publish_cos.js --dir <报告目录> --public

# 可选参数
--dir <dir>        报告所在目录，默认当前目录
--prefix <p>       对象前缀，默认 stock-reports/<今天>/
--include-csv      连 CSV 一起传（默认只传 HTML）
--no-index         不更新索引页（只传文件）
--public           对象显式设为公有读

# 3) 推荐做法：把当期报告拷进一个干净目录再发布
#    （脚本会扫描 --dir 下所有 .html 全量上传，不能让历史报告混进来）
node scripts/publish_cos.js --dir _publish --prefix stock-reports/2026-10-20/ --public

每日产物与学员端对应关系

> 两张总榜页由引擎同一个模板 render_pool(n, rows) 渲染，TOP50 / TOP80 自动生成，只改标题与统计口径。

工作流

1. 确认产物：在 --dir 目录里找 *.html（--include-csv 时再加 *.csv）。
2. 自检：跑 scripts/verify_setup.js，确认 SDK 已装、凭证有效、桶可达。失败就按提示修，不要盲目重试。
3. 上传：逐个 PutObject，Content-Type 按扩展名设置；HTML 报告设 Content-Disposition: inline（中文原名写进 filename*，仅作另存为建议名），浏览器点链接直接打开页面；CSV 才用 attachment。对象同时显式设 x-cos-acl: public-read。
4. 更新索引：读取桶里的 stock-reports/index.json，写入/覆盖当天条目，再生成 stock-reports/index.html（按日期倒序，列出每天的报告链接）。
5. 收敛（关键，不可省略）：运行 node scripts/converge_index_top50.js，把当天及所有历史日期的索引收敛为「仅 TOP50 一个文件」——它会删除云端多余的 v7 全量 / TOP80 对象，只保留学员要看的 TOP50。若跳过这步，学员端会看到 3 个文件卡片（v7/TOP50/TOP80）。脚本用环境变量 PUBLISH_SCRIPT 定位 publish_cos.js 的 renderIndex()（未设时 fallback 到技能文件夹绝对路径）；「今天」的条目禁止被自愈删除（只清历史孤儿），且用本地时区判日期。
6. 回报：打印每个对象的大小与访问链接，并给出索引页地址。

v1.0.2 修复（学员端「点链接看不到」）

• publish_cos.js 对 HTML 报告的 Content-Disposition 由 attachment 改为 inline：旧版学员点链接只会下载 .html 文件，手机/微信内置浏览器里经常打不开，表现成「报告看不到」。CSV 仍按 attachment 处理。
• converge_index_top50.js 重写 index.json / index.html 时补 x-cos-acl: public-read：与发布脚本 --public 同口径，避免收敛把索引改成私有、学员匿名读不到索引导致整份报告消失。
• 学员端 fetch_report.js 移除签名链接生成路径，对外一律匿名永久地址；references/read_setup.md 旧口径文档整体重写。
• 升级后需对此前已上传的报告对象重传一次才会生效（对象元数据不会自动变更）；之后每天自动发布即为新头。

v1.0.1 加固记录（与 daily_run.py --phase finalize 同口径）

• publish_cos.js --public 显式设置 x-cos-acl: public-read，不再依赖桶级公有读配置。
• --prune-older 的守卫正则修为 /(^|\/)\d{4}-\d{2}-\d{2}\/$/：旧版用 ^\d{4} 匹配，但因对象键前缀是 stock-reports/，守卫永不命中、清理静默失效。
• 本次有任一上传失败就跳过 --prune-older：保留昨天那份可用报告兜底，避免把云端唯一可访问的旧报告删掉。
• COS SDK 一律用 Promise 形式 await cos.xxx({...})；callback 形式会挂起。
• converge_index_top50.js 与项目根版本保持 MD5 一致：自愈只删历史孤儿、结尾对被 delete 的日期判空（旧版会抛 TypeError 且对象已物理删除）。

关键约定

• 默认只传 HTML 报告，不传 CSV 与原始数据；需要时用 --include-csv。
• 日期目录按本地日期生成，不会覆盖历史报告。同一天重复发布是覆盖更新，属正常行为。
• 对象键 URL 必须按段 encodeURIComponent（整段编码会把 / 变成 %2F，链接就废了）。
• 报告桶按公有读运行：索引页、报告对象、链接都对学员匿名可读，且报告为 inline 在线打开。学员端对外链接固定为匿名永久地址，不输出签名 URL；若真把桶改成私有，学员端链接会直接 403，需另行设计带鉴权的分发方式，不能只靠学员端签名读取。

常见问题