feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

This commit is contained in:
Neo
2026-03-20 01:43:48 +08:00
parent 075caf067f
commit 79f9a0e1da
437 changed files with 118603 additions and 976 deletions

View File

@@ -2,6 +2,7 @@
> 本文档记录项目中所有文档资产的位置、类型和内容概要,方便快速定位。
> 归档规则见末尾「文档归档规则」章节;程序输出路径规范见 `docs/deployment/EXPORT-PATHS.md`。
> 最后更新2026-03-19RNS1.3 三看板接口文档补充)
---
@@ -53,8 +54,9 @@
| `audit_dashboard.md` | 审计仪表盘,汇总所有变更审计记录 |
| `README.md` | 审计目录说明 |
| `SESSION-LOG-GUIDE.md` | Session 日志使用指南:索引字段说明、查询方法、典型场景、与其他审计产物的关系 |
| `changes/` | 39 份变更审计文档(`YYYY-MM-DD__<slug>.md` 格式),每份包含:变更原因、影响范围、回滚策略、验证 SQL |
| `prompt_logs/` | ~500 份 Prompt 日志(`prompt_log_YYYYMMDD_HHMMSS.md`),记录每次 AI 交互的输入输出 |
| `AUDIT-HOOKS-GUIDE.md` | 审计 Hooks 使用指南Hook 触发机制、配置方式、与审计流程的集成 |
| `changes/` | 56 份变更审计文档(`YYYY-MM-DD__<slug>.md` 格式),每份包含:变更原因、影响范围、回滚策略、验证 SQL |
| `prompt_logs/` | Prompt 日志(`prompt_log_YYYYMMDD_HHMMSS.md`),记录每次 AI 交互的输入输出 |
| `session_logs/` | 全量会话记录(按 `YYYY-MM/DD/` 分层),含双索引(`_session_index.json` / `_session_index_full.json`)、每轮 execution 的完整 Markdown 记录、LLM 生成的操作摘要 |
### 2.4 数据契约 `docs/contracts/`
@@ -70,19 +72,26 @@
| 文件 | 内容 |
|------|------|
| `LAUNCH-CHECKLIST.md` | 上线检查清单:环境配置、数据库迁移、服务启动、验证步骤 |
| `launch-checklist-patch.md` | 上线检查清单补丁 |
| `EXPORT-PATHS.md` | 输出路径规范:环境变量映射表、目录结构、新增场景检查清单 |
| `PRIVACY-POLICY.md` | 隐私政策文档 |
| `wx-api-security-guide.md` | 微信 API 安全指南 |
| `wx-encrypt-guide.md` | 微信加密指南 |
### 2.6 产品需求 `docs/prd/`
| 路径 | 内容 |
|------|------|
| `小程序前后端.txt` | 小程序前后端原始需求描述 |
| `后端接口需求说明_数据需求PRD.md` | 后端接口需求说明与数据需求 PRD |
| `PRD审阅-Q&A.md` | PRD 审阅问答记录(第一轮) |
| `PRD审阅-Q&A-R2.md` | PRD 审阅问答记录(第二轮) |
| `SPI 消费力指数.md` | 消费力指数SPI算法需求说明 |
| `ai-app-prompts.md` | AI 应用 Prompt 设计 |
| `AI需求2.md` | AI 需求第二版 |
| `specs/00-数据依赖矩阵.md` | 各 SPEC 间的数据依赖关系矩阵 |
| `specs/01-SPEC任务拆分总览.md` | 11 个 SPEC 的任务拆分总览 |
| `specs/P1~P11` | 11 份 SPEC 拆分文档,覆盖:数据库基础(P1)、ETL DWS 扩展(P2)、认证系统(P3)、核心业务(P4)、AI 集成(P5)、前端任务/绩效/看板/详情(P6-P9)、租户管理后台(P10)、部署上线(P11) |
| `specs/P1~P11` | 15 份 SPEC 拆分文档,覆盖:数据库基础(P1)、ETL DWS 扩展(P2)、认证系统(P3)、核心业务(P4)、AI 集成(P5/P5.1/P5.2)、前端任务/绩效/看板/详情(P6-P9)、租户管理后台(P10)、部署上线(P11) |
### 2.7 小程序 UI 原型 `docs/h5_ui/`
@@ -91,40 +100,32 @@ H5 静态原型页面,用于小程序 UI 设计参考。
| 路径 | 内容 |
|------|------|
| `index.html` | 原型首页入口 |
| `pages/` | 23 个页面原型,包括:登录(`login`)、申请(`apply`)、审核中(`reviewing`)、无权限(`no-permission`)、任务列表/详情(`task-list`/`task-detail`)、绩效(`performance`/`performance-records`)、助教详情(`coach-detail`)、客户详情(`customer-detail`)、客户服务记录(`customer-service-records`)、看板(`board-coach`/`board-customer`/`board-finance`)、聊天(`chat`/`chat-history`)、个人中心(`my-profile`)、首页设置(`home-settings`)、笔记(`notes`)、AI 图标演示(`ai-icon-demo`) |
| `pages/` | 23+ 个页面原型,包括:登录(`login`)、申请(`apply`)、审核中(`reviewing`)、无权限(`no-permission`)、任务列表/详情(`task-list`/`task-detail`/`task-detail-callback`/`task-detail-priority`/`task-detail-relationship`)、绩效(`performance`/`performance-records`)、助教详情(`coach-detail`)、客户详情(`customer-detail`)、客户服务记录(`customer-service-records`)、看板(`board-coach`/`board-customer`/`board-finance`)、聊天(`chat`/`chat-history`)、个人中心(`my-profile`)、笔记(`notes`) |
| `pages/_baked/` | 已烘焙(固化)的页面快照 |
| `css/` | 6 个样式文件 |
| `js/` | 8 个交互脚本 |
| `img/` | 图片资源 |
| `tools/` | H5 转小程序检查工具(`h5-to-mp-checker/` |
### 2.8 小程序前端开发指南 `docs/miniprogram-dev/`
微信小程序前端页面开发与 H5 原型迁移的统一文档中心。覆盖批量自动迁移、用户指定半自动开发、新页面从零开发三种模式。
微信小程序前端页面开发与 H5 原型迁移的统一文档中心。
| 路径 | 内容 |
|------|------|
| `README.md` | 入口索引:快速导航、目录结构、Power 依赖、关联资源 |
| `README.md` | 入口索引:快速导航、目录结构、关联资源 |
| `QUICK-REFERENCE.md` | 快速参考手册 |
| `API-contract.md` | API 契约文档 |
| `API-OUTPUT-SPEC.md` | 后端接口输出规范DS-API-OUTPUT-001字段类型约定 / 枚举值 / 各页面接口字段对照表 |
| `API-requirement.md` | API 需求文档 |
| `design-system/VI-DESIGN-SYSTEM.md` | VI 设计系统:任务/客户/等级配色、AI 图标、CSS 变量速查 |
| `design-system/DATETIME-DISPLAY-STANDARD.md` | 日期时间展示规范:由近及远 6 级展示规则、边界处理、JS 实现参考 |
| `design-system/DISPLAY-STANDARDS.md` | 前端展示规范第1-6章金额 / 课时 / 计数 / 空值 / 百分比 / 等级文案 |
| `design-system/DISPLAY-STANDARDS-2.md` | 前端展示规范第7-9章截止日期 / 评分星级 / Mock 数据规范 + 工具函数总表 |
| `API-OUTPUT-SPEC.md` | 后端接口输出规范DS-API-OUTPUT-001字段类型约定 / 枚举值 / 各页面接口字段对照表 |
| `01-orchestration/batch-auto-playbook.md` | 批量自动模式89 单元编排 + 4 代理流水线 |
| `01-orchestration/user-guided-playbook.md` | 半自动模式:对话触发 + 按需执行 |
| `01-orchestration/new-page-playbook.md` | 新页面开发:有原型 / 无原型两条路径 |
| `02-action/screenshot-agent.md` | 截图代理H5/MP 双端截图执行手册 |
| `02-action/audit-agent.md` | 审计代理:结构化审计执行手册 |
| `02-action/fix-agent.md` | 修正代理P0-P7 分级修正执行手册 |
| `02-action/verify-agent.md` | 验证代理:回归校验执行手册 |
| `02-action/page-dev-agent.md` | 页面开发代理:新页面完整开发执行手册 |
| `03-reference/wxss-rules.md` | WXSS 规范 + rpx 换算 + 颜色/字号/圆角标准值 |
| `03-reference/page-structure-map.md` | 各页面特殊结构速查 |
| `03-reference/css-risk-features.md` | CSS 风险特性 + 替代方案 |
| `03-reference/power-integration.md` | Power 集成指南4 个 Power 的调用方式) |
| `03-reference/benchmark-history.md` | 基准测试历史记录 |
| `04-audit/PROGRESS.md` | 89 单元进度跟踪(实时更新) |
| `04-audit/CHANGELOG.md` | 文档体系版本变更记录 |
| `05-lessons/pitfalls.md` | 踩坑速查 + 页面迁移经验 |
| `05-lessons/convergence-patterns.md` | 收敛模式 + 不可消除差异白名单 |
| `design-system/vi-guide.html` | VI 设计系统可视化指南HTML |
| `api-audit/` | 19 个页面的 API 审计文档(每页一份 `.md`),含硬编码汇总(`_hardcode-summary.md` |
| `h5-migration/` | H5 转小程序迁移指南:桥接文档(`h5-to-mp-bridge.md`)、附录(`appendix/` |
| `API-requirement/` | API 需求子目录(预留) |
### 2.9 参考资料 `docs/reference/`
@@ -137,10 +138,15 @@ H5 静态原型页面,用于小程序 UI 设计参考。
一次性数据分析、调研产出的报告文档。与 `prd/specs/` 的区别specs 是需求规格reports 是基于数据的分析结论。
| 文件 | 内容 |
| 路径 | 内容 |
|------|------|
| `complex-orders-analysis.md` | 复杂订单结构分析ODS 全量扫描,关联键与复杂度定义) |
| `dwd-amount-duration-calibration.md` | DWD 层金额·绩效·时长字段口径全景(置信度与存疑项标注) |
| `DWD-DOC/` | **权威标杆文档**(业务模型与财务数据权威数据源):消费链路全景(01)、支付渠道与对账公式(02)、收入构成与储值卡资金流(03)、维度表全景(04)、F2 收支平衡公式(05)、校准清单(06)、GAP 闭环状态(07)、consume_money 口径时间线(`consume/`) |
| `business-analysis/` | 业务分析报告:每日营收报告(`daily-revenue-latest.md`)、高价值充值客户分析(`high-value-recharge-customer-analysis.md`) |
| `etl-calibration/` | ETL 校准报告DWS BD 手册校准(2026-03-07)、DWS 代码校准(2026-03-07)、财务看板 DWS 审计(2026-03-07) |
| `h5-mp-conversion/` | H5 转小程序报告:财务看板审计(`board-finance-h5-mp-audit.md`)、H5 UI 提取(`h5-ui-extraction.md`) |
| `p4-task/` | P4 任务报告Spec 与实现差距分析、任务生命周期全景 |
| `tech-solution/` | 技术方案:百炼技术方案(`bailian-technical-solution.md`) |
| `vi-color-audit/` | VI 配色审计:详细审计(Phase2)、完成报告、实施文档、合规审计 |
### 2.11 架构文档 `docs/architecture/`
@@ -148,20 +154,26 @@ H5 静态原型页面,用于小程序 UI 设计参考。
|------|------|
| `etl-feiqiu-architecture.md` | ETL Connector 整体架构说明数据流、DWS/INDEX 任务、调度编排、CLI |
### 2.12 其他项目级文档目录
### 2.12 MCP 文档 `docs/mcp/`
| 文件 | 内容 |
|------|------|
| `AI-DATABASE-QUERY-MANUAL.md` | AI 数据库查询手册 |
| `WEIXIN-DEVTOOLS-MCP.md` | 微信开发者工具 MCP 集成文档 |
### 2.13 其他项目级文档目录
| 路径 | 内容 |
|------|------|
| `docs/architecture/` | 架构文档(预留,待填充) |
| `docs/roadmap/BACKLOG.md` | 项目待办事项 |
| `docs/roadmap/2026-02-24__fdw-dwd-to-core-migration-plan.md` | FDW + DWD→Core 迁移计划 |
| `docs/migrate/monorepo-migration-summary.md` | Monorepo 迁移总结 |
| `docs/migrate/oldworkspace-kiro-agent-config-summary.md` | 旧工作区 Kiro 配置迁移记录 |
| `docs/ops/` | 运维文档(预留,待填充) |
| `docs/ops/init-test-user.md` | 测试用户初始化指南 |
| `docs/permission_matrix/` | 权限矩阵(预留,待填充) |
| `docs/vi-standards/` | VI 设计标准(预留,待填充) |
| `docs/spec-input/2026-02-22__etl-aggregation-fix-spec-input.md` | ETL 聚合修复的 Spec 输入文档 |
---
## 三、模块内部文档
@@ -173,6 +185,38 @@ H5 静态原型页面,用于小程序 UI 设计参考。
| `README.md` | 架构概览、双库连接、认证系统、17 个路由模块摘要、服务层、配置加载、触发器系统 |
| `docs/API-REFERENCE.md` | 完整 API 参考17 个路由模块的所有端点、请求/响应示例、认证要求、错误码 |
RNS1.2 新增模块(客户与助教接口):
| 路径 | 内容 |
|------|------|
| `app/routers/xcx_customers.py` | 客户端点CUST-1 客户详情、CUST-2 客户服务记录 |
| `app/routers/xcx_coaches.py` | 助教端点COACH-1 助教详情 |
| `app/services/customer_service.py` | 客户查询服务Banner 概览、AI 洞察、消费记录嵌套、coachTasks、favoriteCoaches |
| `app/services/coach_service.py` | 助教查询服务绩效、收入、任务分组、TOP 客户、历史月份 |
| `app/schemas/xcx_customers.py` | 客户相关 Pydantic SchemaCustomerDetailResponse、CustomerRecordsResponse 等) |
| `app/schemas/xcx_coaches.py` | 助教相关 Pydantic SchemaCoachDetailResponse 等) |
| `tests/unit/test_degradation_rns12.py` | RNS1.2 优雅降级单元测试 |
| `tests/unit/test_auth_rns12.py` | RNS1.2 权限校验单元测试 |
| `tests/integration/test_e2e_customer_coach.py` | CUST-1/CUST-2/COACH-1 端到端集成测试 |
RNS1.3 新增模块(三看板接口):
| 路径 | 内容 |
|------|------|
| `app/routers/xcx_board.py` | 看板端点BOARD-1 助教看板、BOARD-2 客户看板、BOARD-3 财务看板 |
| `app/routers/xcx_config.py` | 配置端点CONFIG-1 技能类型 |
| `app/services/board_service.py` | 看板编排服务:日期范围/环比/排序/分页/降级 |
| `app/schemas/xcx_board.py` | 看板相关 Pydantic Schema7 枚举 + ~40 响应 Schema |
| `app/schemas/xcx_config.py` | 配置相关 Pydantic SchemaSkillTypeItem |
Monorepo 级属性测试(`tests/`
| 路径 | 内容 |
|------|------|
| `tests/test_rns12_properties.py` | RNS1.2 属性测试14 个 PropertyHypothesis 框架) |
| `tests/test_board_properties.py` | RNS1.3 属性测试18 个测试函数12 个 PropertyHypothesis 框架) |
| `tests/test_board_service_unit.py` | RNS1.3 看板工具函数单元测试 |
### 3.2 ETL Connector `apps/etl/connectors/feiqiu/`
| 路径 | 内容 |
@@ -234,44 +278,111 @@ H5 静态原型页面,用于小程序 UI 设计参考。
### 5.1 Steering 文件(`.kiro/steering/`
13 个 Steering 文件,控制 AI 助手的行为规范:
17 个 Steering 文件,控制 AI 助手的行为规范:
| 文件 | 作用 |
|------|------|
| `language-zh.md` | 语言规范:输出简体中文,代码标识符保留英文 |
| `governance.md` | 治理规范:审计触发条件、执行方式、产物要求 |
| `product.md` / `product-full.md` | 产品概述(精简版 / 完整版) |
| `agent-behavior.md` | AI 执行行为约束:上下文保护、子代理委托场景 |
| `planning-interrogation.md` | 编码前需求审问:必问清单、追问规则 |
| `pre-change-research.md` | 逻辑改动前置调研子代理调研流程、Session 索引查询 |
| `project-overview.md` | 项目概览(精简版) |
| `product-full.md` | 产品概述完整版fileMatch 自动加载) |
| `tech.md` / `tech-full.md` | 技术栈与构建(精简版 / 完整版) |
| `structure-lite.md` / `structure.md` | 项目结构(精简版 / 完整版 |
| `structure.md` | 项目结构完整版fileMatch 自动加载 |
| `export-paths.md` / `export-paths-full.md` | 输出路径规范(精简版 / 完整版) |
| `testing-env.md` | 测试环境规范环境变量加载、cwd 要求、测试库使用 |
| `db-docs.md` | 数据库文档规范 |
| `doc-map.md` | 文档地图 SteeringfileMatch 触发) |
| `deprecated-objects.md` | 归档目录与废弃对象规则 |
| `dwd-doc-authority.md` | DWD-DOC 标杆文档权威性声明 |
| `steering-readme-maintainer.md` | README 维护者技能:变更影响审查与文档同步 |
### 5.2 Spec 文件`.kiro/specs/`
### 5.2 Hooks`.kiro/hooks/`
17Spec 目录,每个包含 `requirements.md``design.md``tasks.md` 三件套
11Agent Hook自动化审计与流程控制
| Hook | 触发事件 | 作用 |
|------|----------|------|
| `agent-on-stop` | agentStop | Agent 停止时触发审计流程 |
| `prompt-on-submit` | promptSubmit | Prompt 提交时触发合规预扫描 |
| `pre-change-guard` | preToolUse | 写操作前的变更守卫 |
| `cwd-guard-shell` | preToolUse | Shell 命令 cwd 守卫 |
| `run-audit-writer` | userTriggered | 手动触发审计写入 |
| `session-summary` | agentStop | Session 摘要生成 |
| `etl-fullstack-integration` | postTaskExecution | ETL 全栈集成任务后处理 |
| `etl-unified-analysis` | userTriggered | ETL 统一分析 |
| `field-disappearance-scan` | userTriggered | 字段消失扫描 |
| `h5-screenshot` | userTriggered | H5 截图 |
| `daily-revenue-report` | userTriggered | 每日营收报告 |
### 5.3 Skills`.kiro/skills/`
3 个技能模块:
| 技能 | 作用 |
|------|------|
| `bd-manual-db-docs` | PostgreSQL schema 变更时落盘 BD 手册到 `docs/database/` |
| `change-annotation-audit` | 每次修改生成审计记录、AI_CHANGELOG、CHANGE 标记注释 |
| `steering-readme-maintainer` | 变更影响审查并同步更新 README 与审计记录 |
### 5.4 Agents`.kiro/agents/`
| Agent | 作用 |
|-------|------|
| `audit-writer.md` | 变更后审计 + 文档同步,输出审计产物 |
### 5.5 Scripts`.kiro/scripts/`
11 个自动化脚本,支撑 Hooks 和审计流程:
| 脚本 | 作用 |
|------|------|
| `agent_on_stop.py` | Agent 停止时的审计处理 |
| `prompt_on_submit.py` | Prompt 提交时的合规预扫描 |
| `audit_flagger.py` | 审计标记器 |
| `audit_reminder.py` | 审计提醒器 |
| `build_audit_context.py` | 构建审计上下文 |
| `change_compliance_prescan.py` | 变更合规预扫描 |
| `file_baseline.py` | 文件基线管理 |
| `prompt_audit_log.py` | Prompt 审计日志 |
| `session_log.py` | Session 日志管理 |
| `_ensure_root.py` | 确保根目录工具 |
### 5.6 Spec 文件(`.kiro/specs/`
24 个 Spec 目录,每个包含 `requirements.md``design.md``tasks.md` 三件套:
| Spec | 内容 |
|------|------|
| `01-miniapp-db-foundation` | P1小程序数据库基础建设 |
| `02-etl-dws-miniapp-extensions` | P2ETL DWS 小程序扩展 |
| `03-miniapp-auth-system` | P3小程序认证系统 |
| `04-miniapp-core-business` | P4小程序核心业务 |
| `05-miniapp-ai-integration` | P5小程序 AI 集成 |
| `[ETL]-fullstack-integration` | ETL 全栈集成 |
| `miniapp-core-business` | 小程序核心业务 |
| `miniapp-db-foundation` | 小程序数据库基础(早期版本) |
| `admin-web-console` | 管理后台控制台 |
| `etl-aggregation-fix` | ETL 聚合修复 |
| `assistant-abolish-cleanup` | 助教废除清理 |
| `business-day-cutoff` | 营业日截止逻辑 |
| `dataflow-field-completion` | 数据流字段补全 |
| `dataflow-structure-audit` | 数据流结构审计 |
| `dwd-business-panorama` | DWD 业务全景 |
| `dwd-phase1-refactor` | DWD 第一阶段重构 |
| `etl-coupon-detail` | ETL 优惠券明细 |
| `etl-dws-flow-refactor` | ETL DWS 流程重构 |
| `etl-pipeline-debug` | ETL 管道调试 |
| `etl-staff-dimension` | ETL 员工维度 |
| `dwd-phase1-refactor` | DWD 第一阶段重构 |
| `etl-unified-pipeline` | ETL 统一管道 |
| `h5-miniprogram-migration` | H5 转小程序迁移 |
| `h5-miniprogram-migration-subsequent` | H5 转小程序迁移(后续) |
| `ods-dedup-standardize` | ODS 去重标准化 |
| `p4-prerequisite-fixes` | P4 前置修复 |
| `p52-miniapp-fe-all-pages` | P5.2 小程序前端全页面 |
| `rns1-infra-contract-rewrite` | RNS1.0 基础设施与契约重写响应包装、CamelModel、路由修正、API 契约) |
| `rns1-task-performance-api` | RNS1.1 任务与绩效接口TASK-1 扩展、TASK-2、PERF-1、PERF-2、前端适配 |
| `rns1-customer-coach-api` | RNS1.2 客户与助教接口CUST-1 客户详情、CUST-2 客户服务记录、COACH-1 助教详情) |
| `rns1-board-apis` | RNS1.3 三看板接口BOARD-1 助教看板、BOARD-2 客户看板、BOARD-3 财务看板、CONFIG-1 技能类型) |
| `spi-spending-power-index` | SPI 消费力指数 |
| `dataflow-field-completion` | 数据流字段补全 |
| `dataflow-structure-audit` | 数据流结构审计 |
| `assistant-abolish-cleanup` | 助教废除清理 |
---
@@ -287,16 +398,17 @@ H5 静态原型页面,用于小程序 UI 设计参考。
| 变更审计记录 | `audit/changes/` | `YYYY-MM-DD__<slug>.md` 格式 |
| 产品需求规格 | `prd/specs/` | P1-P11 等需求 spec不放分析报告 |
| 数据契约 | `contracts/` | OpenAPI spec、JSON Schema、数据字典 |
| 部署与运维配置 | `deployment/` | 启动清单、路径规范、安全指南 |
| 部署与运维配置 | `deployment/` | 启动清单、路径规范、安全指南、隐私政策 |
| 路线图与规划 | `roadmap/` | 迁移计划、BACKLOG |
| Spec 需求输入 | `spec-input/` | 问题汇总,供开启 Spec 流程 |
| 外部参考资料 | `reference/` | 第三方 API/SDK 指南 |
| 迁移记录 | `migrate/` | 仓库迁移总结、配置迁移记录 |
| MCP 相关 | `mcp/` | AI 工具集成文档 |
| UI 原型 | `h5_ui/` | H5 静态原型页面 |
| 小程序前端开发指南 | `miniprogram-dev/` | 页面开发流程、代理手册、规范参考、进度审计、经验教训 |
| 运维手册 | `ops/` | 故障排查、日常运维流程 |
| 小程序前端开发指南 | `miniprogram-dev/` | 页面开发流程、API 审计、设计系统、H5 迁移指南 |
| 运维手册 | `ops/` | 故障排查、日常运维流程、测试用户初始化 |
| 权限矩阵 | `permission_matrix/` | 角色-资源权限映射 |
| VI 设计标准 | `vi-standards/` | 视觉识别设计标准 |
### 判断流程