436 lines
23 KiB
Markdown
436 lines
23 KiB
Markdown
# NeoZQYY 文档地图
|
||
|
||
> 本文档记录项目中所有文档资产的位置、类型和内容概要，方便快速定位。
|
||
> 归档规则见末尾「文档归档规则」章节；程序输出路径规范见 `docs/deployment/EXPORT-PATHS.md`。
|
||
> 最后更新：2026-03-20（RNS1.4 CHAT 模块重建 + FDW→直连统一 + R3 筛选修复 审计收口）
|
||
|
||
---
|
||
|
||
## 一、根目录
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `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 日志使用指南：索引字段说明、查询方法、典型场景、与其他审计产物的关系 |
|
||
| `AUDIT-HOOKS-GUIDE.md` | 审计 Hooks 使用指南：Hook 触发机制、配置方式、与审计流程的集成 |
|
||
| `changes/` | 67 份变更审计文档（`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/`
|
||
|
||
| 路径 | 内容 |
|
||
|------|------|
|
||
| `openapi/backend-api.json` | 后端 API 的 OpenAPI 规范文件 |
|
||
| `data_dictionary/` | 数据字典（预留，待填充） |
|
||
| `schemas/` | 数据 Schema 定义（预留，待填充） |
|
||
|
||
### 2.5 部署文档 `docs/deployment/`
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `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` | 15 份 SPEC 拆分文档，覆盖：数据库基础(P1)、ETL DWS 扩展(P2)、认证系统(P3)、核心业务(P4)、AI 集成(P5/P5.1/P5.2)、前端任务/绩效/看板/详情(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`/`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 原型迁移的统一文档中心。
|
||
|
||
| 路径 | 内容 |
|
||
|------|------|
|
||
| `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 数据规范 + 工具函数总表 |
|
||
| `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/`
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `bailian-agent-guide.md` | 百炼 Agent 集成参考指南（由 v1 + v2 合并） |
|
||
| `bailian-dashscope-api.md` | 百炼 DashScope API 参考 |
|
||
|
||
### 2.10 数据分析报告 `docs/reports/`
|
||
|
||
一次性数据分析、调研产出的报告文档。与 `prd/specs/` 的区别：specs 是需求规格，reports 是基于数据的分析结论。
|
||
|
||
| 路径 | 内容 |
|
||
|------|------|
|
||
| `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/`
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `etl-feiqiu-architecture.md` | ETL Connector 整体架构说明（数据流、DWS/INDEX 任务、调度编排、CLI） |
|
||
|
||
### 2.12 MCP 文档 `docs/mcp/`
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `AI-DATABASE-QUERY-MANUAL.md` | AI 数据库查询手册 |
|
||
| `WEIXIN-DEVTOOLS-MCP.md` | 微信开发者工具 MCP 集成文档 |
|
||
|
||
### 2.13 其他项目级文档目录
|
||
|
||
| 路径 | 内容 |
|
||
|------|------|
|
||
| `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/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 输入文档 |
|
||
|
||
---
|
||
|
||
## 三、模块内部文档
|
||
|
||
### 3.1 FastAPI 后端 `apps/backend/`
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `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 Schema（CustomerDetailResponse、CustomerRecordsResponse 等） |
|
||
| `app/schemas/xcx_coaches.py` | 助教相关 Pydantic Schema（CoachDetailResponse 等） |
|
||
| `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 Schema（7 枚举 + ~40 响应 Schema） |
|
||
| `app/schemas/xcx_config.py` | 配置相关 Pydantic Schema（SkillTypeItem） |
|
||
|
||
RNS1.4 新增模块（CHAT 对齐与联调收尾）：
|
||
|
||
| 路径 | 内容 |
|
||
|------|------|
|
||
| `app/routers/xcx_chat.py` | CHAT 端点：CHAT-1 对话历史、CHAT-2a/2b 消息查询、CHAT-3 发送消息、CHAT-4 SSE 流式（替代原 `xcx_ai_chat.py`，路径从 `/api/ai/*` 迁移到 `/api/xcx/chat/*`） |
|
||
| `app/services/chat_service.py` | CHAT 业务逻辑：对话管理、消息持久化、对话复用规则、referenceCard 组装、标题生成 |
|
||
| `app/schemas/xcx_chat.py` | CHAT 相关 Pydantic Schema（ChatHistoryResponse、ChatMessagesResponse、ReferenceCard、SendMessageResponse、ChatStreamRequest 等） |
|
||
|
||
Monorepo 级属性测试（`tests/`）：
|
||
|
||
| 路径 | 内容 |
|
||
|------|------|
|
||
| `tests/test_rns12_properties.py` | RNS1.2 属性测试（14 个 Property，Hypothesis 框架） |
|
||
| `tests/test_board_properties.py` | RNS1.3 属性测试（18 个测试函数，12 个 Property，Hypothesis 框架） |
|
||
| `tests/test_board_service_unit.py` | RNS1.3 看板工具函数单元测试 |
|
||
| `tests/test_rns1_chat_title_properties.py` | RNS1.4 属性测试：标题生成优先级（Property 4，Hypothesis 框架） |
|
||
| `tests/test_rns1_chat_reuse_properties.py` | RNS1.4 属性测试：对话复用规则（Property 6） |
|
||
| `tests/test_rns1_chat_reference_card_properties.py` | RNS1.4 属性测试：referenceCard round trip（Property 7） |
|
||
| `tests/test_rns1_chat_persistence_properties.py` | RNS1.4 属性测试：消息持久化与会话元数据更新（Property 8） |
|
||
| `tests/test_rns1_chat_sse_properties.py` | RNS1.4 属性测试：SSE 事件类型有效性（Property 9） |
|
||
| `tests/test_rns1_chat_ordering_properties.py` | RNS1.4 属性测试：列表排序不变量（Property 3） |
|
||
|
||
### 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/`）
|
||
|
||
17 个 Steering 文件，控制 AI 助手的行为规范：
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `language-zh.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.md` | 项目结构（完整版，fileMatch 自动加载） |
|
||
| `export-paths.md` / `export-paths-full.md` | 输出路径规范（精简版 / 完整版） |
|
||
| `testing-env.md` | 测试环境规范：环境变量加载、cwd 要求、测试库使用 |
|
||
| `db-docs.md` | 数据库文档规范 |
|
||
| `doc-map.md` | 文档地图 Steering（fileMatch 触发） |
|
||
| `deprecated-objects.md` | 归档目录与废弃对象规则 |
|
||
| `dwd-doc-authority.md` | DWD-DOC 标杆文档权威性声明 |
|
||
| `steering-readme-maintainer.md` | README 维护者技能：变更影响审查与文档同步 |
|
||
|
||
### 5.2 Hooks（`.kiro/hooks/`）
|
||
|
||
11 个 Agent 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` | P2：ETL DWS 小程序扩展 |
|
||
| `03-miniapp-auth-system` | P3：小程序认证系统 |
|
||
| `04-miniapp-core-business` | P4：小程序核心业务 |
|
||
| `05-miniapp-ai-integration` | P5：小程序 AI 集成 |
|
||
| `[ETL]-fullstack-integration` | ETL 全栈集成 |
|
||
| `admin-web-console` | 管理后台控制台 |
|
||
| `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 员工维度 |
|
||
| `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 技能类型） |
|
||
| `rns1-chat-integration` | RNS1.4 CHAT 对齐与联调收尾（CHAT-1/2/3/4 路径迁移、对话复用、referenceCard、SSE 流式、FDW 验证、13 页面联调） |
|
||
| `spi-spending-power-index` | SPI 消费力指数 |
|
||
|
||
---
|
||
|
||
## 六、文档归档规则
|
||
|
||
新建文档时，按以下规则选择目标目录。禁止在 `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/` | 页面开发流程、API 审计、设计系统、H5 迁移指南 |
|
||
| 运维手册 | `ops/` | 故障排查、日常运维流程、测试用户初始化 |
|
||
| 权限矩阵 | `permission_matrix/` | 角色-资源权限映射 |
|
||
| VI 设计标准 | `vi-standards/` | 视觉识别设计标准 |
|
||
|
||
### 判断流程
|
||
|
||
1. 是模块专属文档？→ 放模块内部 `docs/`（如 `apps/etl/.../docs/`）
|
||
2. 是审计产物？→ 统一写 `docs/audit/`，禁止写入子模块
|
||
3. 按上表匹配文档类型 → 放对应子目录
|
||
4. 都不匹配？→ 先在上表新增分类，再创建子目录
|
||
|
||
> 本规则由 `.kiro/steering/export-paths.md` 强制执行。
|