使用文档
本页内容改编自项目内的 使用说明.md 与 docs/*.md，
凡是本站无法从源文件确认的操作，一律标注「待补充」。
一、安装与启动
安装版（推荐）
- 双击
AISportsAnalytics-Setup-1.1.0.exe，按向导完成安装。安装器为当前用户安装到%LOCALAPPDATA%\Programs\AISportsAnalytics，不需要管理员权限。 - 安装完成后会创建桌面快捷方式、开始菜单入口和卸载项；勾选「立即启动」会直接打开系统。
- 升级安装不会覆盖已有
config.ini；卸载不会删除服务端data/数据库，便于重装后恢复。 - 若 Windows SmartScreen 提示未知发布者，先核对安装包 SHA-256 与交付清单一致，再选择「仍要运行」。 正式分发前建议对 EXE / 安装包做代码签名。
绿色版
- 将发布压缩包解压到本机可写目录，例如
D:\AISportsAnalytics\。 不要放在只读目录、网络共享盘或需要管理员权限才能写入的Program Files下。 - 确认
config.ini、AISportsServer\、AISportsClient\、启动系统.bat在同一层目录。 - 双击
启动系统.bat。首次启动会创建数据库、服务端密钥和日志，并打开桌面客户端。 - 服务端就绪后，脚本会打印管理后台地址：
http://127.0.0.1:8766/admin（启用 HTTPS 后为https://）。 - 重复双击启动脚本是安全的：已运行的服务端和客户端会被复用，不会重复启动。
启动脚本会打开一个服务端控制台窗口。该窗口是本地服务进程，正常使用期间不要关闭； 关闭它会导致客户端断开、分析内容冻结。需要停止系统时，关闭客户端后再关闭服务端控制台。
端口与修改端口
用户接口默认 8765，管理员后台使用独立回环端口 8766。
若用户端口被占用，需同时修改下列三处，然后重启服务端与客户端：
| 配置文件位置 | 键 | 默认值 |
|---|---|---|
| [server] | port | 8765 |
| [server] | trusted_origins | http://127.0.0.1:8765,… |
| [payment] | return_url | http://127.0.0.1:8765/pay/return |
| [client] | server_url | http://127.0.0.1:8765 |
二、首次启动与管理员初始化
- 在本机浏览器打开
http://127.0.0.1:8766/admin（启用 HTTPS 后为https://127.0.0.1:8766/admin）。 - 安装程序（或绿色包首次启动时的
start.ps1）会随机生成初始管理员密码，写入data\admin_initial_password.txt。使用账号admin和该文件中的密码登录； 不要使用任何固定默认口令。 - 首次登录会强制进入修改密码页面。新密码需满足页面提示的强度要求；修改成功后其他管理员会话会失效。
- 管理员密码不会在客户端出现，客户端也没有任何管理员入口。
- 管理员登录状态只保存在当前浏览器标签页的
sessionStorage，关闭标签页即清除。
如果忘记管理员密码，需要在停止服务端后由维护人员直接处理数据库 / 重新部署； 本项目不提供客户端找回入口。
管理后台里能做什么
- 总览：活跃会员、收入、在线会话、调度器状态、最近订单与审计
- 用户与会员：查询用户、查看订单/设备/心跳、手工增减会员、封禁/解封、撤销会员
- 订单与支付：全部订单、回执详情、状态
- 收款设置：上传/替换/删除收款码；查看待人工核账列表，确认或驳回凭证
- 数据源：新增/修改/测试/启用自定义 HTTP JSON API，或恢复内置 NowScore；token 不回显
- 审计日志：只追加、不可修改；可按动作/目标筛选
- 实时调度：节拍器指标、数据源健康、暂停/恢复实时调度
- 系统配置：价格、套餐天数、节拍、超时、公告、心跳间隔；保存后热更新并写入审计
- 品牌白标：显示名、窗口标题、主题色、图标与 Logo；只改显示，不改会员与权限
- 风控名单：黑名单/白名单（用户名、IP、设备），变更写入审计
三、账号与订阅
注册与登录
- 在客户端登录页选择「注册新账号」。
- 用户名和密码只提交给本机服务端；密码在服务端使用 scrypt 加盐哈希保存。
- 登录成功后，客户端会向服务端登记设备并取得设备凭据。设备凭据通过 Windows DPAPI 加密保存在当前 Windows 用户的本地目录，不写明文。
- 勾选「在此 Windows 账户下记住登录状态」后，下次启动可恢复会话；取消勾选则只在当前运行期间保留。
客户端每 60 秒发送一次心跳。心跳中断、实时通道断开、账号被封禁或会员到期时，分析内容会被冻结或锁定； 恢复网络 / 服务后会自动重新同步。冻结期间界面保留最后一次服务端下发的内容，但不会继续更新。
套餐与价格
周卡（basic）
赛事列表、实时比分、全部进行中赛事原始数据、基础分析（胜平负 / 大小球 / 双方进球）、 基础数据完整度与趋势摘要。
月卡（advanced）
含周卡全部权益，另加高级分析与多盘口矩阵、比分矩阵、亚洲让球、风险因子、 深度历史与整场回放、多维度面板与动量分析。
价格、套餐天数、节拍、采集/推理超时、心跳间隔均可通过服务端配置或管理后台调整，因此以上为 默认值；客户端不接收「自行计算的会员时长」，价格只展示服务端返回的套餐数据。 来源：README.md「会员与功能」末段
购买流程（默认：个人二维码 + 人工核账）
- 登录后进入「订阅」页面，选择周卡或月卡。
- 点击购买后，客户端向服务端创建订单，并打开应用内嵌收银台；不会跳转外部浏览器。
- 收银台显示管理员上传的支付宝/微信收款码。扫码付款后，填写渠道、交易单号
（4–64 位字母/数字/
-/_），可选填付款人/备注，点击「提交支付凭证」。 - 提交后订单进入「待人工确认」，会员不会立即到账。管理员需要在后台核对账单中的 金额、时间和交易单号，确认后服务端才写入会员。系统会明确显示 「付款后等待人工确认（通常 10 分钟内）」，不会假装自动到账。
- 若管理员驳回，订单会显示驳回原因，并重新获得 15 分钟提交窗口；可点击「重新提交」。
pending订单默认 15 分钟内有效；claimed（待确认）订单不会自动过期。 关闭待支付订单的收银台会被视为取消支付意图；已提交凭证的订单不会被客户端取消。
请务必在付款后如实填写交易单号。重复使用同一交易单号会被服务端拒绝； 伪造单号不会发放会员，管理员会以账单为准。
商户网关模式（可选）
若运营者改用 custom_webhook 商户网关，客户端会显示「等待支付渠道签名回调」，
服务端验签通过后自动开通；公网中继与商户资质由运营者自行接入。
沙箱模式（payment.provider = sandbox）仅用于功能验收，不能收取真实款项。
四、数据、备份与恢复
服务端数据（data\）
aisports.db（SQLite WAL，可能同时有-wal/-shm）server_secret.key、payment_secret.keyed25519_private.pem/ed25519_public.pembranding_public.pem/branding_local_private.pemadmin_initial_password.txt（改密后请删除）logs/server.log及轮转日志
备份时先正常停止服务端，再整体复制 data/。
不要在运行时只复制 aisports.db 而漏掉 -wal。
密钥文件必须与数据库一起备份——只恢复数据库而丢失密钥会导致支付回执验签、离线凭证失效。
客户端数据
路径：%LOCALAPPDATA%\AISportsAnalytics\client\，主要是 DPAPI 加密的
credentials.bin。该文件只能在同一个 Windows 用户下解密；
换用户或换机器后需要重新注册 / 登录。
日志轮转
服务端日志写入 data/logs/server.log，按 8 MB × 8 轮转；
所有请求错误返回统一结构：
{"detail": {"code": "error_code", "message": "面向用户的说明"}}
五、常见问题
下表逐条改编自 使用说明.md §8 的故障排查表。
双击后提示「未找到服务端程序」
确认 AISportsServer\AISportsServer.exe 与启动脚本在同一发布目录。
提示端口被占用
修改 config.ini 三处端口（见 第一节），重启服务端与客户端；或关闭占用端口的程序。
服务端 90 秒内未就绪
打开 data\logs\server.log 查看错误；检查数据目录是否可写、端口是否被占用、杀毒软件是否拦截。
管理后台打不开
必须用本机浏览器访问 http://127.0.0.1:8766/admin（HTTPS 时为 https://）；不要用局域网 IP 或外部域名。
客户端显示「本地服务未连接」
确认服务端窗口仍在运行；稍等客户端自动重试，或重新双击启动脚本。
登录提示账号或设备被限制
管理员后台检查黑名单 / 用户状态。
客户端显示「当前无有效会员」
会员未开通或已到期；购买后在订阅页刷新，等待心跳同步。
支付后会员未到账
二维码模式需管理员在后台核对账单并确认后才会发放；先在订单列表查看状态是「待人工确认」还是「凭证被驳回」。沙箱模式需在收银台点击模拟支付成功并等待服务端验签。超时订单需重新下单。
订单一直显示「待人工确认」
管理员尚未核账。请确认已提交正确交易单号；管理员可在后台「收款设置」看到待核账列表。claimed 订单不会自动过期。
凭证被驳回
查看驳回原因，点击「重新提交」，填写正确的渠道与交易单号；订单会获得新的 15 分钟提交窗口。
下单提示「支付不可用」
管理员尚未上传任何收款码。请管理员登录后台「收款设置」上传支付宝或微信收款码后再试。
分析内容一直冻结
检查顶部心跳与实时通道标签；心跳异常、SSE 断开或会员失效都会冻结。查看服务端日志和调度器页面。
统计显示「—」
表示该字段未从匿名页面观测到，而不是等于 0。捷报公开详情页提供射门、射正、控球、 危险进攻、进攻、射门不中、近 3/10 场均值、进失球概率、半场/全场统计与交锋； xG、犯规不在匿名页面，固定显示「—」。
收银台空白
该版本应内置 QtWebEngine。二维码收款必须使用内嵌收银台，若组件加载失败会明确提示而不是回退到沙箱；检查发布目录是否完整。
客户端启动报错
查看 %LOCALAPPDATA%\AISportsAnalytics\client\ 与发布目录的日志；必要时备份 credentials.bin 后重建。
本站再补三个文档里没直接写的
为什么 3 秒节拍不等于 3 秒刷新？
3 秒是派发节拍。默认 max_matches = 2000、采集并发 32，
一轮最坏约 188 秒；要 3 秒级刷新需降低 max_matches 或提高采集并发。
安装版能做自动训练吗？
不能。自动训练只在源码运行模式可用，它需要 scripts/train_daily.py 与
data/raw、data/clean 历史数据；安装包和绿色版均不包含这些。
安装版后台会提示从源码目录运行 python run_server.py。
能把服务端放到服务器上给多个人用吗？
默认不行：服务端面向单机本地部署，是单进程应用（SQLite + 进程内事件节拍），
默认只监听回环地址。局域网 / HTTPS 部署必须显式开启并校验来源 IP、Host、
Origin 与 TLS（见 docs/DEPLOY_REMOTE.md）。
它不是多机集群、主从复制或 K8s 高可用方案；单进程 + 本地 SQLite 不支持多实例同时写同一数据目录。
六、源项目文档索引
| 文件 | 内容 |
|---|---|
| 使用说明.md | 安装、启动、注册、购买、后台与故障排查 |
| docs/ARCHITECTURE.md | 服务端 / 客户端、事件节拍、数据流、数据库与并发模型 |
| docs/API.md | 签名、用户接口、管理员接口、SSE 与错误码 |
| docs/ACCURACY.md | 准确率与对外口径（由脚本从 metrics.json 生成） |
| docs/DATA_PROVIDER.md | NowScore 实时适配器、自定义 API、JSON 契约、字段映射与合规要求 |
| docs/SECURITY.md | 威胁模型、密钥、权限隔离、审计与加固 |
| docs/ANTI_TAMPER.md | 信任边界、已实现签名与服务端权益、明确未实现项 |
| docs/PAYMENT_INTEGRATION.md | 二维码人工核账、商户网关回调、沙箱流程 |
| docs/PRIVACY.md | 本机收集的数据、外发请求、日志脱敏 |
| docs/WHITE_LABEL.md | 白标签名配置与可热更新范围 |
| docs/DEPLOYMENT_CHECKLIST.md | 上线前检查、备份恢复、验收步骤 |
| docs/DEPLOY_REMOTE.md | 局域网 / HTTPS 远程部署 |
| docs/ROADMAP.md | 路线图与政策文档 |
| docs/MODEL_SELECTION.md | 模型选择纪律 |
| docs/LOAD_TEST.md | 压测说明（压测数字属于 1.0.0，1.1.0 未重跑） |
本页不提供源码编译指引与打包脚本说明的完整转载 ——
那部分见项目内 README.md「从源码运行」与「打包发布」两节。
本站待补充项
- 实际运营方的客服流程、退款政策 —— 待补充，项目文档里没有。
- 线上服务的真实会员数、收入数据 —— 待补充，项目里只有回测报告与本地验收记录。
- Windows 版本兼容性矩阵的实测清单 —— 文档只说 Windows 10/11 64 位，没有逐版本实测记录。