mirror of
https://github.com/IRS-Public/direct-file.git
synced 2025-06-28 04:25:52 +00:00
initial commit
This commit is contained in:
sps-irs
Alexander Petros
parent
2f3ebd6693
commit
e0d5c84451
3413 changed files with 794524 additions and 1 deletions
BIN
docs/engineering/.DS_Store
vendored
Normal file
BIN
docs/engineering/.DS_Store
vendored
Normal file
Binary file not shown.
1
docs/engineering/README.md
Normal file
1
docs/engineering/README.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
# Engineering docs
|
||||
333
docs/engineering/Tax-Logic.md
Normal file
333
docs/engineering/Tax-Logic.md
Normal file
|
|
@ -0,0 +1,333 @@
|
|||
# Tax Logic
|
||||
|
||||
# Scenarios
|
||||
|
||||
### Validating scenarios
|
||||
|
||||
Here some images that explain what scenarios are and how we validate them.
|
||||
<img width="736" alt="Screenshot 2025-05-21 at 2 42 04 PM" src="https://github.com/user-attachments/assets/71b5a337-a7e7-4243-9b10-7757055a58bb" />
|
||||
<img width="680" alt="Screenshot 2025-05-21 at 2 42 12 PM" src="https://github.com/user-attachments/assets/88f187b5-728d-4df6-aff7-219a928acf56" />
|
||||
<img width="727" alt="Screenshot 2025-05-21 at 2 42 26 PM" src="https://github.com/user-attachments/assets/bed7889e-c98f-4d65-b987-58e97c556a8d" />
|
||||
<img width="912" alt="Screenshot 2025-05-21 at 2 42 45 PM" src="https://github.com/user-attachments/assets/c4a9aa68-2a06-4a0b-be7a-df81d8558254" />
|
||||
|
||||
|
||||
|
||||
# Translations
|
||||
|
||||
## Summary
|
||||
|
||||
We use a library called [i18next](https://www.i18next.com/) for internationalization (i18n).
|
||||
|
||||
It creates the ability to use references (keys) to point to translation values based on various natural languages. Currently we have translations for English (by default) and Spanish. The translations are found in en.yaml and es.yaml.
|
||||
|
||||
Any content provided by design needs to be added to the en.yaml. All content is submitted by design to General Counsel (GC). After it is approved by GC, we do the Spanish translations, which are added to the es.yaml (Note: we are working on tooling to simplify translations)
|
||||
|
||||
## Tips and Tricks for adding content
|
||||
|
||||
- en.yaml is a very long file. See if your IDE has bookmarks, and use them to mark your spot
|
||||
- en.yaml is organized by content type (subsubsections, headings, info, dataviews, fields)
|
||||
- When implementing several screens, input by content component type rather than screen content. For example, input all the headings of each of the screens since they will be next to each other in the yaml file. Then do all the InfoDisplay content, then Modal content, etc).
|
||||
- You can interpolate any (non-nested) fact value into the content using double curly brackets (ex. \`{{/taxYear}})
|
||||
- If your content string starts with interpolation (ex `{{/secondaryFiler/firstName}}`), you need to wrap the string in double quotes
|
||||
- Use a proper apostrophe char `’`instead of a single quote `'` when an apostrophe is needed. On a Mac, the shortcut is `Option + Shift + ]`(there is a test for this, and search and replace may be the most efficient way to do this when copying and pasting from design)
|
||||
- To reference existing content within the yaml, use the syntax `$t(path./to-value)`([for reference](https://www.i18next.com/translation-function/nesting))
|
||||
- `>-` basically means 'newline' in yaml
|
||||
|
||||
# Flamingo Fact Checker
|
||||
|
||||
[Link to plugin and instructions](Flamingo-Fact-Checker).
|
||||
|
||||
# FAQs
|
||||
|
||||
* [What is migrateScenarios?](#what-is-migratescenarios)
|
||||
* [Is there some fact graph 101 I can read?](#is-there-some-fact-graph-101-i-can-read)
|
||||
* [Can someone explain the distinction between categories, subcategories, and subsubcategories in the codebase and why i MUST have a subsubcategory according to my console?](#can-someone-explain-the-distinction-between-categories-subcategories-and-subsubcategories-in-the-codebase-and-why-i-must-have-a-subsubcategory-according-to-my-console)
|
||||
* [What's a scenario?](#whats-a-scenario)
|
||||
* [Why don't we call scenarios fact graphs or vice versa?](#why-dont-we-call-scenarios-fact-graphs-or-vice-versa)
|
||||
* [What tests should I run if making screen changes or fact changes?](#what-tests-should-i-run-if-making-screen-changes-or-fact-changes)
|
||||
* [What do flowSnapshots do and why do I have 100 errors?](#what-do-flowsnapshots-do-and-why-do-i-have-100-errors)
|
||||
* [What are we doing when we SetFactAction?](#what-are-we-doing-when-we-setfactaction)
|
||||
* [Does `npm run test` run all the frontend tests?](#does-npm-run-test-run-all-the-frontend-tests)
|
||||
* [When do facts need to be sent "downstream" or sent to "mef"?](#when-do-facts-need-to-be-sent-downstream-or-sent-to-mef)
|
||||
* [Adding new collection aliases are weird ?](#adding-new-collection-aliases-are-weird)
|
||||
* [What's the deal with Placeholders?](#whats-the-deal-with-placeholders)
|
||||
* [What is the difference between a fact in the dictionary with a value put in \<Placeholder\> tags like this, and a fact in the dictionary with just a value assigned but no Placeholder tag like this?](#what-is-the-difference-between-a-fact-in-the-dictionary-with-a-value-put-in-placeholder-tags-likethis-and-a-fact-in-the-dictionary-with-just-a-value-assigned-but-no-placeholder-tag-likethis)
|
||||
* [What about \<ExportZero/\>?](#what-about-exportzero)
|
||||
* [How does one deal with the requirement of export zero dollar values, **sometimes**, **conditionally**?](#how-does-one-deal-with-the-requirement-of-export-zero-dollar-valuessometimesconditionally)
|
||||
* [How are data view created?](#how-are-data-view-created)
|
||||
* [When can we use which fact types when writing facts?](#when-can-we-use-which-fact-types-when-writing-facts)
|
||||
* [\[ERROR\] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project directfile-api: Fatal error compiling: error: release version 21 not supported](#error-failed-to-execute-goal-orgapachemavenpluginsmaven-compiler-plugin3130compile-default-compile-on-project-directfile-api-fatal-error-compiling-error-release-version-21-not-supported)
|
||||
* [How to create a knockout?](#how-to-create-a-knockout)
|
||||
* [What is the difference between `useDynamicFact` and `useFact`?](#what-is-the-difference-between-usedynamicfact-and-usefact)
|
||||
* [Headings vs InfoDisplays?](#headings-vs-infodisplays)
|
||||
* [When we have a screen where we calculated a bunch of stuff to show to the tp, but it isn't a writable field - these results don't show up in the dataview. it seems weird not to have them. How do we add a non-field piece of info to the dataview for that subsubcategory?](#when-we-have-a-screen-where-we-calculated-a-bunch-of-stuff-to-show-to-the-tp-but-it-isnt-a-writable-field---these-results-dont-show-up-in-the-dataview-it-seems-weird-not-to-have-them-how-do-we-add-a-non-field-piece-of-info-to-the-dataview-for-that-subsubcategory)
|
||||
* [My test is failing with \`Invalid UUID string: undefined](#my-test-is-failing-with-invalid-uuid-string-undefined)
|
||||
* [I got a CSP warning in the console. I need to update the CSP. Where do I do that?](#i-got-a-csp-warning-in-the-console-i-need-to-update-the-csp-where-do-i-do-that)
|
||||
* [What is All-Screens and where can I find it?](#what-is-all-screens-and-where-can-i-find-it)
|
||||
* [What's the difference between `DFAlert`, `Assertion` , `TaxReturnAlert` , `MefAlert`, `FactAssertion`, and `FactResultAssertion` ?](#whats-the-difference-betweendfalert-assertion--taxreturnalert-mefalert-factassertion-and-factresultassertion-)
|
||||
* [I have to create some checkboxes and can use MultiEnum or Booleans as checkboxes. When should I use one over the other?](#i-have-to-create-some-checkboxes-and-can-use-multienum-or-booleans-as-checkboxes-when-should-i-use-one-over-the-other)
|
||||
* [Why does this Fact error out with \`java.lang.UnsupportedOperationException: must use getVect to access...](#why-does-this-fact-error-out-with-javalangunsupportedoperationexception-must-use-getvect-to-access)
|
||||
* [I need to set a limit for a fact based on the value of another fact. How do I do it?](#i-need-to-set-a-limit-for-a-fact-based-on-the-value-of-another-fact-how-do-i-do-it)
|
||||
* [How do I format a recent factgraph module that I changed?](#how-do-i-format-a-recent-factgraph-module-that-i-changed)
|
||||
* [How to capitalize an Enum using existing CompNodes?](#how-to-capitalize-an-enum-using-existing-compnodes)
|
||||
|
||||
|
||||
### What is migrateScenarios?
|
||||
|
||||
Why? When a change in the codebase requires that all jsons contain new facts or updates to existing facts, this script can be used to update all of the files at once.
|
||||
|
||||
How? The script does not automatically detect anything or run automatically.
|
||||
|
||||
* The eng who made the change to the codebase should change this script to update the facts as needed.
|
||||
* In most cases only the section between MIGRATION START and MIGRATION END will need to be updated.
|
||||
* Then the eng runs this script and commits the updated jsons. `npm run migrate-scenarios`
|
||||
|
||||
Note that even though it is checked in, this script runs only once to update all the scenario jsons.
|
||||
|
||||
### Can someone explain the distinction between categories, subcategories, and subsubcategories in the codebase and why i MUST have a subsubcategory according to my console?
|
||||
|
||||
* Categories and subcategories appear in the checklist
|
||||
* Each subcategory may have 1-2 items of data in the checklist
|
||||
* Each subcategory has a dataview, which is a summary of the subcategory.
|
||||
* In some cases the dataview might just be a screen within the subcategory (`<Screen actAsDataView={true} />`)
|
||||
* But in most cases the dataview is a new page which shows all the subsubcategories.
|
||||
* The subsubcategories in the dataview have multiple items of data and an edit button.
|
||||
* The subsubcategory edit button takes you to those screens in the flow.
|
||||
* Then you will be in review mode and on completion of the screens in that subsubcategory, get redirected back to the dataview.
|
||||
* Every screen must be in a subsubcategory with the following exceptions
|
||||
* If a screen is the only screen in a subcategory AND it is marked with `actAsDataview`
|
||||
* If a screen is not editable, can be placed inside a subcategory. In this case, the screen will only be shown to a taxpayer on their first pass of the screens- it will not show up in review mode.
|
||||
|
||||
### What's a scenario?
|
||||
|
||||
As a client enters information in the Direct File (DF) application, the application accumulates these facts. These accumulated facts is sometimes called the "client factgraph json". This json file can represent almost any situation, and they essentially represent one user's tax situation or _scenario_.
|
||||
|
||||
So we store them and use them to test different user scenarios. We have a few hundred pre-defined scenarios. These scenarios lay the foundation for testing various parts of our app. As we add scope, we may add more scenarios.
|
||||
|
||||
### Why don't we call scenarios fact graphs or vice versa?
|
||||
|
||||
I guess we could, but to allow some distinction between any fact graph and this set of fact graphs that represent different user tax return situations, we introduced the concept of scenarios.
|
||||
|
||||
Scenarios are a subset of factgraphs as they are required to be complete - as in, the person got to the sign and submit screen and there were no submission blocking errors.
|
||||
|
||||
### What tests should I run if making screen changes or fact changes?
|
||||
|
||||
It kinda depends on what is changing in the screen. If the screen order changes then the `flowSnapshots` tests would capture this. When facts change there can be a whole cascade of tests that can test this change. Our recommendation is to follow this [mural](https://app.mural.co/t/usdigitalservice0135/m/usdigitalservice0135/1722960219541/36%5B%E2%80%A6%5D510295f8a2727fd347e319714a73c?sender=u609b185fbd158566f8103243) and walk through each step when making fact changes. There are 4 steps and each step has instructions on what tests to run.
|
||||
|
||||
### What do flowSnapshots do and why do I have 100 errors?
|
||||
|
||||
flowSnapshots are making sure the order of the screens are what we expect them to be for each scenario.
|
||||
|
||||
The way it works is that it runs through the scenario, as though the user is clicking through screens and stores the sequence of screens seen. Then that sequence is stored, so that we can test that it doesn't change accidentally.
|
||||
|
||||
If some new screen was added that will be shown to the users represented by lots of scenarios, that sequence will now change and not match what was stored. So when the flowSnapshot test ran it updated all snapshots and you may be seeing many errors.
|
||||
|
||||
If the change you see in the files is what was expected based on the change you made in your PR, you can simply check in the new sequence.
|
||||
|
||||
### What are we doing when we SetFactAction?
|
||||
|
||||
Sometimes we need to set a fact when the tax payer (TP) reaches a screen, regardless of their input. In other words, "when a TP reaches this screen, set this fact".
|
||||
|
||||
### Does `npm run test` run all the frontend tests?
|
||||
|
||||
Yes, `npm run test` runs all the frontend vite tests. There are two other tests that may be helpful:
|
||||
|
||||
* `npm run test:ci` - which runs all tests from the CI/CD pipeline (ie, when a PR is opened or committed to) except the completenessTests and functionalFlowTests.
|
||||
* `npm run test:ci:2` - runs the completenessTests and functionalFlowTests
|
||||
|
||||
### When do facts need to be sent "downstream" or sent to "mef"?
|
||||
|
||||
Our fact dictionary is broken into modules. Each fact dictionary module is an XML fie. Here's a list of them as of the time of writing this answer:
|
||||
|
||||
{width="281" height="822"}
|
||||
|
||||
With `elderlyAndDisabled.xml` selected, opening this file, we see:
|
||||
|
||||
{width="1063" height="822"}A few things we notice that the first line of this file designates this to be a fact dictionary. The first fact has the export statement of:
|
||||
|
||||
* Export mef="true" downstreamFacts="true"
|
||||
|
||||
Certain facts are needed by other modules, if/when a fact is needed by another module, you can specify `downstreamFacts="true"`. Another advantage is testing. Fact that we're exporting for reuse in other modules should probably have tests.
|
||||
|
||||
You do not need to set downstreamFacts in order to write the value in a PDF, that process is just another way of displaying the value and is not subject to dependency management.
|
||||
|
||||
A few things to keep in mind
|
||||
|
||||
1. Always run the `npm run watch-fact-dictionary` so that any changes to any fact dictionary module will automatically re-build the dictionary
|
||||
2. To validate your fact dictionary changes, you can run `npm run verify-module-dependencies`. This will let you know if some facts are in error or if you are missing the `mef` or `downstreamFacts` attribute on any fact definition.
|
||||
|
||||
### Adding new collection aliases are weird
|
||||
|
||||
Indeed. In the filers.xml fact dictionary module, you will sometimes see facts with a \_`*` eg, `/filers/`\_`*/firstName`. This would be a _collection_. Each collection is made up of _collection items._ In this case, the filers collection is made up of two items, namely the primary and secondary UUIDs.
|
||||
|
||||
Lets say we wanted to operate on that collection, by e.g., filtering it. When we filter that collection, the resulting collection could be
|
||||
|
||||
1. \[primaryUUID, secondaryUUID\]
|
||||
2. \[primaryUUID\]
|
||||
3. \[secondaryUUID\]
|
||||
4. \[\]
|
||||
|
||||
This filtered collection, doesn't have access to the other facts in the filers module. For example, `/filers/*/MiddleInitial` or `/filers/*/dateofBirth`. In order to access these other facts, we use aliases.
|
||||
|
||||
There are two files responsible for aliases, ie, aliases.ts and dependencyGraph.ts
|
||||
|
||||
### What's the deal with Placeholders?
|
||||
|
||||
Placeholders help set the value but don't make a fact complete.To answer your questions more directly, placeholders mean that a value of a fact will never be blank. Once a fact is written we generally don't provide ways to clear out written facts. The reason they don't work as a proper default is that we also end up checking if a fact is complete in a couple of different spots.
|
||||
|
||||
### What is the difference between a fact in the dictionary with a value put in \<Placeholder\> tags and a fact in the dictionary with just a value assigned but no Placeholder tag
|
||||
|
||||
So we have a concept of writable facts and derived facts where writable facts are those that the user can update and derived facts that are just "calculated" values. "Placeholders" I believe are only supported for writable facts as the intention is that the user should potentially override them with a written value. Derived facts can just be static values like in the example you gave. I would consider it to be more of a constant than a default value, but that's likely just a jargon/pedantic distinction. This is a default value in the sense that this value will not really change.
|
||||
|
||||
### What about \<ExportZero/\>?
|
||||
|
||||
By default, facts with value zero are not sent to PDF or XML generation. This tag overrides that behavior for a fact, so that the zero will be included in the outputs.
|
||||
|
||||
Note that it is possible to conditionally export zero values by using this tag on a fact that conditionally leaves its value unspecified (incomplete). PDF generation automatically ignores incomplete fact values, producing the effect of a "blank" output. XML mappings can use the Optional syntax to get a similar result.
|
||||
|
||||
### How does one deal with the requirement of export zero dollar values, **sometimes**, **conditionally**?
|
||||
|
||||
TBD
|
||||
|
||||
### How are data view created?
|
||||
|
||||
Some info [here](flow/dataviews.md)
|
||||
|
||||
### When can we use which fact types when writing facts?
|
||||
|
||||
When creating facts the first question to ask is, is the fact a writable fact or a derived fact. If the fact is writable. then generally speaking we will require it to use one of the factTypes, to calculate a new fact based on some other fact (called a Dependency).
|
||||
|
||||
### \[ERROR\] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project directfile-api: Fatal error compiling: error: release version 21 not supported
|
||||
|
||||
In the event that anyone else has ran into the issue of `./mvnw` ignoring `JAVA_HOME`, I discovered that at some point in my past, I created a `~/.mavenrc` file that overrode `JAVA_HOME` to a specific version number, but only when running maven. Deleting that file caused `./mvnw` to use the correct version.
|
||||
|
||||
### How to create a knockout?
|
||||
|
||||
In summary there are 3 steps:
|
||||
|
||||
1. Create the fact that will be responsible to knockout the TP
|
||||
2. Add the Screen that will use the fact created in Step 1 and set `isKnockout={true}` on it.
|
||||
3. Add the newly created fact from Step 1 to the `/flowIsKnockedOut` fact in flow.xml.
|
||||
|
||||
### Headings vs InfoDisplays?
|
||||
|
||||
Every screen has a `Heading` and yes they are sometimes long. Every screen can only have one `Heading`.
|
||||
|
||||
Usually the top most text on every screen is the `Heading`. I believe in some cases there is a section header above the header. `InfoDisplay`s handles a lot of flexible content as you can put "html" inside it. Most explanatory text would use `InfoDisplay` by default.
|
||||
|
||||
You can have more than one `InfoDisplay` in a screen but not more than one `Heading`.
|
||||
|
||||
### When we have a screen where we calculated a bunch of stuff to show to the tp, but it isn't a writable field - these results don't show up in the `dataview`. it seems weird not to have them. How do we add a non-field piece of info to the `dataview` for that `subsubcategory`?
|
||||
|
||||
What you may be be looking for is `displayOnlyOn` property. You can add this to any of the content declaration types we have like Dollar or String with the corresponding fact and set the `displayOnlyOn` to `data-view` . We have a handful of examples of this within the CreditSubsection.
|
||||
|
||||
### My test is failing with \`Invalid UUID string: undefined
|
||||
|
||||
You may need to add a a line here in the test file:
|
||||
|
||||
```jsx
|
||||
const collectionIdMap = {
|
||||
[`/flow/you-and-your-family/about-you`]: primaryFilerId,
|
||||
[`/flow/you-and-your-family/spouse`]: primaryFilerId,
|
||||
[`/flow/you-and-your-family/dependents`]: dependentId,
|
||||
[`/flow/income/jobs`]: w2Id,
|
||||
[`/flow/income/interest`]: interestReportId,
|
||||
[`/flow/income/unemployment`]: formId,
|
||||
[`/flow/income/retirement`]: retirementForm1099Id,
|
||||
[`/flow/income/apf`]: apfForm1099Id,
|
||||
[`/flow/income/social-security`]: reportId, };``
|
||||
```
|
||||
|
||||
### What is All-Screens and where can I find it?
|
||||
|
||||
All screens is a page that displays every screen in the application and the conditionals for that page. The URL for local development is at http://localhost:3000/df/file/all-screens/index.html
|
||||
|
||||
### What's the difference between `DFAlert`, `Assertion` , `TaxReturnAlert` , `MefAlert`, `FactAssertion`, and `FactResultAssertion` ?
|
||||
|
||||
`<DFAlert>` has no special behavior and just renders content on a screen like normal
|
||||
|
||||
`<Assertion>` is used for alerts that should show up only in the SubCategory dataview screen
|
||||
|
||||
`<TaxReturnAlert>` is rendered in a specific screen and an aggregated alert summary on the checklist and dataview pages
|
||||
|
||||
* If `type='error'` and the alert's conditions are true, submission will be blocked until the filer makes the necessary updates to fix the error.
|
||||
* If `type='warning'` does not block submission and just directs the user to review the data on the screen in which it is present
|
||||
* If the type is set to anything else, the alert will not render under any conditions (this is likely something we should prevent, but may have been unintentional)
|
||||
* We currently use these to prompt filers to remove any income items associated with a secondary filer if they change their status to anything other than Married Filing Jointly.
|
||||
|
||||
`<MefAlert>` are used when an alert is based on the response from MEF and not something we can determine in advance and the error is correctable.
|
||||
|
||||
* These will only ever render when a tax return is rejected. They are configured with an `mefErrorCode` that is returned from MEF and linked to the user's return separately from the fact graph and is a required condition for displaying the alert.
|
||||
* These alerts also bubble up to the checklist and dataviews just as with `<TaxReturnAlert>` and have the same behaviors with the `type` attribute.
|
||||
* Additional conditions on `<MefAlert>` nodes are used when we are able to determine whether the cause of the error has been resolved and can hide/remove the alert.
|
||||
* As an example, the `IND-180-01` MEF error code is set if the user submits a return claiming that they have no IP Pin but the IRS has records saying that they do. This prompts a blocking `<MefAlert>` to be displayed that will only become inactive once the user answers that they do, in fact, have a PIN and enter it.
|
||||
* If we have no way know for certain whether the user has corrected the problem, we should make sure the alert is set to warning, so the user can resubmit once they believe they have corrected the issue.
|
||||
|
||||
`<TaxReturnAlert>` and `<MefAlert>` are both aggregated from the screen config so that we can direct them all the way from the checklist, down to the specific screen(s) they belong to.
|
||||
|
||||
`<FactAssertion>`, `<FactResultAssertion>`, and the `outcomeI18nKey`/`resultI18nKey` keys are used to display alerts that only bubble up to the dataview and collection screens and are primarily used in the dependents and qualifying persons section.
|
||||
|
||||
Lastly, "Cues & Aggregators" area of this 2023 Mural board does a good job explaining [how the alerts work](https://app.mural.co/t/usdigitalservice0135/m/usdigitalservice0135/1679591477411/ca7cc4ebdd42dfd9a3ee5ea57153b0135df9971f?wid=0-1701705425590). Documentation from Jen in the [design wiki - TODO](), should mirror what's on that 2023 Mural.
|
||||
|
||||
### I have to create some checkboxes and can use MultiEnum or Booleans as checkboxes. When should I use one over the other?
|
||||
|
||||
Use MultiEnum if
|
||||
|
||||
* All your checkboxes need to packaged into a single fact as a Set/List and needs to sent to MeF
|
||||
|
||||
Use Boolean if
|
||||
|
||||
* You need access to those checkbox values later on in the flow
|
||||
|
||||
### Why does this Fact error out with \`java.lang.UnsupportedOperationException: must use getVect to access...
|
||||
|
||||
Can you see the problem with the code below?
|
||||
|
||||
```jsx
|
||||
<Fact path="/cdccCareProviders/*/isHouseholdEmployeeNo">
|
||||
<Name>Is Not a Household Employee</Name>
|
||||
<Description>Whether care provider is not a household employee. Used for the f2441 PDF 'No'
|
||||
checkbox</Description>
|
||||
|
||||
<Derived>
|
||||
<Not>
|
||||
<Dependency path="/cdccCareProviders/*/isHouseholdEmployee" />
|
||||
</Not>
|
||||
</Derived>
|
||||
</Fact>
|
||||
```
|
||||
|
||||
The problem lies in the following fact: `/cdccCareProviders/*/isHouseholdEmployee`. Is this fact, complete and true?
|
||||
|
||||
To fix this issue, this fact:
|
||||
|
||||
```jsx
|
||||
<Dependency path="/cdccCareProviders/*/isHouseholdEmployee" />`
|
||||
```
|
||||
|
||||
should be
|
||||
|
||||
```jsx
|
||||
<Dependency path="../isHouseholdEmployee" />
|
||||
```
|
||||
|
||||
The error is telling you, you need to use get vect because the original `/cdccCareProviders/*/isHouseholdEmployee` is an array since we don't have the context for the `*`.\
|
||||
If we use the `../isHouseholdEmployee` we are referencing the same id in the main fact so we would only get a single value here instead of an array.
|
||||
|
||||
### I need to set a limit for a fact based on the value of another fact. How do I do it?
|
||||
|
||||
There's been some discussion on setting up dynamic fact limits for field level validation, but field level validation alone would not work because you could change the limiting fact so `TaxReturnAlert` is used instead. `<TaxReturnAlert>` has the advantage that if you go back and make edits that would change the validity of that fact, you'll be directed to the now-invalid fact. The downside is the user is not immediately notified of the error.
|
||||
|
||||
### How do I format a recent factgraph module that I changed?
|
||||
|
||||
Navigate to the project you are working on (backend, submit, etc) and run \`./mvnw spotless:apply\`
|
||||
|
||||
### How to capitalize an Enum using existing CompNodes?
|
||||
|
||||
```jsx
|
||||
<ToUpper>
|
||||
<AsString>
|
||||
<Dependency module="filers" path="/filerResidenceAndIncomeState" />
|
||||
</AsString>
|
||||
</ToUpper>
|
||||
```
|
||||
65
docs/engineering/bug-prioritization.md
Normal file
65
docs/engineering/bug-prioritization.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
# Bug Prioritization
|
||||
|
||||
The following is a draft of guidelines for prioritizing bugs and incident responses that arise during tax season. For the below, we expect releases to happen weekly.\
|
||||
\
|
||||
**Rank 0 (R0): Emergency Hotfix, needs to ship as soon as possible**
|
||||
|
||||
* You can't submit a tax return (as an individual or to a state) for \>1% of submissions
|
||||
* Refund or amount due calculation is incorrect and we know taxpayers are being affected by the issue
|
||||
* Security incident or PII is exposed
|
||||
* Direct File is down or significantly degraded
|
||||
* High traffic feature where functionality is broken or not available, and no workaround
|
||||
|
||||
\
|
||||
**R1: Now, Showstopper fix for the next immediate release**
|
||||
|
||||
* High traffic functionality is broken - difficult or time consuming workaround
|
||||
* Medium traffic functionality is broken for a smaller percentage of taxpayers (10 - 50%) with no workaround
|
||||
* Submissions to states or MeF are blocked for \<1% of taxpayers
|
||||
* Direct file performance is degraded (metric)
|
||||
* Refund or amount due calculation would be incorrect but circumstances to trigger the issue are rare enough that production users are unlikely to be affected before scheduled release.
|
||||
|
||||
\
|
||||
**R2: Next, fix for the scheduled release following the next immediate release**
|
||||
|
||||
* High value taxpayer experience improvements: Medium, high, to very high traffic feature has confusing functionality with a workaround
|
||||
* Low traffic functionality is broken for a smaller percentage of taxpayers (10 - 50%)
|
||||
|
||||
\
|
||||
**R3: Later this tax season**
|
||||
|
||||
* Usability feedback (via customer support or other sources): improves a medium traffic feature but there is a current workaround
|
||||
* Low traffic functionality is broken for a smaller percentage of taxpayers (\<10%)
|
||||
|
||||
\
|
||||
**R4: Consider for this tax season**
|
||||
|
||||
* Nice to have usability improvements, functionality not needed to perform daily work and is not time sensitive
|
||||
|
||||
\
|
||||
**R5: backlog for future tax seasons**
|
||||
|
||||
* Unlikely to get to these: low impact improvements
|
||||
|
||||
## References
|
||||
|
||||
* Last year's guidelines
|
||||
* P0: emergency, merits a hotfix\
|
||||
P1: a **must**/show stopper for the next scheduled release\
|
||||
P2: a **should** for the next scheduled release\
|
||||
P3: a **must** for this tax season\
|
||||
P4: a **should** for this tax season\
|
||||
P5: backlog for future tax seasons
|
||||
* Feedback from states
|
||||
* ability to submit a return is impacted (critical)
|
||||
* ability to accurately _calculate_ state taxes is impacted (high priority)
|
||||
* smooth user experience for TP when doing their state taxes (lower priority)
|
||||
* Tax Logic Priority Scale
|
||||
* P0: Yesterday (needs to ship as soon as possible, probably an incident)
|
||||
* P1: Now (needs to be in the next regular release)
|
||||
* P2: Next (should be release after next)
|
||||
* P3: Later
|
||||
* P4: Before the end of filing season
|
||||
* P5: After filing season
|
||||
* CfA user pain score calculator: https://files.codeforamerica.org/2022/11/29092445/Client-Pain-Score-User-Pain-Score.pdf
|
||||
* Note: we chose Rank (R0) vs. Priority (P0) because there is a separate IRWorks priority that uses a different "P" scale
|
||||
75
docs/engineering/df-tools/Flamingo-Fact-Checker.md
Normal file
75
docs/engineering/df-tools/Flamingo-Fact-Checker.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# Flamingo Fact Checker
|
||||
|
||||
[Flamingo Fact Checker (zip file in utils directory)](../../utils/) is a chrome extension to assist devs with tracking facts as they move through the UI.
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
* Fact tracking - View fact values live on screen.
|
||||
* Live facts - shows the facts associated with the fields on the page currently being viewed.
|
||||
* Telescope - View fact documentation and live values of the dependencies inline. Requires environment variable `VITE_ENABLE_FLAMINGO_TELESCOPE` to be set to true.
|
||||
* Import / Export of factgraph - click on the extension button in Chrome to robustly import or export a factgraph.
|
||||
* Import / Export of fact names - click on the extension button in Chrome to track a group of facts.
|
||||
|
||||
<img width="523" alt="image-1" src="https://github.com/user-attachments/assets/a82a157c-8195-43eb-9139-998b9c142bd9" />
|
||||
|
||||
|
||||
<img width="706" alt="image-2" src="https://github.com/user-attachments/assets/81ff2ab3-092b-491a-b8da-819e88b6ea64" />
|
||||
|
||||
## How to install
|
||||
|
||||
1. Get the latest release zip
|
||||
2. Extract the zip, it should create a folder named flamingo
|
||||
3. Go to `chrome://extensions/`
|
||||
4. Enable developer mode
|
||||
5. Click on "Load unpacked", navigate to the folder and click select
|
||||
6. Go to directfile on [localhost](http://localhost) and it should load.
|
||||
|
||||
### How to update
|
||||
|
||||
1. Get the latest release zip
|
||||
2. Extract the zip, it should create a folder named flamingo
|
||||
3. Go to `chrome://extensions/`
|
||||
4. Hit the reload the button on the extension
|
||||
|
||||
### How to enable telescope
|
||||
|
||||
The data for the fact definitions is rather large and I didn't want to force everyone to download it. So this feature is available only on local dev and requires that you set an environment variable in your local environment:
|
||||
|
||||
```
|
||||
export VITE_ENABLE_FLAMINGO_TELESCOPE=true
|
||||
```
|
||||
|
||||
or start npm with it
|
||||
|
||||
```
|
||||
VITE_ENABLE_FLAMINGO_TELESCOPE=true npm run start
|
||||
```
|
||||
|
||||
## Releases
|
||||
|
||||
### v1.4.0 [flamingo_v1.4.0.zip](https://github.com/DirectFile/flamingo-fact-checker/blob/main/uploads/457d2aa5547a204b35897000246cbe84/flamingo_v1.4.0.zip)
|
||||
|
||||
* Facts truncate if too long, hover to see full name
|
||||
* Bugs with first install fixed (if rewind never seemed to work for you)
|
||||
|
||||
### v1.3.0 [flamingo_v1.3.0.zip](https://github.com/DirectFile/flamingo-fact-checker/blob/main/uploads/14b80c152c2d518673e7bce8bcb65ad7/flamingo_v1.3.0.zip)
|
||||
|
||||
* Telescope into a fact and see its dependencies and their values
|
||||
* Incomplete and placeholder values now visible
|
||||
* Load and copy out your factgraph easily
|
||||
|
||||
### v1.2.1 [flamingo_v1.2.1.zip](https://github.com/DirectFile/flamingo-fact-checker/blob/main/uploads/3107745f4a357647582746fb3a2e8a44/flamingo_v1.2.1.zip)
|
||||
|
||||
* Rewind your factgraph
|
||||
* Hotlink to collection items
|
||||
* Bugfixes
|
||||
|
||||
#### Known Issues
|
||||
|
||||
* Some collection items may have more than one hotlink and depending on factgraph, they may not all be visible pages.
|
||||
|
||||
### v1.1.0 [flamingo_v1.1.0.zip](https://github.com/DirectFile/flamingo-fact-checker/blob/main/uploads/3fd9deef0cc06c1b9394babc7a4b1091/flamingo_v1.1.0.zip)
|
||||
|
||||
* Persistent fact tracking
|
||||
* Live monitor of current facts on page
|
||||
BIN
docs/engineering/df-tools/flamingo-fact-checker-main.zip
Normal file
BIN
docs/engineering/df-tools/flamingo-fact-checker-main.zip
Normal file
Binary file not shown.
13
docs/engineering/md_to_pdf/md-to-pdf-cmp.config.js
Normal file
13
docs/engineering/md_to_pdf/md-to-pdf-cmp.config.js
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
const { pdf_options, footerTemplate } = require("./md-to-pdf.config.js");
|
||||
|
||||
module.exports = {
|
||||
pdf_options: {
|
||||
format: pdf_options.format,
|
||||
headerTemplate: pdf_options.headerTemplate,
|
||||
footerTemplate: footerTemplate.replace('[[FOOTER]]', 'OS:IT:AD:CS-PLN-DFSYS_CM_PLAN-V1.0-03052024')
|
||||
},
|
||||
// https://github.com/simonhaenisch/md-to-pdf/issues/247
|
||||
launch_options: {
|
||||
headless: "new"
|
||||
}
|
||||
};
|
||||
13
docs/engineering/md_to_pdf/md-to-pdf-coh.config.js
Normal file
13
docs/engineering/md_to_pdf/md-to-pdf-coh.config.js
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
const { pdf_options, footerTemplate } = require("./md-to-pdf.config.js");
|
||||
|
||||
module.exports = {
|
||||
pdf_options: {
|
||||
format: pdf_options.format,
|
||||
headerTemplate: pdf_options.headerTemplate,
|
||||
footerTemplate: footerTemplate.replace('[[FOOTER]]', 'OS:IT:AD:CS-SYS-DFSYS_COH-V0.9-01052024')
|
||||
},
|
||||
// https://github.com/simonhaenisch/md-to-pdf/issues/247
|
||||
launch_options: {
|
||||
headless: "new"
|
||||
}
|
||||
};
|
||||
30
docs/engineering/md_to_pdf/md-to-pdf.config.js
Normal file
30
docs/engineering/md_to_pdf/md-to-pdf.config.js
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
const headerTemplate = `
|
||||
<style>
|
||||
section {
|
||||
margin: 0 auto;
|
||||
font-family: system-ui;
|
||||
font-size: 12px;
|
||||
}
|
||||
.footer div {
|
||||
position: absolute;
|
||||
width: 50%;
|
||||
bottom: 30px;
|
||||
}
|
||||
</style>
|
||||
<section><div>[[HEADER]]</div></section>
|
||||
`
|
||||
const footerTemplate = '<section class="footer"><div style="left: 30px;">[[FOOTER]]</div><div style="text-align: right; right: 30px;"><span class="pageNumber"></span></div></section>';
|
||||
|
||||
module.exports = {
|
||||
headerTemplate: headerTemplate,
|
||||
footerTemplate: footerTemplate,
|
||||
pdf_options: {
|
||||
format: 'letter',
|
||||
headerTemplate: headerTemplate.replace('[[HEADER]]', ''),
|
||||
footerTemplate: footerTemplate.replace('[[FOOTER]]', 'Draft/Pre-decisional')
|
||||
},
|
||||
// https://github.com/simonhaenisch/md-to-pdf/issues/247
|
||||
launch_options: {
|
||||
headless: "new"
|
||||
}
|
||||
};
|
||||
85
docs/engineering/md_to_pdf/mdToc.js
Normal file
85
docs/engineering/md_to_pdf/mdToc.js
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
// pipe in all the files
|
||||
// create toc (and figures)
|
||||
// create pdf
|
||||
|
||||
const writeFile = require("node:fs/promises").writeFile;
|
||||
|
||||
const md2Toc = async () => {
|
||||
let options = {
|
||||
bullets: true,
|
||||
bullet: "* ",
|
||||
toplevel: false,
|
||||
ignorebeforetoc: true,
|
||||
indent: true,
|
||||
links: true,
|
||||
maxdepth: 4
|
||||
},
|
||||
tocBody = '',
|
||||
fileOutput = '';
|
||||
|
||||
let passedToc = !options.ignorebeforetoc;
|
||||
for await (const line of streamByLines(process.stdin)) {
|
||||
fileOutput += `${line}\n`;
|
||||
|
||||
if (/^#/.test(line)) {
|
||||
let title = line.replace(/^#+\s+/, ""),
|
||||
onToc = false;
|
||||
if (/^Table of/.test(title)) {
|
||||
passedToc = !options.ignorebeforetoc;
|
||||
onToc = true;
|
||||
} else {
|
||||
onToc = false;
|
||||
}
|
||||
|
||||
if (passedToc) {
|
||||
let currentDepth = (line.match(/^#+/) || [null])[0].length;
|
||||
if (!options.toplevel) currentDepth = currentDepth-1;
|
||||
|
||||
// if we're still under the max depth
|
||||
if (currentDepth > 0 && currentDepth <= options.maxdepth) {
|
||||
let indentSpacer = options.indent ? Array(currentDepth).join(" ") : "";
|
||||
|
||||
let header;
|
||||
if (options.links) {
|
||||
let href = title.replace(/ /g, "-").replace(nonTocCharactersRegex, "").toLowerCase(),
|
||||
link = "[" + title + "](#" + href + ")\n";
|
||||
|
||||
header = options.bullets ? options.bullet + link : link;
|
||||
} else {
|
||||
header = options.bullets ? options.bullet + title + "\n" : title + '\n';
|
||||
}
|
||||
|
||||
tocBody = tocBody + indentSpacer + header;
|
||||
}
|
||||
}
|
||||
passedToc ||= onToc;
|
||||
}
|
||||
}
|
||||
|
||||
const today = new Date().toLocaleDateString('en-US', {month: 'long', day: 'numeric', year: 'numeric'});
|
||||
fileOutput = fileOutput.replace('[[TOC]]', tocBody).replace('[[DATE]]', today);
|
||||
return fileOutput;
|
||||
}
|
||||
|
||||
const streamByLines = (stream) => {
|
||||
stream.setEncoding('utf8');
|
||||
return {
|
||||
async *[Symbol.asyncIterator]() {
|
||||
let buffer = '';
|
||||
|
||||
for await (const chunk of stream) {
|
||||
buffer += chunk;
|
||||
const lines = buffer.split(/\r?\n/);
|
||||
buffer = lines.pop();
|
||||
for (const line of lines) {
|
||||
yield line;
|
||||
}
|
||||
}
|
||||
if (buffer.length > 0) yield buffer;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
md2Toc().then((result) => console.log(result));
|
||||
|
||||
const nonTocCharactersRegex = /(?! |-|[\u0041-\u005A\u0061-\u007A\u00AA\u00B5\u00BA\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02C1\u02C6-\u02D1\u02E0-\u02E4\u02EC\u02EE\u0370-\u0374\u0376\u0377\u037A-\u037D\u0386\u0388-\u038A\u038C\u038E-\u03A1\u03A3-\u03F5\u03F7-\u0481\u048A-\u0527\u0531-\u0556\u0559\u0561-\u0587\u05D0-\u05EA\u05F0-\u05F2\u0620-\u064A\u066E\u066F\u0671-\u06D3\u06D5\u06E5\u06E6\u06EE\u06EF\u06FA-\u06FC\u06FF\u0710\u0712-\u072F\u074D-\u07A5\u07B1\u07CA-\u07EA\u07F4\u07F5\u07FA\u0800-\u0815\u081A\u0824\u0828\u0840-\u0858\u08A0\u08A2-\u08AC\u0904-\u0939\u093D\u0950\u0958-\u0961\u0971-\u0977\u0979-\u097F\u0985-\u098C\u098F\u0990\u0993-\u09A8\u09AA-\u09B0\u09B2\u09B6-\u09B9\u09BD\u09CE\u09DC\u09DD\u09DF-\u09E1\u09F0\u09F1\u0A05-\u0A0A\u0A0F\u0A10\u0A13-\u0A28\u0A2A-\u0A30\u0A32\u0A33\u0A35\u0A36\u0A38\u0A39\u0A59-\u0A5C\u0A5E\u0A72-\u0A74\u0A85-\u0A8D\u0A8F-\u0A91\u0A93-\u0AA8\u0AAA-\u0AB0\u0AB2\u0AB3\u0AB5-\u0AB9\u0ABD\u0AD0\u0AE0\u0AE1\u0B05-\u0B0C\u0B0F\u0B10\u0B13-\u0B28\u0B2A-\u0B30\u0B32\u0B33\u0B35-\u0B39\u0B3D\u0B5C\u0B5D\u0B5F-\u0B61\u0B71\u0B83\u0B85-\u0B8A\u0B8E-\u0B90\u0B92-\u0B95\u0B99\u0B9A\u0B9C\u0B9E\u0B9F\u0BA3\u0BA4\u0BA8-\u0BAA\u0BAE-\u0BB9\u0BD0\u0C05-\u0C0C\u0C0E-\u0C10\u0C12-\u0C28\u0C2A-\u0C33\u0C35-\u0C39\u0C3D\u0C58\u0C59\u0C60\u0C61\u0C85-\u0C8C\u0C8E-\u0C90\u0C92-\u0CA8\u0CAA-\u0CB3\u0CB5-\u0CB9\u0CBD\u0CDE\u0CE0\u0CE1\u0CF1\u0CF2\u0D05-\u0D0C\u0D0E-\u0D10\u0D12-\u0D3A\u0D3D\u0D4E\u0D60\u0D61\u0D7A-\u0D7F\u0D85-\u0D96\u0D9A-\u0DB1\u0DB3-\u0DBB\u0DBD\u0DC0-\u0DC6\u0E01-\u0E30\u0E32\u0E33\u0E40-\u0E46\u0E81\u0E82\u0E84\u0E87\u0E88\u0E8A\u0E8D\u0E94-\u0E97\u0E99-\u0E9F\u0EA1-\u0EA3\u0EA5\u0EA7\u0EAA\u0EAB\u0EAD-\u0EB0\u0EB2\u0EB3\u0EBD\u0EC0-\u0EC4\u0EC6\u0EDC-\u0EDF\u0F00\u0F40-\u0F47\u0F49-\u0F6C\u0F88-\u0F8C\u1000-\u102A\u103F\u1050-\u1055\u105A-\u105D\u1061\u1065\u1066\u106E-\u1070\u1075-\u1081\u108E\u10A0-\u10C5\u10C7\u10CD\u10D0-\u10FA\u10FC-\u1248\u124A-\u124D\u1250-\u1256\u1258\u125A-\u125D\u1260-\u1288\u128A-\u128D\u1290-\u12B0\u12B2-\u12B5\u12B8-\u12BE\u12C0\u12C2-\u12C5\u12C8-\u12D6\u12D8-\u1310\u1312-\u1315\u1318-\u135A\u1380-\u138F\u13A0-\u13F4\u1401-\u166C\u166F-\u167F\u1681-\u169A\u16A0-\u16EA\u1700-\u170C\u170E-\u1711\u1720-\u1731\u1740-\u1751\u1760-\u176C\u176E-\u1770\u1780-\u17B3\u17D7\u17DC\u1820-\u1877\u1880-\u18A8\u18AA\u18B0-\u18F5\u1900-\u191C\u1950-\u196D\u1970-\u1974\u1980-\u19AB\u19C1-\u19C7\u1A00-\u1A16\u1A20-\u1A54\u1AA7\u1B05-\u1B33\u1B45-\u1B4B\u1B83-\u1BA0\u1BAE\u1BAF\u1BBA-\u1BE5\u1C00-\u1C23\u1C4D-\u1C4F\u1C5A-\u1C7D\u1CE9-\u1CEC\u1CEE-\u1CF1\u1CF5\u1CF6\u1D00-\u1DBF\u1E00-\u1F15\u1F18-\u1F1D\u1F20-\u1F45\u1F48-\u1F4D\u1F50-\u1F57\u1F59\u1F5B\u1F5D\u1F5F-\u1F7D\u1F80-\u1FB4\u1FB6-\u1FBC\u1FBE\u1FC2-\u1FC4\u1FC6-\u1FCC\u1FD0-\u1FD3\u1FD6-\u1FDB\u1FE0-\u1FEC\u1FF2-\u1FF4\u1FF6-\u1FFC\u2071\u207F\u2090-\u209C\u2102\u2107\u210A-\u2113\u2115\u2119-\u211D\u2124\u2126\u2128\u212A-\u212D\u212F-\u2139\u213C-\u213F\u2145-\u2149\u214E\u2183\u2184\u2C00-\u2C2E\u2C30-\u2C5E\u2C60-\u2CE4\u2CEB-\u2CEE\u2CF2\u2CF3\u2D00-\u2D25\u2D27\u2D2D\u2D30-\u2D67\u2D6F\u2D80-\u2D96\u2DA0-\u2DA6\u2DA8-\u2DAE\u2DB0-\u2DB6\u2DB8-\u2DBE\u2DC0-\u2DC6\u2DC8-\u2DCE\u2DD0-\u2DD6\u2DD8-\u2DDE\u2E2F\u3005\u3006\u3031-\u3035\u303B\u303C\u3041-\u3096\u309D-\u309F\u30A1-\u30FA\u30FC-\u30FF\u3105-\u312D\u3131-\u318E\u31A0-\u31BA\u31F0-\u31FF\u3400-\u4DB5\u4E00-\u9FCC\uA000-\uA48C\uA4D0-\uA4FD\uA500-\uA60C\uA610-\uA61F\uA62A\uA62B\uA640-\uA66E\uA67F-\uA697\uA6A0-\uA6E5\uA717-\uA71F\uA722-\uA788\uA78B-\uA78E\uA790-\uA793\uA7A0-\uA7AA\uA7F8-\uA801\uA803-\uA805\uA807-\uA80A\uA80C-\uA822\uA840-\uA873\uA882-\uA8B3\uA8F2-\uA8F7\uA8FB\uA90A-\uA925\uA930-\uA946\uA960-\uA97C\uA984-\uA9B2\uA9CF\uAA00-\uAA28\uAA40-\uAA42\uAA44-\uAA4B\uAA60-\uAA76\uAA7A\uAA80-\uAAAF\uAAB1\uAAB5\uAAB6\uAAB9-\uAABD\uAAC0\uAAC2\uAADB-\uAADD\uAAE0-\uAAEA\uAAF2-\uAAF4\uAB01-\uAB06\uAB09-\uAB0E\uAB11-\uAB16\uAB20-\uAB26\uAB28-\uAB2E\uABC0-\uABE2\uAC00-\uD7A3\uD7B0-\uD7C6\uD7CB-\uD7FB\uF900-\uFA6D\uFA70-\uFAD9\uFB00-\uFB06\uFB13-\uFB17\uFB1D\uFB1F-\uFB28\uFB2A-\uFB36\uFB38-\uFB3C\uFB3E\uFB40\uFB41\uFB43\uFB44\uFB46-\uFBB1\uFBD3-\uFD3D\uFD50-\uFD8F\uFD92-\uFDC7\uFDF0-\uFDFB\uFE70-\uFE74\uFE76-\uFEFC\uFF21-\uFF3A\uFF41-\uFF5A\uFF66-\uFFBE\uFFC2-\uFFC7\uFFCA-\uFFCF\uFFD2-\uFFD7\uFFDA-\uFFDC\u0E01-\u0E3A\u0E40-\u0E4F\u0E5A\u05B])[\W]/g;
|
||||
BIN
docs/engineering/tax-flow/Tax_Code_to_Factgraph.pdf
Normal file
BIN
docs/engineering/tax-flow/Tax_Code_to_Factgraph.pdf
Normal file
Binary file not shown.
77
docs/engineering/tax-flow/dataviews.md
Normal file
77
docs/engineering/tax-flow/dataviews.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# Dataviews
|
||||
|
||||
Before we get into Dataviews - here are some captured describing where this page could use some additional work and if the content:
|
||||
|
||||
"we really need to fill it out and organize it in a way that benefits new engineers and also our designers so they know what is easy to do vs what is an unsupported pattern. It would also be good to understand any roadmap requests they have for the improvements of Dataviews, and fixing known problems (interactions with KOs and loops for instance)."
|
||||
|
||||
"We need to better document the behavior of our Dataviews and what they are capable of. This will allow us to speed up development, have better conversations with Design, and plan for how we want to make improvements for them going forward. We also need to gather the growing list of known issues with data views to understand if there are holistic changes we can make to the infrastructure to create better experiences."
|
||||
|
||||
---
|
||||
|
||||
# How to make content vary within a question
|
||||
|
||||
## Outside of Loops
|
||||
|
||||
You can use standard facts within dataview questions and answers.
|
||||
|
||||
You can have content vary for MFJ by adding `_spouse` to the end of the string name, and it will be automatically used.
|
||||
|
||||
Otherwise, DataViews are limited. You can't specify the same context indicators you can for screen titles/questions, so be wary if you find you are mapping multiple strings to a single variable; you'll need to keep the dataview question generic to handle all cases, and that isn't a great practice to show a different question than the one you asked on the screen.
|
||||
|
||||
EXAMPLE
|
||||
|
||||
## Within Loops
|
||||
|
||||
Within loops the same rules as above apply, but you can also use facts related to the current filer. But you must use their name, not a pronoun.
|
||||
|
||||
For instance, this works:
|
||||
|
||||
`This is the answer for `_`PrimaryFirstName`_
|
||||
|
||||
`This is the answer for `_`SecondaryFirstName`_
|
||||
|
||||
This does not:
|
||||
|
||||
`This is the answer for `_`you`_
|
||||
|
||||
`This is the answer for `_`SecondaryFirstName`_
|
||||
|
||||
EXAMPLE
|
||||
|
||||
# How to make content vary within an answer
|
||||
|
||||
You can use the `i18nKeySuffixContext` along with conditions to vary the content displayed for a fact on the screen, but beware that we have limited ability to use conditional context in data-views.
|
||||
|
||||
For the most part, you are tied to the answers that were posed in the original screen.
|
||||
|
||||
There are ways around that, but they require custom code.
|
||||
|
||||
EXAMPLE
|
||||
|
||||
# How to hide a question on the data view
|
||||
|
||||
Use the displayOnlyOn property set to 'edit'. (e.g.`displayOnlyOn='edit'`)
|
||||
|
||||
EXAMPLE:
|
||||
|
||||
```
|
||||
<LimitingString
|
||||
path='/formW2s/*/filer/lastName'
|
||||
readOnly={true}
|
||||
displayOnlyOn='edit'
|
||||
hintKey='/info/income/w2/why-change-name'
|
||||
condition='/formW2s/*/filer/isPrimaryFiler'
|
||||
/>
|
||||
```
|
||||
|
||||
# How to show text only on the data view
|
||||
|
||||
Use a Generic String with the displayOnlyOn property set to 'data-view'. (e.g.`displayOnlyOn='data-view'`)
|
||||
|
||||
The string should be inserted in the flow sub or subsub category where you want it to appear.
|
||||
|
||||
EXAMPLE:
|
||||
|
||||
```
|
||||
<GenericString path='/hsaDistributions/*/filer/fullName' displayOnlyOn='data-view' batches={[`hsa-1`]} />
|
||||
```
|
||||
31
docs/engineering/tax-flow/writing-facts.md
Normal file
31
docs/engineering/tax-flow/writing-facts.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# Writing facts
|
||||
|
||||
- Modules don't have any actual meaning, they're just a tool for organizing code
|
||||
- The fact dictionary files eventually all compile down to one big dictionary
|
||||
|
||||
## examples of using dependencies in a fact
|
||||
|
||||
This establishes the context for the fact, in this case we're looking inside the "filers" collection:
|
||||
```
|
||||
<Fact path="/filers/*/hsaContributionsTotal">
|
||||
```
|
||||
|
||||
This is a fact that lives outside the "filers" collection, so we don't use a relative path. It's being imported from the "filingStatus" module:
|
||||
```
|
||||
<Dependency module="filingStatus" path="/isFilingStatusMFJ" />
|
||||
```
|
||||
|
||||
This is a fact that lives inside the "filers" collection, but is written in a different file:
|
||||
```
|
||||
<Dependency module="filers" path="../isSecondaryFiler" />
|
||||
```
|
||||
|
||||
This is a relative path because it exists inside the "filers" collection. It is written in the filers.xml file, but that doesn't matter because we're already working within the filers collection so we have access to everything in that collection regardless of which module/file it is in:
|
||||
```
|
||||
<Dependency path="../isSecondaryFiler" />
|
||||
```
|
||||
|
||||
This is a path for a fact that is written in the same file where it is being called. It is not a relative path because it exists outside the "filers" collection, but it does not need a module because it is in the current file:
|
||||
```
|
||||
<Dependency path="/secondaryHsaContributionsTotal" />
|
||||
```
|
||||
30
docs/engineering/working-on-client-app.md
Normal file
30
docs/engineering/working-on-client-app.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Testing in the Direct File Client App
|
||||
|
||||
The Direct File client app has many steps for completing a tax return, making manual testing and bug reproduction time-consuming. These tools help streamline the process.
|
||||
|
||||
## Dev-Only Control Panel
|
||||
|
||||
<img width="673" alt="Screenshot 2025-05-23 at 10 08 03 AM" src="https://github.com/user-attachments/assets/5e098552-bd0d-448c-bde1-6b41d279ac7e" />
|
||||
|
||||
Access the control panel at `/df/file/account/` for development settings and data management:
|
||||
|
||||
- **Change date** - Set browser date to test deadline-related functionality
|
||||
- **Data Import Profile** - Modify seeded test data (like date of birth) that can't be changed in the normal tax flow during local development
|
||||
- **Download Data** - Export fact graph as JSON for attaching to pull requests or bug reports
|
||||
- **Upload Data** - Import fact graph to quickly navigate to specific application states when testing PRs or reproducing bugs
|
||||
- **Preview Tax Return** - View backend tax return preview
|
||||
- **Load Preach UUID** - Load specific Preach configurations
|
||||
|
||||
## All Screens
|
||||
|
||||
<img width="1279" alt="Screenshot 2025-05-23 at 10 09 05 AM" src="https://github.com/user-attachments/assets/7fd2966f-4627-48d9-b8ad-0b3f2c8bbab8" />
|
||||
|
||||
Navigate to `/df/file/all-screens/index.html` to view all application pages in one location.
|
||||
|
||||
This page displays every screen in the tax flow and post-submission pages. Use the menu to filter and manipulate the view. Generate a PDF by pressing "p" and using the [Just-One-Page-PDF Chrome extension](https://chromewebstore.google.com/detail/just-one-page-pdf-an-awes/fgbhbfdgdlojklkbhdoilkdlomoilbpl?hl=en&pli=1).
|
||||
|
||||
## Flamingo Fact Checker
|
||||
|
||||
|
||||
|
||||
Use the [Flamingo Fact Checker](df-tools/Flamingo-Fact-Checker.md) to monitor specific fact values as you progress through the tax flow.
|
||||
Loading…
Add table
Add a link
Reference in a new issue