15 KiB
15 KiB
NeoZQYY 文档地图
本文档记录项目中所有文档资产的位置、类型和内容概要，方便快速定位。 归档规则见末尾「文档归档规则」章节；程序输出路径规范见
docs/deployment/EXPORT-PATHS.md。
一、根目录
| 文件 | 内容 |
|---|---|
README.md |
项目总览：模块表（含文档链接）、技术栈、快速开始命令 |
.env.template |
环境变量模板，列出所有可配置项及说明 |
二、项目级文档 docs/
2.1 文档中心首页
| 文件 | 内容 |
|---|---|
docs/README.md |
项目架构图、模块文档索引、技术栈速览、认证体系概览、四库架构、常用命令 |
2.2 数据库变更手册 docs/database/
业务库（zqyy_app）相关的 BD 手册。ETL 专属表级文档已迁移至 apps/etl/connectors/feiqiu/docs/database/（见 3.2 节）。
| 文件 | 记录内容 |
|---|---|
BD_Manual_auth_tables.md |
auth Schema 8 张认证表（users、roles、permissions、user_applications 等） |
BD_Manual_biz_tables.md |
biz Schema 核心业务表（coach_tasks、coach_task_history、notes、trigger_jobs、AI 表等） |
BD_Manual_auth_biz_schemas.md |
auth + biz Schema 创建 |
BD_Manual_fdw_etl_setup.md |
FDW 跨库访问配置（zqyy_app → etl_feiqiu） |
BD_Manual_app_schema_rls_views.md |
app Schema RLS 视图 |
BD_Manual_ai_tables.md |
AI 相关表（ai_chat_sessions、ai_chat_messages 等） |
BD_Manual_member_retention_clue.md |
会员留存线索表 |
README.md |
数据库文档目录说明 |
子目录：
| 目录 | 内容 |
|---|---|
ddl/ |
10 个 DDL 基线文件（含种子数据），覆盖 etl_feiqiu 六层 Schema（meta/ods/dwd/core/dws/app）+ zqyy_app 三个 Schema（auth/biz/public）+ FDW |
_archived/ |
已归档的历史变更文档（已废弃的表、已回滚的变更、已合并入 DDL 基线的迁移记录） |
2.3 审计记录 docs/audit/
项目变更的完整审计追踪体系。审计追溯链：Prompt 日志 ↔ Session 日志 ↔ 变更审计记录，通过 Prompt-ID 和 Session-ID 双向关联。
| 路径 | 内容 |
|---|---|
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 交互的输入输出 |
session_logs/ |
全量会话记录（按 YYYY-MM/DD/ 分层），含双索引（_session_index.json / _session_index_full.json）、每轮 execution 的完整 Markdown 记录、LLM 生成的操作摘要 |
2.4 数据契约 docs/contracts/
| 路径 | 内容 |
|---|---|
openapi/backend-api.json |
后端 API 的 OpenAPI 规范文件 |
data_dictionary/ |
数据字典（预留，待填充） |
schemas/ |
数据 Schema 定义（预留，待填充） |
2.5 部署文档 docs/deployment/
| 文件 | 内容 |
|---|---|
LAUNCH-CHECKLIST.md |
上线检查清单：环境配置、数据库迁移、服务启动、验证步骤 |
EXPORT-PATHS.md |
输出路径规范：环境变量映射表、目录结构、新增场景检查清单 |
2.6 产品需求 docs/prd/
| 路径 | 内容 |
|---|---|
小程序前后端.txt |
小程序前后端原始需求描述 |
PRD审阅-Q&A.md |
PRD 审阅问答记录（第一轮） |
PRD审阅-Q&A-R2.md |
PRD 审阅问答记录（第二轮） |
SPI 消费力指数.md |
消费力指数（SPI）算法需求说明 |
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) |
2.7 小程序 UI 原型 docs/h5_ui/
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) |
css/ |
6 个样式文件 |
js/ |
8 个交互脚本 |
img/ |
图片资源 |
2.8 小程序前端开发指南 docs/miniprogram-dev/
微信小程序前端页面开发与 H5 原型迁移的统一文档中心。覆盖批量自动迁移、用户指定半自动开发、新页面从零开发三种模式。
| 路径 | 内容 |
|---|---|
README.md |
入口索引：快速导航、目录结构、Power 依赖、关联资源 |
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 |
收敛模式 + 不可消除差异白名单 |
2.9 参考资料 docs/reference/
| 文件 | 内容 |
|---|---|
bailian-agent-guide.md |
百炼 Agent 集成参考指南（由 v1 + v2 合并） |
bailian-dashscope-api.md |
百炼 DashScope API 参考 |
2.10 数据分析报告 docs/reports/
一次性数据分析、调研产出的报告文档。与 prd/specs/ 的区别：specs 是需求规格，reports 是基于数据的分析结论。
| 文件 | 内容 |
|---|---|
complex-orders-analysis.md |
复杂订单结构分析（ODS 全量扫描，关联键与复杂度定义） |
dwd-amount-duration-calibration.md |
DWD 层金额·绩效·时长字段口径全景（置信度与存疑项标注） |
2.11 架构文档 docs/architecture/
| 文件 | 内容 |
|---|---|
etl-feiqiu-architecture.md |
ETL Connector 整体架构说明（数据流、DWS/INDEX 任务、调度编排、CLI） |
2.12 其他项目级文档目录
| 路径 | 内容 |
|---|---|
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/permission_matrix/ |
权限矩阵（预留，待填充） |
docs/spec-input/2026-02-22__etl-aggregation-fix-spec-input.md |
ETL 聚合修复的 Spec 输入文档 |
三、模块内部文档
3.1 FastAPI 后端 apps/backend/
| 文件 | 内容 |
|---|---|
README.md |
架构概览、双库连接、认证系统、17 个路由模块摘要、服务层、配置加载、触发器系统 |
docs/API-REFERENCE.md |
完整 API 参考：17 个路由模块的所有端点、请求/响应示例、认证要求、错误码 |
3.2 ETL Connector apps/etl/connectors/feiqiu/
| 路径 | 内容 |
|---|---|
README.md |
Connector 总览、快速开始、CLI 用法 |
docs/README.md |
文档目录索引 |
docs/CHANGELOG.md |
变更日志 |
docs/api-reference/ |
上游飞球 API 接口文档（字段映射、请求参数、响应结构） |
docs/architecture/ |
架构设计文档（数据流、分层设计、SCD 策略） |
docs/business-rules/ |
业务规则文档（金额精度、时区处理、去重逻辑） |
docs/database/ |
ETL 数据库文档：按 Schema 层分目录（ODS/DWD/DWS/ETL_Admin），含表结构、索引策略、跨层映射（cross_layer）、变更记录 |
docs/etl_tasks/ |
ETL 任务文档（每个任务的输入输出、依赖、调度配置） |
docs/operations/ |
运维文档（监控、告警、故障排查） |
docs/requirements/ |
需求文档（功能需求、非功能需求） |
3.3 微信小程序 apps/miniprogram/
| 文件 | 内容 |
|---|---|
README.md |
后端 API 集成、认证流程（含开发模式）、权限模型、关键端点说明 |
doc/auth-integration-guide.md |
认证集成详细指南 |
3.4 管理后台 apps/admin-web/
| 文件 | 内容 |
|---|---|
README.md |
8 个页面、组件体系（含营业日提示）、API 层、状态管理、开发指南 |
3.5 MCP Server apps/mcp-server/
| 文件 | 内容 |
|---|---|
README.md |
MCP Server 功能说明、工具列表、配置方式 |
3.6 共享包 packages/shared/
| 文件 | 内容 |
|---|---|
README.md |
4 个模块（enums / money / datetime_utils / 其他工具）的 API 文档及用法示例 |
四、数据库目录 db/
| 路径 | 内容 |
|---|---|
README.md |
数据库目录总览、四库架构说明 |
zqyy_app/README.md |
业务库文档：auth Schema 8 张表字段说明、迁移顺序、FDW 跨库访问 |
zqyy_app/migrations/ |
业务库迁移脚本（已合并入 DDL 基线，目录保留 .gitkeep） |
etl_feiqiu/README.md |
ETL 库文档：六层 Schema 说明、表清单 |
etl_feiqiu/migrations/ |
ETL 库迁移脚本（已合并入 DDL 基线，目录保留 .gitkeep） |
fdw/ |
FDW（Foreign Data Wrapper）跨库访问配置脚本（4 个，运行时资产） |
scripts/ |
数据库运维脚本 |
_archived/ |
已归档的历史数据库文件 |
五、Kiro 配置 .kiro/
5.1 Steering 文件（.kiro/steering/）
13 个 Steering 文件，控制 AI 助手的行为规范：
| 文件 | 作用 |
|---|---|
language-zh.md |
语言规范：输出简体中文，代码标识符保留英文 |
governance.md |
治理规范：审计触发条件、执行方式、产物要求 |
product.md / product-full.md |
产品概述（精简版 / 完整版） |
tech.md / tech-full.md |
技术栈与构建（精简版 / 完整版） |
structure-lite.md / structure.md |
项目结构（精简版 / 完整版） |
export-paths.md / export-paths-full.md |
输出路径规范（精简版 / 完整版） |
testing-env.md |
测试环境规范：环境变量加载、cwd 要求、测试库使用 |
db-docs.md |
数据库文档规范 |
steering-readme-maintainer.md |
README 维护者技能：变更影响审查与文档同步 |
5.2 Spec 文件（.kiro/specs/）
17 个 Spec 目录，每个包含 requirements.md、design.md、tasks.md 三件套：
| Spec | 内容 |
|---|---|
01-miniapp-db-foundation |
P1：小程序数据库基础建设 |
02-etl-dws-miniapp-extensions |
P2：ETL DWS 小程序扩展 |
03-miniapp-auth-system |
P3：小程序认证系统 |
[ETL]-fullstack-integration |
ETL 全栈集成 |
miniapp-core-business |
小程序核心业务 |
miniapp-db-foundation |
小程序数据库基础（早期版本） |
admin-web-console |
管理后台控制台 |
etl-aggregation-fix |
ETL 聚合修复 |
etl-dws-flow-refactor |
ETL DWS 流程重构 |
etl-pipeline-debug |
ETL 管道调试 |
etl-staff-dimension |
ETL 员工维度 |
dwd-phase1-refactor |
DWD 第一阶段重构 |
ods-dedup-standardize |
ODS 去重标准化 |
spi-spending-power-index |
SPI 消费力指数 |
dataflow-field-completion |
数据流字段补全 |
dataflow-structure-audit |
数据流结构审计 |
assistant-abolish-cleanup |
助教废除清理 |
六、文档归档规则
新建文档时，按以下规则选择目标目录。禁止在 docs/ 根目录散放文件（README.md 和 DOCUMENTATION-MAP.md 除外）。
| 文档类型 | 目标目录 | 说明 |
|---|---|---|
| 数据分析报告、调研产出 | reports/ |
一次性分析结论，带"生成时间/数据来源"标记 |
| 架构设计文档 | architecture/ |
系统/模块架构图与说明 |
| 数据库变更审计 | database/ |
BD_Manual_*.md 格式，含回滚与验证 SQL |
| 变更审计记录 | audit/changes/ |
YYYY-MM-DD__<slug>.md 格式 |
| 产品需求规格 | prd/specs/ |
P1-P11 等需求 spec，不放分析报告 |
| 数据契约 | contracts/ |
OpenAPI spec、JSON Schema、数据字典 |
| 部署与运维配置 | deployment/ |
启动清单、路径规范、安全指南 |
| 路线图与规划 | roadmap/ |
迁移计划、BACKLOG |
| Spec 需求输入 | spec-input/ |
问题汇总，供开启 Spec 流程 |
| 外部参考资料 | reference/ |
第三方 API/SDK 指南 |
| 迁移记录 | migrate/ |
仓库迁移总结、配置迁移记录 |
| MCP 相关 | mcp/ |
AI 工具集成文档 |
| UI 原型 | h5_ui/ |
H5 静态原型页面 |
| 小程序前端开发指南 | miniprogram-dev/ |
页面开发流程、代理手册、规范参考、进度审计、经验教训 |
| 运维手册 | ops/ |
故障排查、日常运维流程 |
| 权限矩阵 | permission_matrix/ |
角色-资源权限映射 |
判断流程
- 是模块专属文档？→ 放模块内部
docs/（如apps/etl/.../docs/） - 是审计产物？→ 统一写
docs/audit/，禁止写入子模块 - 按上表匹配文档类型 → 放对应子目录
- 都不匹配？→ 先在上表新增分类，再创建子目录
本规则由
.kiro/steering/export-paths.md强制执行。