99 lines
23 KiB
Markdown
99 lines
23 KiB
Markdown
# 商务功能迁移执行记录
|
||
|
||
## 基线与方法
|
||
|
||
- 旧后端：`D:/Users/Yvan/projects/yzyz/sw`，`main`，`f9a5e3a90`。
|
||
- 框架基线：`d31082f4a7816d4c83544b8f54e6f42a3b2132b1`。
|
||
- 旧前端：`D:/Users/Yvan/projects/yzyz/sw/web`，`dev/dev1.0`，`ba284011c87fd3d5730e0e3dceffb14a7389730c`。
|
||
- 新实现分支：`codex/sw-business-migration`。
|
||
|
||
按基线至当前版本的最终差异提取功能，以当前 Java 实现、实际调用的前端接口和 SQL 为核对依据。提交记录用于解释修复和撤销，不逐提交搬运。旧前端中未接入的 mock、废弃接口不能作为已实现业务迁移。
|
||
|
||
沿用现有迁移 SQL 的 `/sw/` 路由与 `view/sw/` 菜单组件路径。认证、响应信封、权限、表格及图表采用 Kra；业务字段、统计口径、状态流转、可见范围保留旧实现。登录页、系统名称和品牌资源来自旧商务。新增代码注释与提交信息使用中文。
|
||
|
||
用户补充：允许直接优化旧接口、SQL 和逻辑。优化时记录行为差异并验证业务结果；各批实现必须实际请求 HTTP 接口，不能只以单元测试和构建作为完成依据。
|
||
|
||
2026-11-04 用户调整验证要求：后续不需要检查页面交互，只验证接口并继续迁移，包括工作台/仪表盘。后续保留旧页面源码核对、接口实测、数据断言和构建检查，不再执行 Chrome 交互验收。
|
||
|
||
用户再次指出页面偏差后，明确按旧前端实际页面核对入口，不能从后端接口推断 UI 功能。详见 `page-parity.md`。商务列表已移除错误增加的编辑入口，恢复“绑定列表”名称及仅三级显示规则，并对齐按审核状态显示行操作。
|
||
|
||
用户已有的 `configs/config.yaml` 修改与迁移 SQL 保留。未经最后阶段的数据库确认，不连接、复制或修改用户的旧数据库。
|
||
|
||
## 依赖顺序与完成标准
|
||
|
||
| 阶段 | 范围 | 状态 |
|
||
| --- | --- | --- |
|
||
| 1 | 商务用户字段、层级与角色、账号资料和审核、偏好、登录及找回密码 | 进行中 |
|
||
| 2 | 平台绑定、商务/渠道可见范围、外部平台与 OA 数据源、商务列表及抽屉 | 进行中；绑定、旗下渠道、商务/SDK 画像、OA 激活只读接口已接入；外部数据源及审核实库联调待完成 |
|
||
| 3 | 预警规则、记录与状态机、操作日志、附件、消息、任务注册与调度 | 进行中；规则、记录和工作流已接入；任务待迁移，消息盒子已确认属于未改动框架代码 |
|
||
| 4 | 渠道列表及新增、渠道激活、推广游戏等业务接口与页面 | 功能已接入；包含渠道画像，完整业务数据和源平台联调仍待最终验收 |
|
||
| 5 | 日汇总构建、充值/注册明细、渠道/游戏/区服报表、排行、画像与仪表盘 | 进行中；画像、注册/充值明细及导出、渠道/游戏/区服统计已接入，排行、仪表盘业务数据与任务待迁移 |
|
||
| 6 | 静态接口核对、后端测试、前端构建和页面验证 | 随阶段推进，最终全量复核 |
|
||
| 7 | 用户确认源数据库，复制至隔离库，执行迁移，启动并逐接口核对数据 | 未开始，必须等待用户确认 |
|
||
|
||
每项完成需覆盖 DTO → service → biz → data、路由目录、权限、菜单页面和有意义的行为测试。只有真实实现并通过验证的项才标为完成。整项目标在实库验证之前保持未完成。
|
||
|
||
## 已核实的业务约束
|
||
|
||
- 超管创建一级商务，一级创建二级，二级创建三级；三级不能创建下级。层级与祖先链由服务器生成。
|
||
- 新增子商务最终版本默认正常，不采用残留注释中的“默认待审核”。
|
||
- 一/二级商务列表只显示下级树，不显示自己；三级列表为空。报表使用独立渠道可见范围，不能套用 Kra 的部门过滤替代。
|
||
- `includeSubPromote` 与 `idcardDedup` 无记录或数据库值非零时均为开启，新增账号同时初始化开启。
|
||
- SDK 商务绑定数量仅计算已通过记录；渠道计数依照当前直属渠道算法，跨平台 ID 不能混用。
|
||
- 用户审核状态有正常、停用、驳回、待审核四种，须保留 `business_status`，不能压成 `enable` 后丢失含义。
|
||
- 金额查询固定不做身份证去重；人数查询遵守全局偏好。
|
||
- SQL 已建立用户、角色、文件等 ID 映射；平台实体及业务主键保留。迁移验收应按映射比较，不能直接比较所有原始 ID。
|
||
|
||
## 验证记录
|
||
|
||
- 已落地商务用户七个扩展字段的存取及增量补列；登录和既有会话同时检查商务审核状态。
|
||
- 已落地全局偏好 GET/PUT、当前用户隔离、缺省开启、显式关闭及幂等写入；Kra 顶栏增加统计口径入口。
|
||
- 已落地商务列表、查询资料、新增子商务、部分编辑和审核状态，以及 Kra 风格 `BusinessList` 页面。层级及角色由服务端按原角色 ID 映射分配；账号、角色、偏好在同一事务创建。列表按平台与商务组合键统计直属一级渠道和已通过绑定。
|
||
- 商务、SDK 商务和渠道画像已接入；其余报表及任务继续迁移。后端导出等接口另按源码核对，不能据此给旧页面增加不存在的按钮；最终仍需完整数据源验收。
|
||
- 已接入绑定列表、指定商务已通过绑定详情、提交绑定及解绑四个接口，页面恢复仅三级可见的“绑定列表”页签及只读详情抽屉。绑定流程保持三级限制、平台验密、OA 待审核及驳回重提规则；新增键锁表 `sys_business_binding_locks`，串行处理同一平台商务的并发绑定。
|
||
- 已恢复旧登录页的图片、文案、布局及记住账号功能，系统名称统一为“遨游龙翔游戏平台”。找回密码四个匿名接口位于 `/sw/auth/forgot-password/`，保留账号/手机号检查、60 秒发码限制、两分钟验证码、十分钟凭证、6–15 位密码及失败五次吊销等规则。
|
||
- 找回密码采用同库事务保存验证码摘要和一次性凭证，并原子执行改密/消费凭证；新增 `sys_business_password_codes`、`sys_business_password_resets`。更新密码版本使旧 JWT 失效。短信复用 Kra 集成配置，`SW_PASSWORD_RESET_SMS_PROVIDER` 默认 `tencent`，也支持 `aliyun`；模板和通道凭据在对应集成配置中维护。
|
||
- 旗下渠道接口 `/sw/business/:userId/promotes` 和两处抽屉入口已接入：先校验商务可见范围，再按已通过绑定的 `(source_db, platform_busier_id)` 查询直属一级渠道；按渠道 ID、平台稳定分页。实际 sw7 请求与隔离完整数据 HTTP/仓储测试均通过，浏览器确认绑定入口同时携带平台和平台商务 ID，未通过绑定禁用该入口。
|
||
- 平台数据源通过 Kra 的 `data.database_list` 复用连接，别名为 `lx` / `hw` / `yq`。旧密码算法支持三种格式，兼容盐通过环境变量 `SW_SDK_AUTH_CODE`、`SW_SDK_MIGRATE_AUTH_CODE` 提供，取值应与旧 `XiguPasswordUtils` 对应常量一致；`SW_SDK_TABLE_PREFIX` 缺省为 `sys_`。真实连接凭据和盐不写进新仓库。完整平台库验密仍需部署配置后联调。
|
||
- 已生成 `source-inventory.json`：现有 SQL 的 63 个接口契约、279 个变更源文件及额外找回密码控制器。此清单是范围索引，不代表已完成实现。
|
||
- 已执行 `make generate`、相关 Go 测试、变更前端 ESLint 和生产构建。构建存在原 `arcdash` 依赖的 BigInt 浏览器目标警告。
|
||
- 第一批提交 `ce4b54a` 后 `go test ./...` 全量通过；第二批账号功能的 biz/data/service/modules/server/cmd 检查及前端生产构建通过。
|
||
- 用户反馈实际商务列表失败后，定位为 sw7 缺少 `tab_promote`。已解耦基础列表与渠道统计：有绑定且渠道表缺失时返回 `promoteCount: null`，界面显示“未接入”，无绑定账号仍为真实零。新增通过真实 TCP 请求的 HTTP 回归测试，覆盖系统数据库及完整渠道表两种场景。
|
||
- 已通过正常验证码登录取得测试会话，并在修复后的独立 18000 实例连接同一 sw7 执行 HTTP 请求。列表总数 45，分页、账号筛选、资料和偏好查询全部成功。详见 `http-verification-2026-11-03.json`。8000 为用户 GoLand 旧二进制，需重新运行才加载源码修复。
|
||
- 绑定批次通过 13 项真实 HTTP 检查：商务 45 条、绑定 58 条、平台与审核筛选、详情、偏好查询和写请求校验，结果见 `http-business-bindings-2026-11-03.json`；`scripts/sw_http_smoke.py` 可复用且不记录令牌。真实库不制造测试商务或发起实际平台绑定。新增、修改、偏好关闭、提交绑定及解绑的正向流程已用独立 SQLite 数据库通过实际 TCP HTTP 测试；平台验密外部边界使用测试替身，密码算法另用固定向量验证。
|
||
- 登录/找回密码批次 `go test ./...` 全量通过，前端 ESLint 和生产构建通过。Chrome 已检查桌面/移动登录页及三步找回流程（短信接口受控替身）；完整找回密码链路已通过匿名 TCP HTTP + SQLite 测试，覆盖错误验证码后重试、原子消费、改密版本更新和凭证重放拒绝。实际运行实例四个匿名接口校验与既有 13 项商务 HTTP 回归全部通过，未发送真实短信或修改真实用户密码。
|
||
- 预警规则七个接口及 Kra 页面已接入。一级商务管理自己的规则，二/三级读取所属一级的规则，超管可管理全部；启停、软删除、监控指标与原校验一致。分类选项来自历史预警记录，删除规则不会丢失历史分类。编辑不覆盖独立的启停/删除状态，省略的可选指标字段沿用旧值。
|
||
- 新增预警表缺表建表迁移，保留既有表；阈值列支持原页面 9999% 上限。当前 sw7 启动前后均为 `decimal(7,2)`，没有改动既有规则数据。触发检测任务和记录去重写入尚未迁移，不作为规则页面完成范围。
|
||
- 规则批次通过 biz/data/service/cmd/server/modules 检查、前端 ESLint 与生产构建；隔离 SQLite + TCP HTTP 测试覆盖新增、编辑、启停、软删除、历史分类和跨商务权限。`alert-rules-http-2026-11-03.json` 记录真实 sw7 查询与无效写请求，`alert-rules-page-2026-11-03.json` 记录四级角色入口与指标表单联动；可复用脚本为 `scripts/sw_alert_rules_smoke.cjs`。
|
||
- 预警记录八个接口与列表、处理抽屉已接入。列表、详情和写入同时按所属一级商务及本人/下级的已通过绑定隔离，渠道键包含平台，保留停用一级渠道的历史预警。`businessId` 筛选取指定商务渠道范围与查看范围的交集，不误用预警归属一级字段。状态汇总仅随范围、平台和指定渠道变化，不受名称、分类、指标及列表状态筛选影响。
|
||
- 完整工作流为未处理→处理中→待审核→已处理，或待审核→审核驳回→处理中后重新提交。审核只允许一级商务，超管等级为零时也不能审核。状态条件在带权限条件的行锁事务中检查，状态日志及可选备注共同提交；独立备注不改状态，保留原接口允许已关闭记录追加备注的行为（旧页面只读态仍不展示备注编辑区）。
|
||
- 备注图片复用 Kra 上传接口，支持选取、拖拽、粘贴、暂存预览和移除；添加备注时才上传。修复旧前后端矛盾：先要求非空备注再上传，部分上传或备注失败重试时复用已上传结果。历史数字附件批量查询新文件表，URL 附件保持原值，异常 JSON 视为空附件；记录/规则/日志大 ID 使用字符串响应，避免浏览器精度丢失。
|
||
- 补充 `202611030007_business_alert_attachments`，针对原 SQL 遗留的日志数字附件做文件 ID 映射。只转换与 `bak_sw2kra_20261103_sys_alert_operation_log` 备份相符的旧日志，新日志、URL 或已变化引用不改动；缺失旧文件不解释为同号新文件，原引用保留在备份。详见 `alert-attachment-migration.md`。
|
||
- 预警记录批次全量 `go test ./...`、前端 ESLint 与生产构建通过。隔离 SQLite + 实际 TCP HTTP 覆盖全部处理动作、驳回重提、跨商务/平台拒绝、大 ID、附件读取与缺表场景；仓储测试覆盖日志失败回滚与重复请求。MySQL 行锁的真实并发验证留待最终隔离旧库验收。`alert-records-http-2026-11-03.json` 记录当前 sw7 的真实会话请求；当前预警零条，未创建真实预警或上传文件。原商务 45 条、绑定 58 条的 HTTP 回归继续通过。
|
||
- `alert-records-page-2026-11-03.json` 记录真实 Chrome 下四个等级、五种状态的入口检查，以及完整抽屉流程、附件延迟上传、状态卡片筛选、缺渠道数据提示。浏览器业务数据、处理写入和上传使用受控替身；正向服务端行为另由前述 TCP HTTP 测试覆盖。
|
||
- 渠道激活 `/sw/promoteActivePool/bindList` 和 `/sw/promoteActivePool/bindSpendDetail` 及旧同名页面已接入。OA 连接复用 `data.database_list` 中别名 `oa` 的共享客户端；只读 `sys_promote_active_pool_bind`，不创建或修改 OA 表。普通商务按本人已通过绑定的账号集合匹配 OA 认领，不包含下级，超管不限；保持旧实现按账号匹配的规则。
|
||
- 激活流水从主库 `tab_spend` 按游戏汇总，成功支付、同平台、绑定开始（含）到达标/解绑截止（含）；渠道树包含本级、直属子级及 `top_promote_id` 匹配项，不依赖全局下级/身份证偏好。达标时间优先于解绑时间，进行中没有结束上限。使用 EXISTS 避免重复渠道行导致金额翻倍，金额及大 ID 以字符串返回，计算和页面格式化避免浮点精度丢失。
|
||
- 激活批次通过全量 `go test ./...`、ESLint 和生产构建，以及主库/OA 两个隔离数据库的实际 TCP HTTP 测试。`activation-http-2026-11-03.json` 记录当前真实会话请求（OA 未接入，明确 available=false）；`activation-page-2026-11-03.json` 核对旧页面列、五种状态入口、筛选重置、达标截止与大金额。待审核可以打开流水入口但显示原接口“审核通过后可查看”，已驳回不显示入口；明细读取失败不展示伪造零流水。
|
||
- 已对框架基线至 main 的 Git 差异核实：`SysMessageController` 与 `SysMessageServiceImpl` 未变更，旧导航栏消息入口也被注释，因此不新增商务消息 UI。SW 主库写入待审绑定后由外部 OA 审核，并没有需要照搬的 SW 内部 OA 同步任务；最终联调仍须核对 OA 连接目标及商务用户 ID 映射，不能把隔离替身测试当成外部审核验收。
|
||
- 渠道列表、可用绑定、新增渠道、推广游戏分布四个接口及对应 Kra 页面已接入。列表读取本人及全部下级的正常绑定，超管默认不限；指定商务用户只取该用户本人的绑定。商务账号关键词同时匹配平台账号和 SW 登录名，保留 Java 文字子串语义，不把 `%` 变成通配符。渠道状态筛选使用锁定状态字段。
|
||
- 渠道列表游戏数仅统计当前渠道已通过申请的去重游戏；玩家数和成功充值额按原渠道树及全局偏好汇总。身份证去重跨整棵统计树进行，空证件不计入，末尾 X/x 归一。指标按平台/渠道组合批量查询；缺失指标单独返回 null，已有指标继续显示。真实 TCP HTTP 回归发现并修复 `idcard` 列映射错误，增加存储字段与实际返回人数断言。
|
||
- 游戏分布只列当前渠道已通过的推广游戏，读取 `tab_sw_report_day` / `tab_sw_report_day_key`，人数按当前去重模式去重，金额固定模式 0。累计起点保留旧实现从当前人数口径的最早日汇总取得、缺省当天的规则，截止上海当天；不能与列表原始注册/充值口径混用。金额先保留两位再排序，同金额按游戏 ID。
|
||
- 新增渠道由 biz 决定一级、待审核 `-3`、默认注册类型和七天结算周期；data 在对应源平台库同事务写渠道、结算记录、商务渠道关系。密码复用旧 cmf 格式和 `SW_SDK_AUTH_CODE`。MySQL 创建使用固定连接持有账号命名锁直到事务提交，商务关系在行锁内追加；命名锁的真实并发验证留待最终隔离平台库联调。没有创建真实平台测试渠道，也没有伪造主库同步副本。
|
||
- 渠道批次通过全量 Go 检查、前端 ESLint/生产构建、独立主库和源平台 SQLite 的 TCP HTTP 验证。`channel-http-2026-11-03.json` 记录实际 sw7 会话请求，当前主库渠道数据未接入，lx/hw/yq 正常绑定选项分别为 17/20/20 条。`channel-page-2026-11-03.json` 核对一级商务新增入口、平台切换清空绑定、跨平台同号、零游戏数入口、缺失指标提示及新增提交参数。画像入口继续随画像用例迁移，当前不将整个渠道菜单标为完成。
|
||
- 核对剩余用户接口的基线差异及 Kra 原生能力，记录于 `system-api-audit.md`；保留历史别名未注册、Excel 协议未兼容等差异，不把能力对应表当成接口兼容完成证明。商务页面仍不增加原页面没有的编辑/删除/导入/导出入口。
|
||
- 修复原生用户启停只更新 enable、商务状态不同步的问题：由 biz 决定状态联动，在 data 行锁事务中一起写入；未启用时保留待审/驳回，个人资料请求不能自行解除管理员限制。当前 45 个真实用户只读检查未发现已有冲突，没有批量更新真实账号；正常启停、审核状态保留、失败回滚和越权通过隔离 HTTP/仓储/领域测试。全量 Go 测试通过，实际服务检查记录为 `user-status-http-2026-11-03.json`。
|
||
- 新增 `/sw/business/:userId/portrait` 与 `/sw/business/bindPlatform/portrait`。补齐商务列表画像、正常绑定画像和只读 SDK 详情平台入口，共用 Kra 风格抽屉，包含基本资料、五个时间周期、四项指标、可交互趋势、注册/充值 TOP 5 及独立分页的关联预警。SVG 图表使用 Kra 主题变量，无新增图表依赖，支持键盘数据点和负金额。
|
||
- 普通商务基本资料来自新系统用户，SDK 资料来自对应平台库，父级分别按 SW parent_id 和平台 commerce1/commerce2 解析。SDK 状态 0 仍是待审核，不能当作 SW 正常；关联预警/旗下渠道使用打开时的 SW 用户 ID，平台商务 ID 只作为绑定筛选。保留旧 SDK 画像关联预警按商务及平台的实际范围。
|
||
- 画像日指标与日趋势读取汇总/身份键表，模式 0 人数带平台前缀、模式 1 跨平台身份证去重，金额固定模式 0。付费率分母为活跃人数，人均充值分母为注册人数；上期活跃为零时付费率对照和百分点差为 null。今日/昨日趋势读原始主账号与成功支付、补齐 24 小时；MySQL 保留原 HOUR(FROM_UNIXTIME) 会话时区语义。注册 TOP 5 在渠道树内 COUNT DISTINCT；人数上限在排序截取前应用。
|
||
- 画像批次通过领域/存储/双库实际 TCP HTTP 测试、全量 Go 检查和前端 ESLint/构建；验证月末/闰月对比、四舍五入与负零、去重切换、金额稳定、原始小时口径、父级状态、跨商务拒绝及缺表。`portrait-http-2026-11-03.json` 为真实会话检查：无绑定返回零指标及完整趋势，有绑定缺表保留基本资料并明确未知。`portrait-page-2026-11-03.json` 核对三个入口、周期切换、交互图表、两个 ID 范畴和缺数据提示。
|
||
- 当前没有执行最终旧数据库复制与迁移验收。
|
||
- 渠道画像 `/sw/promote/portrait` 与列表入口已接入，包含基本资料、累计/当期指标、趋势、四档付费分层、关联预警及推广游戏抽屉。复用画像统计并增加经过校验的单渠道树范围、无对照期分支；渠道第四项保持活跃玩家。分层成员取累计注册身份，金额按历史成功支付及原始付款账号/身份证口径，保持无日期过滤，不能误复用指标周期过滤。
|
||
- 修复旧渠道页面两处参数错配：近7/30天改发 last7/last30，关联预警改发 targetPromoteId 而不是 businessId。领域、存储和隔离 TCP HTTP 覆盖分层边界、子账号与跨平台、模式切换、累计无环比、原始小时趋势和缺数据；浏览器验证入口、正确参数、四档分层及游戏抽屉。全量 Go、ESLint/构建通过；当前真实会话请求记录于 `channel-portrait-http-2026-11-03.json`，仍未复制实际旧业务库。
|
||
- 注册/充值明细、两个 XLSX 导出及游戏下拉共五个接口已接入。注册保留 puid=0、同平台玩家全部历史成功充值；充值合计只算成功单，不随列表状态改变。渠道精确匹配、商务文字筛选、官方/未知渠道和跨平台同号均按旧口径处理。
|
||
- 修复注册游戏关联跨平台、超过200个渠道后放宽筛选的问题，批量补充当前页资料。导出超过10000条提前拒绝，保留数字/文本类型及原字段顺序。页面使用 Kra 表格、筛选、日期控件与下载，保留近30天默认显示和大额行高亮；注册导出权限与接口一致。
|
||
- 明细批次通过全量 Go、前端 ESLint/构建、隔离 TCP HTTP、工作簿内容校验和浏览器筛选/下载。真实 sw7 请求及空查询工作簿验证记录见 `ledger-http-2026-11-04.json`、`ledger-page-2026-11-04.json`，没有导出或修改真实业务行；详细边界见 `ledger-source-notes.md`。
|
||
- 渠道/游戏统计两个接口与 Kra 页面已接入，保留游戏筛选、渠道账号/类型筛选、平台、日期、排序、分页及全量汇总。金额固定模式 0，人数按当前身份证偏好；游戏汇总累加各游戏，渠道超管汇总全局去重、普通商务累加可见渠道，不互相替代。渠道模糊匹配扩到可见同树渠道，并保持类型交集；超管全平台范围包含官方和历史孤立渠道。
|
||
- 统计批次通过全量 Go、隔离数据库真实 TCP HTTP、领域/仓储测试、ESLint/生产构建；真实 sw7 请求和 Chrome 检查见 `analytics-http-2026-11-04.json`、`analytics-page-2026-11-04.json`。分页不改变汇总，缺表明确未接入；非法日期/倒置周期明确报错。没有添加旧统计页面不存在的导出按钮。详细口径与优化见 `analytics-source-notes.md`。
|
||
- 区服列表与区服选项接口、Kra 区服分析页面已接入。统计按平台＋游戏＋区服编号分组，人数区服内去重、金额固定模式 0；页尾汇总全部筛选行。游戏必选，选项按当前游戏名，报表按历史游戏名，区服编号保留前导零。
|
||
- 区服批次通过全量 Go、隔离数据库真实 TCP HTTP、前端 ESLint/构建和真实 sw7 只读接口请求，结果见 `server-analysis-http-2026-11-04.json`。覆盖跨平台同号、全量汇总、零行处理、偏好切换、资料补全及缺表；按用户新要求未执行页面交互检查。最终旧库验收仍未开始。
|