weizhiqiang/superlink
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9e080b175c33ebfb7bbaf17057d24c69d7d7999c
superlink/docs/superlink_架构与功能优化设计方案.md
T

16 KiB
Raw Blame History

SuperLink 架构与功能优化设计方案（草案 v0.1 · 待评审）

原则：先文档 · 后评审 · 再写代码。 本文档为实施前的设计草案 + 现状评审发现，供项目负责人评审拍板。评审通过前不改动代码。 关联：docs/superlink_产品评测与优化路线图_2026.md（战略总览）；本文档为落地执行细案。

  • 撰写：2026-09
  • 目标版本：v1.0.51 起
  • 状态：DRAFT — 待评审

0. 评审结论速览（TL;DR）

主题 结论 建议动作
迁移管理 ⚠️ 无版本表，多环境易漏跑迁移 第一批落地
鉴权 🔴 login 用 sha1（无盐），CSRF 仅靠请求头 第一批加固
样板代码 🔴 每个接口重复堆"鉴权+校验+JSON+日志" 抽出统一定义层
前端 🟡 单文件过大、字符串拼 HTML 组件化收敛
官网承诺 vs 代码 🔴 AI 触达/线索流转/ROI 是营销态，代码未实现 第二批功能闭环
差异化 🟢 碎片治理/完整度/渠道归因已是独特资产 放大 + 产品化
数据库 🟡 索引/口径/预算备份表待清理 第三批打磨

🔴=高优先级 · 🟡=中 · 🟢=已具备/优

1. 现状评审发现（问题清单）

依据源码精读（文件行号截至 v1.0.50）。

1.1 安全

  • [REV-SEC-1]🔴 密码仅 sha1 无加盐（api/auth/login.php:37 hash_equals($user['password'], sha1($password))）。撞库成本极低。
  • [REV-SEC-2]🟡 CSRF 仅靠 X-Requested-With 头（common/auth.php::checkAjax），无真正的 CSRF Token，敏感写操作可被跨站伪造（头只能防"简单表单"）。
  • [REV-SEC-3]🟡 登录无速率限制/失败锁定，可被爆破。
  • [REV-SEC-4]🟡 session 默认配置，未设 cookie httponly/samesite，未设会话超时/固定防护。

1.2 可维护性 / 架构

  • [REV-ARCH-1]🔴 无数据库迁移版本表。sql/migration_v1.0.XX.sql 需手工依次执行，无 schema_versions 记录、无校验、无回滚；v1.0.48 遗留 preliminary_data_bak_* 冗余备份表。
  • [REV-ARCH-2]🔴 样板重复：每个 api/<模块>/<动作>.php 重复 require db/response/auth + checkAjax + checkPermission + SQL + logAction + Response，约十余个接口高度同构，改一处规范需改 N 处。
  • [REV-ARCH-3]🟡 无集中错误/慢查询观测，仅靠 system_logs 业务审计，无技术异常日志。
  • **[REV-ARCH-4]🟡 前端 static/js/fragment.js 单文件承载硬/软两套逻辑，common.js 用字符串拼 HTML，难维护难测试。
  • [REV-ARCH-5]🟢 统一 JSON 规范（code/msg/data）、字段白名单（helpers.php）、完整度引擎（completeness.php）、审计（logger.php）已具备且质量良好——是很好的可扩展地基。

1.3 数据 / 性能

  • [REV-DATA-1]🟡 social_accounts 多态 owner，跨表统计口径绕；高频过滤列（is_incomplete/source_channel/owner_type+owner_id/platform）索引不明确。
  • **[REV-DATA-2]🟡 ammer_time 历史遗留：tools/migrate_time_to_date.php 已有迁移脚本，但未见在迁移流程中统一执行。
  • **[REV-DATA-3]🟢 phone.dat（4.5MB）已打包，可做成离线手机归属地查询能力，无外部依赖。

1.4 功能缺口（对照官网承诺）

  • [REV-FN-1]🔴 "AI 补全" 是占位（fragment.js 操作列），未真正调用任何 AI/RAG。
  • [REV-FN-2]🔴 EDM 只有"筛选+导出"（marketing/edm.php），无真实发送/回传。
  • [REV-FN-3]🔴 无"线索→商机→成交"状态机与跟进轨迹时间线，与官网"线索自动流转、全程记录跟进轨迹"不符。
  • [REV-FN-4]🟡 无 ROI 面板（dashboard 有统计卡，无"获客成本/转化率/成交额"）。
  • [REV-FN-5]🟡 舆情监测/竞品分析多为占位；EAV 产品参数已建模但"行业对比"视图未落地。
  • [REV-FN-6]🟢 人脉亲密度算法已实现（person/connections.php），可产品化为可视化图谱放大差异化。

1.5 代码级评审发现（已核实 v1.0.50 · 2026-09 补充 code review）

由评审会对 common/ auth/ fragment/ channel/ system/user_add 逐一核实到行号得出。

🔴 严重（安全）

  • [REV-1] 密码 sha1 无加盐：login.php:37、user_add.php:48。离线可撞库。
  • [REV-2] CSRF 仅 X-Requested-With 头（auth.php::checkAjax），无随机 Token。
  • [REV-3] 前端字符串拼 innerHTML 渲染服务器字段 → 潜在存储型 XSS（待确认 C1），缺统一转义。

🟠 高（一致性/正确性）

  • [REV-4] 硬碎片来源不可编辑：hard_update.php:89-111 的 UPDATE 装列不含 source_channel，只能 add 不能改。
  • [REV-5] 碎片录入被主表全局唯一性"拦死"（hard_add/soft_update 对 companies/social_accounts 判重）：业务口径需确认 C2。同邮箱/电话跨企业、多电话同人时新线索录不进。
  • [REV-6] soft_update.php:77 $id 以字符串拼进 SQL（已 int 强转不可注入，但破坏 prepared 风格，卫生项）。

🟡 中

  • [REV-7] 渠道分析 N+1：analysis.php:59-69 循环内逐条查 source_detail。
  • [REV-8] 登录无限流/无失败锁定、startSession 未设 httponly/samesite。
  • [REV-9] analysis.php 表名 $table 直接拼 SQL（当前仅内部常量调用安全，属 footgun）。

🔵 低

  • [REV-10] hard_convert.php:141 $resolveCompany 先查后插，并发同名称可能建重复企业。
  • [REV-11] user_add.php:23 密码仅长度校验。
  • [REV-12] phone/email 全库跨企业+人员全局判重，交叉占用会互相阻断（同 REV-5）。

待确认项

  • C1 前端渲染是否逐处转义（决定 REV-3 是否为已存在 XSS）。
  • C2 全局唯一性是"阻断"还是"提示"（决定碎片录入产品语义，涉及 REV-5/REV-12）。

2. 目标架构设计

2.1 目录结构（目标）

api/
  common/
    Api.php            # 新增：统一接口基座（鉴权 + 参数 + JSON + 日志 + 分页）
    migrate.php        # 新增：迁移执行器（配合 sql/schema_versions）
    security.php       # 新增：CSRF Token、限流、Session 安全配置
  auth/  channel/  ... # 业务模块（逐步接入 Api.php，非一次性重写）
tools/
  migrate.php          # 新增/改造：命令行跑迁移
  bump_version.php     # 改造：同时同步 config.js
sql/
  schema_versions.sql  # 新增：建版本表 + 首次基线

2.2 评审通过的决策点（由你拍板）

  • D1 迁移方案：采用「版本表 + 顺序执行脚本」最小方案（A），暂不引入 php-migrations 等第三方依赖，保持纯 PHP 极简。
  • D2 密码升级：password_hash(password_verify)，存量 sha1 用户在登录命中时平滑迁移到新哈希（登录一次即升级，无需批量重写密码）。
  • D3 CSRF：Session 绑定随机 Token，前端 common.js AJAX 统一追加 X-CSRF-Token 头；保持现有 checkAjax() 兼容。
  • D4 是否抽统一 Api.php 基座：建议抽；新接口必须走它，存量接口"用到的先迁、不动的不强制迁移"，避免大爆炸式重写。
  • D5 AI 补全如何接入：接千视 RAG/大模型（需提供 API），输出"带置信度的建议字段"，用户一键采纳/拒绝。若暂无 AI API，可先做"规则式自动补全"（手机归属地→城市、行业字号→行业、国家→地址缺省）占位过渡。
  • D6 触达通道：EDM 发送优先（可邮件模板 + SMTP/第三方），企微/短信二期。

2.3 统一接口基座（common/Api.php 设计）

class Api {
    // 用法：Api::handle('fragment', function(PDO $pdo, array $in){ ... return $data; })
    // 内部统一：requireLogin + checkPermission + checkAjax(写) + 参数默认 + Response + 异常兜底(log) + logAction
}
  • 收敛 checkAjax/checkPermission/logAction 重复样板；
  • 统一异常→JSON、SQL 错误→技术日志 + 友好提示；
  • 提供 paged() 输出，统一 list 分页结构。

2.4 迁移执行器（tools/migrate.php + sql/schema_versions）

  • 建 schema_versions(id, version, applied_at, checksum)；
  • php tools/migrate.php up　顺序执行 sql/migration_*.sql 中未应用者，记录版本与文件 checksum（防改旧脚本）；
  • 提供 php tools/migrate.php down <version>（可选，先支持正向即可）；
  • 首次基线收录现有 migration_*.sql；清理 preliminary_data_bak_* 用一条收敛迁移。

3. 功能设计（第二批）

3.1 AI/规则补全（P0，破局）

  • 数据表：无需新表，落在 preliminary_data / 主表字段。
  • 接口：api/fragment/ai_suggest.php
    • 入参：target_type / fragment_id / 已有字段
    • 出参：suggestions:[{field, value, confidence, reason}]
  • 前端：硬/软碎片"AI 补全"按钮 → 弹窗展示建议列表 → 采纳/拒绝 → 回写 hard_update/soft_update。
  • 过渡：权限/hook 式——有千视 API 走 AI，无则走规则引擎（手机归属地→工作地/国家；cn_to_en 已有能力复用）。

3.2 EDM 真实触达 + ROI 面板（P0/P1）

  • EDM：edm.php 增 发送/模板/任务，edm_export 保持；发送回执写回 system_logs 或新 edm_tasks。
  • ROI：dashboard 增加"渠道 ROI"卡片/图表（数据来自 source_channel × 商机状态 × 预估成交额），复用已引入的 ECharts。

3.3 线索状态机 + 跟进轨迹（P1）

  • 新表 leads(id, ref_table, ref_id, status[初访/跟进中/已商机/已成交/放弃], owner_user_id, pipeline...)，或直接在 companies/persons 加 lead_status。
  • system_logs 扩展 follow_status，形成按线索的时间线。
  • 意向识别（is_incomplete 由 1→0、完整度晋升、EDM 打开/回复）→ 自动创建 lead 并推送 owner_user_id。

3.4 舆情监测 + 竞品参数对比 + 人脉图谱（P1/P2，差异化）

  • 舆情：接入千视舆情能力 → media_opinion 真实成单页。
  • 竞品对比：EAV 行转列，同行业 company_products_attr_value 对比表 → competitor_data 落地。
  • 人脉图谱：person/connections.php 亲密度 → ECharts 关系图（graph）→ person 详情页增强。

4. 落地路线图（3 个批次）

每批独立可发布、可评审、可回滚。

批次 1 · 架构筑基（v1.0.51）

项 涉及文件 说明
迁移版本管理 新增 tools/migrate.php、sql/schema_versions.sql；收敛旧 migration 先建基座
登录安全 login.php(bcrypt 平滑迁移)、auth.php、新增 security.php bcrypt + 限流 + session 加固（REV-1/REV-8）
CSRF Token auth/auth.php/session.php + common.js 写接口头校验（REV-2）
统一 Api 基座 新增 common/Api.php；先迁 fragment/hard_* 或 system/* 一个模块试点 收敛样板
前端收敛 common.js 拆表格/弹窗/分页 helper + 统一 esc() 转义 可增量（REV-3/C1）
碎片来源可编辑 fragment/hard_update.php 更新装列加入 source_channel 一致性（REV-4）
prepared 卫生 soft_update.php:77 等残余字符串拼参改占位符 卫生项（REV-6/REV-9）

验收：①能 up/down 跑迁移；②新用户密码为 bcrypt、老用户登录后被平滑升级；③写接口带 CSRF Token 合法可过、缺失被拒；④至少 1 个模块接入 Api 基座且行为不变；⑤硬碎片来源可新增/修改；⑥统一 esc() 后抽查模块无未转义渲染（此需求取决于 C1 确认）。

批次 2 · 功能闭环（v1.0.52）

项 说明
AI/规则补全落地 ai_suggest.php + 前端弹窗（接千视 API 或规则兜底）
EDM 真实触达 模板/发送/回执
ROI 面板 dashboard 渠道 ROI 图表

批次 3 · 销售闭环 + 差异化（v1.0.53+）

项 说明
线索状态机 + 跟进时间线 leads 表 + 自动流转
舆情监测 / 竞品参数对比 / 人脉图谱 差异化成单模块
索引 / 性能 / 导入即治理 打磨

5. 需要你拍板的决策（评审门槛）

  1. D5 关键：AI 补全——是否已有千视 RAG/大模型 API 可接？若暂缺，是否接受先用"规则式补全"过渡？（决定批次 2 的 AI 项怎么落地）
  2. D4：是否同意新增 common/Api.php 统一基座并"用到的先迁、存量不强制"？
  3. D2：密码升级方案（bcrypt 平滑迁移）是否认可？（会改变存量用户密码存储格式）
  4. 批次节奏：是否按「批次1 架构筑基 → 批次2 功能闭环 → 批次3 差异化」推进？可只做其中某批次。
  5. 优先级冲突时：先保架构地基（批次1）还是先上能对外演示的功能（批次2）？
  6. C2（评审 REV-5/12）：手机/邮箱/企业名等全局唯一性校验遇到主表已有记录时，是保持"阻断新增"（当前行为）还是降级为"提示但允许继续"？（后者更贴合"碎片=待审线索"语义，但会让同一电话挂在多个主体下）

附：C1（前端转义是否已存在 XSS）需现场确认后再决定批次1「前端收敛」是否纳入 REV-3 修复。

评审意见请直接回复上表的决策项编号与结论（例如"D5 暂无AI，先规则补全；按批次1→2→3 推进"）。通过后我按批次开始写代码。

6. 批次1 实现记录（v1.0.51 · 已实现并验证）

已拍板的批次1范围，本版本全部落地。服务器端验证通道：ssh ubuntu@106.55.169.92 → docker php:8.2-cli php -l（95/95 通过）+ CSRF/bcrypt CLI 冒烟（ALL PASS）。

项 落地文件 验证
①版本迁移 sql/schema_versions.sql、sql/migration_v1.0.51.sql、tools/migrate.php（up/status/down、natsort、md5 checksum） lint 通过
②登录安全 bcrypt 平滑迁移（api/auth/login.php：旧 sha1 命中→password_verify→自动重写 bcrypt；user_add/user_update 新强度规则+password_hash）+ 限流/session 加固（api/common/security.php） 冒烟 PASS
③CSRF Token 服务端 csrfToken()/checkCsrf()（security.php），GET 取 token（auth/csrf.php public）、写接口统一校验；前端 common.js httpPost 携带 X-CSRF-Token、login.js 登录页取 token 冒烟 PASS（错误 token → 403）
④统一基座+强制迁移 common/Api.php Api::boot(['public'/'super'/'module'/'permissions'])，全部 70 个 endpoint 存量强制迁移（脚本转换，逐一审计无遗漏、无误删 include）；hard_common.php 等纯 include 保留 全局 require 审计干净
⑤前端收敛 common.js 新增 esc 别名（现即统一转义入口）；统一 escHtml —
⑥REV-4 来源渠道可编辑 hard_update.php 支持 source_channel + 前端补全弹窗新增来源渠道下拉（回显） —
⑦prepared 卫生 soft_update.php 违规 $pdo->query 修为 prepared（REV-6）；analysis.php 表名白名单（REV-9） lint 通过

明确延后（记录在案，建议下批次处理）：

  • REV-7：analysis.php 渠道详情 N+1（LIMIT 10 内子查询，量级可控，批内不动）。
  • REV-3/C1：XSS 前端收敛——已提供统一 esc() 转义入口，但存量页面 JS 的逐个改逃逸需下批次；新写代码一律用 esc()。
  • REV-5/12：手机/邮箱/企业名全局唯一性 保持"阻断新增"（已拍板）。
  • REV-10：并发下企业重名竞态（可在 company/add 加唯一索引兜底，下批次）。
  • 部署形态：确认长期部署目标为服务器 106.55.169.92；config/database.php 当前写死 127.0.0.1/mysuperlink/...，容器化部署需改为 env 注入（下批次随 docker-compose 落地）。

附录 A：与战略文档的关系

本《设计方案》是把战略文档第四部分（架构+功能优化）细化到"改哪些文件、怎么改、能否回滚、验收标准"的可执行层。两文档共用同一结论：先补齐迁移/安全/样板三块地基，再用 AI 补全 + EDM + 线索流转 + ROI 兑现官网承诺，最后用舆情/竞品/人脉图谱做出差异化。

Reference in New Issue View Git Blame Copy Permalink