kra-new/docs/sw6-to-kra/implementation.md

商务功能迁移执行记录

基线与方法

• 旧后端：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 接口，不能只以单元测试和构建作为完成依据。

用户再次指出页面偏差后，明确按旧前端实际页面核对入口，不能从后端接口推断 UI 功能。详见 page-parity.md。商务列表已移除错误增加的编辑入口，恢复“绑定列表”名称及仅三级显示规则，并对齐按审核状态显示行操作。

用户已有的 configs/config.yaml 修改与迁移 SQL 保留。未经最后阶段的数据库确认，不连接、复制或修改用户的旧数据库。

依赖顺序与完成标准

阶段	范围	状态
1	商务用户字段、层级与角色、账号资料和审核、偏好、登录及找回密码	进行中
2	平台绑定、商务/渠道可见范围、外部平台与 OA 数据源、商务列表及抽屉	进行中；绑定和旗下渠道已接入，画像及 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 映射分配；账号、角色、偏好在同一事务创建。列表按平台与商务组合键统计直属一级渠道和已通过绑定。
• 商务画像及其关联报表仍在后续范围内；后端导出等接口另按源码核对，不能据此给旧页面增加不存在的按钮。当前不将整个商务菜单标为完成。
• 已接入绑定列表、指定商务已通过绑定详情、提交绑定及解绑四个接口，页面恢复仅三级可见的“绑定列表”页签及只读详情抽屉。绑定流程保持三级限制、平台验密、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。
• 当前没有执行最终旧数据库复制与迁移验收。