diff --git a/AIcoding.md b/AIcoding.md deleted file mode 100644 index 61e5c76..0000000 --- a/AIcoding.md +++ /dev/null @@ -1,133 +0,0 @@ -# AI Coding 通用方法与技巧 - -> 一套可迁移到任意项目的 AI 辅助编码（AI Coding）方法论：如何与 AI 高效协作、如何约束 AI 产出质量、如何让系统保持可回归与可审计。 - ---- - -## 一、核心方法论 - -### 1. 规格驱动开发（Spec-Driven Development） - -先规格、后代码。把"需求 → 设计 → 任务"作为地面真值，再让 AI 据此实现： - -| 阶段 | 产出 | 要点 | -|------|------|------| -| 需求 | 可测试、可追溯的需求描述 | 用结构化句式（如 WHEN/IF/WHERE/SHALL），每条需求都能映射到验收标准 | -| 设计 | 架构、数据模型、模块边界、**正确性属性** | 明确不变量（invariants），它们将成为测试依据 | -| 任务 | 可执行的任务清单 | 拆到可独立实现并验证的粒度 | - -**收益**：AI 有明确的"做什么"与"对错标准"，避免凭感觉发挥；改动前先回到规格确认，减少返工与漂移。 - -### 2. 确定性核心 + AI 语言层 的分层（最关键的架构原则） - -> **凡涉及金额、评分、判定、裁决等关乎正确性与合规的逻辑，一律用确定性纯函数实现，绝不交给大模型；大模型只承担语言理解（解析、抽取、归类、摘要、预填）。** - -- **确定性核心**：无副作用、可复算、相同输入恒得相同输出，便于测试与审计。 -- **AI 边界层**：负责把自然语言/非结构化输入转成结构化数据；调用失败或超时时**自动降级**到确定性兜底，不阻塞主流程。 -- **收益**：把大模型的不确定性隔离在"翻译层"，不污染决策；系统结果稳定、可解释、可回归——这是合规与高可靠系统的硬要求。 - -### 3. 属性化测试（Property-Based Testing） - -对核心逻辑写"属性"，而不仅是样例用例。属性描述对**任意**合法输入都应成立的不变量，例如： - -- 输出值恒落在合法值域内； -- 派生结果与其定义函数恒等（如等级恒等于按分值分级的结果）； -- 幂等性：重复执行结果不变； -- 往返一致：序列化后再反序列化与原值等价； -- 局部不变：修改 A 不应影响与之无关的 B。 - -**收益**：用随机输入覆盖人想不到的边界；属性即"活的规格"，是重构时的安全网。 - ---- - -## 二、与 AI 协作的有效技巧 - -### 1. 小步快跑 + 每批验证 -长任务拆成小批，每批改完立刻跑验证三件套（类型检查 / 静态检查 / 测试），全绿才进入下一批。**绝不在未验证的情况下连续堆叠改动**——否则错误会层叠，难以定位。 - -### 2. 用强类型/静态检查做护栏 -开启语言可用的最严格静态检查选项。编译器/类型系统把大量运行期 bug 前移到编码期；AI 生成的代码尤其受益于强约束护栏。 - -### 3. 每个可工作的改动独立提交 -一个改动完成并验证后立即提交，提交信息写清"根因 + 改法 + 验证方式"。便于回滚，也便于审计 AI 的每一步决策。 - -### 4. 根因优先，拒绝表面打补丁 -遇到问题先定位**根因**再动手： -- 区分"数据/输入缺失"与"逻辑 bug"——前者加校验与提示，后者改逻辑。 -- 区分"展示问题"与"计算问题"——不要用改公式来掩盖录入或展示缺陷。 -- 同一方法连续失败两次就停下来分析根因，换思路，而不是继续微调。 - -### 5. 端到端真实验证 -单元测试之外，在接近真实的环境做端到端验证：触发操作 → 检查副作用（数据库记录、文件产出、外部状态），确认改动真的生效，而不仅是"代码看起来对"。 - -### 6. 复用既有约定，一处修复全局受益 -新功能优先沿用项目既有组件、约定与模式，而非另起炉灶。把修复做在共享组件/工具层，让所有调用方一起受益，而不是到处贴补丁。 - -### 7. 明确给 AI 的协作偏好 -开工前把稳定偏好讲清楚，例如： -- 回复与文档使用的语言； -- "简单改动直接改、复杂设计先给方案确认"； -- 哪些逻辑禁止交给大模型； -- 命名/格式/金额展示等约定； -- 测试数据必须清理、长任务分批推进等流程要求。 - -AI 在明确边界内自主推进效率最高。 - -### 8. 规避工具与环境陷阱 -- 命令行处理多字节文本（如中文）易被截断/乱码时，改用写临时文件 + 脚本读取等稳健方式。 -- 复杂逻辑放进脚本（`node -e` / `python3 -c` 等），避免在 shell 里拼脆弱的一行命令。 -- 编译型/需构建的后端，改完务必重新构建再重启进程，否则跑的是旧产物。 -- 注意存储层对特殊字符的限制（如某些数据库不接受特定控制字符），入库前编码、读出时解码。 - ---- - -## 三、工程实践沉淀 - -- **数据库变更迁移化**：所有 schema 变更走可重放、可回滚的迁移脚本，保证各环境一致。 -- **配置与密钥惰性读取**：运行期再读取密钥/配置，避免模块加载时固化导致开关失效；密钥不入库，放进被忽略的本地配置。 -- **统一审计中间件**：用一处中间件集中记录写操作与关键读操作（操作人、角色、对象、动作、结果、耗时、来源），跳过高频轮询端点避免日志噪音。 -- **稳定 ID 关联 + 数据隔离**：记录之间用稳定 ID 关联、界面实时解析为可读名称；按角色/归属做行级数据隔离。 -- **质量内建**：把可访问性、对比度、一致性等检查纳入自动化测试，由统一的设计体系保证 UI 一致。 -- **一键部署**：把构建、上传、迁移、重启、健康检查封装成一条命令，降低发布风险与心智负担。 - ---- - -## 四、优化建议（通用清单） - -### 工程与质量 -1. **端到端回归纳入 CI**：补一条主链路 E2E，作为"改 A 坏 B"的防线。 -2. **CI 门禁**：类型检查 + 静态检查 + 测试全绿才可合并/部署；发布脚本前置测试闸门。 -3. **测试分层与解耦**：高频变动模块按功能区拆分测试，降低脆性；区分单元/集成/E2E 各司其职。 -4. **性能前置**：列表服务端分页 + 关键查询建索引；大数据量时前端虚拟滚动。 - -### 架构与可维护性 -5. **及时拆分巨型文件**：单文件过大时按职责/资源域拆分，降低认知负担与合并冲突。 -6. **减少隐式依赖**：避免依赖框架的隐式缓存/副作用，关键数据显式获取一次并复用。 -7. **关键语义文档化**：易被误解的业务语义（如可累加 vs 幂等、历史值 vs 当前值）写入设计文档，防止重复踩坑。 - -### AI 层 -8. **AI 输出做 schema 校验 + 置信度阈值**：结构化校验大模型产出，低置信走兜底；把调用耗时/降级率纳入监控。 -9. **提示词与模型版本治理**：集中管理、版本化 prompt 与模型名，便于灰度与回滚。 -10. **数据飞轮**：把"预测 vs 实际"的偏差、人工修正反哺给 AI 的少样本示例，持续提升质量。 - -### 安全与合规 -11. **认证用成熟方案**：优先用成熟库而非自实现，支持密钥轮换、较短有效期 + 刷新令牌。 -12. **密钥治理与备份演练**：确认密钥不入库；定期演练备份恢复，而不仅是备份。 -13. **会话失效策略**：无状态令牌如需"立即失效"，引入短期令牌 + 服务端黑名单/版本号。 - ---- - -## 五、可复用的"黄金法则"清单 - -1. 决策逻辑确定性纯函数化，AI 只做语言层，二者严格隔离。 -2. 先规格（需求 / 设计 / 正确性属性）后代码，规格是地面真值。 -3. 核心逻辑写属性测试，而不仅是样例测试。 -4. 小步改动 + 每批"类型检查 + 测试"验证 + 独立提交。 -5. 根因优先，拒绝表面打补丁。 -6. 改完在接近真实的环境做端到端验证（含副作用）。 -7. 强类型 + 迁移化 schema + 统一审计，让系统可回归、可审计、可解释。 -8. 开工前对齐协作偏好与边界，让 AI 在明确约束内自主推进。 - ---- - -*本文为通用方法论，可随团队实践持续补充。* diff --git a/demo.config.mjs b/demo.config.mjs new file mode 100644 index 0000000..a3df9de --- /dev/null +++ b/demo.config.mjs @@ -0,0 +1,294 @@ +// 外包项目风险评估系统 — 详细使用演示视频配置 +// 运行：AI_API_KEY= node demo-video-kit/src/cli.mjs demo.config.mjs --out demo-video-out +// +// 设计：多角色走查（销售 → 风控 → 管理层 → 系统管理员），以生产环境真实数据为准， +// 全程只读浏览 + 展示新建向导前两步（不实际运行，避免产生脏数据；演示草稿事后清理）。 + +const PASS = '123456'; +const ADMIN_PASS = 'Abc123456'; +// 已完成（approved）评估，数据完整，用于详情逐区讲解。 +const DETAIL_ID = 'assessment-mq8wvenq-sou59jrj'; + +/** 登录指定用户（SPA，无整页刷新；字幕浮层保留）。 */ +async function login(page, username, password, pause) { + // 已登录则先退出，回到登录页。 + const logoutBtn = page.getByRole('button', { name: '退出' }); + if (await logoutBtn.count()) { + await logoutBtn.first().click(); + await pause(1500); + } + await page.getByPlaceholder('请输入用户名').fill(username); + await page.getByPlaceholder('请输入密码').fill(password); + await page.getByRole('button', { name: '登录', exact: true }).click(); + await pause(2600); +} + +/** 点击顶部导航（data-nav-link 跨度元素）。 */ +async function nav(page, text, pause) { + await page.locator('[data-nav-link]', { hasText: text }).first().click(); + await pause(1800); +} + +/** 展开详情页所有可折叠分区，便于完整呈现。 */ +async function expandAll(page) { + for (let i = 0; i < 18; i += 1) { + const collapsed = page.locator('button[aria-expanded="false"]'); + if ((await collapsed.count()) === 0) break; + try { await collapsed.first().click({ timeout: 4000 }); } catch { break; } + await page.waitForTimeout(180); + } +} + +/** 平滑滚动到指定纵向位置。 */ +async function scrollTo(page, y) { + await page.evaluate((yy) => window.scrollTo({ top: yy, behavior: 'smooth' }), y); +} + +export default { + baseUrl: 'https://pm.hr8ai.top', + viewport: { width: 1440, height: 900 }, + brand: '外包项目风险评估系统', + outDir: 'demo-video-out', + gotoTimeout: 60000, + subtitles: false, // 不在画面上渲染字幕（仍按解说时间轴配音） + + voice: { name: 'Cherry', model: 'qwen-tts', apiKeyEnv: 'AI_API_KEY', fallbackVoice: 'Tingting' }, + + intro: { + narration: + '欢迎使用外包项目风险评估系统。它把人工智能的语言理解与确定性的风控引擎结合，' + + '帮助企业在承接外包项目前，自动完成风险评分、红线校验与盈利测算，并支持多角色的分级审批。', + }, + outro: { + narration: + '以上就是从销售申报、风控审核、管理层审批到系统管理的完整流程演示。' + + '评分、分级、红线与盈利测算均为确定性计算，全程留痕可审计。感谢观看。', + }, + + steps: [ + // ---------------- 销售视角 ---------------- + { + label: '销售登录', + narration: + '首先以销售人员张伟的身份登录。系统采用角色化的权限管理，不同角色登录后看到的工作台与可用功能各不相同。', + run: async ({ page, pause }) => { + await login(page, '张伟', PASS, pause); + }, + }, + { + label: '销售工作台', + narration: + '这是销售的工作台。上方是我的评估统计，下方可以看到我发起的项目、审批进度，以及未完成的向导草稿。销售只能看到本人发起的评估，实现了数据隔离。', + run: async ({ page, pause }) => { + await scrollTo(page, 0); + await pause(2000); + await scrollTo(page, 360); + await pause(1500); + }, + }, + { + label: '新建评估-立项', + narration: + '点击新建评估，进入六步录入向导。第一步填写立项信息：项目名称、客户名称与适用地域。客户名称会自动匹配信用档案，影响后续的坏账计提。', + run: async ({ page, pause }) => { + await nav(page, '新建评估', pause); + await page.getByPlaceholder('如 某银行信用卡客服 BPO').fill('某制造企业生产线劳务外包项目（演示）'); + await page.getByPlaceholder('客户公司全称').fill('某大型制造企业（演示）'); + await page.locator('select').first().selectOption('上海').catch(() => {}); + await pause(1800); + }, + }, + { + label: '新建评估-描述', + narration: + '第二步填写项目描述。系统会调用大模型解析这段文字，自动识别业务类型、所属行业，并为风险指标给出预填建议，销售只需确认或微调，大幅降低录入成本。', + run: async ({ page, pause }) => { + await page.getByRole('button', { name: '下一步', exact: true }).click().catch(() => {}); + await pause(1200); + await page.locator('textarea').first().fill( + '为客户提供生产线普工与质检岗位的劳务外包，约一百二十人，两班倒；' + + '按人头费率结算，账期约两个月；需符合最低工资与社保合规要求，涉及驻场管理与考勤。', + ).catch(() => {}); + await pause(2200); + }, + }, + + // ---------------- 风控视角 ---------------- + { + label: '风控登录', + narration: + '接下来以风控专员刘洋的身份登录，查看需要审核的项目。', + run: async ({ page, pause }) => { + await login(page, '刘洋', PASS, pause); + }, + }, + { + label: '风控待办', + narration: + '风控工作台的核心是待办审核列表，列出了所有报送到风控、等待审阅的项目，以及风险分、分级与承接建议。', + run: async ({ page, pause }) => { + await scrollTo(page, 0); + await pause(2200); + }, + }, + { + label: '评估详情-结论', + narration: + '我们打开一个已完成的评估详情。页面顶部是核心结论：风险总分、风险分级、可接受性与承接建议，一目了然。', + run: async ({ page, pause }) => { + await page.goto('https://pm.hr8ai.top/assessments/' + DETAIL_ID, { waitUntil: 'domcontentloaded' }); + await pause(2500); + await expandAll(page); + await scrollTo(page, 0); + await pause(1500); + }, + }, + { + label: '详情-风险评分', + narration: + '向下是风险评分明细。系统按多个维度的指标加权计算总分，并标注每项数据的来源——是用户输入、智能体假设，还是外部数据，保证评分过程完全可解释。', + run: async ({ page, pause }) => { + await scrollTo(page, 620); + await pause(2600); + }, + }, + { + label: '详情-红线校验', + narration: + '红线校验区会列出命中的合规红线，例如派遣比例超标、低于最低工资等。需要人工核实的项，风控可以在这里直接裁定。', + run: async ({ page, pause }) => { + await scrollTo(page, 1240); + await pause(2600); + }, + }, + { + label: '详情-盈利分析', + narration: + '盈利分析区基于全口径成本——工资、社保、公积金、福利与各项摊销，测算月度与合同期的毛利、净利、税费与风险准备金，收入则按报价模式确定性计算。', + run: async ({ page, pause }) => { + await scrollTo(page, 1860); + await pause(2800); + }, + }, + { + label: '详情-现金流', + narration: + '现金流与垫资峰值，反映外包先垫付成本、账期后才收款的资金压力，帮助判断项目的现金占用与融资成本。', + run: async ({ page, pause }) => { + await scrollTo(page, 2480); + await pause(2600); + }, + }, + { + label: '详情-定价曲线', + narration: + '盈亏平衡与定价空间曲线，直观展示在不同报价水平下的净利率，给出安全的降价空间，为商务谈判提供依据。', + run: async ({ page, pause }) => { + await scrollTo(page, 3100); + await pause(2600); + }, + }, + { + label: '详情-审计时间线', + narration: + '页面底部是完整的操作时间线，记录从发起、风控审核到管理层审批的每一步，全程留痕，可供合规追溯。', + run: async ({ page, pause }) => { + await scrollTo(page, await page.evaluate(() => document.body.scrollHeight - 900)); + await pause(2600); + }, + }, + + // ---------------- 管理层视角 ---------------- + { + label: '管理层登录', + narration: + '再以管理层赵磊的身份登录。管理层负责终审，并维护费率、红线与客户档案等基础数据。', + run: async ({ page, pause }) => { + await page.goto('https://pm.hr8ai.top/', { waitUntil: 'domcontentloaded' }); + await pause(1500); + await login(page, '赵磊', PASS, pause); + }, + }, + { + label: '管理层看板', + narration: + '管理层看板提供组合分析：预测准确度对比预测与实际净利率，给出系统性偏差并支持一键校准；还有驳回原因排行、到期复评与审批超时提醒。', + run: async ({ page, pause }) => { + await scrollTo(page, 0); + await pause(2200); + await scrollTo(page, 420); + await pause(2200); + }, + }, + { + label: '费率管理', + narration: + '费率管理把社保、公积金、增值税等费率从代码中解放出来，按地域可配置、可复核、可版本化，盈利测算据此计算。', + run: async ({ page, pause }) => { + await nav(page, '费率管理', pause); + await pause(1800); + }, + }, + { + label: '红线管理', + narration: + '红线管理是可配置的合规规则库，可以按地域和业务类型启用规则、绑定度量与阈值，让红线在评估时自动判定命中。', + run: async ({ page, pause }) => { + await nav(page, '红线管理', pause); + await pause(1800); + }, + }, + { + label: '客户档案', + narration: + '客户档案维护客户的信用评级、逾期与集中度。集中度过高会自动预警，信用评级则联动坏账准备金的计提比例。', + run: async ({ page, pause }) => { + await nav(page, '客户档案', pause); + await pause(1800); + await scrollTo(page, 360); + await pause(1500); + }, + }, + + // ---------------- 系统管理员视角 ---------------- + { + label: '管理员登录', + narration: + '最后以系统管理员周强的身份登录，负责用户、审批流程与系统日志的管理。', + run: async ({ page, pause }) => { + await page.goto('https://pm.hr8ai.top/', { waitUntil: 'domcontentloaded' }); + await pause(1500); + await login(page, '周强', ADMIN_PASS, pause); + }, + }, + { + label: '用户管理', + narration: + '用户管理可以新增、停用账号并分配角色。每个人都有稳定的用户编号，系统用它在各类记录中保持关联，界面再实时解析成姓名。', + run: async ({ page, pause }) => { + await page.goto('https://pm.hr8ai.top/users', { waitUntil: 'domcontentloaded' }).catch(() => {}); + await pause(2200); + }, + }, + { + label: '审批流程', + narration: + '审批流程页配置审批规则与审批线：哪些项目需要管理层终审、各角色的服务时限，以及销售归属的风控与管理层。', + run: async ({ page, pause }) => { + await nav(page, '审批流程', pause); + await pause(2000); + }, + }, + { + label: '日志管理', + narration: + '日志管理记录系统的全部操作——登录登出、申报审批、配置变更乃至报告导出，支持按操作人、角色、动作、方法、结果和时间范围多维筛选，满足审计追溯需求。', + run: async ({ page, pause }) => { + await nav(page, '日志管理', pause); + await pause(2200); + await scrollTo(page, 300); + await pause(1800); + }, + }, + ], +}; diff --git a/docs/外包项目分控系统介绍.mp4 b/docs/外包项目分控系统介绍.mp4 new file mode 100644 index 0000000..77e32e9 Binary files /dev/null and b/docs/外包项目分控系统介绍.mp4 differ